fsanyoto commited on
Commit
b02098c
Β·
verified Β·
1 Parent(s): 2183dbe

Deploy AIOS web (React glide grid + FastAPI slice)

Browse files
Files changed (47) hide show
  1. RELEASES.json +1 -1
  2. VERSION +1 -1
  3. api/rollup_sql.py +33 -2
  4. api/routes_customers.py +617 -15
  5. api/routes_grid.py +473 -33
  6. api/routes_shares.py +427 -13
  7. api/routes_tables.py +258 -11
  8. platform/aios_grid.py +293 -4
  9. platform/aios_grid_fields.json +0 -62
  10. platform/core/field_permissions.py +194 -9
  11. platform/core/grid_events.py +15 -5
  12. platform/core/user_tables.py +1059 -10
  13. platform/harness/semantic.py +124 -17
  14. platform/model/topics/odoo_products.yml +0 -40
  15. platform/model/topics/sales_lines.yml +37 -0
  16. platform/modules/product_data.py +91 -65
  17. platform/modules/products.py +42 -2
  18. web/src/customer-grid/ColumnMenu.tsx +785 -54
  19. web/src/customer-grid/CustomerGrid.tsx +672 -54
  20. web/src/customer-grid/MapView.tsx +679 -5
  21. web/src/customer-grid/RecordDetail.tsx +2 -2
  22. web/src/customer-grid/RouteNav.tsx +763 -0
  23. web/src/customer-grid/SwipeView.tsx +586 -586
  24. web/src/customer-grid/Toolbar.tsx +110 -9
  25. web/src/customer-grid/ViewSidebar.tsx +680 -182
  26. web/src/customer-grid/apiBridge.ts +161 -0
  27. web/src/customer-grid/folders.ts +163 -0
  28. web/src/customer-grid/formulaEngine.ts +434 -9
  29. web/src/customer-grid/types.ts +534 -13
  30. web/src/customer-grid/useVisibleRows.ts +120 -15
  31. web/src/customer-grid/viewEcho.ts +159 -1
  32. web/src/customer-grid/viewModes.tsx +114 -22
  33. web/src/filter-kit/FieldsHidePanel.tsx +357 -35
  34. web/src/filter-kit/fieldClass.ts +179 -0
  35. web/src/index.css +36 -16
  36. web/src/shell/NavExtras.tsx +19 -8
  37. web/src/shell/ShareDialog.tsx +124 -4
  38. web/src/shell/Shell.tsx +442 -98
  39. web/src/shell/nav.ts +160 -0
  40. web/src/styles/wave42/hop-editor.css +67 -0
  41. web/src/styles/wave42/rail-views.css +125 -0
  42. web/src/styles/wave42/route-nav.css +244 -0
  43. web/src/viz/types.ts +10 -1
  44. web/wiring_rows/wave42_c.py +174 -0
  45. web/wiring_rows/wave42_d.py +71 -0
  46. web/wiring_rows/wave42_f.py +101 -0
  47. web/wiring_rows/wave42_g.py +57 -0
RELEASES.json CHANGED
@@ -1,5 +1,5 @@
1
  {
2
- "current": "a8583e6",
3
  "releases": [
4
  {
5
  "version": "v53",
 
1
  {
2
+ "current": "582a6c8",
3
  "releases": [
4
  {
5
  "version": "v53",
VERSION CHANGED
@@ -1 +1 @@
1
- a8583e6
 
1
+ 582a6c8
api/rollup_sql.py CHANGED
@@ -39,7 +39,35 @@ for _p in (str(_HERE), str(_PLATFORM)):
39
 
40
 
41
  class RollupSourceError(Exception):
42
- """The rollup could not be computed HONESTLY β€” no cells are written when this is raised."""
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
43
 
44
 
45
  def _ut():
@@ -90,7 +118,10 @@ def group_values(bag, today=None):
90
  date_from=date_from, date_to=date_to,
91
  limit=sem.MAX_GROUPS, today=today)
92
  except Exception as e: # noqa: BLE001
93
- raise RollupSourceError(f"{type(e).__name__}: {e}") from e
 
 
 
94
 
95
  if res.get("truncated"):
96
  # β›” THE REFUSAL THAT MATTERS. See the module header: a truncated GROUP set is a wrong
 
39
 
40
 
41
  class RollupSourceError(Exception):
42
+ """The rollup could not be computed HONESTLY β€” no cells are written when this is raised.
43
+
44
+ β›”β›” THE ORIGINAL EXCEPTION IS CARRIED AS `.cause`, AND THAT ATTRIBUTE IS THE CONTRACT.
45
+ `group_values` wraps whatever the semantic layer raises, and it used to keep only
46
+ `f"{type(e).__name__}: {e}"` β€” the TYPE survived as TEXT and nothing else. A caller wanting to
47
+ tell "you named a column this topic does not have" (a 400 naming the column) apart from "this
48
+ topic has no store binding" (a 503) then had no choice but to match words in a sentence, which
49
+ is exactly the discriminator amendment A8 exists to forbid: that sentence is copy that reaches
50
+ a screen, so it WILL be reworded, and the branch stops firing without a word.
51
+
52
+ ⚠ `__cause__` is set as well (every wrap keeps its `from e`), but it is NOT the contract.
53
+ `__cause__` is traceback chaining, dropped silently by the first later `raise
54
+ RollupSourceError(...)` written without `from`; a named attribute set at the raise site cannot
55
+ go missing that quietly, and `isinstance(err.__cause__, X)` is a DIFFERENT contract from the
56
+ one A8 wrote.
57
+
58
+ ⚠ `cause` DEFAULTS TO None and the message argument is unchanged, so single-argument
59
+ construction and `str(err)` behave exactly as before β€” `verify_odoo_relational.py`'s
60
+ `except R.RollupSourceError` needs no edit. The two refusals raised by this module's own logic
61
+ (an unresolvable window, a truncated group set) have no underlying exception, so they leave it
62
+ None: `.cause is None` means "this module refused", not "nothing was wrapped".
63
+
64
+ Test it as `isinstance(err.cause, semantic.UnknownColumnError)`, NEVER as
65
+ `"UnknownColumnError" in str(err)`.
66
+ """
67
+
68
+ def __init__(self, message, cause=None):
69
+ super().__init__(message)
70
+ self.cause = cause
71
 
72
 
73
  def _ut():
 
118
  date_from=date_from, date_to=date_to,
119
  limit=sem.MAX_GROUPS, today=today)
120
  except Exception as e: # noqa: BLE001
121
+ # β›” `cause=e` IS THE POINT OF THIS LINE, not decoration. The message keeps the type name
122
+ # for a human reading a log; a CALLER branches on `err.cause`, never on that text. See
123
+ # `RollupSourceError`'s docstring for why the text is not a discriminator.
124
+ raise RollupSourceError(f"{type(e).__name__}: {e}", cause=e) from e
125
 
126
  if res.get("truncated"):
127
  # β›” THE REFUSAL THAT MATTERS. See the module header: a truncated GROUP set is a wrong
api/routes_customers.py CHANGED
@@ -87,8 +87,8 @@ def _pool_for(rt, team_id, agent):
87
  rt.pool_cache[key] = snap # seed, so the memo stamps stay coherent
88
  return snap[1]
89
  raise err(503, "connector_paused",
90
- "this data source is paused and no snapshot exists for your scope β€” "
91
- "an admin can resume it under Settings β†’ Connectors")
92
 
93
  def _build():
94
  # ⚠ THE SCOPE GOES INTO THE BUILDER. `pool(agent_name, team_id)` is the same reconciled
@@ -203,7 +203,32 @@ def shared_cells(pids, st=None):
203
  return {}
204
 
205
 
206
- def _merge_shared_fields(fields, defs, session=None):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
207
  """`fields` PLUS the tenant-wide columns this topic declares β€” `routes_tables._ut_shared_fields`
208
  on the customer topic.
209
 
@@ -212,15 +237,74 @@ def _merge_shared_fields(fields, defs, session=None):
212
  closure's reach otherwise and carries the hidden value out wearing a second name. It is also
213
  the only order in which `field_grant_hidden` can ever see the `granted` marker at all β€” merge
214
  afterwards and the per-field wall is inert while every test still passes.
215
- ⚠ A key the canonical contract already declares WINS. A shared column is an ADDITION to this
216
- database's contract, never a redefinition of a column it already has.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
217
  """
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
218
  if not defs:
219
  return fields
220
- have = {f.get("key") for f in (fields or ()) if isinstance(f, dict)}
221
  projected = []
222
  for k, f in defs.items():
223
- if k in have:
 
 
 
 
 
 
224
  continue
225
  item = dict(f, source="overlay", shared=True)
226
  if session is not None:
@@ -230,8 +314,82 @@ def _merge_shared_fields(fields, defs, session=None):
230
  is_admin=session.admin, st=session.runtime)
231
  if role:
232
  item["sharedRole"] = role
233
- projected.append(item)
234
- return list(fields or ()) + projected
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
235
 
236
 
237
  def grid_assembly(session: Session, scope: str = "customer", storage_key: str = "",
@@ -322,7 +480,13 @@ def grid_assembly(session: Session, scope: str = "customer", storage_key: str =
322
  # ⭐⭐ W38-T20 β€” AND THE COLUMN DEFINITIONS, BEFORE THE WALL. See `_merge_shared_fields`: this
323
  # position is load-bearing twice, once for the transitive closure and once because it is the
324
  # only order in which the per-field grant marker is ever presented to `hidden_keys`.
325
- fields = _merge_shared_fields(fields, _defs, session=session)
 
 
 
 
 
 
326
  # ⭐⭐ W41-T01 / RULING R5 / CONTRACTS C1 + C8 β€” **THE THREE BADGES, STAMPED ONCE, HERE.**
327
  #
328
  # C1 makes `field_permissions.field_class` the ONE producer of `{origin, audience, sharedBy,
@@ -361,12 +525,24 @@ def grid_assembly(session: Session, scope: str = "customer", storage_key: str =
361
  # definition would be one account's answer served to the next reader of the same cached
362
  # structure. The copy makes that impossible to reintroduce rather than merely untrue now, which
363
  # is the same rule `_payload` states over `rows_src`.
364
- # β›” AND ONLY `class`. C8's `usage`, `agg` and `descriptionEdited` belong to other tickets, and
365
- # C8 is explicit that an absent key means "not built yet", never "false".
 
 
 
 
 
 
366
  try:
367
  from core import field_permissions as _fp
 
 
 
 
 
368
  _classes = _fp.field_classes(fields, session.uname, table_key=_shared_key(),
369
- grant_topic=SHARE_TOPIC, values_shared=set(_defs), st=rt)
 
370
  fields = [dict(f, **{"class": _classes[f["key"]]})
371
  if isinstance(f, dict) and _classes.get(f.get("key")) else f
372
  for f in fields]
@@ -388,6 +564,79 @@ def grid_assembly(session: Session, scope: str = "customer", storage_key: str =
388
  # makes this degrade safe: a client renders NOTHING for a missing `class` rather than a
389
  # wrong badge, so a registry that will not open costs the badges and not the grid.
390
  pass
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
391
  # THE FIELD WALL β€” a TRANSITIVE closure (C-PERM amendment 5), so hiding a field also hides
392
  # every formula computed FROM it. Formulas evaluate in the browser from `{ref}`s, so
393
  # shipping a dependent formula while withholding its input either leaks the input through
@@ -420,6 +669,50 @@ def grid_assembly(session: Session, scope: str = "customer", storage_key: str =
420
  ws["overlays"] = {pid: {k: v for k, v in (cells or {}).items() if k not in hidden}
421
  for pid, cells in _ov.items()}
422
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
423
  today = time.strftime("%Y-%m-%d")
424
  stamp = _pool_stamp(rt, team_id, agent)
425
  # ⭐⭐ W38-T19 β€” THE METRICS CAPABILITY, AND THIS GRAIN NEEDS **THREE** GUARDS WHERE THE
@@ -439,6 +732,20 @@ def grid_assembly(session: Session, scope: str = "customer", storage_key: str =
439
  # The derived channel: cohort membership cells + measure column values, ONE dict β€” the
440
  # same read-only channel the embed host hands to rows_from_pool.
441
  derived = aios_grid.cohort_cells(lists)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
442
  # ⭐ W33-T43 / owner item 12 ("One unique ID per database always"). The customer grid carried
443
  # NO Odoo id column at all, while its retiring twin `ut_odoo_customers` carried `partner_id`
444
  # as its join key β€” so the merge would have lost the one value every Odoo document joins on.
@@ -790,7 +1097,7 @@ def patch_customer(pid: int, body: dict = Body(default=None),
790
  "pid": pid, "updates": updates}, ctx)
791
  except grid_events.StoreUnavailable:
792
  raise err(503, "store_unavailable",
793
- "the tenant store is unavailable β€” your change was not saved")
794
 
795
  route_accepted, route_swaps, route_taken = ({}, [], set())
796
  if route_updates:
@@ -858,6 +1165,28 @@ ROUTE_KEY_PREFIX = "route_"
858
  #: convention is not a declaration.
859
  ROUTE_KIND = "route_order"
860
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
861
  #: ⭐⭐ W41-T05 / CONTRACT C3 β€” THE DESCRIPTION EVERY ROUTE COLUMN IS BORN WITH.
862
  #:
863
  #: `shared_overlay.mint_field` refuses a tenant-wide column that has no description, and the
@@ -1027,6 +1356,147 @@ def _own_route_fork(session: Session, key: str):
1027
  return entry
1028
 
1029
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1030
  @router.get("/customers/route-order")
1031
  def route_order_list(session: Session = Depends(module_gate(MODULE))):
1032
  """The route-order columns this session may see, with the fingerprint each was solved from.
@@ -1038,8 +1508,18 @@ def route_order_list(session: Session = Depends(module_gate(MODULE))):
1038
  about a moment that has already passed.
1039
  """
1040
  out = []
1041
- for key, defn in sorted(_route_defs(session).items()):
 
 
 
 
 
 
 
 
 
1042
  route = defn.get("route") if isinstance(defn.get("route"), dict) else {}
 
1043
  out.append({
1044
  "key": key,
1045
  "label": defn.get("label") or key,
@@ -1054,6 +1534,23 @@ def route_order_list(session: Session = Depends(module_gate(MODULE))):
1054
  # the way out so the client can grey the control instead of discovering a 403.
1055
  "mine": bool(session.admin
1056
  or str(defn.get("createdBy") or "") == session.uname),
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1057
  })
1058
  # ⭐⭐ OWNER ITEM 5 β€” THE DEFAULT NAME IS ALLOCATED **HERE**, NEVER ON THE CLIENT.
1059
  #
@@ -1066,7 +1563,12 @@ def route_order_list(session: Session = Depends(module_gate(MODULE))):
1066
  #
1067
  # ⚠ IT LEAKS NOTHING. What travels is the first FREE name, which is a fact about absence.
1068
  import aios_grid
 
 
 
 
1069
  return {"fields": out,
 
1070
  "nextLabel": _next_route_label(shared_fields(st=session.runtime) or {},
1071
  aios_grid.FIELDS)}
1072
 
@@ -1543,3 +2045,103 @@ def route_order_rename(field_key: str, body: dict = Body(default=None),
1543
  shared_overlay.put_field(_shared_key(), key, patch, st=session.runtime)
1544
  return {"ok": True, "field": key, "label": patch.get("label") or key,
1545
  "note": patch.get("note") or ""}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
87
  rt.pool_cache[key] = snap # seed, so the memo stamps stay coherent
88
  return snap[1]
89
  raise err(503, "connector_paused",
90
+ "this data source is paused and no snapshot exists for your scope. "
91
+ "An admin can resume it under Settings, then Connectors.")
92
 
93
  def _build():
94
  # ⚠ THE SCOPE GOES INTO THE BUILDER. `pool(agent_name, team_id)` is the same reconciled
 
203
  return {}
204
 
205
 
206
+ def _canonical_field_keys():
207
+ """The keys THE CANONICAL CONTRACT declares, read from `aios_grid.FIELDS`.
208
+
209
+ ⭐ W42-T46 β€” this is the discriminator `_merge_shared_fields` narrows its precedence rule on,
210
+ and the one `grid_assembly` tells `contract` from `personal` with when it lends C10's strata
211
+ map. Derived from the contract list itself rather than from a mark on the definition, because
212
+ every mark on a definition survives being copied out of the document it came from (the whole
213
+ of `field_permissions.field_stratum`'s docstring is that proof).
214
+
215
+ β›”β›” THE IMPORT IS LOCAL, LIKE EVERY OTHER `aios_grid` USE IN THIS FILE (nine of them), AND
216
+ LEAVING IT OUT WAS A LIVE DEFECT RATHER THAN AN UNTIDINESS. `routes_customers` never imports
217
+ `aios_grid` at module scope, so a bare `aios_grid.FIELDS` here raised `NameError` on EVERY call
218
+ -- and `_merge_shared_fields` calls this unconditionally, on the main grid read path.
219
+ ⚠ WHAT MADE IT INVISIBLE IS THE INTERESTING HALF: `routes_nav.nav_schema` wraps its customer
220
+ branch in `except Exception: fields = []`, whose own comment calls that fail-closed and correct.
221
+ So the NameError did not surface as an error; it surfaced as a schema drawer serving an EMPTY
222
+ field contract, and the only thing that noticed was `verify_api.py:786` indexing `[0]` of it.
223
+ A lenient except turned a typo into a silent empty payload.
224
+ """
225
+ import aios_grid
226
+
227
+ return {str(f.get("key") or "").strip()
228
+ for f in (aios_grid.FIELDS or ()) if isinstance(f, dict)}
229
+
230
+
231
+ def _merge_shared_fields(fields, defs, session=None, strata=None):
232
  """`fields` PLUS the tenant-wide columns this topic declares β€” `routes_tables._ut_shared_fields`
233
  on the customer topic.
234
 
 
237
  closure's reach otherwise and carries the hidden value out wearing a second name. It is also
238
  the only order in which `field_grant_hidden` can ever see the `granted` marker at all β€” merge
239
  afterwards and the per-field wall is inert while every test still passes.
240
+
241
+ ⭐⭐ W42-T46 / R15 / R16 β€” THE PRECEDENCE RULE, NARROWED, AND IT IS THE ROOT CAUSE OF
242
+ INSTRUCTION 17. The old rule was flat: `if k in have: continue`, so a viewer holding ANY
243
+ same-key entry silently discarded the tenant-wide definition and read their own. Their own was
244
+ never marked shared, so it filed as private, which is the owner's *"Gabriel created the Route
245
+ and it ends up being MY field"* verbatim: a route IS a field (`kind: "route_order"`, key
246
+ `route_<slug>`) minted tenant-wide, and it landed in every other account's private list.
247
+
248
+ The rule is now:
249
+
250
+ * a key the canonical contract declares AND the incoming list already carries -> the LOCAL
251
+ entry wins, exactly as before. This is the original guard's whole purpose: a shared overlay
252
+ may never redefine a built-in column.
253
+ * a key the incoming list carries that the contract does NOT declare (a user-created column,
254
+ a route among them) -> the SHARED definition wins, in place, carrying its own `createdBy`
255
+ so `field_class` reports its real owner.
256
+ * a key the incoming list does not carry -> projected and appended, exactly as before.
257
+
258
+ β›” THE CANONICAL GUARD IS CONDITIONAL ON `k in have`, AND THAT IS DELIBERATE RATHER THAN
259
+ SLOPPY. Skipping a canonical key unconditionally would DROP a key that is projected today
260
+ (a contract key absent from the incoming list), and which keys are present is a WALL question,
261
+ not a precedence one. Under this rule the outgoing key set is `incoming | (defs - have)` for
262
+ every input, byte for byte what it was.
263
+
264
+ ⚠ SUPERSEDED, NOT DELETED (R16), AND IT IS STRUCTURAL. This helper is a read-time projection:
265
+ it writes nothing, and the viewer's own definition stays in their workspace member exactly as
266
+ `TableStore.save_field` left it. A caller recovers it by reading the workspace member before
267
+ the merge (`aios_grid.workspace_wire`'s output, the `fields` argument here). What rides on the
268
+ wire is a THIN marker under `superseded`, never a copy of the local definition: a nested
269
+ definition would be copied verbatim into a fork by `grid_events.field_upsert`
270
+ (`base = field_by_key[key]` then `{**base, ...}`) and persisted, and a nested `formula` would
271
+ sit outside `hidden_keys`' closure, which walks entries and not nested dicts.
272
+
273
+ ⭐ `strata` IS AN OUT-PARAMETER, filled per key with C10's stratum for the definition that
274
+ WON: `contract` | `shared` | `personal`. `field_permissions.field_class` cannot derive it (see
275
+ `field_stratum`), so the assembly that did the reading lends it. Only `grid_assembly` passes
276
+ one; the return type is unchanged for every other call site.
277
  """
278
+ incoming = list(fields or ())
279
+ canonical = _canonical_field_keys()
280
+ lent = strata if isinstance(strata, dict) else None
281
+
282
+ # Index the incoming list ONCE, and mark each of its keys with the stratum it was read from:
283
+ # a key the contract declares is `contract`, anything else came out of this viewer's own
284
+ # workspace member and is `personal`. Keys are stripped because `field_classes` strips both
285
+ # sides of its lookup, and an unstripped entry would silently fall back instead of failing.
286
+ have = {}
287
+ for idx, f in enumerate(incoming):
288
+ if not isinstance(f, dict):
289
+ continue
290
+ k = str(f.get("key") or "").strip()
291
+ if not k or k in have:
292
+ continue
293
+ have[k] = idx
294
+ if lent is not None:
295
+ lent[k] = "contract" if k in canonical else "personal"
296
+
297
  if not defs:
298
  return fields
 
299
  projected = []
300
  for k, f in defs.items():
301
+ k = str(k or "").strip()
302
+ if not k:
303
+ continue
304
+ idx = have.get(k)
305
+ if idx is not None and k in canonical:
306
+ # THE CANONICAL GUARD, UNCHANGED. A shared column is an ADDITION to this database's
307
+ # contract, never a redefinition of a column it already has.
308
  continue
309
  item = dict(f, source="overlay", shared=True)
310
  if session is not None:
 
314
  is_admin=session.admin, st=session.runtime)
315
  if role:
316
  item["sharedRole"] = role
317
+ if idx is None:
318
+ projected.append(item)
319
+ else:
320
+ local = incoming[idx] if isinstance(incoming[idx], dict) else {}
321
+ item["superseded"] = {
322
+ "stratum": "personal",
323
+ "owner": str(local.get("createdBy") or "").strip() or None,
324
+ "label": str(local.get("label") or "").strip() or None,
325
+ }
326
+ incoming[idx] = item
327
+ if lent is not None:
328
+ lent[k] = "shared"
329
+ return incoming + projected
330
+
331
+
332
+ def _mark_offerability(fields):
333
+ """Every `route_order` column marked NOT offerable in a field picker, and nothing else touched.
334
+
335
+ ⭐⭐ W42-T53 / CONTRACT C11 / R20 / R23 β€” THE NAVIGATION COMPLAINT, MEASURED: ~64 route
336
+ columns on a 53-field grid, each carrying ~21 filled stops against ~3,620 blanks (99.4%
337
+ empty), every one of them in every field picker on the topic.
338
+
339
+ β›”β›” THIS IS PRESENTATION. IT IS NOT A PERMISSION AND IT IS NOT A DELETION, AND THE
340
+ DIFFERENCE IS THE WHOLE TICKET. The columns are still SERVED: W42-T20's projection reads
341
+ them to build its one column, and `route_order_write` still validates a full 1..N
342
+ permutation per column. Filtering them out of the payload would leave the projection with
343
+ nothing to project and take the route planner's data off the wire, and R20 keeps the 64 as
344
+ the store underneath precisely so that nothing has to be migrated irreversibly on live.
345
+ So this adds ONE key to an entry and never removes an entry.
346
+
347
+ β›” KIND-CHECKED, NEVER PREFIX-CHECKED, the rule `_split_route_updates` and
348
+ `route_order_delete` both state: `ROUTE_KEY_PREFIX` is a naming convention and a convention
349
+ is not a declaration.
350
+
351
+ ⭐ AND THE `kind` IS READ OFF THE **SERVED ENTRY**, NOT OFF `shared_fields`. After W42-T46
352
+ narrowed the precedence rule a route key reaches the outgoing list two ways, and `kind`
353
+ rides the entry in both: projected from the tenant-wide stratum, and replaced IN PLACE over
354
+ a viewer's own same-key entry (the `superseded` branch). Both go through
355
+ `dict(f, source="overlay", shared=True)`, which copies the stored definition whole. Reading
356
+ the entry rather than the `defs` dict also means this helper is honest about the list it was
357
+ actually handed, instead of about a second document that may not describe it.
358
+
359
+ ⚠ THE ONE SHAPE IT CANNOT SEE, STATED RATHER THAN GLOSSED: a route key that exists ONLY in a
360
+ viewer's own workspace member, with no tenant-wide definition left to supersede it.
361
+ `aios_grid.fields_from_workspace` rebuilds a user-created column from a STRICT ALLOWLIST
362
+ (`_field_extras` plus a fixed key set) and `kind` is not in it, so such an entry arrives with
363
+ no kind at all and is not marked. That is not the ~64 this ticket is about -- those are all
364
+ tenant-wide -- and marking by key prefix instead would break the rule this whole file keeps
365
+ (a convention is not a declaration). Recorded so the next reader does not assume coverage
366
+ that is not there.
367
+
368
+ ⭐ THE `routes` KEY PASSES THROUGH (C11). W42-T20's pre-set projection column is the ONE
369
+ column a person picks a route with, so withholding it would remove the feature this ticket
370
+ exists to deliver. It is exempted by KEY, because that key is what C11 fixes; whether T20
371
+ gives it `kind: "route_order"` or no kind at all (the `cohort_field` precedent carries no
372
+ kind), it comes out offerable either way.
373
+
374
+ ⚠ ABSENT-MEANS-OFFERABLE IS PRESERVED BY NEVER STAMPING `True`. A non-route column leaves
375
+ this function carrying no `offerable` key whatsoever, so the served bytes for every field
376
+ that predates the flag are unchanged and no stored fixture moves.
377
+
378
+ β›” A NEW DICT PER COLUMN, NEVER AN IN-PLACE STAMP, the same rule `class` and `usage` state a
379
+ few lines below: these entries are per-request copies today, and writing through one would
380
+ make that a dependency rather than a coincidence.
381
+
382
+ Returns a list with the SAME keys in the SAME order as the input.
383
+ """
384
+ out = []
385
+ for f in (fields or ()):
386
+ if (isinstance(f, dict)
387
+ and f.get("kind") == ROUTE_KIND
388
+ and str(f.get("key") or "").strip() != ROUTE_PROJECTION_KEY):
389
+ out.append(dict(f, **{OFFERABLE_KEY: False}))
390
+ else:
391
+ out.append(f)
392
+ return out
393
 
394
 
395
  def grid_assembly(session: Session, scope: str = "customer", storage_key: str = "",
 
480
  # ⭐⭐ W38-T20 β€” AND THE COLUMN DEFINITIONS, BEFORE THE WALL. See `_merge_shared_fields`: this
481
  # position is load-bearing twice, once for the transitive closure and once because it is the
482
  # only order in which the per-field grant marker is ever presented to `hidden_keys`.
483
+ # ⭐⭐ W42-T46 / C10 β€” AND IT FILLS THE STRATA MAP ON THE WAY THROUGH. `_strata` is keyed by
484
+ # field key and covers EVERY key in the outgoing list by construction: the merge marks each
485
+ # incoming key as it indexes it and re-marks any key whose shared definition wins. Nothing
486
+ # between this line and the `field_classes` call below adds or renames a column, so lending it
487
+ # there is a complete map rather than a partial one.
488
+ _strata = {}
489
+ fields = _merge_shared_fields(fields, _defs, session=session, strata=_strata)
490
  # ⭐⭐ W41-T01 / RULING R5 / CONTRACTS C1 + C8 β€” **THE THREE BADGES, STAMPED ONCE, HERE.**
491
  #
492
  # C1 makes `field_permissions.field_class` the ONE producer of `{origin, audience, sharedBy,
 
525
  # definition would be one account's answer served to the next reader of the same cached
526
  # structure. The copy makes that impossible to reintroduce rather than merely untrue now, which
527
  # is the same rule `_payload` states over `rows_src`.
528
+ # β›” `agg` belongs to another ticket, and C8 is explicit that an absent key means "not built
529
+ # yet", never "false".
530
+ # ⭐⭐ W42-T14 / C4 β€” C8's `usage` IS NO LONGER ONE OF THEM; it is stamped a few lines below,
531
+ # in this same window between the merge and the wall. Until then this topic sent `class` with
532
+ # no `usage` while every `ut_*` grid sent `usage` with no `class`, and
533
+ # `filter-kit/fieldClass.ts::deleteImpactTitle(fc, usage)` composes its delete warning as two
534
+ # independent halves and DROPS whichever argument is null -- so both surfaces rendered half a
535
+ # sentence with every gate on both sides green.
536
  try:
537
  from core import field_permissions as _fp
538
+ # ⭐⭐ W42-T46 / W42-T47 / R15 / C10 β€” `strata=_strata` IS THE LENDER T47 WAITED FOR, and
539
+ # without this argument T47 is a no-op: `field_stratum`'s fallback cannot see a fork and
540
+ # names one `shared`, because `{**base}` copies `shared`/`granted`/`source` into the fork
541
+ # verbatim. This assembly is the one place that KNOWS which document each definition came
542
+ # out of, so it is the only honest source of the fact.
543
  _classes = _fp.field_classes(fields, session.uname, table_key=_shared_key(),
544
+ grant_topic=SHARE_TOPIC, values_shared=set(_defs),
545
+ strata=_strata, st=rt)
546
  fields = [dict(f, **{"class": _classes[f["key"]]})
547
  if isinstance(f, dict) and _classes.get(f.get("key")) else f
548
  for f in fields]
 
564
  # makes this degrade safe: a client renders NOTHING for a missing `class` rather than a
565
  # wrong badge, so a registry that will not open costs the badges and not the grid.
566
  pass
567
+ # ⭐⭐ W42-T14 / C4 β€” **C8's `usage`, THE EXPENSIVE DIRECTION, STAMPED ONCE, HERE.**
568
+ #
569
+ # β›” ONE PRODUCER, REUSED, NEVER A SECOND COUNTER FOR THIS TOPIC. `routes_tables._field_usage`
570
+ # already answers "what breaks if this column goes" over the WHOLE workspace rather than over
571
+ # this caller's stratum, which is the clause the count exists for and the one a second
572
+ # implementation would quietly get wrong. It is imported here rather than restated for the same
573
+ # reason `_tenant_of` is imported inside it: two spellings of one count is
574
+ # [[two-lanes-one-contract-dead-feature]] with a number instead of a key. Imported lazily,
575
+ # because `routes_tables` imports this module's siblings at module scope.
576
+ #
577
+ # β›”β›” ONE MEMO KEY SPELLING, AND IT IS `MODULE`. The memo is `{(tenant, table_key): …}` and it
578
+ # is invalidated by a change token, never by time, so a second spelling of the topic on this
579
+ # door would pin a stale answer under a key nothing invalidates for the life of the process.
580
+ # `MODULE` ("customer_data") is the string `apply_row_scope`, `hidden_keys` and
581
+ # `routes_admin._clean_perms` already spell for this topic, and it is what the permission
582
+ # records inside `_field_usage` are keyed by, so any other choice would also report
583
+ # `permRules: 0` for every account. ⚠ NOT `scope`, which is a ROUTE PARAMETER (`"customer"` by
584
+ # default) two callers may pass differently, and not `_shared_key()`, which names the DOCUMENT.
585
+ #
586
+ # ⚠ THE DOCUMENT IS HANDED IN SEPARATELY, and that is the whole re-parameterisation: this
587
+ # topic's strata live in `customer_table_workspace`, a name no `f"{table_key}_table_workspace"`
588
+ # literal can produce. `rt` carries it, exactly as `_ctx_for` already opens this topic's
589
+ # workspace through `_customer_table(session)`.
590
+ #
591
+ # ⚠ `defn=None` IS NOT A SHORTCUT. That argument is the SHARED CONTRACT leg of
592
+ # `_usage_field_corpus`, and on this topic the merge above has already folded both the
593
+ # canonical contract (`aios_grid.FIELDS`) and the tenant-wide stratum (`_defs`) into `fields`,
594
+ # which the corpus reads as its second source. The third leg -- every OTHER account's `fields`
595
+ # stratum -- comes out of the workspace document, which is the half no caller-scoped list can
596
+ # contain and the half the count is about. Passing `_defs` too would add nothing but a
597
+ # second shape to keep in step, since it is a `{key: field}` dict and not a `{'fields': [...]}`
598
+ # definition.
599
+ #
600
+ # ⚠ AFTER THE MERGE AND BEFORE THE WALL, the same window and the same two reasons as `class`
601
+ # above: after, or the tenant-wide columns are neither in the list to stamp nor in the corpus
602
+ # to count from; before, so `hidden_keys` deletes a column's usage bag along with the column
603
+ # and a reader who may not see a column never learns how much of the workspace depends on it.
604
+ # ⚠ A NEW DICT PER COLUMN AND A COPY OF THE BAG -- `_field_usage` MEMOISES, so handing its own
605
+ # dict out would let anything downstream write into the number the next request reads.
606
+ # ⚠ LENIENT, AND THE ABSENT-KEY POLARITY IS WHAT MAKES THAT SAFE: `_field_usage` returns `{}`
607
+ # rather than zeros on a failed read, and this stamps NO key for a column it has no bag for,
608
+ # because a confident "0 uses" beside a delete button reads as safe to delete.
609
+ try:
610
+ from routes_tables import _field_usage as _fu
611
+ _usage = _fu(session, MODULE, fields, None, rt, _shared_key(), st=rt)
612
+ except Exception: # noqa: BLE001
613
+ _usage = {}
614
+ if _usage:
615
+ fields = [dict(f, usage=dict(_usage[f["key"]]))
616
+ if isinstance(f, dict) and _usage.get(f.get("key")) else f
617
+ for f in fields]
618
+ # ⭐⭐ W42-T53 / C11 β€” **ROUTE OFFERABILITY, STAMPED ONCE, HERE.** See `_mark_offerability`
619
+ # for what it does and does not do (it adds a key; it removes nothing from any wire).
620
+ #
621
+ # β›” IN `grid_assembly` AND NOT IN `_merge_shared_fields`, for the two reasons already
622
+ # written out over `class` above: that helper returns `fields` untouched when `defs` is
623
+ # empty and otherwise only builds the PROJECTED additions, so a route column that reached
624
+ # the list through the viewer's own stratum would leave it unmarked -- and it is called from
625
+ # five places (`_hidden_for`, `_route_defs`, and the three route doors) that want a field
626
+ # list purely to ask the WALL a question and then throw it away. `grid_assembly` is the
627
+ # single assembly both client doors serve verbatim (`_payload` returns `g["fields"]` on
628
+ # `/customers`, `routes_grid` assigns `workspace["fields"] = g["fields"]` on `/workspace`),
629
+ # so it is the only position in which the two wires cannot disagree about a column.
630
+ #
631
+ # ⚠ AFTER THE MERGE AND BEFORE THE WALL, the same window and the same two reasons as `class`
632
+ # and `usage`: after, or the tenant-wide route columns are not in the list to mark; before,
633
+ # so a column this reader may not see loses the mark along with the column rather than
634
+ # leaving a mark behind on nothing.
635
+ # ⚠ NOT LENIENT, and deliberately not: this is a pure list transform over data already in
636
+ # hand, with no store read, no registry open and nothing to raise. A `try` here would be a
637
+ # place for a real defect to hide, which is exactly how a `NameError` in
638
+ # `_canonical_field_keys` shipped as an EMPTY field contract earlier in this lane.
639
+ fields = _mark_offerability(fields)
640
  # THE FIELD WALL β€” a TRANSITIVE closure (C-PERM amendment 5), so hiding a field also hides
641
  # every formula computed FROM it. Formulas evaluate in the browser from `{ref}`s, so
642
  # shipping a dependent formula while withholding its input either leaks the input through
 
669
  ws["overlays"] = {pid: {k: v for k, v in (cells or {}).items() if k not in hidden}
670
  for pid, cells in _ov.items()}
671
 
672
+ # ⭐⭐ W42-T20 / C11 / R9 / R20 / R23 β€” **THE ONE ROUTE PROJECTION COLUMN, APPENDED HERE.**
673
+ #
674
+ # β›”β›” AFTER THE WALL, WHICH IS THE OPPOSITE POSITION TO `class`, `usage` AND `offerable`, AND
675
+ # THE INVERSION IS THE POINT. Those three are marks ON columns the wall then narrows. This is a
676
+ # column DERIVED FROM what the wall left standing: `hidden` is exactly the set of route columns
677
+ # this session was not granted, so narrowing first and projecting second is what makes the
678
+ # projection incapable of naming a route the reader may not see. Projecting before the wall and
679
+ # narrowing afterwards would have to re-parse the joined string to take an entry back out, and
680
+ # a value that has already been assembled has already leaked.
681
+ #
682
+ # β›” THE SAME PREDICATE AS `_route_defs`, NOT A SECOND OPINION. That helper is
683
+ # `shared_fields` filtered by `kind == ROUTE_KIND` minus `perm_scope.hidden_keys(...)`, and
684
+ # `_defs` / `hidden` here are those same two reads on this assembly. Calling `_route_defs`
685
+ # instead would repeat a whole `_merge_shared_fields` and a second `hidden_keys` per request to
686
+ # recompute a set already in hand; what must not diverge is the PREDICATE, and it does not.
687
+ #
688
+ # ⚠ THE APPEND IS CONDITIONED ON THE TENANT HAVING ROUTES AT ALL, AND THE CELLS ON THE VIEWER
689
+ # HAVING GRANTS -- two different questions with two different answers. A tenant that has never
690
+ # planned a route gets no column, which is the cost `cohort_field`'s own note gives for staying
691
+ # out of the canonical contract (an always-present column nobody can fill). A viewer with no
692
+ # route grants on a tenant that HAS routes gets the column BLANK on every row, which is the
693
+ # done-when: hiding the column from them instead would make its presence a signal.
694
+ #
695
+ # ⚠ NOT LENIENT, deliberately, for `_mark_offerability`'s stated reason: this is a pure
696
+ # transform over data already in hand, with no store read and nothing to raise, and a `try`
697
+ # here would be a place for a real defect to hide -- which is exactly how a `NameError` in
698
+ # `_canonical_field_keys` shipped as an EMPTY field contract earlier in this lane.
699
+ #
700
+ # ⚠ THE DUPLICATE-KEY GUARD IS `fields_from_workspace`'s, for its reason: a person can create a
701
+ # column literally called "Routes", whose slug is this key. The client indexes fields by key, so
702
+ # a duplicate does not error -- it silently paints one column's values under the other's header.
703
+ # The user's own column wins and the derived one steps aside.
704
+ #
705
+ # ⚠ IT IS APPENDED AFTER `_mark_offerability` RUNS, so T53's `ROUTE_PROJECTION_KEY` exemption
706
+ # never actually fires for this column. Absent-means-offerable gives the right answer either
707
+ # way; recorded so the next reader does not read that exemption as load-bearing.
708
+ _route_vis = {k: v for k, v in (_defs or {}).items()
709
+ if isinstance(v, dict) and v.get("kind") == ROUTE_KIND
710
+ and k not in (hidden or ())}
711
+ if (any(isinstance(v, dict) and v.get("kind") == ROUTE_KIND for v in (_defs or {}).values())
712
+ and not any(isinstance(f, dict) and f.get("key") == ROUTE_PROJECTION_KEY
713
+ for f in fields)):
714
+ fields = fields + [aios_grid.route_projection_field(ROUTE_PROJECTION_KEY, _route_vis)]
715
+
716
  today = time.strftime("%Y-%m-%d")
717
  stamp = _pool_stamp(rt, team_id, agent)
718
  # ⭐⭐ W38-T19 β€” THE METRICS CAPABILITY, AND THIS GRAIN NEEDS **THREE** GUARDS WHERE THE
 
732
  # The derived channel: cohort membership cells + measure column values, ONE dict β€” the
733
  # same read-only channel the embed host hands to rows_from_pool.
734
  derived = aios_grid.cohort_cells(lists)
735
+ # ⭐⭐ W42-T20 β€” THE ROUTE PROJECTION'S CELLS, ON THE SAME CHANNEL AND NOT A SECOND ONE.
736
+ #
737
+ # β›” `_shared` IS THE SOURCE, AND IT IS THE ONLY ONE THERE IS. `_patch_route_ranks::_held`
738
+ # states the mapping: a record is on a route iff its shared-overlay cell for that route key is
739
+ # non-empty. There is no reverse index and `route.stops` is a COUNT, so the projection is a
740
+ # scan of the cells this assembly already read once for the rows it already scoped.
741
+ # ⚠ `_shared` is STRING-keyed and `derived` is INT-keyed; `route_projection_cells` bridges the
742
+ # two and its docstring says why inverting them is invisible (a blank column reads exactly like
743
+ # a working grant wall).
744
+ # β›” NOTHING IS WRITTEN BACK ANYWHERE. The ~64 route columns REMAIN the store underneath (R20);
745
+ # this reads them and T53 only stops a picker offering them.
746
+ for _pid, _cells in aios_grid.route_projection_cells(
747
+ ROUTE_PROJECTION_KEY, _route_vis, _shared, pids).items():
748
+ derived.setdefault(_pid, {}).update(_cells)
749
  # ⭐ W33-T43 / owner item 12 ("One unique ID per database always"). The customer grid carried
750
  # NO Odoo id column at all, while its retiring twin `ut_odoo_customers` carried `partner_id`
751
  # as its join key β€” so the merge would have lost the one value every Odoo document joins on.
 
1097
  "pid": pid, "updates": updates}, ctx)
1098
  except grid_events.StoreUnavailable:
1099
  raise err(503, "store_unavailable",
1100
+ "the tenant store is unavailable, so your change was not saved")
1101
 
1102
  route_accepted, route_swaps, route_taken = ({}, [], set())
1103
  if route_updates:
 
1165
  #: convention is not a declaration.
1166
  ROUTE_KIND = "route_order"
1167
 
1168
+ #: ⭐⭐ W42-T53 / CONTRACT C11 β€” **THE OFFERABILITY KEY, AS ONE LITERAL, EXPORTED.**
1169
+ #:
1170
+ #: `offerable?: boolean` β€” ABSENT or `True` means offerable; `False` means a field picker
1171
+ #: WITHHOLDS the column. Optional and absent-means-offerable, so every field that predates the
1172
+ #: flag and every stored fixture stays byte-identical (the same reasoning that made C-A2's
1173
+ #: `strict?` optional: the alternative silently reclassifies everything older than the flag).
1174
+ #:
1175
+ #: β›”β›” IT IS A MODULE CONSTANT AND NOT A LITERAL TYPED INTO THE STAMP, BECAUSE THE FAILURE C11
1176
+ #: WAS WRITTEN ABOUT IS A SPELLING DISAGREEMENT ACROSS TWO LANES, NOT A LOGIC ERROR. This lane
1177
+ #: was about to emit `notOfferable: true` while the client half (W42-T54) was about to read
1178
+ #: `offerable === false`: both correct, both sides' gates green, and ~64 route columns still
1179
+ #: filling every picker on screen. A per-side negative control cannot see that. Exporting the
1180
+ #: name lets a parity leg DERIVE the server's emitted key from this module instead of retyping
1181
+ #: it, which is the only shape of assertion that can compare the two literals to each other.
1182
+ OFFERABLE_KEY = "offerable"
1183
+
1184
+ #: ⭐ CONTRACT C11 β€” the key of W42-T20's ONE pre-set projection column, which passes THROUGH the
1185
+ #: filter that withholds the other route columns. Mirrors the `cohort_field` precedent's
1186
+ #: `{key: 'cohorts'}`: served, special, and offered. Named here so the exemption is a fact about
1187
+ #: this module rather than a string repeated in two places.
1188
+ ROUTE_PROJECTION_KEY = "routes"
1189
+
1190
  #: ⭐⭐ W41-T05 / CONTRACT C3 β€” THE DESCRIPTION EVERY ROUTE COLUMN IS BORN WITH.
1191
  #:
1192
  #: `shared_overlay.mint_field` refuses a tenant-wide column that has no description, and the
 
1356
  return entry
1357
 
1358
 
1359
+ #: ⭐⭐ W42-T23's FOLDER SURFACE NAME, DECLARED HERE SO THERE IS ONE SPELLING OF IT.
1360
+ #:
1361
+ #: T22 carried `folderId` on the wire as an honest `None`, because no store document could hold a
1362
+ #: route's placement: `aios_grid.FOLDER_SURFACES` was `{"views", "cohorts"}`, `clean_folders` and
1363
+ #: `clean_item_folders` iterate exactly that set, and the folder write door refused the surface
1364
+ #: outright. T23 widened that set, and this is where the value comes from now.
1365
+ #:
1366
+ #: β›”β›” THE PLACEMENT IS PER VIEWER, AND THE ROUTE ITSELF IS TENANT-WIDE. Those two facts sit
1367
+ #: badly together until you look at where a folder ROW lives: `TableStore.workspace` is keyed by
1368
+ #: USERNAME, so the routes rail's folders are this account's folders and nobody else's. A
1369
+ #: tenant-wide placement could therefore only ever name a folder that no other viewer has, and
1370
+ #: every other account would watch the route fall back to the root anyway β€” a shared fact with an
1371
+ #: unshareable referent. `aios_grid.clean_folders` states the same rule from the other end:
1372
+ #: filing is an ORGANISING act, not part of what the filed thing IS. So the route is one object
1373
+ #: every account sees, and where each account keeps it is that account's own business.
1374
+ #:
1375
+ #: β›” THE HOME IS `itemFolders["routes"]` IN THE PER-USER TABLE WORKSPACE β€” the stratum views and
1376
+ #: cohorts already use β€” and NOT a `folderId` key on the shared definition. A key on the
1377
+ #: definition would be tenant-wide by construction (the wrong answer above), and it would ride
1378
+ #: through `shared_overlay.put_field` on a record whose every other key is a fact about the
1379
+ #: COLUMN rather than about one reader's sidebar.
1380
+ ROUTE_FOLDER_SURFACE = "routes"
1381
+
1382
+
1383
+ def _route_folder_stratum(session: Session):
1384
+ """`(folders, placements)` for the routes rail: this caller's own, never another's.
1385
+
1386
+ ⚠ `consume_corrections=False`, like `_own_route_fork` and like every folder read in
1387
+ `grid_events`. A filing read that consumed a pending label-correction acknowledgement would
1388
+ make the ack's delivery depend on whether somebody had a sidebar open.
1389
+ """
1390
+ try:
1391
+ ws = _customer_table(session).workspace(session.uname, consume_corrections=False)
1392
+ except Exception: # noqa: BLE001
1393
+ return [], {}
1394
+ folders = list((ws.get("folders") or {}).get(ROUTE_FOLDER_SURFACE) or [])
1395
+ placed = dict((ws.get("itemFolders") or {}).get(ROUTE_FOLDER_SURFACE) or {})
1396
+ return folders, placed
1397
+
1398
+
1399
+ def _route_folder_id(placed, folders, key):
1400
+ """The folder this route sits in for this caller, or None for the top level.
1401
+
1402
+ β›” RESOLVED AGAINST THE FOLDERS THAT EXIST, EVERY TIME, and that is not belt-and-braces. A
1403
+ folder can be deleted through the generic folder door, which knows nothing about routes; the
1404
+ placement it leaves behind names nothing, and answering with it would put the route in a
1405
+ section the rail cannot draw. Prune, never invent β€” `clean_item_folders`' posture, said at
1406
+ read time so a stale placement can never outlive its folder on screen.
1407
+
1408
+ ⚠ `ROOT_PLACEMENT` SURVIVES THIS, deliberately, and it is not the same as None. Absence means
1409
+ "never filed", which the client's `groupByFolder` renders into the Shared group for a route
1410
+ somebody shared with you; the reserved id means "this reader deliberately dragged it out to
1411
+ the top level". Wave 32 item 20 is the whole account of why one value cannot carry both.
1412
+ """
1413
+ import aios_grid
1414
+
1415
+ fid = placed.get(key)
1416
+ if not isinstance(fid, str) or not fid:
1417
+ return None
1418
+ if fid == aios_grid.ROOT_PLACEMENT:
1419
+ return fid
1420
+ return fid if any(f.get("id") == fid for f in folders) else None
1421
+
1422
+
1423
+ def _route_share_marks(session: Session, defs):
1424
+ """Per-route `{owner, shared, sharedOut, hasShares, sharedRole}` from ONE registry read.
1425
+
1426
+ ⭐⭐ CONTRACT C6 β€” THE SPELLINGS ARE `ViewSidebar.tsx::viewShareMark`'s, NAME FOR NAME. That
1427
+ function reads `hasShares` / `shared` (line 198), `shared` + `owner` (199), `sharedRole` (203)
1428
+ and `sharedOut` (209); a key spelled one letter differently here is a route navigation that
1429
+ lists routes, opens the share dialog, passes every gate and never draws the shared icon
1430
+ ([[two-lanes-one-contract-dead-feature]]).
1431
+
1432
+ β›” THE GRANT IS THE EXISTING GENERIC FIELD DOOR, NOT A SECOND MECHANISM. A route IS a field
1433
+ (`kind: "route_order"`, key `route_<slug>`), so its share state lives at
1434
+ `shares.field_oid(SHARE_TOPIC, key)` and there is no `route` share kind to invent
1435
+ (`shares.KINDS` is `view | folder | database | field`).
1436
+
1437
+ β›” ONE STORE READ FOR THE WHOLE LISTING, and that is measured rather than tidy.
1438
+ `field_permissions.grant_records` opens `object_shares` once and returns
1439
+ `{field_key: {owner, entries}}` through the SAME `shares._clean_entries` normaliser
1440
+ `shares.grants` uses, so this badge and the wall cannot disagree about a junk-role entry. The
1441
+ per-key `shares.role_for` in `_merge_shared_fields` is the older shape and it is a fresh deep
1442
+ copy of the whole registry PER KEY: this tenant carries dozens of route columns, so the loop
1443
+ would be dozens of serialise/deserialise round trips on a listing that is one read.
1444
+
1445
+ ⚠ NO `try/except` AROUND THE READ. `grant_records` already fails closed on an unreadable
1446
+ bucket. A second, wider swallow here would turn a missing import into "every route reports
1447
+ never-shared" behind a clean 200, which is the exact defect this lane shipped once today.
1448
+
1449
+ ⭐ THE ROLE SEMANTICS ARE `SavedView`'s, because `viewShareMark` is `SavedView`'s reader:
1450
+ `types.ts` declares `sharedRole?: "view" | "edit"` and states that `shared` / `sharedRole` /
1451
+ `owner` all mean *granted TO me*, while the sharer's own leg carries `hasShares` + `sharedOut`
1452
+ and never `shared`. So `sharedRole` here is the ENTRY role, absent for the owner. ⚠ The field
1453
+ surface spells the same member differently (`FieldShareRole` admits `owner`, and
1454
+ `_merge_shared_fields` stamps `shares.role_for`, which reads an admin as `owner`). Two
1455
+ surfaces, two declared types; this one follows the consumer it was written for.
1456
+ """
1457
+ from core import field_permissions, shares
1458
+
1459
+ records = field_permissions.grant_records(SHARE_TOPIC, st=session.runtime) or {}
1460
+ me = str(session.uname or "").strip().lower()
1461
+ marks = {}
1462
+ for key, defn in (defs or {}).items():
1463
+ rec = records.get(key) or {}
1464
+ entries = rec.get("entries") or []
1465
+ # ⭐ THE OWNER IS RESOLVED ONCE AND OWNERSHIP IS TESTED AGAINST THE RESOLVED VALUE. A route
1466
+ # minted before the grant door stamped an owner has `entries` and no `owner` on the
1467
+ # record; testing the raw member would leave its creator reading `shared: true` beside
1468
+ # their own name, and the mark would tell them the column was shared with them by
1469
+ # themselves. `createdBy` is already on the definition and is already on the wire as
1470
+ # `solvedBy`, so the fallback leaks nothing new.
1471
+ owner = (str(rec.get("owner") or "").strip().lower()
1472
+ or str((defn or {}).get("createdBy") or "").strip().lower())
1473
+ mine = bool(me) and owner == me
1474
+ granted = None
1475
+ if me and not mine:
1476
+ for entry in entries:
1477
+ if entry.get("user") in (me, shares.EVERYONE):
1478
+ # The stronger of the two wins, exactly as `shares.role_for` decides it:
1479
+ # naming somebody explicitly is how you raise them above the room.
1480
+ if entry.get("role") == "edit":
1481
+ granted = "edit"
1482
+ break
1483
+ granted = granted or "view"
1484
+ marks[key] = {
1485
+ "owner": owner,
1486
+ "hasShares": bool(entries),
1487
+ "shared": granted is not None,
1488
+ "sharedRole": granted,
1489
+ # ⚠ WHAT `sharedOut` CAN TRUTHFULLY MEAN HERE IS NARROWER THAN ON A VIEW, and the
1490
+ # narrowness is the registry's, not a choice. `field` is excluded from
1491
+ # `shares.RESHARE_KINDS` and `routes_shares._owns_object`'s field branch requires
1492
+ # `createdBy == session.uname`, so an `edit` grantee can never hand a column on. The
1493
+ # only account that can have shared a route out is the one that owns it, which is
1494
+ # what this says: I own it AND somebody holds a grant on it.
1495
+ "sharedOut": bool(mine and entries),
1496
+ }
1497
+ return marks
1498
+
1499
+
1500
  @router.get("/customers/route-order")
1501
  def route_order_list(session: Session = Depends(module_gate(MODULE))):
1502
  """The route-order columns this session may see, with the fingerprint each was solved from.
 
1508
  about a moment that has already passed.
1509
  """
1510
  out = []
1511
+ # β›” THE WALL IS READ ONCE AND NOT RE-ASKED. `_route_defs` is still the ONLY source of the key
1512
+ # set below, and the share marks are looked up BY the keys it returned: a route this session
1513
+ # may not see is absent from `defs`, so it can have no mark, and its existence is not leaked
1514
+ # by a share key either. Nothing here widens what `perm_scope.hidden_keys` let through.
1515
+ defs = _route_defs(session)
1516
+ marks = _route_share_marks(session, defs)
1517
+ # ⭐⭐ W42-T23 β€” ONE workspace read for the whole listing, not one per route. See
1518
+ # `ROUTE_FOLDER_SURFACE` for why the placement is per viewer and lives in this stratum.
1519
+ folders, placed = _route_folder_stratum(session)
1520
+ for key, defn in sorted(defs.items()):
1521
  route = defn.get("route") if isinstance(defn.get("route"), dict) else {}
1522
+ mark = marks.get(key) or {}
1523
  out.append({
1524
  "key": key,
1525
  "label": defn.get("label") or key,
 
1534
  # the way out so the client can grey the control instead of discovering a 403.
1535
  "mine": bool(session.admin
1536
  or str(defn.get("createdBy") or "") == session.uname),
1537
+ # ⭐⭐ CONTRACT C6 β€” THE SHARE STATE, SPELLED AS `viewShareMark` READS IT. Every one of
1538
+ # the five is present on every route, negatives included: a MISSING key and a false
1539
+ # one are the same thing to `viewShareMark`, but they are not the same thing to the
1540
+ # next reader, who cannot tell "not shared" from "this door does not know".
1541
+ #
1542
+ # β›”β›” `shared` HERE IS NOT `shared` ON A FIELD, AND THE TWO LIVE IN THIS ONE FILE.
1543
+ # `_merge_shared_fields` stamps `shared: True` on every tenant-wide column, meaning
1544
+ # *this definition came out of the shared stratum* - and EVERY route is that, always.
1545
+ # `viewShareMark` reads `shared` as *granted to me*, which is FALSE on a tenant-wide
1546
+ # route the caller owns. Same word, two questions; this row answers the client's.
1547
+ "owner": mark.get("owner") or "",
1548
+ "shared": bool(mark.get("shared")),
1549
+ "sharedOut": bool(mark.get("sharedOut")),
1550
+ "hasShares": bool(mark.get("hasShares")),
1551
+ "sharedRole": mark.get("sharedRole"),
1552
+ # C6's spelling, and it reports a real placement now. See `ROUTE_FOLDER_SURFACE`.
1553
+ "folderId": _route_folder_id(placed, folders, key),
1554
  })
1555
  # ⭐⭐ OWNER ITEM 5 β€” THE DEFAULT NAME IS ALLOCATED **HERE**, NEVER ON THE CLIENT.
1556
  #
 
1563
  #
1564
  # ⚠ IT LEAKS NOTHING. What travels is the first FREE name, which is a fact about absence.
1565
  import aios_grid
1566
+ # ⭐ W42-T23 β€” the rail's own folder ROWS travel with the listing, because a `folderId` with
1567
+ # no folder list beside it names a section the client cannot draw. Same rows the generic
1568
+ # folder door writes, read back from the same stratum; `parent` rides along, which is what
1569
+ # makes the routes rail nest exactly as deep as the views rail does.
1570
  return {"fields": out,
1571
+ "folders": [{k: v for k, v in f.items()} for f in folders],
1572
  "nextLabel": _next_route_label(shared_fields(st=session.runtime) or {},
1573
  aios_grid.FIELDS)}
1574
 
 
2045
  shared_overlay.put_field(_shared_key(), key, patch, st=session.runtime)
2046
  return {"ok": True, "field": key, "label": patch.get("label") or key,
2047
  "note": patch.get("note") or ""}
2048
+
2049
+
2050
+ @router.patch("/customers/route-order/{field_key}/folder")
2051
+ def route_order_file(field_key: str, body: dict = Body(default=None),
2052
+ session: Session = Depends(module_gate(MODULE))):
2053
+ """File a route into one of this caller's route folders. `{folderId: str | null}`.
2054
+
2055
+ ⭐⭐ W42-T23 β€” A ROUTE'S OWN DOOR, AND THAT IS THE POINT OF IT EXISTING AT ALL.
2056
+
2057
+ β›”β›” THE GENERIC DOOR IS NOT AVAILABLE HERE, AND IT IS NOT A STYLE CHOICE. `grid_events`'
2058
+ `item_move` gates the mover on `_own_ids(surface, ws)`, which is written as
2059
+ `if sfc == 'views': ...` with an ELSE returning the caller's COHORT ids β€” a two-way split,
2060
+ not a lookup. A route key is never a cohort id, so filing a route through that door answers
2061
+ *"You can file only the items you own"* about a column the person planned themselves. The
2062
+ matching read-side hazard is answered in `aios_grid.FOLDER_SURFACES_TENANT_WIDE`, which is
2063
+ what stops an unrelated folder rename from erasing what this door writes.
2064
+
2065
+ β›” THE WALL IS "CAN YOU SEE IT", NOT "IS IT YOURS", and the two differ here on purpose.
2066
+ `route_order_rename` and `route_order_delete` are creator-or-admin because they change what
2067
+ every account in the workspace reads. A placement changes ONE account's sidebar β€” this one's
2068
+ β€” so requiring ownership would leave a shared route permanently unfileable by the very people
2069
+ it was shared with. A caller who cannot see the column still gets the answer a nonexistent
2070
+ key gets, for `route_order_rename`'s reason: a refusal that said "forbidden" would confirm a
2071
+ route exists here.
2072
+
2073
+ ⚠ THREE INPUTS, NOT TWO. `null` unfiles (no record at all, which is where a new route
2074
+ starts), the reserved root id records a deliberate move to the top level, and any other value
2075
+ must name a folder that exists. Wave 32 item 20 is the full account of why the first two
2076
+ cannot be the same stored state.
2077
+ """
2078
+ from core import shared_overlay
2079
+ from core.table_store import FolderTreeError
2080
+ import core.perm_scope as perm_scope
2081
+ import aios_grid
2082
+
2083
+ body = body if isinstance(body, dict) else {}
2084
+ key = str(field_key or "").strip()
2085
+
2086
+ all_defs = shared_fields(st=session.runtime) or {}
2087
+ defn = all_defs.get(key) if isinstance(all_defs.get(key), dict) else None
2088
+ unknown = err(404, "unknown_field",
2089
+ "that column is not a route order column on this database")
2090
+ if not defn or defn.get("kind") != ROUTE_KIND:
2091
+ raise unknown
2092
+ if key in perm_scope.hidden_keys(
2093
+ session.user, MODULE,
2094
+ _merge_shared_fields(list(aios_grid.FIELDS), all_defs), st=session.runtime):
2095
+ raise unknown
2096
+
2097
+ raw = body.get("folderId")
2098
+ target = None if raw is None else str(raw).strip()[:80]
2099
+
2100
+ store = _customer_table(session)
2101
+ try:
2102
+ ws = store.workspace(session.uname, consume_corrections=False)
2103
+ except Exception: # noqa: BLE001
2104
+ raise err(503, "store_unavailable",
2105
+ "your folders could not be saved because the workspace store is not reachable "
2106
+ "right now, so nothing was changed. Try again in a moment")
2107
+
2108
+ # β›”β›” `save_folders` REPLACES THE WHOLE STRATUM (`ws['folders'] = tree`), so the picture sent
2109
+ # in has to be the COMPLETE one. Passing only the routes surface would file this route and
2110
+ # delete every views and cohorts folder the caller had, with a 200 and no way back.
2111
+ folders = {s: [dict(f) for f in rows]
2112
+ for s, rows in (ws.get("folders") or {}).items() if isinstance(rows, list)}
2113
+ placed = {s: dict(m) for s, m in (ws.get("itemFolders") or {}).items()
2114
+ if isinstance(m, dict)}
2115
+ rows = folders.get(ROUTE_FOLDER_SURFACE) or []
2116
+ mine = dict(placed.get(ROUTE_FOLDER_SURFACE) or {})
2117
+
2118
+ if target is None:
2119
+ mine.pop(key, None) # unfiled: no record is how a route is born
2120
+ elif target == aios_grid.ROOT_PLACEMENT:
2121
+ mine[key] = target
2122
+ else:
2123
+ if not any(str(f.get("id") or "") == target for f in rows):
2124
+ raise err(404, "folder_gone",
2125
+ "that folder is not on this sidebar any more, so the route stayed where it "
2126
+ "was. Reload the page to see the folders you have, then try again")
2127
+ mine[key] = target
2128
+ placed[ROUTE_FOLDER_SURFACE] = mine
2129
+
2130
+ try:
2131
+ receipt = store.save_folders(session.uname, folders, placed)
2132
+ except FolderTreeError as e: # noqa: BLE001
2133
+ # The validator already words this for a person, and it names the folder. Re-wording it
2134
+ # here would be a second sentence about one rule, drifting from the first the day the cap
2135
+ # moves. 400 rather than 500: the tree is illegal, and nothing was written.
2136
+ raise err(400, "folder_tree_illegal", str(e))
2137
+
2138
+ saved = (receipt.get("itemFolders") or {}).get(ROUTE_FOLDER_SURFACE) or {}
2139
+ kept = [dict(f) for f in (receipt.get("folders") or {}).get(ROUTE_FOLDER_SURFACE) or []]
2140
+ return {"ok": True, "field": key,
2141
+ "folderId": _route_folder_id(saved, kept, key),
2142
+ "folders": kept,
2143
+ # ⚠ The receipt travels. `validate_folder_tree` REPAIRS a placement whose folder was
2144
+ # deleted rather than refusing it, and a repair the caller never hears about is a
2145
+ # route that quietly moved. `save_folders`' own docstring makes this the point of its
2146
+ # return value.
2147
+ "repairs": list(receipt.get("repairs") or [])}
api/routes_grid.py CHANGED
@@ -24,7 +24,7 @@ back. A 200 over a write that evaporated is the failure this rule exists to prev
24
  import datetime as dt
25
  import time
26
 
27
- from fastapi import APIRouter, Body, Depends
28
 
29
  from deps import Session, err, module_gate, perms, require_session
30
 
@@ -1029,8 +1029,24 @@ def grid_events_route(body: dict = Body(default=None),
1029
  # an UNCAPPED `IN (?,…)` over them. Confirmed orders only, the wholesale teams and the GIFTWARE
1030
  # DEALS exclusion all come from that topic's `scope_sql`, so the ticket's "confirmed orders only"
1031
  # is enforced by the ONE definition of it rather than by a second copy written here.
1032
- # ⚠ `viaField` therefore RIDES THE WIRE AND IS ADVISORY for this pair (C10, and lane D types
1033
- # against it). A door that refused an unresolvable `viaField` would refuse R10's headline case.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1034
  #
1035
  # β›” AND IT IS STILL NOT CHAINING (R12). `path` is TWO databases. `sales_lines` is the EDGE, not a
1036
  # third stop: none of it reaches the client, no filter over it is accepted, and no caller can name
@@ -1044,36 +1060,192 @@ def grid_events_route(body: dict = Body(default=None),
1044
  #: [[date-window-vocabulary]]. This is a RENAME and nothing else. `all` resolves to `(None, None)`.
1045
  PIVOT_WINDOWS = {"all": "all_time", "last12m": "ltm", "ytd": "ytd"}
1046
 
1047
- #: The DECLARED pivot routes: `(source, target) -> the edge that answers it`. A pair with no entry
1048
- #: is a 400, never an empty grid β€” "there is no way to get there" and "nothing is related" are two
1049
- #: different answers and only one of them is true.
 
 
 
 
 
 
 
 
 
 
 
 
 
1050
  #:
1051
- #: ⚠ `source_key` IS ASSERTED, NOT DECORATION. `filter_eval.visible_pids` reads `row['pid']` and
1052
- #: nothing else, so a future route whose source identity is NOT `pid` would silently pivot on the
1053
- #: wrong column. The route refuses instead. ⭐ For `customer_data` this is exactly right and W41-T19
1054
- #: measured it: `partner_id` is declared `derived` and is on 0 of 3,643 rows, while `pid` IS the
1055
- #: `res.partner` id. `from: "partner_id"` resolves 0 rows with nothing red.
1056
- #:
1057
- #: ⚠ `target_dim` IS THE SKU CODE, NOT `product_id`, AND THE OBVIOUS CHOICE IS THE WRONG ONE.
1058
- #: `product_code` is written to reproduce the product grid's identity exactly, `pid:<odoo id>`
1059
  #: fallback included; `product` (`l.product_id`) splits a re-SKUed pair whose archived half has no
1060
- #: grid row at all. MEASURED on this store: over the wholesale scope, grouping by `product_id`
1061
- #: gives 3,360 buckets and by `product_code` gives 3,352 β€” 8 codes carry two ids each, and it is
1062
- #: the archived id of each pair that no `product_data` row claims (that module keeps archived
1063
- #: products out, by R12). Joining on the id therefore loses 8 real products while looking fine.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1064
  _PIVOT_ROUTES = {
1065
  ("customer_data", "product_data"): {
1066
  "topic": "sales_lines",
1067
  "measure": "revenue",
1068
- "scope_key": "customer", # the cohort bucket the SOURCE tree's cohort leaves name
1069
  "source_dim": "order_partner",
1070
- "source_key": "pid",
1071
  "target_dim": "product_code",
1072
  "target_key": "code",
1073
  },
1074
  }
1075
 
1076
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1077
  def _pivot_today():
1078
  """The tenant's today, ISO. One clock, so the window and any date leaf agree."""
1079
  import core.periods as periods
@@ -1206,14 +1378,43 @@ def grid_pivot(body: dict = Body(default=None),
1206
  f"window must be one of {', '.join(sorted(PIVOT_WINDOWS))}. Refusing to guess "
1207
  f"which period was meant, because guessing 'all time' would widen the answer "
1208
  f"under a count nobody would doubt")
1209
- route = _PIVOT_ROUTES.get((source, target))
1210
- if route is None:
1211
- raise err(400, "no_pivot_route",
1212
- f"there is no declared way to get from '{source}' to '{target}'. "
1213
- f"Declared: " +
1214
- "; ".join(f"{a} to {b}" for a, b in sorted(_PIVOT_ROUTES)))
1215
-
1216
- # ── THE WALL, ON BOTH SIDES OF THE JOIN (R12) ────────────────────────────────────────────
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1217
  src, refusal = _pivot_side(session, source)
1218
  if refusal is not None:
1219
  return _pivot_reply(source, target, [], [], 0, 0, refusal=refusal)
@@ -1224,6 +1425,12 @@ def grid_pivot(body: dict = Body(default=None),
1224
  src_fields, src_rows = src
1225
  tgt_fields, tgt_rows = tgt
1226
 
 
 
 
 
 
 
1227
  today = _pivot_today()
1228
  columns = filter_eval._columns_map(src_fields)
1229
  unanswerable = _pivot_unanswerable(filters, columns)
@@ -1248,10 +1455,9 @@ def grid_pivot(body: dict = Body(default=None),
1248
  for cid, c in cohort_mod.scoped(route["scope_key"]).visible(
1249
  session.uname, pool_pids).items()}
1250
 
1251
- if route["source_key"] != "pid":
1252
- raise err(500, "pivot_source_key",
1253
- f"this pivot names '{route['source_key']}' as the source identity and the row "
1254
- f"engine reads 'pid'. Refusing rather than pivoting on the wrong column")
1255
  member = sorted({p for p in filter_eval.visible_pids(
1256
  {"conj": filter_conj, "nodes": filters}, src_rows, src_fields,
1257
  ctx=filter_eval.EvalCtx(cohort_sets=cohort_sets, today=today))
@@ -1273,8 +1479,45 @@ def grid_pivot(body: dict = Body(default=None),
1273
  filters={route["source_dim"]: member},
1274
  date_from=date_from, date_to=date_to, team_id=team_id, today=today,
1275
  limit=semantic.MAX_GROUPS)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1276
  except semantic.ModelError as exc:
1277
- raise err(503, "pivot_unavailable", str(exc))
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1278
 
1279
  # β›” `truncated` IS READ, NOT ASSUMED FALSE. `store_query` returns groups plus a flag, and a
1280
  # grouped query's groups ARE the answer, so a dropped one is missing data with nothing to
@@ -1374,3 +1617,200 @@ def _register_topic_rows():
1374
  _PRODUCT_MODULE = "product_data"
1375
 
1376
  _C1_ROW_SOURCES = _register_topic_rows()
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
24
  import datetime as dt
25
  import time
26
 
27
+ from fastapi import APIRouter, Body, Depends, HTTPException
28
 
29
  from deps import Session, err, module_gate, perms, require_session
30
 
 
1029
  # an UNCAPPED `IN (?,…)` over them. Confirmed orders only, the wholesale teams and the GIFTWARE
1030
  # DEALS exclusion all come from that topic's `scope_sql`, so the ticket's "confirmed orders only"
1031
  # is enforced by the ONE definition of it rather than by a second copy written here.
1032
+ # β›”β›” `viaField` IS LOAD-BEARING AS OF W42-T05, AND IT USED TO SAY THE OPPOSITE HERE. Until this
1033
+ # ticket the key rode the wire and NOTHING read it: the edge came from a compiled-in route table
1034
+ # keyed on `(source, target)`, so the request named a link field and the server answered from
1035
+ # a different declaration entirely. The table is gone. The edge is now read off the link field the
1036
+ # request NAMES, out of C1's `via` bag (`field["link"]["via"]`, written and validated by
1037
+ # `core.user_tables._clean_via`), which is what lets a second pair exist without editing this file.
1038
+ # ⚠ THE CONSEQUENCE IS STATED RATHER THAN DISCOVERED, AND IT IS BIGGER THAN A MISSING SEED: this
1039
+ # door REFUSES a pivot whose `viaField` does not resolve, with a 400 naming the field, and will
1040
+ # keep doing so until a link field can EXIST on a topic grid. `scoped_fields('customer_data')`
1041
+ # resolves to `aios_grid.FIELDS`, which declares no `link` column, and `user_tables.add_field`
1042
+ # refuses any key without the `ut_` prefix, so there is nowhere to put one. See `_pivot_route`'s
1043
+ # docstring for the trace. That refusal is the ticket's own instruction and it is the honest
1044
+ # answer, because the alternative shape (answer from a table nobody named) is the defect above.
1045
+ # ⚰ AMENDED BY WAVE 42 AMENDMENT A23 β€” ONE PAIR IS EXCEPTED, AND ONLY ONE. The paragraph above
1046
+ # described `(customer_data, product_data)` too, and that took a SHIPPING feature dark on a wave
1047
+ # that ends on the public live domain. `_PIVOT_ROUTES` below is back as a DATED TOMBSTONE holding
1048
+ # exactly that one pair, read ONLY after the strict resolution has already refused. Every other
1049
+ # unresolvable case still refuses with the field named, which is T05's real win and is intact.
1050
  #
1051
  # β›” AND IT IS STILL NOT CHAINING (R12). `path` is TWO databases. `sales_lines` is the EDGE, not a
1052
  # third stop: none of it reaches the client, no filter over it is accepted, and no caller can name
 
1060
  #: [[date-window-vocabulary]]. This is a RENAME and nothing else. `all` resolves to `(None, None)`.
1061
  PIVOT_WINDOWS = {"all": "all_time", "last12m": "ltm", "ytd": "ytd"}
1062
 
1063
+ #: The `via` keys THIS DOOR needs before it can ask a question. C1 makes all six required and
1064
+ #: `core.user_tables._clean_via` refuses a bag missing any of them, so a stored bag always has
1065
+ #: them; this tuple is the door's own check rather than a second copy of that rule, because a bag
1066
+ #: can also arrive from an older write or a hand-edited document. `filter`, `filterConj` and
1067
+ #: `window` are the optional three and are NOT read here (the request's own `window` governs).
1068
+ #: β›” `measure` IS AMONG THE REQUIRED SIX. There is no default: a bag without it is refused, never
1069
+ #: quietly answered with revenue, because the measure decides WHICH relationship the edge reports.
1070
+ _PIVOT_VIA_REQUIRED = ("topic", "measure", "scope_key", "source_dim", "target_dim", "target_key")
1071
+
1072
+ #: ⚠ THE SOURCE IDENTITY IS `pid` AND NOTHING ELSE, WHICH IS WHY `via` HAS NO `source_key`.
1073
+ #: `filter_eval.visible_pids` reads `row['pid']`, so there is exactly one answer and a bag key
1074
+ #: offering a second one could only ever disagree with the engine. The old route table carried
1075
+ #: `source_key` purely to assert `== "pid"` against itself; it died with the table rather than
1076
+ #: being migrated onto `via` (C1, A5). ⭐ W41-T19 measured why the obvious alternative is wrong:
1077
+ #: `partner_id` is declared `derived` and is on 0 of 3,643 customer rows, while `pid` IS the
1078
+ #: `res.partner` id, so `from: "partner_id"` resolves 0 rows with nothing red.
1079
  #:
1080
+ #: ⚠ AND THE MEASUREMENT BEHIND `target_dim: product_code` OUTLIVES THE TABLE IT WAS WRITTEN ON, so
1081
+ #: the next author does not re-derive it: the SKU CODE is right and `product_id` is the wrong
1082
+ #: obvious choice. `product_code` reproduces the product grid's identity exactly, `pid:<odoo id>`
 
 
 
 
 
1083
  #: fallback included; `product` (`l.product_id`) splits a re-SKUed pair whose archived half has no
1084
+ #: grid row at all. MEASURED on this store over the wholesale scope: grouping by `product_id` gives
1085
+ #: 3,360 buckets and by `product_code` gives 3,352 β€” 8 codes carry two ids each, and it is the
1086
+ #: archived id of each pair that no `product_data` row claims (that module keeps archived products
1087
+ #: out, by R12). Joining on the id therefore loses 8 real products while looking fine.
1088
+
1089
+
1090
+ #: ⚰⚰ TOMBSTONE β€” WAVE 42, AMENDMENT A23, 2026-08-25. ONE PAIR. NOT A TABLE. DELETE ME IN WAVE 43.
1091
+ #:
1092
+ #: β›” WHY A DEAD CONSTANT IS BACK, AND IT IS NOT A HACK BOLTED ONTO A CLEAN DESIGN. W42-T05
1093
+ #: dissolved the compiled `(source, target)` route table so the pivot reads its edge off the `via`
1094
+ #: bag on the link field the request NAMES. That work is correct and is not undone here. But the
1095
+ #: old table answered THIS pair while ignoring `viaField` entirely, so the wave's headline
1096
+ #: customer-to-product pivot shipped and worked; after T05 it 400s, and β›” SEEDING A `via` BAG
1097
+ #: CANNOT FIX IT: `aios_grid.FIELDS` is 37 entries with ZERO of type `link`,
1098
+ #: `scoped_fields('customer_data')` returns `list(aios_grid.FIELDS)` through `_customer_rows`,
1099
+ #: `aios_grid.fields_from_workspace` is the CLIENT wire's separate path (notes / `custom_` /
1100
+ #: `measure_` only), and `core.user_tables.add_field` refuses any key without the `ut_` prefix.
1101
+ #: A LINK FIELD CANNOT EXIST ON A TOPIC GRID AT ALL β€” no stratum can hold one.
1102
+ #:
1103
+ #: ⭐ AND THE LANE BASE PREDICTED THIS IN A COMMENT AT THIS SITE (`648f051:routes_grid.py:1032`):
1104
+ #: "`viaField` therefore RIDES THE WIRE AND IS ADVISORY for this pair … a door that refused an
1105
+ #: unresolvable `viaField` would refuse R10's headline case." So this restores an invariant the
1106
+ #: code documented and the ticket instructed away; it does not invent a new one.
1107
+ #:
1108
+ #: ⚰ THIS IS A TOMBSTONE, WITH AN EXPIRY THAT IS PROVABLE RATHER THAN HOPED FOR. Wave 43's
1109
+ #: storage ticket β€” the stratum that lets a link field exist on a topic grid β€” DELETES this
1110
+ #: constant and the guarded read in `_pivot_route` below. `verify_pivot.py` section 12 holds the
1111
+ #: leg that makes the deletion safe: once a real `via` resolves for this pair the fallback is
1112
+ #: UNREACHABLE, so wave 43 can PROVE the tombstone is dead instead of assuming it.
1113
+ #:
1114
+ #: β›” `source_key` IS DELIBERATELY NOT CARRIED. The old table's copy only ever asserted `== "pid"`
1115
+ #: against itself; `_clean_via` refuses it by name as an unknown key, so carrying it here would
1116
+ #: make this bag illegal as a stored `via` and the two shapes would diverge. The six keys below
1117
+ #: are exactly `_PIVOT_VIA_REQUIRED`, and the reasoning behind `order_partner`/`product_code`
1118
+ #: lives in the block above rather than being restated.
1119
  _PIVOT_ROUTES = {
1120
  ("customer_data", "product_data"): {
1121
  "topic": "sales_lines",
1122
  "measure": "revenue",
1123
+ "scope_key": "customer",
1124
  "source_dim": "order_partner",
 
1125
  "target_dim": "product_code",
1126
  "target_key": "code",
1127
  },
1128
  }
1129
 
1130
 
1131
+ def _pivot_route(fields, source, target, via_field):
1132
+ """The strict `via` resolution, with A23's ONE tombstoned pair behind it.
1133
+
1134
+ β›”β›” THE STRICT DOOR IS TRIED FIRST, ALWAYS, AND THAT ORDER IS THE DESIGN. It is what makes
1135
+ the fallback UNREACHABLE the moment a real `via` resolves for this pair, by construction
1136
+ rather than by assertion β€” which is what lets wave 43 delete the tombstone and prove nothing
1137
+ was still riding on it. A pre-check on the pair would invert that and is forbidden.
1138
+
1139
+ ⚰ THE ESCAPE HATCH IS GUARDED TWICE: the strict door must have refused with `no_pivot_route`,
1140
+ AND `(source, target)` must be the one key in `_PIVOT_ROUTES`. Every other unresolvable case
1141
+ still raises with the field named. See the tombstone's own comment for why it exists and for
1142
+ what deletes it.
1143
+ """
1144
+ try:
1145
+ return _pivot_route_via(fields, source, target, via_field)
1146
+ except HTTPException as exc:
1147
+ # β›” NARROW BY CODE, NOT BY TYPE. Only the "there is no edge" refusal may be excepted; a
1148
+ # permission or shape failure raised from anywhere under here must still reach the client.
1149
+ detail = exc.detail if isinstance(exc.detail, dict) else {}
1150
+ if (detail.get("error") or {}).get("code") != "no_pivot_route":
1151
+ raise
1152
+ tomb = _PIVOT_ROUTES.get((source, target))
1153
+ if tomb is None:
1154
+ raise
1155
+ return dict(tomb)
1156
+
1157
+
1158
+ def _pivot_route_via(fields, source, target, via_field):
1159
+ """C1's `via` bag off the link field the REQUEST NAMED, or a 400 that names that field.
1160
+
1161
+ β›”β›” EVERY UNRESOLVABLE CASE REFUSES, AND THAT IS THE WHOLE POINT OF THE FUNCTION. ⚰ Wave 42
1162
+ amendment A23 added EXACTLY ONE exception, and it is not in here: `_pivot_route` above catches
1163
+ this function's `no_pivot_route` for the single tombstoned pair. Nothing else is excepted, and
1164
+ nothing in this function may soften on account of it. Falling
1165
+ through with a partial bag lands as `rows = [r for r in tgt_rows if str(r.get(tkey)) in keys]`
1166
+ matching nothing, which is a 200 carrying `rows: []` and no `refusal` β€” the silent lie
1167
+ `_pivot_reply`'s own docstring forbids, and it reads as "these customers ordered nothing".
1168
+ "There is no way to get there" and "nothing is related" are two different answers and only one
1169
+ of them is ever true.
1170
+
1171
+ ⚠ `fields` IS THE READER'S SCOPED CONTRACT, NOT THE SCHEMA, and the wording follows from that.
1172
+ It arrives through `perm_scope.scoped_fields`, so a field wall can hide a link field that does
1173
+ exist. The refusal therefore says this ACCOUNT cannot resolve the field rather than that the
1174
+ database has no such field, which would be a claim about the schema made out of a fact about
1175
+ the reader. Resolving from the scoped list is still right for a `ut_*` source, whose link
1176
+ fields ARE stored on the table document `scoped_fields` reads.
1177
+
1178
+ β›”β›” AND IT IS STRUCTURALLY EMPTY OF LINK FIELDS FOR A TOPIC SOURCE, WHICH IS MEASURED, NOT
1179
+ FEARED. `scoped_fields('customer_data')` is answered by `_customer_rows` below, which returns
1180
+ `list(aios_grid.FIELDS)` β€” the compiled `aios_grid_fields.json` contract, which carries ZERO
1181
+ entries of type `link`. Nothing merges the per-user `<key>_table_workspace` stratum into that
1182
+ path (`aios_grid.fields_from_workspace` is a different function, reached only by
1183
+ `workspace_wire` on the client wire), and `core.user_tables.add_field` refuses a non-`ut_` key
1184
+ outright, so no link field is written there either. ⚠ SO THE CUSTOMER-TO-PRODUCT PIVOT REFUSES
1185
+ TODAY NO MATTER WHAT IS SEEDED IN A `via` BAG: that pair needs a link field to exist on a topic
1186
+ grid at all, which is a stratum question and not this door's. Refusing is still the right
1187
+ answer here; a second field-assembly door opened inside this route to manufacture one would be
1188
+ the two-doors-onto-one-vocabulary defect this wave has already paid for twice.
1189
+ """
1190
+ via_field = str(via_field or "").strip()
1191
+ if not via_field:
1192
+ raise err(400, "no_pivot_route",
1193
+ f"this pivot did not name a link field, so there is no edge to answer it with. "
1194
+ f"Send 'viaField' naming a link field on '{source}' that points at '{target}'")
1195
+
1196
+ match = None
1197
+ for field in fields or ():
1198
+ if not isinstance(field, dict):
1199
+ continue
1200
+ if str(field.get("key") or "") == via_field and field.get("type") == "link":
1201
+ match = field
1202
+ break
1203
+ if match is None:
1204
+ raise err(400, "no_pivot_route",
1205
+ f"this account cannot resolve a link field named '{via_field}' on '{source}', "
1206
+ f"so there is no declared edge to '{target}'. Pivot from a link field this "
1207
+ f"account can see on that grid")
1208
+
1209
+ link = match.get("link") if isinstance(match.get("link"), dict) else {}
1210
+ points_at = str(link.get("table") or "")
1211
+ if points_at != target:
1212
+ raise err(400, "no_pivot_route",
1213
+ f"the link field '{via_field}' points at "
1214
+ f"'{points_at or 'nothing this door can name'}', not at '{target}'. Refusing "
1215
+ f"rather than pivoting through an edge nobody asked for")
1216
+
1217
+ via = link.get("via") if isinstance(link.get("via"), dict) else None
1218
+ if not via:
1219
+ raise err(400, "no_pivot_route",
1220
+ f"the link field '{via_field}' joins '{source}' to '{target}' directly and "
1221
+ f"carries no 'via' declaration, so this door has no fact table to ask. A pivot "
1222
+ f"needs the edge spelled out: topic, measure, and the two dims it joins on")
1223
+
1224
+ missing = [k for k in _PIVOT_VIA_REQUIRED if not via.get(k)]
1225
+ if missing:
1226
+ raise err(400, "no_pivot_route",
1227
+ f"the 'via' declaration on link field '{via_field}' is missing "
1228
+ f"{', '.join(missing)}, so the edge is not fully described. Refusing rather "
1229
+ f"than filling in a default, which would answer a question nobody asked")
1230
+ return via
1231
+
1232
+
1233
+ #: ARM 2 of the catch below: the `ModelError` sentences that are an AUTHORING fault, matched by a
1234
+ #: needle rather than by type because `harness.semantic` raises the bare class for all of them.
1235
+ #: β›” `unknown metric` IS THE ONE THAT ACTUALLY FIRES ON THIS DOOR. A bad `via.measure` reaches
1236
+ #: `semantic._expand_measures` and comes back as a plain `ModelError`, NOT `UnknownColumnError` β€”
1237
+ #: the subclass covers a bad DIM only. `via.measure` is authored by whoever wrote the link field,
1238
+ #: so answering it with 503 "the store is unavailable" sends that author looking at the wrong
1239
+ #: thing. The rest are here so a bag naming a bad topic, a foreign measure or an over-wide filter
1240
+ #: lands the same way. ⚠ Kept at module level so the set is greppable and can be extended without
1241
+ #: reading the route.
1242
+ _PIVOT_AUTHORING = (
1243
+ "unknown metric", "unknown topic", "belong to another topic", "is company-level",
1244
+ "at least one measure required", "filter tree", "filter rule", "must reference",
1245
+ "grain must be", "is store-only", "unknown dim", "has no name column",
1246
+ )
1247
+
1248
+
1249
  def _pivot_today():
1250
  """The tenant's today, ISO. One clock, so the window and any date leaf agree."""
1251
  import core.periods as periods
 
1378
  f"window must be one of {', '.join(sorted(PIVOT_WINDOWS))}. Refusing to guess "
1379
  f"which period was meant, because guessing 'all time' would widen the answer "
1380
  f"under a count nobody would doubt")
1381
+ # ── C10 / R12 β€” THE WALL THAT WAS BUILT FOR THIS ROUTE, RUN FIRST (W42-T04) ──────────────
1382
+ #
1383
+ # β›” AHEAD OF EVERYTHING, AND THE ORDER IS THE POINT β€” MORE SO NOW THAT THE EDGE COMES OFF A
1384
+ # FIELD. `_pivot_route` cannot run first even in principle: it reads the SOURCE's scoped field
1385
+ # list, which means fetching a database, and fetching before the verdict is the wrong shape.
1386
+ # And the two predicates `_pivot_side` has never enforced β€” `is_linkable_target` on BOTH
1387
+ # endpoints and R12's `PIVOT_PATH_LEN` β€” live only here, so a request naming `users` or
1388
+ # `cohort` gets a permission answer with a reason on the wire (C10) rather than a field lookup.
1389
+ # W42-T04 wrote this note against a route TABLE that could have shadowed the wall; T05 removed
1390
+ # the table and the ordering matters for the same reason under `via`.
1391
+ #
1392
+ # ⚠ `path` IS NOT READ FROM THE BODY. C1 enumerates the wire keys and `pivot_scope` defaults
1393
+ # the walk to `[source, target]`; inventing an undeclared request key so the `chained` leg
1394
+ # could be reached from here would widen the contract to exercise a guard. The leg is in
1395
+ # force and unreachable from this door by construction while exactly one 2-hop pair is
1396
+ # declared; `via` is what will start handing it a longer walk.
1397
+ scope = perm_scope.pivot_scope(session.user, source, target, st=session.runtime)
1398
+ if not scope.permitted:
1399
+ # β›” A 200 WITH A REASON, NOT A STATUS. `_pivot_reply` stays the one envelope: it already
1400
+ # carries `refusal` and `limits`, and `PivotScope.envelope()` would only re-emit the same
1401
+ # `path` this route already writes while raising a key-precedence question nobody needs.
1402
+ # `limits` is standing rule 1's second sentence carried across the join; it is empty on
1403
+ # this pair because neither key is a `ut_` database, and it stops being empty for free the
1404
+ # day one is pivotable.
1405
+ return _pivot_reply(source, target, [], [], 0, 0,
1406
+ refusal=scope.refusal(),
1407
+ limits=scope.limits(st=session.runtime))
1408
+
1409
+ # ── THE ROW AND FIELD WALLS, ON BOTH SIDES OF THE JOIN (R12) ─────────────────────────────
1410
+ # ⚠ THE VERDICT IS ASKED ONCE, ABOVE; THIS IS THE FETCH. `pivot_scope` decides WHETHER, and
1411
+ # `_pivot_side` is what actually gets each side's scoped fields and rows through C1's one door
1412
+ # (`scoped_fields` / `scoped_table`) plus the tenant/account module gate `session.require`.
1413
+ # β›” W42-T05 DECLINED THE OFFERED COLLAPSE INTO `scope.source_grid`/`scope.target_grid`, on
1414
+ # purpose: those two NARROW a `(fields, rows)` pair handed to them, they do not fetch one, so
1415
+ # the collapse would need an UNWALLED read here to feed them and would drop `session.require`
1416
+ # and the refusal shape `_pivot_side` owns. Two callers of one wall is not the redundancy the
1417
+ # note warned about; an unwalled fetch to satisfy a shape would be the actual defect.
1418
  src, refusal = _pivot_side(session, source)
1419
  if refusal is not None:
1420
  return _pivot_reply(source, target, [], [], 0, 0, refusal=refusal)
 
1425
  src_fields, src_rows = src
1426
  tgt_fields, tgt_rows = tgt
1427
 
1428
+ # ⭐⭐ W42-T05 β€” THE EDGE, READ OFF THE LINK FIELD THE REQUEST NAMED. Deliberately AFTER both
1429
+ # sides are walled, so a reader who may not open either one gets the permission answer C10
1430
+ # specifies rather than a lecture about link fields; and deliberately against `src_fields`,
1431
+ # which is the reader's scoped contract and the same list the client chose `viaField` from.
1432
+ route = _pivot_route(src_fields, source, target, body.get("viaField"))
1433
+
1434
  today = _pivot_today()
1435
  columns = filter_eval._columns_map(src_fields)
1436
  unanswerable = _pivot_unanswerable(filters, columns)
 
1455
  for cid, c in cohort_mod.scoped(route["scope_key"]).visible(
1456
  session.uname, pool_pids).items()}
1457
 
1458
+ # β›” NO `source_key` CHECK ANY MORE, AND ITS ABSENCE IS THE POINT (C1, A5). It only ever
1459
+ # compared the old table against itself; `via` declares no such key, so there is nothing left
1460
+ # that could disagree with `visible_pids`' one reading of `row['pid']`.
 
1461
  member = sorted({p for p in filter_eval.visible_pids(
1462
  {"conj": filter_conj, "nodes": filters}, src_rows, src_fields,
1463
  ctx=filter_eval.EvalCtx(cohort_sets=cohort_sets, today=today))
 
1479
  filters={route["source_dim"]: member},
1480
  date_from=date_from, date_to=date_to, team_id=team_id, today=today,
1481
  limit=semantic.MAX_GROUPS)
1482
+ # β›”β›” THREE ARMS, AND THE CATCH STAYS STRUCTURALLY A CATCH-ALL (W42-T05, amendment A8b). Until
1483
+ # this ticket every `ModelError` off this one call became 503 "pivot_unavailable", which told
1484
+ # an author whose `via.measure` was a typo that the STORE was down. Narrowing the catch would
1485
+ # have been the worse fix: `except semantic.ModelError` still wraps everything, and a future
1486
+ # raise site added inside `store_query` lands in arm 3 by DEFAULT rather than escaping as an
1487
+ # uncaught 500. Nothing here re-words `harness.semantic`'s sentences; the arms only choose the
1488
+ # status that makes the sentence actionable.
1489
+ except semantic.UnknownColumnError as exc:
1490
+ # ARM 1 β€” A COLUMN THIS TOPIC DOES NOT HAVE. 400, and the body NAMES IT: a 400 carrying a
1491
+ # generic sentence is the same authoring dead end as the 503 was, one status politer.
1492
+ # `.column` and `.columns` are attributes of the class, not text to be parsed back out.
1493
+ # ⚠ THE REST OF `.columns` IS EMITTED ONLY WHEN THERE IS A REST. It defaults to
1494
+ # `[column]`, so an unconditional parenthetical would read "is 'product_kode' (named:
1495
+ # product_kode)" on the common single-column case, which is words that say nothing.
1496
+ others = [c for c in (exc.columns or ()) if c != exc.column]
1497
+ also = f" It also names {', '.join(others)}." if others else ""
1498
+ raise err(400, "pivot_unknown_column",
1499
+ f"{str(exc).rstrip('. ')}. The column this pivot could not resolve is "
1500
+ f"'{exc.column}'.{also} Fix the link field's 'via' declaration, or pivot "
1501
+ f"through a link field whose dims this topic actually carries")
1502
  except semantic.ModelError as exc:
1503
+ sentence = str(exc)
1504
+ low = sentence.lower()
1505
+ if any(needle in low for needle in _PIVOT_AUTHORING):
1506
+ # ARM 2 β€” AUTHORING, BUT NOT A COLUMN. An unknown metric (the one that fires on a bad
1507
+ # `via.measure`, because `_expand_measures` raises the BARE class), a foreign measure,
1508
+ # an unknown or company-level topic, a filter tree over the width, depth or size
1509
+ # limits, a sort that names nothing selected, and T06's invalid-operator refusal.
1510
+ # Every one of them is a fault in what was ASKED, so the asker is who can fix it.
1511
+ raise err(400, "pivot_bad_edge",
1512
+ f"{sentence.rstrip('. ')}. This pivot's edge comes from the link "
1513
+ f"field's 'via' declaration, so that declaration is what needs correcting")
1514
+ # ARM 3 β€” A GENUINE OUTAGE, 503, UNCHANGED, AND THE DEFAULT. The store is locked, cold or
1515
+ # missing, or the topic has no store binding. ⚠ `harness.semantic`'s data-cache sentence
1516
+ # says the cache is warming up after a restart; that is TRUE about the store and often
1517
+ # FALSE about the cause, which is usually another process holding it. It is not reworded
1518
+ # here: that file belongs to W42-T06, and a second copy of the sentence is how one fact
1519
+ # gets two definitions.
1520
+ raise err(503, "pivot_unavailable", sentence)
1521
 
1522
  # β›” `truncated` IS READ, NOT ASSUMED FALSE. `store_query` returns groups plus a flag, and a
1523
  # grouped query's groups ARE the answer, so a dropped one is missing data with nothing to
 
1617
  _PRODUCT_MODULE = "product_data"
1618
 
1619
  _C1_ROW_SOURCES = _register_topic_rows()
1620
+
1621
+
1622
+ # -----------------------------------------------------------------------------------------------
1623
+ # W42-T07 / contract C2 + amendment A5 - THE HOP OPERAND OFFER.
1624
+ #
1625
+ # `GET /grid/hop-topics` is the picker behind C1's `via` bag: the filter builder needs a topic's
1626
+ # DIMS as operands, the Measure picker needs that topic's MEASURES, and the window select needs
1627
+ # the window vocabulary the SAVE DOOR accepts. All three ride one payload because they are one
1628
+ # feature - A5's whole point is that dims alone leave the Measure picker permanently empty,
1629
+ # `_clean_via` refuses a bag with no `measure`, and no user can ever complete a hop while every
1630
+ # key-set parity gate stays green.
1631
+ #
1632
+ # It lives here and not in `routes_tables`, deliberately: this is pivot machinery.
1633
+ # `routes_tables`' `brief=1` branch answers a different question (which DATABASES a link may
1634
+ # target), and `_rollup_source_offer` answers a third (which (topic, measure, dim) triples a
1635
+ # ROLLUP column may bind). This one is MIRRORED from that offer's logic and calls none of it.
1636
+ #
1637
+ # MODEL FILES ONLY - NO STORE READ, AND THAT IS A DECISION, NOT AN OMISSION.
1638
+ # `_rollup_source_offer` additionally gates each topic on `sem._source_ready(table)`, and this
1639
+ # endpoint deliberately does NOT. `core.user_tables._topic_dims` - the VALIDATOR half of this
1640
+ # very feature - already ruled on the same question in its own docstring: "THE MODEL FILES,
1641
+ # NEVER THE STORE ... a validator that needed the store to say yes would refuse every legal link
1642
+ # the moment the file was locked by a `validate.py` run or cold after a restart." An OFFER that
1643
+ # failed closed on a locked store is strictly worse than a validator that does: the validator
1644
+ # refuses one link out loud, the offer empties the picker for everybody with nothing on screen to
1645
+ # explain it - A5's exact catastrophe, reached by a different road. It would also make the C2
1646
+ # parity gate flip red or green depending on who holds the duckdb lock.
1647
+ # THE COST IS STATED RATHER THAN HIDDEN: a topic with dims and measures but no live table
1648
+ # (`stock_moves` is the standing example) IS offered here and refuses at hop time. That is the
1649
+ # loud failure `_pivot_route_via` is built around, not the silent blank-column failure W37-T13
1650
+ # found on the rollup door. A future ticket may add readiness as a THIRD omission cause; it must
1651
+ # then also decide what an INDETERMINATE store answer means for the cache.
1652
+ #
1653
+ # Because the offer is a pure function of the model files, the cache is unconditionally safe -
1654
+ # none of `_ROLLUP_CACHE`'s "never memoise an indeterminate answer" reasoning applies here.
1655
+ _HOP_CACHE = {}
1656
+
1657
+ #: C2's `Field.source`. Every operand this endpoint offers comes from the TOPIC, never from the
1658
+ #: grid's own field contract, and the client needs to tell them apart when it merges the two
1659
+ #: lists into one filter builder.
1660
+ _HOP_FIELD_SOURCE = "topic"
1661
+
1662
+ #: The `FieldType` names this offer may emit - the intersection of `harness.semantic`'s column
1663
+ #: types and `customer-grid/types.ts::FieldType`. A type outside this set would reach a renderer
1664
+ #: with no branch for it.
1665
+ _HOP_FIELD_TYPES = ("text", "int", "date", "currency", "pct")
1666
+
1667
+
1668
+ def _hop_dim_type(cols, dim_key):
1669
+ """`Field.type` for one dim, READ OUT of `harness.semantic.store_columns`, never mapped here.
1670
+
1671
+ C2 asks for a type "from the dim's store column" and this is literally that: `store_columns`
1672
+ publishes `{sql, type, aggregate}` per column, and the dim's entry is its NAME column - the
1673
+ text a user types "contains" against - so every dim resolves to `text` today, while the
1674
+ `<dim>_id` companion column it also publishes is `int`. That is DERIVED, not a mapping
1675
+ somebody wrote down: give a future dim a numeric name column and the type follows with no
1676
+ edit here.
1677
+
1678
+ `store_columns` reads `_model()` (the cached `platform/model/topics/*.yml`) and opens no
1679
+ DuckDB connection, so asking it costs nothing and cannot make this endpoint store-dependent.
1680
+
1681
+ The `text` fallback is reachable only if `store_columns` and `store.dims` ever disagree about
1682
+ which keys exist, which they cannot today (one iterates the other). It is a floor, not a
1683
+ guess: it keeps an unknown operand FILTERABLE as text rather than emitting a type no renderer
1684
+ has a branch for.
1685
+ """
1686
+ ftype = ((cols or {}).get(dim_key) or {}).get("type")
1687
+ return ftype if ftype in _HOP_FIELD_TYPES else "text"
1688
+
1689
+
1690
+ def _hop_topic_offer():
1691
+ """`{topics, windows, omissions}` - every topic a `via` hop can actually be completed through.
1692
+
1693
+ A DIMLESS TOPIC IS OMITTED, NOT OFFERED EMPTY (amendment A12). The ticket's own done-when
1694
+ asked for it to be "offered with an empty operand list rather than omitted silently", and
1695
+ that is the LETTER of a rule whose operative word is *silently*: `user_tables._clean_via`
1696
+ refuses a `via` whose topic has no dims (`if not dims: return None`), because a hop REQUIRES
1697
+ `source_dim` and `target_dim` to BE dims of that topic. A dimless topic can therefore never
1698
+ be a legal hop, and offering it with an empty operand list ships a dead option that spends
1699
+ the user's time and blanks the column. So it is omitted AND the omission is REPORTED, with a
1700
+ machine-readable cause, under `omissions` - the client can say the topic cannot be hopped
1701
+ through, and nothing offered is unanswerable.
1702
+
1703
+ A TOPIC WITH NO USABLE MEASURE IS OMITTED FOR ITS OWN, DIFFERENT REASON, and the two causes
1704
+ are reported separately because seven of the eight topics omitted today are omitted for the
1705
+ SECOND one. Reporting them all as "declares no dims" would be false for seven of eight, and a
1706
+ client renders a cause verbatim to a user. `odoo_agents` alone carries both codes.
1707
+
1708
+ THE MEASURE EXCLUSION IS A PREDICATE, NEVER A NAME LIST. `store_query` refuses a
1709
+ `ratio`/`derived` metric the moment a `group_by` is present (cross-topic measures are
1710
+ scalar-only), and a hop ALWAYS has a `group_by` - its `target_dim`. Enumerating the excluded
1711
+ metrics by NAME instead would be [[two-enumerations-from-different-anchors]]: the names most
1712
+ often quoted for this rule are `aov`/`margin_pct`/`returns_pct`, and the live predicate
1713
+ catches seven, so a name list would offer four hops that can only ever error, plus every
1714
+ ratio metric added after it was written.
1715
+
1716
+ ONLY THE DECLARED DIMS ARE OFFERED. `store_columns` also publishes a `<dim>_id` companion and
1717
+ a `date` column, and `_clean_tree` would happily validate a filter on either - but C2's
1718
+ operand list is the topic's DIMS, and `_clean_via` matches `source_dim`/`target_dim` against
1719
+ exactly `store.dims`. Offering `<dim>_id` here would put two names for one operand in one
1720
+ picker. A future ticket may add them under their own payload key.
1721
+ """
1722
+ if _HOP_CACHE.get("offer"):
1723
+ return _HOP_CACHE["offer"]
1724
+ from harness import semantic as sem
1725
+ from harness import windows as W
1726
+ import core.user_tables as user_tables
1727
+
1728
+ topics, metrics = sem.topics(), sem.metrics()
1729
+
1730
+ by_topic = {}
1731
+ for key, m in metrics.items():
1732
+ # See the docstring: the predicate IS the enumeration. A ratio/derived metric cannot
1733
+ # survive the `group_by` a hop always carries.
1734
+ if m.get("agg") in ("ratio", "derived"):
1735
+ continue
1736
+ by_topic.setdefault(m.get("topic"), []).append(
1737
+ {"key": key, "label": m.get("label") or key,
1738
+ "format": m.get("format") or "usd",
1739
+ "description": m.get("description") or ""})
1740
+
1741
+ out, omissions = [], []
1742
+ for tkey, t in sorted(topics.items()):
1743
+ store = t.get("store") or {}
1744
+ dims = store.get("dims") or {}
1745
+ measures = by_topic.get(tkey) or []
1746
+ label = t.get("label") or tkey
1747
+ if not dims or not measures:
1748
+ # Machine-readable codes, and BOTH when both apply. No prose sentence lives in this
1749
+ # payload: the wording belongs to the client, which is the surface that knows what
1750
+ # the user was trying to do.
1751
+ reasons = []
1752
+ if not dims:
1753
+ reasons.append("no_dims")
1754
+ if not measures:
1755
+ reasons.append("no_measures")
1756
+ omissions.append({"topic": tkey, "label": label, "reasons": reasons})
1757
+ continue
1758
+ try:
1759
+ cols = sem.store_columns(tkey, include_measures=False)
1760
+ except Exception: # noqa: BLE001
1761
+ # A topic can declare `store.dims` only inside a `store` block, so this is
1762
+ # unreachable today; it is here so a malformed model file drops ONE topic with a
1763
+ # stated cause instead of 500-ing the whole picker.
1764
+ omissions.append({"topic": tkey, "label": label,
1765
+ "reasons": ["no_store_columns"]})
1766
+ continue
1767
+ out.append({
1768
+ "key": tkey,
1769
+ "label": label,
1770
+ "grain": t.get("grain") or "",
1771
+ # C2's `Field[]`. SUPERSET, DECLARED: C2 enumerates `key`/`label`/`type`/`source`,
1772
+ # and `keyedBy` rides along because C1's `target_key` is the TARGET GRID's join
1773
+ # column and the user cannot pick it without knowing whether this dim keys by an
1774
+ # Odoo id or by its own value - the same fact `RollupSourceTopic.dims` carries.
1775
+ "dims": [{"key": dkey,
1776
+ "label": d.get("label") or dkey,
1777
+ "type": _hop_dim_type(cols, dkey),
1778
+ "source": _HOP_FIELD_SOURCE,
1779
+ "keyedBy": "id" if d.get("name_col") else "value"}
1780
+ for dkey, d in dims.items()],
1781
+ "measures": sorted(measures, key=lambda m: m["label"].lower()),
1782
+ })
1783
+
1784
+ # `core.user_tables.LINK_VIA_WINDOWS` IS THE AUTHORITY, not `harness.windows`, because it is
1785
+ # the set `_clean_via` accepts (`window not in LINK_VIA_WINDOWS` refuses the field). It
1786
+ # aliases `ROLLUP_SOURCE_WINDOWS` and deliberately omits the parameterised kinds
1787
+ # (`last_n_days`, `custom`), which have nowhere in the `via` bag to carry their `n`. Offering
1788
+ # a kind the save door refuses would let the editor build a field that cannot be stored.
1789
+ # The all-time key is `all_time`; `all` is not a window and is refused.
1790
+ windows = [{"key": k, "label": W.WINDOW_LABELS.get(k, k).format(n="N")}
1791
+ for k in user_tables.LINK_VIA_WINDOWS]
1792
+
1793
+ offer = {"topics": out, "windows": windows, "omissions": omissions}
1794
+ _HOP_CACHE["offer"] = offer
1795
+ return offer
1796
+
1797
+
1798
+ @router.get("/grid/hop-topics")
1799
+ def grid_hop_topics(session: Session = Depends(require_session)):
1800
+ """C2's operand offer for the hop editor: topics, their dims and measures, and the windows.
1801
+
1802
+ TENANT-SCOPED, for the reason `rollup_sources` records: `sem.topics()` reads the GLOBAL model
1803
+ files, so a tenant with no Odoo mirror behind it would be offered a hop it can never resolve.
1804
+ `odoo_relational.is_royal` is the one authority on that and is reused, not re-decided.
1805
+
1806
+ `omissions` IS PRESENT ON EVERY RESPONSE, including this early return, so the payload shape is
1807
+ unconditional and no reader needs a branch for its absence.
1808
+
1809
+ Declared as a LITERAL path under `/grid/`, and there is no `GET /grid/{something}` route in
1810
+ this file for it to be swallowed by. If one is ever added it must go BELOW this line - FastAPI
1811
+ matches in declaration order.
1812
+ """
1813
+ import odoo_relational
1814
+ if not odoo_relational.is_royal(session.tenant):
1815
+ return {"topics": [], "windows": [], "omissions": []}
1816
+ return _hop_topic_offer()
api/routes_shares.py CHANGED
@@ -411,6 +411,412 @@ def _unremovable(held_rows, entries, uname):
411
  stuck.add(user)
412
  return stuck
413
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
414
 
415
  @router.get("/share/mine")
416
  def my_shares(session: Session = Depends(require_session)):
@@ -626,21 +1032,15 @@ def put_share(kind: str, oid: str, body: dict = Body(default=None),
626
  # A field grant is a visibility and edit wall. Promote a private custom
627
  # field exactly once, then keep the requested Share field role as the
628
  # authoritative override for the legacy permissions bag.
629
- from core import field_permissions, shared_overlay
 
 
 
630
  table_key, field_key = shares.split_field_oid(oid)
631
- defn, already_shared, workspace_key, shared_key, grant_topic = _field_definition(
632
- session, table_key, field_key)
633
- if not isinstance(defn, dict):
634
  raise err(404, "no_object", "no such field, or it is not shared with this account")
635
- if not already_shared:
636
- defn = field_permissions.promote_field(
637
- workspace_key, shared_key, grant_topic,
638
- session.uname, defn, st=session.runtime)
639
- stamped = dict(defn)
640
- stamped["shared"] = True
641
- stamped["granted"] = True
642
- shared_overlay.put_field(shared_key, field_key, stamped, st=session.runtime)
643
- oid = shares.field_oid(grant_topic, field_key)
644
  # ⭐⭐ R4 / W40-T02 (D3) β€” OWNERSHIP NEVER MOVES ON A RE-SHARE, AND IT IS SAID HERE RATHER
645
  # THAN LEFT TO FALL OUT. `set_grants`' owner is sticky, so the old `rec["owner"] or
646
  # session.uname` already happened not to transfer ownership β€” incidentally, as a property of
@@ -670,6 +1070,20 @@ def put_share(kind: str, oid: str, body: dict = Body(default=None),
670
  except shares.GrantsChanged as exc:
671
  raise err(409, "grants_changed", str(exc))
672
  _notify_new_grantees(session, kind, oid, before=rec["entries"], after=out.get("entries") or [])
 
 
 
 
 
 
 
 
 
 
 
 
 
 
673
  return out
674
 
675
 
 
411
  stuck.add(user)
412
  return stuck
413
 
414
+ # ── ⭐⭐ WAVE 42 Β· T25 β€” SHARING A VIEW SHARES THE FIELDS IT NAMES ──────────────────────────────
415
+ #
416
+ # A saved view is a SELECTION expressed in columns: an order, a visible set, a group, a colour,
417
+ # a sort and a filter tree, every one of which names a field key. Granting the view alone hands
418
+ # the receiver a rail row whose columns resolve to nothing they may read, so the feature that
419
+ # looked shipped puts an empty grid on their screen. This block closes that, and it refuses
420
+ # LOUDLY in the three places where a grant would otherwise be a lie.
421
+ #
422
+ # β›”β›” TRAP 1 β€” A FIELD GRANT IS TOPIC-WIDE, NOT VIEW-SCOPED. It is keyed
423
+ # `shares.field_oid(topic, key)`, so it hands the receiver that column on EVERY view of that
424
+ # database, for as long as the grant stands. That is the existing grant primitive and this
425
+ # ticket does not narrow it; what it does is refuse to let the response PRETEND otherwise, which
426
+ # is why `sharedFieldScope` rides back beside the list.
427
+ #
428
+ # β›”β›” TRAP 2 β€” THE SHARER CANNOT GRANT A COLUMN THEY DO NOT OWN. `field` is absent from
429
+ # `shares.RESHARE_KINDS` and `_owns_object`'s field branch demands `createdBy == session.uname`,
430
+ # so a view built over a colleague's column simply cannot carry that column with it. Silently
431
+ # skipping it ships an empty column; silently granting it is a permission hole. It is REFUSED
432
+ # BY NAME, inside the 200 response, with the sentence that says who to ask.
433
+ #
434
+ # β›”β›” TRAP 3 β€” A GRANT CANNOT UN-HIDE AN ADMIN-WALLED COLUMN. `perm_scope.hidden_keys` UNIONS
435
+ # the administrator's `hiddenFields` with the field-grant source, so granting a walled column
436
+ # answers 200, writes the record, and the receiver still sees nothing: granted with no effect,
437
+ # which is the failure this ticket exists to end. Detected BEFORE the grant, refused by name,
438
+ # and the receiver it is walled from is named too.
439
+ #
440
+ # ⚠ THE WALL IS READ FROM THE ADMIN SOURCE DIRECTLY AND NEVER THROUGH `hidden_keys`, AND THAT IS
441
+ # NOT AN OPTIMISATION. `hidden_keys` unions `field_grant_hidden` β€” "hidden because you were not
442
+ # granted it" β€” which is true of every column this route is ABOUT to grant. Asking it here would
443
+ # refuse the whole set on the grounds that the grant has not happened yet.
444
+
445
+
446
+ def _view_configs(view):
447
+ """The dicts a saved view keeps its column state in.
448
+
449
+ `SavedView.config` is the contract (`types.ts::ViewConfig`) and is where every key below
450
+ actually lives. The record ITSELF is read as well because a legacy row that stored the same
451
+ members flat costs one dict lookup to cover and would otherwise hand back an empty key set,
452
+ which is the shape that grants nothing and reports nothing wrong.
453
+ """
454
+ out = []
455
+ if not isinstance(view, dict):
456
+ return out
457
+ cfg = view.get("config")
458
+ if isinstance(cfg, dict):
459
+ out.append(cfg)
460
+ out.append(view)
461
+ return out
462
+
463
+
464
+ def _view_field_keys(view):
465
+ """Every field key this view NAMES, in the order a reader would meet them.
466
+
467
+ ⚠ `filters[].rhs` IS ONE OF THEM AND IS THE ONE THAT GETS DROPPED. A field-vs-field leaf
468
+ (`{colId: price, op: lt, rhs: {kind: field, colId: cost}}`) names TWO columns, and a share
469
+ carrying only the left one leaves the receiver a filter that cannot evaluate. `kind` `stat`
470
+ is not a column reference and is skipped, matching `perm_scope`'s own reader of the tree.
471
+
472
+ ⚠ AND `filters` IS A TREE, NOT A LIST. Condition groups nest under `children`, so the walk
473
+ recurses rather than iterating once: a column named only inside a group is still named.
474
+ """
475
+ keys, seen = [], set()
476
+
477
+ def add(raw):
478
+ key = str(raw or "").strip()
479
+ if key and key not in seen:
480
+ seen.add(key)
481
+ keys.append(key)
482
+
483
+ def walk(node):
484
+ if isinstance(node, list):
485
+ for child in node:
486
+ walk(child)
487
+ return
488
+ if not isinstance(node, dict):
489
+ return
490
+ kids = node.get("children")
491
+ if isinstance(kids, list):
492
+ walk(kids)
493
+ add(node.get("colId"))
494
+ rhs = node.get("rhs")
495
+ if isinstance(rhs, dict) and rhs.get("kind") != "stat":
496
+ add(rhs.get("colId"))
497
+
498
+ for cfg in _view_configs(view):
499
+ for key in (cfg.get("order") or ()):
500
+ add(key)
501
+ for key in (cfg.get("visible") or ()):
502
+ add(key)
503
+ walk(cfg.get("filters"))
504
+ add(cfg.get("groupBy"))
505
+ colour = cfg.get("colorBy")
506
+ add(colour.get("colId") if isinstance(colour, dict) else colour)
507
+ sorts = cfg.get("sorts")
508
+ if isinstance(sorts, dict):
509
+ sorts = [sorts]
510
+ for spec in (sorts or ()):
511
+ if isinstance(spec, dict):
512
+ add(spec.get("colId"))
513
+ return keys
514
+
515
+
516
+ def _find_view_topic(session, oid):
517
+ """`(topic, view)` for a saved view living in any personal stratum of any topic, else
518
+ `(None, None)`.
519
+
520
+ ⚠ THE TOPIC IS HALF THE ANSWER. A field grant is keyed by TOPIC, so resolving the view
521
+ without remembering which workspace answered would leave the caller guessing at the oid,
522
+ which is exactly how two arms of one route come to write two different keys for one column.
523
+ Same loop and same finder as `_owns_object`, which answers a different question about the
524
+ same lookup and is deliberately left alone.
525
+ """
526
+ try:
527
+ import core.table_store as table_store
528
+ except Exception: # noqa: BLE001
529
+ return None, None
530
+ for topic in _topics(session):
531
+ try:
532
+ hit = table_store.make(f"{topic}_table_workspace", st=session.runtime).find_view(oid)
533
+ except Exception: # noqa: BLE001
534
+ continue
535
+ if hit:
536
+ return str(topic), (hit[1] if len(hit) > 1 else {})
537
+ return None, None
538
+
539
+
540
+ def _promote_field_for_grant(session, table_key, field_key):
541
+ """Promote a private column exactly once, stamp it shared, and answer its GRANT OID.
542
+
543
+ β›”β›” ONE SEQUENCE, TWO ARMS, AND THAT IS THE WHOLE REASON THIS IS A FUNCTION. `put_share`'s
544
+ `field` arm and its `view` arm (T25) both hand a column to somebody. Two spellings of
545
+ "promote, stamp, key the oid" is how two surfaces start disagreeing about what a grant
546
+ means, and the oid is the exact member that would drift: it is normalised through
547
+ `_field_storage_keys(...)[2]`, never built from whatever key the caller happened to hold.
548
+
549
+ Answers `None` for a key with no definition on that database, so the caller decides whether
550
+ that is a 404 (the `field` arm, where the column IS the request) or a named refusal (the
551
+ `view` arm, where it is one entry in a list).
552
+ """
553
+ from core import field_permissions, shared_overlay
554
+ defn, already_shared, workspace_key, shared_key, grant_topic = _field_definition(
555
+ session, table_key, field_key)
556
+ if not isinstance(defn, dict):
557
+ return None
558
+ if not already_shared:
559
+ defn = field_permissions.promote_field(
560
+ workspace_key, shared_key, grant_topic,
561
+ session.uname, defn, st=session.runtime)
562
+ stamped = dict(defn)
563
+ stamped["shared"] = True
564
+ stamped["granted"] = True
565
+ shared_overlay.put_field(shared_key, field_key, stamped, st=session.runtime)
566
+ return shares.field_oid(grant_topic, field_key)
567
+
568
+
569
+ def _grant_receivers(session, entries):
570
+ """`{username: display name}` for everybody a grant list actually reaches.
571
+
572
+ `shares.EVERYONE` is a real audience, not a placeholder, so it expands to the tenant roster
573
+ `_people` already computes for the picker. Reading it from a second place would be a second
574
+ answer to "who is in this workspace".
575
+ """
576
+ people = None
577
+ out = {}
578
+ for entry in shares._clean_entries(entries):
579
+ who = str(entry.get("user") or "").strip().lower()
580
+ if not who:
581
+ continue
582
+ if who == shares.EVERYONE:
583
+ if people is None:
584
+ people = _people(session.tenant)
585
+ for person in people:
586
+ out.setdefault(str(person["username"]).strip().lower(), person["name"])
587
+ continue
588
+ out.setdefault(who, who)
589
+ if out:
590
+ try:
591
+ reg = users.registry() or {}
592
+ except Exception: # noqa: BLE001
593
+ reg = {}
594
+ for uname in list(out):
595
+ rec = reg.get(uname)
596
+ if isinstance(rec, dict) and rec.get("name"):
597
+ out[uname] = str(rec["name"])
598
+ return out
599
+
600
+
601
+ def _admin_walled(session, grant_topic, defs, receivers):
602
+ """`{field key: [display names]}` for receivers an ADMINISTRATOR has already walled off.
603
+
604
+ β›” THE ADMIN SOURCE ONLY. `perm_scope.entry(rec, module)['hiddenFields']` is the half of
605
+ `hidden_keys` a field grant cannot overrule; the other half IS the field grant, so consulting
606
+ the closure here would report every column this route is about to grant as hidden and refuse
607
+ the lot (see the block note above).
608
+
609
+ ⭐ THE MEASURE BINDING IS BORROWED, NEVER RESPELLED. An administrator ticking
610
+ "Metric - Gross margin" stores `measure_margin`, while the COLUMNS carrying that number are
611
+ keyed `measure_margin_<rand>`; `perm_scope._measure_bound_keys` is the one evaluator that
612
+ joins the two, and a second copy here would be the first to drift.
613
+
614
+ ⚠ AN ADMINISTRATOR RECEIVER IS NEVER WALLED β€” `hidden_keys` answers an empty set for one
615
+ before it reads anything β€” so the same short circuit runs here, or this function would refuse
616
+ a grant to somebody who can already see the column.
617
+
618
+ ⚠ A RECEIVER WITH NO REGISTRY RECORD IS SKIPPED RATHER THAN TREATED AS WALLED: `perm_scope`
619
+ reads a permission block off the RECORD (`_rec` answers `{}` for a bare username), so a name
620
+ this tenant cannot resolve carries no admin wall to find. `_entries_or_400` has already
621
+ refused a grant list naming an account that does not exist.
622
+ """
623
+ import core.perm_scope as perm_scope
624
+ import core.perms as perms
625
+ try:
626
+ reg = users.registry() or {}
627
+ except Exception: # noqa: BLE001
628
+ reg = {}
629
+ field_list = [dict(defn or {}, key=key) for key, defn in defs.items()
630
+ if isinstance(defn, dict)]
631
+ walled = {}
632
+ for uname, display in sorted(receivers.items()):
633
+ rec = reg.get(uname)
634
+ if not isinstance(rec, dict) or perms.is_admin(rec):
635
+ continue
636
+ try:
637
+ entry = perm_scope.entry(rec, grant_topic) or {}
638
+ except Exception: # noqa: BLE001
639
+ continue
640
+ hidden = {str(k) for k in (entry.get("hiddenFields") or ()) if k}
641
+ if not hidden:
642
+ continue
643
+ try:
644
+ hidden |= set(perm_scope._measure_bound_keys(hidden, field_list))
645
+ except Exception: # noqa: BLE001
646
+ pass
647
+ for key in defs:
648
+ if key in hidden:
649
+ walled.setdefault(key, []).append(display)
650
+ return walled
651
+
652
+
653
+ #: ⭐ THE THREE REASONS A VIEW'S COLUMN IS NOT GRANTED, EACH ITS OWN CODE. One fused
654
+ #: "could not share" would make the three walls unprovable apart, which is the
655
+ #: [[a-declared-gate-is-an-unchecked-claim]] failure `verify_field_doors` section 8 exists to
656
+ #: prevent: every cause fails by its own name, or it is not gated at all.
657
+ #: β›” STANDING RULE 2 β€” no em dash and no en dash in any sentence below; these reach a screen.
658
+ FIELD_REFUSAL_CODES = ("not_a_shared_column", "not_owned", "admin_hidden")
659
+
660
+ #: ⭐ TRAP 1, SAID OUT LOUD. A column grant is keyed by DATABASE, so it is not scoped to the view
661
+ #: that occasioned it. The response carries this sentence rather than letting a caller infer a
662
+ #: narrower promise than the store actually makes.
663
+ FIELD_GRANT_SCOPE = ("A column shared this way is shared on the whole database, so the people "
664
+ "you named can see it on every view of it, not only on this one.")
665
+
666
+
667
+ def _refusal(key, code, names=()):
668
+ """One refused column, with the sentence a person reads."""
669
+ if code == "not_a_shared_column":
670
+ why = ('"{k}" belongs to the database itself rather than to a person, so there was '
671
+ 'nothing to grant. Anybody who can open the database already sees it.')
672
+ elif code == "not_owned":
673
+ why = ('"{k}" is somebody else\'s column, and only its owner (or an administrator) can '
674
+ 'share it. Ask them to share it, then share this view again.')
675
+ else:
676
+ why = ('"{k}" is hidden from {who} by an administrator, so sharing it would change '
677
+ 'nothing. Ask an administrator to unhide it first.')
678
+ return {"field": key, "reason": code,
679
+ "message": why.format(k=key, who=_named(names) if names else "them")}
680
+
681
+
682
+ def _classify_view_fields(keys, owned, defined, walled):
683
+ """`(sharedFieldKeys, refusedFieldKeys)` for the columns a view names. PURE.
684
+
685
+ β›” EVERY KEY IS DECIDED BEFORE ANY OF THEM IS WRITTEN, which is the same property the ceiling
686
+ block above claims for the three role walls: a refusal must not be able to leave part of the
687
+ set promoted and part of it untouched.
688
+
689
+ ⚠ THE ORDER OF THE CAUSES IS FIXED AND IT DECIDES WHICH SENTENCE A PERSON READS. A built-in
690
+ column is owned by nobody, so "there was nothing to grant" has to be asked before "you do not
691
+ own it", or every database column in `visible` would be reported as somebody else's.
692
+ """
693
+ granted, refused = [], []
694
+ for key in keys:
695
+ if key not in defined:
696
+ refused.append(_refusal(key, "not_a_shared_column"))
697
+ elif key not in owned:
698
+ refused.append(_refusal(key, "not_owned"))
699
+ elif walled.get(key):
700
+ refused.append(_refusal(key, "admin_hidden", walled.get(key)))
701
+ else:
702
+ granted.append(key)
703
+ return granted, refused
704
+
705
+ def _merge_field_entries(existing, incoming):
706
+ """A column's grant list with `incoming` ADDED to it. Nobody is removed, nobody is lowered.
707
+
708
+ β›”β›” THE SHARE PUT REPLACES, AND A COLUMN'S AUDIENCE IS NOT THE VIEW'S AUDIENCE. This route's
709
+ contract is a REPLACING set (`PUT ... entries` at the top of the file), which is right for the
710
+ object the caller is looking at and catastrophic for the columns underneath it: a column grant
711
+ is TOPIC-WIDE, so handing the view's list straight to `set_grants` would rewrite the column's
712
+ audience to whoever this view happens to be shared with. A colleague granted that column
713
+ through the `field` door would lose it, on every view of the database, silently, inside a 200.
714
+ That is exactly the harm D-474 closed at the view door, arriving one door over.
715
+
716
+ ⚠ AND A LENGTH CHECK DOES NOT SEE IT. Replacing a one-person list with a different one-person
717
+ list keeps the count identical, so the gate asserts the HELD USER IS STILL THERE AT THEIR OWN
718
+ ROLE rather than counting rows.
719
+
720
+ ⭐ RAISED, NEVER LOWERED. A receiver already held at `view` who arrives on an `edit` share is
721
+ raised, because only the column's owner (or an administrator) reaches this path at all and
722
+ that is the access they just asked to hand over. An `edit` holder meeting a `view` share keeps
723
+ `edit`: a share is an addition, and nothing here is a revocation.
724
+
725
+ ⚠ `by` RIDES ON EXISTING ROWS AND IS NEVER TAKEN FROM AN INCOMING ONE. Provenance decides who
726
+ may revoke a grant (`_unremovable`), so an incoming payload must not be able to claim it;
727
+ `set_grants` stamps a genuinely new row from `granter`.
728
+ """
729
+ rank = {"view": 0, "edit": 1}
730
+ order, merged = [], {}
731
+ for row in (existing or ()):
732
+ if not isinstance(row, dict):
733
+ continue
734
+ who = str(row.get("user") or "").strip().lower()
735
+ role = str(row.get("role") or "").strip().lower()
736
+ if not who or role not in rank or who in merged:
737
+ continue
738
+ kept = {"user": who, "role": role}
739
+ stamp = str(row.get("by") or "").strip().lower()
740
+ if stamp:
741
+ kept["by"] = stamp
742
+ merged[who] = kept
743
+ order.append(who)
744
+ for row in (incoming or ()):
745
+ if not isinstance(row, dict):
746
+ continue
747
+ who = str(row.get("user") or "").strip().lower()
748
+ role = str(row.get("role") or "").strip().lower()
749
+ if not who or role not in rank:
750
+ continue
751
+ if who not in merged:
752
+ merged[who] = {"user": who, "role": role}
753
+ order.append(who)
754
+ elif rank[role] > rank[merged[who]["role"]]:
755
+ merged[who]["role"] = role
756
+ return [merged[who] for who in order]
757
+
758
+ def _share_view_fields(session, oid, entries):
759
+ """The `view` arm's field half: classify every column the view names, then grant the ones
760
+ that survive. `(sharedFieldKeys, refusedFieldKeys)`.
761
+
762
+ β›” CLASSIFY EVERYTHING, THEN WRITE. `_classify_view_fields` sees the whole key set before
763
+ `_promote_field_for_grant` touches a single definition, so a refusal cannot leave half the
764
+ view's columns promoted.
765
+
766
+ ⚠ THE VIEW'S OWN GRANT HAS ALREADY BEEN WRITTEN when this runs, and that order is the safe
767
+ one: a `409 grants_changed` on the view must not be preceded by a set of column promotions
768
+ for a share that then did not happen.
769
+ """
770
+ topic, view = _find_view_topic(session, oid)
771
+ if not topic or not isinstance(view, dict):
772
+ return [], []
773
+ keys = _view_field_keys(view)
774
+ if not keys:
775
+ return [], []
776
+ table_key = f"{topic}_table_workspace"
777
+ grant_topic = _field_storage_keys(table_key)[2]
778
+ defs, defined, owned, owners = {}, set(), set(), {}
779
+ for key in keys:
780
+ defn, already_shared = _field_definition(session, table_key, key)[:2]
781
+ if not isinstance(defn, dict):
782
+ continue
783
+ defs[key] = defn
784
+ defined.add(key)
785
+ # ⚠ THE COLUMN'S OWNER, NOT THIS SESSION. `set_grants`' owner is sticky, so stamping the
786
+ # SHARER here would hand an administrator sharing somebody else's column the ownership
787
+ # of it as a side effect of sharing a view. Same resolver the claim wall uses.
788
+ owners[key] = _field_owner(session, defn, already_shared)
789
+ # β›” ONE OWNERSHIP PREDICATE. `_owns_object` is the wall the `field` arm claims through
790
+ # and the DELETE door reads; a second "does this person own this column" here is how the
791
+ # two answers come apart. It short circuits True for an administrator, which is right:
792
+ # an administrator may already share any column through the `field` door.
793
+ if _owns_object(session, "field", shares.field_oid(grant_topic, key)):
794
+ owned.add(key)
795
+ walled = _admin_walled(session, grant_topic, defs, _grant_receivers(session, entries))
796
+ granted, refused = _classify_view_fields(keys, owned, defined, walled)
797
+ written = []
798
+ for key in granted:
799
+ field_oid = _promote_field_for_grant(session, table_key, key)
800
+ if not field_oid:
801
+ refused.append(_refusal(key, "not_a_shared_column"))
802
+ continue
803
+ # β›”β›” ADDED TO, NEVER REPLACED. `set_grants` writes the list it is given, and this route
804
+ # PUTs a REPLACING set, so handing it the view's `entries` would make the view's audience
805
+ # the COLUMN's audience: a colleague granted this column through the `field` door would
806
+ # lose it, on every view of the database, inside a 200. `_merge_field_entries` says what
807
+ # that sentence means once, and it is the only writer of a column list on this path.
808
+ held = shares.grants("field", field_oid, st=session.runtime)
809
+ # ⚠ NO `expect` HERE, AND THAT IS NOT AN OVERSIGHT. The compare-and-set on the view's own
810
+ # grant guards a record TWO PEOPLE ARE EDITING through the same dialog. A column's record
811
+ # was just read (and possibly created) inside this call, nobody is looking at it in a
812
+ # dialog, and a `409` raised at this point would fail a PUT whose view grant has ALREADY
813
+ # been written, which is the half-applied state the refusals above exist to avoid.
814
+ shares.set_grants("field", field_oid,
815
+ _merge_field_entries(held.get("entries"), entries),
816
+ owner=held.get("owner") or owners.get(key) or session.uname,
817
+ granter=session.uname, st=session.runtime)
818
+ written.append(key)
819
+ return written, refused
820
 
821
  @router.get("/share/mine")
822
  def my_shares(session: Session = Depends(require_session)):
 
1032
  # A field grant is a visibility and edit wall. Promote a private custom
1033
  # field exactly once, then keep the requested Share field role as the
1034
  # authoritative override for the legacy permissions bag.
1035
+ # ⭐⭐ W42-T25 β€” THE SEQUENCE MOVED INTO `_promote_field_for_grant` AND DID NOT CHANGE.
1036
+ # The `view` arm below now hands columns to people as well, and one function answering
1037
+ # "promote, stamp, key the oid" is what keeps the two arms writing the SAME oid for the
1038
+ # same column. `None` here still means the column does not exist on that database.
1039
  table_key, field_key = shares.split_field_oid(oid)
1040
+ promoted = _promote_field_for_grant(session, table_key, field_key)
1041
+ if promoted is None:
 
1042
  raise err(404, "no_object", "no such field, or it is not shared with this account")
1043
+ oid = promoted
 
 
 
 
 
 
 
 
1044
  # ⭐⭐ R4 / W40-T02 (D3) β€” OWNERSHIP NEVER MOVES ON A RE-SHARE, AND IT IS SAID HERE RATHER
1045
  # THAN LEFT TO FALL OUT. `set_grants`' owner is sticky, so the old `rec["owner"] or
1046
  # session.uname` already happened not to transfer ownership β€” incidentally, as a property of
 
1070
  except shares.GrantsChanged as exc:
1071
  raise err(409, "grants_changed", str(exc))
1072
  _notify_new_grantees(session, kind, oid, before=rec["entries"], after=out.get("entries") or [])
1073
+ # ⭐⭐ W42-T25 β€” SHARING A VIEW SHARES THE FIELDS IT NAMES. A view is a selection expressed
1074
+ # in columns, so a grant that carries the view and none of its columns puts a rail row on
1075
+ # the receiver's screen over an empty grid. The three refusals are named rather than thrown:
1076
+ # this PUT succeeded, the view IS shared, and what could not follow it is reported by name
1077
+ # with the reason. Throwing instead would make the ordinary case (a view over one built-in
1078
+ # column) unshareable.
1079
+ # β›” THE EXISTING KEYS ARE UNTOUCHED. `{owner, entries}` is what every current client reads
1080
+ # off this route; the field report is additive, and a caller that ignores it is unaffected.
1081
+ if kind == "view":
1082
+ shared_fields, refused_fields = _share_view_fields(session, oid, entries)
1083
+ return {**out,
1084
+ "sharedFieldKeys": shared_fields,
1085
+ "refusedFieldKeys": refused_fields,
1086
+ "sharedFieldScope": FIELD_GRANT_SCOPE}
1087
  return out
1088
 
1089
 
api/routes_tables.py CHANGED
@@ -1050,10 +1050,32 @@ def _usage_column_refs(field):
1050
  return rollup, automation
1051
 
1052
 
1053
- def _field_usage(session, table_key, fields, defn, ops, st=None):
1054
  """`{field_key: {views, filters, rollups, automations, permRules}}` β€” C8's `usage`, computed
1055
  over the WHOLE workspace, or `{}` when it cannot be established.
1056
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1057
  ⭐⭐ W41-T10 / R3 / C8. The `done-when`'s load-bearing clause is *"over the whole workspace,
1058
  not from a partial client list"*: the assembly's own `ws` holds this caller's stratum merged
1059
  with the views shared TO them, so a count taken from it would miss every private view every
@@ -1099,18 +1121,18 @@ def _field_usage(session, table_key, fields, defn, ops, st=None):
1099
  return {}
1100
  lent = st if st is not None else session.runtime
1101
  memo_key = (str(getattr(session, "tenant", "") or ""), str(table_key))
1102
- token = _usage_token(lent, ops.table_key)
1103
  if token is not None:
1104
  hit = _USAGE_MEMO.get(memo_key)
1105
  if hit and hit[0] == token:
1106
  return hit[1]
1107
  try:
1108
- # ⚠ `ops.st` and `ops.table_key`, not a rebuilt literal: the store key `_ops` closed over
1109
- # is the one this database's strata actually live under, and a second spelling of the
1110
- # suffix is a second thing to keep in step. A lend passes `<key>_table_workspace` straight
1111
- # through to the runtime (it serves only `user_tables` and `object_shares`), so this is
1112
- # the tenant's own document.
1113
- ws_doc = ops.st.get(ops.table_key) or {}
1114
  except Exception: # noqa: BLE001
1115
  return {}
1116
  try:
@@ -1285,8 +1307,14 @@ def ut_assembly(session: Session, table_key: str, storage_key: str = "",
1285
  # `dict(f, source=…)` copies for the shared stratum but passes the rest through by reference,
1286
  # and `_usage_field_corpus` hands those same objects back. Mutating one would write a count
1287
  # into a definition the next reader shares.
1288
- # β›” AND ONLY `usage`. `class` shipped with W41-T01, `agg` belongs to lanes B and D and
1289
- # `descriptionEdited` to W41-T11; C8 is explicit that an absent key means "not built yet".
 
 
 
 
 
 
1290
  #
1291
  # ⚠ LENIENT, LIKE EVERY OTHER DISPLAY READ ON THIS ASSEMBLY, and C8's absent-key polarity is
1292
  # what makes degrading safe: a client renders nothing for a missing `usage` rather than a
@@ -1295,13 +1323,59 @@ def ut_assembly(session: Session, table_key: str, storage_key: str = "",
1295
  # ⚠ A COPY OF THE BAG, because `_field_usage` MEMOISES its answer: handing the memo's own dict
1296
  # out would let anything downstream write into the number the next request reads.
1297
  try:
1298
- _usage = _field_usage(session, table_key, fields, defn, ops, st=st)
 
1299
  except Exception: # noqa: BLE001
1300
  _usage = {}
1301
  if _usage:
1302
  fields = [dict(f, usage=dict(_usage[f["key"]]))
1303
  if isinstance(f, dict) and _usage.get(f.get("key")) else f
1304
  for f in fields]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1305
  # ⭐⭐ C8's `descriptionEdited`, AND IT CLOSES A CONSUMER THAT WAS ALREADY WRITTEN.
1306
  # W41-T11 built the producer (`user_tables.description_edited`, R19's custody mark scoped to the
1307
  # description) and correctly stopped at its own fence, which is one core file. Measured across
@@ -2606,6 +2680,179 @@ def delete_field(table_key: str, fkey: str, session: Session = Depends(require_s
2606
  return {"deleted": fkey}
2607
 
2608
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2609
  @router.delete("/tables/{table_key}/rows/{rid}")
2610
  def delete_row(table_key: str, rid: str, session: Session = Depends(require_session)):
2611
  # ⭐⭐ W31 QA β€” ONE SNAPSHOT FOR THE WHOLE DELETE, and the owner reported what it cost.
 
1050
  return rollup, automation
1051
 
1052
 
1053
+ def _field_usage(session, table_key, fields, defn, ws_st, ws_key, st=None):
1054
  """`{field_key: {views, filters, rollups, automations, permRules}}` β€” C8's `usage`, computed
1055
  over the WHOLE workspace, or `{}` when it cannot be established.
1056
 
1057
+ ⭐⭐ W42-T14 / C4 β€” **PARAMETERISED OFF `(ws_st, ws_key)`, NOT OFF A `user_tables` OPS OBJECT.**
1058
+ The only two things the old `ops` argument was ever asked for were `ops.st` (the bound store
1059
+ handle) and `ops.table_key` (the name of the document every account's strata live in), so
1060
+ taking those two directly is what lets a SECOND surface call this. It matters because the
1061
+ document is NOT named `<key>_table_workspace` everywhere: on the customer topic it is
1062
+ `modules.customer_data.TABLE_KEY` (`customer_table_workspace`), a name no `f"{table_key}_…"`
1063
+ literal can produce. Rebuilding the string here rather than being handed it is exactly the
1064
+ second spelling `_ops`' own note refuses.
1065
+
1066
+ β›”β›” `table_key` IS THE MEMO KEY AND IT IS THE TOPIC, NEVER THE DOCUMENT. `(tenant, table_key)`
1067
+ addresses the memo, `rec['perms'][table_key]` addresses the permission record and
1068
+ `config.targetTable == table_key` addresses the flow binding β€” three reads that must all name
1069
+ the SAME thing the registry calls this database. `ut_assembly` passes its `table_key`;
1070
+ `routes_customers.grid_assembly` passes its module constant `customer_data`, which is the key
1071
+ `apply_row_scope`, `hidden_keys` and `routes_admin._clean_perms` already spell there. A caller
1072
+ that spelled it differently (the topic on one door, the bucket on another) would pin a stale
1073
+ answer under a key nothing ever invalidates, for the life of the process.
1074
+ ⚠ ON THE CUSTOMER TOPIC THE FLOW LEG IS A TRUE ZERO, not a missed read: `automation_engine`
1075
+ resolves `targetTable` out of `user_tables` only, so no flow can bind to that topic at all.
1076
+ The COLUMN leg (`field['automation']['urlField']`) still counts there, which is the half a
1077
+ customer column can actually carry.
1078
+
1079
  ⭐⭐ W41-T10 / R3 / C8. The `done-when`'s load-bearing clause is *"over the whole workspace,
1080
  not from a partial client list"*: the assembly's own `ws` holds this caller's stratum merged
1081
  with the views shared TO them, so a count taken from it would miss every private view every
 
1121
  return {}
1122
  lent = st if st is not None else session.runtime
1123
  memo_key = (str(getattr(session, "tenant", "") or ""), str(table_key))
1124
+ token = _usage_token(lent, ws_key)
1125
  if token is not None:
1126
  hit = _USAGE_MEMO.get(memo_key)
1127
  if hit and hit[0] == token:
1128
  return hit[1]
1129
  try:
1130
+ # ⚠ THE HANDLE AND THE NAME ARE BOTH HANDED IN, never rebuilt from `table_key`: the store
1131
+ # key the calling assembly closed over is the one this database's strata actually live
1132
+ # under, and a second spelling of it is a second thing to keep in step. A lend passes a
1133
+ # workspace document straight through to the runtime (a lend serves only `user_tables` and
1134
+ # `object_shares`), so this is the tenant's own document either way.
1135
+ ws_doc = ws_st.get(ws_key) or {}
1136
  except Exception: # noqa: BLE001
1137
  return {}
1138
  try:
 
1307
  # `dict(f, source=…)` copies for the shared stratum but passes the rest through by reference,
1308
  # and `_usage_field_corpus` hands those same objects back. Mutating one would write a count
1309
  # into a definition the next reader shares.
1310
+ # β›” `agg` belongs to lanes B and D; C8 is explicit that an absent key means "not built yet".
1311
+ # ⭐⭐ W42-T14 / C4 β€” `class` NOW RIDES BESIDE IT, and the pair is the contract. `class` shipped
1312
+ # on `customer_data` with W41-T01 and stopped at that fence, so a `ut_*` grid sent `usage` with
1313
+ # no `class` while the customer grid sent `class` with no `usage` β€” and
1314
+ # `filter-kit/fieldClass.ts::deleteImpactTitle(fc, usage)` composes its warning as two
1315
+ # independent halves and DROPS whichever argument is null. Both live readers (`ColumnMenu`,
1316
+ # `FieldsHidePanel`) pass both. So each surface was rendering half a sentence with every gate on
1317
+ # both sides green, which is [[two-lanes-one-contract-dead-feature]] wearing a third face.
1318
  #
1319
  # ⚠ LENIENT, LIKE EVERY OTHER DISPLAY READ ON THIS ASSEMBLY, and C8's absent-key polarity is
1320
  # what makes degrading safe: a client renders nothing for a missing `usage` rather than a
 
1323
  # ⚠ A COPY OF THE BAG, because `_field_usage` MEMOISES its answer: handing the memo's own dict
1324
  # out would let anything downstream write into the number the next request reads.
1325
  try:
1326
+ _usage = _field_usage(session, table_key, fields, defn,
1327
+ ops.st, ops.table_key, st=st)
1328
  except Exception: # noqa: BLE001
1329
  _usage = {}
1330
  if _usage:
1331
  fields = [dict(f, usage=dict(_usage[f["key"]]))
1332
  if isinstance(f, dict) and _usage.get(f.get("key")) else f
1333
  for f in fields]
1334
+ # ⭐⭐ W42-T14 / C4 β€” **THE THREE BADGES, THE CHEAP DIRECTION.** `field_classes` is O(1) in
1335
+ # store reads for the whole list (one `object_shares` read via `grant_records`, one
1336
+ # `<key>__shared` read for the value stratum) and this is the only line on a `ut_*` grid that
1337
+ # calls it.
1338
+ #
1339
+ # ⚠ THE TWO KEYS ARE THE SAME STRING HERE AND THAT IS NOT A TYPO. On the customer topic the
1340
+ # bucket (`customer_table_workspace`) and the grant topic (`customer_data`) are different
1341
+ # names; on a user table both are `table_key` itself, which is what `delete_shared_field`
1342
+ # already spells three lines apart (`shared_overlay.fields(table_key)` and
1343
+ # `grant_topic=table_key`) and what `_ut_shared_fields` passes as `shared_key=table_key`.
1344
+ #
1345
+ # ⚠ `st=st` IS THE LEND, AND IT IS SAFE ON A NON-LENDABLE BUCKET. `grant_records` reads
1346
+ # `object_shares`, which IS lendable, so the badges ride the document this pass already holds
1347
+ # (the D-214 shape). `_shared_value_keys` then reads `<key>__shared`, which is NOT in
1348
+ # `_LENDABLE` -- and `_Lent.get`'s first branch forwards exactly that case straight to the
1349
+ # runtime rather than answering empty, which is checked in `verify_field_row` rather than
1350
+ # assumed: a lend that swallowed it would make every `values` badge read `personal` under a
1351
+ # lenient try, which is this ticket's own failure class.
1352
+ #
1353
+ # β›” NO `strata` MAP IS LENT, DELIBERATELY, AND THE ABSENCE IS THE HONEST ANSWER. W42-T47 gates
1354
+ # its behaviour change on the stratum being ASSERTED by the caller that did the reading, and
1355
+ # a guessed `personal` would MOVE A PERMISSION β€” `user_tables.delete_field_refusal` reads
1356
+ # `bag['owner']` to decide DELETE. This assembly cannot assert one: `workspace_wire` returns
1357
+ # the contract and this account's fork already merged into one list with no record of which
1358
+ # document each entry came out of. What it CAN say is not needed either: `_ut_shared_fields`
1359
+ # only ADDS keys the list does not already have, never replaces one, so no fork with a copied
1360
+ # `shared` mark is created here and `field_stratum`'s per-key fallback answers correctly. An
1361
+ # unlent map is today's answer plus the new member, which is exactly T47's designed fallback.
1362
+ #
1363
+ # ⚠ A NEW DICT PER COLUMN, NEVER AN IN-PLACE STAMP β€” the same rule as `usage` above and for a
1364
+ # sharper reason: `class` carries THIS viewer's `sharedBy` and `owner`, and `_ut_shared_fields`
1365
+ # passes non-shared entries through BY REFERENCE, so an in-place stamp would write one
1366
+ # account's answer into a definition the next reader shares.
1367
+ # ⚠ LENIENT AND ABSENT-KEY, like every other display read on this assembly: a registry that
1368
+ # will not open costs the badges and not the grid, and a client renders nothing for a missing
1369
+ # `class` rather than a wrong badge.
1370
+ try:
1371
+ from core import field_permissions as _fp
1372
+ _classes = _fp.field_classes(fields, session.uname, table_key=table_key,
1373
+ grant_topic=table_key, st=st)
1374
+ fields = [dict(f, **{"class": _classes[f["key"]]})
1375
+ if isinstance(f, dict) and _classes.get(f.get("key")) else f
1376
+ for f in fields]
1377
+ except Exception: # noqa: BLE001
1378
+ pass
1379
  # ⭐⭐ C8's `descriptionEdited`, AND IT CLOSES A CONSUMER THAT WAS ALREADY WRITTEN.
1380
  # W41-T11 built the producer (`user_tables.description_edited`, R19's custody mark scoped to the
1381
  # description) and correctly stopped at its own fence, which is one core file. Measured across
 
2680
  return {"deleted": fkey}
2681
 
2682
 
2683
+ #: ⭐��� W42-T28 β€” THE SENTENCES THE BULK DOOR SAYS **FOR ITSELF**, and why they are not next door.
2684
+ #:
2685
+ #: β›” NONE OF THESE IS A RIGHTS REFUSAL, so none of them belongs in `_delete_field_sentence`. That
2686
+ #: function renders `user_tables.delete_field_refusal`'s stable codes and nothing else, which is
2687
+ #: C2's *"no surface re-implements either test"* read the other way round: a door that folded its
2688
+ #: own execution outcomes into the rights renderer would make the two indistinguishable to the next
2689
+ #: reader, and the first person to add a code there would be writing a second opinion about who may
2690
+ #: delete what. These four are outcomes of the EXECUTOR or of this door's read wall.
2691
+ #:
2692
+ #: β›” STANDING RULE 2 β€” NO EM DASH AND NO EN DASH. Every one of these reaches a toast beside a
2693
+ #: column name, so they are user-facing copy; they are written to read naturally without the
2694
+ #: punctuation rather than having it stripped out afterwards.
2695
+ _BULK_DELETE_SENTENCES = {
2696
+ "unknown_field": ("that column is not on this database. It may already have been removed, so "
2697
+ "reload and check before trying again"),
2698
+ "field_hidden": ("this database has no column by that name that you may remove"),
2699
+ "last_field": ("a database must keep at least one column, so this one cannot be removed. Add "
2700
+ "another column first, then remove this one"),
2701
+ "delete_failed": ("that column could not be removed. Reload the database and try again"),
2702
+ }
2703
+
2704
+
2705
+ def _bulk_delete_refusal(key, code):
2706
+ """One refused outcome, in the same shape a deleted one has: a key, a status, a machine code
2707
+ and a sentence. The code is what a client switches on; the sentence is what a person reads."""
2708
+ return {"key": key, "status": "refused", "code": code,
2709
+ "reason": _BULK_DELETE_SENTENCES.get(code, _BULK_DELETE_SENTENCES["delete_failed"])}
2710
+
2711
+
2712
+ def _contract_holds_field(ut, table_key, fkey, st):
2713
+ """Is `fkey` STILL a declared column of this database's contract? Asked only on the failure
2714
+ path, because it is a whole-document read and it separates two very different refusals:
2715
+ `user_tables.delete_field` answers False both for *"a database must keep at least one"* and for
2716
+ a key that is already gone (an ordinary link's reciprocal disappears when its source column
2717
+ does, so key B can vanish while key A of the same request is being deleted)."""
2718
+ fields = (ut.get(table_key, st=st) or {}).get("fields") or []
2719
+ return any(isinstance(f, dict) and str(f.get("key")) == str(fkey) for f in fields)
2720
+
2721
+
2722
+ @router.post("/tables/{table_key}/fields/delete")
2723
+ @router.delete("/tables/{table_key}/fields")
2724
+ def delete_fields(table_key: str, body: dict = Body(default=None),
2725
+ session: Session = Depends(require_session)):
2726
+ """⭐⭐ W42-T28 / CONTRACT C4 β€” **REMOVE N COLUMNS IN ONE CALL, AND ANSWER PER KEY.**
2727
+
2728
+ `{"keys": [...]}` in, `{"results": [{key, status, ...}, ...]}` out. Both a POST to
2729
+ `…/fields/delete` and a DELETE to `…/fields` reach this one handler, because a body on a DELETE
2730
+ is legal and unevenly supported by clients, and the two spellings must not become two doors.
2731
+
2732
+ β›” THIS IS NOT A LOOP OVER `delete_field`, AND THE DIFFERENCE IS THE OWNER'S BUG. Instruction 21
2733
+ of wave 41 was a column that *"reappeared three times"*: the singular route below deletes ONE
2734
+ stratum, the `user_tables` contract, and leaves the shared bucket, every other account's fork
2735
+ and the grant record alive for `migrate_legacy_fields` to promote straight back on the next
2736
+ read. W41-T07 fixed that in `field_permissions.delete_field_everywhere`, which is the five-leg
2737
+ executor, and this door goes through it once per key. Multiplying the broken delete by N would
2738
+ have multiplied the resurrection by N.
2739
+
2740
+ β›” PARTIAL SUCCESS IS THE POINT, NOT A TOLERANCE. A key the caller may not delete is refused
2741
+ while the rest still go, so the outcomes are per key and there is no transaction around them.
2742
+ A field manager offers a multi-select over columns a person may own only some of; an
2743
+ all-or-nothing answer would make the one column they cannot touch block the nine they can, and
2744
+ a bare 200 would leave them believing all ten went.
2745
+
2746
+ β›” THE RIGHT IS NOT DECIDED HERE. `user_tables.delete_field_refusal` is C2's one pair and it
2747
+ answers both halves in one call (the decision, and the reason a person reads);
2748
+ `_delete_field_sentence` turns its code into this door's sentence, exactly as
2749
+ `delete_shared_field` already does. Spelling the owner-or-admin test a second time is how the
2750
+ two delete doors came apart in the first place.
2751
+
2752
+ ⚠ `deleted` IS EARNED BY A TRUTHY REMOVAL, NEVER BY THE ABSENCE OF A REFUSAL. `tombstoned` is
2753
+ always True and is deliberately not counted; a key that passed every wall and still moved
2754
+ nothing is reported refused, because a `deleted` that removed nothing reads exactly like a
2755
+ working delete and is the failure this ticket exists to end.
2756
+
2757
+ ⚠ NO `fields` LIST COMES BACK, and the omission is the answer. A list assembled here has been
2758
+ through neither `ut_assembly`'s hidden closure nor C4's `class`/`usage` stamps, so a client
2759
+ that trusted it would render columns C1 walls away. `rerender: True` is the instruction to
2760
+ refetch, which is what `delete_shared_field` ships for the same reason.
2761
+
2762
+ ⚠ `st=session.runtime` FOR BOTH EXECUTORS, NEVER THE WALL'S LEND. The last-column rule is
2763
+ evaluated against the field list as of the PREVIOUS key's deletion; answering it from a
2764
+ pre-write snapshot would refuse the wrong key of a request that empties a database.
2765
+ """
2766
+ # β›” NO `defs_only`, matching every other write wall in this file: a projected snapshot must
2767
+ # never reach a post-write read (contract C5), and this door writes.
2768
+ defn = _defn_or_refuse(session, table_key, scope_applied=True)
2769
+ ut = _ut()
2770
+ if not ut.is_user_table(table_key, st=session.runtime):
2771
+ raise err(400, "not_a_user_table",
2772
+ "only a user-created database has an editable schema. A connected source "
2773
+ "owns its own columns")
2774
+ raw = (body or {}).get("keys")
2775
+ if not isinstance(raw, list):
2776
+ raise err(400, "bad_keys", "send `keys`, the list of columns to remove")
2777
+ ordered = []
2778
+ for k in raw:
2779
+ k = str(k or "").strip()
2780
+ if k and k not in ordered:
2781
+ ordered.append(k)
2782
+ if not ordered:
2783
+ raise err(400, "bad_keys", "name at least one column to remove")
2784
+
2785
+ from core import field_permissions, shared_overlay
2786
+ declared = [f for f in (defn.get("fields") or []) if isinstance(f, dict)]
2787
+ contract_keys = {str(f.get("key")) for f in declared}
2788
+ # ⚠ Read ONCE for the whole request rather than per key: neither the hidden closure nor the
2789
+ # shared bucket can change under us mid-request, and both are whole-document reads.
2790
+ hidden = _ut_hidden(session, table_key, declared)
2791
+ # β›” AND THE LENIENT BRANCH REMEMBERS THAT IT FAILED, which the display reads on this
2792
+ # assembly deliberately do not. An unreadable bucket that silently became `{}` would report a
2793
+ # tenant-wide column as `unknown_field` β€” *"that column is not on this database"* β€” which is a
2794
+ # confident false statement about a destructive act, and the person would go looking for who
2795
+ # else deleted it. A read that did not happen answers "try again", not "it is not there".
2796
+ bucket_read = True
2797
+ try:
2798
+ shared_defs = shared_overlay.fields(table_key, st=session.runtime) or {}
2799
+ except Exception: # noqa: BLE001
2800
+ shared_defs, bucket_read = {}, False
2801
+
2802
+ results = []
2803
+ landed = []
2804
+ for key in ordered:
2805
+ field = next((f for f in declared if str(f.get("key")) == key), None)
2806
+ if field is None and isinstance(shared_defs.get(key), dict):
2807
+ # A tenant-wide column lives in `<key>__shared`, a document the contract cannot see.
2808
+ field = shared_defs[key]
2809
+ if field is None:
2810
+ results.append(_bulk_delete_refusal(
2811
+ key, "unknown_field" if bucket_read else "delete_failed"))
2812
+ continue
2813
+ # ⭐⭐ W36-T21's wall, per key. An account that cannot SEE a column must not be able to
2814
+ # delete it for the whole tenant. The sentence is delete-flavoured on purpose: the schema
2815
+ # wall's own says "that you may edit", which would be the server explaining the wrong rule.
2816
+ if key in hidden:
2817
+ results.append(_bulk_delete_refusal(key, "field_hidden"))
2818
+ continue
2819
+ refusal = ut.delete_field_refusal(
2820
+ table_key, key, session.uname, session.admin, session.runtime,
2821
+ field=field, grant_topic=table_key)
2822
+ if refusal is not None:
2823
+ results.append({"key": key, "status": "refused", "code": refusal,
2824
+ "reason": _delete_field_sentence(
2825
+ refusal, str(field.get("createdBy") or ""))})
2826
+ continue
2827
+ # ⚠ ONE `try` PER KEY, and that is what makes partial success real rather than claimed: a
2828
+ # store that fails on key 3 must not cost keys 4 and 5 their turn, and must not turn a
2829
+ # request that already deleted keys 1 and 2 into a bare 500 the client will repeat.
2830
+ try:
2831
+ dropped = False
2832
+ if key in contract_keys:
2833
+ dropped = bool(ut.delete_field(table_key, key, st=session.runtime))
2834
+ if not dropped and _contract_holds_field(ut, table_key, key, session.runtime):
2835
+ results.append(_bulk_delete_refusal(key, "last_field"))
2836
+ continue
2837
+ removed = field_permissions.delete_field_everywhere(
2838
+ f"{table_key}_table_workspace", table_key, table_key, key,
2839
+ st=session.runtime)
2840
+ except Exception: # noqa: BLE001
2841
+ results.append(_bulk_delete_refusal(key, "delete_failed"))
2842
+ continue
2843
+ if not (dropped or removed.get("shared") or removed.get("personal")):
2844
+ results.append(_bulk_delete_refusal(key, "delete_failed"))
2845
+ continue
2846
+ landed.append(key)
2847
+ results.append({"key": key, "status": "deleted", "contract": dropped,
2848
+ "removed": removed})
2849
+
2850
+ if landed:
2851
+ _refresh_relations(session)
2852
+ return {"ok": True, "rerender": True, "results": results, "deleted": landed,
2853
+ "refused": [r["key"] for r in results if r["status"] == "refused"]}
2854
+
2855
+
2856
  @router.delete("/tables/{table_key}/rows/{rid}")
2857
  def delete_row(table_key: str, rid: str, session: Session = Depends(require_session)):
2858
  # ⭐⭐ W31 QA β€” ONE SNAPSHOT FOR THE WHOLE DELETE, and the owner reported what it cost.
platform/aios_grid.py CHANGED
@@ -339,9 +339,92 @@ def _clean_permissions(raw):
339
  #: drift risk this file's docstring names. The charset says which characters may appear; the
340
  #: engine says what they mean. `_quotes_balanced` below is the one structural rule the quote
341
  #: character brings with it.
342
- _FORMULA_CHARS = re.compile(r"^[\w\s{}()+\-*/.,<>=!^&\"]*$")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
343
  _FORMULA_REF = re.compile(r"\{([^{}]*)\}")
344
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
345
 
346
  def _quotes_balanced(s):
347
  """An even number of `"` β€” the structural half of string support.
@@ -436,6 +519,32 @@ def _clean_formula(raw, valid_keys=None):
436
  return None
437
  if not _quotes_balanced(s):
438
  return None
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
439
  refs = _FORMULA_REF.findall(s)
440
  leftover = _FORMULA_REF.sub("", s)
441
  if "{" in leftover or "}" in leftover: # unbalanced / nested braces
@@ -606,6 +715,152 @@ def cohort_cells(cohorts, allowed_pids=None):
606
  return {pid: {COHORT_COLUMN: ', '.join(names)} for pid, names in cells.items()}
607
 
608
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
609
  def clean_measure_field(raw, offered):
610
  """Validate one UNTRUSTED formula-measure field (owner item 7) against the caller's OFFER.
611
 
@@ -1921,7 +2176,37 @@ def _clean_display(raw, valid_keys):
1921
  #: id happened to be 'folders'. (2) Folder placement is a per-user ORGANISING act, not part of
1922
  #: what a view IS: keeping it out of the view config means duplicating or exporting a view does
1923
  #: not drag a folder reference along with it. One map, one home, both surfaces.
1924
- FOLDER_SURFACES = {"views", "cohorts"}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1925
  MAX_FOLDERS = 60
1926
  MAX_FOLDER_NAME = 80
1927
 
@@ -2114,8 +2399,12 @@ def clean_item_folders(raw, folders, valid_ids):
2114
  # scrubbed here on the way back out, so the mark would be stored and instantly lost:
2115
  # the two halves are ONE change and shipping either alone is worse than shipping
2116
  # neither ([[lost-write-looks-like-failed-read]]).
2117
- if item_id in (valid_ids or {}).get(surface, ()) and (fid == ROOT_PLACEMENT
2118
- or fid in fids):
 
 
 
 
2119
  ok[item_id[:120]] = fid
2120
  if ok:
2121
  out[surface] = ok
 
339
  #: drift risk this file's docstring names. The charset says which characters may appear; the
340
  #: engine says what they mean. `_quotes_balanced` below is the one structural rule the quote
341
  #: character brings with it.
342
+ #: ⭐⭐ WAVE 42 G7 (2026-08-25) β€” THE SAME SCAR, WIDENED IN THE SAME CHANGE THIS TIME.
343
+ #:
344
+ #: The client engine gained REGEX_EXTRACT, REGEX_REPLACE, SUBSTITUTE, FIND, SWITCH, DATEADD,
345
+ #: DATETIME_DIFF and DATETIME_FORMAT. Each added character below is admitted because a token
346
+ #: the client's tokenizer parses would otherwise die here:
347
+ #:
348
+ #: ' a SINGLE-QUOTED literal. Airtable's own documentation spells every unit and date
349
+ #: format that way -- DATETIME_DIFF({a}, {b}, 'days') -- and a user pastes what the
350
+ #: documentation prints. Without this, EVERY date function is refused on save.
351
+ #: [ ] a regex character class, the commonest construct there is: "[0-9]+".
352
+ #: | regex alternation.
353
+ #: ? regex optional, and the non-capturing group "(?:...)".
354
+ #: \ regex escapes: \d \s \. \w.
355
+ #: : "(?:...)", and a class such as "[a-z:]".
356
+ #: @ SUBSTITUTE/FIND over an email or a URL, the canonical use of both.
357
+ #:
358
+ #: ⚠ AND THREE THAT THE EIGHT DO NOT NEED, admitted because they are the SAME BUG already
359
+ #: sitting here unnoticed: `textFormat` in the client accepts "#,##0", "$#,##0.00" and "0%",
360
+ #: so `TEXT({x}, "0%")` parses client-side and is refused here TODAY. That is the 2026-08-03
361
+ #: failure still live for three format shapes, so:
362
+ #: # $ % the TEXT() number formats the client already implements. ($ doubles as the regex
363
+ #: end-anchor and % as a literal in text, so all three earn their place twice.)
364
+ #:
365
+ #: β›” `;` STAYS REFUSED, and the fields-contract gate asserts it. Nothing in the grammar needs
366
+ #: a statement separator, and it is the shape an injection attempt takes.
367
+ _FORMULA_CHARS = re.compile(r"^[\w\s{}()+\-*/.,<>=!^&\"'\[\]|?:\\#$%@]*$")
368
  _FORMULA_REF = re.compile(r"\{([^{}]*)\}")
369
 
370
+ #: Longest single string literal a formula may carry. A regex pattern is a string literal, and
371
+ #: an unbounded pattern reaching a regex engine in the tenant's ONE process is a denial of
372
+ #: service rather than a slow cell. 200 inside a 500-character formula is far above honest use.
373
+ MAX_FORMULA_LITERAL_LEN = 200
374
+
375
+ #: The catastrophic-backtracking SHAPE: a group whose body already carries an unbounded
376
+ #: quantifier, quantified again -- `(a+)+`, `(a*)*`, `(?:\d+)*`.
377
+ #:
378
+ #: β›” IT IS APPLIED TO STRING LITERALS ONLY, NEVER TO THE WHOLE EXPRESSION. `({a} + {b}) * 2`
379
+ #: has exactly this character shape and is ordinary arithmetic; scanning the whole source would
380
+ #: refuse it.
381
+ #:
382
+ #: ⚠ AND IT IS A STATIC, EARLY refusal, not the guarantee. A pattern assembled at run time --
383
+ #: `REGEX_EXTRACT({a}, "(x" & "+)+")`, or a pattern read out of another field -- is invisible
384
+ #: to any check here. The LOAD-BEARING bound is the client's `safeRegex`, which sees the actual
385
+ #: pattern at evaluation time and caps the SUBJECT too. This wall stops the obvious one early
386
+ #: and cheaply; it does not pretend to be the wall.
387
+ _NESTED_QUANT = re.compile(r"\((?:[^()\\]|\\.)*[*+](?:[^()\\]|\\.)*\)\??\s*[*+]")
388
+
389
+
390
+ def _string_literals(s):
391
+ """Every string literal's BODY, in order, or None if one is unterminated.
392
+
393
+ Mirrors the client tokenizer exactly: `"..."` and `'...'` are the same literal in two
394
+ spellings, a DOUBLED quote of the opening kind is one character of body, and a quote of the
395
+ OTHER kind inside is ordinary text. That last part is why this is a scanner and not a parity
396
+ count: `"Owner's report"` is one literal containing an apostrophe, and counting `'` would
397
+ refuse it.
398
+
399
+ ⚠ This is NOT the second grammar the module refuses to write. It answers one question --
400
+ where does a literal begin and end -- which is the same structural question `_quotes_balanced`
401
+ and the `{ref}` scan already answer. It assigns no MEANING to anything it finds.
402
+ """
403
+ out = []
404
+ i = 0
405
+ n = len(s)
406
+ while i < n:
407
+ ch = s[i]
408
+ if ch not in ('"', "'"):
409
+ i += 1
410
+ continue
411
+ j = i + 1
412
+ body = []
413
+ while True:
414
+ if j >= n:
415
+ return None # unterminated
416
+ if s[j] == ch:
417
+ if j + 1 < n and s[j + 1] == ch:
418
+ body.append(ch)
419
+ j += 2
420
+ continue
421
+ break
422
+ body.append(s[j])
423
+ j += 1
424
+ out.append("".join(body))
425
+ i = j + 1
426
+ return out
427
+
428
 
429
  def _quotes_balanced(s):
430
  """An even number of `"` β€” the structural half of string support.
 
519
  return None
520
  if not _quotes_balanced(s):
521
  return None
522
+ # ⭐⭐ WAVE 42 G7 β€” the regex bound, and it runs at READ TIME TOO, deliberately.
523
+ #
524
+ # Every other refusal in this function is split write/read because a `{ref}`'s validity
525
+ # CHANGES with the world: a column referenced today can be deleted tomorrow, and refusing
526
+ # then would vaporise a stored column. A string literal's SHAPE is intrinsic to the
527
+ # expression and cannot become invalid later, so there is no stored-and-later-invalid case
528
+ # for the split to protect. Applying it both ways is what makes it reach the user-tables
529
+ # door, which calls this validator with `valid_keys=None` on WRITE as well as on read
530
+ # (core/user_tables.py::_clean_field) -- a write-only gate would simply miss `ut_*`.
531
+ #
532
+ # ⚠ THE TWO LEGS ARE SCOPED DIFFERENTLY, and the difference is data loss.
533
+ # The SHAPE test is safe everywhere: no formula written before today contains `"(a+)+"`,
534
+ # so it can only fire on something new. The LENGTH cap is not: a formula stored yesterday
535
+ # could carry a 250-character message literal and still sit under MAX_FORMULA_LEN, and
536
+ # refusing it at read time does not blank a cell -- `user_tables` drops the whole COLUMN.
537
+ # So the cap applies only where a literal can BE a pattern, which is a formula that names
538
+ # a regex function at all. That is a substring test, not a second grammar.
539
+ literals = _string_literals(s)
540
+ if literals is None:
541
+ return None
542
+ regexy = 'REGEX_' in s.upper()
543
+ for lit in literals:
544
+ if regexy and len(lit) > MAX_FORMULA_LITERAL_LEN:
545
+ return None
546
+ if _NESTED_QUANT.search(lit):
547
+ return None
548
  refs = _FORMULA_REF.findall(s)
549
  leftover = _FORMULA_REF.sub("", s)
550
  if "{" in leftover or "}" in leftover: # unbalanced / nested braces
 
715
  return {pid: {COHORT_COLUMN: ', '.join(names)} for pid, names in cells.items()}
716
 
717
 
718
+ # --- W42-T20: THE ROUTE PROJECTION COLUMN (owner instructions 7 + 19, R9/R20/R23, C11) -------
719
+ #
720
+ # ⭐⭐ THE SHAPE IS `cohort_field` / `cohort_cells`, FLAG FOR FLAG, AND THAT IS DELIBERATE: the
721
+ # grouping behaviour this column exists for is FREE only in that shape. `useVisibleRows::groupRows`
722
+ # fans a row out per element for a `multi` (or `multiselect`) field and it does so with
723
+ # `cell.split(",")`, so the value is a COMMA-JOINED STRING and nothing else can be substituted.
724
+ #
725
+ # β›”β›” THE KEY IS NOT DECLARED HERE, IT IS PASSED IN. C11 fixes the literal at
726
+ # `routes_customers.ROUTE_PROJECTION_KEY`, because `_mark_offerability` exempts this column BY KEY
727
+ # and two spellings of one key is the failure C11 was written about. `platform/` cannot import the
728
+ # API layer (layers point one way), so the caller hands the key down rather than this module
729
+ # holding a second copy of it.
730
+ #
731
+ # β›”β›” AND THE APPEND IS NOT HERE EITHER. `fields_from_workspace` appends `cohort_field()` for every
732
+ # grain that calls it, PRODUCT GRIDS INCLUDED; this column is appended by exactly one caller,
733
+ # `routes_customers.grid_assembly`. That absence of a call is the mechanism by which `product_data`
734
+ # does not offer this column at all: nothing on that grain builds route definitions and nothing on
735
+ # that grain calls either of these two functions.
736
+
737
+
738
+ def _route_label(fkey, defn):
739
+ """The route's name AS THE CELL SHOWS IT, which is the name minus any comma.
740
+
741
+ ⚠ The COMMA is the separator the client splits on to group a record into every route it is
742
+ on, so it cannot also occur inside a name. Route labels are free text ("North loop, Tuesday"
743
+ is a name somebody will type), so a comma is replaced here rather than left to break the split
744
+ silently: one group called "North loop" and another called "Tuesday" would be two routes that
745
+ do not exist. The cost is cosmetic and confined to the cell; the route listing still shows the
746
+ name the person typed.
747
+ """
748
+ return str((defn or {}).get('label') or fkey or '').replace(',', ' ').strip()
749
+
750
+
751
+ def route_projection_field(key, defs=None, label='Routes'):
752
+ """The derived column listing the routes a record is on, one descriptor per request.
753
+
754
+ ⭐ `source: 'odoo'` is doing the same ONE job it does on `cohort_field` and it is not
755
+ provenance: the client keys editability off `source == 'overlay'` and `_cl_handle_grid_event`
756
+ accepts cell writes only for overlay keys, so 'odoo' is what makes this column READ-ONLY at
757
+ both ends. It is a mechanism and not a UI decision, which is why it is stated here rather than
758
+ left to a renderer. `derived: True` stops the column menu calling it a source field.
759
+
760
+ ⚠ IT IS PRE-SET IN THE SENSE THAT NO PERSON MADE IT, AND THAT IS NOT A BADGE ON THE WIRE.
761
+ The descriptor carries no `createdBy`, which is what `field_permissions.field_origin` WOULD
762
+ answer `"preset"` from -- and it is never asked, because the one caller appends this column
763
+ AFTER the badge pass (`class`), after `usage` and after `offerable`, so the served entry
764
+ carries none of those three keys. Each of them is absent-means-nothing by design, so a client
765
+ renders no badge rather than a wrong one. The clause a reader should observe for read-only-ness
766
+ is `source != 'overlay'`, above, which is a mechanism both ends already enforce.
767
+
768
+ ⚠ `filterable: False`, for `cohort_field`'s reason exactly. Text ops over a joined string
769
+ almost work and disagree at the edges (`contains "North"` also matches "North loop extra"),
770
+ and a filter that is nearly right is worse than one that is absent. β›” THAT DOES NOT CONTRADICT
771
+ `routeOwners`: the replacement is a CONDITION (`Where [Route author] ...`) reading the map
772
+ below, exactly as `cohort_field`'s replacement is the `Where [Cohort]` condition and not a text
773
+ op on its own joined string.
774
+
775
+ ⭐⭐ `routeOwners` IS THE SIDE CHANNEL FOR `createdBy`, AND ITS DERIVATION RULE IS PART OF THE
776
+ CONTRACT. Each cell entry is `<label> - <position>`, so the author cannot be written into the
777
+ entry without changing the format the owner asked for. It rides beside it instead, as
778
+ `{<label as it appears in the cell>: <createdBy>}`. A reader recovers the label from an entry
779
+ by stripping a trailing ` - <digits>` ANCHORED AT THE END (`/ - \\d+$/`): a position is always
780
+ digits, so that stays exact even for a route whose own name contains " - ". Named here so the
781
+ later filter ticket reads THIS key instead of inventing a second one, which is
782
+ [[two-lanes-one-contract-dead-feature]] with a map instead of a flag.
783
+
784
+ ⚠ TWO ROUTES WITH ONE LABEL RESOLVE TO NO AUTHOR RATHER THAN TO THE WRONG ONE. The map is
785
+ keyed by what the cell shows, and a duplicate label cannot name one author; a filter offering
786
+ a confident wrong name is worse than one offering none.
787
+
788
+ ⚠ THE MAP IS BUILT FROM THE **WALLED** defs the caller passes, so it can never name a route
789
+ this viewer was not granted. Absent when empty, so a viewer with no grants receives no map at
790
+ all rather than an empty one to reason about.
791
+ """
792
+ owners = {}
793
+ for fkey, defn in (defs or {}).items():
794
+ name = _route_label(fkey, defn)
795
+ who = str((defn or {}).get('createdBy') or '').strip()[:80]
796
+ if name in owners and owners[name] != who:
797
+ owners[name] = ''
798
+ else:
799
+ owners.setdefault(name, who)
800
+ return {
801
+ 'key': key, 'label': label, 'type': 'text', 'source': 'odoo',
802
+ 'default': False, 'filterable': False, 'derived': True, 'multi': True,
803
+ 'note': 'Every saved route this customer is a stop on, written as "Route name - position" '
804
+ 'and sorted by route name. A route holds a SET of stops, so grouping by this '
805
+ 'column puts a customer under EVERY route they are on, and the group counts '
806
+ 'therefore add up to more than the record count, which stays the number of '
807
+ 'distinct customers. It names only the routes you have been granted. Read-only: '
808
+ 'a position changes only when somebody plans that route again.',
809
+ **({'routeOwners': owners} if owners else {}),
810
+ }
811
+
812
+
813
+ def route_projection_cells(key, defs, shared, pids):
814
+ """`{pid: {key: 'North loop - 3, South loop - 11'}}` for the rows named by `pids`.
815
+
816
+ `defs` is `{route_key: definition}` ALREADY NARROWED BY THE VIEWER'S GRANT WALL, and that
817
+ narrowing is the whole security property: ORing across every route on the tenant would tell a
818
+ reader that a route they hold no grant on exists ([[enriching-a-wall-leaks-what-it-judges]]).
819
+ This function projects what it is given and never widens it, so the wall is testable by handing
820
+ it walled defs and then unwalled defs and comparing the two answers.
821
+
822
+ Built per render from the CALLER'S OWN walled view and handed to `rows_from_pool` as `derived`,
823
+ never merged into the cached pool rows: those are shared across users and carry no `uname`, so
824
+ stamping one viewer's route visibility onto them would serve it to everybody else on the next
825
+ render.
826
+
827
+ ⚠ `shared` IS STRING-KEYED AND THE RESULT IS INT-KEYED, because the two dicts are read by
828
+ different halves of `rows_from_pool` (`overlays.get(str(pid))` against `derived.get(pid)`).
829
+ Inverting them yields a blank column, which is indistinguishable from the grant wall working.
830
+
831
+ ⚠ `pids` IS THE ROW WALL, INHERITED. It is the set the caller has already narrowed with
832
+ `apply_row_scope`, so iterating it rather than the cells dict means a route stop belonging to
833
+ the other business unit has no row to attach itself to.
834
+
835
+ ⚠ A record on no visible route gets NO ENTRY, not an empty one: `rows_from_pool` already writes
836
+ `''` for a derived key it has no value for, and `is empty` on a text column is the question
837
+ somebody will ask of it.
838
+ """
839
+ order = sorted((defs or {}).items(),
840
+ key=lambda kv: (_route_label(kv[0], kv[1]).lower(), str(kv[0])))
841
+ out = {}
842
+ for pid in (pids or ()):
843
+ cells = (shared or {}).get(str(pid)) or {}
844
+ parts = []
845
+ for fkey, defn in order:
846
+ # β›”β›” THE MEMBERSHIP TEST IS `_patch_route_ranks::_held`'s, CLAUSE FOR CLAUSE, AND IT
847
+ # IS NOT MERELY "NON-EMPTY". That function skips `None` and `''` and then does
848
+ # `int(str(cell).strip())` inside a `try`, so a cell holding junk is NOT a stop. Read
849
+ # off the code rather than off the prose, because two spellings of one membership rule
850
+ # is [[two-lanes-one-contract-dead-feature]] with a predicate instead of a key: the
851
+ # looser one here would paint `North loop - False` on a row the route planner and the
852
+ # write door both agree is not on that route. There is no reverse index to check it
853
+ # against either -- `route.stops` is a COUNT, not a pid list.
854
+ try:
855
+ rank = int(str(cells.get(fkey)).strip())
856
+ except (TypeError, ValueError):
857
+ continue
858
+ parts.append(_route_label(fkey, defn) + ' - ' + str(rank))
859
+ if parts:
860
+ out[pid] = {key: ', '.join(parts)}
861
+ return out
862
+
863
+
864
  def clean_measure_field(raw, offered):
865
  """Validate one UNTRUSTED formula-measure field (owner item 7) against the caller's OFFER.
866
 
 
2176
  #: id happened to be 'folders'. (2) Folder placement is a per-user ORGANISING act, not part of
2177
  #: what a view IS: keeping it out of the view config means duplicating or exporting a view does
2178
  #: not drag a folder reference along with it. One map, one home, both surfaces.
2179
+ #: ⭐⭐ W42-T23 / AMENDMENT A21 β€” `routes` IS THE THIRD SURFACE, AND WIDENING THIS SET IS THE
2180
+ #: WHOLE OF THE STORE-SIDE CHANGE. Both `clean_folders` and `clean_item_folders` iterate exactly
2181
+ #: this set and DROP anything outside it, and `core/grid_events.py` refuses a folder event whose
2182
+ #: `surface` is not in it (`surface_unknown`). So before this line a route's placement could not
2183
+ #: be written, could not be read back, and the write door said the sidebar did not exist. One
2184
+ #: constant, three refusals.
2185
+ #: ⚠ THE VIEWS RAIL IS UNTOUCHED BY THIS, and it was checked rather than assumed:
2186
+ #: `workspace_wire` folds ONLY the literal `'cohorts'` surface into `views` at serve time (it
2187
+ #: names the string, it does not iterate this set), and it emits `_folders['views']` alone. A
2188
+ #: routes folder is therefore invisible to the views rail by construction, not by luck.
2189
+ FOLDER_SURFACES = {"views", "cohorts", "routes"}
2190
+
2191
+ #: β›”β›” SURFACES WHOSE ITEMS ARE TENANT-WIDE, SO "IS THIS ITEM YOURS" HAS NO ANSWER TO GIVE.
2192
+ #:
2193
+ #: `clean_item_folders` drops a placement whose ITEM is not in the caller-supplied `valid_ids`.
2194
+ #: That test is right for views and cohorts, which are per-user objects. A route-order column is
2195
+ #: tenant-wide (`routes_customers.ROUTE_KEY_PREFIX`'s own note: the other two created-column
2196
+ #: namespaces are per user, "this one is tenant-wide"), so no per-user id set describes it.
2197
+ #:
2198
+ #: β›” AND THE EXEMPTION IS LOAD-BEARING, NOT TIDINESS. `grid_events`'s `_own_ids(surface, ws)`
2199
+ #: reads `if sfc == 'views': ... return cohorts` β€” an ELSE, not a lookup. The moment `routes`
2200
+ #: joined the set above, every folder event on ANY surface began handing this function the
2201
+ #: caller's COHORT ids as the legal item set for `routes`, and a route key is never a cohort id.
2202
+ #: Every stored route placement would have been silently erased by the next unrelated folder
2203
+ #: rename, and the drag that wrote it would have reported success. `grid_events.py` is not this
2204
+ #: ticket's to edit; the surface it asks about is, so the answer is given here.
2205
+ #:
2206
+ #: ⚠ Nothing is fail-open: a placement on an exempt surface must STILL name a folder that exists
2207
+ #: (or `ROOT_PLACEMENT`), and its reader re-resolves the route key against the columns that
2208
+ #: reader may actually see. What is skipped is the ownership test alone.
2209
+ FOLDER_SURFACES_TENANT_WIDE = {"routes"}
2210
  MAX_FOLDERS = 60
2211
  MAX_FOLDER_NAME = 80
2212
 
 
2399
  # scrubbed here on the way back out, so the mark would be stored and instantly lost:
2400
  # the two halves are ONE change and shipping either alone is worse than shipping
2401
  # neither ([[lost-write-looks-like-failed-read]]).
2402
+ # ⭐⭐ W42-T23 β€” THE OWNERSHIP TEST IS SKIPPED ON A TENANT-WIDE SURFACE. See
2403
+ # `FOLDER_SURFACES_TENANT_WIDE` for why it has to be, and for what it does not relax:
2404
+ # the folder must still exist, or be the deliberate `ROOT_PLACEMENT`.
2405
+ owned = (surface in FOLDER_SURFACES_TENANT_WIDE
2406
+ or item_id in (valid_ids or {}).get(surface, ()))
2407
+ if owned and (fid == ROOT_PLACEMENT or fid in fids):
2408
  ok[item_id[:120]] = fid
2409
  if ok:
2410
  out[surface] = ok
platform/aios_grid_fields.json CHANGED
@@ -396,68 +396,6 @@
396
  "source": "odoo",
397
  "description": "Fisch pricelist price for this SKU. Blank when that list prices it nowhere."
398
  },
399
- {
400
- "key": "price_royal_1",
401
- "label": "Royal 1 price",
402
- "type": "currency",
403
- "source": "odoo",
404
- "description": "Royal 1 pricelist price for this SKU. Blank when that list prices it nowhere."
405
- },
406
- {
407
- "key": "price_royal_2",
408
- "label": "Royal 2 price",
409
- "type": "currency",
410
- "source": "odoo",
411
- "description": "Royal 2 pricelist price for this SKU. Blank when that list prices it nowhere."
412
- },
413
- {
414
- "key": "price_1",
415
- "label": "Price 1",
416
- "type": "currency",
417
- "source": "odoo",
418
- "default": false,
419
- "description": "Cheapest live price for this SKU, across active pricelists."
420
- },
421
- {
422
- "key": "unit_1",
423
- "label": "Unit 1",
424
- "type": "text",
425
- "source": "odoo",
426
- "default": false,
427
- "description": "Package label for Price 1. Blank means Odoo has no package reference for that price."
428
- },
429
- {
430
- "key": "price_2",
431
- "label": "Price 2",
432
- "type": "currency",
433
- "source": "odoo",
434
- "default": false,
435
- "description": "Second-cheapest live price for this SKU."
436
- },
437
- {
438
- "key": "unit_2",
439
- "label": "Unit 2",
440
- "type": "text",
441
- "source": "odoo",
442
- "default": false,
443
- "description": "Package label for Price 2."
444
- },
445
- {
446
- "key": "price_3",
447
- "label": "Price 3",
448
- "type": "currency",
449
- "source": "odoo",
450
- "default": false,
451
- "description": "Third-cheapest live price for this SKU."
452
- },
453
- {
454
- "key": "unit_3",
455
- "label": "Unit 3",
456
- "type": "text",
457
- "source": "odoo",
458
- "default": false,
459
- "description": "Package label for Price 3."
460
- },
461
  {
462
  "key": "price_fisch_t1",
463
  "label": "Fisch tier 1 price",
 
396
  "source": "odoo",
397
  "description": "Fisch pricelist price for this SKU. Blank when that list prices it nowhere."
398
  },
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
399
  {
400
  "key": "price_fisch_t1",
401
  "label": "Fisch tier 1 price",
platform/core/field_permissions.py CHANGED
@@ -26,6 +26,26 @@ FIELD_ORIGINS = ("preset", "user")
26
  FIELD_AUDIENCES = ("private", "users", "everyone")
27
  FIELD_VALUE_STRATA = ("shared", "personal")
28
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
29
  #: `permissions_from_grants`' edit vocabulary -> C1's audience vocabulary. The two answer the SAME
30
  #: question in different words (who can reach this column), so this map is the whole of the
31
  #: translation and there is no second derivation to drift from it
@@ -200,6 +220,82 @@ def field_origin(field):
200
  return "preset"
201
 
202
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
203
  def _shared_value_keys(table_key, st=None):
204
  """The columns of `table_key` whose VALUES are one tenant-wide stratum."""
205
  key = str(table_key or "").strip()
@@ -272,12 +368,24 @@ def grant_records(grant_topic, st=None):
272
 
273
 
274
  def field_class(field, viewer, grants=None, *, table_key=None, grant_topic=None,
275
- values_shared=None, st=None):
276
  """⭐⭐ W41-T01 / R5 / CONTRACT C1 β€” **THE ONE PRODUCER OF A FIELD'S THREE BADGES.**
277
 
278
- Returns `{origin, audience, sharedBy, values, owner}` and nothing else derives a badge
279
- independently. The five member spellings are C1's and they are the wire's: the payload key is
280
- `class`, its members are `origin`, `audience`, `sharedBy`, `values`, `owner`.
 
 
 
 
 
 
 
 
 
 
 
 
281
 
282
  `viewer` is a USERNAME STRING (`session.uname`), never a user dict β€” a dict compares unequal to
283
  every stored name, which would make `sharedBy` silently never match and `owner` never equal the
@@ -326,6 +434,19 @@ def field_class(field, viewer, grants=None, *, table_key=None, grant_topic=None,
326
  contract-declared one), else `personal`. This is R5's new information and it is INDEPENDENT of
327
  audience: a route column is `private` with `shared` values, Supplier is `everyone` with `shared`
328
  values, and a column you made is `private` with `personal` ones.
 
 
 
 
 
 
 
 
 
 
 
 
 
329
  ⚠ `values_shared` IS LENT BY THE CALLER because the key set is a MODULE-level fact
330
  (`product_data.SHARED_KEYS()`), and `core` never imports up. Absent, it is derived from
331
  `shared_overlay.fields(table_key)`, which is right for an overlay topic and blind to a
@@ -342,8 +463,45 @@ def field_class(field, viewer, grants=None, *, table_key=None, grant_topic=None,
342
  me = _uname(viewer)
343
 
344
  origin = field_origin(field)
 
 
 
 
 
 
 
 
 
 
 
345
  record = grants if isinstance(grants, dict) else _grant_record(
346
  key, table_key=table_key, grant_topic=grant_topic, st=st)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
347
  owner = _uname(record.get("owner")) or None
348
  entries = [e for e in (record.get("entries") or ()) if isinstance(e, dict)]
349
 
@@ -354,10 +512,19 @@ def field_class(field, viewer, grants=None, *, table_key=None, grant_topic=None,
354
  if _governed(field):
355
  audience = _AUDIENCE_FROM_EDIT.get(
356
  permissions_from_grants(entries).get("edit"), "private")
357
- elif values == "shared" or origin == "preset":
358
  # Ungoverned AND tenant-wide: the database's holders all hold this column. `origin` covers
359
  # a contract-declared column whose VALUES are per-user (a canonical Odoo column); the
360
  # `values` leg covers a shared-stratum column the contract never named.
 
 
 
 
 
 
 
 
 
361
  audience = "everyone"
362
  else:
363
  audience = "private"
@@ -372,13 +539,30 @@ def field_class(field, viewer, grants=None, *, table_key=None, grant_topic=None,
372
  if shared_by == me:
373
  shared_by = None
374
 
 
 
 
 
375
  return {"origin": origin, "audience": audience, "sharedBy": shared_by,
376
- "values": values, "owner": owner or _uname(field.get("createdBy")) or None}
 
377
 
378
 
379
  def field_classes(fields, viewer, *, table_key=None, grant_topic=None, values_shared=None,
380
- st=None):
381
- """`{field_key: <C1 bag>}` for a whole field list, on ONE registry read. See `grant_records`.
 
 
 
 
 
 
 
 
 
 
 
 
382
 
383
  ⚠ EVERY COLUMN GETS A BAG, INCLUDING ONE THE REGISTRY HAS NEVER HEARD OF: the missing record is
384
  substituted explicitly rather than left to `field_class` to re-read, which is what keeps the
@@ -389,6 +573,7 @@ def field_classes(fields, viewer, *, table_key=None, grant_topic=None, values_sh
389
  if values_shared is None:
390
  values_shared = _shared_value_keys(table_key, st=st)
391
  shared_keys = {str(k) for k in (values_shared or ())}
 
392
  out = {}
393
  for field in (fields or ()):
394
  if not isinstance(field, dict):
@@ -398,7 +583,7 @@ def field_classes(fields, viewer, *, table_key=None, grant_topic=None, values_sh
398
  continue
399
  out[key] = field_class(field, viewer, grants=records.get(key) or _empty_record(),
400
  table_key=table_key, grant_topic=topic,
401
- values_shared=shared_keys, st=st)
402
  return out
403
 
404
 
 
26
  FIELD_AUDIENCES = ("private", "users", "everyone")
27
  FIELD_VALUE_STRATA = ("shared", "personal")
28
 
29
+ #: ⭐⭐ W42-T47 / RULING R15 / CONTRACT C10 β€” WHICH STRATUM A DEFINITION WAS READ FROM.
30
+ #:
31
+ #: C10: *"`field_classes` reports, beside `{origin, audience, sharedBy, values, owner}`, WHICH
32
+ #: STRATUM the definition was read from, so the client sections on ownership without re-deriving
33
+ #: it."* The three are the three places a field definition can physically live in this codebase:
34
+ #:
35
+ #: * ``contract`` β€” the canonical contract file (`aios_grid_fields.json`) or a module's declared
36
+ #: columns. Nobody made it here; it is the same document for every account.
37
+ #: * ``shared`` β€” `shared_overlay`'s tenant-wide bucket (`<topic>_table_workspace__shared`),
38
+ #: which is where `mint_field` and `promote_field` put a definition. ONE document, read by
39
+ #: every account.
40
+ #: * ``personal`` β€” the reader's OWN member of the `<topic>_table_workspace` document. A
41
+ #: per-user definition: no other account ever receives it.
42
+ #:
43
+ #: β›” IT IS NOT `FIELD_VALUE_STRATA` WEARING A SECOND HAT, AND THE TWO MUST NOT BE COMPARED. That
44
+ #: tuple says where a column's VALUES live; this one says where its DEFINITION was read from. A
45
+ #: column can be `stratum='personal'` with `values='shared'` β€” that pair is R15's report, not R15's
46
+ #: bug (see `field_stratum`).
47
+ FIELD_DEFINITION_STRATA = ("contract", "shared", "personal")
48
+
49
  #: `permissions_from_grants`' edit vocabulary -> C1's audience vocabulary. The two answer the SAME
50
  #: question in different words (who can reach this column), so this map is the whole of the
51
  #: translation and there is no second derivation to drift from it
 
220
  return "preset"
221
 
222
 
223
+ def _grant_mark():
224
+ """The name of the wall's own mark, read from `perm_scope` and never re-spelled locally.
225
+
226
+ β›” `_governed`'s note forbids a second reader by name: *"Re-spelling `f.get('granted') is True`
227
+ locally would be a second reader of the mark, and a second reader is how the two come apart."*
228
+ The stratum fallback below needs the same mark, so it takes the CONSTANT rather than the
229
+ literal, and the two cannot drift apart on a rename.
230
+
231
+ ⚠ THE FAILURE DIRECTION IS DELIBERATE AND IS THE OPPOSITE OF `_governed`'S. `_governed`
232
+ degrades to `False` (not governed), which is right for a WALL question. Here an unresolvable
233
+ import must not tip a definition toward `personal`, because `personal` zeroes the grant record
234
+ in `field_class`; falling back to the mark's own spelling keeps the conservative answer
235
+ (`shared`, i.e. trust the registry) when `core.perm_scope` cannot be loaded at all.
236
+ """
237
+ try:
238
+ import core.perm_scope as perm_scope
239
+ return str(perm_scope.FIELD_GRANT_MARK)
240
+ except Exception: # noqa: BLE001
241
+ return "granted"
242
+
243
+
244
+ def field_stratum(field):
245
+ """⭐⭐ W42-T47 / R15 / C10 β€” THE **FALLBACK** DERIVATION OF WHICH STRATUM A DEFINITION CAME
246
+ FROM, for a caller that cannot lend the fact. See `FIELD_DEFINITION_STRATA`.
247
+
248
+ β›”β›” IT IS A FALLBACK AND NOT THE ANSWER, AND THE REASON IS THE WHOLE OF THIS TICKET: **NOTHING
249
+ ON A FIELD DEFINITION RECORDS WHICH DOCUMENT IT WAS READ FROM.** Every mark that looks like
250
+ evidence survives being COPIED OUT of that document:
251
+
252
+ * `routes_customers._merge_shared_fields` projects a shared definition as
253
+ `dict(f, source="overlay", shared=True)`;
254
+ * that merged list reaches `grid_events.field_upsert`, whose fork-minting branch is
255
+ `base = field_by_key[key]` then `field = {**base, 'note': ...}` β€” `{**base}` copies EVERY
256
+ key, `shared` and `granted` and `source` included;
257
+ * `TableStore.save_field` then writes that copy into THIS user's own workspace member.
258
+
259
+ So a personal fork of a tenant-wide route carries `shared: True` verbatim, and a mark-based
260
+ test calls it `shared`. That is R15's own reproduction (gabriel mints `route_x`; another
261
+ account forks it through Format or Summary), which is exactly the case this member exists to
262
+ report, so the mark test cannot be the producer of the answer.
263
+
264
+ β›” ADDING MORE MARKS DOES NOT RESCUE IT. `source == "overlay"` is copied by the same `{**base}`
265
+ and fails identically. A key-keyed store (the grant registry, `shared_overlay.fields()`
266
+ membership, the lent `values_shared`) fails the other way: it answers about whichever
267
+ definition of that key lives in ITS document, which on a fork is a DIFFERENT definition from
268
+ the dict in hand, so it can never report the conflict either.
269
+
270
+ ⚠ THE BLIND SPOT, STATED RATHER THAN HIDDEN: **this fallback cannot see a fork, and names one
271
+ `shared`.** A documented blind spot beats a silent one; the honest answer is lent by the
272
+ assembly that DID the reading, through `field_class(stratum=...)` / `field_classes(strata=...)`.
273
+
274
+ The marks are still the best available evidence for everything else, and the polarity matches
275
+ `field_origin`'s: unmarked plus a demonstrable author is `personal`, everything else `contract`.
276
+ """
277
+ if not isinstance(field, dict):
278
+ return "contract"
279
+ if field.get("shared") is True or field.get(_grant_mark()) is True:
280
+ return "shared"
281
+ if field_origin(field) == "user":
282
+ return "personal"
283
+ return "contract"
284
+
285
+
286
+ def _clean_stratum(value, field=None):
287
+ """One lent stratum, canonicalised, falling back to `field_stratum` on anything unrecognised.
288
+
289
+ β›” AN UNKNOWN TOKEN FALLS BACK RATHER THAN FAILING CLOSED TO `personal`. `personal` is not the
290
+ safe direction here: it ZEROES the grant record in `field_class`, so a typo in a lent map would
291
+ silently strip the owner and the audience off every column it named.
292
+ """
293
+ token = str(value or "").strip().lower()
294
+ if token in FIELD_DEFINITION_STRATA:
295
+ return token
296
+ return field_stratum(field)
297
+
298
+
299
  def _shared_value_keys(table_key, st=None):
300
  """The columns of `table_key` whose VALUES are one tenant-wide stratum."""
301
  key = str(table_key or "").strip()
 
368
 
369
 
370
  def field_class(field, viewer, grants=None, *, table_key=None, grant_topic=None,
371
+ values_shared=None, stratum=None, st=None):
372
  """⭐⭐ W41-T01 / R5 / CONTRACT C1 β€” **THE ONE PRODUCER OF A FIELD'S THREE BADGES.**
373
 
374
+ Returns `{origin, audience, sharedBy, values, owner, stratum}` and nothing else derives a badge
375
+ independently. The member spellings are C1's and C10's, and they are the wire's: the payload key
376
+ is `class`, its members are `origin`, `audience`, `sharedBy`, `values`, `owner`, `stratum`.
377
+
378
+ **stratum** β€” ⭐⭐ W42-T47 / R15 / C10, and it is the member the other five are now ANCHORED to.
379
+ `contract` | `shared` | `personal`: WHICH DOCUMENT this definition was read from. The client
380
+ sections on ownership (My fields / From my colleagues / Built in) from `stratum` plus `owner`
381
+ WITHOUT re-deriving either.
382
+ ⚠ IT IS **LENT BY THE CALLER**, for `values_shared`'s reason turned up one notch: not merely
383
+ that `core` never imports up, but that the fact is not present in ANY of this function's
384
+ inputs. Nothing on a definition records the document it came from, because every mark on it
385
+ survives being copied out of that document (`field_stratum` carries the proof and the copying
386
+ doors). Only the assembly that DID the reading knows, so it lends
387
+ `field_classes(strata={key: stratum})`, and absent that the derivation falls back to
388
+ `field_stratum`, whose blind spot is stated there rather than hidden here.
389
 
390
  `viewer` is a USERNAME STRING (`session.uname`), never a user dict β€” a dict compares unequal to
391
  every stored name, which would make `sharedBy` silently never match and `owner` never equal the
 
434
  contract-declared one), else `personal`. This is R5's new information and it is INDEPENDENT of
435
  audience: a route column is `private` with `shared` values, Supplier is `everyone` with `shared`
436
  values, and a column you made is `private` with `personal` ones.
437
+ β›”β›” W42-T47 / R15 β€” `values` AND `audience` KEEP READING GENUINELY DIFFERENT STORES, AND THEY
438
+ ARE STILL INCAPABLE OF DESCRIBING DIFFERENT DEFINITIONS. The independence is required (one is
439
+ membership of the shared-overlay stratum, the other is `shares.grants`), so it is not removed;
440
+ what is removed is the second opinion about WHICH DEFINITION is being described. `stratum` is
441
+ computed once, from the definition in hand, and both legs are anchored to it: the registry is
442
+ not consulted at all on a `personal` definition, and `values` no longer decides an audience for
443
+ one. R15's *"`Private` + `Shared values` is NOT a state to preserve, it IS the bug"* is
444
+ therefore answered by making the pair UNAMBIGUOUS rather than by suppressing either member: a
445
+ column whose cells come from the shared pool but whose definition is the reader's own now reads
446
+ `{stratum: 'personal', values: 'shared', audience: 'private', owner: <its own author>}`, which
447
+ is one coherent sentence and the exact fact the owner reported, instead of two badges that
448
+ contradict each other about who has this column.
449
+
450
  ⚠ `values_shared` IS LENT BY THE CALLER because the key set is a MODULE-level fact
451
  (`product_data.SHARED_KEYS()`), and `core` never imports up. Absent, it is derived from
452
  `shared_overlay.fields(table_key)`, which is right for an overlay topic and blind to a
 
463
  me = _uname(viewer)
464
 
465
  origin = field_origin(field)
466
+ # β›”β›” W42-T47 β€” AN **ASSERTED** STRATUM ANCHORS THE BAG; A GUESSED ONE REPORTS AND NOTHING MORE.
467
+ # `user_tables._field_badges` calls `field_class` on a RIGHTS path: `delete_field_refusal` reads
468
+ # `bag['owner']` and returns `NOT_FIELD_OWNER` on a mismatch, so anything that moves `owner`
469
+ # moves a delete. That caller lends no stratum, and the fallback derivation is a guess by its
470
+ # own docstring, so letting a guess re-source `owner` could hand somebody a delete they did not
471
+ # have. This ticket makes a REPORT honest; it moves no wall, and this line is where that
472
+ # promise is kept rather than asserted. A caller that KNOWS which document it read (C10's lent
473
+ # map) gets the anchored answer; every existing caller keeps today's behaviour byte for byte.
474
+ asserted = str(stratum or "").strip().lower() in FIELD_DEFINITION_STRATA
475
+ stratum = _clean_stratum(stratum, field)
476
+ anchored_personal = asserted and stratum == "personal"
477
  record = grants if isinstance(grants, dict) else _grant_record(
478
  key, table_key=table_key, grant_topic=grant_topic, st=st)
479
+ # β›”β›” W42-T47 / R15 / C10 β€” THE REGISTRY RECORD IS KEYED BY FIELD **KEY**, SO ON A PERSONAL
480
+ # DEFINITION IT DESCRIBES A DIFFERENT DEFINITION AND IS DROPPED ENTIRELY.
481
+ #
482
+ # `shares.field_oid(topic, key)` names a KEY, not a document. A grant record for `route_x` was
483
+ # written about the definition in the tenant-wide bucket; when the dict in hand came from the
484
+ # reader's own workspace member instead, those are two different definitions of one key, and
485
+ # `routes_customers._merge_shared_fields` makes that routine rather than exotic β€” its rule is
486
+ # `if k in have: continue`, so a reader holding ANY same-key entry silently keeps their own and
487
+ # never sees the shared one (that merge is W42-T46's, not this ticket's).
488
+ #
489
+ # Reading `owner`, `sharedBy` and `audience` off that record while reading `origin`, `values`
490
+ # and the marks off the personal dict is how ONE bag came to describe TWO definitions, which is
491
+ # R15's *"Gabriel created the Route and it ends up being MY field"* β€” the owner fact and the
492
+ # audience were answering about different documents. Zeroing the record here is what makes the
493
+ # anchoring STRUCTURAL: after this line there is no path by which a registry-derived member can
494
+ # describe a definition the `stratum` member does not name.
495
+ #
496
+ # ⚠ NO PERMISSION MOVES, AND IT IS CHECKED RATHER THAN REASONED β€” BUT NOT FOR THE REASON IT
497
+ # FIRST LOOKS LIKE. A fork carries `granted: True` copied verbatim, so a `personal` definition
498
+ # CAN be one the wall does consult the registry about; this arm is exactly where R15's fork
499
+ # lands. What makes it safe is that the wall reads the registry ITSELF
500
+ # (`perm_scope.field_grant_hidden` -> `shares.role_for`) and never reads this bag, so zeroing
501
+ # here changes the REPORT and nothing else. The report is the thing that was wrong: a personal
502
+ # definition's grant record describes a document the reader is not reading.
503
+ if anchored_personal:
504
+ record = _empty_record()
505
  owner = _uname(record.get("owner")) or None
506
  entries = [e for e in (record.get("entries") or ()) if isinstance(e, dict)]
507
 
 
512
  if _governed(field):
513
  audience = _AUDIENCE_FROM_EDIT.get(
514
  permissions_from_grants(entries).get("edit"), "private")
515
+ elif not anchored_personal and (values == "shared" or origin == "preset"):
516
  # Ungoverned AND tenant-wide: the database's holders all hold this column. `origin` covers
517
  # a contract-declared column whose VALUES are per-user (a canonical Odoo column); the
518
  # `values` leg covers a shared-stratum column the contract never named.
519
+ #
520
+ # β›” W42-T47 β€” THE `stratum != "personal"` GUARD IS THIS TICKET'S BEHAVIOUR CHANGE, AND IT
521
+ # FIRES ON EXACTLY ONE SHAPE: a definition read from the reader's OWN workspace member
522
+ # whose key ALSO has a definition (and therefore shared cells) in the tenant-wide bucket.
523
+ # Without it, `values` β€” a fact about the SHARED document β€” promoted a definition nobody
524
+ # else can even receive to `everyone`. The reader would be told the whole tenant can see a
525
+ # column that exists only in their own stratum, which is a promise the merge cannot keep.
526
+ # ⚠ It cannot touch a shared or contract definition: both answer a `stratum` this test
527
+ # admits, so Supplier and every minted route badge exactly as they did before.
528
  audience = "everyone"
529
  else:
530
  audience = "private"
 
539
  if shared_by == me:
540
  shared_by = None
541
 
542
+ # ⚠ THE `createdBy` FALLBACK IS NOW THE WHOLE ANSWER ON A PERSONAL DEFINITION, not merely the
543
+ # create-window stopgap it was written as, because `record` was zeroed above. That is the
544
+ # intended reading of C10's *"whose it is"*: the author mark rides on the definition that was
545
+ # read, so `owner` and `stratum` cannot name different documents.
546
  return {"origin": origin, "audience": audience, "sharedBy": shared_by,
547
+ "values": values, "owner": owner or _uname(field.get("createdBy")) or None,
548
+ "stratum": stratum}
549
 
550
 
551
  def field_classes(fields, viewer, *, table_key=None, grant_topic=None, values_shared=None,
552
+ strata=None, st=None):
553
+ """`{field_key: <C1 + C10 bag>}` for a whole field list, on ONE registry read. See `grant_records`.
554
+
555
+ ⭐⭐ W42-T47 / C10 β€” every bag carries `stratum` (`contract` | `shared` | `personal`), so a
556
+ caller sections on ownership without re-deriving it.
557
+
558
+ β›” `strata` IS THE LENT MAP AND IT IS THE ONLY HONEST SOURCE: `{field_key: <one of
559
+ FIELD_DEFINITION_STRATA>}`, supplied by the assembly that READ each definition and therefore
560
+ knows which document each entry of `fields` came out of. Partial maps are fine β€” a key the map
561
+ does not name falls back to `field_stratum`, per key, so a caller can lend only the keys it is
562
+ sure about. ⚠ THE PER-FIELD ANSWER IS NOT DERIVABLE FROM ANYTHING THIS FUNCTION HOLDS:
563
+ `records` and `values_shared` are both keyed by field key, so they describe whichever
564
+ definition of that key lives in THEIR store, which on a forked column is a different definition
565
+ from the one in `fields`. That is why the fact is lent rather than computed here.
566
 
567
  ⚠ EVERY COLUMN GETS A BAG, INCLUDING ONE THE REGISTRY HAS NEVER HEARD OF: the missing record is
568
  substituted explicitly rather than left to `field_class` to re-read, which is what keeps the
 
573
  if values_shared is None:
574
  values_shared = _shared_value_keys(table_key, st=st)
575
  shared_keys = {str(k) for k in (values_shared or ())}
576
+ lent = {str(k).strip(): v for k, v in strata.items()} if isinstance(strata, dict) else {}
577
  out = {}
578
  for field in (fields or ()):
579
  if not isinstance(field, dict):
 
583
  continue
584
  out[key] = field_class(field, viewer, grants=records.get(key) or _empty_record(),
585
  table_key=table_key, grant_topic=topic,
586
+ values_shared=shared_keys, stratum=lent.get(key), st=st)
587
  return out
588
 
589
 
platform/core/grid_events.py CHANGED
@@ -2428,11 +2428,21 @@ def handle_one(event, ctx):
2428
  # already the sentence a person reads and already C7-clean, and `folder_id` is an
2429
  # attribute, so nothing is parsed out of the message.
2430
  #
2431
- # ⚠ UNREACHABLE FROM THIS DOOR TODAY, AND SAYING SO IS PART OF THE HANDOVER.
2432
- # `_mutate` returns `_agf.clean_folders(...)`, whose row is `{id, name, order}` plus an
2433
- # optional `icon` β€” it STRIPS `parent` entirely, so no nesting can reach the validator
2434
- # through here and neither raise can fire. This is the forward contract with T12: the day
2435
- # `clean_folders` learns `parent`, the refusal is already wired and worded.
 
 
 
 
 
 
 
 
 
 
2436
  try:
2437
  _receipt = _tops(ctx).save_folders(uname, _res[0], _res[1])
2438
  except _tstore.FolderTreeError as _fte:
 
2428
  # already the sentence a person reads and already C7-clean, and `folder_id` is an
2429
  # attribute, so nothing is parsed out of the message.
2430
  #
2431
+ # ⭐⭐ REACHABLE NOW, AND THIS COMMENT SAID THE OPPOSITE UNTIL /wave-validate CHANGED IT.
2432
+ # It read: 'UNREACHABLE FROM THIS DOOR TODAY ... `clean_folders` STRIPS `parent` entirely,
2433
+ # so no nesting can reach the validator through here and neither raise can fire. This is
2434
+ # the forward contract with T12: the day `clean_folders` learns `parent`, the refusal is
2435
+ # already wired and worded.'
2436
+ #
2437
+ # That day is 2026-08-25. `aios_grid.clean_folders` carries `parent` through, the
2438
+ # `folder_create` branch above forwards it, and `validate_folder_tree` now fires for real:
2439
+ # an 11-deep chain raises `too_deep` naming the folder, a cycle raises `cycle`, and a
2440
+ # dangling parent REPAIRS to root with a receipt this branch turns into a toast. Driven
2441
+ # both ways, including the negative control that a payload with no `parent` anywhere comes
2442
+ # back byte-identical with zero repairs.
2443
+ #
2444
+ # β›” LEFT AS A CORRECTION RATHER THAN DELETED. A comment asserting a guard is dead is
2445
+ # exactly what stops the next reader checking, and this one would have outlived the fix.
2446
  try:
2447
  _receipt = _tops(ctx).save_folders(uname, _res[0], _res[1])
2448
  except _tstore.FolderTreeError as _fte:
platform/core/user_tables.py CHANGED
@@ -355,7 +355,51 @@ def limit_report(table_key, st=None):
355
  }
356
 
357
 
358
- MAX_FIELDS = 60
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
359
  #: the badge the nav paints for a table with no connector behind it
360
  BLANK_SOURCE = 'Blank'
361
  #: automation-created tables carry their maker instead (wave 18 C4-AUTO)
@@ -800,6 +844,174 @@ FIELD_AGGS = ('sum', 'average', 'median', 'min', 'max', 'count')
800
  #: stored value has exactly ONE spelling and two fields cannot disagree about `#ebf6ef`.
801
  _OPTION_COLOR_RE = re.compile(r'#[0-9A-F]{6}')
802
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
803
 
804
  def _clean_option_colors(raw, options):
805
  """`{option label β†’ #RRGGBB}`, capped to the field's own option vocabulary (wave-29 C1).
@@ -832,7 +1044,28 @@ def _clean_option_colors(raw, options):
832
  return out
833
 
834
 
835
- def _clean_format(raw):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
836
  """One `format` bag β†’ the stored shape, or None.
837
 
838
  β›”β›” THIS FUNCTION EXISTS BECAUSE THE BAG HAD NO STORAGE AT ALL. The column menu has shipped a
@@ -864,6 +1097,39 @@ def _clean_format(raw):
864
  tz = str(raw.get('tz') or '').strip().lower()
865
  if tz in FORMAT_TZ:
866
  out['tz'] = tz
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
867
  return out or None
868
 
869
 
@@ -887,7 +1153,10 @@ def clean_fields(raw):
887
  # ⭐ 2026-08-10 β€” the DISPLAY format, carried through the CREATE door. See `_clean_format`:
888
  # this is the fifth time an entry built key-by-key has silently dropped a bag the editor
889
  # sends, and the fourth of those was `agg` on this very line one wave ago.
890
- fmt = _clean_format(f.get('format'))
 
 
 
891
  if fmt:
892
  entry['format'] = fmt
893
  description = ' '.join(str(f.get('description') or '').split())[:300]
@@ -903,10 +1172,46 @@ def clean_fields(raw):
903
  if note:
904
  entry['note'] = note
905
  if ftype in ('select', 'multiselect'):
 
 
 
 
 
906
  opts = [' '.join(str(o).split())[:60] for o in (f.get('options') or [])
907
- if str(o).strip()][:50]
 
 
908
  if opts:
909
  entry['options'] = opts
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
910
  if f.get('default') is True:
911
  entry['default'] = True
912
  # ⭐ WAVE-27 item 19 (R15) + D-80 β€” THE PRIMARY COLUMN, CARRIED THROUGH THE CREATE DOOR.
@@ -952,6 +1257,16 @@ def clean_fields(raw):
952
  # β›” THE TYPE/BAG PAIRING IS ENFORCED BOTH WAYS, as it is in `_clean_field`: a `link` with
953
  # no bag can never resolve a row, and a bag on a column of another type is a declaration
954
  # nothing reads. Either half alone is the silent kind of broken.
 
 
 
 
 
 
 
 
 
 
955
  for bag_key, cleaner in (('link', _clean_link), ('rollup', _clean_rollup)):
956
  bag = cleaner(f.get(bag_key)) if f.get(bag_key) is not None else None
957
  if ftype == bag_key and bag is None:
@@ -1251,6 +1566,15 @@ def add_row(table_key, values=None, username=None, st=None, rid=None):
1251
  rid = str(max((int(r) for r in rows if str(r).isdigit()), default=0) + 1)
1252
  valid = {f['key'] for f in (defn.get('fields') or [])}
1253
  clean = {k: str(v) for k, v in (values or {}).items() if k in valid}
 
 
 
 
 
 
 
 
 
1254
  # C3 (wave 25): a PROFILE cell is validated and normalised on the insert door too, not only
1255
  # on the edit door. A row born with `https://instagram.com/p/Cxyz` in its handle column is a
1256
  # row the enrich action can never answer, and the failure would otherwise surface as an
@@ -1313,9 +1637,17 @@ def add_rows(table_key, rows_in, username=None, st=None):
1313
  valid = {f['key'] for f in (defn.get('fields') or [])}
1314
  pf = _profile_of(defn.get('fields') or [])
1315
  next_id = max((int(r) for r in rows if str(r).isdigit()), default=0)
 
 
 
 
 
1316
  made = []
1317
  for values in batch:
1318
  clean = {k: str(v) for k, v in values.items() if k in valid}
 
 
 
1319
  if pf and pf['key'] in clean:
1320
  handle, ok = normalize_profile(clean[pf['key']], pf['profile'].get('source'))
1321
  if not ok:
@@ -1575,7 +1907,340 @@ def is_linkable_target(table_key):
1575
  return key.startswith(KEY_PREFIX) and len(key) > len(KEY_PREFIX)
1576
 
1577
 
1578
- def _clean_link(raw):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1579
  """One `link` bag β†’ the stored shape, or None (refused).
1580
 
1581
  Same posture as `_clean_metric`: a mis-shaped bag REFUSES THE FIELD. A link column stored
@@ -1623,13 +2288,126 @@ def _clean_link(raw):
1623
  # than dropped: a bag half of which is silently ignored is [[wrong-parent-not-broken-control]]
1624
  # with the control still on screen.
1625
  return None
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1626
  if reciprocal:
1627
  out['reciprocal'] = reciprocal
1628
  if raw.get('single') is True:
1629
  out['single'] = True
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1630
  return out
1631
 
1632
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1633
  def _clean_rollup(raw):
1634
  """One `rollup` bag β†’ the stored shape, or None (refused).
1635
 
@@ -2111,7 +2889,7 @@ def _clean_field(raw, previous=None):
2111
  # `raw.get('format')`, exactly like `description` below: an explicit `{}`/None CLEARS the
2112
  # format, while omitting the key keeps what is stored. A PATCH that sends only a label must not
2113
  # silently strip a formatting choice β€” that is how `agg` stopped totalling a money column.
2114
- fmt = _clean_format(raw.get('format') if 'format' in raw else prev.get('format'))
2115
  if fmt:
2116
  out['format'] = fmt
2117
  # Canonical descriptions are schema metadata, not the user's per-view note. Preserve them
@@ -2154,7 +2932,15 @@ def _clean_field(raw, previous=None):
2154
  out['note'] = note
2155
  opts_raw = raw.get('options') if 'options' in raw else prev.get('options')
2156
  if ftype in ('select', 'multiselect'):
2157
- opts = [' '.join(str(o).split())[:60] for o in (opts_raw or []) if str(o).strip()][:50]
 
 
 
 
 
 
 
 
2158
  if opts:
2159
  out['options'] = opts
2160
  # ⭐⭐ WAVE-29 CONTRACT C1 (owner item 13) β€” **THE OPTION COLOURS, WHICH THIS DOOR DROPPED.**
@@ -2196,6 +2982,51 @@ def _clean_field(raw, previous=None):
2196
  else prev.get('colorCodeOptions'))
2197
  if isinstance(color_code, bool):
2198
  out['colorCodeOptions'] = color_code
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2199
  # ⭐ WAVE-29 T22's own repair: a `rating` column's star count. Grid-created columns on a `ut_*`
2200
  # database now come through this door rather than the per-user overlay, and this validator had
2201
  # no `max` β€” so a 3-star or 10-star column silently became 5-star on the way in. Bounded rather
@@ -2208,6 +3039,37 @@ def _clean_field(raw, previous=None):
2208
  out['max'] = max(2, min(int(max_raw), 10))
2209
  except (TypeError, ValueError):
2210
  pass
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2211
  role = str(raw.get('editRole') or prev.get('editRole') or 'admins').strip().lower()
2212
  out['editRole'] = role if role in FIELD_EDIT_ROLES else 'admins'
2213
  if prev.get('default') is True or raw.get('default') is True:
@@ -2483,9 +3345,23 @@ def cell_type_refusal(field, value):
2483
  label = f.get('label') or f.get('key') or 'that column'
2484
  if ftype in _NUMERIC_CELL_TYPES:
2485
  try:
2486
- float(text.replace('$', '').replace(',', '').replace('%', '').replace(' ', ''))
 
2487
  except (TypeError, ValueError):
2488
  return f'{text[:40]!r} is not a number, and {label!r} holds numbers'
 
 
 
 
 
 
 
 
 
 
 
 
 
2489
  return None
2490
  if ftype == 'rating':
2491
  try:
@@ -2965,6 +3841,14 @@ def add_field(table_key, raw, st=None):
2965
  # the existing column in its refusal (`_refusal_sentence`); the LAW is here.
2966
  if field.get('profile') and _profile_of(have):
2967
  return None
 
 
 
 
 
 
 
 
2968
 
2969
  def _add(cur):
2970
  t = cur.get(str(table_key))
@@ -2994,6 +3878,44 @@ def _reciprocal_link_key(table_key, field_key):
2994
  return f'linked_{digest}'
2995
 
2996
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2997
  def sync_reciprocal_link(table_key, field_key, st=None):
2998
  """Create/repair Airtable's reciprocal link field for one ordinary link.
2999
 
@@ -3102,7 +4024,7 @@ def sync_reciprocal_link(table_key, field_key, st=None):
3102
  reciprocal_key = _reciprocal_link_key(table_key, field_key)
3103
  reciprocal = _clean_field({
3104
  'key': reciprocal_key,
3105
- 'label': str(source.get('label') or table_key)[:80],
3106
  'type': 'link',
3107
  'link': {'table': table_key, 'inverse': field_key,
3108
  'reciprocal': field_key},
@@ -3127,9 +4049,106 @@ def sync_reciprocal_link(table_key, field_key, st=None):
3127
  return result
3128
 
3129
 
3130
- def patch_field(table_key, fkey, raw, st=None):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3131
  """Edit one column's definition IN PLACE. Returns the stored field, or None if refused.
3132
 
 
 
 
 
 
 
 
 
 
 
 
3133
  ⚠ THE KEY NEVER MOVES. A field's key is what every stored cell is filed under, so accepting
3134
  a new one here would orphan every value in the column while looking like a rename. The
3135
  LABEL is the renameable thing; the key is identity.
@@ -3166,6 +4185,10 @@ def patch_field(table_key, fkey, raw, st=None):
3166
  # as adding one. `exclude=fkey` so re-saving the profile column does not collide with itself.
3167
  if field.get('profile') and _profile_of(fields, exclude=str(fkey)):
3168
  return None
 
 
 
 
3169
  # ⭐⭐ 2026-08-09 β€” THE CUSTODY STAMP IS WRITTEN HERE, at the ONE door a human reaches.
3170
  #
3171
  # `USER_EDITED_KEY`'s note has the why. It is written here rather than inside `_clean_field`
@@ -3203,6 +4226,18 @@ def patch_field(table_key, fkey, raw, st=None):
3203
  and not description_edited(field) and not user_edited(field):
3204
  field.pop('note', None)
3205
 
 
 
 
 
 
 
 
 
 
 
 
 
3206
  def _set(cur):
3207
  t = cur.get(str(table_key))
3208
  if t is not None:
@@ -3210,6 +4245,20 @@ def patch_field(table_key, fkey, raw, st=None):
3210
  if f.get('key') == str(fkey):
3211
  t['fields'][i] = field
3212
  break
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3213
  return cur
3214
 
3215
  _st(st).update(STORE_KEY, _set, flush='sync')
 
355
  }
356
 
357
 
358
+ #: ⭐⭐ W42-T36 β€” **60 -> 100, AND THE NUMBER IS MEASURED RATHER THAN CHOSEN.** Copying one table
359
+ #: document at each shape, on this box:
360
+ #:
361
+ #: rows 60 fields 100 fields delta
362
+ #: 0 1.42ms 1.65ms +0.23ms
363
+ #: 5000 203.32ms 437.35ms +234.03ms
364
+ #: 20000 1535.34ms 2254.67ms +719.33ms
365
+ #: 60000 4015ms 9593ms 2.39x <- MAX_ROWS, the true worst case
366
+ #:
367
+ #: β›”β›” THE `MAX_ROWS` ARM IS THE ONE TO READ, AND IT WAS NOT IN THE ORIGINAL MEASUREMENT. Every
368
+ #: arm above 20,000 rows was an extrapolation until this one was run; the extrapolation said ~1.6x
369
+ #: and the measurement says **2.39x, at 9.6 SECONDS for one full-document copy**. A store copy is
370
+ #: not linear in document size at that scale, so the honest statement is that the cost was
371
+ #: measured at the ceiling rather than reasoned toward it.
372
+ #: ⚠ THIS IS A CEILING, NOT A TYPICAL COST: it needs a table simultaneously at `MAX_ROWS` AND at
373
+ #: the new `MAX_FIELDS`, which no tenant document is today. Recorded so the next person raising
374
+ #: either cap knows which one they are multiplying, and books the async-flush question rather than
375
+ #: rediscovering it under an incident.
376
+ #:
377
+ #: β›” **`MAX_FIELDS` IS A ROW COST, NOT A FIELD-DEFINITION COST**, and that is the mechanism a
378
+ #: later reader needs rather than the milliseconds. With no rows the cap is free (0.23 ms); every
379
+ #: ROW carries a cell per field, so raising it multiplies the ~99%-of-document part. The ratio is
380
+ #: what travels: ~+47% copy time at 20,000 rows for +67% columns.
381
+ #: β›” DO NOT QUOTE THESE ABSOLUTES AS CONSTANTS. The identical shape measured 791 ms and then
382
+ #: 1535 ms on this machine, a 1.94x spread under lane contention; one arm of the first run came
383
+ #: back NEGATIVE, which is impossible and is the tell that the absolutes are noise.
384
+ #: ⚠ 100 IS THE CEILING THE MEASUREMENT COVERS. Anything above it is estimated, and this cap
385
+ #: exists precisely so the number is not guessed.
386
+ MAX_FIELDS = 100
387
+ #: ⭐⭐ W42-T36 / CONTRACT C8b β€” THE OPTION CAP, DECLARED ONCE AND USED AT BOTH DOORS.
388
+ #:
389
+ #: β›” IT WAS TWO BARE `[:50]` SLICES, WHICH IS THE PART THAT MATTERED MORE THAN THE NUMBER. A
390
+ #: slice DROPS THE TAIL SILENTLY: the 51st option vanished, the request answered 200, and the
391
+ #: column came back short with nothing anywhere to notice. Standing rule 1's second half is
392
+ #: explicit that *"a limit that genuinely cannot be removed must be REPORTED, with cause and a
393
+ #: recommended fix, never silently enforced"* β€” so raising the number without changing the
394
+ #: BEHAVIOUR would only have moved where the silence happens. Over the cap now REFUSES the field.
395
+ #:
396
+ #: ⚠ MEASURED, LIKE `MAX_FIELDS`, AND IT IS THE CHEAP ONE. Options live in the field DEFINITION
397
+ #: and never scale with rows: 50 options 3.03 ms -> 200 options 9.64 ms at rows=0, and that delta
398
+ #: does not grow with the row count because no row carries an option. The ticket's own `how:`
399
+ #: warned about this cap; the measurement says `MAX_FIELDS` is the expensive one.
400
+ #: β­’ The CLIENT half (`types.ts::parseOptions`, still `slice(0, 50)`) is lane B's W42-T37. Until
401
+ #: that lands the two ends disagree, and the server is the permissive one.
402
+ MAX_OPTIONS = 200
403
  #: the badge the nav paints for a table with no connector behind it
404
  BLANK_SOURCE = 'Blank'
405
  #: automation-created tables carry their maker instead (wave 18 C4-AUTO)
 
844
  #: stored value has exactly ONE spelling and two fields cannot disagree about `#ebf6ef`.
845
  _OPTION_COLOR_RE = re.compile(r'#[0-9A-F]{6}')
846
 
847
+ #: ⭐⭐ W42-T32 β€” THE RATING SYMBOL VOCABULARY, AND IT HAS EXACTLY ONE MEMBER TODAY.
848
+ #:
849
+ #: β›” THE HONEST LIST IS THE SHORT ONE. `iconShapes.ts::TYPE_SHAPES` (:54) is keyed by field TYPE,
850
+ #: not by symbol, and its `rating` entry holds ONE path: a star. A repo-wide sweep for
851
+ #: `ratingSymbol` / `rating_symbol` / `RATING_SHAPES` / `symbolChoices` returns zero hits β€” no
852
+ #: rating-symbol vocabulary exists anywhere in the product. So this list names what the client can
853
+ #: genuinely DRAW and nothing else. Inventing `heart`/`flag`/`thumb` here would ship a picker whose
854
+ #: members render as nothing: a list that LOOKS complete and is not is worse than an honest single
855
+ #: member, because the gap is then invisible to the next reader instead of stated.
856
+ #: β­’ A wave-43 ticket that wants more symbols extends `iconShapes.ts::TYPE_SHAPES` FIRST and this
857
+ #: tuple second. The order matters: a name here with no path there is a blank cell.
858
+ RATING_SYMBOLS = ('star',)
859
+ RATING_SYMBOL_DEFAULT = 'star'
860
+
861
+ #: ⭐⭐ W42-T32 β€” THE CHECKBOX MARK. Same posture and the same honesty as `RATING_SYMBOLS`: the
862
+ #: only checkbox geometry in the client is `TYPE_SHAPES.checkbox` (a square plus a tick), and the
863
+ #: cell itself paints glide's stock `BooleanCell` tick (`cells.ts:539`) in the shared theme accent
864
+ #: `LP_BLUE_DEEP` (`theme.ts:100`). That accent IS "today's mark", recorded here as the value an
865
+ #: unset column means.
866
+ #: β›” THE DEFAULTS ARE NOT EMITTED BY THE VALIDATOR, and that is deliberate rather than lazy.
867
+ #: `verify_api.py` and `verify_automation.py` assert `_clean_field(f) == f` over every
868
+ #: engine-seeded field list, so a branch stamping `icon`/`color` onto every checkbox column would
869
+ #: redden both gates for every preset column in the product ([[default-must-pass-its-own-guard]]).
870
+ #: ABSENCE MEANS THE DEFAULT, and `checkbox_mark()` below is the one reader that resolves it.
871
+ CHECKBOX_ICONS = ('check',)
872
+ CHECKBOX_ICON_DEFAULT = 'check'
873
+ CHECKBOX_COLOR_DEFAULT = '#768FB6'
874
+
875
+ #: The column kinds that can carry a `defaultValue` at all. β›” A TEXT COLUMN IS DELIBERATELY OUT:
876
+ #: the done-when names seven kinds, and every one of them has a vocabulary or a shape the
877
+ #: validator can check a default AGAINST. A free-text default would be a string nothing can refuse,
878
+ #: which is a stored preference rather than a validated setting.
879
+ #: β›” Every COMPUTED kind is out by construction (`rollup`, `formula`, `link`, `ai_enrich`,
880
+ #: `metric`), and `row_defaults` re-checks that with `is_computed_cell` before applying one: a
881
+ #: default written into a cell the server recomputes is an invented value with a delay on it.
882
+ DEFAULT_VALUE_TYPES = ('select', 'multiselect', 'checkbox', 'int', 'currency', 'pct', 'date')
883
+
884
+ #: The "this default is unusable" answer, distinct from `None` which means "no default here".
885
+ #: ⚠ A SENTINEL OBJECT RATHER THAN A FALSY VALUE, because `0` and `False` are both legitimate
886
+ #: defaults: `defaultValue: 0` on an int column and `defaultValue: False` on a checkbox are
887
+ #: exactly the settings a person would set, and a truthiness test would silently discard them.
888
+ _DEFAULT_REFUSED = object()
889
+
890
+
891
+ def _clean_default_value(value, ftype, options):
892
+ """One `defaultValue` β†’ the stored value, `None` (none set / cleared), or `_DEFAULT_REFUSED`.
893
+
894
+ ⭐⭐ W42-T32 β€” A FIELD CARRIES ITS OWN CONFIGURATION, NOT JUST ITS TYPE.
895
+
896
+ β›” AN OUT-OF-VOCABULARY SELECT DEFAULT REFUSES THE FIELD rather than dropping the key, and the
897
+ posture is `metric`/`profile`'s rather than `agg`'s on purpose. A dropped key is a setting the
898
+ user chose, saved, and will not find again β€” the exact silent-loss shape this module is a
899
+ museum of. A refusal is a sentence at the door. `select` and `multiselect` are the two kinds
900
+ where "outside the declared options" is even askable, which is why the done-when names them.
901
+
902
+ ⚠ THE NUMERIC AND DATE FAMILIES DELEGATE TO `cell_type_refusal`, the module's existing
903
+ evaluator for "can this value be this column's value". A second opinion on whether a string is
904
+ a date is how two doors start disagreeing ([[one-evaluator-per-question]]).
905
+
906
+ ⚠ `bool` IS AN `int` SUBCLASS, so `True` in an int column's default would otherwise store as
907
+ the number 1. Refused, not interpreted β€” the same guard `decimals` carries in `_clean_format`.
908
+ """
909
+ if value is None:
910
+ return None
911
+ if ftype not in DEFAULT_VALUE_TYPES:
912
+ return _DEFAULT_REFUSED
913
+ if ftype == 'checkbox':
914
+ return value if isinstance(value, bool) else _DEFAULT_REFUSED
915
+ if ftype == 'select':
916
+ text = ' '.join(str(value).split())[:60]
917
+ return text if text and text in (options or []) else _DEFAULT_REFUSED
918
+ if ftype == 'multiselect':
919
+ if not isinstance(value, (list, tuple)):
920
+ return _DEFAULT_REFUSED
921
+ picked = [' '.join(str(v).split())[:60] for v in value]
922
+ if not picked or any(p not in (options or []) for p in picked):
923
+ return _DEFAULT_REFUSED
924
+ return picked
925
+ if ftype in _NUMERIC_CELL_TYPES:
926
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
927
+ return _DEFAULT_REFUSED
928
+ return value
929
+ if cell_type_refusal({'type': ftype, 'label': 'default'}, value):
930
+ return _DEFAULT_REFUSED
931
+ return ' '.join(str(value).split())
932
+
933
+
934
+ def checkbox_mark(field):
935
+ """The icon and colour a checkbox column actually renders with. β›” THE ONE RESOLVER.
936
+
937
+ Absence means the default (see `CHECKBOX_ICONS`' note for why the validator does not stamp
938
+ one), so every reader must come through here or two surfaces will disagree about what an
939
+ unconfigured checkbox looks like.
940
+ """
941
+ f = field if isinstance(field, dict) else {}
942
+ return {'icon': f.get('icon') or CHECKBOX_ICON_DEFAULT,
943
+ 'color': f.get('color') or CHECKBOX_COLOR_DEFAULT}
944
+
945
+
946
+ def rating_symbol(field):
947
+ """The symbol a rating column draws. Absence means `RATING_SYMBOL_DEFAULT`, same rule."""
948
+ return (field if isinstance(field, dict) else {}).get('symbol') or RATING_SYMBOL_DEFAULT
949
+
950
+
951
+ def _default_cell_text(value):
952
+ """A validated `defaultValue` β†’ the STORED CELL string, in the store's own vocabularies.
953
+
954
+ β›” THE CONTRACTS ARE THE STORE'S, NOT THIS FUNCTION'S INVENTION. A checkbox cell is `'1'` or
955
+ empty (`aios_grid.py:133`, `cells.ts:10`, `display.ts::checkboxOn`), and a multiselect cell is
956
+ a COMMA-JOINED set (`cells.ts:789`). Written as a bare `str(value)` a checkbox default would
957
+ store the text `'True'`, which `checkboxOn` reads as unchecked: a default that saves, reads
958
+ back, and renders as off. That is the "a default that is not applied is not a default" failure
959
+ arriving one layer lower down than expected.
960
+ """
961
+ if value is True:
962
+ return '1'
963
+ if value is False:
964
+ return ''
965
+ if isinstance(value, (list, tuple)):
966
+ return ', '.join(str(v) for v in value)
967
+ return str(value)
968
+
969
+
970
+ def row_defaults(fields):
971
+ """`{field key: stored cell text}` for every column declaring a default. β›” ONE DERIVATION.
972
+
973
+ ⭐⭐ W42-T32 β€” **A DEFAULT THAT IS NOT APPLIED IS NOT A DEFAULT.** Storing the setting and
974
+ stopping there is a key with no importer, which is the shape this repo has shipped repeatedly:
975
+ the pane saves, the request succeeds, and every new row is still blank. Both row-create doors
976
+ (`add_row`, `add_rows`) read this.
977
+
978
+ β›” A COMPUTED CELL IS SKIPPED. `is_computed_cell` is the module's own predicate for "the server
979
+ owns this number"; seeding one is an invented value the next compute pass overwrites, with
980
+ nothing anywhere to notice. `DEFAULT_VALUE_TYPES` already excludes the computed TYPES, so this
981
+ catches the remaining case: a `metric` bag sitting on an `int` column.
982
+ """
983
+ out = {}
984
+ for f in fields or []:
985
+ if not isinstance(f, dict) or 'defaultValue' not in f:
986
+ continue
987
+ if is_computed_cell(f):
988
+ continue
989
+ key = str(f.get('key') or '')
990
+ if key:
991
+ out[key] = _default_cell_text(f['defaultValue'])
992
+ return out
993
+
994
+
995
+ def option_cap_refusal(raw_options):
996
+ """Why this option list cannot be stored, NAMING THE COUNT, or None if it fits.
997
+
998
+ ⭐⭐ W42-T36 β€” **STANDING RULE 1'S SECOND HALF, WHICH IS THE HALF THAT GETS DROPPED.** A limit
999
+ that cannot be removed must be REPORTED with its cause, never silently enforced. Both option
1000
+ doors were bare `[:50]` slices: they dropped the tail with no error, so the only way to learn
1001
+ the cap existed was to count the column afterwards. Raising 50 to `MAX_OPTIONS` without this
1002
+ would have moved where the silence happens and changed nothing about the silence.
1003
+
1004
+ ⚠ THIS FUNCTION IS THE WORDS; the WALL is in `_clean_field` and `clean_fields`, which refuse.
1005
+ They are separate because a validator that returns `None` cannot carry a sentence, and the
1006
+ route that answers the browser (`routes_tables._refusal_sentence`) is outside this module. A
1007
+ surface wanting the sentence calls this; nothing here depends on it having been called.
1008
+ """
1009
+ n = len([o for o in (raw_options or []) if str(o).strip()])
1010
+ if n <= MAX_OPTIONS:
1011
+ return None
1012
+ return (f'That column declares {n} options and the limit is {MAX_OPTIONS}. '
1013
+ f'Remove {n - MAX_OPTIONS} of them, or split the vocabulary across two columns.')
1014
+
1015
 
1016
  def _clean_option_colors(raw, options):
1017
  """`{option label β†’ #RRGGBB}`, capped to the field's own option vocabulary (wave-29 C1).
 
1044
  return out
1045
 
1046
 
1047
+ #: ⭐⭐ W42-T33 β€” THE CURRENCY SYMBOL VOCABULARY, DELIBERATELY CLOSED.
1048
+ #:
1049
+ #: ⚠ REFERENCE DIVERGENCE, RECORDED SO A LATER READER DOES NOT THINK WE MATCHED IT. Airtable's own
1050
+ #: create-field panel offers the currency symbol as a FREE TEXT INPUT
1051
+ #: (`reference/airtable-field-docs/9701435990-number-based-fields-in-airtable__1.png`). We are
1052
+ #: keeping a closed list ON PURPOSE: a validator that admits arbitrary text into a symbol that then
1053
+ #: prefixes every number in a rendered money column is the worse trade, and this module's whole
1054
+ #: posture is refuse-do-not-coerce. Widening the list is a one-line change; narrowing it after
1055
+ #: arbitrary text has been stored is a migration.
1056
+ FORMAT_CURRENCY_SYMBOLS = ('$', '€', 'Β£', 'Β₯', 'β‚©', 'β‚Ή', 'CHF', 'C$', 'A$', 'S$', 'HK$', 'R$')
1057
+
1058
+ #: ⭐⭐ W42-T33 β€” the DURATION kinds, on `int` columns only. These name a DISPLAY shape and nothing
1059
+ #: else: the stored value stays a plain integer count of seconds, which is the entire point (see
1060
+ #: `_clean_format`'s note). Vocabulary matches Airtable's duration formats, which is what any
1061
+ #: importer or exporter will already speak.
1062
+ FORMAT_DURATION_KINDS = ('h:mm', 'h:mm:ss', 'h:mm:ss.s', 'h:mm:ss.ss', 'h:mm:ss.sss')
1063
+
1064
+ #: The kinds `allowNegative` can speak about at all. A text or date column has no sign.
1065
+ _FORMAT_SIGNED_TYPES = ('int', 'currency', 'pct')
1066
+
1067
+
1068
+ def _clean_format(raw, ftype=None):
1069
  """One `format` bag β†’ the stored shape, or None.
1070
 
1071
  β›”β›” THIS FUNCTION EXISTS BECAUSE THE BAG HAD NO STORAGE AT ALL. The column menu has shipped a
 
1097
  tz = str(raw.get('tz') or '').strip().lower()
1098
  if tz in FORMAT_TZ:
1099
  out['tz'] = tz
1100
+ # ⭐⭐ W42-T33 β€” A NUMBER COLUMN SAYS WHAT IT MEANS.
1101
+ #
1102
+ # β›” THE SIGNATURE GREW A TYPE, AND IT HAD TO. "a `duration` format on `int`" is not a
1103
+ # question this function could answer as written: it took one bag and no field type, so the
1104
+ # rule would have had to be re-stated wherever the type IS known, which is two more copies of
1105
+ # a validator ([[one-evaluator-per-question]]). `ftype` is in scope at BOTH in-tree call sites
1106
+ # (`clean_fields`, `_clean_field`) and both now pass it β€” changing only one would have left
1107
+ # the rule holding on the CREATE door and not the PATCH door, or the reverse, which is D-91's
1108
+ # exact class. ⚠ The sibling `aios_grid._clean_format(raw, ftype)` has taken a type since
1109
+ # wave 5; this is the two validators converging, not diverging.
1110
+ # ⚠ `ftype=None` KEEPS THE CALL SHAPE VALID for a caller with no type context, and then judges
1111
+ # the type-guarded keys on SHAPE alone. Both in-tree callers pass a real type.
1112
+ symbol = str(raw.get('symbol') or '').strip()
1113
+ if symbol in FORMAT_CURRENCY_SYMBOLS and ftype in (None, 'currency'):
1114
+ out['symbol'] = symbol
1115
+ # ⚠ `bool` IS AN `int` SUBCLASS and this bag is mostly booleans, so the guard runs the other
1116
+ # way here: `allowNegative` must be a REAL bool, which `isinstance(x, bool)` already gives.
1117
+ # β›” ABSENT MEANS ALLOWED, and that is what makes this safe to ship. Every number column in
1118
+ # every user database has no `allowNegative` today; a default of False would start refusing
1119
+ # values those columns already hold. Only an EXPLICIT `False` is a wall.
1120
+ allow_negative = raw.get('allowNegative')
1121
+ if isinstance(allow_negative, bool) and ftype in (None,) + _FORMAT_SIGNED_TYPES:
1122
+ out['allowNegative'] = allow_negative
1123
+ duration = str(raw.get('duration') or '').strip().lower()
1124
+ if duration in FORMAT_DURATION_KINDS and ftype in (None, 'int'):
1125
+ out['duration'] = duration
1126
+ # β›” `duration` AND `time` CANNOT BOTH STAND, and the resolution is to keep `duration`
1127
+ # rather than to refuse the bag. `time` means "this DATE also shows a clock" and is read
1128
+ # by the date renderer; a duration is an elapsed count on an `int` column. Both set is a
1129
+ # contradiction, but returning None for it would silently discard the user's UNRELATED
1130
+ # format choices in the same bag (decimals, thousands, the lot) to punish one stray key.
1131
+ # The narrower key wins and the contradiction is dropped, not the document.
1132
+ out.pop('time', None)
1133
  return out or None
1134
 
1135
 
 
1153
  # ⭐ 2026-08-10 β€” the DISPLAY format, carried through the CREATE door. See `_clean_format`:
1154
  # this is the fifth time an entry built key-by-key has silently dropped a bag the editor
1155
  # sends, and the fourth of those was `agg` on this very line one wave ago.
1156
+ # ⚠ W42-T33 β€” `ftype` is passed HERE TOO, not only on the patch door. A currency symbol or
1157
+ # a duration kind that survived one door and not the other is the crossed-validator shape
1158
+ # this file keeps paying for.
1159
+ fmt = _clean_format(f.get('format'), ftype)
1160
  if fmt:
1161
  entry['format'] = fmt
1162
  description = ' '.join(str(f.get('description') or '').split())[:300]
 
1172
  if note:
1173
  entry['note'] = note
1174
  if ftype in ('select', 'multiselect'):
1175
+ # ⭐⭐ W42-T36 β€” ONE declared cap, and it REFUSES rather than truncating. See
1176
+ # `MAX_OPTIONS`. ⚠ This door DROPS the field rather than returning None for the whole
1177
+ # list, which is `clean_fields`' existing posture for every other refusal here (an
1178
+ # unknown type, a duplicate key): one bad column must not cost the caller the other
1179
+ # fifty-nine. `option_cap_refusal` names the count for the surface that asks.
1180
  opts = [' '.join(str(o).split())[:60] for o in (f.get('options') or [])
1181
+ if str(o).strip()]
1182
+ if len(opts) > MAX_OPTIONS:
1183
+ continue
1184
  if opts:
1185
  entry['options'] = opts
1186
+ # ⭐⭐ W42-T32 β€” THE FIVE CONFIGURATION KEYS, ON THIS DOOR TOO, IN THE SAME CHANGE.
1187
+ #
1188
+ # β›” THIS FUNCTION BUILDS ITS ENTRY KEY-BY-KEY, and the module's own note twenty lines up
1189
+ # says what that costs: *"this is the fifth time an entry built key-by-key has silently
1190
+ # dropped a bag the editor sends"*. `create()` (:1371) and `set_fields` (:1479) both come
1191
+ # through here, and `create` IS a user door, so a column authored with a default at table
1192
+ # creation would have arrived without it while the very same column patched a second later
1193
+ # kept it. One validator's answer, two doors, or it is D-91 again.
1194
+ # ⚠ DROP, DO NOT REFUSE, which is this door's posture for every other refusal it makes
1195
+ # (an unknown type, a duplicate key, an over-cap option list): one unusable setting must
1196
+ # not cost the caller the column. `_clean_field` refuses instead, because it is handed ONE
1197
+ # field and `None` is the only refusal it has.
1198
+ if 'defaultValue' in f:
1199
+ dv = _clean_default_value(f.get('defaultValue'), ftype, entry.get('options') or [])
1200
+ if dv is not None and dv is not _DEFAULT_REFUSED:
1201
+ entry['defaultValue'] = dv
1202
+ if ftype == 'user' and f.get('single') is True:
1203
+ entry['single'] = True
1204
+ if ftype == 'rating':
1205
+ sym = str(f.get('symbol') or '').strip().lower()
1206
+ if sym in RATING_SYMBOLS:
1207
+ entry['symbol'] = sym
1208
+ if ftype == 'checkbox':
1209
+ icon = str(f.get('icon') or '').strip().lower()
1210
+ if icon in CHECKBOX_ICONS:
1211
+ entry['icon'] = icon
1212
+ cb_color = str(f.get('color') or '').strip().upper()
1213
+ if _OPTION_COLOR_RE.fullmatch(cb_color):
1214
+ entry['color'] = cb_color
1215
  if f.get('default') is True:
1216
  entry['default'] = True
1217
  # ⭐ WAVE-27 item 19 (R15) + D-80 β€” THE PRIMARY COLUMN, CARRIED THROUGH THE CREATE DOOR.
 
1257
  # β›” THE TYPE/BAG PAIRING IS ENFORCED BOTH WAYS, as it is in `_clean_field`: a `link` with
1258
  # no bag can never resolve a row, and a bag on a column of another type is a declaration
1259
  # nothing reads. Either half alone is the silent kind of broken.
1260
+ # ⚠ W42-T35 β€” AND THIS DOOR STAYS SHAPE-ONLY FOR A LINK'S RECORD FILTER, DECLINED WITH
1261
+ # ITS REASON RATHER THAN OVERLOOKED. `_clean_link` validates a filter's COLUMN NAMES only
1262
+ # when a caller hands it the target's column set, and this function has no `st` to
1263
+ # resolve one from: `clean_fields` is reached from `create()`/`set_fields()`, neither of
1264
+ # which carries a store handle at the point the field list is cleaned. `add_field` and
1265
+ # `patch_field` both do, and both check there (`link_filter_refusal`). The gap is LATENT,
1266
+ # not live, for the reason the paragraph above already gives: no API route calls
1267
+ # `set_fields`, and `odoo_relational` writes its definitions directly. It stops being
1268
+ # latent the moment a route does, and closing it means plumbing `st` through this
1269
+ # signature, which is a caller-visible change outside one ticket's fence.
1270
  for bag_key, cleaner in (('link', _clean_link), ('rollup', _clean_rollup)):
1271
  bag = cleaner(f.get(bag_key)) if f.get(bag_key) is not None else None
1272
  if ftype == bag_key and bag is None:
 
1566
  rid = str(max((int(r) for r in rows if str(r).isdigit()), default=0) + 1)
1567
  valid = {f['key'] for f in (defn.get('fields') or [])}
1568
  clean = {k: str(v) for k, v in (values or {}).items() if k in valid}
1569
+ # ⭐⭐ W42-T32 β€” THE COLUMN DEFAULTS, APPLIED. A stored `defaultValue` that no writer reads is
1570
+ # a setting the pane saves and nothing honours; `row_defaults` is the one derivation and this
1571
+ # is one of its two callers.
1572
+ # ⚠ ONLY WHERE THE CALLER SAID NOTHING. An explicit value always wins, including an explicit
1573
+ # BLANK β€” clearing a cell on the way in is a thing a caller may mean, and a default that
1574
+ # overrode it would make the column impossible to leave empty.
1575
+ for _dk, _dv in row_defaults(defn.get('fields') or []).items():
1576
+ if _dk in valid and _dk not in clean:
1577
+ clean[_dk] = _dv
1578
  # C3 (wave 25): a PROFILE cell is validated and normalised on the insert door too, not only
1579
  # on the edit door. A row born with `https://instagram.com/p/Cxyz` in its handle column is a
1580
  # row the enrich action can never answer, and the failure would otherwise surface as an
 
1637
  valid = {f['key'] for f in (defn.get('fields') or [])}
1638
  pf = _profile_of(defn.get('fields') or [])
1639
  next_id = max((int(r) for r in rows if str(r).isdigit()), default=0)
1640
+ # ⭐⭐ W42-T32 β€” the same defaults as `add_row`, DERIVED ONCE for the whole batch. Both doors
1641
+ # read one function, so an imported row and a typed row cannot disagree about what a column's
1642
+ # default is; computing it per row would also be a full field scan per line of a 2,000-row
1643
+ # import, which is the shape this function exists to avoid.
1644
+ row_default_cells = row_defaults(defn.get('fields') or [])
1645
  made = []
1646
  for values in batch:
1647
  clean = {k: str(v) for k, v in values.items() if k in valid}
1648
+ for _dk, _dv in row_default_cells.items():
1649
+ if _dk in valid and _dk not in clean:
1650
+ clean[_dk] = _dv
1651
  if pf and pf['key'] in clean:
1652
  handle, ok = normalize_profile(clean[pf['key']], pf['profile'].get('source'))
1653
  if not ok:
 
1907
  return key.startswith(KEY_PREFIX) and len(key) > len(KEY_PREFIX)
1908
 
1909
 
1910
+ #: ⭐⭐ W42-T03 / RULING R1 / CONTRACT C1 (2026-08-25) β€” THE NINE KEYS OF THE `via` HOP BAG.
1911
+ #:
1912
+ #: R1: *"a user-created link field may take TWO HOPS, the user configures the hop with the existing
1913
+ #: filter UI, capped structurally at one `via`"*. `via` is OPTIONAL; absent means today's one-hop
1914
+ #: join, unchanged to the byte. Present, it names the MIDDLE topic the join travels through:
1915
+ #: `customer -> (sales_lines) -> product`, which is what RETIRES `routes_grid._PIVOT_ROUTES`, a
1916
+ #: hand-written table of exactly one route.
1917
+ #:
1918
+ #: ⚠ RETIRES, NOT YET DELETES, and the distinction is load-bearing (A23, 2026-08-25, corrected
1919
+ #: after this paragraph shipped saying "dissolves"). `_PIVOT_ROUTES` is still on disk as a DATED
1920
+ #: SINGLE-PAIR TOMBSTONE, because no user-created link field can exist on a topic grid yet:
1921
+ #: `aios_grid.FIELDS` holds zero entries of type `link` and `add_field` refuses non-`ut_` keys, so
1922
+ #: deleting the table outright would have taken the customer-to-product pivot off the public live
1923
+ #: domain. `routes_grid._pivot_route` tries THIS bag first and reaches the tombstone only when the
1924
+ #: strict door refuses, so the tombstone expires by itself the moment a real `via` exists on that
1925
+ #: pair. Wave 43's storage ticket deletes it, and `verify_pivot.py` section 13 is the proof it may.
1926
+ #:
1927
+ #: β›” `target_key` AND `scope_key` ARE REQUIRED AND ARE NOT DIM NAMES. This is the trap the
1928
+ #: contract names by hand, because both LOOK like the two dims sitting beside them. `target_dim`
1929
+ #: is a dim of the TOPIC (`product_code` on `sales_lines`); `target_key` is the column the TARGET
1930
+ #: GRID joins on (`code` on `product_data`), and `scope_key` is the cohort bucket (`customer`).
1931
+ #: Validating either as a dim refuses every legal bag; omitting either is worse β€” the target-row
1932
+ #: filter then matches nothing and the reply is a 200 with `rows: []` and NO refusal, the silent
1933
+ #: lie `_pivot_reply` exists to forbid. So both are required and neither is checked against dims.
1934
+ #:
1935
+ #: ⚠ `source_key` IS DELIBERATELY ABSENT, and it is the seventh key of the route table rather than
1936
+ #: a forgotten one. `grid_pivot` only ever self-checked it (`!= "pid"` -> 500) and never passed it
1937
+ #: downstream, so it dies WHEN THE TOMBSTONE DOES, not before. Do not add it: `_clean_via` refuses it by name
1938
+ #: through this very allowlist, and `verify_pivot.py` asserts that refusal.
1939
+ #:
1940
+ #: β›” THE ORDER OF THESE NAMES IS NOT DECORATIVE β€” `verify_pivot.py` extracts the keys
1941
+ #: `_clean_via` actually reads FROM ITS AST and asserts they are exactly this tuple. A key added
1942
+ #: here with no `raw.get('<key>')` beside it (or read through a `for key in (...)` loop, which the
1943
+ #: extractor cannot see) turns that gate red rather than shipping a key the client can send and
1944
+ #: the server silently drops.
1945
+ LINK_VIA_KEYS = ('topic', 'source_dim', 'target_dim', 'target_key', 'scope_key', 'measure',
1946
+ 'filter', 'filterConj', 'window')
1947
+
1948
+ #: The conjunctions the hop filter may name. Mirrors `clean_filter_tree`'s own two.
1949
+ LINK_VIA_CONJ = ('and', 'or')
1950
+
1951
+ #: The date-window kinds the hop may name. β›” IT IS `ROLLUP_SOURCE_WINDOWS` ITSELF, BOUND TO A
1952
+ #: SECOND NAME RATHER THAN COPIED, so the two bags cannot drift into different calendars: this
1953
+ #: module already keeps that tuple as the local mirror of `harness/windows.py::WINDOW_KINDS`, it
1954
+ #: is what `GET /tables/rollup-sources` serves, and it is what the field editor's existing rollup
1955
+ #: branch already emits.
1956
+ #:
1957
+ #: β›”β›” THERE IS NO BARE `'all'`, AND THE NEAR-MISS IS WORTH KEEPING (wave 42 amendment A5). C1's
1958
+ #: first draft wrote `"window": "all"` while the client shipped `all_time`. Had the server
1959
+ #: accepted the alias, every hop a user built would have failed at the window WITH BOTH LANES'
1960
+ #: GATES GREEN β€” a parity gate that compares key NAMES sees a key-set match and is blind to a
1961
+ #: value mismatch. That is why `verify_pivot.py` asserts the accepted VALUE set for `window` too,
1962
+ #: and why this validator names the shared constant instead of a literal anybody could retype.
1963
+ LINK_VIA_WINDOWS = ROLLUP_SOURCE_WINDOWS
1964
+
1965
+
1966
+ def _topic_dims(topic):
1967
+ """The dim names declared by a topic, or None when nothing declares that topic.
1968
+
1969
+ β›” THE MODEL FILES, NEVER THE STORE. `harness.semantic.topics()` is a cached read of
1970
+ `platform/model/topics/*.yml` and touches no DuckDB connection at all. That is the whole
1971
+ reason this helper exists rather than a `store_columns` call: a validator that needed the
1972
+ store to say yes would refuse every legal link the moment the file was locked by a
1973
+ `validate.py` run or cold after a restart, and the user would see a correctly configured
1974
+ column refused for reasons nothing on screen could explain.
1975
+
1976
+ ⚠ The import is function-local for the reason `_ag_formula` states two hundred lines up:
1977
+ `core` must stay importable without the layers above it, and one module-level `import
1978
+ harness...` here is how the API's boot path grows a cycle.
1979
+ """
1980
+ if not topic:
1981
+ return None
1982
+ try:
1983
+ from harness import semantic as _sem
1984
+ t = (_sem.topics() or {}).get(topic)
1985
+ except Exception:
1986
+ # β›” FAIL CLOSED. An unreadable model is not a licence to accept an unvalidated topic;
1987
+ # it is a reason to refuse until somebody can say what the topic means.
1988
+ return None
1989
+ if not t:
1990
+ return None
1991
+ dims = ((t.get('store') or {}).get('dims')) or {}
1992
+ return frozenset(dims) or None
1993
+
1994
+
1995
+ def _clean_via_filter(raw, depth=1, budget=None):
1996
+ """The hop's condition tree, SHAPE-validated, or None (refuse the field).
1997
+
1998
+ β›” SHAPE ONLY, AND THAT IS THE DIVISION OF LABOUR C1 DRAWS. Whether `category` is a real
1999
+ column of `sales_lines` is answered by `harness/semantic.py::_clean_tree(tree,
2000
+ store_columns(topic))` on the way to the engine (W42-T06's ticket), never here and NEVER by
2001
+ `_clean_rollup`, whose source-backed branch returns before it reads a filter at all. What
2002
+ this function guarantees is that what got stored is a `FilterNode[]` at all: a list of
2003
+ objects, nested no deeper than the shared cap, with JSON-shaped values.
2004
+
2005
+ β›” IT REFUSES RATHER THAN TRUNCATES, matching `_clean_tree` and departing from
2006
+ `clean_filter_tree` on purpose. Dropping an AND-condition WIDENS the set the hop measures
2007
+ while the column keeps its name, which is the silent-different-answer failure
2008
+ [[no-unverifiable-aggregates]] forbids. The client's cap is a per-render DoS guard where a
2009
+ dropped leaf is the lesser evil; a stored one is not.
2010
+ """
2011
+ import aios_grid as _agv
2012
+ if budget is None:
2013
+ budget = [_agv.MAX_FILTER_NODES]
2014
+ if not isinstance(raw, list):
2015
+ return None
2016
+ if len(raw) > _agv.MAX_FILTER_SIBLINGS:
2017
+ return None
2018
+ out = []
2019
+ for node in raw:
2020
+ if not isinstance(node, dict):
2021
+ return None
2022
+ budget[0] -= 1
2023
+ if budget[0] < 0:
2024
+ return None
2025
+ children = node.get('children')
2026
+ if isinstance(children, list):
2027
+ if depth >= _agv.MAX_FILTER_DEPTH:
2028
+ return None
2029
+ kids = _clean_via_filter(children, depth + 1, budget)
2030
+ if kids is None:
2031
+ return None
2032
+ out.append({'conj': 'or' if node.get('conj') == 'or' else 'and', 'children': kids})
2033
+ continue
2034
+ leaf = {}
2035
+ for k, v in node.items():
2036
+ if not isinstance(k, str):
2037
+ return None
2038
+ if isinstance(v, str):
2039
+ leaf[k] = v[:500]
2040
+ elif isinstance(v, (int, float, bool)) or v is None:
2041
+ leaf[k] = v
2042
+ elif isinstance(v, (list, dict)):
2043
+ # A CG-8 measure condition carries a nested `window` object, so a leaf may hold
2044
+ # structure. It is passed on untouched for the engine's own validator to judge;
2045
+ # what is refused is anything that is not JSON at all.
2046
+ leaf[k] = v
2047
+ else:
2048
+ return None
2049
+ out.append(leaf)
2050
+ return out
2051
+
2052
+
2053
+ def _clean_via(raw):
2054
+ """One `via` hop bag β†’ the stored shape, or None (REFUSE THE WHOLE FIELD).
2055
+
2056
+ β›”β›” THE ONE-HOP CAP IS THE FIRST LINE OF THIS FUNCTION AND IT IS HAND-WRITTEN. `_clean_link`
2057
+ is flat and reads six named keys, silently dropping every other key on the bag β€” so a `via`
2058
+ nested inside a `via` would be DROPPED, not refused, and the field would store a two-hop
2059
+ configuration wearing a one-hop shape. Recursing into the sub-bag would be exactly as blind.
2060
+ The check is `'via' in raw`, MEMBERSHIP AND NOT TRUTHINESS: `{'via': None}` and `{'via': {}}`
2061
+ are both falsy, and a `.get()` test would wave both through and drop the key, which is the
2062
+ silent failure this cap exists to make impossible.
2063
+
2064
+ ⚠ The allowlist below would also catch a nested `via` (it is not one of the nine names). That
2065
+ redundancy is deliberate and the order is load-bearing: C1 requires the cap to be a check
2066
+ somebody WROTE, not a side effect of an allowlist that a later ticket might loosen to admit a
2067
+ tenth key.
2068
+
2069
+ β›” THE ALLOWLIST IS INSIDE THE `via` BAG ONLY, never on the outer `link` bag. W42-T35 adds a
2070
+ SECOND and different filter to the outer bag β€” a condition tree over the TARGET database's own
2071
+ columns, restricting which records a person may pick β€” and a strict outer allowlist would
2072
+ refuse it before it could land. `via.filter` filters the middle TOPIC; they are two keys, two
2073
+ validators and two tickets.
2074
+ """
2075
+ if not isinstance(raw, dict):
2076
+ return None
2077
+ if 'via' in raw:
2078
+ return None # the cap. Membership, not truthiness. See the docstring.
2079
+ for key in raw:
2080
+ if key not in LINK_VIA_KEYS:
2081
+ return None
2082
+ # β›” Each key is read by a LITERAL `raw.get('<name>')`. A `for key in (...)` loop would be
2083
+ # shorter and would make `verify_pivot.py`'s AST extraction blind to every key in it, so the
2084
+ # gate would assert parity over a set that quietly excluded them.
2085
+ topic = str(raw.get('topic') or '').strip()
2086
+ dims = _topic_dims(topic)
2087
+ if not dims:
2088
+ return None
2089
+ source_dim = str(raw.get('source_dim') or '').strip()
2090
+ target_dim = str(raw.get('target_dim') or '').strip()
2091
+ if source_dim not in dims or target_dim not in dims:
2092
+ return None
2093
+ # β›” NOT DIMS, AND NOT DEFAULTED FROM `on`. `target_key` and C1's example `on` both read
2094
+ # `code` here, which makes a fallback look free; it is not, because then a bag that omits
2095
+ # `target_key` would be silently repaired instead of refused, and the refusal is the whole
2096
+ # point of requiring it.
2097
+ target_key = _field_key(raw.get('target_key'))
2098
+ scope_key = _field_key(raw.get('scope_key'))
2099
+ measure = _field_key(raw.get('measure'))
2100
+ if not target_key or not scope_key or not measure:
2101
+ return None
2102
+ out = {'topic': topic, 'source_dim': source_dim, 'target_dim': target_dim,
2103
+ 'target_key': target_key, 'scope_key': scope_key, 'measure': measure}
2104
+ raw_filter = raw.get('filter')
2105
+ if raw_filter is not None:
2106
+ nodes = _clean_via_filter(raw_filter)
2107
+ if nodes is None:
2108
+ return None
2109
+ out['filter'] = nodes
2110
+ raw_conj = raw.get('filterConj')
2111
+ if raw_conj is not None:
2112
+ conj = str(raw_conj).strip().lower()
2113
+ if conj not in LINK_VIA_CONJ:
2114
+ return None
2115
+ out['filterConj'] = conj
2116
+ raw_window = raw.get('window')
2117
+ if raw_window is not None:
2118
+ window = str(raw_window).strip().lower()
2119
+ if window not in LINK_VIA_WINDOWS:
2120
+ return None
2121
+ out['window'] = window
2122
+ return out
2123
+
2124
+
2125
+ #: ⭐⭐ W42-T35 / AMENDMENT A34 (2026-08-25) β€” THE LEAF KEYS A RECORD-SELECTION RULE MAY CARRY.
2126
+ #:
2127
+ #: The feature: *"a link field can restrict which records are selectable"*. Airtable badges it
2128
+ #: *Filter record selection by a condition*, a THIRD toggle beside *Allow linking to multiple
2129
+ #: records* (this bag's `single`) and *Limit record selection to a view* (a curated row set, a
2130
+ #: different feature that is not built here).
2131
+ #:
2132
+ #: β›”β›” IT IS AN ALLOWLIST, AND THAT IS THE ENTIRE SAFETY ARGUMENT. Airtable's condition row
2133
+ #: carries a gear offering STATIC (*"filter all records by the same condition"*) or DYNAMIC
2134
+ #: (*"filter records based on a field in this table"*), and DYNAMIC IS CHECKED BY DEFAULT in its
2135
+ #: own documentation. `ROLLUP_CONDITION_OPS`' vocabulary has LITERAL right-hand sides only, so it
2136
+ #: cannot express the dynamic mode at all: there is nowhere for "the value of a column on the ROW
2137
+ #: BEING EDITED" to live. Meanwhile `_clean_link` builds its bag key by key and drops everything
2138
+ #: else in silence, with no unknown-key rejection on the outer bag. Put those two facts together
2139
+ #: and a dynamic leaf would be STORED AS THOUGH IT WERE STATIC, and the picker would offer the
2140
+ #: WRONG RECORD SET with nothing red anywhere. A filter resolving against the wrong operand is
2141
+ #: worse than no filter.
2142
+ #:
2143
+ #: So the refusal cannot be a blocklist of marker names somebody guessed: a marker not on the
2144
+ #: guess list ships as static, which is the exact failure. This is `_clean_via`'s discipline
2145
+ #: (`if key not in LINK_VIA_KEYS`) applied one level out, so `mode`, `dynamic`, `sourceField`,
2146
+ #: `fromField` and whatever the client calls it next quarter are all refused BY NAME for free,
2147
+ #: and `ref`/`sigmas` go with them (see `_clean_link_conditions`). The dynamic half is wave 43's,
2148
+ #: booked as D-568.
2149
+ LINK_FILTER_LEAF_KEYS = ('field', 'op', 'value')
2150
+
2151
+
2152
+ def _clean_link_conditions(raw, columns=None):
2153
+ """The `conditions` / `conditionConj` half of a `link` bag.
2154
+
2155
+ Returns `(the keys to store, None)` or `(None, the sentence the refusal owes the user)`.
2156
+
2157
+ β›”β›” THIS IS NOT `via.filter`, AND CONFUSING THE TWO SHIPS ONE FEATURE TWICE. `via.filter`
2158
+ (`_clean_via_filter`, one screen up) lives INSIDE the `via` bag, is a `FilterNode[]` in
2159
+ `aios_grid`'s client vocabulary, is validated against `store_columns(topic)` by
2160
+ `harness/semantic.py` on the way to the engine, and filters the MIDDLE TOPIC of a two-hop
2161
+ pivot. This one lives on the link bag's TOP LEVEL, speaks `_clean_rollup`'s vocabulary, is
2162
+ validated against the TARGET DATABASE's own columns, and decides WHICH RECORDS A PERSON MAY
2163
+ PICK IN A CELL. Two keys, two validators, two consumers.
2164
+
2165
+ ⚠ AND THE KEY NAMES ARE `_clean_rollup`'s TOO, DELIBERATELY. A repo-wide grep for
2166
+ `conditionConj` now answers from two bags, exactly as the `single` note at `_clean_field`'s
2167
+ `user` arm describes for its own word. There is no collision to fix: these live in
2168
+ `field['link']`, the twin lives in `field['rollup']`, a field carries one bag or the other and
2169
+ the type/bag pairing is enforced both ways. Reusing the names is what says the two speak the
2170
+ SAME vocabulary; inventing a synonym would have implied they might not.
2171
+
2172
+ ⭐ THE VOCABULARY IS `_clean_rollup`'s, BY SYMBOL AND NEVER BY COPY: `ROLLUP_CONDITION_OPS`,
2173
+ `ROLLUP_CONDITION_CONJ`, `ROLLUP_MAX_CONDITIONS`. A second copy of an operator list is how two
2174
+ validators start disagreeing about what a filter means, and the disagreement is silent on both
2175
+ sides.
2176
+
2177
+ β›” FLAT, NOT NESTED, mirroring `_clean_rollup`'s own loop rather than `_clean_via_filter`'s
2178
+ recursion. A nested tree would drag in `aios_grid`'s depth/sibling/budget caps and with them
2179
+ the second vocabulary this docstring exists to keep out. One list plus one conjunction is what
2180
+ the ops above can express; deeper grouping lands when the ops do.
2181
+
2182
+ β›” `ref` / `sigmas` ARE REFUSED, and it is `_clean_rollup`'s OWN decision reused rather than a
2183
+ new one: its `where` branch passes `allow_ref=False` because a set-statistic threshold needs a
2184
+ FOLDED SET to be a statistic OF. A record picker folds nothing, so `mean + k*stdev` here has
2185
+ no set to compute over and would freeze into whatever the first read happened to see. The leaf
2186
+ allowlist above refuses both names without a branch of their own.
2187
+
2188
+ ⚠ `columns=None` MEANS NOT CHECKED; `frozenset()` MEANS THE TARGET HAS NO COLUMNS. Collapsing
2189
+ the two would make an unresolvable target refuse every legal rule with a sentence that reads
2190
+ like the user typed the column name wrong. `_clean_link` passes `None` so that
2191
+ `_clean_field(f) == f` still round-trips a stored field with no store in reach; the write
2192
+ doors pass the real set in through `link_filter_refusal`.
2193
+ """
2194
+ raw_conditions = raw.get('conditions')
2195
+ if raw_conditions is None:
2196
+ return {}, None
2197
+ if not isinstance(raw_conditions, list):
2198
+ return None, 'A record filter has to be a list of rules.'
2199
+ if len(raw_conditions) > ROLLUP_MAX_CONDITIONS:
2200
+ return None, (f'A link may carry at most {ROLLUP_MAX_CONDITIONS} record filter rules, '
2201
+ f'and this one carries {len(raw_conditions)}.')
2202
+ conditions = []
2203
+ for condition in raw_conditions:
2204
+ if not isinstance(condition, dict):
2205
+ return None, 'Every record filter rule has to be an object.'
2206
+ # β›”β›” A34, AND IT IS THE FIRST THING THE LOOP DOES. Naming the offending key before the
2207
+ # rule is read at all is what makes a dynamic leaf a REFUSAL WITH AN ADDRESS instead of a
2208
+ # silent coercion to static.
2209
+ for key in condition:
2210
+ if key not in LINK_FILTER_LEAF_KEYS:
2211
+ return None, (f'A record filter rule cannot carry "{key}". This link filters by '
2212
+ f'a fixed value only. A rule that reads a field on the row being '
2213
+ f'edited is refused rather than saved as a fixed one, because a '
2214
+ f'filter resolved against the wrong column offers the wrong '
2215
+ f'records with nothing to notice.')
2216
+ condition_field = _field_key(condition.get('field'))
2217
+ op = str(condition.get('op') or '').strip().lower()
2218
+ if not condition_field:
2219
+ return None, 'Every record filter rule has to name a column of the linked database.'
2220
+ if op not in ROLLUP_CONDITION_OPS:
2221
+ return None, f'"{op}" is not a comparison a record filter understands.'
2222
+ # ⭐ THE LEFT OPERAND IS A COLUMN OF THE TARGET, which is what Airtable's own picker
2223
+ # caption says in as many words: *"Choose a field from the people in the linked table"*.
2224
+ if columns is not None and condition_field not in columns:
2225
+ return None, (f'The linked database has no column named "{condition_field}". Pick a '
2226
+ f'column it has, or drop that rule.')
2227
+ item = {'field': condition_field, 'op': op}
2228
+ if op not in ('is_empty', 'is_not_empty'):
2229
+ value = condition.get('value')
2230
+ if not isinstance(value, (str, int, float, bool)):
2231
+ return None, (f'The rule on "{condition_field}" needs a value to compare '
2232
+ f'against.')
2233
+ item['value'] = str(value)[:1000]
2234
+ conditions.append(item)
2235
+ if not conditions:
2236
+ return {}, None
2237
+ conj = str(raw.get('conditionConj') or 'and').strip().lower()
2238
+ if conj not in ROLLUP_CONDITION_CONJ:
2239
+ return None, f'"{conj}" is not a way record filter rules can be joined.'
2240
+ return {'conditions': conditions, 'conditionConj': conj}, None
2241
+
2242
+
2243
+ def _clean_link(raw, columns=None):
2244
  """One `link` bag β†’ the stored shape, or None (refused).
2245
 
2246
  Same posture as `_clean_metric`: a mis-shaped bag REFUSES THE FIELD. A link column stored
 
2288
  # than dropped: a bag half of which is silently ignored is [[wrong-parent-not-broken-control]]
2289
  # with the control still on screen.
2290
  return None
2291
+ # ⭐⭐ W42-T03 / R1 / C1 β€” THE SECOND HOP. Absent, this block does nothing and the bag above is
2292
+ # byte-identical to what it has always been.
2293
+ #
2294
+ # β›” IT RIDES THE `on` BRANCH AND NOWHERE ELSE, and that is a decision rather than an
2295
+ # oversight. A hop needs a first join to hop FROM. An `inverse` link is computed from the far
2296
+ # side and has no `on` at all, so a `via` on one stores a promise nothing can resolve β€” the
2297
+ # same thing this function already refuses for a `from` with no `on`, two branches up. A
2298
+ # `via` arriving on an inverse or on an unconfigured bag therefore refuses the whole field
2299
+ # rather than being dropped into a column that would silently answer a one-hop question.
2300
+ if raw.get('via') is not None:
2301
+ if 'on' not in out:
2302
+ return None
2303
+ via = _clean_via(raw.get('via'))
2304
+ if via is None:
2305
+ return None
2306
+ out['via'] = via
2307
  if reciprocal:
2308
  out['reciprocal'] = reciprocal
2309
  if raw.get('single') is True:
2310
  out['single'] = True
2311
+ # ⭐⭐ W42-T35 β€” WHICH RECORDS A PERSON MAY PICK. Absent, this block does nothing and the bag
2312
+ # above is byte-identical to what it has always been.
2313
+ #
2314
+ # β›” IT RIDES THE PICKABLE BRANCH AND NOWHERE ELSE. A restriction on a picker needs a picker,
2315
+ # and `is_derived_link` is the one definition of which links have none: an `on` join or an
2316
+ # `inverse` backlink is computed by the engine, so `patch_link_cell` already refuses to take
2317
+ # a human write on either. Storing a record filter there would be a control the editor shows
2318
+ # and nothing can ever apply, which is the same silence this function refuses two branches up
2319
+ # for a `from` with no `on`. The whole field is refused rather than the key dropped.
2320
+ #
2321
+ # β›” AND IT IS A DEFINITION FLAG, NOT A RETROACTIVE DELETE, exactly as the `user` column's
2322
+ # `single` note says of its own. Records linked before the filter existed stay linked and
2323
+ # visible because NOTHING here or in any reader touches a cell: `compute_relation_cells`,
2324
+ # `patch_link_cell`'s `valid` set and every rollup fold read the target's rows, never this
2325
+ # key. Applying it on read would delete links nobody asked to remove, invisibly, on a store
2326
+ # with no history to undo it ([[a-cleanup-deletes-what-it-did-not-create]]).
2327
+ if raw.get('conditions') is not None:
2328
+ if out.get('on') or out.get('inverse'):
2329
+ return None
2330
+ picked, _sentence = _clean_link_conditions(raw, columns)
2331
+ if picked is None:
2332
+ return None
2333
+ out.update(picked)
2334
  return out
2335
 
2336
 
2337
+ def link_target_columns(table_key, st=None):
2338
+ """The column keys a link TARGET database actually has, or None when nothing can answer.
2339
+
2340
+ β›” `None` IS NOT AN EMPTY SET, and collapsing the two is the failure this signature exists to
2341
+ prevent. `frozenset()` says "this database has no columns" and correctly refuses every rule;
2342
+ `None` says "nobody here can say", which is a reason to refuse the FILTER naming that reason,
2343
+ not to refuse each column with a sentence that reads like the user typed the name wrong.
2344
+
2345
+ ⚠ TWO NAMESPACES, the same two `is_linkable_target` allows. A `ut_*` database answers from
2346
+ its own stored `fields`; the two registry modules answer from `aios_grid`, which is where
2347
+ `routes_tables::_module_link_targets` already reads their column lists for the field editor's
2348
+ own dropdown, so the offer and the check cannot disagree about what a column is.
2349
+
2350
+ ⚠ The import is function-local for the reason `_topic_dims` states: `core` must stay
2351
+ importable without the layers above it.
2352
+ """
2353
+ key = str(table_key or '')
2354
+ if key in LINKABLE_MODULE_KEYS:
2355
+ try:
2356
+ import aios_grid as _agl
2357
+ fields = _agl.FIELDS if key == 'customer_data' else _agl.product_fields()
2358
+ except Exception:
2359
+ return None # fail closed: an unreadable grid answers nothing
2360
+ cols = frozenset(str(f.get('key') or '') for f in (fields or [])
2361
+ if isinstance(f, dict) and f.get('key'))
2362
+ return cols or None
2363
+ if not is_linkable_target(key):
2364
+ return None
2365
+ defn = get(key, st)
2366
+ if not isinstance(defn, dict):
2367
+ return None
2368
+ return frozenset(str(f.get('key') or '') for f in (defn.get('fields') or [])
2369
+ if isinstance(f, dict) and f.get('key'))
2370
+
2371
+
2372
+ def link_filter_refusal(raw_bag, st=None):
2373
+ """The sentence a refused record filter owes the user, or None when the filter is acceptable.
2374
+
2375
+ β›”β›” IT EXISTS BECAUSE `_clean_link` HAS NO ERROR CHANNEL, and `verify_pivot.py` section 18
2376
+ booked that gap by name: *"the refusal NAMES the missing key ... cannot be observed from
2377
+ here: `_clean_via` returns a bare None, `_clean_link` returns None ... The naming half belongs
2378
+ to a user_tables ticket."* This is that ticket, and this is that half. The shape is
2379
+ `ai_enrich_dropped_keys`': a SEPARATE reporting function reading the SAME validator, never a
2380
+ second copy of the rules.
2381
+
2382
+ β›” IT READS THE RAW BAG, NEVER THE STORED ONE. A dynamic leaf cannot survive `_clean_link`, so
2383
+ a function handed the cleaned bag would have nothing left to name.
2384
+
2385
+ ⚠ THE LAW IS `_clean_link`; THIS IS THE SENTENCE. Same split `add_field`'s one-profile-column
2386
+ rule already uses ("the route names the existing column in its refusal; the LAW is here"), so
2387
+ a route that forgets to print this still cannot store a filter the target cannot satisfy.
2388
+ """
2389
+ if not isinstance(raw_bag, dict) or raw_bag.get('conditions') is None:
2390
+ return None
2391
+ if raw_bag.get('on') or raw_bag.get('inverse'):
2392
+ return ('A record filter belongs on a link whose records a person picks. This link is '
2393
+ 'computed by the server, so there is no picker to restrict.')
2394
+ # β›”β›” THE SHAPE PASS RUNS FIRST, AND THE ORDER IS THE A34 CLAUSE. A dynamic leaf is refused
2395
+ # BY NAME whether or not the target's columns can be read: resolving columns first would
2396
+ # answer a bag carrying `mode: "dynamic"` with "the columns cannot be read", which names the
2397
+ # wrong thing and points the user at the wrong fix. Caught by this ticket's own probe, which
2398
+ # went 37/55 with the two calls the other way round.
2399
+ _shape, sentence = _clean_link_conditions(raw_bag, None)
2400
+ if sentence:
2401
+ return sentence
2402
+ table = _field_key(raw_bag.get('table'))
2403
+ columns = link_target_columns(table, st)
2404
+ if columns is None:
2405
+ return (f'The columns of the linked database "{table}" cannot be read right now, so a '
2406
+ f'record filter on it cannot be checked. Remove the filter, or try again.')
2407
+ _picked, sentence = _clean_link_conditions(raw_bag, columns)
2408
+ return sentence
2409
+
2410
+
2411
  def _clean_rollup(raw):
2412
  """One `rollup` bag β†’ the stored shape, or None (refused).
2413
 
 
2889
  # `raw.get('format')`, exactly like `description` below: an explicit `{}`/None CLEARS the
2890
  # format, while omitting the key keeps what is stored. A PATCH that sends only a label must not
2891
  # silently strip a formatting choice β€” that is how `agg` stopped totalling a money column.
2892
+ fmt = _clean_format(raw.get('format') if 'format' in raw else prev.get('format'), ftype)
2893
  if fmt:
2894
  out['format'] = fmt
2895
  # Canonical descriptions are schema metadata, not the user's per-view note. Preserve them
 
2932
  out['note'] = note
2933
  opts_raw = raw.get('options') if 'options' in raw else prev.get('options')
2934
  if ftype in ('select', 'multiselect'):
2935
+ # ⭐⭐ W42-T36 β€” the SAME declared cap as `clean_fields`, and the same refuse-do-not-truncate
2936
+ # posture. β›” THE DOORS DIFFER IN WHAT THEY REFUSE, deliberately: this validator is handed
2937
+ # ONE field and its only refusal is `None`, which is `metric`/`profile`/`link`'s posture
2938
+ # and what `add_field`/`patch_field` turn into a 400. A silent `[:MAX_OPTIONS]` here would
2939
+ # be the 51st option vanishing under a 200 response, which is the exact behaviour the cap
2940
+ # was raised to stop being invisible.
2941
+ opts = [' '.join(str(o).split())[:60] for o in (opts_raw or []) if str(o).strip()]
2942
+ if len(opts) > MAX_OPTIONS:
2943
+ return None
2944
  if opts:
2945
  out['options'] = opts
2946
  # ⭐⭐ WAVE-29 CONTRACT C1 (owner item 13) β€” **THE OPTION COLOURS, WHICH THIS DOOR DROPPED.**
 
2982
  else prev.get('colorCodeOptions'))
2983
  if isinstance(color_code, bool):
2984
  out['colorCodeOptions'] = color_code
2985
+ # ⭐⭐ W42-T32 β€” THE COLUMN'S OWN DEFAULT VALUE, VALIDATED AGAINST WHAT THE COLUMN MEANS.
2986
+ #
2987
+ # ⚠ PLACED AFTER THE OPTIONS BLOCK ON PURPOSE. A select's default is checked against
2988
+ # `out['options']`, which is computed twenty lines up; validated before that it would compare
2989
+ # against an empty list and pass vacuously for every value β€” a leg that iterates the RESULT
2990
+ # rather than the REQUIREMENT.
2991
+ #
2992
+ # ⚠ `'defaultValue' in raw` β€” the `format`/`description`/`agg` idiom, and the done-when's
2993
+ # "clearing is distinguishable from never having set one" clause IS this idiom. Written the
2994
+ # loose way (`raw.get(...) or prev.get(...)`) an explicit `None` from the pane's "no default"
2995
+ # row would inherit the stored value and the control would be a no-op with the menu cheerfully
2996
+ # showing the change. It also settles the falsy question: `0` and `False` are real defaults and
2997
+ # survive, because presence is asked with `in` and emptiness with `is None`.
2998
+ #
2999
+ # β›” INHERITANCE IS GUARDED ON `prev_type == ftype`, exactly like `link`/`rollup`/`formula`.
3000
+ # Retyping a select column to `int` must not resurrect the old select default through `prev`,
3001
+ # fail its new vocabulary and REFUSE THE WHOLE PATCH β€” that is the bug those guards record,
3002
+ # and here it would make a select column impossible to retype at all.
3003
+ _prev_type_dv = str(prev.get('type') or '').strip().lower()
3004
+ if 'defaultValue' in raw or (_prev_type_dv == ftype and 'defaultValue' in prev):
3005
+ dv_raw = (raw.get('defaultValue') if 'defaultValue' in raw
3006
+ else prev.get('defaultValue'))
3007
+ dv = _clean_default_value(dv_raw, ftype, out.get('options') or [])
3008
+ if dv is _DEFAULT_REFUSED:
3009
+ return None
3010
+ if dv is not None:
3011
+ out['defaultValue'] = dv
3012
+ # ⭐ W42-T32 β€” ONE PERSON, NOT MANY, on a `user` column.
3013
+ #
3014
+ # β›”β›” NAME COLLISION, AND THE TWO KEYS LIVE AT DIFFERENT LEVELS. `_clean_link` already stores a
3015
+ # `single` (:1859) meaning "this LINK holds one record" β€” but it stores it INSIDE the link bag
3016
+ # (`field['link']['single']`), while this one is a top-level key on a `user` column meaning
3017
+ # "one person". Two keys, one word, two meanings; the `ftype == 'user'` guard is what stops
3018
+ # either validator answering for the other, and it must not be relaxed into a generic arm.
3019
+ #
3020
+ # ⚠ IT IS A DEFINITION FLAG, NOT A READ-TIME TRUNCATION. Switching an existing multi-value
3021
+ # `user` column to single must leave the stored cells exactly as they are until somebody next
3022
+ # edits one: truncating on read would delete names nobody asked to remove, and would do it
3023
+ # invisibly, on a store with no history to undo it ([[a-cleanup-deletes-what-it-did-not-create]]).
3024
+ # Nothing here or in any reader touches a cell, which is how that clause is satisfied.
3025
+ if ftype == 'user':
3026
+ single_raw = (raw.get('single') if 'single' in raw
3027
+ else (prev.get('single') if _prev_type_dv == 'user' else None))
3028
+ if single_raw is True:
3029
+ out['single'] = True
3030
  # ⭐ WAVE-29 T22's own repair: a `rating` column's star count. Grid-created columns on a `ut_*`
3031
  # database now come through this door rather than the per-user overlay, and this validator had
3032
  # no `max` β€” so a 3-star or 10-star column silently became 5-star on the way in. Bounded rather
 
3039
  out['max'] = max(2, min(int(max_raw), 10))
3040
  except (TypeError, ValueError):
3041
  pass
3042
+ # ⭐ W42-T32 β€” the SHAPE those 1..max marks are drawn as. Bounded by `RATING_SYMBOLS`,
3043
+ # whose note explains why that tuple has one member and what a wave-43 ticket must extend
3044
+ # FIRST. An unknown name is DROPPED rather than refusing the field, `max`'s posture and
3045
+ # `code`'s reasoning: a symbol chooses a GLYPH over a rating the column already holds, so
3046
+ # an unusable value is a default and never a lost column.
3047
+ # β›” OMIT-WHEN-ABSENT. Stamping `symbol: 'star'` on every rating column would break the
3048
+ # `_clean_field(f) == f` identity two gates assert over every engine-seeded field list;
3049
+ # `rating_symbol()` is the reader that resolves absence to the default.
3050
+ sym = str((raw.get('symbol') if 'symbol' in raw else prev.get('symbol'))
3051
+ or '').strip().lower()
3052
+ if sym in RATING_SYMBOLS:
3053
+ out['symbol'] = sym
3054
+ # ⭐ W42-T32 β€” THE CHECKBOX'S MARK: which glyph, and in what colour.
3055
+ #
3056
+ # βœ… A HEX IS VALIDATED; BRAND MEMBERSHIP IS NOT, and this is not a new policy β€” it is the one
3057
+ # `_clean_option_colors` twenty screens up already states, with its reasons. The client maps a
3058
+ # stored colour to its nearest brand swatch at DISPLAY time (`choiceColors.brandedTint`),
3059
+ # keeping the stored value byte-stable, so refusing a non-brand hex here would refuse values
3060
+ # the sibling validator accepts on the same UI and would break a column that moved between the
3061
+ # two. "From the brand swatches" describes the PICKER, not the wall.
3062
+ # ⚠ A MALFORMED HEX IS DROPPED, matching `_clean_option_colors` exactly: same question, same
3063
+ # answer, or the two doors start disagreeing about what a colour is.
3064
+ if ftype == 'checkbox':
3065
+ icon = str((raw.get('icon') if 'icon' in raw else prev.get('icon'))
3066
+ or '').strip().lower()
3067
+ if icon in CHECKBOX_ICONS:
3068
+ out['icon'] = icon
3069
+ color_raw = raw.get('color') if 'color' in raw else prev.get('color')
3070
+ color = str(color_raw or '').strip().upper()
3071
+ if _OPTION_COLOR_RE.fullmatch(color):
3072
+ out['color'] = color
3073
  role = str(raw.get('editRole') or prev.get('editRole') or 'admins').strip().lower()
3074
  out['editRole'] = role if role in FIELD_EDIT_ROLES else 'admins'
3075
  if prev.get('default') is True or raw.get('default') is True:
 
3345
  label = f.get('label') or f.get('key') or 'that column'
3346
  if ftype in _NUMERIC_CELL_TYPES:
3347
  try:
3348
+ number = float(text.replace('$', '').replace(',', '')
3349
+ .replace('%', '').replace(' ', ''))
3350
  except (TypeError, ValueError):
3351
  return f'{text[:40]!r} is not a number, and {label!r} holds numbers'
3352
+ # ⭐⭐ W42-T33 β€” **A COLUMN THAT REFUSES NEGATIVES SAYS SO, IN A SENTENCE.**
3353
+ #
3354
+ # β›” THE WALL COULD NOT LIVE IN `_clean_format`, AND THAT IS THE WHOLE PLACEMENT NOTE.
3355
+ # That function validates a SETTING; it never sees a cell and cannot decline one. This is
3356
+ # the module's only evaluator that answers "why can this value not go in this column" with
3357
+ # words, so a rule about VALUES belongs here or it is unbuilt: the setting would store,
3358
+ # the pane would save, and a negative number would land anyway.
3359
+ # ⚠ ABSENT MEANS ALLOWED (see `_clean_format`), so this is silent for every column that
3360
+ # existed before this ticket and for every column that never opts in.
3361
+ fmt = f.get('format')
3362
+ if isinstance(fmt, dict) and fmt.get('allowNegative') is False and number < 0:
3363
+ return (f'{label!r} does not take negative numbers, and {text[:40]!r} '
3364
+ f'is below zero')
3365
  return None
3366
  if ftype == 'rating':
3367
  try:
 
3841
  # the existing column in its refusal (`_refusal_sentence`); the LAW is here.
3842
  if field.get('profile') and _profile_of(have):
3843
  return None
3844
+ # ⭐⭐ W42-T35 β€” THE RECORD FILTER IS CHECKED AGAINST THE TARGET'S OWN COLUMNS, HERE, because
3845
+ # here is the first door that holds a store. `_clean_field` cannot do it: it is also the
3846
+ # machine's validator and two gates assert `_clean_field(f) == f` over engine-seeded field
3847
+ # lists with no store in reach, so a column check inside it would refuse every legal field
3848
+ # the moment the store was cold. The RAW bag is passed, not the cleaned one, so a dynamic
3849
+ # leaf is still there to be named.
3850
+ if field.get('type') == 'link' and link_filter_refusal((raw or {}).get('link'), st):
3851
+ return None
3852
 
3853
  def _add(cur):
3854
  t = cur.get(str(table_key))
 
3878
  return f'linked_{digest}'
3879
 
3880
 
3881
+ #: The suffix a SELF-LINK's reciprocal column wears, and the room it needs inside the 80-char
3882
+ #: label ceiling `_clean_field` enforces. Declared as a pair so the budget can never drift from
3883
+ #: the string: a suffix appended without reserving room truncates straight back to the field
3884
+ #: label, and the two columns collide again with nothing anywhere going red.
3885
+ _SELF_LINK_SUFFIX = ' (backlink)'
3886
+ _SELF_LINK_LABEL_ROOM = 80 - len(_SELF_LINK_SUFFIX)
3887
+
3888
+
3889
+ def _reciprocal_label(source, source_field, table_key, target_key):
3890
+ """The label the backlink column carries. β›” TWO CASES, AND THE SPLIT IS THE WHOLE POINT.
3891
+
3892
+ ⭐⭐ W42-T31 β€” A SELF-LINK'S RECIPROCAL WAS AN UNREADABLE TWIN. For a CROSS-TABLE link the
3893
+ backlink lands on the OTHER database, where naming the SOURCE DATABASE is exactly the useful
3894
+ thing: on "Orders" a backlink from "Customers.Primary contact" reads "Customers", which is
3895
+ what Airtable shows and what a person expects. That case is UNCHANGED here, deliberately.
3896
+
3897
+ β›” A SELF-LINK IS THE CASE THAT BREAKS. Target IS source, so the generated column lands on the
3898
+ same grid as the field the user just built, and `source.label` names the database BOTH columns
3899
+ already live on: "Tasks" sitting beside "Tasks", one of them inert. The user cannot tell which
3900
+ is which without opening either, and the inert one is the derived twin (`inverse` in its bag)
3901
+ that is permanently read-only and opens on zero rows.
3902
+
3903
+ β›” AND THE OBVIOUS FIX IS ALSO WRONG: stamping the FIELD's label verbatim gives two columns
3904
+ both reading "Parent task", which is the same indistinguishability wearing a better name. The
3905
+ label must be DERIVED from the field label, never equal to it β€” so the mirror names what it
3906
+ mirrors AND is legible as the mirror.
3907
+
3908
+ ⚠ The field label is truncated to leave room for the suffix. Without that reservation an
3909
+ 80-char field label truncates back to exactly the field label inside `_clean_field`, and the
3910
+ collision returns silently for precisely the columns whose names were already hard to read.
3911
+ """
3912
+ if target_key and str(target_key) == str(table_key):
3913
+ flabel = ' '.join(str((source_field or {}).get('label') or '').split())
3914
+ if flabel:
3915
+ return f'{flabel[:_SELF_LINK_LABEL_ROOM]}{_SELF_LINK_SUFFIX}'
3916
+ return str((source or {}).get('label') or table_key)[:80]
3917
+
3918
+
3919
  def sync_reciprocal_link(table_key, field_key, st=None):
3920
  """Create/repair Airtable's reciprocal link field for one ordinary link.
3921
 
 
4024
  reciprocal_key = _reciprocal_link_key(table_key, field_key)
4025
  reciprocal = _clean_field({
4026
  'key': reciprocal_key,
4027
+ 'label': _reciprocal_label(source, source_field, table_key, target_key),
4028
  'type': 'link',
4029
  'link': {'table': table_key, 'inverse': field_key,
4030
  'reciprocal': field_key},
 
4049
  return result
4050
 
4051
 
4052
+ #: ⭐⭐ W42-T34 β€” **THE ONE DECLARED COERCION TABLE.** What happens to a stored cell when its
4053
+ #: column changes type, keyed by the TARGET type and by nothing else.
4054
+ #:
4055
+ #: β›” IT IS A TABLE, NOT A CHAIN OF `if`s SPREAD THROUGH THE WRITER, and that is the whole shape of
4056
+ #: the ticket. A second copy of "what does a retype mean" is how two surfaces start disagreeing
4057
+ #: about it, which this module has paid for with `agg`, `format`, `optionColors` and `note`.
4058
+ #:
4059
+ #: β›” KEYED ON TYPE, NEVER ON FORMAT. A `duration`-formatted `int` and a plain `int` must coerce
4060
+ #: identically, because a duration's stored value IS a plain integer (W42-T33) and every existing
4061
+ #: `sum`/`average` fold over that column depends on it staying one. Reading `format` here is how
4062
+ #: that guarantee would quietly stop holding.
4063
+ #:
4064
+ #: The four rules, and why each:
4065
+ #: 'meanable' β€” keep the cell iff `cell_type_refusal` says the value can BE this kind. That
4066
+ #: function is the module's existing evaluator for exactly this question; asking it
4067
+ #: again in different words is [[one-evaluator-per-question]]'s failure mode.
4068
+ #: 'boolish' β€” the checkbox contract is `'1'` or empty (`aios_grid.py:133`). Anything else is a
4069
+ #: string a BooleanCell renders as unchecked while the store says otherwise.
4070
+ #: 'keep' β€” the target renders any string, so clearing would DELETE DATA for no gain.
4071
+ #: 'clear' β€” the SERVER owns this cell now (`is_computed_cell`'s family). A human string left
4072
+ #: under a rollup is a fossil that no reader agrees with and the next compute pass
4073
+ #: overwrites anyway.
4074
+ #:
4075
+ #: β›” `select`/`multiselect` ARE `keep`, AND THE NARROWING IS DELIBERATE. Clearing on option
4076
+ #: membership was the obvious reading and it is the wrong one: `cell_type_refusal`'s own note says
4077
+ #: choice vocabularies stay out of the wall because *"their options change under a stored row, and
4078
+ #: refusing an import against a vocabulary edited yesterday would reject data that is merely out of
4079
+ #: date"*. Clearing here would DELETE that same merely-stale data, on a store with no history to
4080
+ #: undo it ([[a-cleanup-deletes-what-it-did-not-create]]). We clear what the new kind cannot
4081
+ #: RENDER, not what its current vocabulary does not list.
4082
+ RETYPE_COERCIONS = {
4083
+ 'int': 'meanable', 'currency': 'meanable', 'pct': 'meanable',
4084
+ 'date': 'meanable', 'rating': 'meanable',
4085
+ 'checkbox': 'boolish',
4086
+ 'text': 'keep', 'phone': 'keep', 'email': 'keep', 'url': 'keep',
4087
+ 'json': 'keep', 'code': 'keep', 'image': 'keep', 'user': 'keep',
4088
+ 'select': 'keep', 'multiselect': 'keep', 'automation': 'keep',
4089
+ 'rollup': 'clear', 'formula': 'clear', 'link': 'clear', 'ai_enrich': 'clear',
4090
+ }
4091
+
4092
+ #: The checkbox cell vocabulary, named once so `boolish` and any later reader cannot drift.
4093
+ _CHECKBOX_CELL_VALUES = ('1', '')
4094
+
4095
+
4096
+ def _retype_survives(value, new_field):
4097
+ """Can this stored cell stay, under the new column's kind? β›” Reads `RETYPE_COERCIONS` only."""
4098
+ rule = RETYPE_COERCIONS.get(str((new_field or {}).get('type') or ''), 'keep')
4099
+ if rule == 'keep':
4100
+ return True
4101
+ if rule == 'clear':
4102
+ return False
4103
+ text = '' if value is None else str(value).strip()
4104
+ if not text:
4105
+ return True # ⚠ a blank cell is a blank cell in every column
4106
+ if rule == 'boolish':
4107
+ return str(value) in _CHECKBOX_CELL_VALUES
4108
+ return cell_type_refusal(new_field, value) is None
4109
+
4110
+
4111
+ def retype_plan(table_key, fkey, new_field, st=None):
4112
+ """What a type change WOULD clear, computed without writing anything.
4113
+
4114
+ ⭐⭐ W42-T34 (as amended by A28) β€” **THE PREVIEW PAYLOAD A DIALOG WOULD NEED.** `patch_field`
4115
+ cannot warn anybody: it is a store writer with no surface. What it CAN do is compute the count
4116
+ and the column before it writes and hand them out through a channel, which is what this is and
4117
+ what `patch_field(preview=...)` fills. No ticket this wave owns the dialog itself (D-558).
4118
+
4119
+ β›” IT IS A SEPARATE PUBLIC FUNCTION so a future dialog can ask the question WITHOUT writing.
4120
+ A preview only reachable by performing the act it previews is not a preview.
4121
+
4122
+ Returns `{'column', 'label', 'from', 'to', 'rows', 'clearing', 'rowIds'}`.
4123
+ """
4124
+ defn = get(table_key, st) or {}
4125
+ prev_field = next((f for f in (defn.get('fields') or [])
4126
+ if f.get('key') == str(fkey)), None) or {}
4127
+ rows = defn.get('rows') or {}
4128
+ hits = [str(rid) for rid, cells in rows.items()
4129
+ if isinstance(cells, dict) and str(fkey) in cells
4130
+ and not _retype_survives(cells.get(str(fkey)), new_field)]
4131
+ return {'column': str(fkey),
4132
+ 'label': str((new_field or {}).get('label') or prev_field.get('label') or ''),
4133
+ 'from': str(prev_field.get('type') or ''),
4134
+ 'to': str((new_field or {}).get('type') or ''),
4135
+ 'rows': len(rows), 'clearing': len(hits), 'rowIds': hits}
4136
+
4137
+
4138
+ def patch_field(table_key, fkey, raw, st=None, preview=None):
4139
  """Edit one column's definition IN PLACE. Returns the stored field, or None if refused.
4140
 
4141
+ ⭐⭐ W42-T34 β€” **A RETYPE NOW DOES SOMETHING HONEST TO THE CELLS.** Until this ticket `_set`
4142
+ replaced the field dict and never touched `rows` at all, so a text column retyped to `int`
4143
+ kept every cell as a string and the grid rendered whatever that does. The rewrite runs through
4144
+ `RETYPE_COERCIONS`, the ONE declared table.
4145
+
4146
+ ⚠ `preview` IS AN OUT-PARAM, NOT A CHANGED RETURN TYPE, and that is load-bearing. This
4147
+ function's return value is what `routes_tables` echoes to the client; wrapping it in a tuple or
4148
+ stuffing a preview into the field dict would break a caller outside this module's fence and
4149
+ the failure would read like a regression somewhere else. The pattern is
4150
+ `sync_reciprocal_link`'s `result` dict, one screen up: report what happened through a channel,
4151
+ leave the wall's signature alone. Pass a dict and it is filled BEFORE the store write.
4152
  ⚠ THE KEY NEVER MOVES. A field's key is what every stored cell is filed under, so accepting
4153
  a new one here would orphan every value in the column while looking like a rename. The
4154
  LABEL is the renameable thing; the key is identity.
 
4185
  # as adding one. `exclude=fkey` so re-saving the profile column does not collide with itself.
4186
  if field.get('profile') and _profile_of(fields, exclude=str(fkey)):
4187
  return None
4188
+ # W42-T35 β€” the column check rides the EDIT door too, for the reason the profile rule above
4189
+ # names: a law taught to only one of the two doors is a law the other silently permits.
4190
+ if field.get('type') == 'link' and link_filter_refusal(merged.get('link'), st):
4191
+ return None
4192
  # ⭐⭐ 2026-08-09 β€” THE CUSTODY STAMP IS WRITTEN HERE, at the ONE door a human reaches.
4193
  #
4194
  # `USER_EDITED_KEY`'s note has the why. It is written here rather than inside `_clean_field`
 
4226
  and not description_edited(field) and not user_edited(field):
4227
  field.pop('note', None)
4228
 
4229
+ # ⭐⭐ W42-T34 β€” THE PLAN IS COMPUTED BEFORE THE WRITE, and only for a genuine TYPE CHANGE.
4230
+ # β›” `prev['type'] != field['type']` IS THE WHOLE TRIGGER. Anything looser reprocesses every
4231
+ # cell on every rename, which on a 28.6 MB store is a silent full-document rewrite for a
4232
+ # header edit. It is also what protects W42-T32's preservation clause: flipping a `user`
4233
+ # column's `single` is not a type change, so its multi-value cells are never walked.
4234
+ plan = None
4235
+ if str(fields[idx].get('type') or '').strip().lower() != field['type']:
4236
+ plan = retype_plan(table_key, fkey, field, st)
4237
+ if isinstance(preview, dict):
4238
+ preview.update({k: v for k, v in plan.items() if k != 'rowIds'})
4239
+ preview['rewrote'] = False
4240
+
4241
  def _set(cur):
4242
  t = cur.get(str(table_key))
4243
  if t is not None:
 
4245
  if f.get('key') == str(fkey):
4246
  t['fields'][i] = field
4247
  break
4248
+ # ⭐⭐ THE BYTE-IDENTITY CLAUSE LIVES IN THIS `if`. A retype that clears nothing must
4249
+ # leave the rows EXACTLY as they were, and the way to guarantee that is not to compare
4250
+ # afterwards but never to enter the branch: a loop that rewrites every cell to the
4251
+ # same value passes a hash check and is still the full-document write this guard
4252
+ # exists to prevent. `rewrote` records which happened, so the two are distinguishable
4253
+ # from outside.
4254
+ if plan and plan['clearing']:
4255
+ bucket = t.get('rows') or {}
4256
+ for rid in plan['rowIds']:
4257
+ cells = bucket.get(rid)
4258
+ if isinstance(cells, dict):
4259
+ cells.pop(str(fkey), None)
4260
+ if isinstance(preview, dict):
4261
+ preview['rewrote'] = True
4262
  return cur
4263
 
4264
  _st(st).update(STORE_KEY, _set, flush='sync')
platform/harness/semantic.py CHANGED
@@ -47,7 +47,7 @@ def _customer_move_domain(move_type):
47
  def build(date_from=None, date_to=None, team_id=None, **kw):
48
  if team_id:
49
  raise ModelError(
50
- f"customer {move_type} documents are COMPANY-LEVEL β€” credit notes and invoices "
51
  f"carry no trustworthy business-unit tag, so a team-scoped total cannot be "
52
  f"produced. Refusing rather than returning the company number.")
53
  dom = [("move_type", "=", move_type), ("state", "=", "posted")]
@@ -71,6 +71,26 @@ class ModelError(Exception):
71
  """A model-file problem (unknown key, bad reference, unparseable expr)."""
72
 
73
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
74
  # ---------------------------------------------------------------- loading
75
 
76
  @functools.lru_cache(maxsize=1)
@@ -164,7 +184,7 @@ def describe(key):
164
  def _domain(topic_def, date_from, date_to, team_id):
165
  b = topic_def.get("domain_builder")
166
  if not b:
167
- raise ModelError(f"topic {topic_def['key']!r} is store-only β€” use store_query() "
168
  f"(no live-path domain builder bound yet)")
169
  return _BUILDERS[b](date_from, date_to, team_id=team_id)
170
 
@@ -390,7 +410,7 @@ def _store_con():
390
  import harness.datastore as DS
391
  if not DS.ready(): # a mid-backfill store returns PARTIAL totals silently
392
  raise ModelError("the data cache is still warming up after a restart (a one-time first "
393
- "sync) β€” the dashboards work now from live data; ask me again in a "
394
  "moment and I'll have it")
395
  return DS.ro_cursor() # cursor on the shared instance β€” no sync-writer contention
396
 
@@ -456,7 +476,7 @@ def _post_compute(row, key):
456
  _FORMAT_TYPE = {"usd": "currency", "int": "int", "pct": "pct"}
457
 
458
 
459
- def _clean_tree(tree, cols):
460
  """Run a filter tree through the SAME validator the client's view state goes through.
461
 
462
  `filter_sql`'s documented input contract is "feed me CLEANED trees" β€” it is faithful to the
@@ -470,6 +490,9 @@ def _clean_tree(tree, cols):
470
  module with zero imports of its own, so this cannot cycle.
471
  """
472
  from aios_grid import (clean_filter_tree, COHORT_FIELD as _COHORT_FIELD,
 
 
 
473
  MAX_FILTER_DEPTH, MAX_FILTER_NODES, MAX_FILTER_SIBLINGS)
474
 
475
  # REFUSE an over-large tree rather than TRUNCATE it. clean_filter_tree caps siblings per
@@ -535,15 +558,92 @@ def _clean_tree(tree, cols):
535
  # it here, the fix is to pass the membership in, not to let it fall through.
536
  if cohorts:
537
  raise ModelError(
538
- f"filter tree carries cohort-membership condition(s) {sorted(set(cohorts))} β€” "
539
  f"cohort membership is host state, not a column of this topic. Refusing rather than "
540
  f"dropping it, which would silently widen the result under an authoritative count.")
541
  if windowed:
542
  raise ModelError(
543
  f"filter tree carries measure condition(s) over a date window {sorted(set(windowed))}"
544
- f" β€” those are resolved to a set of ids by harness.measure_filter, not compiled into "
545
  f"this query. Refusing rather than dropping or mis-compiling them, either of which "
546
  f"would silently answer a different question under an authoritative count.")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
547
  return clean_filter_tree(tree, set(cols))
548
 
549
 
@@ -688,7 +788,7 @@ def _channel_sql(channel):
688
  tid = names.get(channel)
689
  if tid is None:
690
  raise ModelError(
691
- f"channel {channel!r} is not a team this tenant names β€” `tenant.yml::team_names` "
692
  f"carries {sorted(names)}, so the channel cannot be resolved to a team id")
693
  return f"o.team_id = {int(tid)} AND l.order_partner_id NOT IN " \
694
  f"(SELECT id FROM res_partner WHERE name LIKE {_sql_value(excl)})"
@@ -766,7 +866,7 @@ def store_query(topic, measures, group_by=None, grain=None, date_from=None, date
766
  # never count(*) on the wrong table); in a GROUPED query they are refused (split the request).
767
  foreign = [k for k in base_keys if _model()["metrics"][k]["topic"] != topic]
768
  if foreign and (group_by or grain):
769
- raise ModelError(f"metrics {foreign} belong to another topic β€” cross-topic measures are "
770
  f"scalar-only; run them against their own topic when grouping")
771
  base_keys = [k for k in base_keys if k not in foreign]
772
  foreign_vals = {}
@@ -782,7 +882,8 @@ def store_query(topic, measures, group_by=None, grain=None, date_from=None, date
782
  gb = [g for g in (group_by or []) if g]
783
  for g in gb:
784
  if g not in dims:
785
- raise ModelError(f"group_by {g!r} not a dim of {topic!r} (allowed: {list(dims)})")
 
786
  d = dims[g]
787
  select.append(f"{d['col']} AS {g}_id" if d.get("name_col") else f"{d['col']} AS {g}")
788
  group_cols.append(d["col"])
@@ -815,13 +916,14 @@ def store_query(topic, measures, group_by=None, grain=None, date_from=None, date
815
  # cell that reads as "this SKU sold nothing on Amazon" β€” a FALSE number, not a narrower one.
816
  if team_id and scope_variant is None:
817
  if not s.get("team_col"):
818
- raise ModelError(f"topic {topic!r} is company-level β€” it has no business-unit filter")
819
  where.append(f"{s['team_col']} = ?"); params.append(int(team_id))
820
  if exclude_services and s.get("service_filter"):
821
  where.append(render_scope(s["service_filter"]))
822
  for dim_key, vals in (filters or {}).items():
823
  if dim_key not in dims:
824
- raise ModelError(f"filter dim {dim_key!r} not allowed (use: {list(dims)})")
 
825
  # id dims filter by int; TEXT dims (e.g. city) filter by the value itself β€” either way
826
  # every VALUE stays parameterized (the whitelist covers identifiers only)
827
  def _coerce(v):
@@ -847,7 +949,7 @@ def store_query(topic, measures, group_by=None, grain=None, date_from=None, date
847
  if pred.uses_aggregate:
848
  bad = sorted(c for c in pred.columns_used if cols[c].get("aggregate"))
849
  raise ModelError(
850
- f"filter_tree references measure(s) {bad} β€” a measure filter has to land in "
851
  f"HAVING, and that path is deliberately NOT built: CG-1 ships the WHERE path "
852
  f"because its consumer (CG-2, the line-grain sales table) does not aggregate. "
853
  f"Filter on dims, or aggregate first and filter the result.")
@@ -945,7 +1047,7 @@ def store_rows(topic, date_from=None, date_to=None, team_id=None, filter_tree=No
945
  scope_params.append(f"{date_to} 23:59:59")
946
  if team_id:
947
  if not s.get("team_col"):
948
- raise ModelError(f"topic {topic!r} is company-level β€” it has no business-unit filter")
949
  scope.append(f"{s['team_col']} = ?")
950
  scope_params.append(int(team_id))
951
  if exclude_services and s.get("service_filter"):
@@ -953,7 +1055,12 @@ def store_rows(topic, date_from=None, date_to=None, team_id=None, filter_tree=No
953
 
954
  # --- the user's narrowing, on top of the scope --------------------------------------
955
  narrow, narrow_params = [], []
956
- pred = _fs.compile_filter_tree(_clean_tree(filter_tree or [], cols), filter_conj, cols,
 
 
 
 
 
957
  today=today,
958
  member_ids=member_ids or None, id_sql=id_sql)
959
  if pred is not None:
@@ -1027,7 +1134,7 @@ def store_field_values(topic, dim, search=None, limit=25):
1027
  raise ModelError(f"topic {topic!r} has no store binding")
1028
  d = (t["store"].get("dims") or {}).get(dim)
1029
  if not d:
1030
- raise ModelError(f"unknown dim {dim!r} for topic {topic!r}")
1031
  if not d.get("name_col"):
1032
  raise ModelError(f"dim {dim!r} has no name column (filter by id)")
1033
  s = t["store"]
@@ -1320,7 +1427,7 @@ def _one_binding_offer(topic, b, strict=False, ready=None):
1320
  # user did not get rather than a base metric they never asked for.
1321
  key = key + _suffix
1322
  if strict:
1323
- raise _EntityMeasureError(f"{topic}: measure {key!r} refused β€” {reason}")
1324
  refused.append({"key": key, "reason": reason})
1325
 
1326
  for key in b["keys"]:
@@ -1472,7 +1579,7 @@ def entity_measure_values(topic, keys, date_from=None, date_to=None, team_id=Non
1472
  # `rollup_sql.group_values` makes, for the same reason. Never write cells from one.
1473
  if res.get("truncated"):
1474
  raise _EntityMeasureError(
1475
- f"{topic}: {src} grouped by {dim} exceeded {MAX_GROUPS} groups β€” refusing to write "
1476
  f"cells from a truncated result")
1477
  # `store_query` emits the bare dim name when the dim has no `name_col`, `<dim>_id` when it
1478
  # does. Both shapes are live in the model, so read whichever arrived.
 
47
  def build(date_from=None, date_to=None, team_id=None, **kw):
48
  if team_id:
49
  raise ModelError(
50
+ f"customer {move_type} documents are COMPANY-LEVEL: credit notes and invoices "
51
  f"carry no trustworthy business-unit tag, so a team-scoped total cannot be "
52
  f"produced. Refusing rather than returning the company number.")
53
  dom = [("move_type", "=", move_type), ("state", "=", "posted")]
 
71
  """A model-file problem (unknown key, bad reference, unparseable expr)."""
72
 
73
 
74
+ class UnknownColumnError(ModelError):
75
+ """A request named a COLUMN (dim / filter key / group key) the topic does not have.
76
+
77
+ W42-T06 / amendment A8. A SUBCLASS of ModelError so every existing `except ModelError`
78
+ stays byte-identical, and so the route layer can tell "you asked for a column that is not
79
+ there" (a 400 naming the column) apart from "this topic has no store binding" (a 503).
80
+
81
+ The offending name is the `column` ATTRIBUTE, not merely a substring of the message.
82
+ A caller that had to match the sentence would break the moment somebody reworded it, and
83
+ the sentence is copy that reaches a screen, so it WILL be reworded (standing rule 2).
84
+ `columns` carries the full sorted set when a tree named several, so the message stays short
85
+ while nothing is hidden.
86
+ """
87
+
88
+ def __init__(self, message, column, columns=None):
89
+ super().__init__(message)
90
+ self.column = str(column)
91
+ self.columns = sorted({str(c) for c in (columns or [column])})
92
+
93
+
94
  # ---------------------------------------------------------------- loading
95
 
96
  @functools.lru_cache(maxsize=1)
 
184
  def _domain(topic_def, date_from, date_to, team_id):
185
  b = topic_def.get("domain_builder")
186
  if not b:
187
+ raise ModelError(f"topic {topic_def['key']!r} is store-only, so use store_query() "
188
  f"(no live-path domain builder bound yet)")
189
  return _BUILDERS[b](date_from, date_to, team_id=team_id)
190
 
 
410
  import harness.datastore as DS
411
  if not DS.ready(): # a mid-backfill store returns PARTIAL totals silently
412
  raise ModelError("the data cache is still warming up after a restart (a one-time first "
413
+ "sync). The dashboards work now from live data; ask me again in a "
414
  "moment and I'll have it")
415
  return DS.ro_cursor() # cursor on the shared instance β€” no sync-writer contention
416
 
 
476
  _FORMAT_TYPE = {"usd": "currency", "int": "int", "pct": "pct"}
477
 
478
 
479
+ def _clean_tree(tree, cols, tolerate=()):
480
  """Run a filter tree through the SAME validator the client's view state goes through.
481
 
482
  `filter_sql`'s documented input contract is "feed me CLEANED trees" β€” it is faithful to the
 
490
  module with zero imports of its own, so this cannot cycle.
491
  """
492
  from aios_grid import (clean_filter_tree, COHORT_FIELD as _COHORT_FIELD,
493
+ VIEW_FIELD as _VIEW_FIELD, FILTER_OPS as _FILTER_OPS,
494
+ COHORT_OPS as _COHORT_OPS, COHORT_OP_ALIASES as _COHORT_ALIASES,
495
+ VIEW_OPS as _VIEW_OPS,
496
  MAX_FILTER_DEPTH, MAX_FILTER_NODES, MAX_FILTER_SIBLINGS)
497
 
498
  # REFUSE an over-large tree rather than TRUNCATE it. clean_filter_tree caps siblings per
 
558
  # it here, the fix is to pass the membership in, not to let it fall through.
559
  if cohorts:
560
  raise ModelError(
561
+ f"filter tree carries cohort-membership condition(s) {sorted(set(cohorts))}, but "
562
  f"cohort membership is host state, not a column of this topic. Refusing rather than "
563
  f"dropping it, which would silently widen the result under an authoritative count.")
564
  if windowed:
565
  raise ModelError(
566
  f"filter tree carries measure condition(s) over a date window {sorted(set(windowed))}"
567
+ f". Those are resolved to a set of ids by harness.measure_filter, not compiled into "
568
  f"this query. Refusing rather than dropping or mis-compiling them, either of which "
569
  f"would silently answer a different question under an authoritative count.")
570
+ # ⭐ W42-T06 β€” AN UNKNOWN COLUMN IS REFUSED BY NAME, and this is the LAST check before the
571
+ # validator because `clean_filter_tree` DROPS an unrecognised `colId` (its documented
572
+ # fail-closed-per-node contract, correct on a saved view where one bad rule must not cost a
573
+ # user the whole view). On THIS path it is the same silent widening the caps above refuse:
574
+ # a hop whose `via.filter` names a column the middle topic does not have would return the
575
+ # UNFILTERED set under a count that looks authoritative. So the server names it instead.
576
+ # - a leaf with no `colId` is MALFORMED, not "a column this topic lacks" - left to the
577
+ # validator, which drops it as it always has;
578
+ # - `__cohort__` / `__view__` are HOST STATE, not columns of any topic; the cohort arm
579
+ # above already refuses its own leaf, and a view leaf keeps today's drop;
580
+ # - `tolerate` is for a caller whose `cols` is deliberately NARROWER than the topic's
581
+ # vocabulary (store_rows at row grain drops count-style metrics). Those keys keep
582
+ # today's silent drop rather than becoming a 400 that misnames a metric as a typo.
583
+ tolerated = {str(c) for c in (tolerate or ())}
584
+ known = set(cols) | tolerated | {_COHORT_FIELD, _VIEW_FIELD}
585
+ unknown = []
586
+ bad_ops = []
587
+
588
+ def _cols(nodes):
589
+ for node in nodes or []:
590
+ if not isinstance(node, dict):
591
+ continue
592
+ if isinstance(node.get('children'), list):
593
+ _cols(node['children'])
594
+ continue
595
+ col = node.get('colId')
596
+ if col in (None, ''):
597
+ continue
598
+ col = str(col)
599
+ if col not in known:
600
+ unknown.append(col)
601
+ continue
602
+ # ⭐ THE SAME HOLE ONE KEY OVER, ruled into this ticket 2026-08-25 and INHERITED, not
603
+ # introduced: `clean_filter_tree` drops a leaf whose `op` it does not know, by the
604
+ # same fail-closed-per-node contract, and the result is identical. A `via.filter`
605
+ # authored with `op: "is"` returned the WHOLE unfiltered topic (measured on
606
+ # sales_lines: 16,779,678.21 instead of 14,763,400.38) under an authoritative count.
607
+ # This is an AUTHORING error, not an unknown column, so it stays a plain ModelError:
608
+ # `UnknownColumnError` has to keep meaning "unknown column" or the 400 it produces
609
+ # would name a column that is perfectly fine.
610
+ # - the three vocabularies are DISJOINT ON PURPOSE (aios_grid says so), so this is
611
+ # per-leaf-KIND, never one union;
612
+ # - a cohort leaf may carry `eq`/`neq`, which are PERMANENT aliases of
613
+ # `anyOf`/`noneOf`; checking COHORT_OPS alone would 400 every saved view written
614
+ # before the alias rewrite;
615
+ # - the RANK ops are in FILTER_OPS and PASS here even though `filter_sql` cannot
616
+ # compile them to row SQL. That refusal already exists downstream with its own
617
+ # message; restating it here would change which error a caller sees;
618
+ # - a leaf with NO `op` is MALFORMED, not a bad operator: left to the validator's
619
+ # existing drop, exactly as a leaf with no `colId` is;
620
+ # - a `tolerate`d key keeps its long-standing silent drop end to end, op included.
621
+ if tolerated and col in tolerated and col not in cols:
622
+ continue
623
+ op = node.get('op')
624
+ if op in (None, ''):
625
+ continue
626
+ legal = (_COHORT_OPS | set(_COHORT_ALIASES) if col == _COHORT_FIELD
627
+ else _VIEW_OPS if col == _VIEW_FIELD
628
+ else _FILTER_OPS)
629
+ if str(op) not in legal:
630
+ bad_ops.append((col, str(op), sorted(legal)))
631
+
632
+ _cols(tree)
633
+ if unknown:
634
+ bad = sorted(set(unknown))
635
+ extra = f" (and {bad[1:]})" if len(bad) > 1 else ""
636
+ raise UnknownColumnError(
637
+ f"filter rule names column {bad[0]!r}{extra}, which this topic does not have. "
638
+ f"Refusing rather than dropping the rule, which would silently widen the result.",
639
+ column=bad[0], columns=bad)
640
+ if bad_ops:
641
+ col, op, legal = bad_ops[0]
642
+ raise ModelError(
643
+ f"filter rule on column {col!r} carries operator {op!r}, which is not one this "
644
+ f"filter understands (use: {legal}). Refusing rather than dropping the rule, which "
645
+ f"would silently widen the result.")
646
+
647
  return clean_filter_tree(tree, set(cols))
648
 
649
 
 
788
  tid = names.get(channel)
789
  if tid is None:
790
  raise ModelError(
791
+ f"channel {channel!r} is not a team this tenant names. `tenant.yml::team_names` "
792
  f"carries {sorted(names)}, so the channel cannot be resolved to a team id")
793
  return f"o.team_id = {int(tid)} AND l.order_partner_id NOT IN " \
794
  f"(SELECT id FROM res_partner WHERE name LIKE {_sql_value(excl)})"
 
866
  # never count(*) on the wrong table); in a GROUPED query they are refused (split the request).
867
  foreign = [k for k in base_keys if _model()["metrics"][k]["topic"] != topic]
868
  if foreign and (group_by or grain):
869
+ raise ModelError(f"metrics {foreign} belong to another topic. Cross-topic measures are "
870
  f"scalar-only; run them against their own topic when grouping")
871
  base_keys = [k for k in base_keys if k not in foreign]
872
  foreign_vals = {}
 
882
  gb = [g for g in (group_by or []) if g]
883
  for g in gb:
884
  if g not in dims:
885
+ raise UnknownColumnError(
886
+ f"group_by {g!r} not a dim of {topic!r} (allowed: {list(dims)})", column=g)
887
  d = dims[g]
888
  select.append(f"{d['col']} AS {g}_id" if d.get("name_col") else f"{d['col']} AS {g}")
889
  group_cols.append(d["col"])
 
916
  # cell that reads as "this SKU sold nothing on Amazon" β€” a FALSE number, not a narrower one.
917
  if team_id and scope_variant is None:
918
  if not s.get("team_col"):
919
+ raise ModelError(f"topic {topic!r} is company-level, so it has no business-unit filter")
920
  where.append(f"{s['team_col']} = ?"); params.append(int(team_id))
921
  if exclude_services and s.get("service_filter"):
922
  where.append(render_scope(s["service_filter"]))
923
  for dim_key, vals in (filters or {}).items():
924
  if dim_key not in dims:
925
+ raise UnknownColumnError(
926
+ f"filter dim {dim_key!r} not allowed (use: {list(dims)})", column=dim_key)
927
  # id dims filter by int; TEXT dims (e.g. city) filter by the value itself β€” either way
928
  # every VALUE stays parameterized (the whitelist covers identifiers only)
929
  def _coerce(v):
 
949
  if pred.uses_aggregate:
950
  bad = sorted(c for c in pred.columns_used if cols[c].get("aggregate"))
951
  raise ModelError(
952
+ f"filter_tree references measure(s) {bad}. A measure filter has to land in "
953
  f"HAVING, and that path is deliberately NOT built: CG-1 ships the WHERE path "
954
  f"because its consumer (CG-2, the line-grain sales table) does not aggregate. "
955
  f"Filter on dims, or aggregate first and filter the result.")
 
1047
  scope_params.append(f"{date_to} 23:59:59")
1048
  if team_id:
1049
  if not s.get("team_col"):
1050
+ raise ModelError(f"topic {topic!r} is company-level, so it has no business-unit filter")
1051
  scope.append(f"{s['team_col']} = ?")
1052
  scope_params.append(int(team_id))
1053
  if exclude_services and s.get("service_filter"):
 
1055
 
1056
  # --- the user's narrowing, on top of the scope --------------------------------------
1057
  narrow, narrow_params = [], []
1058
+ # ⚠ `cols` here is the ROW-grain projection, which drops count-style metrics on purpose.
1059
+ # Tolerate the aggregate-grain vocabulary so such a key keeps its long-standing silent drop
1060
+ # instead of being refused as an unknown COLUMN, which would name a real metric a typo.
1061
+ pred = _fs.compile_filter_tree(_clean_tree(filter_tree or [], cols,
1062
+ tolerate=store_columns(topic)),
1063
+ filter_conj, cols,
1064
  today=today,
1065
  member_ids=member_ids or None, id_sql=id_sql)
1066
  if pred is not None:
 
1134
  raise ModelError(f"topic {topic!r} has no store binding")
1135
  d = (t["store"].get("dims") or {}).get(dim)
1136
  if not d:
1137
+ raise UnknownColumnError(f"unknown dim {dim!r} for topic {topic!r}", column=dim)
1138
  if not d.get("name_col"):
1139
  raise ModelError(f"dim {dim!r} has no name column (filter by id)")
1140
  s = t["store"]
 
1427
  # user did not get rather than a base metric they never asked for.
1428
  key = key + _suffix
1429
  if strict:
1430
+ raise _EntityMeasureError(f"{topic}: measure {key!r} refused, because {reason}")
1431
  refused.append({"key": key, "reason": reason})
1432
 
1433
  for key in b["keys"]:
 
1579
  # `rollup_sql.group_values` makes, for the same reason. Never write cells from one.
1580
  if res.get("truncated"):
1581
  raise _EntityMeasureError(
1582
+ f"{topic}: {src} grouped by {dim} exceeded {MAX_GROUPS} groups, so refusing to write "
1583
  f"cells from a truncated result")
1584
  # `store_query` emits the bare dim name when the dim has no `name_col`, `<dim>_id` when it
1585
  # does. Both shapes are live in the model, so read whichever arrived.
platform/model/topics/odoo_products.yml CHANGED
@@ -195,46 +195,6 @@ fields:
195
  type: currency
196
  kind: data
197
  means: "Fisch pricelist price for this SKU. Blank when that list prices it nowhere."
198
- - key: price_royal_1
199
- label: "Royal 1 price"
200
- type: currency
201
- kind: data
202
- means: "Royal 1 pricelist price for this SKU. Blank when that list prices it nowhere."
203
- - key: price_royal_2
204
- label: "Royal 2 price"
205
- type: currency
206
- kind: data
207
- means: "Royal 2 pricelist price for this SKU. Blank when that list prices it nowhere."
208
- - key: price_1
209
- label: "Price 1"
210
- type: currency
211
- kind: data
212
- means: "Cheapest live package price for this SKU pooled across ALL active pricelists and unattributed. Ask the per-list tier fields for what a named list charges."
213
- - key: unit_1
214
- label: "Unit 1"
215
- type: text
216
- kind: data
217
- means: "Package label for Price 1; blank means Odoo has no package reference for that price."
218
- - key: price_2
219
- label: "Price 2"
220
- type: currency
221
- kind: data
222
- means: "Second-cheapest live package price pooled across ALL pricelists, unattributed."
223
- - key: unit_2
224
- label: "Unit 2"
225
- type: text
226
- kind: data
227
- means: "Package label for Price 2."
228
- - key: price_3
229
- label: "Price 3"
230
- type: currency
231
- kind: data
232
- means: "Third-cheapest live package price pooled across ALL pricelists, unattributed."
233
- - key: unit_3
234
- label: "Unit 3"
235
- type: text
236
- kind: data
237
- means: "Package label for Price 3."
238
  - key: price_fisch_t1
239
  label: "Fisch tier 1 price"
240
  type: currency
 
195
  type: currency
196
  kind: data
197
  means: "Fisch pricelist price for this SKU. Blank when that list prices it nowhere."
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
198
  - key: price_fisch_t1
199
  label: "Fisch tier 1 price"
200
  type: currency
platform/model/topics/sales_lines.yml CHANGED
@@ -74,6 +74,32 @@ store:
74
  # 2,056 customers have a non-agent as agent_ids[0]. Do NOT "fix" it by reading the commission
75
  # table, which mixes agents and salespeople.
76
  agent: {col: "rp.agent_id", name_col: "ag.name", label: "Agent"}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
77
 
78
  ai_context: >
79
  The wholesale sales dataset of Royal Imports / Fisch Floral Supply, at order-LINE grain.
@@ -117,3 +143,14 @@ ai_context: >
117
  has no address on file β€” present it as "no state on file", keep it in totals) and duplicate
118
  state records exist (two ids can share one name, e.g. New Jersey twice) β€” list them as the
119
  data shows and note the duplication rather than silently merging.
 
 
 
 
 
 
 
 
 
 
 
 
74
  # 2,056 customers have a non-agent as agent_ids[0]. Do NOT "fix" it by reading the commission
75
  # table, which mixes agents and salespeople.
76
  agent: {col: "rp.agent_id", name_col: "ag.name", label: "Agent"}
77
+ # ⭐⭐ W42-T01 (ruling R6) β€” THE ORDER-STATUS DIMS. R1's owner sentence is "where
78
+ # `sale.order.line` is Invoiced", and until now the topic declared nothing to filter that on.
79
+ # Both live on the PARENT order, which the `o` join already reaches; neither widens the scope.
80
+ #
81
+ # ⚠ `name_col` is DELIBERATELY THE SAME EXPRESSION AS `col`, the `city` pattern above. These
82
+ # are text status codes, not m2o ids: give them a DIFFERENT name_col and `store_columns`
83
+ # publishes an `<dim>_id` column typed `int` over a VARCHAR, and a numeric filter on it
84
+ # quietly compares 0 against 0 for every row. Keeping them equal suppresses that id column
85
+ # while still giving `store_field_values` a name column to resolve values with β€” a dim with
86
+ # `name_col: null` raises "no name column (filter by id)" there (semantic.py, store_field_values),
87
+ # so null is not an option either. ⚠ THOSE ARE TWO SEPARATE HAZARDS, and a third one is the
88
+ # `receivables.payment_state` scar recorded in verify_odoo_relational: THAT one raised nothing
89
+ # at all β€” `group_values` read a `<dim>_id` column the dim never emitted, so every cell came
90
+ # back blank with no exception anywhere. Keeping name_col == col avoids all three: the id
91
+ # column IS emitted (store_query always emits `<dim>_id` when name_col is set) and it holds
92
+ # the same text value the user filters on.
93
+ #
94
+ # ⚠ VALUES ARE THE RAW ODOO STATES, not display words: invoice_status is one of
95
+ # 'invoiced' / 'to invoice' / 'no' / 'upselling'; order_state is 'sale' / 'done'.
96
+ invoice_status: {col: "o.invoice_status", name_col: "o.invoice_status",
97
+ label: "Invoice status"}
98
+ # β›” TRAP, AND IT IS NOT A BUG: `scope_sql` already pins o.state IN ('sale','done'), so this
99
+ # dim can only ever return those two buckets. It exists to name the distinction inside the
100
+ # confirmed scope (Confirmed vs Locked), NOT to reach quotes or cancellations. Do NOT "fix"
101
+ # it by widening `scope_sql` β€” that would change what every metric on this topic means.
102
+ order_state: {col: "o.state", name_col: "o.state", label: "Order state"}
103
 
104
  ai_context: >
105
  The wholesale sales dataset of Royal Imports / Fisch Floral Supply, at order-LINE grain.
 
143
  has no address on file β€” present it as "no state on file", keep it in totals) and duplicate
144
  state records exist (two ids can share one name, e.g. New Jersey twice) β€” list them as the
145
  data shows and note the duplication rather than silently merging.
146
+ INVOICING questions ("which confirmed sales are invoiced", "what is still to invoice") use the
147
+ `invoice_status` dim, which carries the PARENT ORDER's status: an order is the unit Odoo
148
+ invoices, so a line inherits its order's status rather than having one of its own. Its values
149
+ are the raw Odoo codes, so say them in plain words: 'invoiced' is fully invoiced, 'to invoice'
150
+ is awaiting an invoice, 'no' means nothing to invoice, and 'upselling' means delivered above
151
+ the ordered quantity. The `order_state` dim is 'sale' (confirmed) or 'done' (locked) and can
152
+ never be anything else here, because this topic's scope is confirmed orders only; quotes and
153
+ cancelled orders are outside it, so never read a missing bucket as "we have no quotes".
154
+ DATA CAVEAT, measured 2026-08-25: 'done' (locked) is reachable under this scope but has NO rows
155
+ in this tenant's store today, so grouping by `order_state` returns the single bucket 'sale' and
156
+ that is the whole confirmed population, not a filtered slice of it.
platform/modules/product_data.py CHANGED
@@ -685,8 +685,14 @@ def pool(team_id=None, t=None):
685
  # W29-T52's own negative control: the single `3_global` rule computes over `list_price`,
686
  # which is 1.00 on 5,817 of 5,871 products, so the fallback is not a cheaper answer β€”
687
  # it is a wrong one wearing a currency sign.
 
 
 
 
 
 
688
  p = prices.get(code) or {}
689
- for _col, _name in products.PRICELIST_COLUMNS:
690
  row[_col] = p.get(_col)
691
  # ⭐⭐ W37-T14 / T15 β€” THE HONEST SETS, beside the three declared columns rather than
692
  # instead of them. The columns above answer "what does Fisch charge"; these answer "how
@@ -698,20 +704,22 @@ def pool(team_id=None, t=None):
698
  # ⚠ BLANK, NOT "[]" β€” an empty cell reads as "sold in one unit / not priced on any list",
699
  # and an empty JSON array on screen reads as a bug.
700
  _tiers = tiers.get(code) or []
701
- for _n in range(1, 4):
702
- _tier = _tiers[_n - 1] if len(_tiers) >= _n else None
703
- row[f"price_{_n}"] = _tier.get("unit_price") if _tier else None
704
- row[f"unit_{_n}"] = _tier.get("unit") if _tier else None
705
- # ⭐⭐ W40-T09 / RULING R6 (owner I25) β€” THE SAME PRICES, ATTRIBUTED TO THE LIST THAT
706
- # CHARGES THEM: three (price, unit) pairs each for Fisch, Royal 1 and Royal 2.
707
  #
708
- # β›” THIS SUPERSEDES THE SIX LINES ABOVE RATHER THAN EXTENDING THEM, and the difference
709
- # is the whole ticket. `price_1..3` are the cheapest three POOLED ACROSS EVERY LIST and
710
- # carry no attribution, so on the 1,854 SKUs priced on all three lists they answer a
711
- # question nobody asked: not "what does Fisch charge" but "what are the three lowest
712
- # numbers anyone charges". The pooled six stay DECLARED and stay WRITTEN β€” a saved view
713
- # or a stored permission wall naming one must keep working β€” but they are demoted to
714
- # `default: false` in the contract so the default view stops offering the approximation.
 
 
 
 
 
 
715
  #
716
  # ⚠ NO SECOND ODOO READ. `tiers` already carries the pricelist name on every entry;
717
  # `per_list_tier_cells` is a group-by over the list this loop is already holding.
@@ -1096,7 +1104,12 @@ def validate(team_id=None, t=None):
1096
  # LEG 1 β€” COVERAGE PER LIST. Ours: cells we filled. Theirs: a bare Odoo `search_count` of
1097
  # ACTIVE products a fresh read of that list's rules reaches. The rule set is shared (it IS
1098
  # the data) but the EXPANSION is not, and the expansion is what breaks.
1099
- for _col, _name in products.PRICELIST_COLUMNS:
 
 
 
 
 
1100
  _var, _tmpl = _rule_targets(_name)
1101
  _dom = [('active', '=', True), '|', ('id', 'in', sorted(_var)),
1102
  ('product_tmpl_id', 'in', sorted(_tmpl))]
@@ -1113,9 +1126,15 @@ def validate(team_id=None, t=None):
1113
  # render BLANK. Asked of ODOO, never of the map that produced the blank β€” "everything I left
1114
  # empty was genuinely unpriced" is trivially true when checked against the dict that emptied
1115
  # it, which is the self-sealing shape the population leg above exists to end.
 
 
 
 
 
 
1116
  _unpriced = [r for r in rows
1117
  if not any(isinstance(r.get(c), (int, float))
1118
- for c, _n in products.PRICELIST_COLUMNS)]
1119
  _codes = {r["code"] for r in _unpriced}
1120
  _stray = 0
1121
  if _codes:
@@ -1128,12 +1147,15 @@ def validate(team_id=None, t=None):
1128
  ['id', 'product_tmpl_id']):
1129
  _ids.add(_p['id'])
1130
  _tmpls.add(O.m2o_id(_p.get('product_tmpl_id')))
1131
- for _col, _name in products.PRICELIST_COLUMNS:
1132
  _v, _t = _rule_targets(_name)
1133
  _stray += len((_v & _ids) | ({t for t in _tmpls if t in _t}))
1134
  checks.append({
1135
- "check": "every SKU rendering a BLANK price is genuinely unpriced on all three declared "
1136
- "lists (W29-T52's NC: no fallback dressed as a price) β€” asked of Odoo",
 
 
 
1137
  "ours": _stray, "theirs": 0, "ok": _stray == 0,
1138
  "detail": {"blank_skus": len(_unpriced), "priced_skus": len(rows) - len(_unpriced)},
1139
  })
@@ -1143,16 +1165,21 @@ def validate(team_id=None, t=None):
1143
  # counted here rather than dropped. The ASSERTION is the one thing that must never be true β€”
1144
  # a price cell that is present and not a positive number, i.e. a "free" SKU β€” while the
1145
  # rest rides `detail` so it is reported without reddening an honest day's data.
 
 
 
 
 
1146
  _bad = [r["code"] for r in rows
1147
- for c, _n in products.PRICELIST_COLUMNS
1148
  if r.get(c) is not None and not (isinstance(r.get(c), (int, float)) and r[c] > 0)]
1149
  # β›” MEASURED 2026-08-12 AND NOT FIXABLE FROM THIS FENCE: `aios_grid.rows_from_pool` sends
1150
  # every non-text field through `_round(v)` = `round(v)` with no ndigits, i.e. to a whole
1151
  # dollar. 52.1% of fixed prices carry cents and the median relative error is 5.26%, so this
1152
  # column ties to the cent HERE and ships rounded. Reported, never silently enforced.
1153
- _cents = sum(1 for r in rows for c, _n in products.PRICELIST_COLUMNS
1154
  if isinstance(r.get(c), (int, float)) and abs(r[c] - round(r[c])) > 1e-9)
1155
- _to_zero = sum(1 for r in rows for c, _n in products.PRICELIST_COLUMNS
1156
  if isinstance(r.get(c), (int, float)) and round(r[c]) == 0)
1157
  checks.append({
1158
  "check": "no price cell is present-but-not-a-positive-number (a 0 would read as FREE; "
@@ -1486,39 +1513,40 @@ def validate_stock_measures(t=None, days=90, sample=4):
1486
 
1487
 
1488
  def validate_price_and_unit_cells(rows, sample=6):
1489
- """Reconcile typed Price 1..3 / Unit 1..3 cells to a fresh, per-SKU Odoo read.
1490
 
1491
  The pool groups price rules in bulk. This asks Odoo per SKU so a wrong grouping, a lost
1492
  package price, or a missing unit has an oracle which cannot agree by reusing that grouping.
1493
- The contract ships only the cheapest three pairs; duplicate SKU codes may make the pool a
1494
- legitimate superset of a single product's rules.
 
 
 
 
 
 
1495
  """
1496
  checks = []
1497
- priced = [r for r in rows if r.get("price_1") is not None]
1498
- with_first_pair = [r for r in rows if "price_1" in r and "unit_1" in r]
1499
- checks.append({
1500
- "check": "the product grid serves typed Price 1..3 and Unit 1..3 cells, not JSON cells",
1501
- "ours": {"with_price_1": len(priced), "with_first_pair": len(with_first_pair),
1502
- "rows": len(rows)},
1503
- "theirs": {"price_1": ">0", "typed_first_pair": len(rows)},
1504
- "ok": bool(priced) and len(with_first_pair) == len(rows)
1505
- and not any("tier_prices" in r or "units" in r for r in rows),
1506
- "detail": {"two_or_more_prices": sum(1 for r in rows if r.get("price_2") is not None),
1507
- "three_prices": sum(1 for r in rows if r.get("price_3") is not None)},
1508
- })
1509
 
1510
- # ── W40-T09 / R6 β€” the PER-LIST cells, which is what the pooled three above are not ──────
1511
  _tier_keys = [k for t in products.PRICELIST_TIER_COLUMNS for k in t[:2]]
1512
  _typed = [r for r in rows if all(k in r for k in _tier_keys)]
 
1513
  _per_list = {}
1514
  for _p, _u, _name, _n in products.PRICELIST_TIER_COLUMNS:
1515
  _per_list.setdefault(_name, {})[f"t{_n}"] = sum(1 for r in rows if r.get(_p) is not None)
1516
  checks.append({
1517
  "check": "the product grid serves all 18 per-list tier cells (price and unit 1..3 for "
1518
- "each declared pricelist), typed and on every row",
1519
- "ours": {"rows_with_all_18": len(_typed), "rows": len(rows), "cells": len(_tier_keys)},
1520
- "theirs": {"rows_with_all_18": len(rows), "cells": 18},
1521
- "ok": len(_typed) == len(rows) and len(_tier_keys) == 18,
 
 
 
 
 
 
1522
  "detail": {"skus_priced_per_list": _per_list},
1523
  })
1524
  # β›” CHEAPEST-FIRST PACKS FROM THE TOP, so a hole is the signature of a misaligned write:
@@ -1556,6 +1584,17 @@ def validate_price_and_unit_cells(rows, sample=6):
1556
  "detail": {"sku_list_pairs_over_cap": sum(len(v) for v in _over.values())},
1557
  })
1558
 
 
 
 
 
 
 
 
 
 
 
 
1559
  if not priced:
1560
  return checks
1561
  o = O.get_odoo()
@@ -1572,13 +1611,14 @@ def validate_price_and_unit_cells(rows, sample=6):
1572
  _plname = {p["id"]: str(p.get("name") or "").strip()
1573
  for p in o.search_read("product.pricelist", [], ["id", "name"])}
1574
  # Prefer SKUs that carry more than one price, the ticket's own subject.
 
 
1575
  cand = sorted(priced,
1576
- key=lambda r: -sum(r.get(f"price_{n}") is not None for n in range(1, 4)))[:sample]
1577
- bad = []
 
1578
  bad_list, borrowed = [], [] # W40-T09: the per-list oracle and its no-borrow NC
1579
  for r in cand:
1580
- mine = sorted((round(float(r[f"price_{n}"]), 2), str(r.get(f"unit_{n}") or "").strip())
1581
- for n in range(1, 4) if r.get(f"price_{n}") is not None)
1582
  pid = r.get("product_id")
1583
  tmpl = None
1584
  if pid:
@@ -1602,16 +1642,8 @@ def validate_price_and_unit_cells(rows, sample=6):
1602
  by_template.setdefault(plid, []).append(it)
1603
  picked = [it for plid in sorted(set(by_variant) | set(by_template))
1604
  for it in (by_variant.get(plid) or by_template.get(plid) or [])]
1605
- theirs = sorted((round(float(it.get("packaging_price") or it.get("fixed_price") or 0.0), 2),
1606
- str(O.m2o_name(it.get("packaging_id")) or "").strip())
1607
- for it in picked)[:3]
1608
- # ⚠ A code carried by TWO active products legitimately holds MORE entries than a single
1609
- # product's rules (D-309 / `2112-12`), so ours is a SUPERSET, never an equality.
1610
- if not set(theirs) <= set(mine):
1611
- bad.append({"sku": r.get("code"), "ours": mine, "odoo": theirs})
1612
-
1613
- # ── W40-T09 / R6 β€” the SAME oracle, now asked PER LIST ──────────────────────────────
1614
- # ⚠ SUPERSET, NOT EQUALITY, for the same D-309 reason as the pooled leg above: a code
1615
  # carried by two active products merges here, so one list can legitimately hold more
1616
  # pairs than a single product's rules. Equality would go red on a working build.
1617
  theirs_by_list = {}
@@ -1623,8 +1655,9 @@ def validate_price_and_unit_cells(rows, sample=6):
1623
  # ⚠ AN EMPTY ORACLE IS NOT EVIDENCE OF BORROWING. If the per-SKU read came back with no
1624
  # rules at all, there is nothing to compare and firing the NC would report a broken
1625
  # oracle as a data defect β€” the failure mode the display-name bug above actually
1626
- # produced. The pooled leg is immune by construction (`set() <= set(mine)` passes); this
1627
- # one has to say so.
 
1628
  for _name in (_declared_names if picked else []):
1629
  mine_l = sorted(
1630
  (round(float(r[_price_key[(_name, n)]]), 2),
@@ -1641,13 +1674,6 @@ def validate_price_and_unit_cells(rows, sample=6):
1641
  # prints another list's price under this list's heading.
1642
  if not theirs_by_list.get(_name) and mine_l:
1643
  borrowed.append({"sku": r.get("code"), "list": _name, "ours": mine_l})
1644
- checks.append({
1645
- "check": f"each sampled SKU's typed Price/Unit pairs contain every live Odoo pair "
1646
- f"({len(cand)} SKUs, chosen for the most prices)",
1647
- "ours": len(bad), "theirs": 0, "ok": not bad,
1648
- "detail": {"mismatches": bad[:3],
1649
- "sampled": [r.get("code") for r in cand]},
1650
- })
1651
  checks.append({
1652
  "check": f"each sampled SKU's PER-LIST tier cells contain every live Odoo pair ON THAT "
1653
  f"LIST ({len(cand)} SKUs x {len(_declared_names)} declared pricelists)",
 
685
  # W29-T52's own negative control: the single `3_global` rule computes over `list_price`,
686
  # which is 1.00 on 5,817 of 5,871 products, so the fallback is not a cheaper answer β€”
687
  # it is a wrong one wearing a currency sign.
688
+ # β›” `PRICELIST_GRID_COLUMNS`, NOT `PRICELIST_COLUMNS` β€” W42-T56 / R26. `prices` still
689
+ # resolves all three declared lists; only Fisch still gets a BASE grid column, because
690
+ # the per-list tier block supersedes the two Royal ones. The wider tuple stays the
691
+ # PRICELIST IDENTITY registry that `PRICELIST_TIER_COLUMNS` is derived from, so reading
692
+ # it here would write two cells the contract no longer declares β€” and `rows_from_pool`
693
+ # projects STRICTLY, so those two would be dropped on the wire with no error at all.
694
  p = prices.get(code) or {}
695
+ for _col, _name in products.PRICELIST_GRID_COLUMNS:
696
  row[_col] = p.get(_col)
697
  # ⭐⭐ W37-T14 / T15 β€” THE HONEST SETS, beside the three declared columns rather than
698
  # instead of them. The columns above answer "what does Fisch charge"; these answer "how
 
704
  # ⚠ BLANK, NOT "[]" β€” an empty cell reads as "sold in one unit / not priced on any list",
705
  # and an empty JSON array on screen reads as a bug.
706
  _tiers = tiers.get(code) or []
707
+ # ⭐⭐ W40-T09 / RULING R6 (owner I25) β€” THE PRICES, ATTRIBUTED TO THE LIST THAT CHARGES
708
+ # THEM: three (price, unit) pairs each for Fisch, Royal 1 and Royal 2.
 
 
 
 
709
  #
710
+ # β›”β›” W42-T56 / R26 β€” THE POOLED `price_1..3` / `unit_1..3` WRITE THAT USED TO STAND
711
+ # HERE IS GONE, NOT DEMOTED. W40-T09 left it in place with a comment promising the six
712
+ # "stay DECLARED and stay WRITTEN ... demoted to `default: false`"; R26 reverses that
713
+ # sentence and the write had to go with the declaration. The pooled six were the cheapest
714
+ # three prices POOLED ACROSS EVERY LIST with no attribution, so on the 1,854 SKUs priced
715
+ # on all three lists they answered a question nobody asked β€” not "what does Fisch charge"
716
+ # but "what are the three lowest numbers anyone charges" β€” and carrying both blocks made
717
+ # the grid state the same facts in two competing vocabularies.
718
+ #
719
+ # ⚠ DELETING THE CONTRACT ENTRY ALONE WOULD NOT HAVE BEEN ENOUGH, and that is why this
720
+ # loop is deleted rather than left harmlessly writing: `rows_from_pool` projects STRICTLY
721
+ # through `aios_grid_fields.json`, so an undeclared pool key is never iterated and there
722
+ # is NO CELL, silently and with no exception. Six dead writes, every gate green.
723
  #
724
  # ⚠ NO SECOND ODOO READ. `tiers` already carries the pricelist name on every entry;
725
  # `per_list_tier_cells` is a group-by over the list this loop is already holding.
 
1104
  # LEG 1 β€” COVERAGE PER LIST. Ours: cells we filled. Theirs: a bare Odoo `search_count` of
1105
  # ACTIVE products a fresh read of that list's rules reaches. The rule set is shared (it IS
1106
  # the data) but the EXPANSION is not, and the expansion is what breaks.
1107
+ # β›” GRID SUBSET β€” W42-T56 / R26. `ours` counts CELLS THAT WERE WRITTEN, so this leg must
1108
+ # enumerate the columns the grid still carries. Left at the full `PRICELIST_COLUMNS` it asks
1109
+ # Odoo for a live `search_count` on Royal 1 and Royal 2, gets a non-zero `theirs`, and counts
1110
+ # `ours = 0` because nothing writes those cells any more β€” a coverage FAILURE that is really
1111
+ # just a deleted column. The pricelists themselves are unchanged; only the grid narrowed.
1112
+ for _col, _name in products.PRICELIST_GRID_COLUMNS:
1113
  _var, _tmpl = _rule_targets(_name)
1114
  _dom = [('active', '=', True), '|', ('id', 'in', sorted(_var)),
1115
  ('product_tmpl_id', 'in', sorted(_tmpl))]
 
1126
  # render BLANK. Asked of ODOO, never of the map that produced the blank β€” "everything I left
1127
  # empty was genuinely unpriced" is trivially true when checked against the dict that emptied
1128
  # it, which is the self-sealing shape the population leg above exists to end.
1129
+ #
1130
+ # β›” BOTH HALVES OF THIS LEG NARROW TOGETHER, AND SPLITTING THEM IS THE SILENT RED β€” W42-T56.
1131
+ # `_unpriced` asks "which rows render a BLANK cell" (a GRID question, so the grid subset) and
1132
+ # `_stray` asks "does Odoo in fact price them" (also the grid subset, because it must ask
1133
+ # about the SAME lists). Narrow only the first and every SKU blank on Fisch but priced on
1134
+ # Royal 1 counts as a stray: the check goes red on a perfectly correct build.
1135
  _unpriced = [r for r in rows
1136
  if not any(isinstance(r.get(c), (int, float))
1137
+ for c, _n in products.PRICELIST_GRID_COLUMNS)]
1138
  _codes = {r["code"] for r in _unpriced}
1139
  _stray = 0
1140
  if _codes:
 
1147
  ['id', 'product_tmpl_id']):
1148
  _ids.add(_p['id'])
1149
  _tmpls.add(O.m2o_id(_p.get('product_tmpl_id')))
1150
+ for _col, _name in products.PRICELIST_GRID_COLUMNS:
1151
  _v, _t = _rule_targets(_name)
1152
  _stray += len((_v & _ids) | ({t for t in _tmpls if t in _t}))
1153
  checks.append({
1154
+ "check": "every SKU rendering a BLANK price is genuinely unpriced on every declared list "
1155
+ "that still carries a BASE grid column (W29-T52's NC: no fallback dressed as a "
1156
+ "price) β€” asked of Odoo. ⚠ NARROWED FROM 'all three' BY W42-T56/R26: Royal 1 "
1157
+ "and Royal 2 no longer have a base cell to render blank, and their per-list "
1158
+ "tier cells carry their own no-borrow NC in validate_price_and_unit_cells",
1159
  "ours": _stray, "theirs": 0, "ok": _stray == 0,
1160
  "detail": {"blank_skus": len(_unpriced), "priced_skus": len(rows) - len(_unpriced)},
1161
  })
 
1165
  # counted here rather than dropped. The ASSERTION is the one thing that must never be true β€”
1166
  # a price cell that is present and not a positive number, i.e. a "free" SKU β€” while the
1167
  # rest rides `detail` so it is reported without reddening an honest day's data.
1168
+ # β›” GRID SUBSET (W42-T56/R26) β€” all three counters below read GRID CELLS (`r.get(c)`), so
1169
+ # they enumerate the columns the grid still writes. Behaviour is IDENTICAL either way today
1170
+ # (an undeclared key returns None and every branch skips it), which is exactly why this is
1171
+ # worth naming: left wide, these read two keys that can never be present and would report a
1172
+ # narrowing rounding population as though it still covered three lists.
1173
  _bad = [r["code"] for r in rows
1174
+ for c, _n in products.PRICELIST_GRID_COLUMNS
1175
  if r.get(c) is not None and not (isinstance(r.get(c), (int, float)) and r[c] > 0)]
1176
  # β›” MEASURED 2026-08-12 AND NOT FIXABLE FROM THIS FENCE: `aios_grid.rows_from_pool` sends
1177
  # every non-text field through `_round(v)` = `round(v)` with no ndigits, i.e. to a whole
1178
  # dollar. 52.1% of fixed prices carry cents and the median relative error is 5.26%, so this
1179
  # column ties to the cent HERE and ships rounded. Reported, never silently enforced.
1180
+ _cents = sum(1 for r in rows for c, _n in products.PRICELIST_GRID_COLUMNS
1181
  if isinstance(r.get(c), (int, float)) and abs(r[c] - round(r[c])) > 1e-9)
1182
+ _to_zero = sum(1 for r in rows for c, _n in products.PRICELIST_GRID_COLUMNS
1183
  if isinstance(r.get(c), (int, float)) and round(r[c]) == 0)
1184
  checks.append({
1185
  "check": "no price cell is present-but-not-a-positive-number (a 0 would read as FREE; "
 
1513
 
1514
 
1515
  def validate_price_and_unit_cells(rows, sample=6):
1516
+ """Reconcile the typed PER-LIST tier cells to a fresh, per-SKU Odoo read.
1517
 
1518
  The pool groups price rules in bulk. This asks Odoo per SKU so a wrong grouping, a lost
1519
  package price, or a missing unit has an oracle which cannot agree by reusing that grouping.
1520
+ Duplicate SKU codes may make the pool a legitimate superset of a single product's rules,
1521
+ so every comparison below is a SUPERSET test and never an equality.
1522
+
1523
+ ⚠ W42-T56 / R26 β€” THE POOLED `price_1..3` / `unit_1..3` LEG IS GONE, THE TIER LEG STAYS.
1524
+ This function used to validate BOTH vocabularies; R26 removed the pooled six from the grid,
1525
+ so their legs went with them. Deleting the whole function would have silently dropped live
1526
+ validation of the eighteen per-list tier columns, which are the half being KEPT and the half
1527
+ that now carries the entire burden of proving the price cells are right.
1528
  """
1529
  checks = []
 
 
 
 
 
 
 
 
 
 
 
 
1530
 
1531
+ # ── W40-T09 / R6 β€” the PER-LIST cells, the only price vocabulary the grid now speaks ──────
1532
  _tier_keys = [k for t in products.PRICELIST_TIER_COLUMNS for k in t[:2]]
1533
  _typed = [r for r in rows if all(k in r for k in _tier_keys)]
1534
+ _json_cells = sum(1 for r in rows if "tier_prices" in r or "units" in r)
1535
  _per_list = {}
1536
  for _p, _u, _name, _n in products.PRICELIST_TIER_COLUMNS:
1537
  _per_list.setdefault(_name, {})[f"t{_n}"] = sum(1 for r in rows if r.get(_p) is not None)
1538
  checks.append({
1539
  "check": "the product grid serves all 18 per-list tier cells (price and unit 1..3 for "
1540
+ "each declared pricelist), TYPED and on every row β€” never JSON cells",
1541
+ "ours": {"rows_with_all_18": len(_typed), "rows": len(rows), "cells": len(_tier_keys),
1542
+ "rows_with_json_cells": _json_cells},
1543
+ "theirs": {"rows_with_all_18": len(rows), "cells": 18, "rows_with_json_cells": 0},
1544
+ # ⚠ THE `tier_prices`/`units` CLAUSE IS INHERITED, NOT NEW. It rode the pooled
1545
+ # "typed, not JSON cells" check that W42-T56/R26 deleted with the pooled columns, and it
1546
+ # is a different assertion from the one that check was named for: it guards against the
1547
+ # grid regressing to a JSON blob column instead of real typed cells. Rehomed here rather
1548
+ # than dropped, because removing a vocabulary must not quietly remove a guard.
1549
+ "ok": len(_typed) == len(rows) and len(_tier_keys) == 18 and not _json_cells,
1550
  "detail": {"skus_priced_per_list": _per_list},
1551
  })
1552
  # β›” CHEAPEST-FIRST PACKS FROM THE TOP, so a hole is the signature of a misaligned write:
 
1584
  "detail": {"sku_list_pairs_over_cap": sum(len(v) for v in _over.values())},
1585
  })
1586
 
1587
+ # β›” THE POPULATION IS RE-BASED ON THE TIER CELLS β€” W42-T56. It used to be
1588
+ # `r.get("price_1") is not None`, a column that no longer exists; left alone it is falsy on
1589
+ # every row, this function returns early, and the two live-Odoo tier oracles below (the per-list
1590
+ # superset check and the no-borrow NC) STOP RUNNING while `validate()` still reports a full
1591
+ # green β€” [[gate-that-never-ran-reads-as-failure]] at its quietest.
1592
+ # ⚠ THE NEW POPULATION IS A SUBSET OF THE OLD, deliberately: a SKU priced only on a list the
1593
+ # contract does not declare (Public Pricelist) had a pooled cell but has no tier cell, so it
1594
+ # drops out of the sample. That also means `cand` samples different SKUs than it used to.
1595
+ priced = [r for r in rows
1596
+ if any(r.get(_p) is not None
1597
+ for _p, _u, _n2, _n in products.PRICELIST_TIER_COLUMNS)]
1598
  if not priced:
1599
  return checks
1600
  o = O.get_odoo()
 
1611
  _plname = {p["id"]: str(p.get("name") or "").strip()
1612
  for p in o.search_read("product.pricelist", [], ["id", "name"])}
1613
  # Prefer SKUs that carry more than one price, the ticket's own subject.
1614
+ # Prefer SKUs carrying the most tier prices β€” the richest rows are the ticket's own subject
1615
+ # and the ones a mis-grouped write is most likely to get wrong.
1616
  cand = sorted(priced,
1617
+ key=lambda r: -sum(r.get(_p) is not None
1618
+ for _p, _u, _n2, _n in products.PRICELIST_TIER_COLUMNS)
1619
+ )[:sample]
1620
  bad_list, borrowed = [], [] # W40-T09: the per-list oracle and its no-borrow NC
1621
  for r in cand:
 
 
1622
  pid = r.get("product_id")
1623
  tmpl = None
1624
  if pid:
 
1642
  by_template.setdefault(plid, []).append(it)
1643
  picked = [it for plid in sorted(set(by_variant) | set(by_template))
1644
  for it in (by_variant.get(plid) or by_template.get(plid) or [])]
1645
+ # ── W40-T09 / R6 β€” THE ORACLE, ASKED PER LIST ──────────────────────────────
1646
+ # ⚠ SUPERSET, NOT EQUALITY, for the same D-309 reason the deleted pooled leg had: a code
 
 
 
 
 
 
 
 
1647
  # carried by two active products merges here, so one list can legitimately hold more
1648
  # pairs than a single product's rules. Equality would go red on a working build.
1649
  theirs_by_list = {}
 
1655
  # ⚠ AN EMPTY ORACLE IS NOT EVIDENCE OF BORROWING. If the per-SKU read came back with no
1656
  # rules at all, there is nothing to compare and firing the NC would report a broken
1657
  # oracle as a data defect β€” the failure mode the display-name bug above actually
1658
+ # produced. The pooled leg that used to sit above was immune by construction (an
1659
+ # empty oracle is trivially a subset) and W42-T56/R26 deleted it with the pooled
1660
+ # columns, so this is now the ONLY place that says it.
1661
  for _name in (_declared_names if picked else []):
1662
  mine_l = sorted(
1663
  (round(float(r[_price_key[(_name, n)]]), 2),
 
1674
  # prints another list's price under this list's heading.
1675
  if not theirs_by_list.get(_name) and mine_l:
1676
  borrowed.append({"sku": r.get("code"), "list": _name, "ours": mine_l})
 
 
 
 
 
 
 
1677
  checks.append({
1678
  "check": f"each sampled SKU's PER-LIST tier cells contain every live Odoo pair ON THAT "
1679
  f"LIST ({len(cand)} SKUs x {len(_declared_names)} declared pricelists)",
platform/modules/products.py CHANGED
@@ -489,6 +489,39 @@ PRICELIST_COLUMNS = (
489
  ("price_royal_2", "Royal 2"),
490
  )
491
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
492
  #: ⭐⭐ W40-T09 / RULING R6 (owner I25: *"Fisch price and Royal price each have 3 units and 3
493
  #: prices. Separate them and put all of them in the Odoo fields."*) β€” HOW MANY (price, unit)
494
  #: PAIRS EACH DECLARED LIST SHOWS.
@@ -749,8 +782,15 @@ def tier_prices_by_code(prods=None):
749
  """`({code: [{pricelist, unit_price, unit}]}, report)` β€” EVERY live price a SKU really has.
750
 
751
  ⭐⭐ W37-T14 (owner: multiple prices per SKU). `pricelist_by_code` above answers a DIFFERENT
752
- question and both are needed: it fills three DECLARED columns (`price_fisch`, `price_royal_1`,
753
- `price_royal_2`) and therefore cannot show a price on a list the contract does not name. This
 
 
 
 
 
 
 
754
  one is the honest set β€” one entry per PRICE RULE that actually prices this SKU today. One
755
  pricelist can carry Pack, Sleeve and Master rows for the same SKU; collapsing those rows to
756
  a single base price loses the unit-specific prices the catalogue needs to show.
 
489
  ("price_royal_2", "Royal 2"),
490
  )
491
 
492
+ #: β›”β›” THE PRICELIST COLUMNS THAT STILL GET A **BASE GRID COLUMN** OF THEIR OWN β€” W42-T56 / R26,
493
+ #: and this constant exists because the two jobs above were one name doing two things.
494
+ #:
495
+ #: `PRICELIST_COLUMNS` wears TWO HATS: it is a GRID FIELD LIST *and* it is this tenant's
496
+ #: PRICELIST IDENTITY REGISTRY. R26 took `price_royal_1` / `price_royal_2` off the grid β€” the
497
+ #: per-list tier block (`price_royal1_t1..t3`) supersedes them, and carrying both vocabularies
498
+ #: made the product grid answer the same question twice in two different dialects.
499
+ #:
500
+ #: β›” THEY STAY IN `PRICELIST_COLUMNS` ABOVE, AND DELETING THEM THERE IS THE ONE EDIT THAT
501
+ #: DESTROYS THIS TICKET. `PRICELIST_TIER_COLUMNS` is DERIVED from that tuple by running
502
+ #: `_pricelist_slug` over it β€” `price_royal_1` -> `royal1` -> `price_royal1_t1..t3`. Remove the
503
+ #: two entries and the six tier columns R26 explicitly PRESERVES vanish with them, silently and
504
+ #: with every gate green, because every remaining check would then agree about a smaller world.
505
+ #:
506
+ #: THE RULE, stated once: reach for THIS tuple when you are writing or counting a GRID CELL;
507
+ #: reach for `PRICELIST_COLUMNS` when you are asking about a PRICELIST (which lists exist, what
508
+ #: Odoo charges on them, what `pricelist_by_code` returns).
509
+ #:
510
+ #: ⚠ DERIVED BY FILTERING `PRICELIST_COLUMNS`, NOT RETYPED, so the label can never drift from the
511
+ #: list it names β€” and the filter is ASSERTED rather than left to yield quietly. A bare
512
+ #: comprehension would return an EMPTY tuple if `price_fisch` were ever renamed above, which
513
+ #: stops every base price cell being written and reddens nothing at import.
514
+ _GRID_PRICELIST_KEYS = ("price_fisch",)
515
+ PRICELIST_GRID_COLUMNS = tuple(
516
+ (col, name) for col, name in PRICELIST_COLUMNS if col in _GRID_PRICELIST_KEYS
517
+ )
518
+ if len(PRICELIST_GRID_COLUMNS) != len(_GRID_PRICELIST_KEYS):
519
+ raise RuntimeError(
520
+ f"PRICELIST_GRID_COLUMNS names {_GRID_PRICELIST_KEYS} but PRICELIST_COLUMNS only "
521
+ f"offers {[c for c, _n in PRICELIST_COLUMNS]} β€” a pricelist was renamed without "
522
+ f"updating the grid subset, and the silent result is a base price column that is "
523
+ f"never written")
524
+
525
  #: ⭐⭐ W40-T09 / RULING R6 (owner I25: *"Fisch price and Royal price each have 3 units and 3
526
  #: prices. Separate them and put all of them in the Odoo fields."*) β€” HOW MANY (price, unit)
527
  #: PAIRS EACH DECLARED LIST SHOWS.
 
782
  """`({code: [{pricelist, unit_price, unit}]}, report)` β€” EVERY live price a SKU really has.
783
 
784
  ⭐⭐ W37-T14 (owner: multiple prices per SKU). `pricelist_by_code` above answers a DIFFERENT
785
+ question and both are needed: it resolves a base price for all three DECLARED lists
786
+ (`price_fisch`, `price_royal_1`, `price_royal_2`) and therefore cannot show a price on a list
787
+ the contract does not name.
788
+
789
+ ⚠ ONLY ONE OF THOSE THREE IS STILL A GRID COLUMN. W42-T56 / R26 took `price_royal_1` and
790
+ `price_royal_2` off the product grid β€” the per-list tier block supersedes them β€” so
791
+ `pricelist_by_code` still RESOLVES all three (the key is its pricelist identity, and
792
+ `PRICELIST_TIER_COLUMNS` is derived from those very names) while only
793
+ `PRICELIST_GRID_COLUMNS` is written into a cell. Two hats; see that constant. This
794
  one is the honest set β€” one entry per PRICE RULE that actually prices this SKU today. One
795
  pricelist can carry Pack, Sleeve and Master rows for the same SKU; collapsing those rows to
796
  a single base price loses the unit-specific prices the catalogue needs to show.
web/src/customer-grid/ColumnMenu.tsx CHANGED
@@ -18,14 +18,18 @@ import { columnDefinitionOffer } from "./display";
18
  // that must be runnable rather than read back to itself as source text.
19
  import { CODE_LANGUAGE_LABELS, CODE_LANGUAGES, CREATABLE_TYPES, choiceOptions, choiceRenames,
20
  codeLanguageOf, directionLabel, groupTypePickerRows, isDerivedLink, isMachineOwned,
21
- isProfileField, parseOptions, ratingMax, ROLLUP_FN_LABELS, ROLLUP_FNS,
22
- ROLLUP_REF_OPS, mayEditFieldDefinition } from "./types";
23
- import type { AggName, Field, FieldFormat, FieldScope, FieldType, Measure, RollupCondition, RollupFn,
 
 
 
 
24
  RollupRefOp, RollupSource, Viewer } from "./types";
25
  import type { LinkTarget, RollupSourceOffer } from "./apiBridge";
26
  import type { WindowSpec } from "./windows";
27
  import { normalizeWindow, windowLabel } from "./windows";
28
- import { WindowPicker } from "../filter-kit";
29
  // ⭐⭐ W41-T29 (R6, contract C2) β€” the ONE pair of rights predicates plus the copy that says what
30
  // they refused, read from the same module the Fields manager reads. C2: no surface re-implements
31
  // either test, so this menu asks rather than deriving a second answer of its own.
@@ -100,7 +104,9 @@ interface FieldConfigExtra {
100
  geocode?: { addressField: string; country?: string };
101
  /** ⭐ 2026-08-07 β€” a `link` column's target. REQUIRED for the type: `_clean_field` returns
102
  * None for a link with no bag, so a create without this is a column that never appears. */
103
- link?: { table: string; single?: boolean };
 
 
104
  /** ⭐ 2026-08-07 β€” a `rollup` column's aggregate. Same requirement, same reason.
105
  * ⭐ 2026-08-09 β€” or, INSTEAD, a `source` binding: the read-through kind, which summarises
106
  * rows that were never copied into the workspace. The host's `_clean_rollup` reads `source`
@@ -162,6 +168,28 @@ interface ColumnMenuProps {
162
  * as it was before this existed. So this prop is what turns the second kind ON, not a flag.
163
  */
164
  rollupSourceOffer?: RollupSourceOffer;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
165
  locked: boolean;
166
  /** Product-owned preset fields may still drive view actions, but their schema is immutable. */
167
  schemaLocked?: boolean;
@@ -296,11 +324,20 @@ interface ColumnMenuProps {
296
  * DIFFERENT ACT from `onDelete`, and therefore a different door: it destroys no definition and
297
  * no values, and pointing "Remove from my fields" at the delete handler would be a benign word
298
  * on a destructive action.
299
- * ⚠ OPTIONAL for `onDelete`'s reason, and unwired today: `CustomerGrid.tsx` is another lane's
300
- * file and no endpoint unshares a field yet. The half of R6(b) that holds without it is the
301
- * REFUSAL: a shared-with-me column loses its Delete row whether or not this handler arrives.
 
 
 
 
 
 
 
 
 
302
  */
303
- onRemoveFromMine?: () => void;
304
  /** ⭐⭐ Wave-34 (R13) β€” run this AI enrichment column over many rows.
305
  * `scope` is `"blank"` (only cells still empty) or `"always"` (every row the AI
306
  * wrote). OPTIONAL for `onDelete`'s reason: a host that has not wired the door shows
@@ -680,11 +717,15 @@ function optionDrafts(
680
  function optionSettings(
681
  drafts: OptionDraft[],
682
  type: CreateKind
683
- ): { options: string[]; colors: Record<string, string> } {
684
  const clean = drafts.map((draft) =>
685
  type === "multiselect" ? draft.label.replace(/,/g, " ") : draft.label
686
  );
687
- const options = parseOptions(clean.join("\n"));
 
 
 
 
688
  const firstByLabel = new Map<string, OptionDraft>();
689
  drafts.forEach((draft, index) => {
690
  const label = clean[index].trim();
@@ -700,7 +741,7 @@ function optionSettings(
700
  if (color && color !== normalizeOptionColor(defaultOptionColor(option)))
701
  colors[option] = color;
702
  }
703
- return { options, colors };
704
  }
705
 
706
  function optionAppearanceSignature(
@@ -910,6 +951,15 @@ function OptionsEditor({
910
  {settings.options.length} option{settings.options.length === 1 ? "" : "s"}.
911
  {type === "multiselect" && " Commas inside an option are not supported."}
912
  </span>
 
 
 
 
 
 
 
 
 
913
  </div>
914
  );
915
  }
@@ -922,6 +972,20 @@ function OptionsEditor({
922
  */
923
  type CreateKind = FieldType | "measure" | "geocode";
924
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
925
  /**
926
  * ⭐⭐ W37-T22 (R4 / C7) β€” the geocode pseudo-kind's picker label, and the address-column families
927
  * it may read. Declared here beside `CreateKind` because three places consume them (the picker
@@ -956,10 +1020,12 @@ function TypePicker({
956
  onPick,
957
  offerMeasure,
958
  offerGeocode,
 
 
959
  only,
960
  }: {
961
- value: CreateKind;
962
- onPick: (k: CreateKind) => void;
963
  offerMeasure: boolean;
964
  /**
965
  * ⭐⭐ W37-T22 (R4 / C7) β€” offer the geocode pseudo-kind. REQUIRED, not optional: an optional
@@ -977,17 +1043,47 @@ function TypePicker({
977
  * "has an address column", which is what W37-T22's `done-when` asks for.
978
  */
979
  offerGeocode: boolean;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
980
  /** Restrict the list (the Edit-field pane passes RETYPE_TYPES β€” the overlay-editable
981
  * strata a created field may become). Absent = every creatable type. */
982
  only?: readonly FieldType[];
983
  }) {
984
  const [q, setQ] = useState("");
985
  const needle = q.trim().toLowerCase();
986
- const base = only
 
 
 
 
987
  ? FIELD_TYPES.filter((r) => (only as readonly string[]).includes(r.value))
988
  : FIELD_TYPES;
989
- const rows: { value: CreateKind; label: string }[] = [
 
990
  ...base,
 
 
 
 
 
 
 
 
 
 
 
991
  // C-NAME (item 9, 2026-08-02): "Formula measure (over a period)" -> "Metric". Two words
992
  // of jargon and a parenthetical, replaced by the word people already use for the thing.
993
  // The internal key stays `measure` β€” see the C-NAME amendment in the wave doc.
@@ -1056,14 +1152,41 @@ function TypePicker({
1056
  >
1057
  {/* Each row wears the mark its COLUMN will wear. A measure column's real type is
1058
  currency/int/pct and a geocode column's is `text`, so both pseudo-kinds borrow
1059
- rather than inventing a glyph no column ever shows (the iconShapes ruling). */}
 
 
1060
  <FieldTypeIcon
1061
  type={
1062
- r.value === "measure" ? "currency" : r.value === "geocode" ? "text" : r.value
 
1063
  }
1064
  size={16}
1065
  />
1066
- <span className="cg-type-label">{r.label}</span>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1067
  {value === r.value && (
1068
  <svg
1069
  className="cg-type-check"
@@ -1234,6 +1357,182 @@ const AI_ENRICH_OVERWRITE: ReadonlyArray<{ value: string; label: string }> = [
1234
  { value: "always", label: "Every row the AI wrote, every run" },
1235
  ];
1236
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1237
  function ExtraTypeEditor({
1238
  kind,
1239
  fields,
@@ -1257,6 +1556,8 @@ function ExtraTypeEditor({
1257
  onLinkTable,
1258
  linkSingle = false,
1259
  onLinkSingle,
 
 
1260
  rollupMode = "link",
1261
  onRollupMode,
1262
  rollupSourceOffer = { topics: [], windows: [] },
@@ -1323,6 +1624,31 @@ function ExtraTypeEditor({
1323
  onLinkTable?: (v: string) => void;
1324
  linkSingle?: boolean;
1325
  onLinkSingle?: (v: boolean) => void;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1326
  /** ⭐ 2026-08-09 β€” which KIND of rollup is being built. `"link"` folds workspace rows;
1327
  * `"source"` reads through to a governed Odoo topic without copying a row into the store. */
1328
  rollupMode?: "link" | "source";
@@ -1356,7 +1682,11 @@ function ExtraTypeEditor({
1356
  if (kind === "formula") {
1357
  // 2026-07-31 (owner item 2): other FORMULA fields are referencable now β€” evaluation is
1358
  // topological and a cycle is refused at validation, so the old exclusion is gone.
1359
- const referencable = fields.filter((f) => f.key !== "__proto__");
 
 
 
 
1360
  return (
1361
  <>
1362
  <label>
@@ -1613,7 +1943,10 @@ function ExtraTypeEditor({
1613
  // thing it reads. The schedule and the Run-now button are NOT here β€” they belong to the
1614
  // automation itself, on the Automation surface, because one job can fill a column across
1615
  // many records and its cadence is a property of the job, not of the column.
1616
- const urlish = fields.filter((f) => f.type === "url" || f.type === "text");
 
 
 
1617
  const chosen = AUTOMATION_KINDS.find((k) => k.key === automationKind)
1618
  ?? AUTOMATION_KINDS[0];
1619
  return (
@@ -1671,6 +2004,16 @@ function ExtraTypeEditor({
1671
  if (kind === "link") {
1672
  // ⭐ 2026-08-07 β€” Airtable's "Link to another record", and the whole editor is ONE question:
1673
  // which database. The relation itself is then the cell (a set of linked rows).
 
 
 
 
 
 
 
 
 
 
1674
  return (
1675
  <>
1676
  <label>
@@ -1702,10 +2045,196 @@ function ExtraTypeEditor({
1702
  />
1703
  <span>Allow only one linked record</span>
1704
  </label>
1705
- <div className="cg-field-hint">
1706
- A cell here holds the records you pick. Add a Rollup column afterwards to summarise a
1707
- column of those records β€” an average, a total, a count.
1708
- </div>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1709
  </>
1710
  );
1711
  }
@@ -1716,7 +2245,10 @@ function ExtraTypeEditor({
1716
  // WHICH column, folded HOW, and across WHICH records. That last control is the owner's
1717
  // headline ("average Views over last N posts") and Airtable cannot express it β€” its rollup
1718
  // conditions filter by predicate, never by rank.
1719
- const linkFields = fields.filter((f) => f.type === "link");
 
 
 
1720
  const chosenLink = linkFields.find((f) => f.key === rollupLink);
1721
  const target = linkTargets.find((t) => t.key === chosenLink?.link?.table);
1722
  const targetFields = target?.fields ?? [];
@@ -1734,7 +2266,9 @@ function ExtraTypeEditor({
1734
  onRollupSource?.({ ...rollupSource, ...patch });
1735
  // ⚠ A join column must hold a SCALAR the group key can equal. Link and rollup columns hold a
1736
  // comma-joined id list and a computed value respectively, so neither can ever match.
1737
- const joinable = fields.filter(
 
 
1738
  (f) => f.type !== "link" && f.type !== "rollup" && f.key !== "__proto__"
1739
  );
1740
  const sourceEditor = (
@@ -1847,6 +2381,12 @@ function ExtraTypeEditor({
1847
  );
1848
  const linkEditor = (
1849
  <>
 
 
 
 
 
 
1850
  <label>
1851
  <span>Through</span>
1852
  <select
@@ -1868,6 +2408,10 @@ function ExtraTypeEditor({
1868
  link, so add one of those first.
1869
  </div>
1870
  ) : null}
 
 
 
 
1871
  <label>
1872
  <span>Fold</span>
1873
  <select
@@ -1882,6 +2426,7 @@ function ExtraTypeEditor({
1882
  ))}
1883
  </select>
1884
  </label>
 
1885
  {needsField ? (
1886
  <label>
1887
  <span>Column</span>
@@ -1930,6 +2475,14 @@ function ExtraTypeEditor({
1930
  unavailable. Ask an admin to share that database with you, then reopen this editor.
1931
  </div>
1932
  ) : null}
 
 
 
 
 
 
 
 
1933
  {/*
1934
  ⭐⭐ 2026-08-09 (owner) β€” THE PRE-FILTER, ABOVE THE WINDOW, AND THE SCREEN ORDER IS THE
1935
  ORDER OF OPERATIONS. Owner: *"instead of last 12 posts, we also want to make it so its
@@ -2038,6 +2591,8 @@ function ExtraTypeEditor({
2038
  targetFields={targetFields}
2039
  allowRef
2040
  />
 
 
2041
  <div className="cg-field-hint">
2042
  Computed for you and refreshed as the linked records change β€” the cell cannot be typed
2043
  into.
@@ -2048,7 +2603,10 @@ function ExtraTypeEditor({
2048
  // connected source the offer is empty, and a two-way toggle whose second option can never
2049
  // work is a control that configures nothing ([[wrong-parent-not-broken-control]]). The link
2050
  // editor is then simply what a rollup is, exactly as it was before this existed.
2051
- if (!sourceTopics.length) return linkEditor;
 
 
 
2052
  return (
2053
  <>
2054
  <label>
@@ -2123,6 +2681,8 @@ export default function ColumnMenu({
2123
  onClearGroup,
2124
  userOptions = [],
2125
  measures = [],
 
 
2126
  tableKey,
2127
  }: ColumnMenuProps) {
2128
  /**
@@ -2238,7 +2798,9 @@ export default function ColumnMenu({
2238
  /** C5-AUTOFIELD β€” the create form's automation config. */
2239
  const [automationKind, setAutomationKind] = useState(AUTOMATION_KINDS[0].key);
2240
  const [automationUrlField, setAutomationUrlField] = useState(
2241
- () => fields.find((f) => f.type === "url")?.key ?? ""
 
 
2242
  );
2243
  /**
2244
  * ⭐ 2026-08-07 β€” the create form's LINK and ROLLUP configuration.
@@ -2250,6 +2812,12 @@ export default function ColumnMenu({
2250
  */
2251
  const [linkTable, setLinkTable] = useState("");
2252
  const [linkSingle, setLinkSingle] = useState(false);
 
 
 
 
 
 
2253
  /** ⭐ 2026-08-09 β€” the read-through half. `rollupMode` decides which bag `extraFor` builds;
2254
  * the two are mutually exclusive because the host's `_clean_rollup` returns the `source`
2255
  * shape before it ever reads `link`. */
@@ -2268,6 +2836,46 @@ export default function ColumnMenu({
2268
  const [rollupWhereConj, setRollupWhereConj] = useState<"and" | "or">("and");
2269
  const [rollupConditions, setRollupConditions] = useState<RollupCondition[]>([]);
2270
  const [rollupConditionConj, setRollupConditionConj] = useState<"and" | "or">("and");
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2271
  const [swapTo, setSwapTo] = useState("");
2272
  /** The "New field" half of Change-field keeps its own name/options β€” a half-typed insert
2273
  * form must not leak into a swap and vice versa. */
@@ -2368,6 +2976,13 @@ export default function ColumnMenu({
2368
  });
2369
  const [editLinkTable, setEditLinkTable] = useState(() => field.link?.table ?? "");
2370
  const [editLinkSingle, setEditLinkSingle] = useState(() => field.link?.single === true);
 
 
 
 
 
 
 
2371
 
2372
  const swapToNewType = swapTo.startsWith(NEW_PREFIX)
2373
  ? (swapTo.slice(NEW_PREFIX.length) as FieldType)
@@ -2377,7 +2992,8 @@ export default function ColumnMenu({
2377
  const options = createChoice.options;
2378
  const swapChoice = swapToNewType
2379
  ? optionSettings(swapOptionDrafts, swapToNewType)
2380
- : { options: [] as string[], colors: {} as Record<string, string> };
 
2381
  const swapNewOptions = swapChoice.options;
2382
  /** Owner item 8 β€” the Edit pane's parsed choices for the drafted type. */
2383
  const editChoice = optionSettings(editOptionDrafts, editType);
@@ -2427,7 +3043,10 @@ export default function ColumnMenu({
2427
  * permanently unable to run.
2428
  */
2429
  const addressFields = useMemo(
2430
- () => fields.filter((f) => (GEOCODE_ADDRESS_TYPES as readonly string[]).includes(f.type)),
 
 
 
2431
  [fields]
2432
  );
2433
  const offerGeocode = geocodable && addressFields.length > 0;
@@ -2445,6 +3064,10 @@ export default function ColumnMenu({
2445
  const canCreate =
2446
  effectiveLabel.trim() !== "" &&
2447
  (!needsOptions(kind) || options.length > 0) &&
 
 
 
 
2448
  (kind !== "measure" || !!chosenMeasure) &&
2449
  // ⭐⭐ W37-T22 (R4 / C7) β€” a geocode column with no address column to read is a column no run
2450
  // can ever fill: the identical argument the `automation` URL-column rule below makes, and the
@@ -2465,7 +3088,11 @@ export default function ColumnMenu({
2465
  // `ai_enrich` column with no prompt, so creating one without this gate produces a column that
2466
  // is named, configured and simply absent on the next read.
2467
  (kind !== "ai_enrich" || aiEnrich.prompt.trim() !== "") &&
2468
- (kind !== "link" || linkTable !== "") &&
 
 
 
 
2469
  (kind !== "rollup" || (rollupMode === "source"
2470
  // ⭐ 2026-08-09 β€” the read-through bag. ALL FOUR keys are required by `_clean_rollup`
2471
  // (`if not (topic and measure and group_by and on): return None`), and `on` is the one a
@@ -2484,7 +3111,18 @@ export default function ColumnMenu({
2484
  t: CreateKind,
2485
  src: string,
2486
  starCount: number,
2487
- lang: string
 
 
 
 
 
 
 
 
 
 
 
2488
  ): FieldConfigExtra | undefined => {
2489
  if (t === "formula") return { formula: src.trim() };
2490
  if (t === "rating") return { max: starCount };
@@ -2526,7 +3164,19 @@ export default function ColumnMenu({
2526
  // picks records). The DERIVED mode is the automation's, spawned with its join declared β€”
2527
  // offering "join on a column of the other table" here would be a second, harder mental
2528
  // model for the same button.
2529
- if (t === "link") return { link: { table: linkTable, ...(linkSingle ? { single: true } : {}) } };
 
 
 
 
 
 
 
 
 
 
 
 
2530
  if (t === "rollup" && rollupMode === "source")
2531
  // β›” THE SOURCE BAG TRAVELS ALONE. `_clean_rollup` reads `source` first and returns
2532
  // immediately, so sending `link`/`fn` alongside it would ship keys the store drops β€”
@@ -2621,7 +3271,7 @@ export default function ColumnMenu({
2621
  onCreate(clean, kind, position === "end" ? null : field.key, position,
2622
  needsOptions(kind) ? options : undefined, undefined,
2623
  withScope({
2624
- ...extraFor(kind, formulaText, maxValue, codeLanguage),
2625
  ...optionExtraFor(kind, createChoice.colors, createColorCode),
2626
  }));
2627
  onClose();
@@ -2631,6 +3281,10 @@ export default function ColumnMenu({
2631
  swapToNewType != null &&
2632
  swapLabel.trim() !== "" &&
2633
  (!needsOptions(swapToNewType) || swapNewOptions.length > 0) &&
 
 
 
 
2634
  (swapToNewType !== "formula" || swapFormulaCheck.ok) &&
2635
  // ⭐⭐ Wave-34 (R13) β€” the SAME completeness gate `canCreate` carries, on this door too.
2636
  //
@@ -2653,7 +3307,8 @@ export default function ColumnMenu({
2653
  swapToNewType,
2654
  needsOptions(swapToNewType) ? swapNewOptions : undefined,
2655
  withScope({
2656
- ...extraFor(swapToNewType, swapFormulaText, swapMaxValue, swapCodeLanguage),
 
2657
  ...optionExtraFor(swapToNewType, swapChoice.colors, swapColorCode),
2658
  })
2659
  );
@@ -2764,7 +3419,13 @@ export default function ColumnMenu({
2764
  (field.type === "rollup"
2765
  ? JSON.stringify(editRollup) !== JSON.stringify(field.rollup ?? {})
2766
  : editLinkTable !== (field.link?.table ?? "") ||
2767
- editLinkSingle !== (field.link?.single === true));
 
 
 
 
 
 
2768
  const canSaveEdit =
2769
  /**
2770
  * ⭐ W41-T31 β€” THE DESCRIPTION-ONLY PANE'S WHOLE SAVE CONDITION, and it is one dirty flag
@@ -2788,9 +3449,16 @@ export default function ColumnMenu({
2788
  // is refused by the server, so Save is refused here instead: a 400 arriving after the click
2789
  // is the same "named, configured, gone" surprise one layer later.
2790
  (editType !== "ai_enrich" || aiEnrich.prompt.trim() !== "") &&
 
 
 
2791
  (editingRelational
2792
  ? (editRollupValid && (editRelationalTouched || editNameDirty || editNoteDirty) &&
2793
- (field.type !== "link" || editLinkTable !== ""))
 
 
 
 
2794
  : (editNameDirty || editRetypeTouched || editFormulaTouched ||
2795
  (canPeriod && periodChanged) || editNoteDirty)));
2796
  /**
@@ -2836,8 +3504,15 @@ export default function ColumnMenu({
2836
  ...(editNameDirty ? { label: cleanRename } : {}),
2837
  ...(field.type === "rollup"
2838
  ? { rollup: editRollup as Record<string, unknown> }
 
 
 
 
2839
  : { link: { table: editLinkTable,
2840
- ...(editLinkSingle ? { single: true } : {}) } }),
 
 
 
2841
  });
2842
  if (editNoteDirty) onNote(note);
2843
  onClose();
@@ -2920,7 +3595,10 @@ export default function ColumnMenu({
2920
  * would contain; `swapOffered` is whether the picker exists at all, and it is read twice (the
2921
  * control itself, and the focus fallback that has to know whether the control is there).
2922
  */
2923
- const swapOptions = fields.filter((f) => f.key !== field.key);
 
 
 
2924
  const presetSwap = swapOptions.filter((f) => f.source === "odoo" && !f.custom);
2925
  const yourSwap = swapOptions.filter((f) => !(f.source === "odoo" && !f.custom));
2926
  const swapOffered = offer.swap && swapOptions.length > 0;
@@ -3089,10 +3767,12 @@ export default function ColumnMenu({
3089
  rows, Airtable-style. The measure row appears exactly when the host offers
3090
  measures β€” the same availability rule as the filter's measure conditions. */}
3091
  <TypePicker
3092
- value={kind}
3093
- onPick={setKind}
3094
  offerMeasure={measures.length > 0}
3095
  offerGeocode={offerGeocode}
 
 
3096
  />
3097
  </div>
3098
  {kind === "measure" && (
@@ -3195,6 +3875,17 @@ export default function ColumnMenu({
3195
  onLinkTable={setLinkTable}
3196
  linkSingle={linkSingle}
3197
  onLinkSingle={setLinkSingle}
 
 
 
 
 
 
 
 
 
 
 
3198
  rollupMode={rollupMode}
3199
  onRollupMode={setRollupMode}
3200
  rollupSourceOffer={rollupSourceOffer}
@@ -3504,7 +4195,18 @@ export default function ColumnMenu({
3504
  onLinkTable={setEditLinkTable}
3505
  linkSingle={editLinkSingle}
3506
  onLinkSingle={setEditLinkSingle}
 
 
 
 
 
 
 
3507
  rollupSourceOffer={rollupSourceOffer}
 
 
 
 
3508
  rollupMode={editRollup.source ? "source" : "link"}
3509
  // β›” A MODE SWITCH REPLACES THE BAG, it does not merge into it. `_clean_rollup`
3510
  // reads `source` first and returns before it ever looks at `link`, so a bag
@@ -3573,6 +4275,8 @@ export default function ColumnMenu({
3573
  codeLanguage={editCodeLanguage}
3574
  onCodeLanguage={setEditCodeLanguage}
3575
  idPrefix="cg-edit"
 
 
3576
  automationKind={editAutomationKind}
3577
  onAutomationKind={setEditAutomationKind}
3578
  automationUrlField={editAutomationUrlField}
@@ -3589,6 +4293,14 @@ export default function ColumnMenu({
3589
  value={editType}
3590
  onPick={(k) => setEditType(k as FieldType)}
3591
  offerMeasure={false}
 
 
 
 
 
 
 
 
3592
  offerGeocode={
3593
  /* β›” FALSE ON PURPOSE, and stated rather than omitted: this is the RETYPE
3594
  picker, and a geocode column is not a type an existing column can BECOME.
@@ -3731,6 +4443,8 @@ export default function ColumnMenu({
3731
  codeLanguage={editCodeLanguage}
3732
  onCodeLanguage={setEditCodeLanguage}
3733
  idPrefix="cg-edit"
 
 
3734
  showFormulaHelp={false}
3735
  />
3736
  )}
@@ -3847,6 +4561,11 @@ export default function ColumnMenu({
3847
  codeLanguage={swapCodeLanguage}
3848
  onCodeLanguage={setSwapCodeLanguage}
3849
  idPrefix="cg-swap"
 
 
 
 
 
3850
  />
3851
  {needsOptions(swapToNewType) && (
3852
  <OptionsEditor
@@ -4323,18 +5042,30 @@ export default function ColumnMenu({
4323
  <div className="cg-menu-sep" role="separator" aria-hidden />
4324
 
4325
  {/* Group 3 β€” sort. Direction wording stays the shipped per-type directionLabel. */}
4326
- <button type="button" onClick={() => { onSort("asc"); onClose(); }}>
4327
- <MenuLabel
4328
- icon="sortAsc"
4329
- text={`Sort ${directionLabel(field.type, "asc")}`}
4330
- />
4331
- </button>
4332
- <button type="button" onClick={() => { onSort("desc"); onClose(); }}>
4333
- <MenuLabel
4334
- icon="sortDesc"
4335
- text={`Sort ${directionLabel(field.type, "desc")}`}
4336
- />
4337
- </button>
 
 
 
 
 
 
 
 
 
 
 
 
4338
  {sortedDir != null && (
4339
  <button type="button" onClick={() => { onClearSort(); onClose(); }}>
4340
  <MenuLabel icon="off" text="Don't sort by this field" />
 
18
  // that must be runnable rather than read back to itself as source text.
19
  import { CODE_LANGUAGE_LABELS, CODE_LANGUAGES, CREATABLE_TYPES, choiceOptions, choiceRenames,
20
  codeLanguageOf, directionLabel, groupTypePickerRows, isDerivedLink, isMachineOwned,
21
+ isProfileField, offerableCreateKind, parseOptions, ratingMax, ROLLUP_FN_LABELS, ROLLUP_FNS,
22
+ ROLLUP_PRESET_FNS, ROLLUP_PRESETS, ROLLUP_REF_OPS, rollupPresetOf, TYPE_DESCRIPTIONS,
23
+ mayEditFieldDefinition } from "./types";
24
+ import { ROUTE_PROJECTION_KEY, ROUTE_SORT_REFUSAL_TEXT, filterTreeConj, filterTreeNodes,
25
+ offerableFields } from "./types";
26
+ import type { AggName, Conjunction, Field, FieldFormat, FieldScope, FieldType, FilterNode,
27
+ Measure, RollupCondition, RollupFn, RollupPreset,
28
  RollupRefOp, RollupSource, Viewer } from "./types";
29
  import type { LinkTarget, RollupSourceOffer } from "./apiBridge";
30
  import type { WindowSpec } from "./windows";
31
  import { normalizeWindow, windowLabel } from "./windows";
32
+ import { FilterBuilderPanel, WindowPicker } from "../filter-kit";
33
  // ⭐⭐ W41-T29 (R6, contract C2) β€” the ONE pair of rights predicates plus the copy that says what
34
  // they refused, read from the same module the Fields manager reads. C2: no surface re-implements
35
  // either test, so this menu asks rather than deriving a second answer of its own.
 
104
  geocode?: { addressField: string; country?: string };
105
  /** ⭐ 2026-08-07 β€” a `link` column's target. REQUIRED for the type: `_clean_field` returns
106
  * None for a link with no bag, so a create without this is a column that never appears. */
107
+ /** ⭐⭐ W42-T08 (R1, C1) β€” plus, OPTIONALLY, the two-hop `via`. Absent is today's one-hop
108
+ * join, byte-identical to what this menu emitted before the hop existed. */
109
+ link?: { table: string; single?: boolean; via?: HopViaBag };
110
  /** ⭐ 2026-08-07 β€” a `rollup` column's aggregate. Same requirement, same reason.
111
  * ⭐ 2026-08-09 β€” or, INSTEAD, a `source` binding: the read-through kind, which summarises
112
  * rows that were never copied into the workspace. The host's `_clean_rollup` reads `source`
 
168
  * as it was before this existed. So this prop is what turns the second kind ON, not a flag.
169
  */
170
  rollupSourceOffer?: RollupSourceOffer;
171
+ /**
172
+ * ⭐⭐ W42-T08 (R1, contract C2) β€” the topics a Link field's HOP may travel through, each
173
+ * carrying its dims already shaped as `Field[]` so the existing condition builder can take
174
+ * them as its `fields` prop with no adapter in between. Fetched by the host from
175
+ * `GET /grid/hop-topics`.
176
+ *
177
+ * ⚠ EMPTY RENDERS THE QUESTION AND SAYS SO rather than hiding it. An unwired surface that
178
+ * simply vanishes is indistinguishable from a feature that was never built, and this file's
179
+ * fence could not make the prop required at this boundary. W42-T09 wires it.
180
+ */
181
+ hopTopics?: HopTopic[];
182
+ /**
183
+ * ⭐⭐ W42-T08 (contract C1 `scope_key`) β€” the cohort scope of THIS database: `customer`,
184
+ * `product`, or a `ut_*` key. `CustomerGrid` already holds it as `scope` at this mount.
185
+ *
186
+ * β›” IT IS NOT `tableKey`. That prop is `payload.workspace.storageKey`
187
+ * (`product_table_workspace` for a registry topic), and deriving one from the other by
188
+ * stripping a suffix is the near-miss class this menu already carries a warning about. Absent
189
+ * means no `via` may be emitted at all, because a bag missing `scope_key` loses every cohort
190
+ * leaf without a word.
191
+ */
192
+ hopScopeKey?: string;
193
  locked: boolean;
194
  /** Product-owned preset fields may still drive view actions, but their schema is immutable. */
195
  schemaLocked?: boolean;
 
324
  * DIFFERENT ACT from `onDelete`, and therefore a different door: it destroys no definition and
325
  * no values, and pointing "Remove from my fields" at the delete handler would be a benign word
326
  * on a destructive action.
327
+ * ⭐⭐ W42-T13 (instruction 2, D-485) β€” REQUIRED NOW, AND THAT IS THE WHOLE TICKET. It shipped
328
+ * OPTIONAL and unwired, and the control below is gated on the handler's own presence
329
+ * (`canRemoveFromMine && onRemoveFromMine`), so with no host feeding it the row did not render
330
+ * at all: on screen, indistinguishable from a feature nobody built. Required means an unfed
331
+ * mount stops compiling instead of quietly offering nothing.
332
+ *
333
+ * β›” WHAT IT MAY NOT BE IS A SILENT NO-OP. No server door drops you off a field's own grant
334
+ * list: `PUT /share/{kind}/{oid}` needs `may_administer`, which a plain grantee does not hold,
335
+ * and sending `entries: []` there is the OWNER revoking everyone, a different act. So the host
336
+ * hands this the same refusal `useFieldBulkDoors::onRemoveField` already speaks for the Fields
337
+ * manager, which says so in one sentence. A button that renders, is pressed, and does nothing
338
+ * is strictly worse than a button that is absent.
339
  */
340
+ onRemoveFromMine: () => void;
341
  /** ⭐⭐ Wave-34 (R13) β€” run this AI enrichment column over many rows.
342
  * `scope` is `"blank"` (only cells still empty) or `"always"` (every row the AI
343
  * wrote). OPTIONAL for `onDelete`'s reason: a host that has not wired the door shows
 
717
  function optionSettings(
718
  drafts: OptionDraft[],
719
  type: CreateKind
720
+ ): { options: string[]; colors: Record<string, string>; capMessage: string | null } {
721
  const clean = drafts.map((draft) =>
722
  type === "multiselect" ? draft.label.replace(/,/g, " ") : draft.label
723
  );
724
+ // ⭐⭐ W42-T37 (C8b) β€” THE CAP TRAVELS WITH THE LIST. `parseOptions` no longer slices the tail
725
+ // off in silence, so its refusal has to reach both save doors and the pane that shows it; a
726
+ // caller that took only `.options` would put the silence back here instead.
727
+ const parsed = parseOptions(clean.join("\n"));
728
+ const options = parsed.options;
729
  const firstByLabel = new Map<string, OptionDraft>();
730
  drafts.forEach((draft, index) => {
731
  const label = clean[index].trim();
 
741
  if (color && color !== normalizeOptionColor(defaultOptionColor(option)))
742
  colors[option] = color;
743
  }
744
+ return { options, colors, capMessage: parsed.message };
745
  }
746
 
747
  function optionAppearanceSignature(
 
951
  {settings.options.length} option{settings.options.length === 1 ? "" : "s"}.
952
  {type === "multiselect" && " Commas inside an option are not supported."}
953
  </span>
954
+ {/* ⭐⭐ W42-T37 (C8b) β€” THE CAP, SAID OUT LOUD, ON THE ONE PANE EVERY OPTION LIST MOUNTS.
955
+ Standing rule 1's second half: the limit is reported with its cause and what to do,
956
+ never applied behind the person's back. The save doors refuse alongside this, so the
957
+ sentence explains a Create button that has stopped working rather than replacing it. */}
958
+ {settings.capMessage ? (
959
+ <span className="cg-field-hint" role="alert">
960
+ {settings.capMessage}
961
+ </span>
962
+ ) : null}
963
  </div>
964
  );
965
  }
 
972
  */
973
  type CreateKind = FieldType | "measure" | "geocode";
974
 
975
+ /**
976
+ * ⭐⭐ W42-T37 (G3) β€” WHAT THE PICKER CAN OFFER, which is one row wider than what the create pane
977
+ * can BUILD. A preset is a starting point for a `rollup`, not a kind: pick "Count" and `kind`
978
+ * becomes `"rollup"` with its fold already chosen, so nothing downstream of the pick ever sees
979
+ * either name. That is why this union stops at the picker and `CreateKind` is untouched: widening
980
+ * `CreateKind` would push two words that are not types into every switch that renders a cell,
981
+ * which is the failure `CreateKind`'s own comment describes for `measure`.
982
+ */
983
+ type PickerKind = CreateKind | RollupPreset;
984
+
985
+ /** The two presets' rows. The nouns Airtable uses, because they are the words somebody migrating
986
+ * types into the find box; the description under each says it is a rollup. */
987
+ const PRESET_LABELS: Record<RollupPreset, string> = { count: "Count", lookup: "Lookup" };
988
+
989
  /**
990
  * ⭐⭐ W37-T22 (R4 / C7) β€” the geocode pseudo-kind's picker label, and the address-column families
991
  * it may read. Declared here beside `CreateKind` because three places consume them (the picker
 
1020
  onPick,
1021
  offerMeasure,
1022
  offerGeocode,
1023
+ offerPresets,
1024
+ isUserTable,
1025
  only,
1026
  }: {
1027
+ value: PickerKind;
1028
+ onPick: (k: PickerKind) => void;
1029
  offerMeasure: boolean;
1030
  /**
1031
  * ⭐⭐ W37-T22 (R4 / C7) β€” offer the geocode pseudo-kind. REQUIRED, not optional: an optional
 
1043
  * "has an address column", which is what W37-T22's `done-when` asks for.
1044
  */
1045
  offerGeocode: boolean;
1046
+ /**
1047
+ * ⭐⭐ W42-T37 (G3) β€” offer the Count and Lookup PRESETS. REQUIRED for `offerGeocode`'s exact
1048
+ * reason, and false on the retype picker on purpose: a preset AUTHORS a rollup bag, and the
1049
+ * retype pane changes a column's type without authoring anything (its own comment books that
1050
+ * gap for the geocode row already).
1051
+ */
1052
+ offerPresets: boolean;
1053
+ /**
1054
+ * ⭐⭐ W42-T37 (D-497) β€” this grid is a `ut_*` runtime database, so the picker withholds the
1055
+ * kinds `user_tables._clean_field` refuses. REQUIRED, not optional, for the third time in this
1056
+ * signature: an optional flag defaults to "Odoo grid" at whichever mount forgets it, and the
1057
+ * defect being fixed IS a menu offering a kind the server returns `None` for.
1058
+ */
1059
+ isUserTable: boolean;
1060
  /** Restrict the list (the Edit-field pane passes RETYPE_TYPES β€” the overlay-editable
1061
  * strata a created field may become). Absent = every creatable type. */
1062
  only?: readonly FieldType[];
1063
  }) {
1064
  const [q, setQ] = useState("");
1065
  const needle = q.trim().toLowerCase();
1066
+ // ⭐⭐ W42-T37 (D-497) β€” THE WITHHOLDING HAPPENS HERE, ONCE, OVER THE WHOLE VOCABULARY, and it
1067
+ // is a `types.ts` predicate rather than a `type !== "created_time"` written into this JSX: a
1068
+ // rule stated inside a React file is a rule no node gate can run, and this one answers to the
1069
+ // server's own `UT_FIELD_TYPES` through `verify_rollup_editor.py`.
1070
+ const offerable = only
1071
  ? FIELD_TYPES.filter((r) => (only as readonly string[]).includes(r.value))
1072
  : FIELD_TYPES;
1073
+ const base = offerable.filter((r) => offerableCreateKind(r.value, isUserTable));
1074
+ const rows: { value: PickerKind; label: string }[] = [
1075
  ...base,
1076
+ // ⭐⭐ W42-T37 (G3) β€” COUNT AND LOOKUP, the two rollups people arrive looking for by name.
1077
+ // They are PRESETS: picking one selects the rollup kind and fixes its fold, so the editor
1078
+ // below can ask only what is left. No new member of any type vocabulary (contract C8), and
1079
+ // they sit in the ORDINARY group deliberately, which is the entire point of adding them: the
1080
+ // rollup they are made of has just moved under Advanced.
1081
+ ...(offerPresets
1082
+ ? ROLLUP_PRESETS.map((preset) => ({
1083
+ value: preset as PickerKind,
1084
+ label: PRESET_LABELS[preset],
1085
+ }))
1086
+ : []),
1087
  // C-NAME (item 9, 2026-08-02): "Formula measure (over a period)" -> "Metric". Two words
1088
  // of jargon and a parenthetical, replaced by the word people already use for the thing.
1089
  // The internal key stays `measure` β€” see the C-NAME amendment in the wave doc.
 
1152
  >
1153
  {/* Each row wears the mark its COLUMN will wear. A measure column's real type is
1154
  currency/int/pct and a geocode column's is `text`, so both pseudo-kinds borrow
1155
+ rather than inventing a glyph no column ever shows (the iconShapes ruling).
1156
+ ⭐ W42-T37: a Count or Lookup column's real type IS `rollup`, so the presets
1157
+ borrow that mark for the same reason rather than earning a glyph of their own. */}
1158
  <FieldTypeIcon
1159
  type={
1160
+ r.value === "measure" ? "currency" : r.value === "geocode" ? "text"
1161
+ : r.value === "count" || r.value === "lookup" ? "rollup" : r.value
1162
  }
1163
  size={16}
1164
  />
1165
+ {/* ⭐⭐ W42-T37 (R24) β€” THE LABEL AND THE LINE THAT SAYS WHAT IT DOES.
1166
+ β›” INSIDE the button, not a sibling of it: arrow-key navigation collects
1167
+ `button.cg-type-row`, so a description outside would be a row the keyboard
1168
+ walks past and a screen reader reads detached from its option.
1169
+ ⚠ The layout is stated here rather than in index.css because that stylesheet
1170
+ belongs to another fence this wave; `.cg-type-label` keeps its own `flex: 1`
1171
+ and only its single-line clamp is lifted, which is the property a second line
1172
+ needs. */}
1173
+ <span
1174
+ className="cg-type-label"
1175
+ style={{
1176
+ display: "flex", flexDirection: "column", gap: 1,
1177
+ whiteSpace: "normal", overflow: "visible", minWidth: 0,
1178
+ }}
1179
+ >
1180
+ <span>{r.label}</span>
1181
+ <span
1182
+ style={{
1183
+ fontSize: "var(--lp-fs-3xs)", color: "var(--lp-muted)",
1184
+ fontWeight: 400, lineHeight: 1.3,
1185
+ }}
1186
+ >
1187
+ {TYPE_DESCRIPTIONS[r.value]}
1188
+ </span>
1189
+ </span>
1190
  {value === r.value && (
1191
  <svg
1192
  className="cg-type-check"
 
1357
  { value: "always", label: "Every row the AI wrote, every run" },
1358
  ];
1359
 
1360
+ // ──────���──────────────────────────────────────────────────────────────────────────────────────
1361
+ // W42-T08 (ruling R1, contracts C1 + C2) β€” THE HOP.
1362
+ //
1363
+ // A user-created Link field may take TWO HOPS: instead of the user picking rows by hand, the
1364
+ // column reaches the other database THROUGH a governed topic (the order lines that connect a
1365
+ // customer to a product). The user declares that middle step here, at field-creation time, with
1366
+ // the same condition builder every other filter on the product is authored in.
1367
+ //
1368
+ // β›” THE BAG'S KEY NAMES ARE C1, NOT A CHOICE. `aios-web/api/verify_pivot.py` asserts that the
1369
+ // key set the server accepts and the key set THIS FILE emits are identical name-for-name, so
1370
+ // `source_dim` is snake_case because the server spells it that way and `filterConj` is camelCase
1371
+ // for the same reason. Rename one half and the join stops resolving with no error anywhere.
1372
+ //
1373
+ // β›” `target_key` AND `scope_key` ARE NOT DIM NAMES, and this is the trap the ideation record
1374
+ // walked into. `target_key` is a column of the TARGET DATABASE (the value its rows join on) and
1375
+ // `scope_key` is the cohort scope of the database the column is being created ON. Drop
1376
+ // `target_key` and the server matches nothing and still answers 200 with an empty row list: no
1377
+ // refusal, no error, a column of blanks. So both are required before a `via` is emitted at all.
1378
+ //
1379
+ // β›” `source_key` IS DELIBERATELY ABSENT (C1). It is the seventh key of the route table this
1380
+ // ruling dissolves, and it does not travel onto `via`.
1381
+ // ─────────────────────────────────────────────────────────────────────────────────────────────
1382
+
1383
+ /**
1384
+ * C2 β€” one topic as the hop question offers it.
1385
+ *
1386
+ * ⚠ `dims` IS A `Field[]`, NOT the `{key,label,keyedBy}` shape `apiBridge.RollupSourceTopic.dims`
1387
+ * carries. `FilterBuilderPanel` fetches nothing and takes its whole vocabulary as a `fields`
1388
+ * prop, so a topic whose dims already ARE fields can be filtered by the existing control with no
1389
+ * adapter in between. That is the entire reason `GET /grid/hop-topics` exists beside
1390
+ * `/tables/rollup-sources`, and deriving a `type` from `keyedBy` here instead would produce a
1391
+ * plausible operand list with the wrong operators, which is worse than none.
1392
+ */
1393
+ export interface HopTopic {
1394
+ key: string;
1395
+ label: string;
1396
+ dims: Field[];
1397
+ measures: { key: string; label: string }[];
1398
+ }
1399
+
1400
+ /**
1401
+ * C1's `via`, ON THE WIRE β€” nine keys, and the parity gate reads THIS declaration as the client's
1402
+ * emitted key set. `source_dim` is snake_case and `filterConj` is camelCase because the server
1403
+ * spells them that way; do not tidy either.
1404
+ */
1405
+ export interface HopViaBag {
1406
+ topic: string;
1407
+ source_dim: string;
1408
+ target_dim: string;
1409
+ target_key: string;
1410
+ scope_key: string;
1411
+ measure: string;
1412
+ filter: FilterNode[];
1413
+ filterConj: Conjunction;
1414
+ window: string;
1415
+ }
1416
+
1417
+ /** The hop as the editor holds it while it is being authored. `topic: ""` means NO hop. */
1418
+ export interface HopDraft {
1419
+ topic: string;
1420
+ sourceDim: string;
1421
+ targetDim: string;
1422
+ targetKey: string;
1423
+ measure: string;
1424
+ filter: FilterNode[];
1425
+ filterConj: Conjunction;
1426
+ window: string;
1427
+ /**
1428
+ * β›”β›” THE STORED `scope_key`, CARRIED RATHER THAN RE-DERIVED, and it is a scar not a style.
1429
+ *
1430
+ * The relational save is a REBUILD, and `hopVia` refuses to emit a bag with no scope. Derive
1431
+ * the scope from the HOST prop alone and a field with a saved hop, opened on any surface that
1432
+ * does not pass that prop, re-emits its link bag WITHOUT the hop: one rename click silently
1433
+ * deletes a configured join. So a bag that already carries its scope keeps it, and the host's
1434
+ * prop answers only for a hop being authored for the first time.
1435
+ */
1436
+ scopeKey: string;
1437
+ }
1438
+
1439
+ /** ⚠ A FRESH OBJECT PER CALL. `filter` is an array and a shared literal would let one draft's
1440
+ * conditions surface in the next field the user creates. */
1441
+ /**
1442
+ * β›” THE NO-WINDOW KEY IS `all_time`, NOT `all`. `core.user_tables.ROLLUP_SOURCE_WINDOWS` is the
1443
+ * validator's closed set and it spells the whole-history window `all_time`; it is also what
1444
+ * `GET /tables/rollup-sources` offers, so a draft defaulted to anything outside that list would
1445
+ * give a `<select>` whose value matches no option, which renders the FIRST option instead with no
1446
+ * warning. The control would then read "Year to date" while the bag saved something else.
1447
+ * ⚠ C1's example writes `"window": "all"`; that spelling is not in any live vocabulary and is
1448
+ * reported in this ticket's handoff for the lane that owns the server half.
1449
+ */
1450
+ export const HOP_WINDOW_ALL = "all_time";
1451
+
1452
+ export const emptyHopDraft = (): HopDraft => ({
1453
+ topic: "", sourceDim: "", targetDim: "", targetKey: "",
1454
+ measure: "", filter: [], filterConj: "and", window: HOP_WINDOW_ALL, scopeKey: "",
1455
+ });
1456
+
1457
+ /** What one mount of the hop question needs. `null` at a mount that cannot save a hop. */
1458
+ export interface HopOffer {
1459
+ topics: HopTopic[];
1460
+ /** The window vocabulary of the topic being travelled through. */
1461
+ windows: { key: string; label: string }[];
1462
+ /** C1 `scope_key` β€” the cohort scope of the database this column is being created on. It is a
1463
+ * fact about the HOST grid, never a question for the user, so it arrives rather than being
1464
+ * picked. Empty means the host could not name it, and then no `via` may be emitted. */
1465
+ scopeKey: string;
1466
+ draft: HopDraft;
1467
+ onDraft: (patch: Partial<HopDraft>) => void;
1468
+ }
1469
+
1470
+ /**
1471
+ * C1's `via`, or `null` when the hop is blank OR half-declared.
1472
+ *
1473
+ * β›” HALF-DECLARED EMITS NOTHING, and the caller's Create door refuses instead. `_clean_link`
1474
+ * refuses the WHOLE field on a bad `via`, so shipping an incomplete one produces a column that
1475
+ * is named, configured and simply absent on the next read.
1476
+ */
1477
+ export function hopVia(
1478
+ draft: HopDraft | null | undefined,
1479
+ scopeKey: string
1480
+ ): HopViaBag | null {
1481
+ if (!draft) return null;
1482
+ const topic = draft.topic.trim();
1483
+ const sourceDim = draft.sourceDim.trim();
1484
+ const targetDim = draft.targetDim.trim();
1485
+ const targetKey = draft.targetKey.trim();
1486
+ const measure = draft.measure.trim();
1487
+ // β›” THE BAG'S OWN SCOPE WINS. See `HopDraft.scopeKey`: a stored hop must survive a rebuild on a
1488
+ // surface that does not pass the host prop, and the prop answers only for a NEW hop.
1489
+ const scope = (draft.scopeKey || scopeKey || "").trim();
1490
+ if (!topic || !sourceDim || !targetDim || !targetKey || !measure || !scope) return null;
1491
+ // Exactly C1's nine keys, in C1's spelling, and nothing else.
1492
+ return {
1493
+ topic,
1494
+ source_dim: sourceDim,
1495
+ target_dim: targetDim,
1496
+ target_key: targetKey,
1497
+ scope_key: scope,
1498
+ measure,
1499
+ filter: draft.filter,
1500
+ filterConj: draft.filterConj,
1501
+ window: draft.window || HOP_WINDOW_ALL,
1502
+ };
1503
+ }
1504
+
1505
+ /** True when the user has begun a hop but has not finished it. The Create/Save door reads this. */
1506
+ export const hopIncomplete = (draft: HopDraft | null | undefined, scopeKey: string): boolean =>
1507
+ !!draft && draft.topic.trim() !== "" && hopVia(draft, scopeKey) === null;
1508
+
1509
+ /**
1510
+ * Seed a draft from a STORED bag.
1511
+ *
1512
+ * ⚠ THE CAST IS DELIBERATE AND IT IS OWED. `types.ts::Field.link` does not declare `via` yet;
1513
+ * that file belongs to W42-T09 / W42-T37 in this lane, and this ticket's fence is two files.
1514
+ * Reading the key through a narrow local shape is what lets the EDIT pane round-trip an existing
1515
+ * hop instead of rebuilding the bag without it, which would silently delete a saved hop on the
1516
+ * next rename. See the HANDOFF's PENDING line.
1517
+ */
1518
+ export function hopDraftFrom(link: unknown): HopDraft {
1519
+ const via = (link as { via?: Record<string, unknown> } | null | undefined)?.via;
1520
+ const draft = emptyHopDraft();
1521
+ if (!via || typeof via !== "object") return draft;
1522
+ const str = (v: unknown) => (typeof v === "string" ? v : "");
1523
+ return {
1524
+ topic: str(via.topic),
1525
+ sourceDim: str(via.source_dim),
1526
+ targetDim: str(via.target_dim),
1527
+ targetKey: str(via.target_key),
1528
+ measure: str(via.measure),
1529
+ filter: Array.isArray(via.filter) ? (via.filter as FilterNode[]) : [],
1530
+ filterConj: via.filterConj === "or" ? "or" : "and",
1531
+ window: str(via.window) || HOP_WINDOW_ALL,
1532
+ scopeKey: str(via.scope_key),
1533
+ };
1534
+ }
1535
+
1536
  function ExtraTypeEditor({
1537
  kind,
1538
  fields,
 
1556
  onLinkTable,
1557
  linkSingle = false,
1558
  onLinkSingle,
1559
+ hop,
1560
+ rollupPreset = null,
1561
  rollupMode = "link",
1562
  onRollupMode,
1563
  rollupSourceOffer = { topics: [], windows: [] },
 
1624
  onLinkTable?: (v: string) => void;
1625
  linkSingle?: boolean;
1626
  onLinkSingle?: (v: boolean) => void;
1627
+ /**
1628
+ * ⭐⭐ W42-T08 (R1, C1 + C2) β€” the HOP question, and it is REQUIRED at every mount on purpose.
1629
+ *
1630
+ * β›” OPTIONAL WOULD BE THE SAFE-LOOKING WRONG CHOICE (PRD "cross-feature wirings"): an omitted
1631
+ * optional prop degrades to "the feature does not exist", which is indistinguishable from never
1632
+ * built. Required makes `tsc` name every mount the day this lands.
1633
+ *
1634
+ * β›” `null` IS A STATEMENT, NOT AN OMISSION β€” "this mount cannot save a hop, so do not paint
1635
+ * one". The automation, formula and swap mounts pass it: the swap form supplies no link
1636
+ * plumbing at all, so a hop authored there would configure nothing, which this file's own
1637
+ * rules call worse than no control.
1638
+ */
1639
+ hop: HopOffer | null;
1640
+ /**
1641
+ * ⭐⭐ W42-T37 (G3) β€” this rollup is a Count or a Lookup, so the editor asks ONLY what that
1642
+ * preset still needs: the link column, plus the column to look up. The fold is already decided,
1643
+ * and a "Fold" select showing one answer nobody may change is a control that configures
1644
+ * nothing.
1645
+ *
1646
+ * ⚠ THE EDIT PANE PASSES IT TOO, computed from the STORED bag by `types.ts::rollupPresetOf` β€”
1647
+ * that is what makes a Count re-open as a Count rather than as a rollup folded by "Count of
1648
+ * records". `rollupPresetOf` is exact, so a bag carrying anything beyond the preset's own keys
1649
+ * answers `null` and opens in the full editor with every value it holds visible.
1650
+ */
1651
+ rollupPreset?: RollupPreset | null;
1652
  /** ⭐ 2026-08-09 β€” which KIND of rollup is being built. `"link"` folds workspace rows;
1653
  * `"source"` reads through to a governed Odoo topic without copying a row into the store. */
1654
  rollupMode?: "link" | "source";
 
1682
  if (kind === "formula") {
1683
  // 2026-07-31 (owner item 2): other FORMULA fields are referencable now β€” evaluation is
1684
  // topological and a cycle is refused at validation, so the old exclusion is gone.
1685
+ // C11 (W42-T54) β€” a formula's reference picker is a field picker, so it offers the
1686
+ // OFFERABLE columns. ⚠ The formula VALIDATION sets (`known` below, `knownKeys` further
1687
+ // down) are deliberately NOT narrowed: they answer "does this column exist", and a
1688
+ // formula already stored against a route column would start reporting an unknown field.
1689
+ const referencable = offerableFields(fields).filter((f) => f.key !== "__proto__");
1690
  return (
1691
  <>
1692
  <label>
 
1943
  // thing it reads. The schedule and the Run-now button are NOT here β€” they belong to the
1944
  // automation itself, on the Automation surface, because one job can fill a column across
1945
  // many records and its cadence is a property of the job, not of the column.
1946
+ // C11 β€” a picker. Type-narrowed already, so today it can only have held the route
1947
+ // PROJECTION column (text), which passes through by contract; filtered anyway so the
1948
+ // rule does not depend on a route position staying numeric.
1949
+ const urlish = offerableFields(fields).filter((f) => f.type === "url" || f.type === "text");
1950
  const chosen = AUTOMATION_KINDS.find((k) => k.key === automationKind)
1951
  ?? AUTOMATION_KINDS[0];
1952
  return (
 
2004
  if (kind === "link") {
2005
  // ⭐ 2026-08-07 β€” Airtable's "Link to another record", and the whole editor is ONE question:
2006
  // which database. The relation itself is then the cell (a set of linked rows).
2007
+ //
2008
+ // ⭐⭐ W42-T08 (R1) β€” plus ONE added question, and the panel now reads as the sentence it
2009
+ // always was: which database, then through what, then filtered how. It sits INLINE under the
2010
+ // settings it belongs to, which is where the reference art puts a link field's own condition
2011
+ // block; a wizard or a second modal is forbidden by this wave's design contract.
2012
+ const hopTarget = linkTargets.find((t) => t.key === linkTable);
2013
+ const hopTargetFields = hopTarget?.fields ?? [];
2014
+ const hopTopic = hop?.topics.find((t) => t.key === hop.draft.topic);
2015
+ const hopWindow = hop?.draft.window || HOP_WINDOW_ALL;
2016
+ const hopWindowOffered = (hop?.windows ?? []).some((w) => w.key === hopWindow);
2017
  return (
2018
  <>
2019
  <label>
 
2045
  />
2046
  <span>Allow only one linked record</span>
2047
  </label>
2048
+ {/* β›”β›” THIS SENTENCE IS FALSE ONCE A HOP IS SET, so it is not shown then. With a hop the
2049
+ cell does not hold "the records you pick": it holds the records the middle step
2050
+ resolves, and a panel asserting otherwise beside the control that changed it is the
2051
+ surface telling the user something untrue about their own column. It is also a
2052
+ TERMINAL summary, and the hop question below has to follow the reading order the
2053
+ design contract fixes: which database, then through what, then filtered how.
2054
+ ⚠ NOTHING REPLACES IT. The hop's own controls already say what the column does; a
2055
+ second paragraph here would be the app narrating itself (DESIGN.md Β§4). */}
2056
+ {hop?.draft.topic ? null : (
2057
+ <div className="cg-field-hint">
2058
+ A cell here holds the records you pick. Add a Rollup column afterwards to summarise a
2059
+ column of those records β€” an average, a total, a count.
2060
+ </div>
2061
+ )}
2062
+ {hop ? (
2063
+ <div className="cg-hop">
2064
+ <label className="cg-hop-question">
2065
+ <span>Through</span>
2066
+ <select
2067
+ id={`${idPrefix}-hop-topic`}
2068
+ className="cg-input"
2069
+ value={hop.draft.topic}
2070
+ aria-label="Live data this link travels through"
2071
+ onChange={(event) =>
2072
+ // β›” CLEAR EVERY KEY THAT NAMES SOMETHING OF THE OLD TOPIC. Both dims, the
2073
+ // measure and every filter leaf belong TO the topic, so carrying them across a
2074
+ // topic change leaves a bag naming dims the new topic does not have, which the
2075
+ // save door refuses on a form that looks complete. Same rule the source rollup
2076
+ // above follows for its measure and its grouping.
2077
+ hop.onDraft({
2078
+ topic: event.target.value,
2079
+ sourceDim: "", targetDim: "", measure: "", filter: [], filterConj: "and",
2080
+ })
2081
+ }
2082
+ >
2083
+ <option value="">Nothing, I will pick the records myself</option>
2084
+ {hop.topics.map((t) => (
2085
+ <option key={t.key} value={t.key}>{t.label}</option>
2086
+ ))}
2087
+ </select>
2088
+ </label>
2089
+ {hop.topics.length === 0 ? (
2090
+ <div className="cg-field-hint">
2091
+ No live data is offered for this workspace, so there is nothing to travel through.
2092
+ </div>
2093
+ ) : null}
2094
+ {hopTopic ? (
2095
+ <div className="cg-hop-body">
2096
+ <label>
2097
+ <span>Matched from</span>
2098
+ <select
2099
+ id={`${idPrefix}-hop-source-dim`}
2100
+ className="cg-input"
2101
+ value={hop.draft.sourceDim}
2102
+ aria-label="What names a row of this database"
2103
+ onChange={(event) => hop.onDraft({ sourceDim: event.target.value })}
2104
+ >
2105
+ <option value="">Choose what names a row here…</option>
2106
+ {hopTopic.dims.map((d) => (
2107
+ <option key={d.key} value={d.key}>{d.label}</option>
2108
+ ))}
2109
+ </select>
2110
+ </label>
2111
+ <label>
2112
+ <span>Matched to</span>
2113
+ <select
2114
+ id={`${idPrefix}-hop-target-dim`}
2115
+ className="cg-input"
2116
+ value={hop.draft.targetDim}
2117
+ aria-label="What names a row of the other database"
2118
+ onChange={(event) => hop.onDraft({ targetDim: event.target.value })}
2119
+ >
2120
+ <option value="">Choose what names a row over there…</option>
2121
+ {hopTopic.dims.map((d) => (
2122
+ <option key={d.key} value={d.key}>{d.label}</option>
2123
+ ))}
2124
+ </select>
2125
+ </label>
2126
+ {hopTopic.dims.length === 0 ? (
2127
+ <div className="cg-field-hint">
2128
+ This data offers nothing to match on, so it cannot be travelled through.
2129
+ </div>
2130
+ ) : null}
2131
+ {/* β›” C1 `target_key`, AND IT IS NOT A DIM. It is the column of the OTHER
2132
+ database whose value the target dim equals. Leave it out and the server
2133
+ matches nothing and still answers 200 with an empty row list: no refusal, no
2134
+ error, a column of blanks. So the control is offered, and the Create door
2135
+ below refuses without it. */}
2136
+ <label>
2137
+ <span>Column over there</span>
2138
+ <select
2139
+ id={`${idPrefix}-hop-target-key`}
2140
+ className="cg-input"
2141
+ value={hop.draft.targetKey}
2142
+ aria-label="Column in the other database holding that value"
2143
+ onChange={(event) => hop.onDraft({ targetKey: event.target.value })}
2144
+ >
2145
+ <option value="">Choose the other database's column…</option>
2146
+ {hopTargetFields.map((f) => (
2147
+ <option key={f.key} value={f.key}>{f.label}</option>
2148
+ ))}
2149
+ </select>
2150
+ </label>
2151
+ {linkTable === "" ? (
2152
+ <div className="cg-field-hint">
2153
+ Choose a database above first, so its columns can be listed here.
2154
+ </div>
2155
+ ) : hopTargetFields.length === 0 ? (
2156
+ <div className="cg-field-hint">
2157
+ The columns of <b>{linkTable}</b> cannot be listed here, so nothing can be
2158
+ matched against them. Ask an admin to share that database with you, then
2159
+ reopen this editor.
2160
+ </div>
2161
+ ) : null}
2162
+ <label>
2163
+ <span>Measure</span>
2164
+ <select
2165
+ id={`${idPrefix}-hop-measure`}
2166
+ className="cg-input"
2167
+ value={hop.draft.measure}
2168
+ aria-label="Measure"
2169
+ onChange={(event) => hop.onDraft({ measure: event.target.value })}
2170
+ >
2171
+ <option value="">Choose a measure…</option>
2172
+ {hopTopic.measures.map((m) => (
2173
+ <option key={m.key} value={m.key}>{m.label}</option>
2174
+ ))}
2175
+ </select>
2176
+ </label>
2177
+ {hopTopic.measures.length === 0 ? (
2178
+ <div className="cg-field-hint">
2179
+ This data offers no measure yet, so the hop cannot be completed.
2180
+ </div>
2181
+ ) : null}
2182
+ {/* β›”β›” A `<select>` WHOSE VALUE MATCHES NO OPTION RENDERS THE FIRST ONE, SILENTLY.
2183
+ A stored bag may carry a window spelling this offer does not list (C1's
2184
+ example writes `all`, while the validator's closed set spells it `all_time`),
2185
+ and without this row the control would show "Today" while the field saved
2186
+ something else: the control and the saved value disagreeing on screen, which
2187
+ is the exact class of lie this ticket exists to close. So an unlisted value is
2188
+ OFFERED BACK, under its own key, and the user can leave it or replace it. */}
2189
+ {hop.windows.length > 0 ? (
2190
+ <label>
2191
+ <span>Over</span>
2192
+ <select
2193
+ id={`${idPrefix}-hop-window`}
2194
+ className="cg-input"
2195
+ value={hopWindow}
2196
+ aria-label="Date window"
2197
+ onChange={(event) => hop.onDraft({ window: event.target.value })}
2198
+ >
2199
+ {hopWindowOffered ? null : (
2200
+ <option value={hopWindow}>{hopWindow}</option>
2201
+ )}
2202
+ {hop.windows.map((w) => (
2203
+ <option key={w.key} value={w.key}>{w.label}</option>
2204
+ ))}
2205
+ </select>
2206
+ </label>
2207
+ ) : null}
2208
+ {/* ⭐⭐ C2 β€” THE FILTER IS THE CONTROL THAT ALREADY EXISTS. `FilterBuilderPanel`
2209
+ fetches nothing and already mounts against a foreign field list in two
2210
+ permission editors, so the hop reuses it verbatim rather than growing a second
2211
+ condition builder.
2212
+ β›” `fields` AND NOTHING ELSE. `via.filter` is validated server-side against
2213
+ the TOPIC's own store columns, so a cohort, view or measure leaf authored here
2214
+ would be a condition the server drops without saying so. */}
2215
+ <div className="cg-hop-filter">
2216
+ <span className="cg-type-title">Keep only</span>
2217
+ <FilterBuilderPanel
2218
+ fields={hopTopic.dims}
2219
+ filters={{ conj: hop.draft.filterConj, nodes: hop.draft.filter }}
2220
+ onChange={(next) =>
2221
+ hop.onDraft({
2222
+ filter: filterTreeNodes(next),
2223
+ filterConj: filterTreeConj(next),
2224
+ })
2225
+ }
2226
+ />
2227
+ </div>
2228
+ {(hop.draft.scopeKey || hop.scopeKey).trim() === "" ? (
2229
+ <div className="cg-field-hint">
2230
+ This database cannot be named as the starting point of a middle step yet, so
2231
+ the hop cannot be saved.
2232
+ </div>
2233
+ ) : null}
2234
+ </div>
2235
+ ) : null}
2236
+ </div>
2237
+ ) : null}
2238
  </>
2239
  );
2240
  }
 
2245
  // WHICH column, folded HOW, and across WHICH records. That last control is the owner's
2246
  // headline ("average Views over last N posts") and Airtable cannot express it β€” its rollup
2247
  // conditions filter by predicate, never by rank.
2248
+ // C11 β€” a picker. `type === "link"` cannot hold a route column today; filtered for the
2249
+ // same reason `urlish` is, so offerability is a property of PICKERS here and not a list
2250
+ // of the types that happen to collide with routes this wave.
2251
+ const linkFields = offerableFields(fields).filter((f) => f.type === "link");
2252
  const chosenLink = linkFields.find((f) => f.key === rollupLink);
2253
  const target = linkTargets.find((t) => t.key === chosenLink?.link?.table);
2254
  const targetFields = target?.fields ?? [];
 
2266
  onRollupSource?.({ ...rollupSource, ...patch });
2267
  // ⚠ A join column must hold a SCALAR the group key can equal. Link and rollup columns hold a
2268
  // comma-joined id list and a computed value respectively, so neither can ever match.
2269
+ // C11 β€” a picker, and the widest one in this file: every scalar column. This is the one
2270
+ // that would have offered all ~64 route positions as join columns.
2271
+ const joinable = offerableFields(fields).filter(
2272
  (f) => f.type !== "link" && f.type !== "rollup" && f.key !== "__proto__"
2273
  );
2274
  const sourceEditor = (
 
2381
  );
2382
  const linkEditor = (
2383
  <>
2384
+ {/* ⭐⭐ W42-T37 (G3) β€” A PRESET SAYS WHAT IT IS, IN THE PANE, IN THE SAME WORDS THE PICKER
2385
+ USED. It is one rollup among sixteen folds, and a person who chose "Count" should be
2386
+ able to see that without being asked to configure it again. */}
2387
+ {rollupPreset ? (
2388
+ <div className="cg-field-hint">{TYPE_DESCRIPTIONS[rollupPreset]}</div>
2389
+ ) : null}
2390
  <label>
2391
  <span>Through</span>
2392
  <select
 
2408
  link, so add one of those first.
2409
  </div>
2410
  ) : null}
2411
+ {/* β›” W42-T37 β€” THE FOLD IS THE ONE QUESTION A PRESET HAS ALREADY ANSWERED, so the preset
2412
+ editor does not ask it. Hidden rather than disabled: a greyed select showing "Count of
2413
+ records" invites a click that can never do anything. */}
2414
+ {rollupPreset ? null : (
2415
  <label>
2416
  <span>Fold</span>
2417
  <select
 
2426
  ))}
2427
  </select>
2428
  </label>
2429
+ )}
2430
  {needsField ? (
2431
  <label>
2432
  <span>Column</span>
 
2475
  unavailable. Ask an admin to share that database with you, then reopen this editor.
2476
  </div>
2477
  ) : null}
2478
+ {/* β›”β›” W42-T37 β€” EVERYTHING BELOW BELONGS TO THE FULL ROLLUP, AND A PRESET RENDERS NONE OF
2479
+ IT. The window, the de-duplication and both condition lists are what makes our rollup a
2480
+ superset of Airtable's fold; a Count is the ONE preset shape whose bag carries none of
2481
+ them, and `rollupPresetOf` refuses to call any bag a preset once one is set. So hiding
2482
+ them here can never hide a stored value: the two facts are the same rule, written once
2483
+ on each side of the round trip. */}
2484
+ {rollupPreset ? null : (
2485
+ <>
2486
  {/*
2487
  ⭐⭐ 2026-08-09 (owner) β€” THE PRE-FILTER, ABOVE THE WINDOW, AND THE SCREEN ORDER IS THE
2488
  ORDER OF OPERATIONS. Owner: *"instead of last 12 posts, we also want to make it so its
 
2591
  targetFields={targetFields}
2592
  allowRef
2593
  />
2594
+ </>
2595
+ )}
2596
  <div className="cg-field-hint">
2597
  Computed for you and refreshed as the linked records change β€” the cell cannot be typed
2598
  into.
 
2603
  // connected source the offer is empty, and a two-way toggle whose second option can never
2604
  // work is a control that configures nothing ([[wrong-parent-not-broken-control]]). The link
2605
  // editor is then simply what a rollup is, exactly as it was before this existed.
2606
+ // β›” AND A PRESET IS A LINK FOLD BY DEFINITION. Count and Lookup both count or list the
2607
+ // records a LINK reaches, so the read-through mode is not a choice they have; showing the
2608
+ // Summarise switch would offer a second answer that their own bag cannot express.
2609
+ if (rollupPreset || !sourceTopics.length) return linkEditor;
2610
  return (
2611
  <>
2612
  <label>
 
2681
  onClearGroup,
2682
  userOptions = [],
2683
  measures = [],
2684
+ hopTopics = [],
2685
+ hopScopeKey = "",
2686
  tableKey,
2687
  }: ColumnMenuProps) {
2688
  /**
 
2798
  /** C5-AUTOFIELD β€” the create form's automation config. */
2799
  const [automationKind, setAutomationKind] = useState(AUTOMATION_KINDS[0].key);
2800
  const [automationUrlField, setAutomationUrlField] = useState(
2801
+ // C11 β€” the DEFAULT for the `urlish` picker above, narrowed with it: a default the
2802
+ // picker does not list is a control that opens showing something it cannot re-select.
2803
+ () => offerableFields(fields).find((f) => f.type === "url")?.key ?? ""
2804
  );
2805
  /**
2806
  * ⭐ 2026-08-07 β€” the create form's LINK and ROLLUP configuration.
 
2812
  */
2813
  const [linkTable, setLinkTable] = useState("");
2814
  const [linkSingle, setLinkSingle] = useState(false);
2815
+ // ⭐⭐ W42-T08 (R1, C1) β€” the HOP draft for the create pane. `topic: ""` is "no hop", and it is
2816
+ // the default, so a Link field created without touching this question emits exactly the bag it
2817
+ // emitted before this existed.
2818
+ const [hopDraft, setHopDraft] = useState<HopDraft>(emptyHopDraft);
2819
+ const patchHopDraft = (patch: Partial<HopDraft>) =>
2820
+ setHopDraft((prev) => ({ ...prev, ...patch }));
2821
  /** ⭐ 2026-08-09 β€” the read-through half. `rollupMode` decides which bag `extraFor` builds;
2822
  * the two are mutually exclusive because the host's `_clean_rollup` returns the `source`
2823
  * shape before it ever reads `link`. */
 
2836
  const [rollupWhereConj, setRollupWhereConj] = useState<"and" | "or">("and");
2837
  const [rollupConditions, setRollupConditions] = useState<RollupCondition[]>([]);
2838
  const [rollupConditionConj, setRollupConditionConj] = useState<"and" | "or">("and");
2839
+ /**
2840
+ * ⭐⭐ W42-T37 (G3) β€” WHICH PRESET THE CREATE PANE IS BUILDING, or `null` for a rollup authored
2841
+ * in full. It is picker state, never payload: `extraFor` reads the same rollup drafts it always
2842
+ * did, so a Count saves the bag `{link, fn: "countall"}` that `_clean_rollup` already accepts
2843
+ * and returns unchanged, and re-opens through `rollupPresetOf` as a Count.
2844
+ *
2845
+ * β›” IT CANNOT BE DERIVED FROM `kind` AND MUST NOT BE. `kind` is `"rollup"` for all three, so a
2846
+ * derived answer would show the reduced editor to somebody who chose Rollup outright and had
2847
+ * not filled anything in yet.
2848
+ */
2849
+ const [rollupPreset, setRollupPreset] = useState<RollupPreset | null>(null);
2850
+ /**
2851
+ * The picker's one entry point. A preset row selects the rollup kind and FIXES its fold; every
2852
+ * other row clears the preset, because leaving one set would open the reduced editor on a kind
2853
+ * that is not a rollup at all.
2854
+ *
2855
+ * β›” THE WINDOW AND BOTH CONDITION LISTS ARE CLEARED WITH IT. A preset's editor does not render
2856
+ * them, so a value left behind by an abandoned rollup draft would ride out on the bag from
2857
+ * controls the person can no longer see: configuration nobody chose, on a column nobody could
2858
+ * inspect. That is also what keeps the saved bag EXACTLY the preset shape `rollupPresetOf`
2859
+ * recognises, which is the round trip this ticket asserts.
2860
+ */
2861
+ const pickKind = (picked: PickerKind) => {
2862
+ const preset: RollupPreset | null =
2863
+ picked === "count" || picked === "lookup" ? picked : null;
2864
+ setRollupPreset(preset);
2865
+ if (!preset) {
2866
+ setKind(picked as CreateKind);
2867
+ return;
2868
+ }
2869
+ setKind("rollup");
2870
+ setRollupMode("link");
2871
+ setRollupFn(ROLLUP_PRESET_FNS[preset]);
2872
+ if (preset === "count") setRollupField("");
2873
+ setRollupLimit(0);
2874
+ setRollupSortBy("");
2875
+ setRollupDistinctBy("");
2876
+ setRollupWhere([]);
2877
+ setRollupConditions([]);
2878
+ };
2879
  const [swapTo, setSwapTo] = useState("");
2880
  /** The "New field" half of Change-field keeps its own name/options β€” a half-typed insert
2881
  * form must not leak into a swap and vice versa. */
 
2976
  });
2977
  const [editLinkTable, setEditLinkTable] = useState(() => field.link?.table ?? "");
2978
  const [editLinkSingle, setEditLinkSingle] = useState(() => field.link?.single === true);
2979
+ // β›”β›” W42-T08 β€” SEEDED FROM THE STORED BAG, and this is not a nicety. The relational save
2980
+ // below is a REBUILD: it re-emits the whole `link` bag, so a hop the pane never read would be
2981
+ // DELETED by the one click meant to rename the column. Round-tripping it is what makes the
2982
+ // rebuild safe.
2983
+ const [editHopDraft, setEditHopDraft] = useState<HopDraft>(() => hopDraftFrom(field.link));
2984
+ const patchEditHopDraft = (patch: Partial<HopDraft>) =>
2985
+ setEditHopDraft((prev) => ({ ...prev, ...patch }));
2986
 
2987
  const swapToNewType = swapTo.startsWith(NEW_PREFIX)
2988
  ? (swapTo.slice(NEW_PREFIX.length) as FieldType)
 
2992
  const options = createChoice.options;
2993
  const swapChoice = swapToNewType
2994
  ? optionSettings(swapOptionDrafts, swapToNewType)
2995
+ : { options: [] as string[], colors: {} as Record<string, string>,
2996
+ capMessage: null as string | null };
2997
  const swapNewOptions = swapChoice.options;
2998
  /** Owner item 8 β€” the Edit pane's parsed choices for the drafted type. */
2999
  const editChoice = optionSettings(editOptionDrafts, editType);
 
3043
  * permanently unable to run.
3044
  */
3045
  const addressFields = useMemo(
3046
+ // C11 β€” an offer, and the picker behind it.
3047
+ () => offerableFields(fields).filter(
3048
+ (f) => (GEOCODE_ADDRESS_TYPES as readonly string[]).includes(f.type)
3049
+ ),
3050
  [fields]
3051
  );
3052
  const offerGeocode = geocodable && addressFields.length > 0;
 
3064
  const canCreate =
3065
  effectiveLabel.trim() !== "" &&
3066
  (!needsOptions(kind) || options.length > 0) &&
3067
+ // ⭐⭐ W42-T37 (C8b) β€” THE CAP REFUSES, IT DOES NOT TRUNCATE. The pane beside this button is
3068
+ // already saying how many choices are over the line and how many to remove; Create stays shut
3069
+ // until they are, so nothing is dropped on the way to the store.
3070
+ createChoice.capMessage === null &&
3071
  (kind !== "measure" || !!chosenMeasure) &&
3072
  // ⭐⭐ W37-T22 (R4 / C7) β€” a geocode column with no address column to read is a column no run
3073
  // can ever fill: the identical argument the `automation` URL-column rule below makes, and the
 
3088
  // `ai_enrich` column with no prompt, so creating one without this gate produces a column that
3089
  // is named, configured and simply absent on the next read.
3090
  (kind !== "ai_enrich" || aiEnrich.prompt.trim() !== "") &&
3091
+ // β›”β›” W42-T08 (C1) β€” A HALF-DECLARED HOP IS REFUSED HERE, not shipped. `_clean_link` refuses
3092
+ // the WHOLE field on a bad `via`, so a bag naming a topic with no `target_key` would produce
3093
+ // a column that is named, configured and simply absent on the next read. A BLANK hop is not
3094
+ // half-declared and passes untouched, which is the unchanged one-hop path.
3095
+ (kind !== "link" || (linkTable !== "" && !hopIncomplete(hopDraft, hopScopeKey))) &&
3096
  (kind !== "rollup" || (rollupMode === "source"
3097
  // ⭐ 2026-08-09 β€” the read-through bag. ALL FOUR keys are required by `_clean_rollup`
3098
  // (`if not (topic and measure and group_by and on): return None`), and `on` is the one a
 
3111
  t: CreateKind,
3112
  src: string,
3113
  starCount: number,
3114
+ lang: string,
3115
+ /**
3116
+ * β›”β›” W42-T08 β€” THE HOP IS PASSED IN, NOT READ FROM STATE, AND THAT IS THE WHOLE POINT.
3117
+ *
3118
+ * `hopDraft` is component-level state and this builder serves TWO forms: the create pane and
3119
+ * the "change this column" swap form. The swap form is mounted with `hop={null}` so a hop
3120
+ * cannot be AUTHORED there, but reading the draft off state anyway would let a hop configured
3121
+ * in the create pane and abandoned ride out on a link field created by the swap form: a join
3122
+ * the user never asked for, on a column they were only retyping. `null` here says which form
3123
+ * is asking.
3124
+ */
3125
+ hopSource: HopDraft | null
3126
  ): FieldConfigExtra | undefined => {
3127
  if (t === "formula") return { formula: src.trim() };
3128
  if (t === "rating") return { max: starCount };
 
3164
  // picks records). The DERIVED mode is the automation's, spawned with its join declared β€”
3165
  // offering "join on a column of the other table" here would be a second, harder mental
3166
  // model for the same button.
3167
+ // ⭐⭐ W42-T08 (R1, C1) β€” `via` TRAVELS ONLY WHEN IT IS COMPLETE, and its ABSENCE is the
3168
+ // one-hop bag this menu has always emitted. `hopVia` answers null for a blank draft and for a
3169
+ // half-filled one alike; `canCreate` above is what stops the second from reaching here.
3170
+ if (t === "link") {
3171
+ const via = hopVia(hopSource, hopScopeKey);
3172
+ return {
3173
+ link: {
3174
+ table: linkTable,
3175
+ ...(linkSingle ? { single: true } : {}),
3176
+ ...(via ? { via } : {}),
3177
+ },
3178
+ };
3179
+ }
3180
  if (t === "rollup" && rollupMode === "source")
3181
  // β›” THE SOURCE BAG TRAVELS ALONE. `_clean_rollup` reads `source` first and returns
3182
  // immediately, so sending `link`/`fn` alongside it would ship keys the store drops β€”
 
3271
  onCreate(clean, kind, position === "end" ? null : field.key, position,
3272
  needsOptions(kind) ? options : undefined, undefined,
3273
  withScope({
3274
+ ...extraFor(kind, formulaText, maxValue, codeLanguage, hopDraft),
3275
  ...optionExtraFor(kind, createChoice.colors, createColorCode),
3276
  }));
3277
  onClose();
 
3281
  swapToNewType != null &&
3282
  swapLabel.trim() !== "" &&
3283
  (!needsOptions(swapToNewType) || swapNewOptions.length > 0) &&
3284
+ // ⭐⭐ W42-T37 (C8b) β€” the option cap refuses at this door too. Unlike the completeness gates
3285
+ // the comment below books as missing, this one costs nothing to state here: the swap form
3286
+ // mounts the same options editor and therefore shows the same sentence.
3287
+ swapChoice.capMessage === null &&
3288
  (swapToNewType !== "formula" || swapFormulaCheck.ok) &&
3289
  // ⭐⭐ Wave-34 (R13) β€” the SAME completeness gate `canCreate` carries, on this door too.
3290
  //
 
3307
  swapToNewType,
3308
  needsOptions(swapToNewType) ? swapNewOptions : undefined,
3309
  withScope({
3310
+ // β›” `null`: the swap form offers no hop question, so it emits no hop. See `hopSource`.
3311
+ ...extraFor(swapToNewType, swapFormulaText, swapMaxValue, swapCodeLanguage, null),
3312
  ...optionExtraFor(swapToNewType, swapChoice.colors, swapColorCode),
3313
  })
3314
  );
 
3419
  (field.type === "rollup"
3420
  ? JSON.stringify(editRollup) !== JSON.stringify(field.rollup ?? {})
3421
  : editLinkTable !== (field.link?.table ?? "") ||
3422
+ editLinkSingle !== (field.link?.single === true) ||
3423
+ // ⚠ COMPARED AS THE BAG, NOT AS THE DRAFT. `hopDraftFrom` normalises an absent `via` and
3424
+ // an absent `window` to the same seeded draft the empty one produces, so comparing the
3425
+ // drafts by `JSON.stringify` would report a hop change on a pane nobody touched, which is
3426
+ // exactly the false-dirty class the description-only guard above exists to prevent.
3427
+ JSON.stringify(hopVia(editHopDraft, hopScopeKey)) !==
3428
+ JSON.stringify(hopVia(hopDraftFrom(field.link), hopScopeKey)));
3429
  const canSaveEdit =
3430
  /**
3431
  * ⭐ W41-T31 β€” THE DESCRIPTION-ONLY PANE'S WHOLE SAVE CONDITION, and it is one dirty flag
 
3449
  // is refused by the server, so Save is refused here instead: a 400 arriving after the click
3450
  // is the same "named, configured, gone" surprise one layer later.
3451
  (editType !== "ai_enrich" || aiEnrich.prompt.trim() !== "") &&
3452
+ // ⭐⭐ W42-T37 (C8b) β€” and the third door. An EDIT is where a long list actually arrives: a
3453
+ // column already holding choices is where somebody pastes another two hundred in.
3454
+ editChoice.capMessage === null &&
3455
  (editingRelational
3456
  ? (editRollupValid && (editRelationalTouched || editNameDirty || editNoteDirty) &&
3457
+ // β›” W42-T08 β€” the same half-declared-hop refusal `canCreate` makes, at the second
3458
+ // door. `_clean_link` refuses the WHOLE field on a bad `via`, so saving one here would
3459
+ // not edit the column, it would remove it.
3460
+ (field.type !== "link" ||
3461
+ (editLinkTable !== "" && !hopIncomplete(editHopDraft, hopScopeKey))))
3462
  : (editNameDirty || editRetypeTouched || editFormulaTouched ||
3463
  (canPeriod && periodChanged) || editNoteDirty)));
3464
  /**
 
3504
  ...(editNameDirty ? { label: cleanRename } : {}),
3505
  ...(field.type === "rollup"
3506
  ? { rollup: editRollup as Record<string, unknown> }
3507
+ // β›” W42-T08 β€” AND THE HOP RIDES THE REBUILD. This branch re-emits the whole bag, so
3508
+ // omitting `via` would not mean "unchanged", it would DELETE a saved hop. `hopVia`
3509
+ // answers null only for a blank or half-filled draft, and the Save door above already
3510
+ // refuses the second.
3511
  : { link: { table: editLinkTable,
3512
+ ...(editLinkSingle ? { single: true } : {}),
3513
+ ...(hopVia(editHopDraft, hopScopeKey)
3514
+ ? { via: hopVia(editHopDraft, hopScopeKey)! }
3515
+ : {}) } }),
3516
  });
3517
  if (editNoteDirty) onNote(note);
3518
  onClose();
 
3595
  * would contain; `swapOffered` is whether the picker exists at all, and it is read twice (the
3596
  * control itself, and the focus fallback that has to know whether the control is there).
3597
  */
3598
+ // C11 (W42-T54) β€” "Change this column to…" is a picker, so `presetSwap` and `yourSwap`
3599
+ // below are both narrowed by narrowing their source ONCE. ⚠ `swapOffered` reads this list's
3600
+ // LENGTH, so a table whose only other columns were withheld correctly offers no swap at all.
3601
+ const swapOptions = offerableFields(fields).filter((f) => f.key !== field.key);
3602
  const presetSwap = swapOptions.filter((f) => f.source === "odoo" && !f.custom);
3603
  const yourSwap = swapOptions.filter((f) => !(f.source === "odoo" && !f.custom));
3604
  const swapOffered = offer.swap && swapOptions.length > 0;
 
3767
  rows, Airtable-style. The measure row appears exactly when the host offers
3768
  measures β€” the same availability rule as the filter's measure conditions. */}
3769
  <TypePicker
3770
+ value={rollupPreset ?? kind}
3771
+ onPick={pickKind}
3772
  offerMeasure={measures.length > 0}
3773
  offerGeocode={offerGeocode}
3774
+ offerPresets
3775
+ isUserTable={isUserTable}
3776
  />
3777
  </div>
3778
  {kind === "measure" && (
 
3875
  onLinkTable={setLinkTable}
3876
  linkSingle={linkSingle}
3877
  onLinkSingle={setLinkSingle}
3878
+ hop={{
3879
+ topics: hopTopics,
3880
+ // The hop travels through a governed topic, so its window vocabulary is the one the
3881
+ // read-through rollup already offers for the same topics. `all` when none is
3882
+ // offered, which is what C1's default spells.
3883
+ windows: rollupSourceOffer.windows,
3884
+ scopeKey: hopScopeKey,
3885
+ draft: hopDraft,
3886
+ onDraft: patchHopDraft,
3887
+ }}
3888
+ rollupPreset={rollupPreset}
3889
  rollupMode={rollupMode}
3890
  onRollupMode={setRollupMode}
3891
  rollupSourceOffer={rollupSourceOffer}
 
4195
  onLinkTable={setEditLinkTable}
4196
  linkSingle={editLinkSingle}
4197
  onLinkSingle={setEditLinkSingle}
4198
+ hop={{
4199
+ topics: hopTopics,
4200
+ windows: rollupSourceOffer.windows,
4201
+ scopeKey: hopScopeKey,
4202
+ draft: editHopDraft,
4203
+ onDraft: patchEditHopDraft,
4204
+ }}
4205
  rollupSourceOffer={rollupSourceOffer}
4206
+ // ⭐⭐ W42-T37 β€” THE RE-OPEN. Read from the STORED bag, so a Count comes back as a
4207
+ // Count and a rollup that merely happens to fold by "Count of records" over a
4208
+ // window does not.
4209
+ rollupPreset={rollupPresetOf(editRollup)}
4210
  rollupMode={editRollup.source ? "source" : "link"}
4211
  // β›” A MODE SWITCH REPLACES THE BAG, it does not merge into it. `_clean_rollup`
4212
  // reads `source` first and returns before it ever looks at `link`, so a bag
 
4275
  codeLanguage={editCodeLanguage}
4276
  onCodeLanguage={setEditCodeLanguage}
4277
  idPrefix="cg-edit"
4278
+ // This arm is `field.type === "automation"`, which can never be a link.
4279
+ hop={null}
4280
  automationKind={editAutomationKind}
4281
  onAutomationKind={setEditAutomationKind}
4282
  automationUrlField={editAutomationUrlField}
 
4293
  value={editType}
4294
  onPick={(k) => setEditType(k as FieldType)}
4295
  offerMeasure={false}
4296
+ offerPresets={
4297
+ /* β›” FALSE FOR `offerGeocode`'s REASON, one line down. A preset AUTHORS a
4298
+ rollup bag, and this pane retypes an existing column rather than authoring
4299
+ one; a Count row here would set a kind whose configuration nothing on this
4300
+ door writes. */
4301
+ false
4302
+ }
4303
+ isUserTable={isUserTable}
4304
  offerGeocode={
4305
  /* β›” FALSE ON PURPOSE, and stated rather than omitted: this is the RETYPE
4306
  picker, and a geocode column is not a type an existing column can BECOME.
 
4443
  codeLanguage={editCodeLanguage}
4444
  onCodeLanguage={setEditCodeLanguage}
4445
  idPrefix="cg-edit"
4446
+ // This arm is `field.type === "formula"`, which can never be a link.
4447
+ hop={null}
4448
  showFormulaHelp={false}
4449
  />
4450
  )}
 
4561
  codeLanguage={swapCodeLanguage}
4562
  onCodeLanguage={setSwapCodeLanguage}
4563
  idPrefix="cg-swap"
4564
+ // β›” NULL, AND IT IS A STATEMENT. The swap form passes no `linkTargets`,
4565
+ // `onLinkTable` or `onLinkSingle` either, so a link built here already
4566
+ // configures nothing; painting a hop question on top of that would be a
4567
+ // second control that saves nothing rather than a feature.
4568
+ hop={null}
4569
  />
4570
  {needsOptions(swapToNewType) && (
4571
  <OptionsEditor
 
5042
  <div className="cg-menu-sep" role="separator" aria-hidden />
5043
 
5044
  {/* Group 3 β€” sort. Direction wording stays the shipped per-type directionLabel. */}
5045
+ {/* β›”β›” WAVE-42 R22 β€” THE ROUTE PROJECTION COLUMN IS NOT SORTED FROM HERE. Its cell is
5046
+ `Route A - 3, Route B - 7`, so an ordinary sort compares TEXT and puts
5047
+ `Route A - 10` before `Route A - 2`. A stop position only orders records inside ONE
5048
+ route, and this menu is not told what the view is filtered to, so it cannot know
5049
+ whether it is. It says so instead of guessing in the permissive direction; the Sort
5050
+ panel, which does hold the filter, is where the narrowed case is allowed. */}
5051
+ {field.key === ROUTE_PROJECTION_KEY ? (
5052
+ <div className="cg-field-hint">{ROUTE_SORT_REFUSAL_TEXT}</div>
5053
+ ) : (
5054
+ <>
5055
+ <button type="button" onClick={() => { onSort("asc"); onClose(); }}>
5056
+ <MenuLabel
5057
+ icon="sortAsc"
5058
+ text={`Sort ${directionLabel(field.type, "asc")}`}
5059
+ />
5060
+ </button>
5061
+ <button type="button" onClick={() => { onSort("desc"); onClose(); }}>
5062
+ <MenuLabel
5063
+ icon="sortDesc"
5064
+ text={`Sort ${directionLabel(field.type, "desc")}`}
5065
+ />
5066
+ </button>
5067
+ </>
5068
+ )}
5069
  {sortedDir != null && (
5070
  <button type="button" onClick={() => { onClearSort(); onClose(); }}>
5071
  <MenuLabel icon="off" text="Don't sort by this field" />
web/src/customer-grid/CustomerGrid.tsx CHANGED
@@ -82,7 +82,7 @@ import JsonViewer from "./JsonViewer";
82
  import RecordDetail from "./RecordDetail";
83
  import ViewSidebar from "./ViewSidebar";
84
  import ColumnMenu from "./ColumnMenu";
85
- import type { ColumnMenuState } from "./ColumnMenu";
86
  import { HEADER_ICONS } from "./iconShapes";
87
  import { emitHostEvent, eventId } from "./hostBridge";
88
  // ⭐ WAVE 27 item 21 (R14) β€” which of this table's views carry an alert. The SERVER's
@@ -93,9 +93,10 @@ import { API_V1, CREDENTIALS, NAV_MINIMIZE_EVENT, ROWS_STALE_EVENT, TOAST_EVENT,
93
  from "../apiContract";
94
  import type { ViewOpenDetail } from "../apiContract";
95
  import { addTableField, addTableRow, clearTopicRowsCache, deleteRouteOrderField, deleteTableField,
 
96
  deleteTableRow, fetchLinkTargets,
97
  fetchRollupSources, patchRouteOrderField, patchTableField, enrichField } from "./apiBridge";
98
- import type { LinkTarget, RollupSourceOffer } from "./apiBridge";
99
  import SelectFromFile from "./SelectFromFile";
100
  import ImportDialog from "./ImportDialog";
101
  import { FormInterface } from "./FormInterface";
@@ -123,7 +124,7 @@ import type { GridFolder, ViewPermissions } from "./types";
123
  import type { FieldStamps } from "./optimism";
124
  import { evalFormula, orderFormulas, parseFormula } from "./formulaEngine";
125
  import type { FormulaAst } from "./formulaEngine";
126
- import { CalendarView, KanbanView, ListView, MapSettings, ModeSwitch } from "./viewModes";
127
  import { SwipeView } from "./SwipeView";
128
  import type { SwipeSpec } from "./SwipeView";
129
  // The chart engine lives in `viz/` since EXIT wave 2 (W2-5/Y3) β€” the grid is now
@@ -177,7 +178,7 @@ import { ALL_VIEW_ID, MAX_CALENDAR_METRICS, allViewName,
177
  and only consumed here, because W41-T43 (this file) and W41-T44 (`RecordDetail.tsx`) open the
178
  same feature through other doors and neither of them may edit `types.ts`. */
179
  import { buildPivotRequest, cleanSecondaryView, emptyViewConfig, PIVOT_PATH, PIVOT_WINDOW_LABELS,
180
- pivotResponse, relationalTargets } from "./types";
181
  import type {
182
  DisplayMode,
183
  DisplaySpec,
@@ -187,6 +188,7 @@ import type {
187
  FieldType,
188
  FilterNode,
189
  FilterRule,
 
190
  PivotResponse,
191
  PivotWindow,
192
  Row,
@@ -442,10 +444,21 @@ function sameConfig(a: ViewConfig, b: ViewConfig): boolean {
442
  * and it renders a sentence rather than a grid. Collapsing it into `ok` with zero rows would
443
  * put "no related records" on screen as the answer to a question nobody has asked yet.
444
  */
 
 
 
 
 
 
 
 
 
 
445
  type PivotState =
446
  | { status: "idle" }
447
  | { status: "loading" }
448
  | { status: "absent" }
 
449
  | { status: "ok"; answer: PivotResponse };
450
 
451
  /**
@@ -623,6 +636,297 @@ function withColorField(config: ViewConfig, key: string): ViewConfig {
623
  return { ...config, colorBy: key || null, display: cleanDisplay(display) };
624
  }
625
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
626
  function readLocal(storageKey: string): LocalWorkspace | null {
627
  try {
628
  const raw = localStorage.getItem(`aios-grid:${storageKey}`);
@@ -928,6 +1232,47 @@ interface CustomerGridProps {
928
  embeddedSelectable?: boolean;
929
  embeddedSelectedIds?: readonly number[];
930
  onEmbeddedSelectionChange?: (recordIds: number[]) => void;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
931
  }
932
 
933
  interface LinkGridModalProps {
@@ -936,12 +1281,14 @@ interface LinkGridModalProps {
936
  recordIds: readonly number[];
937
  editable?: boolean;
938
  single?: boolean;
 
 
939
  onSave?: (recordIds: number[]) => void;
940
  onClose: () => void;
941
  }
942
 
943
  function LinkGridModal({ label, table, recordIds, editable = false, single = false,
944
- onSave, onClose }: LinkGridModalProps) {
945
  const panelRef = useRef<HTMLDivElement>(null);
946
  const [selectedIds, setSelectedIds] = useState<number[]>(() => [...recordIds]);
947
  const changeSelectedIds = useCallback((ids: number[]) => {
@@ -989,10 +1336,18 @@ function LinkGridModal({ label, table, recordIds, editable = false, single = fal
989
  </button>
990
  </header>
991
  <div className="cg-link-grid-body">
 
 
 
 
 
 
 
992
  <CustomerGrid
993
  scope={table}
994
  embedded
995
  embeddedRecordIds={editable ? undefined : recordIds}
 
996
  embeddedSelectable={editable}
997
  embeddedSelectedIds={selectedIds}
998
  onEmbeddedSelectionChange={changeSelectedIds}
@@ -1069,6 +1424,7 @@ function CustomerGridSurface({
1069
  embeddedSelectable = false,
1070
  embeddedSelectedIds = [],
1071
  onEmbeddedSelectionChange,
 
1072
  }: CustomerGridProps = {}) {
1073
  const isQueryPreview = queryBinding !== undefined;
1074
  /**
@@ -1135,16 +1491,20 @@ function CustomerGridSurface({
1135
  */
1136
  const [pendingRows, setPendingRows] = useState<Row[]>([]);
1137
  const rawRows = useMemo(() => {
1138
- const base = embeddedRecordIds
1139
  ? fetchedRows.filter((row) => new Set(embeddedRecordIds).has(row.pid))
1140
  : fetchedRows;
 
 
 
 
1141
  if (!pendingRows.length) return base;
1142
  const known = new Set(base.map((r) => r.pid));
1143
  const extra = pendingRows.filter((r) => !known.has(r.pid));
1144
  return extra.length ? [...base, ...extra] : base;
1145
  // The scalar key keeps this stable when a caller reconstructs the same id list.
1146
  // eslint-disable-next-line react-hooks/exhaustive-deps
1147
- }, [fetchedRows, embeddedIdsKey, pendingRows]);
1148
  useEffect(() => {
1149
  // ⚠ PRUNED AGAINST THE FETCHED PAYLOAD, not against `rawRows` β€” `rawRows` contains the
1150
  // pending rows, so it can never report that one has been absorbed. Pruning against the
@@ -1896,6 +2256,32 @@ function CustomerGridSurface({
1896
  const isUserTable = !embedded && scope.startsWith("ut_");
1897
  const recordsMutable = payload?.recordsMutable !== false;
1898
  const canMutateRecords = isUserTable && recordsMutable;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1899
  /**
1900
  * ⭐ 2026-08-07 β€” the databases a `link` column may point at, fetched when the column menu
1901
  * OPENS rather than on every render of the grid.
@@ -1969,6 +2355,61 @@ function CustomerGridSurface({
1969
  * carrying these same cells, or the row it paints locally fails the filter it was added under
1970
  * and disappears on the next read β€” the exact blip C2 exists to prevent.
1971
  */
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1972
  const seedValues = useCallback(
1973
  () => filterSeedValues(config.filters, config.filterConj, fields, payload?.viewer),
1974
  [config.filters, config.filterConj, fields, payload?.viewer]
@@ -2566,10 +3007,20 @@ function CustomerGridSurface({
2566
  * grouped: subtotals appeared, the table's own total vanished, and nothing said why.
2567
  *
2568
  * β›” WHY A SECOND PREDICATE RATHER THAN A WIDER `showTotals`. `showTotals` still answers a
2569
- * NARROWER question that two other call sites need unchanged: `freezeTrailingRows` pins
2570
- * exactly one trailing row, and glide's frozen trailing rows sit below the scroll region β€”
2571
- * pinning the grand total there while group footers scroll past it is the ungrouped layout,
2572
- * not the grouped one. This one answers "is a grand-total row appended at all".
 
 
 
 
 
 
 
 
 
 
2573
  *
2574
  * β›” THE WINDOWED ARM IS `showTotals` VERBATIM, AND THAT IS THE WHOLE SAFETY ARGUMENT. Over a
2575
  * `server-windowed` table the fold covers the LOADED WINDOW, and `foldNote` β€” the sentence that
@@ -2815,7 +3266,9 @@ function CustomerGridSurface({
2815
  const displayRows = useMemo(() => {
2816
  const shown = capped ? sliceForDisplay(visibleRows, displayCap) : visibleRows;
2817
  // ⚠ APPENDED AFTER THE SLICE, so the cap can never eat the totals row itself β€” and it is the
2818
- // LAST row, which is what `freezeTrailingRows={1}` pins.
 
 
2819
  // W41-T40 β€” `totalsRowShown`, not `showTotals`: a grouped table gets its grand total back,
2820
  // after the last group's footer. Still appended AFTER the slice, so the cap can never eat it.
2821
  return totalsRowShown
@@ -4107,7 +4560,12 @@ function CustomerGridSurface({
4107
  // The large modal mounts the same Grid surface over exactly these pids, so its standard
4108
  // search, Filters, Sort, Fields, and column menus keep working for every database kind.
4109
  if (row.kind === "data" && field?.type === "link" && field.link?.table) {
4110
- if (field.link.table.startsWith("ut_")) {
 
 
 
 
 
4111
  event.preventDefault();
4112
  setActiveCell(cell[0], cell[1]);
4113
  setLinkAt({ pid: row.record.pid, fieldKey: field.key });
@@ -5946,17 +6404,11 @@ function CustomerGridSurface({
5946
  const f = fieldByKey.get(key);
5947
  if (!f?.custom || key === lockedKey) return;
5948
  setFields((current) => current.filter((item) => item.key !== key));
5949
- const nextWidths = { ...(config.widths ?? {}) };
5950
- delete nextWidths[key];
5951
- updateConfig({
5952
- ...config,
5953
- order: order.filter((k) => k !== key),
5954
- visible: [...visible].filter((k) => k !== key),
5955
- widths: nextWidths,
5956
- sorts: (config.sorts ?? []).filter((s) => s.colId !== key),
5957
- groupBy: config.groupBy === key ? null : config.groupBy,
5958
- colorBy: config.colorBy === key ? null : config.colorBy,
5959
- });
5960
  stampFieldDelete(key);
5961
  emitHostEvent({ id: eventId("fielddel"), type: "field_delete", key });
5962
  },
@@ -5999,17 +6451,11 @@ function CustomerGridSurface({
5999
  void deleteRouteOrderField(key).then((ok) => {
6000
  if (!ok) return; // the bridge has already said why
6001
  setFields((current) => current.filter((item) => item.key !== key));
6002
- const nextWidths = { ...(config.widths ?? {}) };
6003
- delete nextWidths[key];
6004
- updateConfig({
6005
- ...config,
6006
- order: order.filter((k) => k !== key),
6007
- visible: [...visible].filter((k) => k !== key),
6008
- widths: nextWidths,
6009
- sorts: (config.sorts ?? []).filter((s) => s.colId !== key),
6010
- groupBy: config.groupBy === key ? null : config.groupBy,
6011
- colorBy: config.colorBy === key ? null : config.colorBy,
6012
- });
6013
  // β›” AND THE ROWS CACHE, for the reason `revealRouteField` states above: the values went
6014
  // with the definition (`shared_overlay.drop_field` scrubs the cells), so a refetch served
6015
  // from the pre-delete window would repaint the numbers of a column that no longer exists.
@@ -6061,17 +6507,11 @@ function CustomerGridSurface({
6061
  void deleteTableField(scope, key).then((ok) => {
6062
  if (!ok) return; // the bridge has already said why
6063
  setFields((current) => current.filter((item) => item.key !== key));
6064
- const nextWidths = { ...(config.widths ?? {}) };
6065
- delete nextWidths[key];
6066
- updateConfig({
6067
- ...config,
6068
- order: order.filter((k) => k !== key),
6069
- visible: [...visible].filter((k) => k !== key),
6070
- widths: nextWidths,
6071
- sorts: (config.sorts ?? []).filter((s) => s.colId !== key),
6072
- groupBy: config.groupBy === key ? null : config.groupBy,
6073
- colorBy: config.colorBy === key ? null : config.colorBy,
6074
- });
6075
  signal(WORKSPACE_STALE_EVENT);
6076
  signal(ROWS_STALE_EVENT);
6077
  });
@@ -6970,7 +7410,15 @@ function CustomerGridSurface({
6970
  });
6971
  if (!live) return;
6972
  if (!res.ok) {
6973
- setPivot({ status: "absent" });
 
 
 
 
 
 
 
 
6974
  return;
6975
  }
6976
  const answer = pivotResponse(await res.json().catch(() => null));
@@ -7111,6 +7559,12 @@ function CustomerGridSurface({
7111
  ?? (linkField && linkRow ? linkRow[linkField.key] : "")
7112
  ?? ""
7113
  );
 
 
 
 
 
 
7114
  const linkedRecordIds = [...new Set(
7115
  linkValue.split(",").map((part) => Number(part.trim())).filter(
7116
  (pid) => Number.isInteger(pid) && pid > 0
@@ -7200,7 +7654,17 @@ function CustomerGridSurface({
7200
 
7201
  const pivotOn = !!secondary;
7202
  const pivotAnswer = pivot.status === "ok" ? pivot.answer : null;
7203
- const pivotRefusal = pivotAnswer?.refusal ?? null;
 
 
 
 
 
 
 
 
 
 
7204
  /**
7205
  * ⭐ W41-T43 β€” THE SAVED PIVOT NAMES A LINK COLUMN THIS READER WAS NOT SERVED. No request went
7206
  * out (`pivotRequestBody` is empty), so `pivot` stays `idle` and every other branch below is
@@ -7327,6 +7791,19 @@ function CustomerGridSurface({
7327
  relational={relationalState}
7328
  onRelational={setPivotVia}
7329
  onRelationalWindow={setPivotWindow}
 
 
 
 
 
 
 
 
 
 
 
 
 
7330
  />
7331
  ) : null;
7332
 
@@ -7781,6 +8258,18 @@ function CustomerGridSurface({
7781
  if (target && target.shared && target.kind === "route_order") deleteRouteField(key);
7782
  else deleteField(key);
7783
  }}
 
 
 
 
 
 
 
 
 
 
 
 
7784
  /* ⭐⭐ W38-T07 (owner instruction 12) β€” THE ONE COLOUR CONTROL. This was `colorOn` plus a
7785
  boolean toggle whose `true` arm guessed the column: `fields.find(type === "status")`,
7786
  so on a table with two status columns the person got the first one and had no way to
@@ -7864,6 +8353,23 @@ function CustomerGridSurface({
7864
  onToggleRoute={() => setRoutePanelOpen((open) => !open)}
7865
  />
7866
  )}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7867
  {/* Wave-10 item 9: the view's description used to render HERE, as a full-width band
7868
  between the toolbar and the grid β€” it cost every row a strip of vertical space and
7869
  read as an alert rather than as a label. It now sits under the view's name in the
@@ -7977,7 +8483,12 @@ function CustomerGridSurface({
7977
  {pivot.status === "absent" && (
7978
  /* β›”β›” NOTHING, PLUS ONE LINE. C10's endpoint is W41-T20 and it had not been built
7979
  when this shipped. An absent answer means "not built yet", never "false", and
7980
- never an empty grid. */
 
 
 
 
 
7981
  <div className="cg-rel-note" role="status">
7982
  The related view is not available yet, so there is nothing to show.
7983
  </div>
@@ -8071,12 +8582,20 @@ function CustomerGridSurface({
8071
  * ⭐⭐ WAVE-29 T33 (owner item 17) β€” the totals row is glide's OWN frozen trailing
8072
  * row, which is why it is aligned to every column width for free.
8073
  *
8074
- * β›” `showTotals ? 1 : 0`, never a bare `1`: with no totals row appended, freezing
8075
  * one trailing row would pin the LAST DATA RECORD to the bottom of the viewport β€”
8076
  * a record that then appears twice while scrolling, which reads as duplicated data
8077
  * rather than as a layout bug.
 
 
 
 
 
 
 
 
8078
  */
8079
- freezeTrailingRows={showTotals ? 1 : 0}
8080
  rowHeight={rowHeight}
8081
  headerHeight={36}
8082
  rowMarkers="both"
@@ -8820,6 +9339,26 @@ function CustomerGridSurface({
8820
  state={columnMenu}
8821
  field={menuField}
8822
  fields={fields}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8823
  /**
8824
  * ⭐ 2026-08-10 β€” SELF-LINKING, and somebody asked for it (owner, D-113).
8825
  *
@@ -9058,6 +9597,34 @@ function CustomerGridSurface({
9058
  }
9059
  : undefined
9060
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9061
  onDuplicate={
9062
  // Creatable strata only β€” a base Odoo field offers no Duplicate (contract).
9063
  menuField.custom && !menuField.shared ? () => duplicateField(menuField) : undefined
@@ -9143,6 +9710,18 @@ function CustomerGridSurface({
9143
  field={fieldByKey.get(lockedKey)!}
9144
  fields={fields}
9145
  locked
 
 
 
 
 
 
 
 
 
 
 
 
9146
  viewer={viewer}
9147
  sortedDir={null}
9148
  isFiltered={false}
@@ -9153,6 +9732,24 @@ function CustomerGridSurface({
9153
  onNote={() => undefined}
9154
  onHide={() => undefined}
9155
  onCreate={createField}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9156
  /* The SAME answer as the sibling instance above, stated rather than defaulted: this is
9157
  the "+" menu and it creates through the identical `createField`, so a different value
9158
  here would mean one door offers the kind and its twin does not. The note above the
@@ -9184,6 +9781,26 @@ function CustomerGridSurface({
9184
  // either way. See the sibling's note for why self-links are offered now.
9185
  linkTargets={linkTargets}
9186
  rollupSourceOffer={rollupSourceOffer}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9187
  />
9188
  )}
9189
 
@@ -9413,13 +10030,14 @@ function CustomerGridSurface({
9413
  onClose={closeJson}
9414
  />
9415
  )}
9416
- {linkField?.type === "link" && linkField.link?.table.startsWith("ut_") && linkAt && (
9417
  <LinkGridModal
9418
  label={linkField.label}
9419
- table={linkField.link.table as SurfaceScope}
9420
  recordIds={linkedRecordIds}
9421
  editable={canEditField(linkField) && !isDerivedLink(linkField)}
9422
- single={linkField.link.single === true}
 
9423
  onSave={(ids) => patchAndRecord(
9424
  linkAt.pid,
9425
  { [linkField.key]: ids.join(",") },
 
82
  import RecordDetail from "./RecordDetail";
83
  import ViewSidebar from "./ViewSidebar";
84
  import ColumnMenu from "./ColumnMenu";
85
+ import type { ColumnMenuState, HopTopic } from "./ColumnMenu";
86
  import { HEADER_ICONS } from "./iconShapes";
87
  import { emitHostEvent, eventId } from "./hostBridge";
88
  // ⭐ WAVE 27 item 21 (R14) β€” which of this table's views carry an alert. The SERVER's
 
93
  from "../apiContract";
94
  import type { ViewOpenDetail } from "../apiContract";
95
  import { addTableField, addTableRow, clearTopicRowsCache, deleteRouteOrderField, deleteTableField,
96
+ deleteTableFields,
97
  deleteTableRow, fetchLinkTargets,
98
  fetchRollupSources, patchRouteOrderField, patchTableField, enrichField } from "./apiBridge";
99
+ import type { FieldDeleteResult, LinkTarget, RollupSourceOffer } from "./apiBridge";
100
  import SelectFromFile from "./SelectFromFile";
101
  import ImportDialog from "./ImportDialog";
102
  import { FormInterface } from "./FormInterface";
 
124
  import type { FieldStamps } from "./optimism";
125
  import { evalFormula, orderFormulas, parseFormula } from "./formulaEngine";
126
  import type { FormulaAst } from "./formulaEngine";
127
+ import { CalendarSettings, CalendarView, KanbanView, ListView, MapSettings, ModeSwitch } from "./viewModes";
128
  import { SwipeView } from "./SwipeView";
129
  import type { SwipeSpec } from "./SwipeView";
130
  // The chart engine lives in `viz/` since EXIT wave 2 (W2-5/Y3) β€” the grid is now
 
178
  and only consumed here, because W41-T43 (this file) and W41-T44 (`RecordDetail.tsx`) open the
179
  same feature through other doors and neither of them may edit `types.ts`. */
180
  import { buildPivotRequest, cleanSecondaryView, emptyViewConfig, PIVOT_PATH, PIVOT_WINDOW_LABELS,
181
+ pivotRefusalFromBody, pivotResponse, relationalTargets } from "./types";
182
  import type {
183
  DisplayMode,
184
  DisplaySpec,
 
188
  FieldType,
189
  FilterNode,
190
  FilterRule,
191
+ PivotRefusal,
192
  PivotResponse,
193
  PivotWindow,
194
  Row,
 
444
  * and it renders a sentence rather than a grid. Collapsing it into `ok` with zero rows would
445
  * put "no related records" on screen as the answer to a question nobody has asked yet.
446
  */
447
+ /**
448
+ * ⭐⭐ W42-T09 β€” **`refused` IS THE FIFTH STATE, AND IT IS THE ONE THAT WAS MISSING.** A non-2xx
449
+ * answer used to land in `absent` beside "the endpoint is not there", so a server that had
450
+ * walled the reader out, refused the route, or found more related records than one answer can
451
+ * carry printed the words *not available yet* β€” half of why D-484 read as "nothing works". The
452
+ * server authored a reason every time; nothing read it.
453
+ *
454
+ * ⚠ It carries the SAME `PivotRefusal` a 200-with-a-refusal carries, so both arrive at one
455
+ * renderer and there is one sentence about walls on this surface rather than two.
456
+ */
457
  type PivotState =
458
  | { status: "idle" }
459
  | { status: "loading" }
460
  | { status: "absent" }
461
+ | { status: "refused"; refusal: PivotRefusal }
462
  | { status: "ok"; answer: PivotResponse };
463
 
464
  /**
 
636
  return { ...config, colorBy: key || null, display: cleanDisplay(display) };
637
  }
638
 
639
+ /**
640
+ * ⭐⭐ W42-T11 β€” THE ONE RECONCILER FOR COLUMNS THAT NO LONGER EXIST, AND IT TAKES A SET.
641
+ *
642
+ * Every delete on this surface has to scrub the same six members of the view config against the
643
+ * key it just removed: `order`, `visible`, `widths`, `sorts`, `groupBy` and `colorBy`. Three
644
+ * handlers below (`deleteField`, `deleteRouteField`, `deleteDefinitionField`) each spelled that
645
+ * scrub out by hand, and a bulk delete needed a fourth copy β€” except a bulk delete cannot be
646
+ * three copies run in a loop, because each rebuilds `config` from the SAME closed-over snapshot
647
+ * and only the last survives. So the scrub becomes a pure function over a SET of removed keys,
648
+ * and the plural act performs exactly ONE config write.
649
+ *
650
+ * β›” `groupBy` AND `colorBy` ARE SCALARS, AND NULL IS THE ONLY CORRECT ANSWER FOR THEM. The other
651
+ * four are collections you filter; these two each name ONE column, and when that column goes the
652
+ * view is grouped by nothing and coloured by nothing. Left dangling, `useVisibleRows::groupRows`
653
+ * reads `r[groupBy]` as `undefined` on every row and pours the whole table into a single
654
+ * "(empty)" bucket while the toolbar chip reads `Group: ?` β€” a config fault wearing the costume
655
+ * of a data fault. `""` is not the answer either: the rest of this file tests `!config.groupBy`
656
+ * and `config.colorBy` for truthiness, and an empty string only passes those by accident.
657
+ *
658
+ * β›” AND THE COLOUR IS TWO KEYS, NOT ONE. `withColorField` above is the ONE writer of a colour
659
+ * choice precisely because two renderers read it β€” `config.colorBy` washes the grid rows and
660
+ * `config.display.colorField` colours the map pins. A reconciler that nulled only the first
661
+ * would leave the map painting by a column nobody can see, which is the same half-written state
662
+ * that function exists to prevent. Both go, in this one call.
663
+ *
664
+ * ⚠ PURE, AND IT RETURNS THE ORIGINAL WHEN NOTHING WAS REMOVED. `viewEcho` compares whole config
665
+ * objects, so manufacturing a new identity for a no-op delete would bill an autosave for nothing.
666
+ */
667
+ export function configWithoutFields(
668
+ config: ViewConfig,
669
+ removed: readonly string[]
670
+ ): ViewConfig {
671
+ const gone = new Set(removed.filter((key) => typeof key === "string" && key !== ""));
672
+ if (gone.size === 0) return config;
673
+ const widths = { ...(config.widths ?? {}) };
674
+ for (const key of gone) delete widths[key];
675
+ const next: ViewConfig = {
676
+ ...config,
677
+ order: (config.order ?? []).filter((key) => !gone.has(key)),
678
+ visible: (config.visible ?? []).filter((key) => !gone.has(key)),
679
+ widths,
680
+ sorts: (config.sorts ?? []).filter((sort) => !gone.has(sort.colId)),
681
+ groupBy: config.groupBy && gone.has(config.groupBy) ? null : config.groupBy,
682
+ colorBy: config.colorBy && gone.has(config.colorBy) ? null : config.colorBy,
683
+ };
684
+ const spec = next.display;
685
+ if (spec?.colorField && gone.has(spec.colorField)) {
686
+ const display: DisplaySpec = { ...spec };
687
+ delete display.colorField;
688
+ next.display = cleanDisplay(display);
689
+ }
690
+ return next;
691
+ }
692
+
693
+ /**
694
+ * ⭐⭐ W42-T11 β€” WHICH DOOR DELETES THIS COLUMN, ASKED ONCE.
695
+ *
696
+ * The column menu's `onDelete` already dispatches three strata, spelled inline across sixty lines
697
+ * of prose. A bulk delete has to ask the SAME question of every key it was handed, and a second
698
+ * copy of that test is how the two surfaces stop agreeing about what is deletable. So the test
699
+ * moves here, pure and exported, and the menu's own branches keep their sentences.
700
+ *
701
+ * β›” `null` IS AN ANSWER AND IT MEANS "NO DOOR", not "try the nearest one". `deleteField`'s guard
702
+ * (`if (!f?.custom …) return;`) makes a wrong guess look exactly like a successful delete that
703
+ * paints nothing, which is the failure this ticket exists to close.
704
+ */
705
+ export type FieldDeleteDoor = "overlay" | "definition" | "route";
706
+
707
+ export function fieldDeleteDoor(
708
+ field: Field | undefined,
709
+ opts: { isUserTable: boolean; lockedKey: string }
710
+ ): FieldDeleteDoor | null {
711
+ if (!field || field.key === opts.lockedKey) return null;
712
+ if (field.custom && !field.shared) return "overlay";
713
+ if (
714
+ opts.isUserTable && !field.custom &&
715
+ (field.type === "link" || field.type === "rollup" || field.type === "formula")
716
+ ) return "definition";
717
+ if (field.shared && field.kind === "route_order") return "route";
718
+ return null;
719
+ }
720
+
721
+ /**
722
+ * The five doors `filter-kit/FieldsHidePanel.tsx` needs a HOST to supply, built in one place.
723
+ *
724
+ * β›”β›” THE PANEL DOES NOT LOOP, AND NEITHER DOES ANY HANDLER BELOW. `runBulk` collects the fields
725
+ * that passed contract C2's rights test into one `passed` array and fires ONE plural call per
726
+ * act, because every per-key host handler on this surface rewrites the view config from a
727
+ * closed-over snapshot: N of them in a tick all rebuild the SAME config and only the last write
728
+ * survives. What that forbids is looping the HANDLER, and since W42-T58 (contract C4) the REQUEST
729
+ * is not looped either: `deleteTableFields` posts every key to the plural door in one call and
730
+ * hands back a per key verdict, and this hook then performs exactly ONE `updateConfig`. The per
731
+ * key door it used to walk is still the only door a SINGLE column delete elsewhere in this file
732
+ * has, and that is a call, not a loop.
733
+ *
734
+ * β›” A KEY THE SERVER REFUSED IS NOT RECONCILED OUT. Scrubbing it from `order` and `visible`
735
+ * would take the column off the screen while it still exists in the store, so the refusal would
736
+ * read as a success until the next workspace fetch put the column back.
737
+ *
738
+ * β›”β›” SHARE, REASSIGN AND REMOVE REFUSE OUT LOUD RATHER THAN DOING NOTHING, and that is the
739
+ * whole point of wiring them at all (D-485: a control that silently no-ops is worse than one
740
+ * that is absent). The server doors for the first two exist and are per object
741
+ * (`PUT /share/field/{oid}` and `PUT /share/field/{oid}/owner`), but both need a PERSON picked,
742
+ * and the only opener this tree may reach is the `aios:share-open` event, which carries ONE oid.
743
+ * Firing it five times is exactly the five-dialog experience R3 asked to be replaced, so these
744
+ * say so in one sentence instead. `onRemoveField` has no door at all: dropping yourself from a
745
+ * colleague's grant list needs `may_administer`, which a plain grantee does not hold.
746
+ *
747
+ * ⚠ NOT CALLED FROM THIS COMPONENT YET, and that is a fence, not an oversight:
748
+ * `customer-grid/Toolbar.tsx` declares none of the five props and is the only thing standing
749
+ * between these doors and the panel. Wiring it is the next ticket's; see the handoff.
750
+ */
751
+ export interface FieldBulkDoorDeps {
752
+ config: ViewConfig;
753
+ updateConfig: (next: ViewConfig) => void;
754
+ /** The RECONCILED sequence and set, which is what every delete on this surface writes back. */
755
+ order: string[];
756
+ visible: Set<string>;
757
+ lockedKey: string;
758
+ fieldByKey: Map<string, Field>;
759
+ isUserTable: boolean;
760
+ scope: string;
761
+ rowsPath: string;
762
+ setFields: (update: (current: Field[]) => Field[]) => void;
763
+ stampFieldDelete: (key: string) => void;
764
+ }
765
+
766
+ export interface FieldBulkDoors {
767
+ onSetFieldsHidden: (keys: string[], hidden: boolean) => void;
768
+ onShareFields: (keys: string[]) => void;
769
+ onReassignFields: (keys: string[]) => void;
770
+ onDeleteFields: (keys: string[]) => void;
771
+ onRemoveField: (key: string) => void;
772
+ }
773
+
774
+ /**
775
+ * ⭐⭐ W42-T58 (contract C4) β€” THE SERVER'S OWN SENTENCE, ABOUT THE COLUMN IT IS ACTUALLY ABOUT.
776
+ *
777
+ * β›” D-485, WHICH THIS LANE ALREADY FOUGHT IN T12: widening a return type and leaving nothing
778
+ * reading it is a control that degrades to nothing. C4 answers the plural delete door with a
779
+ * status, a code and a reason PER KEY, and this is the thing that reads them. Before it, the
780
+ * refusal was raised from inside the per key request, one toast per key, several of them racing
781
+ * into one slot with nothing naming which column each sentence belonged to.
782
+ *
783
+ * ⚠ THE MACHINE CODE STAYS OFF THE SCREEN. It is carried on the type for a caller that wants to
784
+ * branch on it; pasted into a sentence it is not an explanation to the person reading it. And a
785
+ * refusal with no sentence at all still says so out loud, because a control that silently leaves
786
+ * a column alone is the failure this whole surface was rewired to end.
787
+ */
788
+ function reportFieldDeleteRefusals(
789
+ results: readonly FieldDeleteResult[],
790
+ fieldByKey: Map<string, Field>
791
+ ): void {
792
+ const refused = results.filter((r) => r.status === "refused");
793
+ if (refused.length === 0) return;
794
+ const explained = refused.find((r) => typeof r.reason === "string" && r.reason.trim().length > 0);
795
+ if (!explained) {
796
+ signal(TOAST_EVENT, refused.length === 1
797
+ ? "That column was left alone, and the server gave no reason."
798
+ : `${refused.length} of those columns were left alone, and the server gave no reason.`);
799
+ return;
800
+ }
801
+ const label = fieldByKey.get(explained.key)?.label ?? explained.key;
802
+ signal(TOAST_EVENT, refused.length === 1
803
+ ? `${label} was left alone. ${explained.reason}`
804
+ : `${refused.length} of those columns were left alone. ${label}: ${explained.reason}`);
805
+ }
806
+
807
+ export function useFieldBulkDoors(deps: FieldBulkDoorDeps): FieldBulkDoors {
808
+ const { config, updateConfig, order, visible, lockedKey, fieldByKey, isUserTable, scope,
809
+ rowsPath, setFields, stampFieldDelete } = deps;
810
+
811
+ /**
812
+ * β›” AN ABSOLUTE SET, NOT A DELTA, because that is what the primitive underneath takes:
813
+ * `onColumnsVisible` is called as `onColumnsVisible(fields.map(f => f.key))` for Show all and
814
+ * `onColumnsVisible([lockedKey])` for Hide all. Handing it the keys being hidden would hide
815
+ * everything else instead.
816
+ * ⚠ THE LOCKED COLUMN NEVER LEAVES. `useGridColumns::setColumnVisible` already refuses to hide
817
+ * it one key at a time; a plural door that forgot would hide the row identity of the grid.
818
+ */
819
+ const onSetFieldsHidden = useCallback(
820
+ (keys: string[], hidden: boolean) => {
821
+ const next = new Set(visible);
822
+ for (const key of keys) {
823
+ if (hidden) {
824
+ if (key !== lockedKey) next.delete(key);
825
+ } else {
826
+ next.add(key);
827
+ }
828
+ }
829
+ updateConfig({ ...config, visible: [...new Set([lockedKey, ...next])] });
830
+ },
831
+ [config, lockedKey, updateConfig, visible]
832
+ );
833
+
834
+ const onDeleteFields = useCallback(
835
+ (keys: string[]) => {
836
+ const overlay: string[] = [];
837
+ const definition: string[] = [];
838
+ const route: string[] = [];
839
+ const noDoor: string[] = [];
840
+ for (const key of keys) {
841
+ const door = fieldDeleteDoor(fieldByKey.get(key), { isUserTable, lockedKey });
842
+ if (door === "overlay") overlay.push(key);
843
+ else if (door === "definition") definition.push(key);
844
+ else if (door === "route") route.push(key);
845
+ else noDoor.push(key);
846
+ }
847
+ void (async () => {
848
+ const gone = [...overlay];
849
+ let touchedServer = false;
850
+ let unreadableAnswer = false;
851
+ if (definition.length > 0) {
852
+ const outcome = await deleteTableFields(scope, definition);
853
+ gone.push(...outcome.deleted);
854
+ touchedServer = touchedServer || outcome.deleted.length > 0;
855
+ unreadableAnswer = unreadableAnswer || outcome.unreadable;
856
+ reportFieldDeleteRefusals(outcome.results, fieldByKey);
857
+ }
858
+ for (const key of route) {
859
+ // ⚠ SEQUENTIAL, AND THIS DOOR STATES ITS OWN REASON NOW (W42-T58 took the plural
860
+ // delete off the per key door, so there is no longer a shared note to point at):
861
+ // `deleteRouteOrderField` raises the server's refusal itself, one toast per key, and
862
+ // fired in parallel several of them race into one slot.
863
+ // eslint-disable-next-line no-await-in-loop
864
+ const ok = await deleteRouteOrderField(key);
865
+ if (ok) {
866
+ gone.push(key);
867
+ touchedServer = true;
868
+ }
869
+ }
870
+ if (noDoor.length > 0) {
871
+ signal(TOAST_EVENT,
872
+ noDoor.length === 1
873
+ ? "One of those columns cannot be deleted here, so it was left alone."
874
+ : `${noDoor.length} of those columns cannot be deleted here, so they were left alone.`);
875
+ }
876
+ if (gone.length > 0) {
877
+ const goneSet = new Set(gone);
878
+ setFields((current) => current.filter((item) => !goneSet.has(item.key)));
879
+ // β›” ONE CONFIG WRITE FOR THE WHOLE ACT. This is the line the panel's JSDoc protects,
880
+ // and it is written over the keys that ACTUALLY WENT, never over the keys asked for.
881
+ updateConfig(configWithoutFields({ ...config, order, visible: [...visible] }, gone));
882
+ for (const key of overlay) {
883
+ stampFieldDelete(key);
884
+ emitHostEvent({ id: eventId("fielddel"), type: "field_delete", key });
885
+ }
886
+ }
887
+ if (touchedServer || unreadableAnswer) {
888
+ // The values went with the definitions, so the rows are a beat stale as well as the
889
+ // schema β€” the same pair every singular definition delete signals.
890
+ // ⚠ THE SECOND TERM IS THE ANSWER NOBODY COULD READ (C4). The view is left exactly as
891
+ // it is, nothing above reconciled, and the truth is FETCHED rather than guessed at.
892
+ // Without it the person is told the table is being read again and nothing reads it.
893
+ clearTopicRowsCache(rowsPath);
894
+ signal(WORKSPACE_STALE_EVENT);
895
+ signal(ROWS_STALE_EVENT);
896
+ }
897
+ })();
898
+ },
899
+ [config, fieldByKey, isUserTable, lockedKey, order, rowsPath, scope, setFields,
900
+ stampFieldDelete, updateConfig, visible]
901
+ );
902
+
903
+ const onShareFields = useCallback((keys: string[]) => {
904
+ if (keys.length === 0) return;
905
+ signal(TOAST_EVENT,
906
+ "Sharing several fields in one go is not available yet, so share them one at a time from " +
907
+ "each column's own menu.");
908
+ }, []);
909
+
910
+ const onReassignFields = useCallback((keys: string[]) => {
911
+ if (keys.length === 0) return;
912
+ signal(TOAST_EVENT,
913
+ "Handing several fields to a new owner in one go is not available yet, so change the " +
914
+ "owner one column at a time from its share panel.");
915
+ }, []);
916
+
917
+ const onRemoveField = useCallback((key: string) => {
918
+ if (!key) return;
919
+ signal(TOAST_EVENT,
920
+ "Taking a shared field off your own list is not available yet, so hide it or ask the " +
921
+ "person who owns it to withdraw it.");
922
+ }, []);
923
+
924
+ return useMemo(
925
+ () => ({ onSetFieldsHidden, onShareFields, onReassignFields, onDeleteFields, onRemoveField }),
926
+ [onDeleteFields, onReassignFields, onRemoveField, onSetFieldsHidden, onShareFields]
927
+ );
928
+ }
929
+
930
  function readLocal(storageKey: string): LocalWorkspace | null {
931
  try {
932
  const raw = localStorage.getItem(`aios-grid:${storageKey}`);
 
1232
  embeddedSelectable?: boolean;
1233
  embeddedSelectedIds?: readonly number[];
1234
  onEmbeddedSelectionChange?: (recordIds: number[]) => void;
1235
+ /** W42-T29 β€” the SOURCE record, withheld from its own candidate list so a record cannot be
1236
+ * offered as a link to itself. Applied on top of any projection above. */
1237
+ embeddedExcludeRecordId?: number;
1238
+ }
1239
+
1240
+ /**
1241
+ * ⭐⭐ W42-T29 β€” WHICH TABLES A LINK COLUMN MAY POINT AT, mirroring the server's own predicate
1242
+ * `core.user_tables.is_linkable_target` rather than guessing a second time.
1243
+ *
1244
+ * β›” THE CLIENT HAD ONE HALF OF IT. Every door into the linked-record picker tested the `ut_`
1245
+ * prefix alone, so once the server learned to accept the two registry databases the client
1246
+ * refused to open the picker for them at all: no chips, no typing, no candidate list, and no
1247
+ * error either, because a click gate that falls through simply does nothing.
1248
+ *
1249
+ * β›” TWO NAMESPACES, ONE PREDICATE, and both halves are strict. A user database must reach
1250
+ * BEYOND the prefix, so the bare three characters are not a table and never were. The module
1251
+ * half is EXACT MEMBERSHIP, never a prefix test, which is what keeps it an allowlist rather
1252
+ * than a hole a lookalike key can walk through.
1253
+ */
1254
+ const LINKABLE_MODULE_KEYS = ["customer_data", "product_data"] as const;
1255
+
1256
+ export function isLinkableTarget(table: unknown): boolean {
1257
+ if (typeof table !== "string") return false;
1258
+ if (table.startsWith("ut_") && table.length > 3) return true;
1259
+ return (LINKABLE_MODULE_KEYS as readonly string[]).includes(table);
1260
+ }
1261
+
1262
+ /**
1263
+ * The SURFACE the picker mounts for an eligible link target.
1264
+ *
1265
+ * ⚠ A TARGET KEY IS NOT A SCOPE, and conflating them is how this half breaks silently: the
1266
+ * registry names the two module databases with the `_data` suffix, while the renderer's scopes
1267
+ * are the bare topic words. `topicForScope` falls back to the customer topic for anything it
1268
+ * does not recognise, so an unmapped key opens a fully populated picker over the WRONG table.
1269
+ * Unresolvable targets get `undefined`, which is the signal not to open anything.
1270
+ */
1271
+ export function scopeForLinkTable(table: unknown): SurfaceScope | undefined {
1272
+ if (!isLinkableTarget(table)) return undefined;
1273
+ if (table === "customer_data") return "customer";
1274
+ if (table === "product_data") return "product";
1275
+ return table as `ut_${string}`;
1276
  }
1277
 
1278
  interface LinkGridModalProps {
 
1281
  recordIds: readonly number[];
1282
  editable?: boolean;
1283
  single?: boolean;
1284
+ /** The source record, when this picker draws the source record's OWN database. */
1285
+ excludeRecordId?: number;
1286
  onSave?: (recordIds: number[]) => void;
1287
  onClose: () => void;
1288
  }
1289
 
1290
  function LinkGridModal({ label, table, recordIds, editable = false, single = false,
1291
+ excludeRecordId, onSave, onClose }: LinkGridModalProps) {
1292
  const panelRef = useRef<HTMLDivElement>(null);
1293
  const [selectedIds, setSelectedIds] = useState<number[]>(() => [...recordIds]);
1294
  const changeSelectedIds = useCallback((ids: number[]) => {
 
1336
  </button>
1337
  </header>
1338
  <div className="cg-link-grid-body">
1339
+ {/* β›” W42-T29 β€” the candidate list is every row of the target database, and when the
1340
+ target IS this record's own database that list contained the record itself, so a
1341
+ record could be linked to itself. The source is withheld only while the picker is
1342
+ EDITABLE: a read-only mount is showing links that already exist, and hiding one
1343
+ there would hide data rather than refuse an act. A self-link already stored
1344
+ survives either way, because the selection is carried by pid and is not rebuilt
1345
+ from the rows on screen. */}
1346
  <CustomerGrid
1347
  scope={table}
1348
  embedded
1349
  embeddedRecordIds={editable ? undefined : recordIds}
1350
+ embeddedExcludeRecordId={editable ? excludeRecordId : undefined}
1351
  embeddedSelectable={editable}
1352
  embeddedSelectedIds={selectedIds}
1353
  onEmbeddedSelectionChange={changeSelectedIds}
 
1424
  embeddedSelectable = false,
1425
  embeddedSelectedIds = [],
1426
  onEmbeddedSelectionChange,
1427
+ embeddedExcludeRecordId,
1428
  }: CustomerGridProps = {}) {
1429
  const isQueryPreview = queryBinding !== undefined;
1430
  /**
 
1491
  */
1492
  const [pendingRows, setPendingRows] = useState<Row[]>([]);
1493
  const rawRows = useMemo(() => {
1494
+ const projected = embeddedRecordIds
1495
  ? fetchedRows.filter((row) => new Set(embeddedRecordIds).has(row.pid))
1496
  : fetchedRows;
1497
+ // W42-T29 β€” the source record is not a candidate for its own link column.
1498
+ const base = embeddedExcludeRecordId
1499
+ ? projected.filter((row) => row.pid !== embeddedExcludeRecordId)
1500
+ : projected;
1501
  if (!pendingRows.length) return base;
1502
  const known = new Set(base.map((r) => r.pid));
1503
  const extra = pendingRows.filter((r) => !known.has(r.pid));
1504
  return extra.length ? [...base, ...extra] : base;
1505
  // The scalar key keeps this stable when a caller reconstructs the same id list.
1506
  // eslint-disable-next-line react-hooks/exhaustive-deps
1507
+ }, [fetchedRows, embeddedIdsKey, embeddedExcludeRecordId, pendingRows]);
1508
  useEffect(() => {
1509
  // ⚠ PRUNED AGAINST THE FETCHED PAYLOAD, not against `rawRows` β€” `rawRows` contains the
1510
  // pending rows, so it can never report that one has been absorbed. Pruning against the
 
2256
  const isUserTable = !embedded && scope.startsWith("ut_");
2257
  const recordsMutable = payload?.recordsMutable !== false;
2258
  const canMutateRecords = isUserTable && recordsMutable;
2259
+ /**
2260
+ * ⭐⭐ W42-T12 (D-485, amendment A20) β€” THE FIELD MANAGER'S FIVE DOORS, CALLED AT LAST.
2261
+ *
2262
+ * W42-T11 built and exported `useFieldBulkDoors` and stopped at the fence: the hook existed,
2263
+ * nothing called it, and every bulk act in the Fields manager was a silent no-op. This call is
2264
+ * the other half. Each door batches its whole selection into ONE config write, which is why
2265
+ * none of them may be assembled at the toolbar out of the per-key props beside them β€” N calls
2266
+ * to a per-key handler in one tick all rebuild from the same closed-over snapshot and only the
2267
+ * last survives (see `FieldBulkDoors`' own note upstream).
2268
+ *
2269
+ * ⚠ IT SITS HERE, ABOVE the pivot and the main mount, because a hook may not be called
2270
+ * conditionally and both `<Toolbar>` mounts render below.
2271
+ */
2272
+ const fieldBulkDoors = useFieldBulkDoors({
2273
+ config,
2274
+ updateConfig,
2275
+ order,
2276
+ visible,
2277
+ lockedKey,
2278
+ fieldByKey,
2279
+ isUserTable,
2280
+ scope,
2281
+ rowsPath: topic.rowsPath,
2282
+ setFields,
2283
+ stampFieldDelete,
2284
+ });
2285
  /**
2286
  * ⭐ 2026-08-07 β€” the databases a `link` column may point at, fetched when the column menu
2287
  * OPENS rather than on every render of the grid.
 
2355
  * carrying these same cells, or the row it paints locally fails the filter it was added under
2356
  * and disappears on the next read β€” the exact blip C2 exists to prevent.
2357
  */
2358
+ /**
2359
+ * ⭐⭐ W42-T09 (R1, contract C2) β€” THE HOP'S OPERAND LIST, FETCHED ONCE PER GRID.
2360
+ *
2361
+ * `GET /grid/hop-topics` hands back the governed topics a Link column's two-hop join may travel
2362
+ * THROUGH, each carrying its dimensions already shaped as `Field[]` (`source: "topic"`) so the
2363
+ * link editor can hand them straight to the condition builder as its `fields` prop. That is the
2364
+ * entire reason this endpoint exists beside `/tables/rollup-sources`, whose `dims` are the bare
2365
+ * `{key, label, keyedBy}` shape: deriving a `type` from `keyedBy` would produce a plausible
2366
+ * operand list with the WRONG OPERATORS, which is worse than no list at all.
2367
+ *
2368
+ * β›”β›” THE SERVER HALF IS NOT IN THIS WORKTREE, AND AN EMPTY LIST IS THE CORRECT ANSWER TO
2369
+ * THAT. A 404 here leaves `hopTopics` empty, the editor renders the Through question and says
2370
+ * it has nothing to offer, and no `via` can be authored β€” which is exactly today's one-hop
2371
+ * behaviour. Nothing is stubbed and nothing throws: a client that crashed on an unbuilt
2372
+ * endpoint would take the whole column menu down with it.
2373
+ *
2374
+ * ⚠ THE GUARD IS AN `asked` REF, NOT `topics.length`, and gates on BOTH DOORS. Both reasons are
2375
+ * the rollup offer's above, learned the hard way twice in this file: an empty offer is a common
2376
+ * and correct answer, so a length guard re-asks on every menu open for exactly the workspaces
2377
+ * where the answer can never change; and a fetch gated on `columnMenu` alone leaves the "+"
2378
+ * create menu with an empty list while its twin is full.
2379
+ */
2380
+ const [hopTopics, setHopTopics] = useState<HopTopic[]>([]);
2381
+ const hopTopicsAsked = useRef(false);
2382
+ useEffect(() => {
2383
+ if ((!columnMenu && !plusMenu) || hopTopicsAsked.current) return;
2384
+ hopTopicsAsked.current = true;
2385
+ let live = true;
2386
+ (async () => {
2387
+ try {
2388
+ const res = await fetch(`${API_V1}/grid/hop-topics`, { credentials: CREDENTIALS });
2389
+ if (!live || !res.ok) return;
2390
+ const body = (await res.json().catch(() => null)) as { topics?: unknown } | null;
2391
+ if (!live || !Array.isArray(body?.topics)) return;
2392
+ /* ⚠ SHAPE-CHECKED, NOT TRUSTED. `key` and `label` are what the editor renders and `dims`
2393
+ is what it filters by; a topic missing any of them would draw a nameless row that
2394
+ cannot be picked. `measures` is tolerated as absent because a hop may legitimately
2395
+ carry none, and the editor already defaults it. */
2396
+ const clean = (body!.topics as unknown[]).filter(
2397
+ (t): t is HopTopic =>
2398
+ !!t && typeof t === "object" &&
2399
+ typeof (t as HopTopic).key === "string" && !!(t as HopTopic).key &&
2400
+ typeof (t as HopTopic).label === "string" &&
2401
+ Array.isArray((t as HopTopic).dims)
2402
+ ).map((t) => ({ ...t, measures: Array.isArray(t.measures) ? t.measures : [] }));
2403
+ setHopTopics(clean);
2404
+ } catch {
2405
+ /* An unreachable endpoint and an unbuilt one are the same fact here, and the same
2406
+ truthful answer: this database offers no hop today. */
2407
+ }
2408
+ })();
2409
+ return () => {
2410
+ live = false;
2411
+ };
2412
+ }, [columnMenu, plusMenu]);
2413
  const seedValues = useCallback(
2414
  () => filterSeedValues(config.filters, config.filterConj, fields, payload?.viewer),
2415
  [config.filters, config.filterConj, fields, payload?.viewer]
 
3007
  * grouped: subtotals appeared, the table's own total vanished, and nothing said why.
3008
  *
3009
  * β›” WHY A SECOND PREDICATE RATHER THAN A WIDER `showTotals`. `showTotals` still answers a
3010
+ * NARROWER question that two other call sites need unchanged: the WINDOWED ARM of this very
3011
+ * memo, and `foldNote` β€” the disclosure sentence. Both are about a fabricated aggregate over a
3012
+ * partial window, which is a different question from "is a grand-total row appended at all",
3013
+ * which is what THIS one answers.
3014
+ *
3015
+ * ⭐⭐ W42-T17 (D-494, owner ruling R7) β€” AND THE FROZEN-ROW COUNT READS THIS ONE, NOT
3016
+ * `showTotals`. The earlier text here argued that pinning the grand total below the scroll
3017
+ * region while group footers scroll past it was "the ungrouped layout, not the grouped one",
3018
+ * and left the frozen-row count on `showTotals`. That split is the defect: `showTotals` carries
3019
+ * `!config.groupBy`, so under grouping the row was APPENDED by this memo and then not pinned β€”
3020
+ * it existed, it scrolled away with the rows, and it read as missing. R7 reverses the split.
3021
+ * The frozen-row count is now this same predicate, so FREEZE ≑ APPEND by construction: exactly
3022
+ * one trailing row is frozen whenever exactly one is appended, and zero when none is, which is
3023
+ * what stops the last DATA record being pinned on a grid with no totals row.
3024
  *
3025
  * β›” THE WINDOWED ARM IS `showTotals` VERBATIM, AND THAT IS THE WHOLE SAFETY ARGUMENT. Over a
3026
  * `server-windowed` table the fold covers the LOADED WINDOW, and `foldNote` β€” the sentence that
 
3266
  const displayRows = useMemo(() => {
3267
  const shown = capped ? sliceForDisplay(visibleRows, displayCap) : visibleRows;
3268
  // ⚠ APPENDED AFTER THE SLICE, so the cap can never eat the totals row itself β€” and it is the
3269
+ // LAST row, which is the one glide's frozen-trailing-row count pins.
3270
+ // W42-T17 (R7) β€” that count is passed as `totalsRowShown ? 1 : 0`, i.e. THIS predicate, so a
3271
+ // row appended here is always the row pinned there, and a grid with no totals row freezes 0.
3272
  // W41-T40 β€” `totalsRowShown`, not `showTotals`: a grouped table gets its grand total back,
3273
  // after the last group's footer. Still appended AFTER the slice, so the cap can never eat it.
3274
  return totalsRowShown
 
4560
  // The large modal mounts the same Grid surface over exactly these pids, so its standard
4561
  // search, Filters, Sort, Fields, and column menus keep working for every database kind.
4562
  if (row.kind === "data" && field?.type === "link" && field.link?.table) {
4563
+ // β›” W42-T29 β€” THE ELIGIBILITY QUESTION IS THE SERVER'S, ASKED THROUGH ONE PREDICATE.
4564
+ // The prefix test that stood here answered a narrower question than the store does, so
4565
+ // a link pointed at either registry database fell through this branch with no `else`
4566
+ // and the cell had no door at all: no picker on a click, and none on a keystroke either,
4567
+ // since the cell carries no overlay.
4568
+ if (isLinkableTarget(field.link.table)) {
4569
  event.preventDefault();
4570
  setActiveCell(cell[0], cell[1]);
4571
  setLinkAt({ pid: row.record.pid, fieldKey: field.key });
 
6404
  const f = fieldByKey.get(key);
6405
  if (!f?.custom || key === lockedKey) return;
6406
  setFields((current) => current.filter((item) => item.key !== key));
6407
+ // ⭐ W42-T11 β€” the six-member scrub is `configWithoutFields` now, one copy for all
6408
+ // four deletes on this surface, and it drops the map's `display.colorField` too.
6409
+ // The RECONCILED `order`/`visible` are handed in, exactly as this line always
6410
+ // wrote them back, so a delete still persists the healed column sequence.
6411
+ updateConfig(configWithoutFields({ ...config, order, visible: [...visible] }, [key]));
 
 
 
 
 
 
6412
  stampFieldDelete(key);
6413
  emitHostEvent({ id: eventId("fielddel"), type: "field_delete", key });
6414
  },
 
6451
  void deleteRouteOrderField(key).then((ok) => {
6452
  if (!ok) return; // the bridge has already said why
6453
  setFields((current) => current.filter((item) => item.key !== key));
6454
+ // ⭐ W42-T11 β€” the six-member scrub is `configWithoutFields` now, one copy for all
6455
+ // four deletes on this surface, and it drops the map's `display.colorField` too.
6456
+ // The RECONCILED `order`/`visible` are handed in, exactly as this line always
6457
+ // wrote them back, so a delete still persists the healed column sequence.
6458
+ updateConfig(configWithoutFields({ ...config, order, visible: [...visible] }, [key]));
 
 
 
 
 
 
6459
  // β›” AND THE ROWS CACHE, for the reason `revealRouteField` states above: the values went
6460
  // with the definition (`shared_overlay.drop_field` scrubs the cells), so a refetch served
6461
  // from the pre-delete window would repaint the numbers of a column that no longer exists.
 
6507
  void deleteTableField(scope, key).then((ok) => {
6508
  if (!ok) return; // the bridge has already said why
6509
  setFields((current) => current.filter((item) => item.key !== key));
6510
+ // ⭐ W42-T11 β€” the six-member scrub is `configWithoutFields` now, one copy for all
6511
+ // four deletes on this surface, and it drops the map's `display.colorField` too.
6512
+ // The RECONCILED `order`/`visible` are handed in, exactly as this line always
6513
+ // wrote them back, so a delete still persists the healed column sequence.
6514
+ updateConfig(configWithoutFields({ ...config, order, visible: [...visible] }, [key]));
 
 
 
 
 
 
6515
  signal(WORKSPACE_STALE_EVENT);
6516
  signal(ROWS_STALE_EVENT);
6517
  });
 
7410
  });
7411
  if (!live) return;
7412
  if (!res.ok) {
7413
+ /* β›”β›” W42-T09 β€” THE BODY IS READ BEFORE ANYTHING IS CONCLUDED FROM THE STATUS. Every
7414
+ non-2xx used to collapse to `absent`, which prints "not available yet" β€” and the
7415
+ server had already said which wall it hit (`no_pivot_route`, `pivot_unavailable`,
7416
+ `pivot_truncated`, `forbidden`), each with a sentence a reader can act on. Falling
7417
+ back to the generic line now means only what it says: the body carried no reason at
7418
+ all, so this client has nothing of the server's to quote. */
7419
+ const refusal = pivotRefusalFromBody(await res.json().catch(() => null));
7420
+ if (!live) return;
7421
+ setPivot(refusal ? { status: "refused", refusal } : { status: "absent" });
7422
  return;
7423
  }
7424
  const answer = pivotResponse(await res.json().catch(() => null));
 
7559
  ?? (linkField && linkRow ? linkRow[linkField.key] : "")
7560
  ?? ""
7561
  );
7562
+ // W42-T29 β€” the surface the picker will mount, or `undefined` when this column points at
7563
+ // something no link may target. One resolution, shared by the render guard and the mount, so
7564
+ // the modal cannot open onto a table the predicate did not authorise.
7565
+ const linkTargetScope = linkField?.type === "link"
7566
+ ? scopeForLinkTable(linkField.link?.table)
7567
+ : undefined;
7568
  const linkedRecordIds = [...new Set(
7569
  linkValue.split(",").map((part) => Number(part.trim())).filter(
7570
  (pid) => Number.isInteger(pid) && pid > 0
 
7654
 
7655
  const pivotOn = !!secondary;
7656
  const pivotAnswer = pivot.status === "ok" ? pivot.answer : null;
7657
+ /**
7658
+ * ⭐⭐ W42-T09 β€” ONE REFUSAL, TWO DOORS INTO IT. A refusal reaches this client either as C10's
7659
+ * `refusal` member on a 200 (`_pivot_reply`'s permission walls) or as a non-2xx body the fetch
7660
+ * effect above has already turned into the same shape. Both land here, so the renderer below
7661
+ * is untouched and there is exactly one sentence about walls on this surface.
7662
+ *
7663
+ * ⚠ `pivotServed` and `pivotColumnless` are unaffected on purpose: both gate on `pivotAnswer`,
7664
+ * which is null in the `refused` state, so neither predicate moves.
7665
+ */
7666
+ const pivotRefusal =
7667
+ pivotAnswer?.refusal ?? (pivot.status === "refused" ? pivot.refusal : null);
7668
  /**
7669
  * ⭐ W41-T43 β€” THE SAVED PIVOT NAMES A LINK COLUMN THIS READER WAS NOT SERVED. No request went
7670
  * out (`pivotRequestBody` is empty), so `pivot` stays `idle` and every other branch below is
 
7791
  relational={relationalState}
7792
  onRelational={setPivotVia}
7793
  onRelationalWindow={setPivotWindow}
7794
+ /* ⭐⭐ W42-T12 β€” THE PIVOT ROW STATES `null` FIVE TIMES, AND STATING IT IS THE POINT.
7795
+ `fieldBulkDoors` writes THIS view's `config` through `updateConfig`; the row below
7796
+ edits `secondary.config` through `setPivotConfig`, so handing it the grid's doors would
7797
+ mean a bulk hide on the related table silently rewriting the table you pivoted FROM.
7798
+ There is no second bag to hand it, so each act is declared absent β€” and absent makes the
7799
+ control not render at all, which is this panel's house posture. Required keys are what
7800
+ force that decision to be written down instead of left out. */
7801
+ viewer={viewer}
7802
+ onSetFieldsHidden={null}
7803
+ onShareFields={null}
7804
+ onReassignFields={null}
7805
+ onDeleteFields={null}
7806
+ onRemoveField={null}
7807
  />
7808
  ) : null;
7809
 
 
8258
  if (target && target.shared && target.kind === "route_order") deleteRouteField(key);
8259
  else deleteField(key);
8260
  }}
8261
+ /* ⭐⭐ W42-T12 (D-485, amendment A20) β€” THE FIELD MANAGER'S FIVE DOORS AND WHO IS
8262
+ LOOKING. This is the mount that renders the manager, so this is the mount that has
8263
+ to feed it: a ticked selection with Hide, Show, Share, Reassign or Delete behind it
8264
+ now reaches `useFieldBulkDoors`, which batches each act into a single config write.
8265
+ `viewer` is what lets contract C2's rights pair be asked per row, so a colleague's
8266
+ shared column offers "Remove from my fields" and never a delete. */
8267
+ viewer={viewer}
8268
+ onSetFieldsHidden={fieldBulkDoors.onSetFieldsHidden}
8269
+ onShareFields={fieldBulkDoors.onShareFields}
8270
+ onReassignFields={fieldBulkDoors.onReassignFields}
8271
+ onDeleteFields={fieldBulkDoors.onDeleteFields}
8272
+ onRemoveField={fieldBulkDoors.onRemoveField}
8273
  /* ⭐⭐ W38-T07 (owner instruction 12) β€” THE ONE COLOUR CONTROL. This was `colorOn` plus a
8274
  boolean toggle whose `true` arm guessed the column: `fields.find(type === "status")`,
8275
  so on a table with two status columns the person got the first one and had no way to
 
8353
  onToggleRoute={() => setRoutePanelOpen((open) => !open)}
8354
  />
8355
  )}
8356
+ {/* ⭐⭐ WAVE 42 Β· W42-T19 (owner instruction 11) β€” CALENDAR'S SECOND ROW, MOUNTED EMPTY IN
8357
+ THE BASELINE COMMIT. `CalendarSettings` renders `null` until lane D fills it; the mount
8358
+ lands here, now, because this file belongs to a DIFFERENT lane and a cross-lane mount is
8359
+ exactly how wave 41 shipped features nothing ever rendered. Same position and the same
8360
+ guard shape as `MapSettings` directly above, which is the pattern the owner named. */}
8361
+ {displayMode === "calendar" && !pivotOn && (
8362
+ <CalendarSettings
8363
+ dateField={calendarField}
8364
+ dateChoices={dateFieldChoices}
8365
+ onPickField={setDisplayField}
8366
+ calendarMode={displaySpec?.calendarMode ?? "records"}
8367
+ onCalendarMode={setCalendarMode}
8368
+ calendarMetrics={displaySpec?.calendarMetrics}
8369
+ metricChoices={sizeFieldChoices}
8370
+ onCalendarMetrics={setCalendarMetrics}
8371
+ />
8372
+ )}
8373
  {/* Wave-10 item 9: the view's description used to render HERE, as a full-width band
8374
  between the toolbar and the grid β€” it cost every row a strip of vertical space and
8375
  read as an alert rather than as a label. It now sits under the view's name in the
 
8483
  {pivot.status === "absent" && (
8484
  /* β›”β›” NOTHING, PLUS ONE LINE. C10's endpoint is W41-T20 and it had not been built
8485
  when this shipped. An absent answer means "not built yet", never "false", and
8486
+ never an empty grid.
8487
+ ⭐⭐ W42-T09 β€” AND IT NOW MEANS ONLY THAT. Every non-2xx used to land here, so
8488
+ this sentence was also being printed at readers the server had walled out and
8489
+ at routes it had refused by name. A body carrying any reason at all is read
8490
+ into `refused` above and quoted; this line is what is left when there is
8491
+ genuinely nothing of the server's to say. */
8492
  <div className="cg-rel-note" role="status">
8493
  The related view is not available yet, so there is nothing to show.
8494
  </div>
 
8582
  * ⭐⭐ WAVE-29 T33 (owner item 17) β€” the totals row is glide's OWN frozen trailing
8583
  * row, which is why it is aligned to every column width for free.
8584
  *
8585
+ * β›” A CONDITIONAL COUNT, never a bare `1`: with no totals row appended, freezing
8586
  * one trailing row would pin the LAST DATA RECORD to the bottom of the viewport β€”
8587
  * a record that then appears twice while scrolling, which reads as duplicated data
8588
  * rather than as a layout bug.
8589
+ *
8590
+ * ⭐⭐ W42-T17 (D-494, ruling R7) β€” THE CONDITION IS `totalsRowShown`, NOT
8591
+ * `showTotals`. `displayRows` appends the grand-total row on `totalsRowShown`;
8592
+ * `showTotals` additionally carries `!config.groupBy`. While the two differed, a
8593
+ * GROUPED grid painted its grand total and then froze zero rows, so the total
8594
+ * scrolled away with the body and read as missing. Reading the same predicate the
8595
+ * append reads makes freeze ≑ append: one frozen row exactly when one is appended,
8596
+ * zero otherwise, so the ungrouped case is unchanged and no data record is pinned.
8597
  */
8598
+ freezeTrailingRows={totalsRowShown ? 1 : 0}
8599
  rowHeight={rowHeight}
8600
  headerHeight={36}
8601
  rowMarkers="both"
 
9339
  state={columnMenu}
9340
  field={menuField}
9341
  fields={fields}
9342
+ /**
9343
+ * ⭐⭐ W42-T09 (R1, contracts C1 + C2) β€” THE TWO PROPS THAT LET A LINK COLUMN ASK THE
9344
+ * "through what?" QUESTION. Without them T08's hop editor renders and offers nothing,
9345
+ * which on screen is indistinguishable from a feature that was never built.
9346
+ *
9347
+ * β›”β›” PASSED AT BOTH `<ColumnMenu>` MOUNTS, and this file's own history is why the
9348
+ * rule is written here rather than remembered: the note beside `linkTargets` below
9349
+ * records the SAME defect landing twice, where the full column menu had a prop its "+"
9350
+ * twin did not and a column created through one door came out different from the other.
9351
+ * A hop alive at one door and dead at the other is that defect again.
9352
+ *
9353
+ * β›” `hopScopeKey` IS `scope`, NOT `storageKey`. It is contract C1's `scope_key`: the
9354
+ * COHORT scope (`customer`, `product`, a `ut_*` key), which is what a hop's cohort
9355
+ * leaves resolve against. `tableKey` is the workspace's storage key
9356
+ * (`product_table_workspace`), and stripping a suffix off one to get the other is the
9357
+ * near-miss this menu already carries a warning about. A bag missing `scope_key`
9358
+ * loses every cohort leaf without a word, so the editor refuses to emit one.
9359
+ */
9360
+ hopTopics={hopTopics}
9361
+ hopScopeKey={scope}
9362
  /**
9363
  * ⭐ 2026-08-10 β€” SELF-LINKING, and somebody asked for it (owner, D-113).
9364
  *
 
9597
  }
9598
  : undefined
9599
  }
9600
+ /**
9601
+ * ⭐⭐ W42-T13 (instruction 2, D-485) β€” "Remove from my fields" GETS ITS HOST.
9602
+ *
9603
+ * W41-T29 built the row in `ColumnMenu.tsx` and gated it on the handler's own presence
9604
+ * (`canRemoveFromMine && onRemoveFromMine`), with the prop OPTIONAL and nobody passing
9605
+ * it. So the row never rendered, at either mount, and the shipped feature looked exactly
9606
+ * like a feature nobody built. The prop is required now; this is the feed.
9607
+ *
9608
+ * β›”β›” IT REFUSES OUT LOUD, AND THAT IS DELIBERATE, NOT A STUB. There is no server door
9609
+ * for the act: `PUT /share/{kind}/{oid}` refuses anyone without `may_administer`, which
9610
+ * a plain grantee (the only person who ever sees this row) does not hold, and its
9611
+ * `entries: []` body is the OWNER revoking everyone, which is a different act with a
9612
+ * different blast radius. `useFieldBulkDoors::onRemoveField` already speaks the one
9613
+ * sentence that says so for the Fields manager's copy of this control, so both surfaces
9614
+ * say the same thing rather than drifting into two wordings of one refusal.
9615
+ * β›” NOT `deleteField`, and not the definition or route doors either. Dropping a share
9616
+ * destroys nothing, so pointing this at a delete would put a benign word on a
9617
+ * destructive act β€” the one failure W41-T29's note says must not ship.
9618
+ *
9619
+ * β›”β›” PASSED AT BOTH `<ColumnMenu>` MOUNTS. This file's own history is the reason the
9620
+ * rule keeps being restated beside each prop: a prop fed at the full column menu and
9621
+ * not at its "+" twin is the half-landing that `linkTargets` and `hopTopics` both
9622
+ * carry warnings about, caught by grepping and never by the build.
9623
+ */
9624
+ onRemoveFromMine={() => {
9625
+ fieldBulkDoors.onRemoveField(menuField.key);
9626
+ setColumnMenu(null);
9627
+ }}
9628
  onDuplicate={
9629
  // Creatable strata only β€” a base Odoo field offers no Duplicate (contract).
9630
  menuField.custom && !menuField.shared ? () => duplicateField(menuField) : undefined
 
9710
  field={fieldByKey.get(lockedKey)!}
9711
  fields={fields}
9712
  locked
9713
+ /**
9714
+ * β›”β›” W42-T37 (D-583) β€” THE THIRD TIME A PROP LANDED AT ONE OF THESE TWO MOUNTS.
9715
+ * This is the "+" CREATE door, so it is the mount where `offerableCreateKind` actually
9716
+ * decides anything: without this line the flag defaults to `false`, the picker offers
9717
+ * Created time on a `ut_*` database, and `_clean_field` returns `None` for it.
9718
+ * ⚠ `web_rollup_editor` is GREEN over that, because its leg reads `ColumnMenu.tsx`
9719
+ * alone β€” a withheld kind proven at the component and never wired at the door is
9720
+ * D-485 with a passing gate beside it. The three `PASSED AT BOTH MOUNTS` warnings in
9721
+ * this file are about exactly this, and W42-T13's `onRemoveFromMine` was the same
9722
+ * shape one ticket earlier.
9723
+ */
9724
+ isUserTable={isUserTable}
9725
  viewer={viewer}
9726
  sortedDir={null}
9727
  isFiltered={false}
 
9732
  onNote={() => undefined}
9733
  onHide={() => undefined}
9734
  onCreate={createField}
9735
+ /**
9736
+ * ⭐⭐ W42-T13 β€” THE SECOND MOUNT, and it takes the REAL door rather than an inert
9737
+ * `() => undefined` like the action handlers above it. The row is not reachable here
9738
+ * today (this mount opens straight into the create form, its nominal field is the
9739
+ * locked identity column, and `locked` plus `mayRemoveField`'s refusals stand between
9740
+ * it and the screen), and that is precisely why an inert stub would be so cheap to
9741
+ * write and so expensive later: the
9742
+ * moment anything makes it reachable, a silent no-op is D-485 restored at one door with
9743
+ * the twin working. The two doors say the same sentence or neither does.
9744
+ *
9745
+ * ⚠ `lockedKey` and not `menuField.key`: this mount's `field` IS the locked identity
9746
+ * column, so the twin's `menuField` does not exist in this scope. Copying the sibling
9747
+ * body verbatim would have compiled against the wrong identifier or not at all.
9748
+ */
9749
+ onRemoveFromMine={() => {
9750
+ fieldBulkDoors.onRemoveField(lockedKey);
9751
+ setPlusMenu(null);
9752
+ }}
9753
  /* The SAME answer as the sibling instance above, stated rather than defaulted: this is
9754
  the "+" menu and it creates through the identical `createField`, so a different value
9755
  here would mean one door offers the kind and its twin does not. The note above the
 
9781
  // either way. See the sibling's note for why self-links are offered now.
9782
  linkTargets={linkTargets}
9783
  rollupSourceOffer={rollupSourceOffer}
9784
+ /**
9785
+ * ⭐⭐ W42-T09 (R1, contracts C1 + C2) β€” THE TWO PROPS THAT LET A LINK COLUMN ASK THE
9786
+ * "through what?" QUESTION. Without them T08's hop editor renders and offers nothing,
9787
+ * which on screen is indistinguishable from a feature that was never built.
9788
+ *
9789
+ * β›”β›” PASSED AT BOTH `<ColumnMenu>` MOUNTS, and this file's own history is why the
9790
+ * rule is written here rather than remembered: the note beside `linkTargets` below
9791
+ * records the SAME defect landing twice, where the full column menu had a prop its "+"
9792
+ * twin did not and a column created through one door came out different from the other.
9793
+ * A hop alive at one door and dead at the other is that defect again.
9794
+ *
9795
+ * β›” `hopScopeKey` IS `scope`, NOT `storageKey`. It is contract C1's `scope_key`: the
9796
+ * COHORT scope (`customer`, `product`, a `ut_*` key), which is what a hop's cohort
9797
+ * leaves resolve against. `tableKey` is the workspace's storage key
9798
+ * (`product_table_workspace`), and stripping a suffix off one to get the other is the
9799
+ * near-miss this menu already carries a warning about. A bag missing `scope_key`
9800
+ * loses every cohort leaf without a word, so the editor refuses to emit one.
9801
+ */
9802
+ hopTopics={hopTopics}
9803
+ hopScopeKey={scope}
9804
  />
9805
  )}
9806
 
 
10030
  onClose={closeJson}
10031
  />
10032
  )}
10033
+ {linkField && linkTargetScope && linkAt && (
10034
  <LinkGridModal
10035
  label={linkField.label}
10036
+ table={linkTargetScope}
10037
  recordIds={linkedRecordIds}
10038
  editable={canEditField(linkField) && !isDerivedLink(linkField)}
10039
+ single={linkField.link?.single === true}
10040
+ excludeRecordId={linkTargetScope === scope ? linkAt.pid : undefined}
10041
  onSave={(ids) => patchAndRecord(
10042
  linkAt.pid,
10043
  { [linkField.key]: ids.join(",") },
web/src/customer-grid/MapView.tsx CHANGED
@@ -93,6 +93,16 @@ import {
93
  } from "./mapProjection";
94
  import type { GeoStop, Pt, RouteStamp, View } from "./mapProjection";
95
  import { LP_INK, LP_MAP_SELECTED } from "./theme";
 
 
 
 
 
 
 
 
 
 
96
  import "./map.css";
97
 
98
  /**
@@ -423,6 +433,19 @@ export function MapView({
423
  * Kept as pids rather than indices because the selection can change underneath it.
424
  */
425
  const [routeOrder, setRouteOrder] = useState<number[] | null>(null);
 
 
 
 
 
 
 
 
 
 
 
 
 
426
  /**
427
  * β›” OWNER ITEM 6 β€” THE DEPOT UI IS GONE AND THIS STATE DELIBERATELY IS NOT. The owner removed
428
  * the "Optional route start" section: the start is the record dropdown and nothing else. What
@@ -486,8 +509,44 @@ export function MapView({
486
  * must not render "no saved orders".
487
  */
488
  const [routeCols, setRouteCols] = useState<
489
- { key: string; label: string; inputsHash: string; mine: boolean; depot?: RouteDepot | null }[] | null
490
  >(null);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
491
  /** Which saved column a save writes to. `""` = a new field, named in the prompt below. */
492
  const [saveTarget, setSaveTarget] = useState("");
493
  /**
@@ -890,6 +949,9 @@ export function MapView({
890
  if (!routePanelOpen) {
891
  autoRouteRef.current = false;
892
  setAutoCapped(0);
 
 
 
893
  return;
894
  }
895
  if (autoRouteRef.current || points.length < 2) return;
@@ -1117,6 +1179,8 @@ export function MapView({
1117
  const res = await fetch("/api/v1/customers/route-order", { credentials: "same-origin" });
1118
  const body = res.ok ? await res.json().catch(() => null) : null;
1119
  setRouteCols(Array.isArray(body?.fields) ? body.fields : []);
 
 
1120
  setNextLabel(typeof body?.nextLabel === "string" ? body.nextLabel : "");
1121
  } catch {
1122
  // A listing that cannot be fetched is "none known", not an error banner over the map: the
@@ -1262,9 +1326,18 @@ export function MapView({
1262
  return;
1263
  }
1264
  const savedField = String(body?.field || "");
 
 
 
 
 
 
1265
  setSaveTarget(savedField);
1266
  setNaming(false);
1267
  if (savedField) onRouteFieldCreated?.(savedField);
 
 
 
1268
  setSaveMsg(
1269
  `Saved ${Number(body?.stops || 0).toLocaleString()} visit numbers to ` +
1270
  `${body?.label || "the column"}` +
@@ -1278,6 +1351,279 @@ export function MapView({
1278
  }
1279
  }, [plan, saveTarget, roundTrip, routeCols, nextLabel, loadRouteCols, onRouteFieldCreated]);
1280
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1281
  /**
1282
  * The saved column selected for writing, and whether what is on screen would solve differently.
1283
  *
@@ -1483,6 +1829,142 @@ export function MapView({
1483
  [plan]
1484
  );
1485
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1486
  const paint = useCallback(
1487
  (p: MapPoint) => {
1488
  if (!colorBuckets) return DEFAULT_PIN;
@@ -1956,6 +2438,82 @@ export function MapView({
1956
  : "Nothing selected"}
1957
  </span>
1958
  </div>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1959
  <div className="cg-map-route">
1960
  {/* ══ OWNER, 2026-08-23 β€” CHOOSE WHICH SAVED ROUTE TO LOOK AT ══════════════════
1961
  Owner: *"when I click the Route navigation button. I should be able to choose any
@@ -2260,8 +2818,66 @@ export function MapView({
2260
  <div className="cg-map-stoplist">
2261
  {plan.ordered.map((pt, i) => (
2262
  <span className="cg-map-stopitem" key={pt.pid}>
 
 
 
 
 
 
 
2263
  <span className="cg-map-stopn">
2264
- {pt.pid === DEPOT_PID ? "" : i + 1 - (plan.depot ? 1 : 0)}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2265
  </span>
2266
  <span className="cg-map-stopname" title={pt.title || `#${pt.pid}`}>
2267
  {pt.title || `#${pt.pid}`}
@@ -2310,6 +2926,21 @@ export function MapView({
2310
  </div>
2311
  )}
2312
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2313
  {/* β›” WAVE 41 / R13 β€” THE DISCARD-MY-ORDER BUTTON STOOD HERE AND IS NOT REPLACED
2314
  IN PLACE. Discarding the hand-picked sequence is half of `Update calculation`
2315
  in the foot row now, so a control offering only that half would put the panel
@@ -2568,8 +3199,14 @@ export function MapView({
2568
  knew about. It needs shift too β€” alt alone still pans. */}
2569
  <span className="cg-map-hint">
2570
  Scroll to zoom Β· drag to pan Β· {lassoTool ? "shift-drag to lasso" : "shift-drag to select"}{" "}
2571
- Β· shift-alt-drag to extend the selection Β· click a pin to open the record Β· shift-click a
2572
- pin to add or remove it from the selection
 
 
 
 
 
 
2573
  </span>
2574
  </div>
2575
  <div
@@ -2726,7 +3363,18 @@ export function MapView({
2726
  // hint bar above is the SIGHTED half of this same disclosure. It said "Click to
2727
  // select, double click to open." until R10 made that false.
2728
  // Policed by `verify_ui.py::pin_label_states_the_gesture`.
2729
- aria-label={`${p.title || "Untitled record"}. Click to open, shift-click to select.`}
 
 
 
 
 
 
 
 
 
 
 
2730
  onMouseEnter={() => setHoverPid(p.pid)}
2731
  onMouseLeave={() => setHoverPid((h) => (h === p.pid ? null : h))}
2732
  onFocus={() => setHoverPid(p.pid)}
@@ -2744,6 +3392,20 @@ export function MapView({
2744
  pinSelect(p.pid, true);
2745
  return;
2746
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2747
  // ⭐⭐ W41-T48 (owner instruction 22) β€” OPENING A RECORD FOLDS THE RAIL, ON
2748
  // THE MAP EXACTLY AS IN THE GRID. `CustomerGrid.tsx::onCellClicked` raises
2749
  // this on every cell click; the map was the one surface that opened a record
@@ -2778,6 +3440,11 @@ export function MapView({
2778
  onDoubleClick={(e) => {
2779
  if (movedRef.current) return;
2780
  e.preventDefault();
 
 
 
 
 
2781
  onOpen(p.pid);
2782
  }}
2783
  onKeyDown={(e) => {
@@ -2789,6 +3456,13 @@ export function MapView({
2789
  // disambiguate, so the guard the pointer needs would only be superstition.
2790
  if (e.key === "Enter") {
2791
  e.preventDefault();
 
 
 
 
 
 
 
2792
  // W41-T48 β€” the keyboard mirror of the plain click, so it folds the rail
2793
  // for the same reason. ⚠ `!e.repeat` is this path's `e.detail <= 1`: a HELD
2794
  // Enter auto-repeats keydown for as long as the finger is down, and every
 
93
  } from "./mapProjection";
94
  import type { GeoStop, Pt, RouteStamp, View } from "./mapProjection";
95
  import { LP_INK, LP_MAP_SELECTED } from "./theme";
96
+ // W42-T24 (contract C6) β€” the route NAVIGATION, and every door it needs.
97
+ import { RouteNav } from "./RouteNav";
98
+ import type { RouteNavRoute } from "./RouteNav";
99
+ import type { GridFolder } from "./types";
100
+ import { newFolderId } from "./folders";
101
+ import { deleteRouteOrderField, patchRouteOrderField } from "./apiBridge";
102
+ import { emitHostEvent, eventId } from "./hostBridge";
103
+ import type { HostEvent } from "./types";
104
+ // ⚠ `styles/wave42/route-nav.css` is NOT imported here: `index.css` already @imports it at the
105
+ // top of the file, and a second import would ship the rules twice and change their cascade order.
106
  import "./map.css";
107
 
108
  /**
 
433
  * Kept as pids rather than indices because the selection can change underneath it.
434
  */
435
  const [routeOrder, setRouteOrder] = useState<number[] | null>(null);
436
+ /**
437
+ * ⭐ W42-T21 β€” A POSITION CAN BE TYPED, so the visit number is a text box and needs somewhere
438
+ * to hold what a person has typed but not yet committed. Keyed by pid rather than by index:
439
+ * the index of the row being edited changes the instant the order does.
440
+ */
441
+ const [stopPosDraft, setStopPosDraft] = useState<{ pid: number; text: string } | null>(null);
442
+ /**
443
+ * β›” THE REFUSAL IS ON SCREEN, NOT IN THE REQUEST. `route_order_write` rejects any body that
444
+ * is not a full 1..N permutation, so a bad number must never travel; and a box that silently
445
+ * snapped back to the old value would leave a person retyping the same thing. It says what is
446
+ * wrong, keeps the typed text visible, and nothing is sent.
447
+ */
448
+ const [stopPosError, setStopPosError] = useState<{ pid: number; msg: string } | null>(null);
449
  /**
450
  * β›” OWNER ITEM 6 β€” THE DEPOT UI IS GONE AND THIS STATE DELIBERATELY IS NOT. The owner removed
451
  * the "Optional route start" section: the start is the record dropdown and nothing else. What
 
509
  * must not render "no saved orders".
510
  */
511
  const [routeCols, setRouteCols] = useState<
512
+ (RouteNavRoute & { inputsHash: string; depot?: RouteDepot | null })[] | null
513
  >(null);
514
+ /**
515
+ * ⭐⭐ W42-T24 (contract C6) β€” THIS READER'S ROUTE FOLDERS, and they ride the SAME listing.
516
+ *
517
+ * W42-T23 made the rail's folder rows travel with `GET /customers/route-order` for the reason
518
+ * its own comment gives: a `folderId` with no folder list beside it names a section the client
519
+ * cannot draw. So there is no second fetch and no second source of truth about which folders
520
+ * exist.
521
+ */
522
+ const [routeFolders, setRouteFolders] = useState<GridFolder[]>([]);
523
+ /**
524
+ * ⚠ THE RAIL'S OWN ROUTE ORDER, AND IT IS CLIENT-LOCAL THIS WAVE. Filing a route is durable
525
+ * (`PATCH /customers/route-order/{key}/folder`), but there is no per-user ORDER stratum for
526
+ * routes: `view_reorder` writes `save_view_order`, which is the VIEWS rail's order and ignores
527
+ * `surface` entirely, so emitting it for routes would silently replace the reader's view rail
528
+ * arrangement with a list of route keys. Dragging therefore reorders for this session and is
529
+ * declared as such rather than sent to a door that would answer the wrong question.
530
+ */
531
+ const [railOrder, setRailOrder] = useState<string[]>([]);
532
+ /** The route just created, so the rail can PROMPT to share it. Null the rest of the time. */
533
+ const [createdRoute, setCreatedRoute] = useState<{ key: string; label: string } | null>(null);
534
+ /** Which route the rail is waiting on a server answer for. */
535
+ const [routeBusyKey, setRouteBusyKey] = useState("");
536
+ /** The rail's own message slot, on screen whether or not a plan exists. See `startNewRoute`. */
537
+ const [railNotice, setRailNotice] = useState("");
538
+
539
+ /**
540
+ * ⭐⭐ W42-T49 β€” WITH THE ROUTE OPEN, A PIN CLICK ASKS ABOUT A STOP.
541
+ *
542
+ * The pin that was clicked, the name to say it by, and whether it is ALREADY a stop. β›” `on` is
543
+ * MEMBERSHIP and never the map's selection: see `routeStopPids` for why those are two different
544
+ * sets and why reading the wrong one would make this feature answer confidently and wrongly.
545
+ * ⚠ Cleared when the route closes (the reset effect over `autoRouteRef`), so a prompt cannot
546
+ * outlive the mode that raised it and greet somebody minutes later.
547
+ */
548
+ const [routePinAsk, setRoutePinAsk] =
549
+ useState<{ pid: number; title: string; on: boolean } | null>(null);
550
  /** Which saved column a save writes to. `""` = a new field, named in the prompt below. */
551
  const [saveTarget, setSaveTarget] = useState("");
552
  /**
 
949
  if (!routePanelOpen) {
950
  autoRouteRef.current = false;
951
  setAutoCapped(0);
952
+ // W42-T49 β€” closing the route ends its mode completely. A prompt left standing would come
953
+ // back with the panel, asking about a pin somebody clicked before they closed it.
954
+ setRoutePinAsk(null);
955
  return;
956
  }
957
  if (autoRouteRef.current || points.length < 2) return;
 
1179
  const res = await fetch("/api/v1/customers/route-order", { credentials: "same-origin" });
1180
  const body = res.ok ? await res.json().catch(() => null) : null;
1181
  setRouteCols(Array.isArray(body?.fields) ? body.fields : []);
1182
+ // W42-T23 / C6 β€” the rail's own folder ROWS travel with the listing.
1183
+ setRouteFolders(Array.isArray(body?.folders) ? (body.folders as GridFolder[]) : []);
1184
  setNextLabel(typeof body?.nextLabel === "string" ? body.nextLabel : "");
1185
  } catch {
1186
  // A listing that cannot be fetched is "none known", not an error banner over the map: the
 
1326
  return;
1327
  }
1328
  const savedField = String(body?.field || "");
1329
+ // ⭐ W42-T24 β€” A NEW ROUTE PROMPTS TO SHARE IT, AND ONLY A NEW ONE. `saveTarget` is the
1330
+ // column this save WRITES TO, so a non-empty one means the person re-solved a route that
1331
+ // already exists; its sharing was decided when it was made and asking again every time
1332
+ // somebody recalculates would be nagging rather than a choice. Read BEFORE `setSaveTarget`
1333
+ // below moves it to the saved key.
1334
+ const wasNew = !saveTarget;
1335
  setSaveTarget(savedField);
1336
  setNaming(false);
1337
  if (savedField) onRouteFieldCreated?.(savedField);
1338
+ if (savedField && wasNew) {
1339
+ setCreatedRoute({ key: savedField, label: String(body?.label || savedField) });
1340
+ }
1341
  setSaveMsg(
1342
  `Saved ${Number(body?.stops || 0).toLocaleString()} visit numbers to ` +
1343
  `${body?.label || "the column"}` +
 
1351
  }
1352
  }, [plan, saveTarget, roundTrip, routeCols, nextLabel, loadRouteCols, onRouteFieldCreated]);
1353
 
1354
+ // ─────────────── W42-T24 (instruction 10, contract C6): the route NAVIGATION's doors ────────
1355
+ /**
1356
+ * β›”β›” RENAME AND DELETE TAKE THE ROUTE'S OWN DOOR, NEVER THE GENERIC FIELD ONE.
1357
+ *
1358
+ * A route order is a SHARED column on the customers registry topic. The per-user `field_upsert`
1359
+ * event and the `ut_*` definition PATCH both reach a different stratum, so sending a rename
1360
+ * down either forks the tenant-wide column into a private copy of itself wearing the new name
1361
+ * while everybody else keeps the old one. `apiBridge`'s two helpers carry the server's own
1362
+ * refusal sentence, which distinguishes "somebody else planned this" from "that name is taken".
1363
+ */
1364
+ const renameRoute = useCallback(
1365
+ (key: string, label: string) => {
1366
+ setRouteBusyKey(key);
1367
+ void patchRouteOrderField(key, { label }).then((ok) => {
1368
+ setRouteBusyKey("");
1369
+ if (ok) void loadRouteCols();
1370
+ });
1371
+ },
1372
+ [loadRouteCols]
1373
+ );
1374
+
1375
+ const removeRoute = useCallback(
1376
+ (key: string) => {
1377
+ setRouteBusyKey(key);
1378
+ void deleteRouteOrderField(key).then((ok) => {
1379
+ setRouteBusyKey("");
1380
+ if (!ok) return;
1381
+ if (openedRoute === key) setOpenedRoute("");
1382
+ if (saveTarget === key) setSaveTarget("");
1383
+ void loadRouteCols();
1384
+ });
1385
+ },
1386
+ [loadRouteCols, openedRoute, saveTarget]
1387
+ );
1388
+
1389
+ /**
1390
+ * Duplicate a route: the SAME visit numbers under a new name.
1391
+ *
1392
+ * β›” THE RANKS COME OFF THE ROWS, NOT FROM A NEW FETCH, for `openSavedRoute`'s reason: a route
1393
+ * column's rank rides every row the reader may see, so the copy is made from what is already in
1394
+ * hand. ⚠ And it reads `allRows`, the book AFTER the row wall and BEFORE the view's filters, so
1395
+ * a duplicate is the whole route rather than the part today's filter happens to show.
1396
+ * ⚠ A RANK IS READ AS A NUMBER. `shared_overlay` stores cells as strings, so copying the raw
1397
+ * values would hand the server "10" before "2" and mint a plausible day in the wrong sequence.
1398
+ */
1399
+ const duplicateRoute = useCallback(
1400
+ async (key: string) => {
1401
+ const src = (routeCols || []).find((f) => f.key === key);
1402
+ if (!src) return;
1403
+ const book = allRows && allRows.length ? allRows : rows;
1404
+ const ranks: Record<number, number> = {};
1405
+ for (const r of book) {
1406
+ const raw = r[key];
1407
+ if (raw === null || raw === undefined || raw === "") continue;
1408
+ const rank = Number(raw);
1409
+ if (Number.isFinite(rank)) ranks[r.pid] = rank;
1410
+ }
1411
+ if (Object.keys(ranks).length < 2) {
1412
+ // β›” REPORTED, NEVER SILENT (standing rule 1's second sentence). A route whose stops are
1413
+ // all outside this account's book cannot be copied, and a Duplicate that did nothing
1414
+ // would read as a broken menu rather than as a wall doing its job.
1415
+ setSaveErr(
1416
+ "That route has fewer than two stops in your book, so there is nothing to copy. The " +
1417
+ "records it was planned over may sit outside the rows you are permitted to see."
1418
+ );
1419
+ return;
1420
+ }
1421
+ setRouteBusyKey(key);
1422
+ try {
1423
+ const res = await fetch("/api/v1/customers/route-order", {
1424
+ method: "POST",
1425
+ credentials: "same-origin",
1426
+ headers: { "Content-Type": "application/json" },
1427
+ body: JSON.stringify({
1428
+ label: `${src.label} copy`,
1429
+ ranks,
1430
+ inputsHash: src.inputsHash,
1431
+ }),
1432
+ });
1433
+ const body = await res.json().catch(() => null);
1434
+ if (!res.ok) {
1435
+ setSaveErr((body && body.error && body.error.message) || "That route could not be copied.");
1436
+ return;
1437
+ }
1438
+ const madeKey = String(body?.field || "");
1439
+ if (madeKey) {
1440
+ onRouteFieldCreated?.(madeKey);
1441
+ setCreatedRoute({ key: madeKey, label: String(body?.label || madeKey) });
1442
+ }
1443
+ await loadRouteCols();
1444
+ } catch {
1445
+ setSaveErr("That route could not be copied.");
1446
+ } finally {
1447
+ setRouteBusyKey("");
1448
+ }
1449
+ },
1450
+ [routeCols, allRows, rows, loadRouteCols, onRouteFieldCreated]
1451
+ );
1452
+
1453
+ /**
1454
+ * ⭐⭐ SHARING RIDES THE EXISTING GENERIC FIELD DOOR (C6). A route IS a field, so its oid is
1455
+ * `<tableKey>:<fieldKey>` exactly as `ColumnMenu.tsx::shareOid` builds one, and the dialog is
1456
+ * the one a view or a field already opens.
1457
+ *
1458
+ * β›” THE EVENT LITERAL IS RE-SPELLED HERE ON PURPOSE. `customer-grid/**` is host neutral and
1459
+ * may not import `shell/**`, so `SHARE_OPEN_EVENT` is not imported across the boundary. Both
1460
+ * `ColumnMenu.tsx` and `ViewSidebar.tsx` spell it the same way for the same reason.
1461
+ * ⚠ `topic` is omitted: the shell fills it from the active database, and a wrong guess here
1462
+ * would open the dialog against a database this route does not live on.
1463
+ */
1464
+ const shareRoute = useCallback((key: string, label: string) => {
1465
+ window.dispatchEvent(
1466
+ new CustomEvent("aios:share-open", {
1467
+ detail: { kind: "field", id: `customer_data:${key}`, label },
1468
+ })
1469
+ );
1470
+ setCreatedRoute(null);
1471
+ }, []);
1472
+
1473
+ /**
1474
+ * File a route into one of this reader's route folders.
1475
+ *
1476
+ * β›”β›” THE ROUTE'S OWN DOOR, AND THE GENERIC ONE IS NOT AVAILABLE HERE. `grid_events`'
1477
+ * `item_move` gates the mover on `_own_ids(surface, ws)`, which is an `if views: ... else
1478
+ * cohorts` two-way split rather than a lookup β€” so filing a route through it answers "you can
1479
+ * file only the items you own" about a column the person planned themselves. W42-T23 built
1480
+ * `PATCH /customers/route-order/{key}/folder` for exactly that, and it walls on "can you see
1481
+ * it" rather than "is it yours", because a placement changes one account's sidebar only.
1482
+ * ⚠ THE RECEIPT IS ADOPTED, not assumed. `validate_folder_tree` REPAIRS a placement whose
1483
+ * folder was deleted rather than refusing it, and a repair the caller never hears about is a
1484
+ * route that quietly moved.
1485
+ */
1486
+ const moveRoute = useCallback(
1487
+ async (key: string, folderId: string | null) => {
1488
+ setRouteBusyKey(key);
1489
+ try {
1490
+ const res = await fetch(
1491
+ `/api/v1/customers/route-order/${encodeURIComponent(key)}/folder`,
1492
+ {
1493
+ method: "PATCH",
1494
+ credentials: "same-origin",
1495
+ headers: { "Content-Type": "application/json" },
1496
+ body: JSON.stringify({ folderId }),
1497
+ }
1498
+ );
1499
+ const body = await res.json().catch(() => null);
1500
+ if (!res.ok) {
1501
+ setSaveErr((body && body.error && body.error.message) || "That route could not be filed.");
1502
+ return;
1503
+ }
1504
+ await loadRouteCols();
1505
+ } catch {
1506
+ setSaveErr("That route could not be filed.");
1507
+ } finally {
1508
+ setRouteBusyKey("");
1509
+ }
1510
+ },
1511
+ [loadRouteCols]
1512
+ );
1513
+
1514
+ /**
1515
+ * The routes rail's FOLDER rows, through the generic folder door.
1516
+ *
1517
+ * ⚠ THE GENERIC DOOR IS RIGHT FOR A FOLDER AND WRONG FOR A PLACEMENT, and the split is not
1518
+ * arbitrary: `folder_create` / `folder_rename` / `folder_delete` / `folder_reorder` never
1519
+ * consult `_own_ids` for an ITEM, so `surface: "routes"` passes through them unharmed. Only
1520
+ * `item_move` has the ownership gate, and that is the one this file does not use.
1521
+ *
1522
+ * β›” THE CAST IS DECLARED, NOT HIDDEN. `types.ts::FolderSurface` is `"views" | "cohorts"`, and
1523
+ * `types.ts` is not this ticket's file to widen, so a route folder event cannot be typed from
1524
+ * here. `aios_grid.FOLDER_SURFACES` already carries `"routes"` (W42-T23), so the wire value is
1525
+ * legal; what is missing is the client declaration, and it is owed.
1526
+ */
1527
+ const routeFolderEvent = useCallback((event: Record<string, unknown>) => {
1528
+ emitHostEvent({ ...event, surface: "routes" } as unknown as HostEvent);
1529
+ }, []);
1530
+
1531
+ const createRouteFolder = useCallback(
1532
+ (name: string, parent: string | null) => {
1533
+ const folderId = newFolderId();
1534
+ // Optimistic, like every other rail: the folder must exist on screen before a route can be
1535
+ // dragged into it, and the listing's next read is what settles the truth.
1536
+ setRouteFolders((cur) => [...cur, { id: folderId, name, order: cur.length, parent }]);
1537
+ routeFolderEvent({ id: eventId("rtfold"), type: "folder_create", folderId, name, parent });
1538
+ },
1539
+ [routeFolderEvent]
1540
+ );
1541
+
1542
+ const renameRouteFolder = useCallback(
1543
+ (folderId: string, name: string) => {
1544
+ setRouteFolders((cur) => cur.map((f) => (f.id === folderId ? { ...f, name } : f)));
1545
+ routeFolderEvent({ id: eventId("rtfold"), type: "folder_rename", folderId, name });
1546
+ },
1547
+ [routeFolderEvent]
1548
+ );
1549
+
1550
+ const deleteRouteFolder = useCallback(
1551
+ (folderId: string) => {
1552
+ // CONTENTS MOVE TO ROOT, never delete β€” the folder contract is explicit, and the menu's
1553
+ // armed copy says so before this runs.
1554
+ setRouteFolders((cur) => cur.filter((f) => f.id !== folderId));
1555
+ routeFolderEvent({ id: eventId("rtfold"), type: "folder_delete", folderId });
1556
+ // β›” NO RE-READ HERE, AND THE ABSENCE IS DELIBERATE. The listing is fetched over its own
1557
+ // connection while the folder event is still in flight, so a reload fired now can answer
1558
+ // out of the state that predates the delete and put the folder straight back on screen. The
1559
+ // routes it held need no help: their stored placement names an id that no longer resolves,
1560
+ // and both `groupByFolder` here and `_route_folder_id` on the server render exactly that as
1561
+ // the top level, which is the contract's "contents move to root, never delete".
1562
+ },
1563
+ [routeFolderEvent]
1564
+ );
1565
+
1566
+ const reorderRouteFolders = useCallback(
1567
+ (order: string[]) => {
1568
+ setRouteFolders((cur) => {
1569
+ const known = new Map(cur.map((f) => [f.id, f]));
1570
+ const ranked = order.map((id) => known.get(id)).filter(Boolean) as GridFolder[];
1571
+ for (const f of cur) if (!order.includes(f.id)) ranked.push(f);
1572
+ return ranked;
1573
+ });
1574
+ routeFolderEvent({ id: eventId("rtfold"), type: "folder_reorder", order });
1575
+ },
1576
+ [routeFolderEvent]
1577
+ );
1578
+
1579
+ /**
1580
+ * ⭐ CREATING A ROUTE IS A SEPARATE AFFORDANCE from opening one, and it lands in the planner
1581
+ * rather than minting an empty object: a route IS a solved sequence, so "create" means "solve
1582
+ * the stops you have and name the answer". `saveTarget` is cleared first so the save mints a
1583
+ * NEW column instead of overwriting whichever route happens to be open.
1584
+ */
1585
+ const startNewRoute = useCallback(() => {
1586
+ setCreatedRoute(null);
1587
+ // β›”β›” REFUSED OUT LOUD, IN THE RAIL'S OWN SLOT. The name box lives inside the planner's
1588
+ // `{plan && (...)}`, and `plan` is null until two records can actually be routed - so
1589
+ // flipping `naming` with nothing selected would open a form that never renders and leave
1590
+ // Create as a menu row that does nothing. The rail's `notice` is the one message slot that
1591
+ // is on screen whether or not a plan exists, which is why the refusal goes there.
1592
+ if (routable.length < 2) {
1593
+ setRailNotice(
1594
+ "A route is a solved sequence, so select at least two records on the map first. Then " +
1595
+ "Create new gives you the name box."
1596
+ );
1597
+ return;
1598
+ }
1599
+ setRailNotice("");
1600
+ setSaveTarget("");
1601
+ setSaveErr(null);
1602
+ setSaveMsg(null);
1603
+ setRouteOn(true);
1604
+ setNaming(true);
1605
+ setNameDraft(nextLabel);
1606
+ }, [nextLabel, routable]);
1607
+
1608
+ /**
1609
+ * The rail's routes, in the reader's own arrangement.
1610
+ *
1611
+ * ⚠ `railOrder` RANKS, IT DOES NOT FILTER. A route the order has never heard of keeps its place
1612
+ * after the ranked ones, so a colleague's brand-new route appears rather than vanishing until
1613
+ * somebody drags something.
1614
+ */
1615
+ const railRoutes = useMemo<RouteNavRoute[]>(() => {
1616
+ const all = routeCols || [];
1617
+ if (!railOrder.length) return all;
1618
+ const rank = new Map(railOrder.map((k, i) => [k, i]));
1619
+ return [...all].sort(
1620
+ (a, b) => (rank.get(a.key) ?? Number.MAX_SAFE_INTEGER) - (rank.get(b.key) ?? Number.MAX_SAFE_INTEGER)
1621
+ );
1622
+ }, [routeCols, railOrder]);
1623
+
1624
+ const reorderRail = useCallback((order: string[]) => setRailOrder(order), []);
1625
+ const dismissCreated = useCallback(() => setCreatedRoute(null), []);
1626
+
1627
  /**
1628
  * The saved column selected for writing, and whether what is on screen would solve differently.
1629
  *
 
1829
  [plan]
1830
  );
1831
 
1832
+ /**
1833
+ * ⭐ W42-T21 β€” TYPING A POSITION IS A MOVE-TO-POSITION, NOT A RANK.
1834
+ *
1835
+ * β›”β›” THE TYPED NUMBER IS A TARGET INDEX AND IS DISCARDED BEFORE ANY RANK EXISTS. Writing it
1836
+ * as that record's rank is the trap: `routes_customers.py::route_order_write` refuses any body
1837
+ * that is not a full 1..N permutation, so a straight-through write leaves a duplicate or a gap
1838
+ * and the endpoint 400s, which reads to a person as "typing does not work". Here the value
1839
+ * only chooses where the pid is re-inserted; the sequence is then rebuilt by the same
1840
+ * remove-then-insert the arrows use, and `plan` inverts THAT into `ranksByPid` from array
1841
+ * indices. So the saved order is 1..N by construction, whatever was typed.
1842
+ *
1843
+ * Returns the sentence to show, or null when the move was applied.
1844
+ */
1845
+ const moveStopTo = useCallback(
1846
+ (pid: number, raw: string): string | null => {
1847
+ if (!plan || pid === DEPOT_PID) return null;
1848
+ const ids = plan.ordered.filter((p) => p.pid !== DEPOT_PID).map((p) => p.pid);
1849
+ const at = ids.indexOf(pid);
1850
+ if (at < 0) return "This stop is no longer on the route, so its position cannot be set.";
1851
+ const text = raw.trim();
1852
+ if (!/^[0-9]+$/.test(text)) {
1853
+ return "A position is a whole number, so type a digit rather than anything else.";
1854
+ }
1855
+ const pos = Number(text);
1856
+ if (pos < 1 || pos > ids.length) {
1857
+ return ids.length === 1
1858
+ ? "There is one stop on this route, so the only position is 1."
1859
+ : `There are ${ids.length} stops on this route, so a position runs from 1 to ${ids.length}.`;
1860
+ }
1861
+ if (pos === at + 1) return null;
1862
+ const next = [...ids];
1863
+ next.splice(pos - 1, 0, next.splice(at, 1)[0]);
1864
+ // ⚠ AN INVARIANT GUARD, NOT THE REFUSAL A PERSON WILL MEET. Remove-then-insert on a list
1865
+ // that was already a permutation cannot duplicate or drop a pid, so this cannot fire from
1866
+ // the keyboard; it is here so that a future edit which DOES break the sequence stops at
1867
+ // the screen instead of at a 400 the user has no way to read.
1868
+ if (next.length !== ids.length || new Set(next).size !== next.length) {
1869
+ return "That would leave two stops sharing a position, so the route was left as it was.";
1870
+ }
1871
+ setRouteOrder(next);
1872
+ return null;
1873
+ },
1874
+ [plan]
1875
+ );
1876
+
1877
+ /**
1878
+ * Commit what is in the box. A refusal keeps the typed text on screen and sends nothing; a
1879
+ * move clears both the draft and any refusal, and the row renumbers itself from `plan`.
1880
+ */
1881
+ const commitStopPos = useCallback(
1882
+ (pid: number, raw: string) => {
1883
+ const msg = moveStopTo(pid, raw);
1884
+ if (msg) {
1885
+ setStopPosError({ pid, msg });
1886
+ return;
1887
+ }
1888
+ setStopPosDraft(null);
1889
+ setStopPosError(null);
1890
+ },
1891
+ [moveStopTo]
1892
+ );
1893
+
1894
+ /**
1895
+ * β›”β›” W42-T49 β€” MEMBERSHIP, AND IT IS NOT THE SELECTION.
1896
+ *
1897
+ * `selectedPids` is the map's highlight. The route panel SEEDS that highlight from a route when
1898
+ * one is opened, which is exactly what makes the two sets easy to confuse and the confusion
1899
+ * invisible. The question here is a different one: is this record a STOP on the route now on
1900
+ * screen? The route on screen is `plan.ordered` (the depot is not a record, so it is dropped);
1901
+ * before a plan has been solved there is still an order to answer from, either a hand-picked
1902
+ * `routeOrder` or the ranks the saved column carries on the rows, read exactly as
1903
+ * `openSavedRoute` reads them (as NUMBERS, since `shared_overlay` stores cells as strings).
1904
+ *
1905
+ * ⚠ THE SAVED CELLS ARE A LAST RESORT AND NEVER A UNION with the live list. A stop taken off
1906
+ * the route keeps its old rank in the column until Save route writes the new sequence, so
1907
+ * folding the cells into the live set would answer "still on it" for the stop just removed.
1908
+ */
1909
+ const routeStopPids = useMemo<ReadonlySet<number>>(() => {
1910
+ if (plan) {
1911
+ return new Set(plan.ordered.filter((p) => p.pid !== DEPOT_PID).map((p) => p.pid));
1912
+ }
1913
+ if (routeOrder && routeOrder.length) return new Set(routeOrder);
1914
+ const out = new Set<number>();
1915
+ if (!openedRoute) return out;
1916
+ const book = allRows && allRows.length ? allRows : rows;
1917
+ for (const r of book) {
1918
+ const raw = r[openedRoute];
1919
+ if (raw === null || raw === undefined || raw === "") continue;
1920
+ if (Number.isFinite(Number(raw))) out.add(r.pid);
1921
+ }
1922
+ return out;
1923
+ }, [plan, routeOrder, openedRoute, allRows, rows]);
1924
+
1925
+ /**
1926
+ * ⭐⭐ W42-T49 β€” THE PIN CLICK ASKS FIRST, AND IT ASKS THE RIGHT QUESTION.
1927
+ *
1928
+ * β›” IT CHANGES NOTHING. Raising the prompt is the whole of this handler: a pin is a target you
1929
+ * had to aim at, and on a map where pins overlap an aimed click that silently rewrote somebody's
1930
+ * day would be worse than the drawer it replaced.
1931
+ */
1932
+ const askRoutePin = useCallback(
1933
+ (pid: number, title: string) => {
1934
+ if (pid === DEPOT_PID) return;
1935
+ setRoutePinAsk({ pid, title, on: routeStopPids.has(pid) });
1936
+ },
1937
+ [routeStopPids]
1938
+ );
1939
+
1940
+ /**
1941
+ * β›”β›” W42-T49 β€” ADD AND REMOVE GO THROUGH THE PANEL'S OWN DOORS, SO THE SEQUENCE IS REBUILT.
1942
+ *
1943
+ * `route_order_write` refuses any body that is not a full 1..N permutation, so a rank written
1944
+ * through for one record is the trap here exactly as it was for the typed position in W42-T21.
1945
+ * Nothing in this path touches a rank: `addRecord` appends the pid to `routeOrder` and
1946
+ * `removeStop` filters it out, `plan` then re-derives `ranksByPid` from ARRAY INDICES over
1947
+ * whatever list survived, and `saveRouteOrder` sends that. The saved order is therefore 1..N by
1948
+ * construction whichever pin was clicked.
1949
+ *
1950
+ * ⚠ AND IT IS THE ROUTE ON SCREEN THAT MOVES, NOT THE STORED COLUMN. `plan` has not recomputed
1951
+ * in this tick, so saving from here would persist the sequence as it was BEFORE the stop moved:
1952
+ * a plausible permutation describing the wrong day. The message says which act still writes.
1953
+ */
1954
+ const applyRoutePin = useCallback(() => {
1955
+ const ask = routePinAsk;
1956
+ if (!ask) return;
1957
+ setRoutePinAsk(null);
1958
+ const name = ask.title || `record ${ask.pid}`;
1959
+ if (ask.on) {
1960
+ removeStop(ask.pid);
1961
+ setRailNotice(`${name} is off this route. Save route writes the new visit numbers.`);
1962
+ return;
1963
+ }
1964
+ addRecord(ask.pid);
1965
+ setRailNotice(`${name} joins this route at the end. Save route writes the new visit numbers.`);
1966
+ }, [routePinAsk, removeStop, addRecord]);
1967
+
1968
  const paint = useCallback(
1969
  (p: MapPoint) => {
1970
  if (!colorBuckets) return DEFAULT_PIN;
 
2438
  : "Nothing selected"}
2439
  </span>
2440
  </div>
2441
+ {/* ══ W42-T49 β€” THE PIN CLICK'S ANSWER, ASKED BEFORE ANYTHING MOVES ═════════════
2442
+ ⭐ IT LIVES IN THE ROUTE'S OWN PANEL, at the top, because the route is what the
2443
+ question is about and the panel is the surface that shows the consequence: the
2444
+ stop list under it gains or loses the row the moment Add or Take off is pressed.
2445
+ ⚠ EXISTING CLASSES ONLY (`cg-route-name`, the name box's row). The stylesheet is
2446
+ not this ticket's file, and a lane stylesheet cannot override index.css anyway.
2447
+ β›” THE BUTTON HANDLERS TAKE NO EVENT ARGUMENT, deliberately, and this note may not
2448
+ spell the shape it is about either. `verify_map.py`'s `structural_scan` slices the
2449
+ FIRST arrow-with-an-event click handler in this file and reads it as the pin's, so
2450
+ any earlier handler declaring one - or any comment quoting that spelling - hands
2451
+ the R10 referee somebody else's body to judge. */}
2452
+ {routePinAsk && (
2453
+ <div className="cg-route-name" role="group" aria-label="Change this route's stops">
2454
+ <span className="cg-map-route-note">
2455
+ {routePinAsk.on
2456
+ ? `Take ${routePinAsk.title || `record ${routePinAsk.pid}`} off this route?`
2457
+ : `Add ${routePinAsk.title || `record ${routePinAsk.pid}`} to this route?`}
2458
+ </span>
2459
+ <span className="cg-route-name-actions">
2460
+ <button
2461
+ type="button"
2462
+ className="cg-btn cg-btn--primary"
2463
+ autoFocus
2464
+ onClick={applyRoutePin}
2465
+ title={
2466
+ routePinAsk.on
2467
+ ? "Drop this stop and renumber the rest of the route"
2468
+ : "Add this stop at the end of the route"
2469
+ }
2470
+ >
2471
+ {routePinAsk.on ? "Take off route" : "Add to route"}
2472
+ </button>
2473
+ <button
2474
+ type="button"
2475
+ className="cg-btn"
2476
+ onClick={() => setRoutePinAsk(null)}
2477
+ title="Leave the route as it is"
2478
+ >
2479
+ Cancel
2480
+ </button>
2481
+ </span>
2482
+ </div>
2483
+ )}
2484
+ {/* ══ W42-T24 (instruction 10, contract C6) β€” THE ROUTE NAVIGATION ═══════════════
2485
+ ⭐⭐ THE LISTING IS NOW A NAVIGATION, not a dropdown. Every route this account may
2486
+ see, mine and shared, each wearing the share mark when it is shared and carrying a
2487
+ menu that renames, duplicates, deletes and SHARES it; routes drag into folders and
2488
+ reorder; opening one is a single click and creating one is its own affordance.
2489
+ ⚠ IT SITS ABOVE THE PLANNER AND DOES NOT REPLACE IT. The panel now reads
2490
+ navigation first, then the planner that produces what the navigation lists.
2491
+ ⚠ THE `Saved route` SELECT BELOW IS DELIBERATELY LEFT IN PLACE. `verify_map.py`'s
2492
+ `saved-route-picker-is-unconditional` leg INDEXES the literal "Saved route" inside
2493
+ `.cg-map-route` and would raise rather than fail without it; it is also still the
2494
+ planner's own statement of which route is on screen. Removing it needs that leg
2495
+ re-anchored, which is not this ticket's file. */}
2496
+ <RouteNav
2497
+ routes={railRoutes}
2498
+ folders={routeFolders}
2499
+ openKey={openedRoute}
2500
+ busyKey={routeBusyKey}
2501
+ notice={railNotice}
2502
+ onOpenRoute={openSavedRoute}
2503
+ onCreateRoute={startNewRoute}
2504
+ onRenameRoute={renameRoute}
2505
+ onDuplicateRoute={duplicateRoute}
2506
+ onDeleteRoute={removeRoute}
2507
+ onShareRoute={shareRoute}
2508
+ onRouteReorder={reorderRail}
2509
+ onFolderReorder={reorderRouteFolders}
2510
+ onRouteMove={moveRoute}
2511
+ onFolderCreate={createRouteFolder}
2512
+ onFolderRename={renameRouteFolder}
2513
+ onFolderDelete={deleteRouteFolder}
2514
+ created={createdRoute}
2515
+ onCreatedDismiss={dismissCreated}
2516
+ />
2517
  <div className="cg-map-route">
2518
  {/* ══ OWNER, 2026-08-23 β€” CHOOSE WHICH SAVED ROUTE TO LOOK AT ══════════════════
2519
  Owner: *"when I click the Route navigation button. I should be able to choose any
 
2818
  <div className="cg-map-stoplist">
2819
  {plan.ordered.map((pt, i) => (
2820
  <span className="cg-map-stopitem" key={pt.pid}>
2821
+ {/* ⭐ W42-T21 β€” THE VISIT NUMBER IS TYPEABLE. It stays inside the same
2822
+ navy disc rather than becoming a box of its own, so the list reads as
2823
+ the same numbered stack it always did and the affordance is that the
2824
+ number takes a caret. The depot branch is untouched: a depot carries no
2825
+ visit number and so has nothing to type into. The inline rules are the
2826
+ input reset only (a text box's own chrome would draw a rectangle across
2827
+ the disc); every colour and size still comes from `.cg-map-stopn`. */}
2828
  <span className="cg-map-stopn">
2829
+ {pt.pid === DEPOT_PID ? "" : (
2830
+ <input
2831
+ type="text"
2832
+ inputMode="numeric"
2833
+ className="cg-map-stopnum"
2834
+ style={{
2835
+ width: "100%",
2836
+ height: "100%",
2837
+ padding: 0,
2838
+ border: 0,
2839
+ borderRadius: "50%",
2840
+ background: "transparent",
2841
+ color: "inherit",
2842
+ font: "inherit",
2843
+ textAlign: "center",
2844
+ }}
2845
+ value={
2846
+ stopPosDraft && stopPosDraft.pid === pt.pid
2847
+ ? stopPosDraft.text
2848
+ : String(i + 1 - (plan.depot ? 1 : 0))
2849
+ }
2850
+ aria-label={`Position of ${pt.title || `#${pt.pid}`} on the route`}
2851
+ title="Type a position to move this stop there"
2852
+ aria-invalid={stopPosError && stopPosError.pid === pt.pid ? true : undefined}
2853
+ aria-describedby={
2854
+ stopPosError && stopPosError.pid === pt.pid
2855
+ ? "cg-map-stoppos-error"
2856
+ : undefined
2857
+ }
2858
+ onFocus={(e) => e.currentTarget.select()}
2859
+ onChange={(e) => {
2860
+ setStopPosDraft({ pid: pt.pid, text: e.target.value });
2861
+ setStopPosError(null);
2862
+ }}
2863
+ onKeyDown={(e) => {
2864
+ if (e.key === "Enter") {
2865
+ e.preventDefault();
2866
+ commitStopPos(pt.pid, e.currentTarget.value);
2867
+ } else if (e.key === "Escape") {
2868
+ e.preventDefault();
2869
+ setStopPosDraft(null);
2870
+ setStopPosError(null);
2871
+ e.currentTarget.blur();
2872
+ }
2873
+ }}
2874
+ onBlur={(e) => {
2875
+ if (stopPosDraft && stopPosDraft.pid === pt.pid) {
2876
+ commitStopPos(pt.pid, e.target.value);
2877
+ }
2878
+ }}
2879
+ />
2880
+ )}
2881
  </span>
2882
  <span className="cg-map-stopname" title={pt.title || `#${pt.pid}`}>
2883
  {pt.title || `#${pt.pid}`}
 
2926
  </div>
2927
  )}
2928
 
2929
+ {/* ⭐ W42-T21 β€” THE REFUSAL, AND IT IS ON SCREEN RATHER THAN IN A REQUEST.
2930
+ It sits directly under the stop list so it is the next thing below the box that
2931
+ was typed into, is announced as an alert, and is what `aria-describedby` on
2932
+ that box points at. Nothing is sent while it is showing. */}
2933
+ {stopPosError && (
2934
+ <span
2935
+ id="cg-map-stoppos-error"
2936
+ role="alert"
2937
+ className="cg-map-route-note"
2938
+ style={{ color: "var(--lp-red-deep)" }}
2939
+ >
2940
+ {stopPosError.msg}
2941
+ </span>
2942
+ )}
2943
+
2944
  {/* β›” WAVE 41 / R13 β€” THE DISCARD-MY-ORDER BUTTON STOOD HERE AND IS NOT REPLACED
2945
  IN PLACE. Discarding the hand-picked sequence is half of `Update calculation`
2946
  in the foot row now, so a control offering only that half would put the panel
 
3199
  knew about. It needs shift too β€” alt alone still pans. */}
3200
  <span className="cg-map-hint">
3201
  Scroll to zoom Β· drag to pan Β· {lassoTool ? "shift-drag to lasso" : "shift-drag to select"}{" "}
3202
+ Β· shift-alt-drag to extend the selection Β·{" "}
3203
+ {/* W42-T49 β€” the SIGHTED half of the pin's disclosure, and it follows the mode for the
3204
+ same reason the aria-label does. Both wordings stay in the source, which is what
3205
+ `verify_map.py::pin-gesture-disclosed` reads. */}
3206
+ {routePanelOpen
3207
+ ? "click a pin to add it to the route or take it off"
3208
+ : "click a pin to open the record"}{" "}
3209
+ Β· shift-click a pin to add or remove it from the selection
3210
  </span>
3211
  </div>
3212
  <div
 
3363
  // hint bar above is the SIGHTED half of this same disclosure. It said "Click to
3364
  // select, double click to open." until R10 made that false.
3365
  // Policed by `verify_ui.py::pin_label_states_the_gesture`.
3366
+ // ⭐ W42-T49 β€” AND THE NAME FOLLOWS THE MODE, because the gesture does. With the
3367
+ // route open a plain click no longer opens anything, and an accessible name
3368
+ // still promising a record is the same class of lie R10 had to come back and
3369
+ // fix here. The modifier half is unchanged in every branch: shift-click works
3370
+ // the selection whatever the route is doing.
3371
+ aria-label={`${p.title || "Untitled record"}. ${
3372
+ routePanelOpen
3373
+ ? routeStopPids.has(p.pid)
3374
+ ? "Click to take this stop off the route, shift-click to select."
3375
+ : "Click to add this stop to the route, shift-click to select."
3376
+ : "Click to open, shift-click to select."
3377
+ }`}
3378
  onMouseEnter={() => setHoverPid(p.pid)}
3379
  onMouseLeave={() => setHoverPid((h) => (h === p.pid ? null : h))}
3380
  onFocus={() => setHoverPid(p.pid)}
 
3392
  pinSelect(p.pid, true);
3393
  return;
3394
  }
3395
+ // ⭐⭐ W42-T49 β€” WITH THE ROUTE NAVIGATION OPEN, A PIN IS A STOP.
3396
+ // The person has a day on screen and the thing they want after aiming at a
3397
+ // pin is that day changed, not a drawer over the map hiding it. So the click
3398
+ // asks, and the record detail is not opened: everything below this line is
3399
+ // skipped, including the rail fold, which exists only to make room for a
3400
+ // drawer that is not coming.
3401
+ // β›” THE BRANCH IS THE PROP AND NOTHING ELSE. `routePanelOpen` is
3402
+ // `CustomerGrid`'s own state for the route navigation, so with the route
3403
+ // closed this is not taken and the two lines below are today's behaviour,
3404
+ // reached by the same click on the same pin.
3405
+ if (routePanelOpen) {
3406
+ askRoutePin(p.pid, p.title);
3407
+ return;
3408
+ }
3409
  // ⭐⭐ W41-T48 (owner instruction 22) β€” OPENING A RECORD FOLDS THE RAIL, ON
3410
  // THE MAP EXACTLY AS IN THE GRID. `CustomerGrid.tsx::onCellClicked` raises
3411
  // this on every cell click; the map was the one surface that opened a record
 
3440
  onDoubleClick={(e) => {
3441
  if (movedRef.current) return;
3442
  e.preventDefault();
3443
+ // ⚠ W42-T49 β€” THIS IS A REPEAT OF THE PLAIN CLICK (see the note above), so it
3444
+ // repeats what the plain click just did. With the route open that was a
3445
+ // prompt, which is already on screen; opening the record here would let a
3446
+ // double click reach the drawer the single click deliberately did not.
3447
+ if (routePanelOpen) return;
3448
  onOpen(p.pid);
3449
  }}
3450
  onKeyDown={(e) => {
 
3456
  // disambiguate, so the guard the pointer needs would only be superstition.
3457
  if (e.key === "Enter") {
3458
  e.preventDefault();
3459
+ // W42-T49 β€” Enter is the plain click's mirror (see the note over the
3460
+ // keyboard block), so it mirrors the route mode too. A keyboard user who
3461
+ // cannot reach the prompt is a keyboard user who cannot work the route.
3462
+ if (routePanelOpen) {
3463
+ askRoutePin(p.pid, p.title);
3464
+ return;
3465
+ }
3466
  // W41-T48 β€” the keyboard mirror of the plain click, so it folds the rail
3467
  // for the same reason. ⚠ `!e.repeat` is this path's `e.detail <= 1`: a HELD
3468
  // Enter auto-repeats keydown for as long as the finger is down, and every
web/src/customer-grid/RecordDetail.tsx CHANGED
@@ -1569,7 +1569,7 @@ export default function RecordDetail({
1569
  <section className="cg-detail-section cg-detail-relsec">
1570
  <h3 className="cg-detail-sechead">
1571
  {relTargets.length === 0 ? (
1572
- <span>Relational</span>
1573
  ) : (
1574
  <button
1575
  type="button"
@@ -1577,7 +1577,7 @@ export default function RecordDetail({
1577
  aria-expanded={relOpen}
1578
  onClick={() => setRelOpen((open) => !open)}
1579
  >
1580
- Relational
1581
  </button>
1582
  )}
1583
  <span className="cg-detail-seccount">
 
1569
  <section className="cg-detail-section cg-detail-relsec">
1570
  <h3 className="cg-detail-sechead">
1571
  {relTargets.length === 0 ? (
1572
+ <span>Related</span>
1573
  ) : (
1574
  <button
1575
  type="button"
 
1577
  aria-expanded={relOpen}
1578
  onClick={() => setRelOpen((open) => !open)}
1579
  >
1580
+ Related
1581
  </button>
1582
  )}
1583
  <span className="cg-detail-seccount">
web/src/customer-grid/RouteNav.tsx ADDED
@@ -0,0 +1,763 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // customer-grid / RouteNav.tsx
3
+ // W42-T24 (owner instruction 10, contract C6) - THE ROUTE NAVIGATION.
4
+ //
5
+ // Before this file, the Route button opened a bare planner whose only listing was a plain
6
+ // `<select>`. A route could not be renamed, duplicated, deleted, shared or filed from the place
7
+ // it was listed, and a route somebody shared with you wore no mark at all.
8
+ //
9
+ // THIS IS `ViewSidebar.tsx`'s VOCABULARY, NOT A SECOND IMPLEMENTATION. Same row shape, the same
10
+ // `cg-view-row` / `cg-view-main` / `cg-view-more` class names, the same trigger in the same
11
+ // position, the same `AnchoredOverlay` menu surface, the same folder drag behaviour and the same
12
+ // empty-state voice. Interaction parity is the point of the ticket; resemblance is not enough.
13
+ //
14
+ // HOST NEUTRAL. Nothing under `customer-grid/**` may import `shell/**`, so the share dialog is
15
+ // reached the way `ColumnMenu.tsx` reaches it: a `window` CustomEvent named "aios:share-open",
16
+ // whose literal is deliberately re-spelled at each call site rather than imported across the
17
+ // boundary. This file raises no such event itself; it hands the decision up through
18
+ // `onShareRoute`, so the one dispatch lives beside the rest of the route doors in `MapView.tsx`.
19
+ //
20
+ // NO EXPAND / COLLAPSE MACHINERY. The views rail's disclosure chevron is being deleted (R12), so
21
+ // copying it here would ship a control on its way out. A folder shows its routes.
22
+ // ---------------------------------------------------------------------------
23
+
24
+ import { useCallback, useMemo, useState } from "react";
25
+ import type { DragEvent, ReactNode } from "react";
26
+ import { AnchoredOverlay } from "./OverlaySurface";
27
+ import type { AnchorRect } from "./OverlaySurface";
28
+ import { FolderMark, MenuLabel } from "./icons";
29
+ import { SHARE_SHAPE } from "./iconShapes";
30
+ import type { GridFolder } from "./types";
31
+ import {
32
+ ROOT_FOLDER_ID, folderNesting, groupByFolder, isSyntheticFolderId, mayNestFolder,
33
+ reorderFolderIds,
34
+ } from "./folders";
35
+
36
+ /**
37
+ * One route as `GET /customers/route-order` serves it (W42-T22 and W42-T23 grew every key below
38
+ * the first three).
39
+ *
40
+ * `shared` IS THE CLIENT'S MEANING ALREADY, AND IT MUST NOT BE RE-DERIVED.
41
+ * `_merge_shared_fields` stamps `shared: True` on every tenant-wide column, and every route is
42
+ * one of those, always. The route-order door answers the question `viewShareMark` asks instead,
43
+ * which is *granted to me*; re-computing it here from the field definition would put the mark on
44
+ * every route in the list.
45
+ */
46
+ export interface RouteNavRoute {
47
+ key: string;
48
+ label: string;
49
+ inputsHash?: string;
50
+ stops?: number;
51
+ solvedBy?: string | null;
52
+ mine: boolean;
53
+ owner?: string | null;
54
+ shared?: boolean;
55
+ sharedOut?: boolean;
56
+ hasShares?: boolean;
57
+ sharedRole?: string | null;
58
+ folderId?: string | null;
59
+ }
60
+
61
+ export interface RouteShareMark {
62
+ title: string;
63
+ ariaLabel: string;
64
+ }
65
+
66
+ /**
67
+ * CONTRACT C6 - DOES THIS ROUTE WEAR THE SHARE MARK, AND WHAT DOES IT SAY?
68
+ *
69
+ * A LINE-FOR-LINE MIRROR of `ViewSidebar.tsx::viewShareMark`, reading the same five keys in the
70
+ * same order: `hasShares`/`shared` (its line 198), `shared` + `owner` (199), `sharedRole` (203)
71
+ * and `sharedOut` (209). The route-order door spells them that way on purpose; a key spelled one
72
+ * letter differently is a navigation that lists routes, opens the share dialog, passes every gate
73
+ * and never draws the icon.
74
+ *
75
+ * THE COPY IS REWRITTEN, THE READING IS NOT. `viewShareMark` is exported and could have been
76
+ * called directly, but every sentence it returns says "view", so a route would have told its
77
+ * reader it was a view. The rule is shared; the noun is not.
78
+ */
79
+ export function routeShareMark(
80
+ route: Pick<
81
+ RouteNavRoute,
82
+ "shared" | "owner" | "sharedRole" | "label" | "hasShares" | "sharedOut"
83
+ >
84
+ ): RouteShareMark | null {
85
+ if (!route.hasShares && !route.shared) return null;
86
+ if (route.shared && route.owner) {
87
+ return {
88
+ title:
89
+ `Shared with you by ${route.owner}.` +
90
+ (route.sharedRole === "edit"
91
+ ? " You can edit it."
92
+ : " You can open it, not change it."),
93
+ ariaLabel: `${route.label}, shared with you by ${route.owner}`,
94
+ };
95
+ }
96
+ if (route.sharedOut) {
97
+ return {
98
+ title: "You shared this route. Anyone you gave access to can open it.",
99
+ ariaLabel: `${route.label}, shared by you`,
100
+ };
101
+ }
102
+ // `hasShares` and nothing beside it: this route has grants and the payload does not say whose
103
+ // or on what terms. Say only what is known.
104
+ return { title: "This route is shared.", ariaLabel: `${route.label}, shared` };
105
+ }
106
+
107
+ /**
108
+ * The share glyph, drawn from `SHARE_SHAPE` so a shared route, a shared view and a shared field
109
+ * are ONE mark. `ViewSidebar.tsx`'s own `ShareMark` is not exported and that file is not this
110
+ * ticket's to edit, so the geometry is taken from the module both of them already read rather
111
+ * than hand-copied.
112
+ */
113
+ function ShareMark({ size = 13 }: { size?: number }) {
114
+ return (
115
+ <svg width={size} height={size} viewBox="0 0 16 16" aria-hidden>
116
+ {SHARE_SHAPE.map((s) =>
117
+ s.fill ? (
118
+ <path key={s.d} d={s.d} fill="currentColor" />
119
+ ) : (
120
+ <path
121
+ key={s.d}
122
+ d={s.d}
123
+ fill="none"
124
+ stroke="currentColor"
125
+ strokeWidth={1.35}
126
+ strokeLinecap="round"
127
+ strokeLinejoin="round"
128
+ />
129
+ )
130
+ )}
131
+ </svg>
132
+ );
133
+ }
134
+
135
+ const ROUTE_DRAG_TYPE = "application/x-loopable-route";
136
+ const RFOLD_DRAG_TYPE = "application/x-loopable-routefolder";
137
+ const DOTS = "Β·Β·Β·";
138
+
139
+ export interface RouteNavProps {
140
+ /** Every route this account may see, `mine` or not, exactly as the door served them. */
141
+ routes: RouteNavRoute[];
142
+ /** This reader's own route folders, as the same listing carries them. */
143
+ folders: GridFolder[];
144
+ /** The route currently drawn on the map, so the rail can mark it active. */
145
+ openKey: string;
146
+ /** Which route the rail is waiting on a server answer for, or "" for none. */
147
+ busyKey: string;
148
+ /**
149
+ * A sentence the rail owes the reader, or "" for none.
150
+ *
151
+ * β›” IT RENDERS UNCONDITIONALLY, AND THAT IS THE WHOLE REASON IT EXISTS RATHER THAN REUSING THE
152
+ * PLANNER'S `saveErr`. Every message slot inside the planner below sits behind `plan &&`, so a
153
+ * refusal raised while there is no plan yet, which is exactly when Create is refused, would be
154
+ * written to a slot that is not on screen. A control whose refusal is invisible is a dead menu
155
+ * row (standing rule 1's second sentence: reported, never silent).
156
+ */
157
+ notice: string;
158
+ /** ONE CLICK OPENS A ROUTE. There is no second gesture and no confirm step. */
159
+ onOpenRoute: (key: string) => void;
160
+ /** CREATING IS A SEPARATE AFFORDANCE, never a row in the list of what exists. */
161
+ onCreateRoute: () => void;
162
+ onRenameRoute: (key: string, label: string) => void;
163
+ onDuplicateRoute: (key: string) => void;
164
+ onDeleteRoute: (key: string) => void;
165
+ /** Opens the SAME dialog a view or a field opens. The host owns the dispatch. */
166
+ onShareRoute: (key: string, label: string) => void;
167
+ /**
168
+ * REQUIRED, NOT OPTIONAL, AND THAT IS THE TICKET'S OWN INSTRUCTION. `ViewSidebar` learned this
169
+ * the expensive way: an optional reorder prop lets a caller mount the rail with dragging
170
+ * silently switched off, and every gate stays green because the component is correct and the
171
+ * handler simply never arrives. `onViewReorder` was made required in wave 27 for exactly this;
172
+ * its sibling `onFolderReorder?` is still optional there and is the shape being avoided here.
173
+ * Both reorder props below are required, so a mount that forgets one does not compile.
174
+ */
175
+ onRouteReorder: (order: string[]) => void;
176
+ onFolderReorder: (order: string[]) => void;
177
+ /** Drag a route into a folder, or out to the top level. */
178
+ onRouteMove: (key: string, folderId: string | null) => void;
179
+ onFolderCreate: (name: string, parent: string | null) => void;
180
+ onFolderRename: (folderId: string, name: string) => void;
181
+ onFolderDelete: (folderId: string) => void;
182
+ /**
183
+ * THE ROUTE THAT WAS JUST CREATED, so the rail can ASK whether to share it.
184
+ *
185
+ * A PROMPT, NOT A DEFAULT. The done-when is "prompts to share it or keep it private", and a
186
+ * route that opened the share dialog unasked would have made the choice for the person. Null
187
+ * whenever nothing was just made, which is almost always.
188
+ */
189
+ created: { key: string; label: string } | null;
190
+ onCreatedDismiss: () => void;
191
+ }
192
+
193
+ export function RouteNav({
194
+ routes,
195
+ folders,
196
+ openKey,
197
+ busyKey,
198
+ notice,
199
+ onOpenRoute,
200
+ onCreateRoute,
201
+ onRenameRoute,
202
+ onDuplicateRoute,
203
+ onDeleteRoute,
204
+ onShareRoute,
205
+ onRouteReorder,
206
+ onFolderReorder,
207
+ onRouteMove,
208
+ onFolderCreate,
209
+ onFolderRename,
210
+ onFolderDelete,
211
+ created,
212
+ onCreatedDismiss,
213
+ }: RouteNavProps) {
214
+ const [menu, setMenu] = useState<{ key: string; anchor: AnchorRect } | null>(null);
215
+ const [folderMenu, setFolderMenu] = useState<{ id: string; anchor: AnchorRect } | null>(null);
216
+ const [createMenu, setCreateMenu] = useState<AnchorRect | null>(null);
217
+ const [renamingKey, setRenamingKey] = useState("");
218
+ const [renamingFolder, setRenamingFolder] = useState("");
219
+ const [draft, setDraft] = useState("");
220
+ const [armedDelete, setArmedDelete] = useState("");
221
+ const [routeDrag, setRouteDrag] = useState("");
222
+ const [routeOver, setRouteOver] = useState("");
223
+ const [foldDrag, setFoldDrag] = useState("");
224
+ const [foldOver, setFoldOver] = useState("");
225
+
226
+ const nesting = useMemo(() => folderNesting(folders), [folders]);
227
+ const nestedFolders = nesting.ordered;
228
+
229
+ /**
230
+ * The rail's groups, depth first.
231
+ *
232
+ * `nesting.ordered` rather than `folders`, because `groupByFolder` emits one group per folder
233
+ * IN THE ORDER IT IS HANDED THEM. Passing the raw list would draw a child folder above its
234
+ * parent whenever the store happened to hold it that way.
235
+ * `folderIdOf` returns the payload value UNTOUCHED, including the difference between absent
236
+ * (never filed) and the reserved root id (deliberately dragged to the top level). Collapsing
237
+ * the two would send a route somebody shared with you out of the Shared group the first time
238
+ * you dragged it anywhere.
239
+ */
240
+ const groups = useMemo(
241
+ () =>
242
+ groupByFolder<RouteNavRoute>(
243
+ routes,
244
+ nestedFolders,
245
+ (r) => r.folderId ?? null,
246
+ (r) => !!r.shared && !!r.owner
247
+ ),
248
+ [routes, nestedFolders]
249
+ );
250
+
251
+ const closeMenus = useCallback(() => {
252
+ setMenu(null);
253
+ setFolderMenu(null);
254
+ setArmedDelete("");
255
+ }, []);
256
+
257
+ const reorderRoutes = useCallback(
258
+ (draggedKey: string, beforeKey: string | null) => {
259
+ const next = reorderFolderIds(routes.map((r) => r.key), draggedKey, beforeKey);
260
+ if (next) onRouteReorder(next);
261
+ },
262
+ [routes, onRouteReorder]
263
+ );
264
+
265
+ const reorderFolders = useCallback(
266
+ (draggedId: string, beforeId: string | null) => {
267
+ const next = reorderFolderIds(folders.map((f) => f.id), draggedId, beforeId);
268
+ if (next) onFolderReorder(next);
269
+ },
270
+ [folders, onFolderReorder]
271
+ );
272
+
273
+ const commitRename = useCallback(() => {
274
+ const name = draft.trim();
275
+ if (renamingKey && name) onRenameRoute(renamingKey, name);
276
+ setRenamingKey("");
277
+ setDraft("");
278
+ }, [draft, renamingKey, onRenameRoute]);
279
+
280
+ const commitFolderRename = useCallback(() => {
281
+ const name = draft.trim();
282
+ if (renamingFolder && name) onFolderRename(renamingFolder, name);
283
+ setRenamingFolder("");
284
+ setDraft("");
285
+ }, [draft, renamingFolder, onFolderRename]);
286
+
287
+ /**
288
+ * Drop handlers for one route row.
289
+ *
290
+ * `stopPropagation` IS LOAD-BEARING, and it is `ViewSidebar`'s reason verbatim: a route drag
291
+ * carries TWO payloads at once, the reorder channel and the plain-text filing channel, so a
292
+ * drop on a row inside a folder would otherwise reorder AND re-file in one gesture.
293
+ */
294
+ const rowDrop = (key: string) => ({
295
+ onDragOver: (e: DragEvent) => {
296
+ if (!e.dataTransfer.types.includes(ROUTE_DRAG_TYPE)) return;
297
+ e.preventDefault();
298
+ e.stopPropagation();
299
+ setRouteOver(key);
300
+ },
301
+ onDragLeave: () => setRouteOver(""),
302
+ onDrop: (e: DragEvent) => {
303
+ if (!e.dataTransfer.types.includes(ROUTE_DRAG_TYPE)) return;
304
+ e.preventDefault();
305
+ e.stopPropagation();
306
+ const dragged = e.dataTransfer.getData(ROUTE_DRAG_TYPE);
307
+ setRouteOver("");
308
+ setRouteDrag("");
309
+ if (dragged && dragged !== key) reorderRoutes(dragged, key);
310
+ },
311
+ });
312
+
313
+ const sectionDrop = (target: string | null) => ({
314
+ onDragOver: (e: DragEvent) => {
315
+ if (!e.dataTransfer.types.includes("text/plain")) return;
316
+ e.preventDefault();
317
+ setFoldOver(target ?? ROOT_FOLDER_ID);
318
+ },
319
+ onDragLeave: () => setFoldOver(""),
320
+ onDrop: (e: DragEvent) => {
321
+ e.preventDefault();
322
+ setFoldOver("");
323
+ const folded = e.dataTransfer.getData(RFOLD_DRAG_TYPE);
324
+ if (folded) {
325
+ setFoldDrag("");
326
+ if (target && folded !== target) reorderFolders(folded, target);
327
+ return;
328
+ }
329
+ const dragged = e.dataTransfer.getData("text/plain");
330
+ setRouteDrag("");
331
+ if (dragged) onRouteMove(dragged, target);
332
+ },
333
+ });
334
+
335
+ const menuRoute = menu ? routes.find((r) => r.key === menu.key) || null : null;
336
+ const folderRow = folderMenu ? folders.find((f) => f.id === folderMenu.id) || null : null;
337
+ const nestHere = folderRow
338
+ ? mayNestFolder(nesting, folderRow.id)
339
+ : { ok: true, reason: undefined as string | undefined };
340
+
341
+ const renderRoute = (route: RouteNavRoute): ReactNode => {
342
+ const mark = routeShareMark(route);
343
+ const active = route.key === openKey;
344
+ const renaming = renamingKey === route.key;
345
+ const stops = typeof route.stops === "number" ? route.stops : null;
346
+ const desc = [
347
+ stops === null ? "" : `${stops.toLocaleString()} ${stops === 1 ? "stop" : "stops"}`,
348
+ route.mine ? "" : route.solvedBy ? `planned by ${route.solvedBy}` : "planned by a colleague",
349
+ ]
350
+ .filter(Boolean)
351
+ .join(" Β· ");
352
+ return (
353
+ <div
354
+ key={route.key}
355
+ className={
356
+ "cg-view-row cg-route-row" +
357
+ (active ? " is-active" : "") +
358
+ (routeDrag === route.key ? " is-viewdrag" : "") +
359
+ (routeOver === route.key && routeDrag ? " is-drop-above" : "")
360
+ }
361
+ draggable={!renaming}
362
+ onDragStart={(e) => {
363
+ e.dataTransfer.setData(ROUTE_DRAG_TYPE, route.key);
364
+ e.dataTransfer.setData("text/plain", route.key);
365
+ e.dataTransfer.effectAllowed = "move";
366
+ setRouteDrag(route.key);
367
+ }}
368
+ onDragEnd={() => {
369
+ setRouteDrag("");
370
+ setRouteOver("");
371
+ }}
372
+ {...rowDrop(route.key)}
373
+ >
374
+ {renaming ? (
375
+ <input
376
+ className="cg-input cg-route-rename"
377
+ value={draft}
378
+ autoFocus
379
+ aria-label={`Rename ${route.label}`}
380
+ onChange={(e) => setDraft(e.target.value)}
381
+ onBlur={commitRename}
382
+ onKeyDown={(e) => {
383
+ if (e.key === "Enter") {
384
+ e.preventDefault();
385
+ commitRename();
386
+ }
387
+ if (e.key === "Escape") {
388
+ e.preventDefault();
389
+ setRenamingKey("");
390
+ }
391
+ }}
392
+ />
393
+ ) : (
394
+ <button
395
+ type="button"
396
+ className="cg-view-main"
397
+ title={route.label}
398
+ disabled={busyKey === route.key}
399
+ onClick={() => onOpenRoute(route.key)}
400
+ >
401
+ <span className="cg-view-text">
402
+ <span className="cg-view-name">{route.label}</span>
403
+ {desc ? <span className="cg-view-desc">{desc}</span> : null}
404
+ </span>
405
+ {mark ? (
406
+ <span
407
+ className="cg-view-shared"
408
+ role="img"
409
+ aria-label={mark.ariaLabel}
410
+ title={mark.title}
411
+ >
412
+ <ShareMark />
413
+ </span>
414
+ ) : null}
415
+ </button>
416
+ )}
417
+ <button
418
+ type="button"
419
+ className="cg-view-more"
420
+ aria-label={`Actions for ${route.label}`}
421
+ aria-haspopup="menu"
422
+ aria-expanded={menu?.key === route.key}
423
+ onClick={(e) => {
424
+ // THE ANCHOR IS HOISTED BEFORE THE UPDATER. `currentTarget` is null by the time a
425
+ // state updater runs, and reading it inside one is the white screen this rail's
426
+ // sibling already shipped once.
427
+ const anchor = e.currentTarget.getBoundingClientRect();
428
+ setFolderMenu(null);
429
+ setArmedDelete("");
430
+ setMenu((cur) => (cur && cur.key === route.key ? null : { key: route.key, anchor }));
431
+ }}
432
+ >
433
+ {DOTS}
434
+ </button>
435
+ </div>
436
+ );
437
+ };
438
+
439
+ return (
440
+ <nav className="cg-route-nav" aria-label="Route navigation">
441
+ <div className="cg-route-nav-head">
442
+ <span className="cg-views-title">Routes</span>
443
+ <button
444
+ type="button"
445
+ className="cg-link-btn cg-create-btn"
446
+ aria-haspopup="menu"
447
+ aria-expanded={!!createMenu}
448
+ onClick={(e) => {
449
+ const anchor = e.currentTarget.getBoundingClientRect();
450
+ closeMenus();
451
+ setCreateMenu((cur) => (cur ? null : anchor));
452
+ }}
453
+ >
454
+ <span className="cg-create-icon">+</span>
455
+ <span className="cg-create-label">{"Create new…"}</span>
456
+ </button>
457
+ </div>
458
+
459
+ {notice ? <span className="cg-route-nav-notice">{notice}</span> : null}
460
+
461
+ {/* CREATING PROMPTS TO SHARE, and the prompt is the whole of the done-when's third clause.
462
+ It offers the same two answers a new view is offered and routes the first one into the
463
+ SAME dialog a view or a field opens. */}
464
+ {created ? (
465
+ <div className="cg-route-share-prompt" role="status">
466
+ <span className="cg-route-share-line">
467
+ {`Saved ${created.label}. Only you can see it for now.`}
468
+ </span>
469
+ <span className="cg-form-actions">
470
+ <button
471
+ type="button"
472
+ className="cg-btn cg-btn-primary"
473
+ onClick={() => onShareRoute(created.key, created.label)}
474
+ >
475
+ Share route
476
+ </button>
477
+ <button type="button" className="cg-btn" onClick={() => onCreatedDismiss()}>
478
+ Keep private
479
+ </button>
480
+ </span>
481
+ </div>
482
+ ) : null}
483
+
484
+ <div className="cg-route-nav-list" {...sectionDrop(ROOT_FOLDER_ID)}>
485
+ {routes.length === 0 ? (
486
+ <div className="cg-fold-empty">
487
+ No routes yet. Plan one on the map, then save it to keep it here.
488
+ </div>
489
+ ) : null}
490
+ {groups.map((group) => {
491
+ if (!group.folder) {
492
+ return (
493
+ <div key={group.pinned ? "pinned" : "root"} className="cg-route-nav-root">
494
+ {group.items.map(renderRoute)}
495
+ </div>
496
+ );
497
+ }
498
+ const f = group.folder;
499
+ const synthetic = isSyntheticFolderId(f.id);
500
+ const depth = nesting.depth[f.id] || 1;
501
+ return (
502
+ <div key={f.id} className="cg-route-nav-group">
503
+ <div
504
+ className={
505
+ "cg-fold-head" +
506
+ (foldDrag === f.id ? " is-viewdrag" : "") +
507
+ (foldOver === f.id ? " is-drop-above" : "")
508
+ }
509
+ style={{ paddingLeft: 6 + (depth - 1) * 12 }}
510
+ draggable={!synthetic && renamingFolder !== f.id}
511
+ onDragStart={(e) => {
512
+ e.dataTransfer.setData(RFOLD_DRAG_TYPE, f.id);
513
+ e.dataTransfer.effectAllowed = "move";
514
+ setFoldDrag(f.id);
515
+ }}
516
+ onDragEnd={() => {
517
+ setFoldDrag("");
518
+ setFoldOver("");
519
+ }}
520
+ {...(synthetic ? {} : sectionDrop(f.id))}
521
+ >
522
+ <FolderMark icon={f.icon} size={16} />
523
+ {renamingFolder === f.id ? (
524
+ <input
525
+ className="cg-input cg-fold-rename"
526
+ value={draft}
527
+ autoFocus
528
+ aria-label={`Rename folder ${f.name}`}
529
+ onChange={(e) => setDraft(e.target.value)}
530
+ onBlur={commitFolderRename}
531
+ onKeyDown={(e) => {
532
+ if (e.key === "Enter") {
533
+ e.preventDefault();
534
+ commitFolderRename();
535
+ }
536
+ if (e.key === "Escape") {
537
+ e.preventDefault();
538
+ setRenamingFolder("");
539
+ }
540
+ }}
541
+ />
542
+ ) : (
543
+ <span className="cg-fold-name" title={f.name}>
544
+ {f.name}
545
+ </span>
546
+ )}
547
+ {synthetic ? null : (
548
+ <button
549
+ type="button"
550
+ className="cg-view-more"
551
+ aria-label={`Actions for folder ${f.name}`}
552
+ aria-haspopup="menu"
553
+ aria-expanded={folderMenu?.id === f.id}
554
+ onClick={(e) => {
555
+ const anchor = e.currentTarget.getBoundingClientRect();
556
+ setMenu(null);
557
+ setArmedDelete("");
558
+ setFolderMenu((cur) =>
559
+ cur && cur.id === f.id ? null : { id: f.id, anchor }
560
+ );
561
+ }}
562
+ >
563
+ {DOTS}
564
+ </button>
565
+ )}
566
+ </div>
567
+ {group.items.length === 0 ? (
568
+ <div className="cg-fold-empty">Empty. Drag a route here.</div>
569
+ ) : (
570
+ group.items.map(renderRoute)
571
+ )}
572
+ </div>
573
+ );
574
+ })}
575
+ </div>
576
+
577
+ {menu && menuRoute ? (
578
+ <AnchoredOverlay
579
+ anchor={menu.anchor}
580
+ className="cg-view-menu cg-route-menu"
581
+ placement="bottom-end"
582
+ role="menu"
583
+ ariaLabel={`Actions for ${menuRoute.label}`}
584
+ onDismiss={closeMenus}
585
+ dataKind="route-menu"
586
+ >
587
+ <button
588
+ type="button"
589
+ role="menuitem"
590
+ className="cg-menu-item"
591
+ disabled={!menuRoute.mine}
592
+ title={
593
+ menuRoute.mine ? undefined : "Only the person who planned this route can rename it."
594
+ }
595
+ onClick={() => {
596
+ setDraft(menuRoute.label);
597
+ setRenamingKey(menuRoute.key);
598
+ closeMenus();
599
+ }}
600
+ >
601
+ <MenuLabel icon="rename" text="Rename" />
602
+ </button>
603
+ <button
604
+ type="button"
605
+ role="menuitem"
606
+ className="cg-menu-item"
607
+ onClick={() => {
608
+ onDuplicateRoute(menuRoute.key);
609
+ closeMenus();
610
+ }}
611
+ >
612
+ <MenuLabel icon="duplicate" text="Duplicate" />
613
+ </button>
614
+ <button
615
+ type="button"
616
+ role="menuitem"
617
+ className="cg-menu-item"
618
+ onClick={() => {
619
+ onShareRoute(menuRoute.key, menuRoute.label);
620
+ closeMenus();
621
+ }}
622
+ >
623
+ <MenuLabel icon={<ShareMark size={16} />} text="Share route" />
624
+ </button>
625
+ <div className="cg-menu-sep" />
626
+ <button
627
+ type="button"
628
+ role="menuitem"
629
+ className={
630
+ "cg-menu-item cg-menu-item--danger is-danger" +
631
+ (armedDelete === menuRoute.key ? " is-armed" : "")
632
+ }
633
+ disabled={!menuRoute.mine}
634
+ title={
635
+ menuRoute.mine ? undefined : "Only the person who planned this route can delete it."
636
+ }
637
+ onClick={() => {
638
+ if (armedDelete !== menuRoute.key) {
639
+ setArmedDelete(menuRoute.key);
640
+ return;
641
+ }
642
+ onDeleteRoute(menuRoute.key);
643
+ closeMenus();
644
+ }}
645
+ >
646
+ <MenuLabel
647
+ icon="trash"
648
+ text={
649
+ armedDelete === menuRoute.key
650
+ ? "Delete route? The visit numbers go with it."
651
+ : "Delete route"
652
+ }
653
+ />
654
+ </button>
655
+ </AnchoredOverlay>
656
+ ) : null}
657
+
658
+ {folderMenu && folderRow ? (
659
+ <AnchoredOverlay
660
+ anchor={folderMenu.anchor}
661
+ className="cg-view-menu cg-route-menu"
662
+ placement="bottom-end"
663
+ role="menu"
664
+ ariaLabel={`Actions for folder ${folderRow.name}`}
665
+ onDismiss={closeMenus}
666
+ dataKind="route-folder-menu"
667
+ >
668
+ <button
669
+ type="button"
670
+ role="menuitem"
671
+ className="cg-menu-item"
672
+ disabled={!nestHere.ok}
673
+ title={nestHere.ok ? undefined : nestHere.reason}
674
+ onClick={() => {
675
+ onFolderCreate("New folder", folderRow.id);
676
+ closeMenus();
677
+ }}
678
+ >
679
+ <MenuLabel icon={<FolderMark size={16} />} text="New folder inside" />
680
+ </button>
681
+ <button
682
+ type="button"
683
+ role="menuitem"
684
+ className="cg-menu-item"
685
+ onClick={() => {
686
+ setDraft(folderRow.name);
687
+ setRenamingFolder(folderRow.id);
688
+ closeMenus();
689
+ }}
690
+ >
691
+ <MenuLabel icon="rename" text="Rename" />
692
+ </button>
693
+ <div className="cg-menu-sep" />
694
+ <button
695
+ type="button"
696
+ role="menuitem"
697
+ className={
698
+ "cg-menu-item cg-menu-item--danger is-danger" +
699
+ (armedDelete === folderRow.id ? " is-armed" : "")
700
+ }
701
+ onClick={() => {
702
+ if (armedDelete !== folderRow.id) {
703
+ setArmedDelete(folderRow.id);
704
+ return;
705
+ }
706
+ onFolderDelete(folderRow.id);
707
+ closeMenus();
708
+ }}
709
+ >
710
+ <MenuLabel
711
+ icon="trash"
712
+ text={
713
+ armedDelete === folderRow.id
714
+ ? "Delete folder? Its routes move to the top level."
715
+ : "Delete folder"
716
+ }
717
+ />
718
+ </button>
719
+ </AnchoredOverlay>
720
+ ) : null}
721
+
722
+ {createMenu ? (
723
+ <AnchoredOverlay
724
+ anchor={createMenu}
725
+ className="cg-view-menu cg-create-flyout cg-route-create"
726
+ placement="bottom-start"
727
+ role="menu"
728
+ ariaLabel="Create"
729
+ onDismiss={() => setCreateMenu(null)}
730
+ dataKind="route-create-new"
731
+ >
732
+ <button
733
+ type="button"
734
+ role="menuitem"
735
+ className="cg-menu-item cg-create-row"
736
+ onClick={() => {
737
+ onFolderCreate("New folder", null);
738
+ setCreateMenu(null);
739
+ }}
740
+ >
741
+ <MenuLabel icon={<FolderMark size={16} />} text="Folder" />
742
+ </button>
743
+ <div className="cg-menu-sep" />
744
+ <button
745
+ type="button"
746
+ role="menuitem"
747
+ className="cg-menu-item cg-create-row"
748
+ onClick={() => {
749
+ onCreateRoute();
750
+ setCreateMenu(null);
751
+ }}
752
+ >
753
+ <MenuLabel icon="addEnd" text="Route" />
754
+ </button>
755
+ <p className="cg-create-note">
756
+ A route starts private. After you save it you are asked whether to share it, and you
757
+ can change that later from Share route.
758
+ </p>
759
+ </AnchoredOverlay>
760
+ ) : null}
761
+ </nav>
762
+ );
763
+ }
web/src/customer-grid/SwipeView.tsx CHANGED
@@ -1,586 +1,586 @@
1
- // ---------------------------------------------------------------------------
2
- // customer-grid / SwipeView.tsx
3
- // ⭐ WAVE-27 item 8 (owner ruling R2, contract C3) β€” the SWIPE deck.
4
- //
5
- // One record at a time, decided left or right into two options of ONE
6
- // single-select. R2 fixes the shape and it is narrow on purpose:
7
- // Β· SINGLE-SELECT ONLY, one field, two of its options. No checkbox binding.
8
- // Β· the deck holds only the records whose bound field is EMPTY β€” a record
9
- // that already has a value has been decided, and re-asking is not triage.
10
- // Β· a swipe writes through the NORMAL cell door (`onSwipe`, which the host
11
- // maps to the same `patchAndRecord` a kanban card move uses), so undo,
12
- // echo-suppression and the permission wall all hold without being
13
- // re-implemented here.
14
- //
15
- // Honesty rules carried from the other modes:
16
- // Β· nothing is silently hidden β€” the deck states what is left, and the
17
- // empty state names the bound field rather than saying "all done".
18
- // Β· a lost binding is SHOWN, never repaired by guessing. `_clean_display`
19
- // validates that `fieldKey` names a field the table HAS and stops there;
20
- // it cannot know the field is still a select, or that the two options are
21
- // still in its vocabulary (its docstring draws that line explicitly). So
22
- // those three losses land here, and each one says what happened and
23
- // re-opens the picker β€” the `viewModes.tsx:190-194` rule, which exists
24
- // because the wave-7 trap was a picker silently falling back to its first
25
- // option.
26
- // ---------------------------------------------------------------------------
27
-
28
- import { useCallback, useEffect, useMemo, useRef, useState } from "react";
29
- // ⭐⭐ W41-T48 (owner instruction 22) β€” opening a record from the swipe deck folds the shell's
30
- // navigation rail exactly as a grid cell click does. Guard rationale: `MapView.tsx:2755`.
31
- import { NAV_MINIMIZE_EVENT, signal } from "../apiContract";
32
- import { choiceOptions } from "./types";
33
- import type { CustomerDoc, DisplaySpec, Field, Row, Viewer } from "./types";
34
- // ⚠ `SurfaceScope` is `apiBridge`'s (a TYPE-only import, so nothing of that module is
35
- // loaded here) β€” the same import `RecordComments` takes for the same prop.
36
- import type { SurfaceScope } from "./apiBridge";
37
- import RecordComments from "./RecordComments";
38
- import { Documents } from "./Documents";
39
- import { formatDisplay } from "./cells";
40
- import { actionHref } from "./display";
41
- import { optionTint } from "./choiceColors";
42
- import { ModeIcon } from "./icons";
43
- // ⭐ W29-T73 β€” the line its three siblings all have, and the one this file shipped without.
44
- // `SwipeView.css` had ZERO references anywhere in `src/`, so T26's two new sections rendered
45
- // unstyled while `.cg-swipe-card` (which lives in `index.css`) kept the card looking right β€”
46
- // a partially-styled surface reads as a design choice, which is why nobody reported it and no
47
- // gate could see it: a side-effect import references no symbol ([[artifact-with-no-importer]]).
48
- import "./SwipeView.css";
49
-
50
- export type SwipeSpec = NonNullable<DisplaySpec["swipe"]>;
51
-
52
- /** The three ways a stored binding can rot that the host cannot see (see the header note). */
53
- type BindingFault =
54
- | { kind: "unbound" }
55
- | { kind: "field-gone"; fieldKey: string }
56
- | { kind: "not-select"; field: Field }
57
- | { kind: "option-gone"; field: Field; missing: string[] };
58
-
59
- function readBinding(spec: SwipeSpec | undefined, fieldByKey: Map<string, Field>):
60
- { ok: true; field: Field; spec: SwipeSpec } | { ok: false; fault: BindingFault } {
61
- if (!spec) return { ok: false, fault: { kind: "unbound" } };
62
- const field = fieldByKey.get(spec.fieldKey);
63
- if (!field) return { ok: false, fault: { kind: "field-gone", fieldKey: spec.fieldKey } };
64
- // R2 β€” SINGLE-select only. `multiselect` is deliberately not accepted: its cell holds a SET,
65
- // so "write this option" would mean append-or-replace, and a triage gesture that sometimes
66
- // adds and sometimes overwrites is two gestures wearing one button.
67
- if (field.type !== "select") return { ok: false, fault: { kind: "not-select", field } };
68
- const options = choiceOptions(field);
69
- const has = new Set(options.map((o) => o.toLowerCase()));
70
- const missing = [spec.leftOption, spec.rightOption].filter((o) => !has.has(o.toLowerCase()));
71
- if (missing.length) return { ok: false, fault: { kind: "option-gone", field, missing } };
72
- return { ok: true, field, spec };
73
- }
74
-
75
- /** The bound cell is EMPTY β€” the one predicate that decides deck membership (R2). */
76
- const isUndecided = (row: Row, key: string): boolean =>
77
- String(row[key] ?? "").trim() === "";
78
-
79
- export function SwipeView({
80
- rows,
81
- fields,
82
- fieldByKey,
83
- spec,
84
- cardKeys,
85
- detailKeys,
86
- scope,
87
- viewer,
88
- docs,
89
- docPayload,
90
- onDocAdd,
91
- onDocFetch,
92
- onDocDelete,
93
- titleKey,
94
- canWrite,
95
- readOnlyReason,
96
- canBind,
97
- onSpec,
98
- onSwipe,
99
- onOpen,
100
- }: {
101
- /** DISTINCT data rows from the full pipeline, overlay edits layered β€” the kanban's contract.
102
- * The deck re-derives from these, so a written record leaves it as soon as the optimistic
103
- * patch lands; there is no local cursor to drift out of step with the data. */
104
- rows: Row[];
105
- /** Every field, for the picker's field list. */
106
- fields: Field[];
107
- fieldByKey: Map<string, Field>;
108
- /** The stored binding, or undefined for a deck nobody has configured yet. */
109
- spec: SwipeSpec | undefined;
110
- /** The handful of visible fields the card lists under its title. */
111
- cardKeys: string[];
112
- titleKey: string;
113
- /** May this viewer write the BOUND field's value? (the kanban's `canMove`) */
114
- canWrite: boolean;
115
- /** Stated when the deck cannot be decided β€” permissions, or a computed column. */
116
- readOnlyReason: string | null;
117
- /** May this viewer change what the deck is bound TO? A VIEW-config act, so it is the
118
- * view-editing permission and NOT `canWrite` β€” conflating the two is
119
- * [[schema-role-is-not-a-value-wall]]. REQUIRED, because a picker that silently does
120
- * nothing is worse than no picker ([[wrong-parent-not-broken-control]]). */
121
- canBind: boolean;
122
- /** `undefined` DELETES the binding β€” absent is the honest unconfigured state, and storing a
123
- * half-binding is what `cleanDisplay` drops on both engines (the `kanbanClamp` law). */
124
- onSpec: (next: SwipeSpec | undefined) => void;
125
- onSwipe: (pid: number, value: string) => void;
126
- onOpen: (pid: number) => void;
127
- /**
128
- * ⭐⭐ WAVE-29 T26 (owner R9) β€” WHAT MAKES THE CARD A RECORD RATHER THAN A SUMMARY.
129
- *
130
- * R9: *"the swipe CARD itself renders the record detail inline β€” fields, comments and
131
- * attachments β€” so a reviewer decides without leaving the deck."* Everything below is that,
132
- * and every one of them is OPTIONAL for one reason: this deck runs on hosts that supply
133
- * different amounts. A card must render with none of them rather than throw β€” the standalone
134
- * embed has no `scope`, and a deployment with no document storage serves no handlers.
135
- */
136
- /** Every field the VIEW shows, in its order β€” not the three-key card summary. */
137
- detailKeys?: string[];
138
- /** The surface these records live on. Comments are keyed by it; absent β‡’ no comments section,
139
- * which is the pre-existing precondition `RecordDetail` already carries. */
140
- scope?: SurfaceScope;
141
- viewer?: Viewer;
142
- /** This record's attachments, and the plumbing. Handlers absent β‡’ the section is not rendered
143
- * at all, exactly as `RecordDetail` decides it (a dead upload control is a promise the app
144
- * cannot keep). */
145
- /** Keyed by pid, because a deck shows many records β€” `RecordDetail` takes ONE record's list
146
- * and that shape cannot serve a deck. */
147
- docs?: Record<string, CustomerDoc[]>;
148
- docPayload?: { pid: number; docId: string; name: string; mime: string; data_b64: string };
149
- /** ⚠ EVERY HANDLER TAKES THE PID, unlike `RecordDetail`'s, whose host closes over the ONE
150
- * open record. A deck paints many records at once, so a handler bound to a single pid would
151
- * attach every reviewer's upload to whichever card happened to be open. */
152
- onDocAdd?: (
153
- pid: number,
154
- file: { name: string; mime: string; size: number; data_b64: string }
155
- ) => void;
156
- onDocFetch?: (pid: number, docId: string) => void;
157
- onDocDelete?: (pid: number, docId: string) => void;
158
- }) {
159
- // "Later" β€” session-only, never stored. A deck with no way past a record you cannot decide
160
- // blocks on that record forever, so this is navigation WITHIN the deck rather than a third
161
- // gesture: it writes nothing, survives no reload, and the count is disclosed in the empty
162
- // state rather than quietly shrinking the deck (rule 8b).
163
- const [later, setLater] = useState<Set<number>>(new Set());
164
- const deckRef = useRef<HTMLDivElement>(null);
165
-
166
- const binding = useMemo(() => readBinding(spec, fieldByKey), [spec, fieldByKey]);
167
- const boundKey = binding.ok ? binding.field.key : null;
168
-
169
- const undecided = useMemo(
170
- () => (boundKey ? rows.filter((r) => isUndecided(r, boundKey)) : []),
171
- [rows, boundKey]
172
- );
173
- const deck = useMemo(() => undecided.filter((r) => !later.has(r.pid)), [undecided, later]);
174
- const card = deck[0];
175
-
176
- // A record decided elsewhere (the grid, another user's echo) must not stay "later" forever β€”
177
- // otherwise the disclosed skip count drifts away from what is actually on the deck.
178
- useEffect(() => {
179
- setLater((prev) => {
180
- if (prev.size === 0) return prev;
181
- const live = new Set(undecided.map((r) => r.pid));
182
- const next = new Set([...prev].filter((pid) => live.has(pid)));
183
- return next.size === prev.size ? prev : next;
184
- });
185
- }, [undecided]);
186
-
187
- const decide = useCallback(
188
- (value: string) => {
189
- if (!card || !canWrite) return;
190
- onSwipe(card.pid, value);
191
- },
192
- [card, canWrite, onSwipe]
193
- );
194
-
195
- // οΏ½οΏ½ / β†’ decide, and they are the SAME two actions the buttons are rather than a second code
196
- // path: the whole point of the mode is that one hand can clear a queue.
197
- useEffect(() => {
198
- if (!binding.ok || !canWrite || !card) return;
199
- const onKey = (e: KeyboardEvent) => {
200
- if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
201
- const el = document.activeElement as HTMLElement | null;
202
- // Never steal an arrow key from a text field or a native control the user is inside.
203
- if (el && (el.tagName === "INPUT" || el.tagName === "SELECT" || el.tagName === "TEXTAREA"))
204
- return;
205
- if (!deckRef.current?.contains(el ?? null) && el !== document.body) return;
206
- e.preventDefault();
207
- decide(e.key === "ArrowLeft" ? binding.spec.leftOption : binding.spec.rightOption);
208
- };
209
- window.addEventListener("keydown", onKey);
210
- return () => window.removeEventListener("keydown", onKey);
211
- }, [binding, canWrite, card, decide]);
212
-
213
- if (!binding.ok) {
214
- return (
215
- <div className="cg-swipe" ref={deckRef}>
216
- <SwipeBinder
217
- fault={binding.fault}
218
- fields={fields}
219
- fieldByKey={fieldByKey}
220
- spec={spec}
221
- canBind={canBind}
222
- onSpec={onSpec}
223
- />
224
- </div>
225
- );
226
- }
227
-
228
- const { field } = binding;
229
- const leftTint = optionTint(field, binding.spec.leftOption);
230
- const rightTint = optionTint(field, binding.spec.rightOption);
231
-
232
- return (
233
- <div className="cg-swipe" ref={deckRef} tabIndex={-1}>
234
- <div className="cg-swipe-bar">
235
- <span className="cg-swipe-bound">
236
- <ModeIcon mode="swipe" />
237
- Sorting into <strong>{field.label}</strong>
238
- </span>
239
- <span className="cg-swipe-left">
240
- {deck.length.toLocaleString()} {deck.length === 1 ? "record" : "records"} to sort
241
- </span>
242
- {canBind && (
243
- <button
244
- type="button"
245
- className="cg-link-btn"
246
- onClick={() => onSpec(undefined)}
247
- title="Choose a different field or different options for this deck"
248
- >
249
- Change
250
- </button>
251
- )}
252
- </div>
253
- {readOnlyReason && <div className="cg-kb-note">{readOnlyReason}</div>}
254
- {card ? (
255
- <div className="cg-swipe-deck">
256
- <button
257
- type="button"
258
- className="cg-swipe-side cg-swipe-side--left"
259
- disabled={!canWrite}
260
- style={leftTint ? { background: leftTint.bg, color: leftTint.fg } : undefined}
261
- onClick={() => decide(binding.spec.leftOption)}
262
- title={`Set ${field.label} to ${binding.spec.leftOption} (left arrow key)`}
263
- >
264
- <span aria-hidden className="cg-swipe-arrow">
265
- <svg width="16" height="16" viewBox="0 0 16 16">
266
- <path
267
- d="M11 3.2 6.2 8l4.8 4.8"
268
- fill="none"
269
- stroke="currentColor"
270
- strokeWidth="1.6"
271
- strokeLinecap="round"
272
- strokeLinejoin="round"
273
- />
274
- </svg>
275
- </span>
276
- {binding.spec.leftOption}
277
- </button>
278
- <article
279
- className="cg-swipe-card"
280
- role="button"
281
- tabIndex={0}
282
- onClick={(e) => {
283
- // ⭐ W41-T48 β€” the card IS the deck's record open, so it folds the rail.
284
- // ⚠ Nothing that is NOT an open can reach this line: every control inside the
285
- // card (a url cell, the comments box, the document tray) already stops its own
286
- // click, and the left/right decision buttons are siblings of the card, not
287
- // children of it. The deck also has no pointer drag to disambiguate β€” its swipe
288
- // is the two buttons and the arrow keys, neither of which opens anything.
289
- // ⚠ `<article role="button">`, not a native button, so a keyboard activation
290
- // never arrives here as a synthetic click; the keydown path below is the whole
291
- // keyboard story and the two cannot both fire for one gesture.
292
- if (e.detail <= 1) signal(NAV_MINIMIZE_EVENT);
293
- onOpen(card.pid);
294
- }}
295
- onKeyDown={(e) => {
296
- if (e.key !== "Enter" && e.key !== " ") return;
297
- e.preventDefault();
298
- // W41-T48 β€” `!e.repeat` is this path's `e.detail <= 1`: a HELD Enter or Space
299
- // auto-repeats keydown, and every one of those repeats is the SAME gesture.
300
- if (!e.repeat) signal(NAV_MINIMIZE_EVENT);
301
- onOpen(card.pid);
302
- }}
303
- >
304
- <h3 className="cg-swipe-title">{String(card[titleKey] ?? "")}</h3>
305
- <div className="cg-swipe-cells">
306
- {/* ⭐ WAVE-29 T26 (R9) β€” the RECORD's visible fields, not the three-key summary the
307
- kanban card lends. `detailKeys` falls back to `cardKeys` so a host that has not
308
- been widened yet renders exactly what it rendered before. */}
309
- {(detailKeys && detailKeys.length ? detailKeys : cardKeys).map((k) => {
310
- const f = fieldByKey.get(k);
311
- if (!f) return null;
312
- const text = formatDisplay(f, card[k]);
313
- if (!text) return null;
314
- // A url cell is a LINK here too (wave-26 item 11), through `display.ts`'s one
315
- // scheme guard β€” and every gesture that reaches it must be stopped from also
316
- // reaching the card, which is a button (the kanban card's note, same trap).
317
- const href = actionHref(f, card[k]);
318
- return (
319
- <div key={k} className="cg-swipe-cell">
320
- <span className="cg-lv-k">{f.label}</span>
321
- {href ? (
322
- <a
323
- className="cg-lv-v"
324
- href={href}
325
- target="_blank"
326
- rel="noopener noreferrer"
327
- title={text}
328
- onClick={(e) => e.stopPropagation()}
329
- onKeyDown={(e) => e.stopPropagation()}
330
- >
331
- {text}
332
- </a>
333
- ) : (
334
- <span className="cg-lv-v">{text}</span>
335
- )}
336
- </div>
337
- );
338
- })}
339
- </div>
340
- {/* ⭐ R9's other two thirds. Both stop their own events: the card is a `role="button"`
341
- that opens the record, and a click on a comment box or an upload control must not
342
- also open the modal it exists to make unnecessary (the kanban card's link trap,
343
- one surface over). */}
344
- {onDocAdd && onDocFetch && onDocDelete && (
345
- <div
346
- className="cg-swipe-docs"
347
- onClick={(e) => e.stopPropagation()}
348
- onKeyDown={(e) => e.stopPropagation()}
349
- role="presentation"
350
- >
351
- <Documents
352
- pid={Number(card.pid)}
353
- docs={docs?.[String(card.pid)] ?? []}
354
- docPayload={docPayload}
355
- onAdd={(file) => onDocAdd(card.pid, file)}
356
- onFetch={(docId) => onDocFetch(card.pid, docId)}
357
- onDelete={(docId) => onDocDelete(card.pid, docId)}
358
- />
359
- </div>
360
- )}
361
- {scope != null && (
362
- <div
363
- className="cg-swipe-comments"
364
- onClick={(e) => e.stopPropagation()}
365
- onKeyDown={(e) => e.stopPropagation()}
366
- role="presentation"
367
- >
368
- {/* ⚠ KEYED ON scope+pid, the same key `RecordDetail` uses: without it React
369
- reuses the mounted instance across a card change and paints one record's
370
- comments under another's name until the fetch returns. */}
371
- <RecordComments
372
- key={`${scope}:${Number(card.pid)}`}
373
- scope={scope}
374
- pid={Number(card.pid)}
375
- viewer={viewer}
376
- />
377
- </div>
378
- )}
379
- {canWrite && (
380
- <button
381
- type="button"
382
- className="cg-link-btn cg-swipe-later"
383
- onClick={(e) => {
384
- e.stopPropagation();
385
- setLater((prev) => new Set(prev).add(card.pid));
386
- }}
387
- >
388
- Decide later
389
- </button>
390
- )}
391
- </article>
392
- <button
393
- type="button"
394
- className="cg-swipe-side cg-swipe-side--right"
395
- disabled={!canWrite}
396
- style={rightTint ? { background: rightTint.bg, color: rightTint.fg } : undefined}
397
- onClick={() => decide(binding.spec.rightOption)}
398
- title={`Set ${field.label} to ${binding.spec.rightOption} (right arrow key)`}
399
- >
400
- {binding.spec.rightOption}
401
- <span aria-hidden className="cg-swipe-arrow">
402
- <svg width="16" height="16" viewBox="0 0 16 16">
403
- <path
404
- d="M5 3.2 9.8 8 5 12.8"
405
- fill="none"
406
- stroke="currentColor"
407
- strokeWidth="1.6"
408
- strokeLinecap="round"
409
- strokeLinejoin="round"
410
- />
411
- </svg>
412
- </span>
413
- </button>
414
- </div>
415
- ) : (
416
- // The empty state NAMES the bound field (C3), because "nothing to sort" is ambiguous
417
- // between "the deck is finished" and "the filter hid everything", and the two want
418
- // different next actions. `later` is disclosed rather than quietly subtracted.
419
- <div className="cg-mode-empty cg-swipe-empty">
420
- {later.size > 0 ? (
421
- <>
422
- <p>
423
- {later.size.toLocaleString()}{" "}
424
- {later.size === 1 ? "record is" : "records are"} set aside for later. Nothing else
425
- in this view is missing a <strong>{field.label}</strong>.
426
- </p>
427
- <button type="button" className="cg-btn" onClick={() => setLater(new Set())}>
428
- Bring them back
429
- </button>
430
- </>
431
- ) : (
432
- <p>
433
- Every record in this view already has a <strong>{field.label}</strong>. Widen the
434
- view's filters to sort more.
435
- </p>
436
- )}
437
- </div>
438
- )}
439
- </div>
440
- );
441
- }
442
-
443
- /**
444
- * The binding picker: field + two options. It is also the surface every LOST binding lands on,
445
- * with the loss stated above it β€” one place that answers "what is this deck for", rather than an
446
- * error screen beside a separate setup screen.
447
- */
448
- function SwipeBinder({
449
- fault,
450
- fields,
451
- fieldByKey,
452
- spec,
453
- canBind,
454
- onSpec,
455
- }: {
456
- fault: BindingFault;
457
- fields: Field[];
458
- fieldByKey: Map<string, Field>;
459
- spec: SwipeSpec | undefined;
460
- canBind: boolean;
461
- onSpec: (next: SwipeSpec | undefined) => void;
462
- }) {
463
- const selects = useMemo(
464
- () => fields.filter((f) => f.type === "select" && choiceOptions(f).length >= 2),
465
- [fields]
466
- );
467
- const [fieldKey, setFieldKey] = useState<string>(() => {
468
- if (spec && fieldByKey.get(spec.fieldKey)?.type === "select") return spec.fieldKey;
469
- return selects[0]?.key ?? "";
470
- });
471
- const chosen = fieldByKey.get(fieldKey);
472
- const options = useMemo(() => (chosen ? choiceOptions(chosen) : []), [chosen]);
473
- const [left, setLeft] = useState<string>("");
474
- const [right, setRight] = useState<string>("");
475
-
476
- // The two option selects follow the FIELD. Kept in an effect rather than derived so the user's
477
- // pick survives re-renders, and reset whenever the field changes β€” carrying an option from the
478
- // previous field would offer a value the new field cannot hold.
479
- useEffect(() => {
480
- setLeft(options[0] ?? "");
481
- setRight(options.find((o) => o !== options[0]) ?? "");
482
- }, [options]);
483
-
484
- const message = ((): string => {
485
- switch (fault.kind) {
486
- case "field-gone":
487
- return "The field this deck sorted into has been deleted. Pick another one.";
488
- case "not-select":
489
- return `β€œ${fault.field.label}” is no longer a single-select, so it has no options to`
490
- + " sort into. Pick another field.";
491
- case "option-gone":
492
- return `${fault.missing.map((m) => `β€œ${m}”`).join(" and ")} ${
493
- fault.missing.length === 1 ? "is" : "are"
494
- } no longer ${fault.missing.length === 1 ? "an option" : "options"} on β€œ${
495
- fault.field.label
496
- }”. Pick the sides again.`;
497
- default:
498
- return "Sort records one at a time into two options of a single-select field.";
499
- }
500
- })();
501
-
502
- if (!canBind) {
503
- return (
504
- <div className="cg-mode-empty">
505
- <p>{message}</p>
506
- <p>Its creator or an admin can set this view up.</p>
507
- </div>
508
- );
509
- }
510
- if (selects.length === 0) {
511
- // Honest and specific: the mode is not broken, the TABLE has nothing to bind to. Naming the
512
- // requirement is what turns a dead end into a next action.
513
- return (
514
- <div className="cg-mode-empty">
515
- <p>
516
- A swipe deck sorts into a single-select field with at least two options. This database
517
- does not have one yet β€” add a single-select column, then come back.
518
- </p>
519
- </div>
520
- );
521
- }
522
- const ready = !!chosen && !!left && !!right && left.toLowerCase() !== right.toLowerCase();
523
- return (
524
- <div className="cg-swipe-setup">
525
- <p className="cg-swipe-setup-note">{message}</p>
526
- <label className="cg-swipe-setup-row">
527
- <span>Sort into</span>
528
- <select
529
- className="cg-select"
530
- value={fieldKey}
531
- onChange={(e) => setFieldKey(e.target.value)}
532
- >
533
- {/* Every option carries an explicit `value`: a <select> whose value names nothing
534
- renders its FIRST option and reports a choice the user never made
535
- ([[cg-condition-builder-items]]). */}
536
- {selects.map((f) => (
537
- <option key={f.key} value={f.key}>
538
- {f.label}
539
- </option>
540
- ))}
541
- </select>
542
- </label>
543
- <div className="cg-swipe-setup-sides">
544
- <label className="cg-swipe-setup-row">
545
- <span>Swipe left</span>
546
- <select className="cg-select" value={left} onChange={(e) => setLeft(e.target.value)}>
547
- {options.map((o) => (
548
- <option key={o} value={o}>
549
- {o}
550
- </option>
551
- ))}
552
- </select>
553
- </label>
554
- <label className="cg-swipe-setup-row">
555
- <span>Swipe right</span>
556
- <select className="cg-select" value={right} onChange={(e) => setRight(e.target.value)}>
557
- {options.map((o) => (
558
- <option key={o} value={o}>
559
- {o}
560
- </option>
561
- ))}
562
- </select>
563
- </label>
564
- </div>
565
- {!ready && left && right && (
566
- // Stated, not silently refused: both engines DROP a binding whose sides are the same
567
- // option, so a Save that looked like it worked would simply not persist.
568
- <p className="cg-swipe-setup-warn">
569
- The two sides must be different options β€” otherwise both gestures do the same thing.
570
- </p>
571
- )}
572
- <button
573
- type="button"
574
- className="cg-btn cg-btn--primary"
575
- disabled={!ready}
576
- onClick={() =>
577
- chosen && onSpec({ fieldKey: chosen.key, leftOption: left, rightOption: right })
578
- }
579
- >
580
- Start sorting
581
- </button>
582
- </div>
583
- );
584
- }
585
-
586
- export default SwipeView;
 
1
+ // ---------------------------------------------------------------------------
2
+ // customer-grid / SwipeView.tsx
3
+ // ⭐ WAVE-27 item 8 (owner ruling R2, contract C3) β€” the SWIPE deck.
4
+ //
5
+ // One record at a time, decided left or right into two options of ONE
6
+ // single-select. R2 fixes the shape and it is narrow on purpose:
7
+ // Β· SINGLE-SELECT ONLY, one field, two of its options. No checkbox binding.
8
+ // Β· the deck holds only the records whose bound field is EMPTY β€” a record
9
+ // that already has a value has been decided, and re-asking is not triage.
10
+ // Β· a swipe writes through the NORMAL cell door (`onSwipe`, which the host
11
+ // maps to the same `patchAndRecord` a kanban card move uses), so undo,
12
+ // echo-suppression and the permission wall all hold without being
13
+ // re-implemented here.
14
+ //
15
+ // Honesty rules carried from the other modes:
16
+ // Β· nothing is silently hidden β€” the deck states what is left, and the
17
+ // empty state names the bound field rather than saying "all done".
18
+ // Β· a lost binding is SHOWN, never repaired by guessing. `_clean_display`
19
+ // validates that `fieldKey` names a field the table HAS and stops there;
20
+ // it cannot know the field is still a select, or that the two options are
21
+ // still in its vocabulary (its docstring draws that line explicitly). So
22
+ // those three losses land here, and each one says what happened and
23
+ // re-opens the picker β€” the `viewModes.tsx:190-194` rule, which exists
24
+ // because the wave-7 trap was a picker silently falling back to its first
25
+ // option.
26
+ // ---------------------------------------------------------------------------
27
+
28
+ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
29
+ // ⭐⭐ W41-T48 (owner instruction 22) β€” opening a record from the swipe deck folds the shell's
30
+ // navigation rail exactly as a grid cell click does. Guard rationale: `MapView.tsx:2755`.
31
+ import { NAV_MINIMIZE_EVENT, signal } from "../apiContract";
32
+ import { choiceOptions } from "./types";
33
+ import type { CustomerDoc, DisplaySpec, Field, Row, Viewer } from "./types";
34
+ // ⚠ `SurfaceScope` is `apiBridge`'s (a TYPE-only import, so nothing of that module is
35
+ // loaded here) β€” the same import `RecordComments` takes for the same prop.
36
+ import type { SurfaceScope } from "./apiBridge";
37
+ import RecordComments from "./RecordComments";
38
+ import { Documents } from "./Documents";
39
+ import { formatDisplay } from "./cells";
40
+ import { actionHref } from "./display";
41
+ import { optionTint } from "./choiceColors";
42
+ import { ModeIcon } from "./icons";
43
+ // ⭐ W29-T73 β€” the line its three siblings all have, and the one this file shipped without.
44
+ // `SwipeView.css` had ZERO references anywhere in `src/`, so T26's two new sections rendered
45
+ // unstyled while `.cg-swipe-card` (which lives in `index.css`) kept the card looking right β€”
46
+ // a partially-styled surface reads as a design choice, which is why nobody reported it and no
47
+ // gate could see it: a side-effect import references no symbol ([[artifact-with-no-importer]]).
48
+ import "./SwipeView.css";
49
+
50
+ export type SwipeSpec = NonNullable<DisplaySpec["swipe"]>;
51
+
52
+ /** The three ways a stored binding can rot that the host cannot see (see the header note). */
53
+ type BindingFault =
54
+ | { kind: "unbound" }
55
+ | { kind: "field-gone"; fieldKey: string }
56
+ | { kind: "not-select"; field: Field }
57
+ | { kind: "option-gone"; field: Field; missing: string[] };
58
+
59
+ function readBinding(spec: SwipeSpec | undefined, fieldByKey: Map<string, Field>):
60
+ { ok: true; field: Field; spec: SwipeSpec } | { ok: false; fault: BindingFault } {
61
+ if (!spec) return { ok: false, fault: { kind: "unbound" } };
62
+ const field = fieldByKey.get(spec.fieldKey);
63
+ if (!field) return { ok: false, fault: { kind: "field-gone", fieldKey: spec.fieldKey } };
64
+ // R2 β€” SINGLE-select only. `multiselect` is deliberately not accepted: its cell holds a SET,
65
+ // so "write this option" would mean append-or-replace, and a triage gesture that sometimes
66
+ // adds and sometimes overwrites is two gestures wearing one button.
67
+ if (field.type !== "select") return { ok: false, fault: { kind: "not-select", field } };
68
+ const options = choiceOptions(field);
69
+ const has = new Set(options.map((o) => o.toLowerCase()));
70
+ const missing = [spec.leftOption, spec.rightOption].filter((o) => !has.has(o.toLowerCase()));
71
+ if (missing.length) return { ok: false, fault: { kind: "option-gone", field, missing } };
72
+ return { ok: true, field, spec };
73
+ }
74
+
75
+ /** The bound cell is EMPTY β€” the one predicate that decides deck membership (R2). */
76
+ const isUndecided = (row: Row, key: string): boolean =>
77
+ String(row[key] ?? "").trim() === "";
78
+
79
+ export function SwipeView({
80
+ rows,
81
+ fields,
82
+ fieldByKey,
83
+ spec,
84
+ cardKeys,
85
+ detailKeys,
86
+ scope,
87
+ viewer,
88
+ docs,
89
+ docPayload,
90
+ onDocAdd,
91
+ onDocFetch,
92
+ onDocDelete,
93
+ titleKey,
94
+ canWrite,
95
+ readOnlyReason,
96
+ canBind,
97
+ onSpec,
98
+ onSwipe,
99
+ onOpen,
100
+ }: {
101
+ /** DISTINCT data rows from the full pipeline, overlay edits layered β€” the kanban's contract.
102
+ * The deck re-derives from these, so a written record leaves it as soon as the optimistic
103
+ * patch lands; there is no local cursor to drift out of step with the data. */
104
+ rows: Row[];
105
+ /** Every field, for the picker's field list. */
106
+ fields: Field[];
107
+ fieldByKey: Map<string, Field>;
108
+ /** The stored binding, or undefined for a deck nobody has configured yet. */
109
+ spec: SwipeSpec | undefined;
110
+ /** The handful of visible fields the card lists under its title. */
111
+ cardKeys: string[];
112
+ titleKey: string;
113
+ /** May this viewer write the BOUND field's value? (the kanban's `canMove`) */
114
+ canWrite: boolean;
115
+ /** Stated when the deck cannot be decided β€” permissions, or a computed column. */
116
+ readOnlyReason: string | null;
117
+ /** May this viewer change what the deck is bound TO? A VIEW-config act, so it is the
118
+ * view-editing permission and NOT `canWrite` β€” conflating the two is
119
+ * [[schema-role-is-not-a-value-wall]]. REQUIRED, because a picker that silently does
120
+ * nothing is worse than no picker ([[wrong-parent-not-broken-control]]). */
121
+ canBind: boolean;
122
+ /** `undefined` DELETES the binding β€” absent is the honest unconfigured state, and storing a
123
+ * half-binding is what `cleanDisplay` drops on both engines (the `kanbanClamp` law). */
124
+ onSpec: (next: SwipeSpec | undefined) => void;
125
+ onSwipe: (pid: number, value: string) => void;
126
+ onOpen: (pid: number) => void;
127
+ /**
128
+ * ⭐⭐ WAVE-29 T26 (owner R9) β€” WHAT MAKES THE CARD A RECORD RATHER THAN A SUMMARY.
129
+ *
130
+ * R9: *"the swipe CARD itself renders the record detail inline β€” fields, comments and
131
+ * attachments β€” so a reviewer decides without leaving the deck."* Everything below is that,
132
+ * and every one of them is OPTIONAL for one reason: this deck runs on hosts that supply
133
+ * different amounts. A card must render with none of them rather than throw β€” the standalone
134
+ * embed has no `scope`, and a deployment with no document storage serves no handlers.
135
+ */
136
+ /** Every field the VIEW shows, in its order β€” not the three-key card summary. */
137
+ detailKeys?: string[];
138
+ /** The surface these records live on. Comments are keyed by it; absent β‡’ no comments section,
139
+ * which is the pre-existing precondition `RecordDetail` already carries. */
140
+ scope?: SurfaceScope;
141
+ viewer?: Viewer;
142
+ /** This record's attachments, and the plumbing. Handlers absent β‡’ the section is not rendered
143
+ * at all, exactly as `RecordDetail` decides it (a dead upload control is a promise the app
144
+ * cannot keep). */
145
+ /** Keyed by pid, because a deck shows many records β€” `RecordDetail` takes ONE record's list
146
+ * and that shape cannot serve a deck. */
147
+ docs?: Record<string, CustomerDoc[]>;
148
+ docPayload?: { pid: number; docId: string; name: string; mime: string; data_b64: string };
149
+ /** ⚠ EVERY HANDLER TAKES THE PID, unlike `RecordDetail`'s, whose host closes over the ONE
150
+ * open record. A deck paints many records at once, so a handler bound to a single pid would
151
+ * attach every reviewer's upload to whichever card happened to be open. */
152
+ onDocAdd?: (
153
+ pid: number,
154
+ file: { name: string; mime: string; size: number; data_b64: string }
155
+ ) => void;
156
+ onDocFetch?: (pid: number, docId: string) => void;
157
+ onDocDelete?: (pid: number, docId: string) => void;
158
+ }) {
159
+ // "Later" β€” session-only, never stored. A deck with no way past a record you cannot decide
160
+ // blocks on that record forever, so this is navigation WITHIN the deck rather than a third
161
+ // gesture: it writes nothing, survives no reload, and the count is disclosed in the empty
162
+ // state rather than quietly shrinking the deck (rule 8b).
163
+ const [later, setLater] = useState<Set<number>>(new Set());
164
+ const deckRef = useRef<HTMLDivElement>(null);
165
+
166
+ const binding = useMemo(() => readBinding(spec, fieldByKey), [spec, fieldByKey]);
167
+ const boundKey = binding.ok ? binding.field.key : null;
168
+
169
+ const undecided = useMemo(
170
+ () => (boundKey ? rows.filter((r) => isUndecided(r, boundKey)) : []),
171
+ [rows, boundKey]
172
+ );
173
+ const deck = useMemo(() => undecided.filter((r) => !later.has(r.pid)), [undecided, later]);
174
+ const card = deck[0];
175
+
176
+ // A record decided elsewhere (the grid, another user's echo) must not stay "later" forever β€”
177
+ // otherwise the disclosed skip count drifts away from what is actually on the deck.
178
+ useEffect(() => {
179
+ setLater((prev) => {
180
+ if (prev.size === 0) return prev;
181
+ const live = new Set(undecided.map((r) => r.pid));
182
+ const next = new Set([...prev].filter((pid) => live.has(pid)));
183
+ return next.size === prev.size ? prev : next;
184
+ });
185
+ }, [undecided]);
186
+
187
+ const decide = useCallback(
188
+ (value: string) => {
189
+ if (!card || !canWrite) return;
190
+ onSwipe(card.pid, value);
191
+ },
192
+ [card, canWrite, onSwipe]
193
+ );
194
+
195
+ // ← / β†’ decide, and they are the SAME two actions the buttons are rather than a second code
196
+ // path: the whole point of the mode is that one hand can clear a queue.
197
+ useEffect(() => {
198
+ if (!binding.ok || !canWrite || !card) return;
199
+ const onKey = (e: KeyboardEvent) => {
200
+ if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
201
+ const el = document.activeElement as HTMLElement | null;
202
+ // Never steal an arrow key from a text field or a native control the user is inside.
203
+ if (el && (el.tagName === "INPUT" || el.tagName === "SELECT" || el.tagName === "TEXTAREA"))
204
+ return;
205
+ if (!deckRef.current?.contains(el ?? null) && el !== document.body) return;
206
+ e.preventDefault();
207
+ decide(e.key === "ArrowLeft" ? binding.spec.leftOption : binding.spec.rightOption);
208
+ };
209
+ window.addEventListener("keydown", onKey);
210
+ return () => window.removeEventListener("keydown", onKey);
211
+ }, [binding, canWrite, card, decide]);
212
+
213
+ if (!binding.ok) {
214
+ return (
215
+ <div className="cg-swipe" ref={deckRef}>
216
+ <SwipeBinder
217
+ fault={binding.fault}
218
+ fields={fields}
219
+ fieldByKey={fieldByKey}
220
+ spec={spec}
221
+ canBind={canBind}
222
+ onSpec={onSpec}
223
+ />
224
+ </div>
225
+ );
226
+ }
227
+
228
+ const { field } = binding;
229
+ const leftTint = optionTint(field, binding.spec.leftOption);
230
+ const rightTint = optionTint(field, binding.spec.rightOption);
231
+
232
+ return (
233
+ <div className="cg-swipe" ref={deckRef} tabIndex={-1}>
234
+ <div className="cg-swipe-bar">
235
+ <span className="cg-swipe-bound">
236
+ <ModeIcon mode="swipe" />
237
+ Sorting into <strong>{field.label}</strong>
238
+ </span>
239
+ <span className="cg-swipe-left">
240
+ {deck.length.toLocaleString()} {deck.length === 1 ? "record" : "records"} to sort
241
+ </span>
242
+ {canBind && (
243
+ <button
244
+ type="button"
245
+ className="cg-link-btn"
246
+ onClick={() => onSpec(undefined)}
247
+ title="Choose a different field or different options for this deck"
248
+ >
249
+ Change
250
+ </button>
251
+ )}
252
+ </div>
253
+ {readOnlyReason && <div className="cg-kb-note">{readOnlyReason}</div>}
254
+ {card ? (
255
+ <div className="cg-swipe-deck">
256
+ <button
257
+ type="button"
258
+ className="cg-swipe-side cg-swipe-side--left"
259
+ disabled={!canWrite}
260
+ style={leftTint ? { background: leftTint.bg, color: leftTint.fg } : undefined}
261
+ onClick={() => decide(binding.spec.leftOption)}
262
+ title={`Set ${field.label} to ${binding.spec.leftOption} (left arrow key)`}
263
+ >
264
+ <span aria-hidden className="cg-swipe-arrow">
265
+ <svg width="16" height="16" viewBox="0 0 16 16">
266
+ <path
267
+ d="M11 3.2 6.2 8l4.8 4.8"
268
+ fill="none"
269
+ stroke="currentColor"
270
+ strokeWidth="1.6"
271
+ strokeLinecap="round"
272
+ strokeLinejoin="round"
273
+ />
274
+ </svg>
275
+ </span>
276
+ {binding.spec.leftOption}
277
+ </button>
278
+ <article
279
+ className="cg-swipe-card"
280
+ role="button"
281
+ tabIndex={0}
282
+ onClick={(e) => {
283
+ // ⭐ W41-T48 β€” the card IS the deck's record open, so it folds the rail.
284
+ // ⚠ Nothing that is NOT an open can reach this line: every control inside the
285
+ // card (a url cell, the comments box, the document tray) already stops its own
286
+ // click, and the left/right decision buttons are siblings of the card, not
287
+ // children of it. The deck also has no pointer drag to disambiguate β€” its swipe
288
+ // is the two buttons and the arrow keys, neither of which opens anything.
289
+ // ⚠ `<article role="button">`, not a native button, so a keyboard activation
290
+ // never arrives here as a synthetic click; the keydown path below is the whole
291
+ // keyboard story and the two cannot both fire for one gesture.
292
+ if (e.detail <= 1) signal(NAV_MINIMIZE_EVENT);
293
+ onOpen(card.pid);
294
+ }}
295
+ onKeyDown={(e) => {
296
+ if (e.key !== "Enter" && e.key !== " ") return;
297
+ e.preventDefault();
298
+ // W41-T48 β€” `!e.repeat` is this path's `e.detail <= 1`: a HELD Enter or Space
299
+ // auto-repeats keydown, and every one of those repeats is the SAME gesture.
300
+ if (!e.repeat) signal(NAV_MINIMIZE_EVENT);
301
+ onOpen(card.pid);
302
+ }}
303
+ >
304
+ <h3 className="cg-swipe-title">{String(card[titleKey] ?? "")}</h3>
305
+ <div className="cg-swipe-cells">
306
+ {/* ⭐ WAVE-29 T26 (R9) β€” the RECORD's visible fields, not the three-key summary the
307
+ kanban card lends. `detailKeys` falls back to `cardKeys` so a host that has not
308
+ been widened yet renders exactly what it rendered before. */}
309
+ {(detailKeys && detailKeys.length ? detailKeys : cardKeys).map((k) => {
310
+ const f = fieldByKey.get(k);
311
+ if (!f) return null;
312
+ const text = formatDisplay(f, card[k]);
313
+ if (!text) return null;
314
+ // A url cell is a LINK here too (wave-26 item 11), through `display.ts`'s one
315
+ // scheme guard β€” and every gesture that reaches it must be stopped from also
316
+ // reaching the card, which is a button (the kanban card's note, same trap).
317
+ const href = actionHref(f, card[k]);
318
+ return (
319
+ <div key={k} className="cg-swipe-cell">
320
+ <span className="cg-lv-k">{f.label}</span>
321
+ {href ? (
322
+ <a
323
+ className="cg-lv-v"
324
+ href={href}
325
+ target="_blank"
326
+ rel="noopener noreferrer"
327
+ title={text}
328
+ onClick={(e) => e.stopPropagation()}
329
+ onKeyDown={(e) => e.stopPropagation()}
330
+ >
331
+ {text}
332
+ </a>
333
+ ) : (
334
+ <span className="cg-lv-v">{text}</span>
335
+ )}
336
+ </div>
337
+ );
338
+ })}
339
+ </div>
340
+ {/* ⭐ R9's other two thirds. Both stop their own events: the card is a `role="button"`
341
+ that opens the record, and a click on a comment box or an upload control must not
342
+ also open the modal it exists to make unnecessary (the kanban card's link trap,
343
+ one surface over). */}
344
+ {onDocAdd && onDocFetch && onDocDelete && (
345
+ <div
346
+ className="cg-swipe-docs"
347
+ onClick={(e) => e.stopPropagation()}
348
+ onKeyDown={(e) => e.stopPropagation()}
349
+ role="presentation"
350
+ >
351
+ <Documents
352
+ pid={Number(card.pid)}
353
+ docs={docs?.[String(card.pid)] ?? []}
354
+ docPayload={docPayload}
355
+ onAdd={(file) => onDocAdd(card.pid, file)}
356
+ onFetch={(docId) => onDocFetch(card.pid, docId)}
357
+ onDelete={(docId) => onDocDelete(card.pid, docId)}
358
+ />
359
+ </div>
360
+ )}
361
+ {scope != null && (
362
+ <div
363
+ className="cg-swipe-comments"
364
+ onClick={(e) => e.stopPropagation()}
365
+ onKeyDown={(e) => e.stopPropagation()}
366
+ role="presentation"
367
+ >
368
+ {/* ⚠ KEYED ON scope+pid, the same key `RecordDetail` uses: without it React
369
+ reuses the mounted instance across a card change and paints one record's
370
+ comments under another's name until the fetch returns. */}
371
+ <RecordComments
372
+ key={`${scope}:${Number(card.pid)}`}
373
+ scope={scope}
374
+ pid={Number(card.pid)}
375
+ viewer={viewer}
376
+ />
377
+ </div>
378
+ )}
379
+ {canWrite && (
380
+ <button
381
+ type="button"
382
+ className="cg-link-btn cg-swipe-later"
383
+ onClick={(e) => {
384
+ e.stopPropagation();
385
+ setLater((prev) => new Set(prev).add(card.pid));
386
+ }}
387
+ >
388
+ Decide later
389
+ </button>
390
+ )}
391
+ </article>
392
+ <button
393
+ type="button"
394
+ className="cg-swipe-side cg-swipe-side--right"
395
+ disabled={!canWrite}
396
+ style={rightTint ? { background: rightTint.bg, color: rightTint.fg } : undefined}
397
+ onClick={() => decide(binding.spec.rightOption)}
398
+ title={`Set ${field.label} to ${binding.spec.rightOption} (right arrow key)`}
399
+ >
400
+ {binding.spec.rightOption}
401
+ <span aria-hidden className="cg-swipe-arrow">
402
+ <svg width="16" height="16" viewBox="0 0 16 16">
403
+ <path
404
+ d="M5 3.2 9.8 8 5 12.8"
405
+ fill="none"
406
+ stroke="currentColor"
407
+ strokeWidth="1.6"
408
+ strokeLinecap="round"
409
+ strokeLinejoin="round"
410
+ />
411
+ </svg>
412
+ </span>
413
+ </button>
414
+ </div>
415
+ ) : (
416
+ // The empty state NAMES the bound field (C3), because "nothing to sort" is ambiguous
417
+ // between "the deck is finished" and "the filter hid everything", and the two want
418
+ // different next actions. `later` is disclosed rather than quietly subtracted.
419
+ <div className="cg-mode-empty cg-swipe-empty">
420
+ {later.size > 0 ? (
421
+ <>
422
+ <p>
423
+ {later.size.toLocaleString()}{" "}
424
+ {later.size === 1 ? "record is" : "records are"} set aside for later. Nothing else
425
+ in this view is missing a <strong>{field.label}</strong>.
426
+ </p>
427
+ <button type="button" className="cg-btn" onClick={() => setLater(new Set())}>
428
+ Bring them back
429
+ </button>
430
+ </>
431
+ ) : (
432
+ <p>
433
+ Every record in this view already has a <strong>{field.label}</strong>. Widen the
434
+ view's filters to sort more.
435
+ </p>
436
+ )}
437
+ </div>
438
+ )}
439
+ </div>
440
+ );
441
+ }
442
+
443
+ /**
444
+ * The binding picker: field + two options. It is also the surface every LOST binding lands on,
445
+ * with the loss stated above it β€” one place that answers "what is this deck for", rather than an
446
+ * error screen beside a separate setup screen.
447
+ */
448
+ function SwipeBinder({
449
+ fault,
450
+ fields,
451
+ fieldByKey,
452
+ spec,
453
+ canBind,
454
+ onSpec,
455
+ }: {
456
+ fault: BindingFault;
457
+ fields: Field[];
458
+ fieldByKey: Map<string, Field>;
459
+ spec: SwipeSpec | undefined;
460
+ canBind: boolean;
461
+ onSpec: (next: SwipeSpec | undefined) => void;
462
+ }) {
463
+ const selects = useMemo(
464
+ () => fields.filter((f) => f.type === "select" && choiceOptions(f).length >= 2),
465
+ [fields]
466
+ );
467
+ const [fieldKey, setFieldKey] = useState<string>(() => {
468
+ if (spec && fieldByKey.get(spec.fieldKey)?.type === "select") return spec.fieldKey;
469
+ return selects[0]?.key ?? "";
470
+ });
471
+ const chosen = fieldByKey.get(fieldKey);
472
+ const options = useMemo(() => (chosen ? choiceOptions(chosen) : []), [chosen]);
473
+ const [left, setLeft] = useState<string>("");
474
+ const [right, setRight] = useState<string>("");
475
+
476
+ // The two option selects follow the FIELD. Kept in an effect rather than derived so the user's
477
+ // pick survives re-renders, and reset whenever the field changes β€” carrying an option from the
478
+ // previous field would offer a value the new field cannot hold.
479
+ useEffect(() => {
480
+ setLeft(options[0] ?? "");
481
+ setRight(options.find((o) => o !== options[0]) ?? "");
482
+ }, [options]);
483
+
484
+ const message = ((): string => {
485
+ switch (fault.kind) {
486
+ case "field-gone":
487
+ return "The field this deck sorted into has been deleted. Pick another one.";
488
+ case "not-select":
489
+ return `β€œ${fault.field.label}” is no longer a single-select, so it has no options to`
490
+ + " sort into. Pick another field.";
491
+ case "option-gone":
492
+ return `${fault.missing.map((m) => `β€œ${m}”`).join(" and ")} ${
493
+ fault.missing.length === 1 ? "is" : "are"
494
+ } no longer ${fault.missing.length === 1 ? "an option" : "options"} on β€œ${
495
+ fault.field.label
496
+ }”. Pick the sides again.`;
497
+ default:
498
+ return "Sort records one at a time into two options of a single-select field.";
499
+ }
500
+ })();
501
+
502
+ if (!canBind) {
503
+ return (
504
+ <div className="cg-mode-empty">
505
+ <p>{message}</p>
506
+ <p>Its creator or an admin can set this view up.</p>
507
+ </div>
508
+ );
509
+ }
510
+ if (selects.length === 0) {
511
+ // Honest and specific: the mode is not broken, the TABLE has nothing to bind to. Naming the
512
+ // requirement is what turns a dead end into a next action.
513
+ return (
514
+ <div className="cg-mode-empty">
515
+ <p>
516
+ A swipe deck sorts into a single-select field with at least two options. This database
517
+ does not have one yet β€” add a single-select column, then come back.
518
+ </p>
519
+ </div>
520
+ );
521
+ }
522
+ const ready = !!chosen && !!left && !!right && left.toLowerCase() !== right.toLowerCase();
523
+ return (
524
+ <div className="cg-swipe-setup">
525
+ <p className="cg-swipe-setup-note">{message}</p>
526
+ <label className="cg-swipe-setup-row">
527
+ <span>Sort into</span>
528
+ <select
529
+ className="cg-select"
530
+ value={fieldKey}
531
+ onChange={(e) => setFieldKey(e.target.value)}
532
+ >
533
+ {/* Every option carries an explicit `value`: a <select> whose value names nothing
534
+ renders its FIRST option and reports a choice the user never made
535
+ ([[cg-condition-builder-items]]). */}
536
+ {selects.map((f) => (
537
+ <option key={f.key} value={f.key}>
538
+ {f.label}
539
+ </option>
540
+ ))}
541
+ </select>
542
+ </label>
543
+ <div className="cg-swipe-setup-sides">
544
+ <label className="cg-swipe-setup-row">
545
+ <span>Swipe left</span>
546
+ <select className="cg-select" value={left} onChange={(e) => setLeft(e.target.value)}>
547
+ {options.map((o) => (
548
+ <option key={o} value={o}>
549
+ {o}
550
+ </option>
551
+ ))}
552
+ </select>
553
+ </label>
554
+ <label className="cg-swipe-setup-row">
555
+ <span>Swipe right</span>
556
+ <select className="cg-select" value={right} onChange={(e) => setRight(e.target.value)}>
557
+ {options.map((o) => (
558
+ <option key={o} value={o}>
559
+ {o}
560
+ </option>
561
+ ))}
562
+ </select>
563
+ </label>
564
+ </div>
565
+ {!ready && left && right && (
566
+ // Stated, not silently refused: both engines DROP a binding whose sides are the same
567
+ // option, so a Save that looked like it worked would simply not persist.
568
+ <p className="cg-swipe-setup-warn">
569
+ The two sides must be different options β€” otherwise both gestures do the same thing.
570
+ </p>
571
+ )}
572
+ <button
573
+ type="button"
574
+ className="cg-btn cg-btn--primary"
575
+ disabled={!ready}
576
+ onClick={() =>
577
+ chosen && onSpec({ fieldKey: chosen.key, leftOption: left, rightOption: right })
578
+ }
579
+ >
580
+ Start sorting
581
+ </button>
582
+ </div>
583
+ );
584
+ }
585
+
586
+ export default SwipeView;
web/src/customer-grid/Toolbar.tsx CHANGED
@@ -35,8 +35,8 @@ import { viewDisplayMode } from "./types";
35
  import { PIVOT_WINDOWS, PIVOT_WINDOW_LABELS } from "./types";
36
  import { COPY_PARTS, COPY_PART_KEYS, copyViewConfig } from "./copyConfig";
37
  import type { CopyPart } from "./copyConfig";
38
- import { directionLabel, filterTreeConj, filterTreeNodes, isFilterGroup, isGroupableField }
39
- from "./types";
40
  import type { WindowSpec } from "./windows";
41
  import { AnchoredOverlay } from "./OverlaySurface";
42
  import { EyeOffIcon, FieldTypeIcon, ModeIcon } from "./icons";
@@ -49,6 +49,10 @@ import type { PoolProgress } from "./counts";
49
  // keeps everything that is genuinely toolbar: the strip, its buttons, sort, group, colour,
50
  // rows, search, the count, and the copy-configuration door it hands the builder as a slot.
51
  import { FilterBuilderPanel, FieldsHidePanel, Popover } from "../filter-kit";
 
 
 
 
52
  import { MEASURE_OP_LIST, countConditions, newRuleId, opsForType } from "../filter-kit/ops";
53
  import "./filters.css";
54
 
@@ -73,6 +77,28 @@ export interface ToolbarProps {
73
  deletableKeys?: ReadonlySet<string>;
74
  onDeleteField?: (key: string) => void;
75
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
76
  /**
77
  * ⭐⭐ W38-T07 (owner instruction 12) β€” THE ONE COLOUR CONTROL, and it names a FIELD rather than
78
  * answering yes/no. It used to be two radios ("No color" / "Color by status") whose `true` arm
@@ -529,19 +555,51 @@ function SortBuilder({
529
  fieldByKey,
530
  sorts,
531
  onSorts,
 
532
  }: {
533
  fields: Field[];
534
  fieldByKey: Map<string, Field>;
535
  sorts: SortSpec;
536
  onSorts: (s: SortSpec) => void;
 
 
 
537
  }) {
 
 
 
 
 
538
  const update = (i: number, patch: Partial<SortRule>) =>
539
  onSorts(sorts.map((s, j) => (j === i ? { ...s, ...patch } : s)));
540
  const remove = (i: number) => onSorts(sorts.filter((_, j) => j !== i));
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
541
  const add = () => {
542
  const used = new Set(sorts.map((s) => s.colId));
543
- const f = fields.find((fl) => !used.has(fl.key)) ?? fields[0];
 
 
 
 
 
544
  if (!f) return;
 
545
  onSorts([...sorts, { colId: f.key, dir: "asc" }]);
546
  };
547
 
@@ -555,6 +613,10 @@ function SortBuilder({
555
  )}
556
  {sorts.map((rule, i) => {
557
  const t = fieldByKey.get(rule.colId)?.type ?? "text";
 
 
 
 
558
  return (
559
  <div className="cg-cond-line" key={i}>
560
  <span className="cg-cond-prefix">{i === 0 ? "Sort by" : "then by"}</span>
@@ -567,8 +629,8 @@ function SortBuilder({
567
  className="cg-cond-field"
568
  ariaLabel="Sort field"
569
  value={rule.colId}
570
- onChange={(key) => update(i, { colId: key })}
571
- fields={fields.map((fl) => ({
572
  key: fl.key, label: fl.label, type: fl.type,
573
  }))}
574
  />
@@ -592,6 +654,11 @@ function SortBuilder({
592
  Γ—
593
  </button>
594
  </span>
 
 
 
 
 
595
  </div>
596
  );
597
  })}
@@ -630,6 +697,14 @@ export default function Toolbar({
630
  onFieldOrder,
631
  deletableKeys,
632
  onDeleteField,
 
 
 
 
 
 
 
 
633
  colorField,
634
  colorChoices,
635
  onColorField,
@@ -790,7 +865,7 @@ export default function Toolbar({
790
  : "Color";
791
  // W41-T42 β€” the same idiom `colorLabel` and `groupLabel` already use: a control that HAS a
792
  // current answer names it on the trigger, so the reader does not have to open it to find out.
793
- const relationalLabel = relational ? `Relational: ${relational.label}` : "Relational";
794
 
795
  /**
796
  * R11's greying, as one attribute. `inert` is not in React 18's JSX typings (it landed with
@@ -826,12 +901,37 @@ export default function Toolbar({
826
  // every other caller of the panel invert twice.
827
  hidden={hiddenKeys}
828
  onToggle={(key) => onColumnVisible(key, !visible.has(key))}
829
- onShowAll={() => onColumnsVisible(fields.map((field) => field.key))}
 
 
 
 
 
 
 
 
 
 
 
830
  onHideAll={() => onColumnsVisible([lockedKey])}
831
  lockedKey={lockedKey}
832
  onFieldOrder={onFieldOrder}
833
  deletableKeys={deletableKeys}
834
  onDeleteField={onDeleteField}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
835
  />
836
  )}
837
  </Popover>
@@ -888,6 +988,7 @@ export default function Toolbar({
888
  fieldByKey={fieldByKey}
889
  sorts={sorts}
890
  onSorts={onSorts}
 
891
  />
892
  )}
893
  </Popover>
@@ -1222,7 +1323,7 @@ export default function Toolbar({
1222
  className="cg-count cg-count-pending"
1223
  title={
1224
  `${unresolvedCount} condition${unresolvedCount === 1 ? "" : "s"} cannot be ` +
1225
- "evaluated β€” a date that does not resolve, or a list this view refers to that no " +
1226
  "longer exists. Rows are hidden rather than shown under a count that would be wrong."
1227
  }
1228
  >
@@ -1245,7 +1346,7 @@ export default function Toolbar({
1245
  <span
1246
  className="cg-count cg-count-partial"
1247
  title={
1248
- `Loading the rest of your ${nouns} in the background β€” you can browse, ` +
1249
  "filter and sort what is already here."
1250
  }
1251
  >
 
35
  import { PIVOT_WINDOWS, PIVOT_WINDOW_LABELS } from "./types";
36
  import { COPY_PARTS, COPY_PART_KEYS, copyViewConfig } from "./copyConfig";
37
  import type { CopyPart } from "./copyConfig";
38
+ import { directionLabel, filterTreeConj, filterTreeNodes, isFilterGroup, isGroupableField,
39
+ isOfferableField, offerableFields, routeSortRefusal } from "./types";
40
  import type { WindowSpec } from "./windows";
41
  import { AnchoredOverlay } from "./OverlaySurface";
42
  import { EyeOffIcon, FieldTypeIcon, ModeIcon } from "./icons";
 
49
  // keeps everything that is genuinely toolbar: the strip, its buttons, sort, group, colour,
50
  // rows, search, the count, and the copy-configuration door it hands the builder as a slot.
51
  import { FilterBuilderPanel, FieldsHidePanel, Popover } from "../filter-kit";
52
+ // ⭐⭐ W42-T12 β€” WHO IS LOOKING, so contract C2's rights pair can be asked inside the manager
53
+ // panel at all. `import type`, because `verbatimModuleSyntax` is on and this file takes no
54
+ // runtime dependency on `fieldClass.ts`.
55
+ import type { FieldViewer } from "../filter-kit/fieldClass";
56
  import { MEASURE_OP_LIST, countConditions, newRuleId, opsForType } from "../filter-kit/ops";
57
  import "./filters.css";
58
 
 
77
  deletableKeys?: ReadonlySet<string>;
78
  onDeleteField?: (key: string) => void;
79
 
80
+ /**
81
+ * ⭐⭐ W42-T12 (D-485) β€” THE FIELD MANAGER'S SIX DOORS, AND EVERY ONE OF THEM IS REQUIRED.
82
+ *
83
+ * This toolbar carries the ONLY mount of `FieldsHidePanel` that runs in manager mode, so a
84
+ * ticked selection with a Share, Reassign, Hide, Show or Delete button behind it is this
85
+ * component's responsibility to feed. Optional would have compiled, rendered the whole bulk
86
+ * bar and done nothing on every press β€” a feature that looks built and is not, which is
87
+ * exactly the shape D-485 records. Required means an unfed host fails the typecheck instead
88
+ * of failing the user.
89
+ *
90
+ * ⚠ `viewer` IS NOT A DOOR AND IS STILL REQUIRED. Without it the panel cannot ask C2's rights
91
+ * pair, so every row falls back to "rights unknown" and the manager withdraws affordances that
92
+ * ship today. The five handlers come from `CustomerGrid::useFieldBulkDoors`, which batches
93
+ * each act into ONE config write; none of them may be built here by looping a per-key prop.
94
+ */
95
+ viewer: FieldViewer | undefined;
96
+ onSetFieldsHidden: ((keys: string[], hidden: boolean) => void) | null;
97
+ onShareFields: ((keys: string[]) => void) | null;
98
+ onReassignFields: ((keys: string[]) => void) | null;
99
+ onDeleteFields: ((keys: string[]) => void) | null;
100
+ onRemoveField: ((key: string) => void) | null;
101
+
102
  /**
103
  * ⭐⭐ W38-T07 (owner instruction 12) β€” THE ONE COLOUR CONTROL, and it names a FIELD rather than
104
  * answering yes/no. It used to be two radios ("No color" / "Color by status") whose `true` arm
 
555
  fieldByKey,
556
  sorts,
557
  onSorts,
558
+ filterTree,
559
  }: {
560
  fields: Field[];
561
  fieldByKey: Map<string, Field>;
562
  sorts: SortSpec;
563
  onSorts: (s: SortSpec) => void;
564
+ /** R22 β€” the CURRENT filter, because whether a route-order sort means anything is a fact
565
+ * about the filter and not about the column. */
566
+ filterTree: FilterTree;
567
  }) {
568
+ // C11 (W42-T54) β€” the sort picker is a field picker, so it offers the offerable columns.
569
+ // β›” BOTH the picker's list AND `add()`'s seed read this ONE list: filtering only the picker
570
+ // would leave "Add sort" free to seed a withheld route column, which is the same defect
571
+ // wearing a different control.
572
+ const offerable = useMemo(() => offerableFields(fields), [fields]);
573
  const update = (i: number, patch: Partial<SortRule>) =>
574
  onSorts(sorts.map((s, j) => (j === i ? { ...s, ...patch } : s)));
575
  const remove = (i: number) => onSorts(sorts.filter((_, j) => j !== i));
576
+ /**
577
+ * β›”β›” R22 β€” THE REFUSAL. Sorting by the route projection column orders records by their STOP
578
+ * POSITION, which is an ordinal inside ONE route and means nothing across two. So the sort is
579
+ * REFUSED, on screen, with a sentence saying why: it is never quietly accepted and then
580
+ * ordered by the cell's raw text, which would put `Route A - 10` before `Route A - 2`.
581
+ *
582
+ * β›” REFUSED AT THE COMMIT, not merely annotated after it. The grid orders rows from
583
+ * `config.sorts` (`useVisibleRows.ts`); a rule that reaches that array HAS been applied, and a
584
+ * message beside an applied wrong order is a caption, not a refusal.
585
+ */
586
+ const [refusal, setRefusal] = useState<{ at: number; text: string } | null>(null);
587
+ const pickField = (i: number, key: string) => {
588
+ const why = routeSortRefusal(key, filterTree, fields);
589
+ if (why) { setRefusal({ at: i, text: why }); return; }
590
+ setRefusal(null);
591
+ update(i, { colId: key });
592
+ };
593
  const add = () => {
594
  const used = new Set(sorts.map((s) => s.colId));
595
+ // The seed skips anything a fresh rule would immediately be refused for: an "Add sort" that
596
+ // lands on a rule the builder then rejects reads as the control being broken.
597
+ const free = offerable.filter(
598
+ (fl) => !used.has(fl.key) && !routeSortRefusal(fl.key, filterTree, fields)
599
+ );
600
+ const f = free[0] ?? offerable.find((fl) => !routeSortRefusal(fl.key, filterTree, fields));
601
  if (!f) return;
602
+ setRefusal(null);
603
  onSorts([...sorts, { colId: f.key, dir: "asc" }]);
604
  };
605
 
 
613
  )}
614
  {sorts.map((rule, i) => {
615
  const t = fieldByKey.get(rule.colId)?.type ?? "text";
616
+ // A rule that is ALREADY stored against the projection column (a saved view, or the
617
+ // filter changing under a sort that used to be fine) says the same sentence.
618
+ const ruleWhy = routeSortRefusal(rule.colId, filterTree, fields);
619
+ const why = refusal?.at === i ? refusal.text : ruleWhy;
620
  return (
621
  <div className="cg-cond-line" key={i}>
622
  <span className="cg-cond-prefix">{i === 0 ? "Sort by" : "then by"}</span>
 
629
  className="cg-cond-field"
630
  ariaLabel="Sort field"
631
  value={rule.colId}
632
+ onChange={(key) => pickField(i, key)}
633
+ fields={offerable.map((fl) => ({
634
  key: fl.key, label: fl.label, type: fl.type,
635
  }))}
636
  />
 
654
  Γ—
655
  </button>
656
  </span>
657
+ {why && (
658
+ <div className="cg-pop-note" role="status">
659
+ {why}
660
+ </div>
661
+ )}
662
  </div>
663
  );
664
  })}
 
697
  onFieldOrder,
698
  deletableKeys,
699
  onDeleteField,
700
+ // ⭐⭐ W42-T12 β€” no defaults, deliberately: each of the six is required, so a default would be
701
+ // a value standing in for a host that never arrived. See `ToolbarProps` for why.
702
+ viewer,
703
+ onSetFieldsHidden,
704
+ onShareFields,
705
+ onReassignFields,
706
+ onDeleteFields,
707
+ onRemoveField,
708
  colorField,
709
  colorChoices,
710
  onColorField,
 
865
  : "Color";
866
  // W41-T42 β€” the same idiom `colorLabel` and `groupLabel` already use: a control that HAS a
867
  // current answer names it on the trigger, so the reader does not have to open it to find out.
868
+ const relationalLabel = relational ? `Related: ${relational.label}` : "Related";
869
 
870
  /**
871
  * R11's greying, as one attribute. `inert` is not in React 18's JSX typings (it landed with
 
901
  // every other caller of the panel invert twice.
902
  hidden={hiddenKeys}
903
  onToggle={(key) => onColumnVisible(key, !visible.has(key))}
904
+ /* C11 (W42-T54) β€” "Show all" shows all of what the panel LISTS. The panel narrows
905
+ to the offerable fields, so passing the unnarrowed list here would make one
906
+ button reveal ~64 route columns the list beside it does not name, with no way
907
+ back through this panel. A withheld column that is visible TODAY is kept
908
+ visible: this control shows things, it does not hide them. */
909
+ onShowAll={() =>
910
+ onColumnsVisible(
911
+ fields
912
+ .filter((field) => isOfferableField(field) || visible.has(field.key))
913
+ .map((field) => field.key)
914
+ )
915
+ }
916
  onHideAll={() => onColumnsVisible([lockedKey])}
917
  lockedKey={lockedKey}
918
  onFieldOrder={onFieldOrder}
919
  deletableKeys={deletableKeys}
920
  onDeleteField={onDeleteField}
921
+ /* ⭐⭐ W42-T12 β€” `manager` IS STATED HERE, and stating it is what makes the six props
922
+ below mandatory. The panel defaults `manager` from `sharedSections`, which this
923
+ mount also leaves unsaid, so the value would be `true` either way; but a default
924
+ is a runtime fact and TypeScript narrows a union only on what a mount WRITES.
925
+ Written, this mount is checked against the manager arm, and dropping any one of
926
+ the six stops the build. Unwritten, it would match the plain arm and every bulk
927
+ control would render inert. */
928
+ manager
929
+ viewer={viewer}
930
+ onSetFieldsHidden={onSetFieldsHidden}
931
+ onShareFields={onShareFields}
932
+ onReassignFields={onReassignFields}
933
+ onDeleteFields={onDeleteFields}
934
+ onRemoveField={onRemoveField}
935
  />
936
  )}
937
  </Popover>
 
988
  fieldByKey={fieldByKey}
989
  sorts={sorts}
990
  onSorts={onSorts}
991
+ filterTree={filterTree}
992
  />
993
  )}
994
  </Popover>
 
1323
  className="cg-count cg-count-pending"
1324
  title={
1325
  `${unresolvedCount} condition${unresolvedCount === 1 ? "" : "s"} cannot be ` +
1326
+ "evaluated: a date that does not resolve, or a list this view refers to that no " +
1327
  "longer exists. Rows are hidden rather than shown under a count that would be wrong."
1328
  }
1329
  >
 
1346
  <span
1347
  className="cg-count cg-count-partial"
1348
  title={
1349
+ `Loading the rest of your ${nouns} in the background. You can browse, ` +
1350
  "filter and sort what is already here."
1351
  }
1352
  >
web/src/customer-grid/ViewSidebar.tsx CHANGED
@@ -1,4 +1,4 @@
1
- import { useMemo, useState } from "react";
2
  import type { ReactNode } from "react";
3
  import type { KeyboardEvent as ReactKeyboardEvent } from "react";
4
  import { AnchoredOverlay } from "./OverlaySurface";
@@ -44,6 +44,7 @@ import { FolderMark, LockMark, MenuLabel, ModeIcon, ToneModeIcon } from "./icons
44
  */
45
  import { WORKSPACE_STALE_EVENT, signal } from "../apiContract";
46
  import { ROOT_FOLDER_ID } from "./folders";
 
47
  // ⭐ W32-T23 (owner item 17) β€” THE BELL, from the shared layer rather than redrawn here.
48
  // The alert row wore `cohortAdd` (a LIST with a plus), which names "add to a cohort" on the
49
  // one row that creates an ALERT β€” a borrowed mark is a small lie a menu repeats every time
@@ -55,11 +56,18 @@ import { BellIcon, StarIcon } from "../ui/icons";
55
  // ⚠ `SHARED_FOLDER_ID` is no longer imported: W34-T25 replaced both of its call sites with
56
  // `isSyntheticFolderId`, and `noUnusedLocals` turns a leftover import into a build error rather
57
  // than into dead weight. The constant itself is still exported and still used by `folders.ts`.
 
 
 
58
  import {
59
- folderHiddenByCollapse,
60
  folderNesting,
 
 
 
 
61
  groupByFolder,
62
  isSyntheticFolderId,
 
63
  mayFileView,
64
  mayNestFolder,
65
  reorderFolderIds,
@@ -467,13 +475,17 @@ interface ViewSidebarProps {
467
  * *"a folder shared to another user reverts to the default folder icon"*, and the cause is that
468
  * the wire has never carried one: `core/grid_events.py::_granted_views` stamps
469
  * `v['sharedFolder'] = <the folder's NAME>`, a string, so the receiver's rail synthesises a group
470
- * from a name and an owner and there is nothing for an icon to travel in. C9 replaces that string
471
- * with the whole folder RECORD β€” and **that half is W41-T14's, in another lane's file.**
 
 
 
472
  *
473
- * ⚠ SO BOTH SHAPES ARE READ, and the older one is not a fallback but TODAY. A string yields a
474
- * name with no icon, which renders the DEFAULT mark exactly as it does now: an absent key means
475
- * "not built yet", never "guess". Nothing paints a mark the sharer did not choose while T14 is
476
- * outstanding, and the day it lands this reader needs no second change.
 
477
  *
478
  * ⚠ THE ICON GOES THROUGH `cleanFolderIcon`, the same whitelist the create pane and the host
479
  * validator use. An unknown shape drops the icon rather than substituting a picture nobody
@@ -493,11 +505,41 @@ function sharedFolderRecord(
493
  via && typeof via === "object" && !Array.isArray(via)
494
  ? (via as Record<string, unknown>)
495
  : null;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
496
  const rawName = typeof via === "string" ? via : record?.name;
497
  const name = typeof rawName === "string" ? rawName.trim() : "";
498
  const owner = typeof view.owner === "string" ? view.owner.trim() : "";
499
  if (!name || !owner) return null;
500
- const icon = record ? cleanFolderIcon(record.icon) : undefined;
 
 
501
  return icon ? { name, owner, icon } : { name, owner };
502
  }
503
 
@@ -544,6 +586,92 @@ function FolderIconPicker({
544
  );
545
  }
546
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
547
  export default function ViewSidebar({
548
  agentPanel = null,
549
  agentOpen = false,
@@ -621,44 +749,62 @@ export default function ViewSidebar({
621
  const exportView = exportFor
622
  ? views.find((view) => view.id === exportFor.viewId)
623
  : undefined;
 
 
 
 
 
 
 
 
 
 
 
 
 
624
  const addView = addFor ? views.find((view) => view.id === addFor.viewId) : undefined;
625
  const menuView = menu ? views.find((view) => view.id === menu.viewId) : undefined;
626
  /** C4 β€” may this viewer change the menu view's IDENTITY? Courtesy only; the host is the
627
  * wall. C3's lock toggle ANDs with this rather than replacing it: the two contracts
628
  * compose (C4 says who may edit, C3 says who may freeze the mode). */
629
  const canEditMenuView = !!menuView && mayEditView(menuView, viewer);
630
- // I11c local UI state. Collapse is deliberately LOCAL (C4: "minimize state
631
- // local") β€” which folders you have open is a per-person, per-session habit,
632
- // not a property of the shared workspace.
633
  /**
634
- * ⭐⭐ WAVE 41 Β· T34 (instruction 13) β€” THE STATE IS "WHICH FOLDERS THE USER OPENED", AND THE
635
- * COLLAPSED SET IS DERIVED FROM IT.
 
 
 
 
 
636
  *
637
- * Owner: *"When a user logs in, a folder defaults to CLOSED, not open."* This used to hold the
638
- * collapsed ids, so an empty set β€” the state every mount starts in β€” meant every folder OPEN,
639
- * the exact opposite of the instruction. Inverting the question is what makes the default fall
640
- * out of the initial state instead of having to be installed into it.
641
  *
642
- * β›” WHY NOT SEED THE COLLAPSED SET INSTEAD. `useState(() => new Set(folderIds))` captures the
643
- * folders present at FIRST RENDER only, and this rail mounts before its workspace lands, so on
644
- * the real load order it would seed from an EMPTY list and every folder would still open. Every
645
- * folder arriving later β€” the workspace payload, a newly granted share, a folder T33's nesting
646
- * reveals β€” would be open too. The `useEffect`-collapses-new-arrivals variant fixes the
647
- * membership but paints one frame with everything open first, so "on first load every folder is
648
- * collapsed" would be false for exactly as long as a user can see it.
649
  *
650
- * β›” NOTHING BUT THE USER'S OWN TOGGLE EVER REMOVES AN ID FROM HERE, which is the whole of
651
- * "expanding one and returning later keeps it expanded". A folder that leaves the list and
652
- * comes back (a live search, a refreshed payload) keeps its id in this set and returns open.
653
- * The set therefore also retains ids of deleted folders; at `MAX_FOLDERS` = 60 and a lifetime
654
- * bounded by the component's, that is a rounding error, and pruning it is what would
655
- * re-introduce the "opened folder silently re-closes" bug.
 
656
  *
657
- * ⚠ SESSION HERE MEANS THE COMPONENT'S LIFETIME, deliberately. There is no localStorage and no
658
- * server preference, and adding one would defeat instruction 13's own first clause: a
659
- * preference that survives a reload is a folder that is open when the user next logs in.
 
 
 
660
  */
661
- const [opened, setOpened] = useState<Set<string>>(new Set());
662
  const [folderMenu, setFolderMenu] = useState<{ id: string; anchor: HTMLElement } | null>(null);
663
  /**
664
  * ⭐ W41-T35 (instruction 11) β€” WHICH FOLDER'S MARK IS BEING CHANGED, and off which button.
@@ -849,6 +995,39 @@ export default function ViewSidebar({
849
  () => folderNesting(foldersOn ? (folders as GridFolder[]) : []),
850
  [foldersOn, folders]
851
  );
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
852
  /**
853
  * ⭐⭐ WAVE 41 Β· T37 (owner instruction 14) β€” THE GROUPING RUNS ONCE PER INPUT CHANGE, NOT
854
  * ONCE PER RENDER.
@@ -939,9 +1118,13 @@ export default function ViewSidebar({
939
  * `groupByFolder` keys with β€” over the record `sharedFolderRecord` returns to BOTH. One
940
  * extractor, one key function, so no second spelling of "which folder is this" exists.
941
  *
942
- * ⚠ EMPTY UNTIL W41-T14 LANDS. The wire carries a folder NAME today, so no entry is ever
943
- * written and every shared folder head falls through to `FolderMark`'s default β€” which is what
944
- * the rail already draws. The gap is a missing icon, never a wrong one.
 
 
 
 
945
  */
946
  const sharedFolderIcons = useMemo(() => {
947
  const marks = new Map<string, FolderIcon>();
@@ -952,43 +1135,194 @@ export default function ViewSidebar({
952
  return marks;
953
  }, [shownViews]);
954
  /**
955
- * ⭐⭐ WAVE 41 Β· T34 (instruction 13) β€” WHICH FOLDERS ARE SHUT RIGHT NOW.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
956
  *
957
- * Read as "every folder head on screen that the user has not opened", so a folder nobody has
958
- * touched is closed WHENEVER it appears β€” at mount, and equally when it arrives afterwards.
959
- * That is the same sentence as `opened` above, from the rendering side, and it is why no
960
- * effect, no ref of already-seen ids and no second render are needed to hold the default.
961
  *
962
- * β›” DERIVED FROM `groups`, NOT FROM `folders`, AND THE CHEVRON IS WHY. `groupByFolder` emits
963
- * one group per stored folder (empty ones included) AND the synthesised groups β€” "Shared with
964
- * me", plus one per shared folder β€” which own a folder head and a working disclosure chevron
965
- * while having no record in `folders` at all. Derived from the stored list, those ids could
966
- * never enter this set: their chevron would write to `opened` and nothing would ever read it
967
- * back, so the toggle would be DEAD and the group permanently open. Reading the groups also
968
- * settles instruction 13 for them the same way it settles it for a stored folder, which is
969
- * what the user sees: a folder head is a folder head. Collapse is presentation with no write
970
- * behind it, so `isSyntheticFolderId` β€” the guard that keeps `item_move` / `folder_rename` off
971
- * these ids β€” has nothing to say here.
 
 
 
 
 
 
972
  *
973
- * β›”β›” A LIVE SEARCH YIELDS, and without this clause T34 would silently kill W41-T33. Search
974
- * hides folders that matched nothing (below) and T33 taught it to KEEP a parent whose child
975
- * matched. With every folder shut by default, `folderHiddenByCollapse` drops those descendants
976
- * before they can render and the survivors show as bare heads with no rows: the user types a
977
- * view's name and the rail answers with chevrons and nothing else, on the very first search of
978
- * every session. So while a needle is live nothing is collapsed. It is presentation only and
979
- * it never touches `opened`, so clearing the search returns each folder to exactly the state
980
- * the user left it in.
981
  */
982
- const collapsed = useMemo(() => {
983
- const shut = new Set<string>();
984
- if (!viewNeedle) {
985
- for (const group of groups) {
986
- const id = group.folder?.id;
987
- if (id && !opened.has(id)) shut.add(id);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
988
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
989
  }
990
- return shut;
991
- }, [groups, opened, viewNeedle]);
992
  const folderMenuF = folderMenu ? folders?.find((f) => f.id === folderMenu.id) : undefined;
993
  /**
994
  * ⭐⭐ W41-T35 β€” THE FOLDER WHOSE MARK IS BEING CHANGED, AND THE SECOND REFUSAL OF A SYNTHETIC
@@ -1015,30 +1349,10 @@ export default function ViewSidebar({
1015
  * the SAME `nesting` the rail renders from, so the verdict and the picture cannot disagree.
1016
  */
1017
  const nestHere = folderMenuF ? mayNestFolder(nesting, folderMenuF.id) : null;
1018
- /**
1019
- * ⭐ WAVE 41 Β· T33 β€” THE ANCESTORS OF EVERY FOLDER A SEARCH MATCHED INSIDE.
1020
- *
1021
- * Item 9's rule ("a folder with no matches is noise") was written when a folder could only
1022
- * hold views. A parent now holds folders too, so its own `items` being empty says nothing
1023
- * about whether anything under it matched β€” and hiding it would orphan the child that did.
1024
- *
1025
- * ⚠ BUILT ONLY WHILE A SEARCH IS LIVE. With no needle the set is never walked and the rule it
1026
- * serves never fires, so the idle rail pays nothing for it.
1027
- */
1028
- const searchKeepsFolder = useMemo(() => {
1029
- const keep = new Set<string>();
1030
- if (viewNeedle) {
1031
- for (const g of groups) {
1032
- if (!g.folder || g.items.length === 0) continue;
1033
- let up = nesting.parent[g.folder.id] ?? null;
1034
- while (up && !keep.has(up)) {
1035
- keep.add(up);
1036
- up = nesting.parent[up] ?? null;
1037
- }
1038
- }
1039
- }
1040
- return keep;
1041
- }, [groups, nesting, viewNeedle]);
1042
  const addPreview = addTarget && folderAddPreview ? folderAddPreview(addTarget) : null;
1043
  /**
1044
  * ONE pair of drop handlers per group, serving TWO drags β€” a view being filed into this
@@ -1174,24 +1488,21 @@ export default function ViewSidebar({
1174
  // folder can always go.
1175
  const into = mayNestFolder(nesting, folderParent).ok ? folderParent : null;
1176
  /**
1177
- * ⭐⭐ WAVE 41 Β· T34 β€” FILING A FOLDER INTO ONE OPENS IT, or the new folder is created
1178
- * INVISIBLY.
1179
- *
1180
- * β›” THIS IS T34's OWN REGRESSION ON T33, and it only exists once folders default to shut.
1181
- * A collapsed folder KEEPS ITS HEAD (`folderHiddenByCollapse` reads ancestors only), so its
1182
- * "…" menu β€” and T33's "New folder inside" row on it β€” stays reachable while it is closed.
1183
- * Create a folder in there and `folderHiddenByCollapse` finds the shut parent above the new
1184
- * child and renders it as null: the user names a folder, presses Create, and the rail does
1185
- * not move. Before T34 the parent was open by default and the path could not be walked.
1186
  *
1187
- * ⚠ THE PARENT ALONE IS ENOUGH, no ancestor walk. The head that carries this menu renders
1188
- * only when NO ancestor of it is collapsed, so reaching this line already proves every
1189
- * folder above `into` is open.
 
 
 
1190
  *
1191
- * ⚠ IT CAN ONLY ADD. Nothing here removes an id, so this cannot close a folder the user
1192
- * opened, and the same-set short-circuit keeps a repeat create from re-rendering the rail.
 
1193
  */
1194
- if (into) setOpened((prev) => (prev.has(into) ? prev : new Set(prev).add(into)));
1195
  // cleanFolderIcon returns undefined for the all-defaults pair, so a folder the user
1196
  // never restyled stays byte-identical to a pre-wave-9 one (the no-churn rule).
1197
  onFolderCreate?.(value, cleanFolderIcon(folderIcon), into);
@@ -1645,31 +1956,69 @@ export default function ViewSidebar({
1645
  </AnchoredOverlay>
1646
  )}
1647
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1648
  <div className="cg-view-list cg-views-scroll">
1649
- {groups.map((group) => {
1650
  const gid = group.folder?.id ?? null;
1651
- // Item 9 β€” while a search is live, a folder with no matches is noise, not a target.
1652
- // ⭐ W41-T33 β€” …UNLESS A FOLDER INSIDE IT MATCHED. Once folders nest, "no matching views
1653
- // of its own" and "nothing under here at all" stop being the same fact: dropping a
1654
- // parent on the first would leave its matching child indented under whatever row
1655
- // happened to precede it, attached to the wrong folder on screen.
1656
- if (viewNeedle && group.folder && group.items.length === 0
1657
- && !searchKeepsFolder.has(group.folder.id)) return null;
1658
  /**
1659
- * ⭐⭐ WAVE 41 Β· T33 (instruction 12, R1) β€” HOW DEEP THIS FOLDER SITS, AND WHETHER IT
1660
- * SHOWS AT ALL.
1661
  *
1662
- * ⚠ A SYNTHETIC GROUP HAS NO ENTRY IN `nesting` and must not acquire one: `__shared__`
1663
- * and every `__sharedfld__:` group are a reading of the view list, not records, so they
1664
- * fall to level 1 and to "not hidden" β€” which is exactly where they rendered before this
1665
- * ticket. The same is true of both `folder: null` groups.
 
 
 
1666
  */
1667
- const depth = gid ? nesting.depth[gid] ?? 1 : 1;
1668
- // β›” A FOLDER INSIDE A COLLAPSED FOLDER DOES NOT RENDER. `shut` below hides a folder's
1669
- // VIEWS; without this its child FOLDERS would keep their rows and stay indented under a
1670
- // parent that is no longer showing anything, which reads as the collapse having half
1671
- // worked. Ancestors only, so the collapsed folder itself keeps the head you re-open it by.
1672
- if (gid && folderHiddenByCollapse(nesting, gid, collapsed)) return null;
1673
  /**
1674
  * ⭐⭐ WAVE 40 Β· T28 (owner instruction 30) β€” THE PIN GROUP: the unfiled default views,
1675
  * rendered above every folder.
@@ -1705,32 +2054,43 @@ export default function ViewSidebar({
1705
  // "Shared with me" while offering them on a colleague's folder would emit `item_move` /
1706
  // `folder_rename` / `folder_delete` against an id that exists in nobody's store.
1707
  const isSynthetic = isSyntheticFolderId(gid);
1708
- const shut = gid != null && collapsed.has(gid);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1709
  return (
1710
  <div
1711
  /* ⭐ W40-T28 β€” a key of its own. Both this group and the ungrouped section have a null
1712
  folder, so the old `gid ?? "__root__"` would give React two children with the same
1713
  key and it would reconcile one over the other. */
1714
  key={isPinnedGroup ? "__pinned__" : gid ?? "__root__"}
1715
- /**
1716
- * ⭐⭐ WAVE 41 Β· T33 (instruction 12) β€” A NESTED FOLDER IS THIS ROW, INDENTED.
1717
- *
1718
- * DESIGN.md Β§4: new nav joins the existing rhythm and never introduces a control
1719
- * shape. 12px is not a new number either β€” it is the step `.cg-fold .cg-view-row`
1720
- * already uses to set a view in from its folder head, so a folder inside a folder
1721
- * lands exactly where a view inside a folder lands, one level on.
1722
- *
1723
- * ⚠ INLINE BECAUSE THE DEPTH IS DATA, not because the rail is short of a class. A
1724
- * stylesheet would need one rule per level to a cap the model owns, and the two
1725
- * numbers would then have to be kept equal by hand.
1726
- */
1727
- style={depth > 1 ? { marginLeft: (depth - 1) * 12 } : undefined}
1728
  className={
1729
  /* ⭐ W40-T28 β€” `gid === null`, not `isRoot`: the pin group wears the SAME class as
1730
  the ungrouped section (no head, the rail's measured root indent) because it is the
1731
  same shape of thing rendered in a different place. DESIGN.md Β§4 β€” this is an
1732
- existing element joining the existing rhythm, not a new control shape. */
1733
- (gid === null ? "cg-fold-root" : "cg-fold") +
 
 
 
 
1734
  (!isPinnedGroup && dropTarget === (gid ?? "__root__") ? " is-drop" : "") +
1735
  // Item 19 β€” the insertion rule reads "the folder you are dragging lands HERE":
1736
  // above this folder, or above the ungrouped section, which is after them all.
@@ -1766,7 +2126,11 @@ export default function ViewSidebar({
1766
  // at `null` beside a `gid` that is `null` for this very section β€” that is the
1767
  // `foldDrag === gid` trap two lines up, which faded the whole ungrouped section
1768
  // permanently once already. `isRoot` is a separate boolean, so the two cannot collide.
1769
- (isRoot && viewDrag !== null ? " is-viewdrop" : "")
 
 
 
 
1770
  }
1771
  {/* No drop handlers on the synthetic group β€” see `isSynthetic`. Spreading `{}`
1772
  rather than branching the element keeps ONE render path for every group.
@@ -1777,7 +2141,11 @@ export default function ViewSidebar({
1777
  somewhere else on screen. The ungrouped section below is the one root target. */
1778
  ...(isSynthetic || isPinnedGroup ? {} : dropHandlers(gid))}
1779
  >
1780
- {group.folder && (
 
 
 
 
1781
  <div
1782
  className="cg-fold-head"
1783
  // ── Item 19 β€” the folder itself is the drag handle ─────────────────────
@@ -1799,38 +2167,31 @@ export default function ViewSidebar({
1799
  flow shifts the folder's name to the right, and this rail's indent is
1800
  MEASURED to the pixel (index.css: "root view name 41.00px / folder header
1801
  48.36px" β€” the whole point of the wave-10 item-2 fix); the gutter it would
1802
- otherwise hide in is already occupied by the disclosure chevron, whose
1803
- open/shut state is the only one this row has. The view rows above have been
1804
  draggable with no handle since wave 8, so a folder that drags the same way
1805
  is the vocabulary this list already teaches, not a hidden feature. */}
1806
  <button
1807
  type="button"
1808
  className="cg-fold-toggle"
1809
- aria-expanded={!shut}
1810
  /**
1811
- * ⚠ W41-T34 β€” THE CLICK IS READ OFF `shut`, THE STATE THE CHEVRON IS DRAWING,
1812
- * not off membership of `opened`.
1813
  *
1814
- * With no search live the two are the same sentence and this behaves exactly as
1815
- * the old symmetric toggle did. They come apart during a SEARCH, which shows
1816
- * every folder open whatever `opened` holds: keyed on membership, clicking the
1817
- * chevron of a folder the user had never opened would ADD it β€” the row would not
1818
- * move, because the search is still forcing it open, and the folder would then be
1819
- * open once the search cleared. The user pressed "close" and got "open", one
1820
- * gesture later. Reading the drawn state makes the click mean what it looks like.
 
 
 
 
1821
  */
1822
- onClick={() =>
1823
- setOpened((prev) => {
1824
- const next = new Set(prev);
1825
- if (shut) next.add(group.folder!.id);
1826
- else next.delete(group.folder!.id);
1827
- return next;
1828
- })
1829
- }
1830
  >
1831
- <span className={"cg-fold-chev" + (shut ? " is-shut" : "")} aria-hidden>
1832
- β–Ύ
1833
- </span>
1834
  {/* I14/I15 β€” the folder wears its chosen mark; a folder that never chose one
1835
  (every pre-wave-9 folder) renders the default grey folder shape, which is
1836
  precisely "existing folders get the folder icon". */}
@@ -1845,8 +2206,9 @@ export default function ViewSidebar({
1845
  β›” AND THE FALLBACK IS `undefined`, WHICH IS THE ANSWER RATHER THAN A GAP:
1846
  `FolderMark` draws the default folder in the default tone for an absent icon,
1847
  which is exactly what "the payload does not carry one yet" should look like.
1848
- Until W41-T14 puts the folder RECORD on the wire this map is empty and this
1849
- line renders precisely what it rendered before. */}
 
1850
  <FolderMark
1851
  icon={group.folder.icon ?? (gid ? sharedFolderIcons.get(gid) : undefined)}
1852
  size={16}
@@ -1932,9 +2294,11 @@ export default function ViewSidebar({
1932
  )}
1933
  </div>
1934
  )}
1935
- {/* A collapsed folder hides its rows but stays a DROP TARGET, so you can
1936
- file something into a folder you have tidied away. */}
1937
- {!shut &&
 
 
1938
  group.items.map((view) => {
1939
  const active = view.id === activeViewId;
1940
  const renaming = renamingId === view.id;
@@ -2239,7 +2603,13 @@ export default function ViewSidebar({
2239
  </div>
2240
  );
2241
  })}
2242
- {group.folder && !shut && group.items.length === 0 && (
 
 
 
 
 
 
2243
  <div className="cg-fold-empty">Empty. Drag a view here.</div>
2244
  )}
2245
  </div>
@@ -2426,26 +2796,43 @@ export default function ViewSidebar({
2426
  </AnchoredOverlay>
2427
  )}
2428
 
2429
- {/* ⭐⭐ WAVE 41 Β· T35 (owner instruction 11) β€” THE CHANGE-ICON PANEL.
2430
- It is the folder menu's own panel shape (`cg-view-menu`, `bottom-end`, the same anchor
2431
- the "…" gave the menu), holding the SAME picker the create pane holds. No new class and
2432
- no new CSS: DESIGN.md Β§4 asks new nav to join the existing rhythm, and `.cg-fold-pick`
2433
- is already a top-level rule rather than one scoped to the create form.
 
 
 
 
 
 
2434
  ⚠ IT WRITES ON EVERY CLICK rather than behind a Save. Shape and tone are two independent
2435
  picks and the folder head repaints under the panel as they land, so the panel IS the
2436
  preview β€” a confirm step would put a button between the user and a change they can see
2437
  and undo by clicking again (Β§4, never over-explain). Dismissing is therefore not a
2438
- cancel, and nothing here pretends it is. */}
 
 
 
 
 
 
 
2439
  {iconMenu && iconMenuF && onFolderIconChange && (
2440
  <AnchoredOverlay
2441
  anchor={iconMenu.anchor}
2442
- className="cg-view-menu"
2443
  placement="bottom-end"
2444
  role="dialog"
2445
  ariaLabel={`Icon for folder ${iconMenuF.name}`}
2446
  onDismiss={() => setIconMenu(null)}
2447
  dataKind="folder-icon"
2448
  >
 
 
 
 
2449
  {/* ⚠ RESOLVED AGAINST THE DEFAULTS RATHER THAN PASSED AS `undefined`: the picker draws
2450
  a selection ring on the swatch that is currently chosen, and a folder that never
2451
  chose an icon IS wearing the default shape in the default tone (`FolderMark` reads
@@ -2461,6 +2848,93 @@ export default function ViewSidebar({
2461
  </AnchoredOverlay>
2462
  )}
2463
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2464
  {/* Item 12 (C-LOCK) β€” the lock picker. Lists the cohorts this reader can see, marks the
2465
  current one, and offers Unlock when there is one: a lock removable only from
2466
  somewhere other than where it was applied is a trap, and the owner asked for a
@@ -2719,6 +3193,30 @@ export default function ViewSidebar({
2719
  >
2720
  <MenuLabel icon="duplicate" text="Duplicate" />
2721
  </button>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2722
  {/* WAVE 20 items 23/26 (R10) β€” "who else can reach this view", the same
2723
  editor a folder and a database open. Deliberately NOT gated on
2724
  `canEditMenuView`: the server decides who may administer (owner or
 
1
+ import { useEffect, useMemo, useState } from "react";
2
  import type { ReactNode } from "react";
3
  import type { KeyboardEvent as ReactKeyboardEvent } from "react";
4
  import { AnchoredOverlay } from "./OverlaySurface";
 
44
  */
45
  import { WORKSPACE_STALE_EVENT, signal } from "../apiContract";
46
  import { ROOT_FOLDER_ID } from "./folders";
47
+ import { pathStorageKey, resolveStoredPath } from "./viewEcho";
48
  // ⭐ W32-T23 (owner item 17) β€” THE BELL, from the shared layer rather than redrawn here.
49
  // The alert row wore `cohortAdd` (a LIST with a plus), which names "add to a cohort" on the
50
  // one row that creates an ALERT β€” a borrowed mark is a small lie a menu repeats every time
 
56
  // ⚠ `SHARED_FOLDER_ID` is no longer imported: W34-T25 replaced both of its call sites with
57
  // `isSyntheticFolderId`, and `noUnusedLocals` turns a leftover import into a build error rather
58
  // than into dead weight. The constant itself is still exported and still used by `folders.ts`.
59
+ // ⚠ `folderHiddenByCollapse` is no longer imported: W42-T43 replaced the whole expand/collapse
60
+ // tree with a path (R12.2), so this rail has no ancestor to be hidden by. The function is still
61
+ // exported from `folders.ts` and still belongs to that file's own contract.
62
  import {
 
63
  folderNesting,
64
+ // ⭐⭐ W42-T43 (C9) β€” the ONE path resolver over both folder systems, from W42-T41.
65
+ // `folderPath` is the breadcrumb (outermost first); `levelAt` answers which folders are the
66
+ // CHILDREN of where the user is standing, which is the whole of the drill.
67
+ folderPath,
68
  groupByFolder,
69
  isSyntheticFolderId,
70
+ levelAt,
71
  mayFileView,
72
  mayNestFolder,
73
  reorderFolderIds,
 
475
  * *"a folder shared to another user reverts to the default folder icon"*, and the cause is that
476
  * the wire has never carried one: `core/grid_events.py::_granted_views` stamps
477
  * `v['sharedFolder'] = <the folder's NAME>`, a string, so the receiver's rail synthesises a group
478
+ * from a name and an owner. ⭐ W42-T18 CLOSED THAT HALF, and it closed it as a SECOND KEY rather
479
+ * than a replacement: the host sends the folder RECORD alongside, on `sharedFolderRecord`
480
+ * (`grid_events.py::_shared_folder_record`), while `sharedFolder` stays the plain name string
481
+ * that `verify_folders.py` and `verify_api.py` both pin. So the icon has somewhere to travel and
482
+ * the string contract is untouched.
483
  *
484
+ * ⚠ SO BOTH SHAPES ARE READ, and the string one is not a fallback but TODAY's name source. The
485
+ * NAME comes from the string; the ICON comes from the record. A payload with no record, or with
486
+ * a record carrying no icon, yields a name with no icon and renders the DEFAULT mark: an absent
487
+ * key means "the owner chose none", never "guess". Nothing paints a mark the sharer did not
488
+ * choose.
489
  *
490
  * ⚠ THE ICON GOES THROUGH `cleanFolderIcon`, the same whitelist the create pane and the host
491
  * validator use. An unknown shape drops the icon rather than substituting a picture nobody
 
505
  via && typeof via === "object" && !Array.isArray(via)
506
  ? (via as Record<string, unknown>)
507
  : null;
508
+ /**
509
+ * ⭐⭐ WAVE 42 Β· T18 β€” THE SECOND SOURCE, AND THE NAME COLLISION IS DELIBERATE.
510
+ *
511
+ * β›” `sharedFolderRecord` IS BOTH THIS FUNCTION AND A WIRE KEY. The server named its key after
512
+ * what this function returns, so `wireRec` below is `v['sharedFolderRecord']` off the payload
513
+ * and has nothing to do with the enclosing function. A grep for the bare name finds this
514
+ * function four times over; only `.sharedFolderRecord` finds the wire field.
515
+ *
516
+ * β›” ONLY THE `icon` IS TAKEN. The record also carries `id`, which is the SENDER's folder id
517
+ * and collides with `groupByFolder`'s id namespace β€” the receiver's group id is synthesised by
518
+ * `sharedFolderGroupId(owner, name)`, so borrowing `rec.id` would key a group on a folder that
519
+ * does not exist in this user's store. `name` keeps coming from the string, which is what
520
+ * `grid_events.py` stamps on `sharedFolder` and what two gates pin as a string contract.
521
+ *
522
+ * ⚠ PRECEDENCE: an inline object on `sharedFolder` WINS over the wire record. The reason is
523
+ * that the name and the icon then come from one object, so they cannot describe two different
524
+ * folders. This is documentation today rather than behaviour: `sharedFolder` is a string in
525
+ * every real payload, so the wire record is what actually supplies the icon.
526
+ *
527
+ * ⚠ A malformed, absent, array-shaped or icon-less record degrades to no icon and the rail
528
+ * draws `FolderMark`'s default. `cleanFolderIcon` is the same whitelist the create pane uses,
529
+ * so an unknown shape drops the mark rather than inventing one nobody picked.
530
+ */
531
+ const wireRec = (view as { sharedFolderRecord?: unknown }).sharedFolderRecord;
532
+ const granted =
533
+ wireRec && typeof wireRec === "object" && !Array.isArray(wireRec)
534
+ ? (wireRec as Record<string, unknown>)
535
+ : null;
536
  const rawName = typeof via === "string" ? via : record?.name;
537
  const name = typeof rawName === "string" ? rawName.trim() : "";
538
  const owner = typeof view.owner === "string" ? view.owner.trim() : "";
539
  if (!name || !owner) return null;
540
+ const icon =
541
+ (record ? cleanFolderIcon(record.icon) : undefined) ??
542
+ (granted ? cleanFolderIcon(granted.icon) : undefined);
543
  return icon ? { name, owner, icon } : { name, owner };
544
  }
545
 
 
586
  );
587
  }
588
 
589
+ // ── WAVE 42 Β· T45 (ruling R12, contract C9): THE BROWSER HALF OF "the path is where I left it" ──
590
+ //
591
+ // R12.6 chose PER-BROWSER persistence of the rail's open folder over always resetting to the top
592
+ // level, and over putting the path in the URL. The URL option was judged the more useful one and
593
+ // is booked as O4; it is deliberately NOT built here.
594
+ //
595
+ // β›”β›” WHY THIS IS IN THE COMPONENT FILE AND NOT IN `viewEcho.ts`. `verify_view_echo.py` compiles
596
+ // `_test/viewEcho.test.ts` and runs it under BARE NODE β€” no jsdom, no `window`, no
597
+ // `localStorage`, and the test installs no shim. Anything touching `window` in that module would
598
+ // be untestable by its own gate: both databases would fall into the same `catch` and answer
599
+ // identically, so "two databases keep separate positions" would go green over nothing. So the
600
+ // module keeps the two PURE pieces the gate can actually prove (`pathStorageKey`,
601
+ // `resolveStoredPath`) and the three `window` reads live here, beside the `aios-views-rail`
602
+ // try/catch this file already owns.
603
+ //
604
+ // β›”β›” THE ACCESSOR ITSELF THROWS. In a private window, with site data cleared, or in a browser
605
+ // configured to block storage, `window.localStorage` throws on PROPERTY ACCESS β€” not on
606
+ // `getItem`. So the familiar `typeof window !== "undefined" && window.localStorage` feature test
607
+ // IS the throwing expression, and it must sit INSIDE the `try`, never in front of it. A rail that
608
+ // throws on mount is a blank shell, so all three helpers are total: they answer a value, or they
609
+ // do nothing.
610
+
611
+ /**
612
+ * The database this browser is remembering a position for, taken from the route.
613
+ *
614
+ * ⚠ DELIBERATE DUPLICATION, NAMED SO IT READS AS A TRADE RATHER THAN AS DRIFT. The canonical
615
+ * transform is `shell/nav.ts::routeKeyOf`; this is a second copy of it. The import is REFUSED
616
+ * because it would INVERT the layering: `shell/` imports `customer-grid/` seventeen times, so
617
+ * this is the LOWER layer, and importing upward is the front-end reading of CLAUDE.md's "core
618
+ * never imports up". Reading the hash from inside `customer-grid` is already precedent
619
+ * (`CustomerGrid.tsx:1020` tests `window.location.hash.startsWith("#/query")`).
620
+ *
621
+ * ⚠ THE ROUTE AND NOT A PROP: this component takes 42 props and not one carries a database key,
622
+ * and it is mounted from `CustomerGrid.tsx`, another lane's file. The hash IS the database
623
+ * identity here β€” the shell itself resolves a database from the route rather than from the rail,
624
+ * because a person reaches one from Home, Starred, a notification or a bookmark.
625
+ *
626
+ * ⚠ SCOUTED, so the next reader need not: a database route's hash is exactly `#/<databaseKey>`
627
+ * (`shell/Shell.tsx:1105`) with no query string and no sub-path, and the active view or tab is
628
+ * never encoded into it. That is what makes this key stable for as long as the viewer stays in
629
+ * one database, which is what "remembered per database, across a reload" rests on. The `?` and
630
+ * nested-`#` stripping reproduced here is pinned by `shell/_test/shell.test.ts:1152`.
631
+ *
632
+ * ⚠ An unreadable hash and an absent one both answer `""`. That collapses every unidentifiable
633
+ * route onto one key, which is harmless β€” no database identity means no position worth keeping β€”
634
+ * but it is NOT per-route isolation and must not be read as such.
635
+ */
636
+ function railDbKey(): string {
637
+ try {
638
+ const hash = window.location.hash;
639
+ return typeof hash === "string" ? hash.replace(/^#\/?/, "").split("?")[0].split("#")[0] : "";
640
+ } catch {
641
+ return "";
642
+ }
643
+ }
644
+
645
+ /** The folder id this browser last had open for `dbKey`, RAW and still UNRESOLVED: it names a
646
+ * folder that may since have been deleted, so it is only ever handed to `resolveStoredPath`
647
+ * before anything is rendered from it. `null` for absent, blocked, wrong type or empty. */
648
+ function readRailPath(dbKey: string): string | null {
649
+ try {
650
+ const raw = localStorage.getItem(pathStorageKey(dbKey));
651
+ return typeof raw === "string" && raw !== "" ? raw : null;
652
+ } catch {
653
+ return null;
654
+ }
655
+ }
656
+
657
+ /**
658
+ * Remember (or forget) this browser's position for `dbKey`. `null` β€” the top level β€” REMOVES the
659
+ * entry rather than storing a sentinel, so "never visited" and "back at the top" are one state
660
+ * with one representation.
661
+ *
662
+ * Silent on failure by design: storage being blocked or full must not turn opening a folder into
663
+ * an error the viewer sees. Losing the memory is the correct degradation.
664
+ */
665
+ function writeRailPath(dbKey: string, folderId: string | null): void {
666
+ try {
667
+ const key = pathStorageKey(dbKey);
668
+ if (folderId) localStorage.setItem(key, folderId);
669
+ else localStorage.removeItem(key);
670
+ } catch {
671
+ // blocked, full, or a private window: the position is simply not remembered.
672
+ }
673
+ }
674
+
675
  export default function ViewSidebar({
676
  agentPanel = null,
677
  agentOpen = false,
 
749
  const exportView = exportFor
750
  ? views.find((view) => view.id === exportFor.viewId)
751
  : undefined;
752
+ /**
753
+ * ⭐⭐ WAVE 42 Β· T44 (ruling R12, contract C9) β€” THE "Move to" PICKER, and which view it is
754
+ * open for. It is the SECOND door onto the move the drag already performs, not a replacement:
755
+ * with the rail navigating by path, a view and a folder ten levels away are never on screen
756
+ * together, so drag alone leaves most destinations unreachable. R12.5 chose both doors.
757
+ */
758
+ const [moveFor, setMoveFor] = useState<{
759
+ viewId: string;
760
+ anchor: HTMLButtonElement;
761
+ } | null>(null);
762
+ const moveView = moveFor
763
+ ? views.find((view) => view.id === moveFor.viewId)
764
+ : undefined;
765
  const addView = addFor ? views.find((view) => view.id === addFor.viewId) : undefined;
766
  const menuView = menu ? views.find((view) => view.id === menu.viewId) : undefined;
767
  /** C4 β€” may this viewer change the menu view's IDENTITY? Courtesy only; the host is the
768
  * wall. C3's lock toggle ANDs with this rather than replacing it: the two contracts
769
  * compose (C4 says who may edit, C3 says who may freeze the mode). */
770
  const canEditMenuView = !!menuView && mayEditView(menuView, viewer);
771
+ // I11c local UI state. Where in the folder path you are standing is deliberately LOCAL
772
+ // (C4: "minimize state local") β€” it is a per-person, per-session habit, not a property of
773
+ // the shared workspace.
774
  /**
775
+ * ⭐⭐ WAVE 42 Β· T43 (instruction 16, R12) β€” THE STATE IS WHERE THE USER IS STANDING, AND
776
+ * THE TREE IS GONE.
777
+ *
778
+ * Owner: *"When I click a folder it opens that folder not as a dropdown BUT as a path … it
779
+ * should only show (in the View navigation) what is IN that folder, and I should be able to go
780
+ * back and forth."* R12.2 deletes the twisty, the indentation and every scrap of expand state
781
+ * with it, so what replaced W41-T34's `opened` set is not a smaller set: it is ONE id.
782
  *
783
+ * β›” `null` IS THE TOP LEVEL, never `ROOT_FOLDER_ID`. The resolver accepts the sentinel as an
784
+ * input and reads it as the top, but this rail only ever writes a real folder id or `null`, so
785
+ * "am I at the top" is one comparison everywhere below rather than two.
 
786
  *
787
+ * ⚠ IT MAY NAME A SYNTHETIC GROUP. "Shared with me" and each shared folder own a head on this
788
+ * rail while having no record in `folders`; drilling into one is the same gesture the user just
789
+ * made on a folder of their own, so it is allowed and `atId` below validates against the GROUPS
790
+ * rather than against the stored list.
 
 
 
791
  *
792
+ * ⭐⭐ WAVE 42 · T45 (R12.6) AMENDS THE LINE THAT STOOD HERE. T43 wrote "session here means the
793
+ * component's lifetime … there is no localStorage", on the reasoning that reopening three
794
+ * folders deep on the next login would be the old "a folder is open when the user next logs in"
795
+ * defect wearing a path. R12.6 REVERSED that: the position now survives a reload, PER DATABASE,
796
+ * in this viewer's own browser. The old defect is not what returns, because it was about a
797
+ * SHARED, server-side expand state deciding what everyone saw; this is one browser remembering
798
+ * one person's own last gesture, and it is resolved against the live rail before it is trusted.
799
  *
800
+ * β›” SEEDED RAW, DELIBERATELY. What comes out of storage may name a folder deleted by another
801
+ * session, so it is NOT validated here β€” `atId` below is the single validator, and it re-runs
802
+ * on every render against the groups that actually exist. Seeding through a validator would
803
+ * also be wrong at this instant: the workspace has not arrived at first render
804
+ * [[grid-init-runs-before-the-workspace-arrives]], so `groups` is empty and every stored path
805
+ * would resolve to `null` and be erased before the rail could ever honour it.
806
  */
807
+ const [at, setAt] = useState<string | null>(() => readRailPath(railDbKey()));
808
  const [folderMenu, setFolderMenu] = useState<{ id: string; anchor: HTMLElement } | null>(null);
809
  /**
810
  * ⭐ W41-T35 (instruction 11) β€” WHICH FOLDER'S MARK IS BEING CHANGED, and off which button.
 
995
  () => folderNesting(foldersOn ? (folders as GridFolder[]) : []),
996
  [foldersOn, folders]
997
  );
998
+ /**
999
+ * ⭐⭐ WAVE 42 Β· T44 (R12, C9) β€” MAY THIS VIEWER FILE THE MENU'S VIEW, computed HERE rather
1000
+ * than inline on the row.
1001
+ *
1002
+ * β›” AND THE REASON IS A GATE, WHICH IS WHY IT IS NOT A STYLE CHOICE. `verify_wiring.py`'s
1003
+ * W39-T29 leg reads the 900 code-characters immediately BEFORE the Share view row and fails if
1004
+ * `canEditMenuView` appears in them β€” that is how it proves sharing is offered outside the
1005
+ * edit-only predicate. A "Move to" row written just above Share view with its gate spelled out
1006
+ * inline would drop that identifier straight into the window and turn a correct row into a red
1007
+ * on a claim it has nothing to do with. Named once up here, the row reads `canFileMenuView`.
1008
+ *
1009
+ * ⚠ `mayFileView`, NOT `mayEditView`, matching the DRAG site exactly (W34-T22 / D-249): filing
1010
+ * writes a placement into the reader's own workspace stratum and never touches the owner's
1011
+ * object, so a read-only shared view may still be filed. Two doors onto one move must also
1012
+ * agree about who may open them.
1013
+ */
1014
+ const canFileMenuView =
1015
+ foldersOn && !!menuView && mayFileView(menuView, canEditMenuView);
1016
+ /**
1017
+ * ⭐⭐ WAVE 42 Β· T44 β€” EVERY FOLDER IN THIS DATABASE, DEPTH-FIRST. This is the whole ticket:
1018
+ * the picker offers the FULL tree, not the level the rail happens to be standing on, so a
1019
+ * folder ten deep is one click away from the top level with no navigating.
1020
+ *
1021
+ * β›” SYNTHETIC IDS ARE NOT DESTINATIONS. "Shared with me" and every shared-folder group are
1022
+ * invented by the grouping pass and have no record in the stored list, so filing a view "into"
1023
+ * one would write an id nothing owns β€” the same write `isSyntheticFolderId` exists to stop at
1024
+ * the drop site. They cannot normally reach `folders` at all; the filter is here so that if one
1025
+ * ever does, this picker is not the door that lets it through.
1026
+ */
1027
+ const moveFolders = useMemo(
1028
+ () => nesting.ordered.filter((f) => !isSyntheticFolderId(f.id)),
1029
+ [nesting]
1030
+ );
1031
  /**
1032
  * ⭐⭐ WAVE 41 Β· T37 (owner instruction 14) β€” THE GROUPING RUNS ONCE PER INPUT CHANGE, NOT
1033
  * ONCE PER RENDER.
 
1118
  * `groupByFolder` keys with β€” over the record `sharedFolderRecord` returns to BOTH. One
1119
  * extractor, one key function, so no second spelling of "which folder is this" exists.
1120
  *
1121
+ * ⭐ POPULATED SINCE W42-T18. The wire carries the folder NAME on `sharedFolder` and the folder
1122
+ * RECORD on `sharedFolderRecord`, and `sharedFolderRecord` (the function, four lines of scroll
1123
+ * up from every call site) pulls the icon off the second while still taking the name from the
1124
+ * first. A shared folder whose owner picked a mark now wears that mark here; one whose owner
1125
+ * picked none still falls through to `FolderMark`'s default, which is the right answer rather
1126
+ * than a gap. The map is keyed by the RECEIVER's synthesised group id, never by the sender's
1127
+ * folder id, so nothing here can name a folder this user does not have.
1128
  */
1129
  const sharedFolderIcons = useMemo(() => {
1130
  const marks = new Map<string, FolderIcon>();
 
1135
  return marks;
1136
  }, [shownViews]);
1137
  /**
1138
+ * ⭐⭐ WAVE 42 Β· T43 (instruction 16, R12.1) β€” WHERE THE USER IS ACTUALLY STANDING.
1139
+ *
1140
+ * β›” VALIDATED AGAINST THE GROUPS, NOT AGAINST `folders`, and for the reason the collapsed set
1141
+ * this replaces gave: a synthesised group ("Shared with me", and one per shared folder) owns a
1142
+ * head on this rail while having no record in the stored list, so validating against `folders`
1143
+ * would bounce the user straight back out of a folder they had just opened. A folder that is
1144
+ * deleted, revoked or filtered away while the user stands inside it falls back to the top level
1145
+ * rather than leaving the rail showing an empty level with no way out.
1146
+ *
1147
+ * ⚠ A LIVE SEARCH KEEPS `at` UNTOUCHED. Search flattens across every level (see `levelGroups`),
1148
+ * so `atId` is not read while a needle is live; recomputing it against the SEARCH-FILTERED
1149
+ * groups would silently reset the path, and clearing the search would land the user at the top
1150
+ * instead of back where they were.
1151
+ *
1152
+ * ⭐⭐ WAVE 42 Β· T45 β€” AND THIS IS ALSO THE STALE-STORED-PATH GUARD. There is exactly ONE
1153
+ * definition of "a place I can stand" in this rail, and it is the set below: a path restored
1154
+ * from localStorage is judged by the same expression as a path the user walked to a moment ago.
1155
+ * A second validator for the restored case is the drift C9 exists to prevent, and it would fail
1156
+ * in a specific, near-unreportable way β€” validating against `folders` (which has no record of a
1157
+ * synthesised shared group) would call a live shared folder deleted and bounce the viewer out
1158
+ * of a folder they had just opened, reading as "reload sometimes forgets where I was".
1159
+ */
1160
+ const standableIds = useMemo(() => {
1161
+ const ids: string[] = [];
1162
+ for (const g of groups) if (g.folder) ids.push(g.folder.id);
1163
+ return ids;
1164
+ }, [groups]);
1165
+ const atId = useMemo(() => {
1166
+ if (at === null) return null;
1167
+ if (viewNeedle) return at;
1168
+ return resolveStoredPath(at, standableIds);
1169
+ }, [at, standableIds, viewNeedle]);
1170
+ /**
1171
+ * ⭐⭐ WAVE 42 Β· T45 (R12.6) β€” THE WRITE HALF, and it persists `at` rather than `atId`.
1172
+ *
1173
+ * β›” THAT CHOICE IS THE WHOLE SAFETY OF THIS EFFECT. `atId` is `null` whenever the groups are
1174
+ * not there yet, and at first render they are not [[grid-init-runs-before-the-workspace-arrives]].
1175
+ * Persisting it would erase the stored path microseconds after reading it, on every single
1176
+ * load, and the feature would fail with storage working perfectly and nothing red anywhere.
1177
+ * `at` moves only when the viewer moves, so what is written is always a gesture.
1178
+ *
1179
+ * ⚠ A STALE ENTRY IS ALLOWED TO SIT. If the folder was deleted elsewhere, `at` keeps the dead
1180
+ * id while `atId` renders the top level; the next navigation overwrites it. Nothing is rendered
1181
+ * from the untrusted value at any point, so cleaning it eagerly would buy nothing and cost the
1182
+ * erasure above.
1183
+ *
1184
+ * ⚠ THE KEY IS RE-READ AT WRITE TIME rather than captured at mount, so a route change cannot
1185
+ * write one database's position into another's slot.
1186
+ */
1187
+ useEffect(() => {
1188
+ writeRailPath(railDbKey(), at);
1189
+ }, [at]);
1190
+ /**
1191
+ * ⭐⭐ WAVE 42 Β· T43 (contract C9) β€” THE LEVEL, FROM T41'S RESOLVER.
1192
+ *
1193
+ * β›” THE PARENT WALK IS NOT REDONE HERE. `levelAt` is the one resolver C9 puts over both folder
1194
+ * systems, and it is what answers "which folders are the children of where I am standing" and
1195
+ * "what is one level out". A second spelling of that walk in the rail is exactly the drift C9
1196
+ * exists to prevent β€” and it is what the parity gate's negative control (drop the parent pass,
1197
+ * watch a two-deep folder resolve to the wrong level) is watching for.
1198
+ *
1199
+ * ⚠ THE VIEWS ARE HANDED IN BUT THE LEAVES ARE NOT READ BACK. The rail renders its rows out of
1200
+ * `groups`, which carries the pin bucket, the synthesised shared groups and every drag key the
1201
+ * handlers below compare against; `levelAt`'s own leaf split would be a second, poorer reading
1202
+ * of the same views. What is read is `folders` (the child folder records) and `parent` (the
1203
+ * back step), which is the half no other pass in this file computes.
1204
+ */
1205
+ const level = useMemo(
1206
+ () =>
1207
+ levelAt(
1208
+ atId,
1209
+ foldersOn ? (folders as GridFolder[]) : [],
1210
+ shownViews,
1211
+ (v) => (folderIdOf ? folderIdOf(v.id) : null)
1212
+ ),
1213
+ [atId, foldersOn, folders, shownViews, folderIdOf]
1214
+ );
1215
+ /**
1216
+ * ⭐ R12.1 β€” ONE CONTINUOUS PATH, outermost first, the folder the user is in last.
1217
+ * Empty at the top level, which is what makes "is there a back step" one truthiness test.
1218
+ * The database half of that path (`Data β€Ί Sales stuff β€Ί Odoo Customers`) belongs to the shell
1219
+ * rail; this is the views half, and the two read as one line because they use one vocabulary.
1220
+ */
1221
+ const crumbs = useMemo(
1222
+ () => folderPath(atId, foldersOn ? (folders as GridFolder[]) : []),
1223
+ [atId, foldersOn, folders]
1224
+ );
1225
+ /**
1226
+ * ⚠ THE NAME OF THE LEVEL WHEN THE PATH CANNOT SPELL IT. `folderPath` walks records, and a
1227
+ * synthesised group ("Shared with me", a colleague's folder) has none β€” so the crumb list is
1228
+ * empty for one even though the user is standing inside it. The GROUP knows its own name, which
1229
+ * is the same name its head was wearing when it was clicked.
1230
+ */
1231
+ const atLabel = useMemo(
1232
+ () => (atId === null ? null : groups.find((g) => g.folder?.id === atId)?.folder?.name ?? null),
1233
+ [atId, groups]
1234
+ );
1235
+ /**
1236
+ * ⭐ W42-T43 β€” WHAT THE PATH ROW SAYS, AND WHAT PRESSING IT DOES, as two strings that are
1237
+ * assembled into ONE accessible name.
1238
+ *
1239
+ * β›” THE ACCESSIBLE NAME CONTAINS THE VISIBLE TEXT. `aria-label` REPLACES a button's visible
1240
+ * text for a screen reader, so a bare "Back to Sales stuff" on a row reading "Sales stuff β€Ί Q3"
1241
+ * would announce a different label than the one on screen β€” the label-in-name failure, and on
1242
+ * the one control that tells the user where they are. The visible path leads, the action
1243
+ * follows it.
1244
+ */
1245
+ const pathLabel = crumbs.length
1246
+ ? crumbs.map((f) => f.name).join(" β€Ί ")
1247
+ : (atLabel ?? "All views");
1248
+ const backLabel = crumbs.length > 1 ? crumbs[crumbs.length - 2].name : "all views";
1249
+ /**
1250
+ * ⭐⭐ WAVE 42 Β· T43 (R12.2, R12.4) β€” THE ROWS OF THIS LEVEL, FOLDERS FIRST.
1251
  *
1252
+ * `groups` stays FLAT and stays the render source (C9: the drag handlers key off folder ids and
1253
+ * `parent`, never a path string). This pass decides two things per group and nothing else:
1254
+ * whether it belongs to the level on screen, and whether it renders as a HEAD you can drill
1255
+ * into or as the LEAVES you are standing among.
1256
  *
1257
+ * β›”β›” THE PIN BUCKET STAYS FIRST AT THE TOP LEVEL, AND THAT IS A RULING CALL, NOT AN OVERSIGHT.
1258
+ * R12.4 orders a level "folders first, then its leaves"; W40-T28 is an owner instruction that
1259
+ * an unfiled default view *"must sit at the very top above all folders unless the user moves it
1260
+ * down"*. Read literally the two disagree here. This takes W40-T28, because R12.4's own
1261
+ * rejected alternatives ("interleaved in manual drag order", "views first") are both readings
1262
+ * of the ORDINARY leaf bucket β€” R12 never mentions the pin β€” and because the pin holds the
1263
+ * per-database default view, so ordering it under every folder would put the rail's
1264
+ * most-clicked row last. The conflict was reported rather than resolved here, and RULED:
1265
+ * ⭐⭐ AMENDMENT A27 (2026-08-25) settles it THIS way, on a stronger ground than the one above.
1266
+ * W40-T28's words are *"above all folders"* β€” a phrase nobody writes without knowing folders
1267
+ * are there, so it does not merely fail to contemplate R12.4, it ANTICIPATES it and overrides
1268
+ * it for this one row.
1269
+ * β›” AND THE LIMIT IS IN THE SAME SENTENCE: the condition is *"when it is NOT IN A FOLDER"*.
1270
+ * The pin outranks folders ONLY while unfiled. File the view and it returns to ordinary leaf
1271
+ * ordering, behind the folders, which is what makes A27 consistent with both rulings rather
1272
+ * than a win for one of them.
1273
  *
1274
+ * ⭐ SEARCH FLATTENS ACROSS EVERY LEVEL. With expand/collapse deleted there is no "open
1275
+ * everything" left for a search to do, and a search that quietly saw only the folder you happen
1276
+ * to be standing in would answer "no such view" about a view that exists. So while a needle is
1277
+ * live every matching view is listed wherever it lives, folder heads are suppressed (a head
1278
+ * carries no matches of its own), and the path row above says so in as many words.
 
 
 
1279
  */
1280
+ const levelGroups = useMemo(() => {
1281
+ const pin: typeof groups = [];
1282
+ const heads: typeof groups = [];
1283
+ const leaves: typeof groups = [];
1284
+ /**
1285
+ * β›”β›” A SYNTHETIC LEVEL HAS NO CHILDREN, AND SAYING SO IS NOT OPTIONAL. `levelAt` resolves
1286
+ * an id it has no record of as the TOP level (`levelIdOf` returns null for an unknown id),
1287
+ * so standing inside "Shared with me" would otherwise hand back every top-level folder as
1288
+ * this level's children and redraw the whole root under a shared heading. The shared groups
1289
+ * are a reading of the view list, not records, so their contents are exactly their views.
1290
+ */
1291
+ const childIds = new Set(
1292
+ atId !== null && isSyntheticFolderId(atId) ? [] : level.folders.map((f) => f.id)
1293
+ );
1294
+ for (const group of groups) {
1295
+ const gid = group.folder?.id ?? null;
1296
+ if (viewNeedle) {
1297
+ // Flattened: every group contributes its matches, no heads, no levels.
1298
+ if (group.items.length > 0) leaves.push(group);
1299
+ continue;
1300
+ }
1301
+ if (group.pinned === true) {
1302
+ if (atId === null) pin.push(group);
1303
+ continue;
1304
+ }
1305
+ if (gid === null) {
1306
+ // The ungrouped bucket is the TOP level's leaves and exists nowhere else.
1307
+ if (atId === null) leaves.push(group);
1308
+ continue;
1309
  }
1310
+ if (gid === atId) {
1311
+ // The folder the user is standing IN renders as its own contents, head suppressed.
1312
+ leaves.push(group);
1313
+ continue;
1314
+ }
1315
+ // ⚠ A SYNTHETIC GROUP HAS NO RECORD, so `levelAt` cannot list it as a child: it is a
1316
+ // reading of the view list rather than a folder, and it sits at the top level exactly
1317
+ // where it sat before this ticket.
1318
+ if (isSyntheticFolderId(gid)) {
1319
+ if (atId === null) heads.push(group);
1320
+ continue;
1321
+ }
1322
+ if (childIds.has(gid)) heads.push(group);
1323
  }
1324
+ return { heads, rows: [...pin, ...heads, ...leaves] };
1325
+ }, [groups, level, atId, viewNeedle]);
1326
  const folderMenuF = folderMenu ? folders?.find((f) => f.id === folderMenu.id) : undefined;
1327
  /**
1328
  * ⭐⭐ W41-T35 β€” THE FOLDER WHOSE MARK IS BEING CHANGED, AND THE SECOND REFUSAL OF A SYNTHETIC
 
1349
  * the SAME `nesting` the rail renders from, so the verdict and the picture cannot disagree.
1350
  */
1351
  const nestHere = folderMenuF ? mayNestFolder(nesting, folderMenuF.id) : null;
1352
+ /* β›” W42-T43 β€” `searchKeepsFolder` IS DELETED WITH THE TREE. It existed to keep a folder head
1353
+ on screen when only a folder INSIDE it matched, which was a rule about hiding descendants.
1354
+ R12.2 removes descendants from the rail entirely and search now flattens across every level,
1355
+ so the matching view is listed in its own right and there is no parent left to orphan. */
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1356
  const addPreview = addTarget && folderAddPreview ? folderAddPreview(addTarget) : null;
1357
  /**
1358
  * ONE pair of drop handlers per group, serving TWO drags β€” a view being filed into this
 
1488
  // folder can always go.
1489
  const into = mayNestFolder(nesting, folderParent).ok ? folderParent : null;
1490
  /**
1491
+ * ⭐⭐ WAVE 42 Β· T43 (R12.1) β€” CREATING A FOLDER INSIDE ONE WALKS YOU INTO IT, or the new
1492
+ * folder is created out of sight.
 
 
 
 
 
 
 
1493
  *
1494
+ * β›” THIS IS T34's REGRESSION, ONE NAVIGATION MODEL LATER. The "New folder inside" row hangs
1495
+ * off a folder HEAD, and a head is a folder one level DOWN from where the user is standing:
1496
+ * the child it creates therefore belongs to a level the rail is not showing. The user names a
1497
+ * folder, presses Create, and nothing moves. T34 answered this by opening the parent; the
1498
+ * path answers it by ENTERING the parent, which is the same sentence in the new vocabulary
1499
+ * and leaves the user looking straight at what they just made.
1500
  *
1501
+ * ⚠ A REFUSED PARENT (`into === null`) LEAVES THE PATH ALONE rather than jumping to the top:
1502
+ * the folder was created at the top level, but yanking the user out of the folder they were
1503
+ * standing in would be a second surprise on top of the first.
1504
  */
1505
+ if (into) setAt(into);
1506
  // cleanFolderIcon returns undefined for the all-defaults pair, so a folder the user
1507
  // never restyled stays byte-identical to a pre-wave-9 one (the no-churn rule).
1508
  onFolderCreate?.(value, cleanFolderIcon(folderIcon), into);
 
1956
  </AnchoredOverlay>
1957
  )}
1958
 
1959
+ {/* ⭐⭐ W42-T43 (instruction 16, R12.1) β€” THE PATH, AND THE ONE WAY BACK.
1960
+ Owner: *"I should be able to go back and forth."*
1961
+
1962
+ β›” OUTSIDE `.cg-view-list`, DELIBERATELY, and both halves of that matter. The list is
1963
+ the scroll container (`.cg-views-scroll`), so a back control inside it scrolls away
1964
+ from a user standing at the bottom of a long folder: the only way out of a level would
1965
+ disappear as you looked through it. And as a direct child of `.cg-views` it obeys
1966
+ `.cg-views.is-collapsed > :not(.cg-views-top)`, so a folded rail hides the path with
1967
+ everything else rather than leaving one orphan row.
1968
+
1969
+ ⚠ NO NEW CONTROL SHAPE (DESIGN.md §4): the row is a `.cg-fold-head` carrying a
1970
+ `.cg-fold-toggle`, which is the folder row this rail already teaches, read backwards.
1971
+ The mark is the caret the shell rail uses for a step, not a second glyph vocabulary. */}
1972
+ {(atId !== null || viewNeedle) && (
1973
+ <div className="cg-fold-head">
1974
+ {viewNeedle ? (
1975
+ /* β›” THE SCOPE IS STATED, never implied. Search flattens across every level, so the
1976
+ list on screen is not the level the path names; leaving the breadcrumb up would
1977
+ claim otherwise. One line, no action needed to fix it (clearing the field is the
1978
+ action), so it is a `.cg-fold-empty` note rather than a control. */
1979
+ <div className="cg-fold-empty">Showing matches in every folder</div>
1980
+ ) : (
1981
+ <button
1982
+ type="button"
1983
+ className="cg-fold-toggle"
1984
+ aria-label={`${pathLabel}. Back to ${backLabel}`}
1985
+ title={`Back to ${backLabel}`}
1986
+ onClick={() => setAt(level.parent)}
1987
+ >
1988
+ <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
1989
+ <path
1990
+ d="M9.8 3.6 5.4 8l4.4 4.4"
1991
+ stroke="currentColor"
1992
+ strokeWidth="1.35"
1993
+ strokeLinecap="round"
1994
+ strokeLinejoin="round"
1995
+ />
1996
+ </svg>
1997
+ {/* ⚠ THE WHOLE PATH, ellipsised by `.cg-fold-name`, not just the folder you are in:
1998
+ R12.1 asks for one continuous path, and on a narrow rail the tail is the part
1999
+ that survives the ellipsis, which is the part the user needs. `β€Ί` is the
2000
+ separator the owner wrote the ruling in. */}
2001
+ <span className="cg-fold-name">{pathLabel}</span>
2002
+ </button>
2003
+ )}
2004
+ </div>
2005
+ )}
2006
+
2007
  <div className="cg-view-list cg-views-scroll">
2008
+ {levelGroups.rows.map((group) => {
2009
  const gid = group.folder?.id ?? null;
 
 
 
 
 
 
 
2010
  /**
2011
+ * ⭐⭐ WAVE 42 Β· T43 (instruction 16, R12.2) β€” IS THIS GROUP THE LEVEL, OR A DOOR INTO ONE?
 
2012
  *
2013
+ * `levelGroups` above already decided which groups belong on screen; this is the one bit
2014
+ * it cannot express as membership. A group with a folder is either the folder the user is
2015
+ * STANDING IN, which renders its views and no head, or a CHILD of that folder, which
2016
+ * renders its head and none of its views. There is no third state, and that is R12.2:
2017
+ * the depth term, the `folderHiddenByCollapse` ancestor test and the whole expand set that
2018
+ * used to live on these lines are gone, so a row's indentation no longer encodes anything
2019
+ * and a folder's contents are reached by entering it.
2020
  */
2021
+ const asLeaves = !group.folder || gid === atId || !!viewNeedle;
 
 
 
 
 
2022
  /**
2023
  * ⭐⭐ WAVE 40 Β· T28 (owner instruction 30) β€” THE PIN GROUP: the unfiled default views,
2024
  * rendered above every folder.
 
2054
  // "Shared with me" while offering them on a colleague's folder would emit `item_move` /
2055
  // `folder_rename` / `folder_delete` against an id that exists in nobody's store.
2056
  const isSynthetic = isSyntheticFolderId(gid);
2057
+ /**
2058
+ * ⭐ W42-T43 β€” THE DROP AREA FOR "FILE THIS INTO THE FOLDER I AM IN".
2059
+ *
2060
+ * β›” A SECOND BOOLEAN, NEVER A WIDER `isRoot`. `isRoot` means the TOP-LEVEL ungrouped
2061
+ * bucket and `verify_grid_ux.py`'s `empty-root-loses-its-drop-area` control drops the
2062
+ * drop area from exactly that surface; widening the name would leave the control
2063
+ * injecting and failing while testing something else entirely.
2064
+ *
2065
+ * ⚠ THE TWO CANNOT BOTH BE TRUE: `isRoot` needs `gid === null`, which only the top level
2066
+ * has, and this needs a folder the user has drilled into. Same class, same area rule
2067
+ * (`.cg-fold-root.is-viewdrop`), because the head that used to accept this drop is not
2068
+ * on screen at its own level.
2069
+ */
2070
+ // ⚠ `!isSynthetic`: a synthesised group takes no drop handlers (see the spread below),
2071
+ // so painting it a drop AREA would advertise a target that silently refuses the release.
2072
+ const isLevelFolder = asLeaves && gid !== null && !isSynthetic && !viewNeedle;
2073
  return (
2074
  <div
2075
  /* ⭐ W40-T28 β€” a key of its own. Both this group and the ungrouped section have a null
2076
  folder, so the old `gid ?? "__root__"` would give React two children with the same
2077
  key and it would reconcile one over the other. */
2078
  key={isPinnedGroup ? "__pinned__" : gid ?? "__root__"}
2079
+ /* β›” W42-T43 (R12.2) β€” THE PER-LEVEL INDENT IS GONE, and nothing replaced it. T33 set a
2080
+ nested folder in by `(depth - 1) * 12`px because the tree had to show you where a row
2081
+ sat; a path shows you by only rendering one level at a time, so an indent here would
2082
+ be a second, weaker answer to a question the path has already answered. This element
2083
+ now carries no `style` at all. */
 
 
 
 
 
 
 
 
2084
  className={
2085
  /* ⭐ W40-T28 β€” `gid === null`, not `isRoot`: the pin group wears the SAME class as
2086
  the ungrouped section (no head, the rail's measured root indent) because it is the
2087
  same shape of thing rendered in a different place. DESIGN.md Β§4 β€” this is an
2088
+ existing element joining the existing rhythm, not a new control shape.
2089
+ ⭐ W42-T43 widens that to every HEADLESS group: the folder you are standing in
2090
+ renders its views with no head of its own, which is the same shape again, and
2091
+ `.cg-fold .cg-view-row`'s 12px child indent would set them in under a head that
2092
+ is not there. */
2093
+ (asLeaves ? "cg-fold-root" : "cg-fold") +
2094
  (!isPinnedGroup && dropTarget === (gid ?? "__root__") ? " is-drop" : "") +
2095
  // Item 19 β€” the insertion rule reads "the folder you are dragging lands HERE":
2096
  // above this folder, or above the ungrouped section, which is after them all.
 
2126
  // at `null` beside a `gid` that is `null` for this very section β€” that is the
2127
  // `foldDrag === gid` trap two lines up, which faded the whole ungrouped section
2128
  // permanently once already. `isRoot` is a separate boolean, so the two cannot collide.
2129
+ (isRoot && viewDrag !== null ? " is-viewdrop" : "") +
2130
+ // ⭐ W42-T43 β€” the same area, one level in: see `isLevelFolder`. Written as its own
2131
+ // term rather than folded into the line above, so that line stays exactly the
2132
+ // literal `verify_grid_ux.py` injects its root-drop control into.
2133
+ (isLevelFolder && viewDrag !== null ? " is-viewdrop" : "")
2134
  }
2135
  {/* No drop handlers on the synthetic group β€” see `isSynthetic`. Spreading `{}`
2136
  rather than branching the element keeps ONE render path for every group.
 
2141
  somewhere else on screen. The ungrouped section below is the one root target. */
2142
  ...(isSynthetic || isPinnedGroup ? {} : dropHandlers(gid))}
2143
  >
2144
+ {/* β›” W42-T43 β€” THE FOLDER YOU ARE STANDING IN HAS NO HEAD HERE. Its name is on the path
2145
+ row above the list, which is the one place it can be while still carrying the way
2146
+ back out; drawing it a second time at the top of its own contents would offer a
2147
+ folder row that opens the folder you are already in. */}
2148
+ {group.folder && !asLeaves && (
2149
  <div
2150
  className="cg-fold-head"
2151
  // ── Item 19 β€” the folder itself is the drag handle ─────────────────────
 
2167
  flow shifts the folder's name to the right, and this rail's indent is
2168
  MEASURED to the pixel (index.css: "root view name 41.00px / folder header
2169
  48.36px" β€” the whole point of the wave-10 item-2 fix); the gutter it would
2170
+ otherwise hide in was the disclosure chevron's until W42-T43 deleted it, and
2171
+ it is where a mark would still have to go. The view rows above have been
2172
  draggable with no handle since wave 8, so a folder that drags the same way
2173
  is the vocabulary this list already teaches, not a hidden feature. */}
2174
  <button
2175
  type="button"
2176
  className="cg-fold-toggle"
 
2177
  /**
2178
+ * ⭐⭐ W42-T43 (instruction 16, R12.1) β€” THIS BUTTON IS THE DRILL NOW.
 
2179
  *
2180
+ * β›” THE BUTTON SURVIVED THE TWISTY, AND THE DISTINCTION IS LOAD-BEARING. What
2181
+ * R12.2 deletes is the `aria-expanded` behaviour and the `.cg-fold-chev` glyph;
2182
+ * `.cg-fold-toggle` itself carries this row's whole layout, its reset chrome and
2183
+ * the MEASURED wave-10 item-2 indent fix, so it keeps its rule and takes a new
2184
+ * job. The chevron was absolutely positioned in the rail's gutter (`left: -8px`),
2185
+ * out of flow, so removing it moves the folder's mark and name by nothing at all.
2186
+ *
2187
+ * ⚠ NO `aria-expanded`. Nothing expands: the control replaces the list with this
2188
+ * folder's contents, and announcing a collapsed/expanded state for a list that
2189
+ * has neither is the wrong sentence read aloud. The label below says what the
2190
+ * press does instead.
2191
  */
2192
+ aria-label={`Open folder ${group.folder.name}`}
2193
+ onClick={() => setAt(group.folder!.id)}
 
 
 
 
 
 
2194
  >
 
 
 
2195
  {/* I14/I15 β€” the folder wears its chosen mark; a folder that never chose one
2196
  (every pre-wave-9 folder) renders the default grey folder shape, which is
2197
  precisely "existing folders get the folder icon". */}
 
2206
  β›” AND THE FALLBACK IS `undefined`, WHICH IS THE ANSWER RATHER THAN A GAP:
2207
  `FolderMark` draws the default folder in the default tone for an absent icon,
2208
  which is exactly what "the payload does not carry one yet" should look like.
2209
+ ⭐ W42-T18 PUT THE FOLDER RECORD ON THE READ, so this map now carries a mark
2210
+ for every shared folder whose owner picked one, and this line paints it. A
2211
+ shared folder whose owner picked none still lands on the default. */}
2212
  <FolderMark
2213
  icon={group.folder.icon ?? (gid ? sharedFolderIcons.get(gid) : undefined)}
2214
  size={16}
 
2294
  )}
2295
  </div>
2296
  )}
2297
+ {/* ⭐ W42-T43 β€” A FOLDER HEAD SHOWS NO ROWS AND STAYS A DROP TARGET. It is a door into
2298
+ a level, so its views live behind it; the drop handlers above are on this same
2299
+ element, which is what keeps "drag a view onto a folder to file it" working from
2300
+ the level the folder is a door on. */}
2301
+ {asLeaves &&
2302
  group.items.map((view) => {
2303
  const active = view.id === activeViewId;
2304
  const renaming = renamingId === view.id;
 
2603
  </div>
2604
  );
2605
  })}
2606
+ {/* β›” W42-T43 β€” THE EMPTY LINE IS ABOUT THE LEVEL, NOT THE BUCKET. A folder can hold
2607
+ folders now, so its own view list being empty no longer means the level is: the
2608
+ heads of this level render as siblings of this group, and saying "Empty" above a
2609
+ list of subfolders would be false. DESIGN.md Β§4 β€” one line and the action that
2610
+ fills it, which is the line this rail already used. */}
2611
+ {group.folder && asLeaves && group.items.length === 0
2612
+ && levelGroups.heads.length === 0 && (
2613
  <div className="cg-fold-empty">Empty. Drag a view here.</div>
2614
  )}
2615
  </div>
 
2796
  </AnchoredOverlay>
2797
  )}
2798
 
2799
+ {/* ⭐⭐ WAVE 41 Β· T35 (owner instruction 11) β†’ WAVE 42 Β· T55 (ruling R25) β€” THE CHANGE-ICON
2800
+ PANEL. It holds the SAME picker the create pane holds, mounted twice and never copied.
2801
+ W41-T35 also gave it the folder menu's panel class, and R25 is where that was corrected:
2802
+ "that navigation already exist, no need to reinvent the wheel." `cg-view-menu` is built
2803
+ for menu ROWS, so the same swatch grid arrived in a narrower, tighter box than the create
2804
+ step's and read as a second control. The panel now wears `cg-fold-icon-pop`, whose rule
2805
+ lives in `styles/wave42/rail-views.css` and takes its padding, hairline, radius, surface
2806
+ and heading type from the create step's own rules.
2807
+ β›” `cg-view-menu` IS DELIBERATELY UNTOUCHED β€” the view menu, the folder menu, the column
2808
+ menu and the create flyout all wear it, so fixing this panel through that class would
2809
+ have restyled four surfaces to correct one.
2810
  ⚠ IT WRITES ON EVERY CLICK rather than behind a Save. Shape and tone are two independent
2811
  picks and the folder head repaints under the panel as they land, so the panel IS the
2812
  preview β€” a confirm step would put a button between the user and a change they can see
2813
  and undo by clicking again (Β§4, never over-explain). Dismissing is therefore not a
2814
+ cancel, and nothing here pretends it is.
2815
+ β›”β›” R25 ASKS FOR THE CREATE STEP'S PRESENTATION, NOT ITS FOOTER, AND THIS IS SETTLED β€”
2816
+ do not re-open it. `cg-form-actions` belongs to the FORM (Create and Cancel for the whole
2817
+ folder-creation), not to the icon step. What is shared is the icon step's container
2818
+ treatment, its padding and width around the grid, and a heading naming the folder. The
2819
+ dismissal that matches is the AFFORDANCES β€” outside click and Escape, both from
2820
+ `useOverlayLayer` β€” not a button pair. A Cancel here would not revert anything, and a
2821
+ control that lies about what it does is worse than the inconsistency it removes. */}
2822
  {iconMenu && iconMenuF && onFolderIconChange && (
2823
  <AnchoredOverlay
2824
  anchor={iconMenu.anchor}
2825
+ className="cg-fold-icon-pop"
2826
  placement="bottom-end"
2827
  role="dialog"
2828
  ariaLabel={`Icon for folder ${iconMenuF.name}`}
2829
  onDismiss={() => setIconMenu(null)}
2830
  dataKind="folder-icon"
2831
  >
2832
+ {/* The create step's label carries its destination and so does this heading: one line,
2833
+ the folder's own name, sentence case, no explanation (DESIGN.md Β§4, and it mirrors
2834
+ the `New folder in <name>` label the create pane shows one door away). */}
2835
+ <div className="cg-fold-icon-title">{`Icon for ${iconMenuF.name}`}</div>
2836
  {/* ⚠ RESOLVED AGAINST THE DEFAULTS RATHER THAN PASSED AS `undefined`: the picker draws
2837
  a selection ring on the swatch that is currently chosen, and a folder that never
2838
  chose an icon IS wearing the default shape in the default tone (`FolderMark` reads
 
2848
  </AnchoredOverlay>
2849
  )}
2850
 
2851
+ {/* ⭐⭐ WAVE 42 Β· T44 (ruling R12, contract C9) β€” THE "Move to" PICKER.
2852
+ It is this rail's OWN picker vocabulary, not a second implementation: the same
2853
+ `AnchoredOverlay`, the same `cg-pop` panel, `cg-pop-title`, `cg-pop-list` and
2854
+ `cg-pick-row` the cohort-lock picker two blocks down already wears, hung off the same
2855
+ "…" anchor the menu used. No new class and NO NEW CSS AT ALL, which is deliberate as
2856
+ well as convenient: `index.css` @imports the lane sheet from the top, so a rule written
2857
+ in `styles/wave42/rail-views.css` loses every equal-specificity fight silently, and the
2858
+ indent this list needs is one inline `paddingLeft` on a row that already has a shape.
2859
+ ⚠ `role="dialog"`, matching the icon and lock pickers rather than the "…" menu: the
2860
+ rows sit inside a scrolling `cg-pop-list`, and a `menu` whose items are owned by an
2861
+ intermediate element is a broken ownership tree rather than a keyboard nicety. */}
2862
+ {moveFor && moveView && (() => {
2863
+ const currentId = folderIdOf ? folderIdOf(moveFor.viewId) : null;
2864
+ /**
2865
+ * β›”β›” THE TWO DOORS EMIT THE SAME ID, AND THIS LINE IS WHERE THAT IS TRUE.
2866
+ * It is the drop handler's expression verbatim β€” `onItemMove?.(id, folderId ??
2867
+ * ROOT_FOLDER_ID)` β€” so the top-level row passes `null` and the sentinel is applied HERE,
2868
+ * exactly as the drag applies it. `null` means "no placement", which `groupByFolder`
2869
+ * reads as "arrived by grant" and would file a shared view straight back under "Shared
2870
+ * with me"; `ROOT_FOLDER_ID` is the receiver saying they filed it at the top. A picker
2871
+ * that emitted the raw `null` would give one action two behaviours with every gate green.
2872
+ */
2873
+ const fileInto = (folderId: string | null) => {
2874
+ onItemMove?.(moveFor.viewId, folderId ?? ROOT_FOLDER_ID);
2875
+ setMoveFor(null);
2876
+ };
2877
+ return (
2878
+ <AnchoredOverlay
2879
+ anchor={moveFor.anchor}
2880
+ className="cg-pop"
2881
+ placement="bottom-end"
2882
+ role="dialog"
2883
+ ariaLabel={`Move ${viewDisplayName(moveView)} to a folder`}
2884
+ onDismiss={() => setMoveFor(null)}
2885
+ dataKind="view-move-to"
2886
+ >
2887
+ <div className="cg-pop-title">Move to</div>
2888
+ <div className="cg-pop-list">
2889
+ {/* ⭐ THE TOP LEVEL IS A DESTINATION LIKE ANY OTHER, and it is marked current for
2890
+ BOTH shapes of "already at the top": the stored sentinel and a view with no
2891
+ placement at all. They are different facts about how the view got there and the
2892
+ same fact about where it is, so a mark that recognised only the sentinel would
2893
+ re-open the absence/sentinel confusion the drop handler exists to close. */}
2894
+ <button
2895
+ type="button"
2896
+ className={
2897
+ "cg-pick-row" +
2898
+ (currentId === null || currentId === ROOT_FOLDER_ID ? " is-on" : "")
2899
+ }
2900
+ onClick={() => fileInto(null)}
2901
+ >
2902
+ <FolderMark size={16} />
2903
+ Top level
2904
+ </button>
2905
+ {/* ⭐⭐ EVERY FOLDER IN THE DATABASE, not the level on screen. `nesting.ordered` is
2906
+ depth-first, so this list runs in the order the rail itself draws the tree, and
2907
+ `nesting.depth` indents each row to the level it sits at. A folder ten deep is
2908
+ therefore offered, and selectable, from the top level with nothing to navigate.
2909
+ ⚠ THE FOLDER THE VIEW IS ALREADY IN IS LISTED AND MARKED, not removed. Dropping
2910
+ it would make the list a different shape for every view, so a user learning
2911
+ where a folder sits in it would have to relearn that on the next view; and the
2912
+ row is harmlessly idempotent, since choosing it emits the placement the view
2913
+ already carries. `title` carries the full trail for a name that truncates. */}
2914
+ {moveFolders.map((f) => (
2915
+ <button
2916
+ type="button"
2917
+ key={f.id}
2918
+ className={"cg-pick-row" + (f.id === currentId ? " is-on" : "")}
2919
+ style={{ paddingLeft: 6 + (nesting.depth[f.id] ?? 0) * 12 }}
2920
+ title={folderPath(f.id, moveFolders).map((p) => p.name).join(" / ")}
2921
+ onClick={() => fileInto(f.id)}
2922
+ >
2923
+ <FolderMark icon={f.icon} size={16} />
2924
+ {f.name}
2925
+ </button>
2926
+ ))}
2927
+ {moveFolders.length === 0 && (
2928
+ <div className="cg-pop-note">
2929
+ There are no folders in this database yet. Make one from the rail and this view
2930
+ can be filed into it.
2931
+ </div>
2932
+ )}
2933
+ </div>
2934
+ </AnchoredOverlay>
2935
+ );
2936
+ })()}
2937
+
2938
  {/* Item 12 (C-LOCK) β€” the lock picker. Lists the cohorts this reader can see, marks the
2939
  current one, and offers Unlock when there is one: a lock removable only from
2940
  somewhere other than where it was applied is a trap, and the owner asked for a
 
3193
  >
3194
  <MenuLabel icon="duplicate" text="Duplicate" />
3195
  </button>
3196
+ {/* ⭐⭐ WAVE 42 Β· T44 (ruling R12, contract C9) β€” MOVE TO, THE SECOND DOOR ONTO THE
3197
+ MOVE THE DRAG ALREADY PERFORMS.
3198
+ β›” NOT POLISH, AND R12.5 SAYS SO. Now that the rail navigates by PATH, the level on
3199
+ screen holds a view and its siblings and nothing else β€” so a folder anywhere but
3200
+ here is never on screen at the same time as the view being moved, and drag alone
3201
+ silently makes most destinations unreachable. The picker lists the WHOLE tree.
3202
+ ⚠ NO GLYPH IN `MENU_ICONS` SAYS "folder", so the mark is passed as a NODE, the way
3203
+ "Share folder" passes `ShareMark` and "Change icon" passes the folder's own mark.
3204
+ The plain `FolderMark` is the honest picture of where this row sends the view, and
3205
+ it keeps `icons.tsx` (another fence entirely) out of this change.
3206
+ ⚠ NO ELLIPSIS ON THE LABEL: `verify_icons`'s T23 sweep reds on one in any
3207
+ `MenuLabel` text, and DESIGN Β§4 asks for sentence case, so the row reads `Move to`. */}
3208
+ {canFileMenuView && (
3209
+ <button
3210
+ type="button"
3211
+ role="menuitem"
3212
+ onClick={() => {
3213
+ setMoveFor({ viewId: menuView.id, anchor: menu.anchor });
3214
+ setMenu(null);
3215
+ }}
3216
+ >
3217
+ <MenuLabel icon={<FolderMark size={16} />} text="Move to" />
3218
+ </button>
3219
+ )}
3220
  {/* WAVE 20 items 23/26 (R10) β€” "who else can reach this view", the same
3221
  editor a folder and a database open. Deliberately NOT gated on
3222
  `canEditMenuView`: the server decides who may administer (owner or
web/src/customer-grid/apiBridge.ts CHANGED
@@ -149,6 +149,29 @@ export function clearWorkspaceCache(): void {
149
  wsCache.clear();
150
  }
151
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
152
  export function clearCustomersCache(): void {
153
  rowsCache.clear();
154
  // β›” THE ENVELOPE IS SESSION-SCOPED FOR THE SAME REASON THE ROWS ARE, and it carries MORE that
@@ -1098,6 +1121,144 @@ export async function deleteTableField(
1098
  }
1099
  }
1100
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1101
  /**
1102
  * ⭐⭐ 2026-08-09 β€” THE DEFINITION SHAPE, NOT A THREE-KEY SUMMARY.
1103
  *
 
149
  wsCache.clear();
150
  }
151
 
152
+ /**
153
+ * ⭐⭐ W42 AMENDMENT A13 β€” LOOK AT WHAT IS ALREADY CACHED FOR A SCOPE, AND DO NOTHING ELSE.
154
+ *
155
+ * β›” A PEEK, NOT A READ-THROUGH. It never fetches, never writes, never evicts and never touches
156
+ * the entry's clock. `grep -rE "export (function|const) (peek|get)?[Ww]orkspace"` over `web/src`
157
+ * returned nothing before this line, which is why the shell could not see a database's views at
158
+ * all: the rail had no way to ask, so it announced that it was reading them forever. The
159
+ * alternative was a second fetch from the shell, which contract C5 forbids and which would also
160
+ * have pinned the "do we already know this database?" flag permanently true.
161
+ *
162
+ * β›” THE `ws`, NOT THE `{at, ws}` ENTRY. The wrapper is this module's own bookkeeping; handing it
163
+ * out would make every caller a second reader of a shape only `fetchWorkspace` may reason about.
164
+ *
165
+ * ⚠ `at` IS DELIBERATELY NOT CONSULTED, and this is a choice rather than an omission. There is no
166
+ * refresh path behind a peek, so answering `undefined` for a present-but-elderly envelope would
167
+ * trade a slightly stale list of views β€” which is correct and useful β€” for a blank rail that
168
+ * never fills. Freshness belongs to `fetchWorkspace`, which owns the clock and the re-read; a
169
+ * caller that needs guaranteed-current data must go through it.
170
+ */
171
+ export function peekWorkspace(scope: string): GridWorkspace | undefined {
172
+ return wsCache.get(scope)?.ws;
173
+ }
174
+
175
  export function clearCustomersCache(): void {
176
  rowsCache.clear();
177
  // β›” THE ENVELOPE IS SESSION-SCOPED FOR THE SAME REASON THE ROWS ARE, and it carries MORE that
 
1121
  }
1122
  }
1123
 
1124
+ /**
1125
+ * ⭐⭐ W42-T58 (contract C4) β€” DELETE SEVERAL DEFINITION COLUMNS IN ONE REQUEST, AND REPORT WHICH
1126
+ * ONES ACTUALLY WENT, KEY BY KEY.
1127
+ *
1128
+ * ⚠ ONE LINE OF HISTORY, BECAUSE THE SHAPE THIS REPLACES WAS NOT A MISTAKE: W42-T11 walked the
1129
+ * per key door N times and documented why at this very spot, and it was CORRECT against the
1130
+ * server that existed then, which had no plural door at all. W42-T28 shipped one. What changed is
1131
+ * the server, not the reasoning.
1132
+ *
1133
+ * β›” ONE REQUEST FOR EVERY N, INCLUDING N = 1. A singular special case would leave two ways for a
1134
+ * delete to be answered and only one of them carrying the per key verdict, so the commonest act
1135
+ * on this surface would be the least explained one.
1136
+ *
1137
+ * β›” THE VERDICT IS RETURNED, NOT SHOUTED FROM IN HERE. A refusal used to reach the person as a
1138
+ * toast raised inside the singular request, one per key, which is why several refusals raced into
1139
+ * one toast slot with nothing naming which column each sentence belonged to. The plural answer
1140
+ * carries a status, a machine code and a sentence PER KEY, and the caller owns what is read.
1141
+ *
1142
+ * ⚠ A REFUSED KEY IS RETURNED, NOT SWALLOWED. Reconciling a refused key out of the view would
1143
+ * take the column off the screen while it still exists on the server β€” the field would be gone
1144
+ * until the next workspace fetch put it back, which reads as a flicker rather than a refusal.
1145
+ *
1146
+ * ⚠ AND AN OLDER SERVER IS ALLOWED FOR, NOT TRUSTED. An accepted answer that names no key at all
1147
+ * is read as neither a silent success nor a blanket refusal: it is reported as an answer this
1148
+ * client could not read, with the unreadable flag raised, so the caller fetches the truth instead
1149
+ * of painting a guess over the view.
1150
+ */
1151
+ export interface FieldDeleteResult {
1152
+ key: string;
1153
+ status: "deleted" | "refused";
1154
+ code?: string;
1155
+ reason?: string;
1156
+ contract?: string;
1157
+ removed?: number;
1158
+ }
1159
+
1160
+ export interface FieldDeleteOutcome {
1161
+ deleted: string[];
1162
+ refused: string[];
1163
+ results: FieldDeleteResult[];
1164
+ /** The server was reached, accepted the act, and named no key either way. */
1165
+ unreadable: boolean;
1166
+ }
1167
+
1168
+ /**
1169
+ * ⚠ USER-FACING, AND IT PROMISES WHAT THE CALLER ACTUALLY DOES: the unreadable branch below is
1170
+ * paired with a refetch on the caller's side, so this sentence is not asking the person to do the
1171
+ * app's job for it.
1172
+ */
1173
+ const DELETE_ANSWER_NAMED_NO_COLUMN =
1174
+ "The server accepted that delete without saying which columns went, so the table is being read " +
1175
+ "again rather than guessed at.";
1176
+
1177
+ function refusedWholesale(
1178
+ fieldKeys: readonly string[],
1179
+ reason: string | undefined,
1180
+ code: string,
1181
+ unreadable = false
1182
+ ): FieldDeleteOutcome {
1183
+ return {
1184
+ deleted: [],
1185
+ refused: [...fieldKeys],
1186
+ results: fieldKeys.map((key) => ({ key, status: "refused" as const, code, reason })),
1187
+ unreadable,
1188
+ };
1189
+ }
1190
+
1191
+ export async function deleteTableFields(
1192
+ tableKey: string,
1193
+ fieldKeys: readonly string[]
1194
+ ): Promise<FieldDeleteOutcome> {
1195
+ if (fieldKeys.length === 0) {
1196
+ return { deleted: [], refused: [], results: [], unreadable: false };
1197
+ }
1198
+ let res: Response;
1199
+ try {
1200
+ res = await fetch(
1201
+ `${API_V1}/tables/${encodeURIComponent(tableKey)}/fields/delete`,
1202
+ {
1203
+ method: "POST",
1204
+ credentials: CREDENTIALS,
1205
+ headers: JSON_HEADERS,
1206
+ body: JSON.stringify({ keys: [...fieldKeys] }),
1207
+ }
1208
+ );
1209
+ } catch {
1210
+ return refusedWholesale(fieldKeys, "That delete did not reach the server.", "unreachable");
1211
+ }
1212
+ // ⚠ NO SENTENCE ON THIS PATH. `handledSession` has already taken the person somewhere else, so
1213
+ // a reason here would be copy nobody is left to read.
1214
+ if (handledSession(res)) return refusedWholesale(fieldKeys, undefined, "session_ended");
1215
+ const body = (await readJson(res)) as {
1216
+ results?: unknown;
1217
+ deleted?: unknown;
1218
+ refused?: unknown;
1219
+ error?: { message?: string; code?: string };
1220
+ } | null;
1221
+ if (!res.ok) {
1222
+ const code = typeof body?.error?.code === "string" ? body.error.code : "refused";
1223
+ return refusedWholesale(fieldKeys, refusalMessage(body, res.status), code);
1224
+ }
1225
+ const rawResults = body?.results;
1226
+ const results: FieldDeleteResult[] = [];
1227
+ if (Array.isArray(rawResults)) {
1228
+ for (const entry of rawResults as unknown[]) {
1229
+ const raw = entry as Record<string, unknown> | null;
1230
+ if (!raw || typeof raw.key !== "string") continue;
1231
+ results.push({
1232
+ key: raw.key,
1233
+ status: raw.status === "deleted" ? "deleted" : "refused",
1234
+ code: typeof raw.code === "string" ? raw.code : undefined,
1235
+ reason: typeof raw.reason === "string" ? raw.reason : undefined,
1236
+ contract: typeof raw.contract === "string" ? raw.contract : undefined,
1237
+ removed: typeof raw.removed === "number" ? raw.removed : undefined,
1238
+ });
1239
+ }
1240
+ } else {
1241
+ // A server that answers the plural door with only the two key lists is still answering it.
1242
+ // Every key is accounted for; what is missing is the explanation, not the verdict.
1243
+ const named = (value: unknown): string[] =>
1244
+ Array.isArray(value) ? value.filter((k): k is string => typeof k === "string") : [];
1245
+ for (const key of named(body?.deleted)) results.push({ key, status: "deleted" });
1246
+ for (const key of named(body?.refused)) results.push({ key, status: "refused" });
1247
+ }
1248
+ if (results.length === 0) {
1249
+ // Nothing here can say whether the schema moved, so nothing cached about it is trustworthy.
1250
+ dropTableRowsCache(tableKey);
1251
+ return refusedWholesale(fieldKeys, DELETE_ANSWER_NAMED_NO_COLUMN, "unreadable_answer", true);
1252
+ }
1253
+ const deleted = results.filter((r) => r.status === "deleted").map((r) => r.key);
1254
+ const refused = results.filter((r) => r.status === "refused").map((r) => r.key);
1255
+ // The schema moved for every key that went, and a deleted LINK takes its reciprocal and every
1256
+ // rollup that folded it with it, so the cached rows are values behind and not merely a column
1257
+ // behind. ONE act, ONE drop, and none at all when the server kept every column.
1258
+ if (deleted.length > 0) dropTableRowsCache(tableKey);
1259
+ return { deleted, refused, results, unreadable: false };
1260
+ }
1261
+
1262
  /**
1263
  * ⭐⭐ 2026-08-09 β€” THE DEFINITION SHAPE, NOT A THREE-KEY SUMMARY.
1264
  *
web/src/customer-grid/folders.ts CHANGED
@@ -801,3 +801,166 @@ export function newFolderId(): string {
801
  : Math.random().toString(36).slice(2, 10);
802
  return `fld_${rand}`;
803
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
801
  : Math.random().toString(36).slice(2, 10);
802
  return `fld_${rand}`;
803
  }
804
+
805
+ // ---------------------------------------------------------------------------
806
+ // ⭐⭐ WAVE 42 Β· T41 (ruling R12, contract C9) β€” ONE PATH MODEL, OVER BOTH FOLDER SYSTEMS.
807
+ //
808
+ // β›” THERE WERE TWO FOLDER SYSTEMS AND THEY SHARED NOTHING. `shell/nav.ts::foldNav` groups
809
+ // DATABASES under the per-user nav folders; everything above this line groups VIEWS. Same word on
810
+ // screen, two spellings of "what is inside this folder", and R12.3 says a DATABASE folder must
811
+ // drill exactly like a VIEW folder. So one resolver answers the two questions a path needs β€”
812
+ // *what is at this path* and *what is the parent of this path* β€” for both.
813
+ //
814
+ // β›” IT ADDS, IT DOES NOT REWRITE. {@link groupByFolder} keeps its FLAT `FolderGroup<T>[]` shape
815
+ // and {@link folderNesting} stays a separate pass, because every drag handler in the rail keys off
816
+ // folder IDs and `parent` and none of them keys off a path string. A builder who flattened the
817
+ // tree into a linear path and dropped the nesting pass would collapse every nested folder to one
818
+ // level, silently, with the rail still rendering.
819
+ //
820
+ // ⚠ THE PARENT ANSWER COMES FROM {@link folderNesting}, NEVER FROM RE-DERIVING A PATH. That is
821
+ // the whole correctness of this file: the nesting pass is where cycles are cut, where a dangling
822
+ // parent is re-rooted, and where depth is counted. A second derivation would be a second truth.
823
+ // ---------------------------------------------------------------------------
824
+
825
+ /**
826
+ * The least a folder must be for the path model to place it.
827
+ *
828
+ * ⚠ STRUCTURAL, AND DECLARED HERE RATHER THAN IMPORTED, so the two systems meet without either
829
+ * one learning the other's type. `GridFolder` (a view folder: `id`, `name`, `order?`, `icon?`,
830
+ * `parent?`) and `shell/nav.ts::NavFolder` (a nav folder: `id`, `name`) both satisfy it as they
831
+ * stand, and neither had to change.
832
+ *
833
+ * β›” A NAV FOLDER HAS NO `parent` TODAY AND MUST NOT BE GIVEN ONE HERE. `parseNavPrefs` mirrors
834
+ * the server's `_clean_nav_prefs`, which builds a strict `{id, name}` row, so a parent written
835
+ * client-side would be dropped on the next save. Parentless folders simply come back from
836
+ * {@link folderNesting} at level 1 with a `null` parent, which is exactly "a flat rail", and
837
+ * {@link levelAt} drills them with the same code that drills a ten-deep view folder.
838
+ */
839
+ export interface PathFolder {
840
+ id: string;
841
+ name: string;
842
+ parent?: string | null;
843
+ }
844
+
845
+ /**
846
+ * One level of the path: what is AT it, and the way back OUT of it.
847
+ *
848
+ * ⭐ `folders` AND `leaves` ARE SEPARATE ARRAYS, which is R12.4 ("every level lists FOLDERS
849
+ * FIRST, then its leaves") expressed as data rather than as an ordering convention a renderer
850
+ * has to remember. A caller renders `folders` then `leaves` and cannot get the order wrong; a
851
+ * single interleaved list would have made the rule a comment.
852
+ */
853
+ export interface FolderLevel<F, T> {
854
+ /** The folder this level IS, or `null` at the top level. */
855
+ folder: F | null;
856
+ /** The folders directly inside this level, in the nesting's own sibling order. */
857
+ folders: F[];
858
+ /** The items filed directly at this level. Never the ones inside a subfolder. */
859
+ leaves: T[];
860
+ /**
861
+ * The id of the level one step OUT, or `null` when that step lands at the top.
862
+ *
863
+ * β›” `null`, NEVER {@link ROOT_FOLDER_ID}. That constant is a reserved ITEM placement and
864
+ * {@link folderNesting} already refuses it as a folder parent; emitting it here would put an
865
+ * item-placement id in a folder-parent slot. It is ACCEPTED as an input `at` (an item really
866
+ * can carry it) and read as "the top level".
867
+ */
868
+ parent: string | null;
869
+ /** 0 at the top level, 1 for a top-level folder, up to {@link FOLDER_DEPTH_MAX}. */
870
+ depth: number;
871
+ }
872
+
873
+ /**
874
+ * Read `at` as a level id: absence, the root sentinel and a dangling id all mean the top level.
875
+ *
876
+ * ⚠ THE DANGLING RULE IS {@link resolveFolderId}'s, REUSED. A path segment naming a folder that
877
+ * has just been deleted has to land SOMEWHERE, or drilling into it would render nothing at all
878
+ * and read as an empty app.
879
+ *
880
+ * ⚠ It deliberately does NOT distinguish "never placed" (absence) from "placed at root" (the
881
+ * sentinel). That split is W32-T27's and it decides the PIN in {@link groupByFolder}; a LEVEL has
882
+ * no such question to answer, because both render at the top.
883
+ */
884
+ function levelIdOf(raw: string | null | undefined, known: ReadonlySet<string>): string | null {
885
+ if (raw == null || raw === ROOT_FOLDER_ID) return null;
886
+ return known.has(raw) ? raw : null;
887
+ }
888
+
889
+ /**
890
+ * ⭐⭐ WHAT IS AT THIS PATH β€” the one resolver, for view folders and database folders alike.
891
+ *
892
+ * `at` is the folder id the user has drilled to, `null`/absent/{@link ROOT_FOLDER_ID} being the
893
+ * top. `folderIdOf` is how an item names its folder, which is the only thing the two systems
894
+ * spell differently: a VIEW carries its `folderId`, while the nav's placement lives in a
895
+ * per-user map (see `shell/nav.ts::navFolderIdOf`, which closes over it and hands back the same
896
+ * shape). Both arrive here as one function from an item to a folder id.
897
+ *
898
+ * β›” DEPTH IS NOT ENFORCED HERE and must not be. {@link mayNestFolder} refuses the eleventh
899
+ * level at the moment a folder is placed; this function RENDERS whatever exists, so a folder at
900
+ * {@link FOLDER_DEPTH_MAX} is still reachable by walking levels one at a time, which is what R12
901
+ * asks the path to do.
902
+ */
903
+ export function levelAt<F extends PathFolder, T>(
904
+ at: string | null | undefined,
905
+ folders: readonly F[],
906
+ items: readonly T[],
907
+ folderIdOf: (item: T) => string | null | undefined
908
+ ): FolderLevel<F, T> {
909
+ const list: F[] = [...folders];
910
+ const byId = new Map<string, F>(list.map((f) => [f.id, f]));
911
+ const known = new Set<string>(byId.keys());
912
+ const nesting = folderNesting(list);
913
+ // β›”β›” THE PARENT PASS, AND THE WHOLE POINT OF THE NEGATIVE CONTROL THAT DROPS IT. Every
914
+ // parent/child answer below reads THIS map β€” the one `folderNesting` built, with its cycles
915
+ // cut and its dangling parents re-rooted. Re-deriving the relationship from a flattened path
916
+ // string instead is the failure C9 names: nested folders collapse to one level, and a
917
+ // two-deep folder answers as though it sat at the top.
918
+ const parentOf: Record<string, string | null> = nesting.parent;
919
+ const hereId = levelIdOf(at, known);
920
+ const here = hereId == null ? null : (byId.get(hereId) ?? null);
921
+ const parent = here ? (parentOf[here.id] ?? null) : null;
922
+ const depth = here ? (nesting.depth[here.id] ?? 1) : 0;
923
+ const subfolders: F[] = [];
924
+ // ⚠ WALKED IN `nesting.ordered`, not in input order: that list is depth-first, so siblings come
925
+ // out in the order the rail already draws them and one folder moving cannot reshuffle a level.
926
+ for (const f of nesting.ordered) {
927
+ const own = byId.get(f.id);
928
+ if (!own) continue;
929
+ if ((parentOf[f.id] ?? null) === (here ? here.id : null)) subfolders.push(own);
930
+ }
931
+ const leaves: T[] = [];
932
+ for (const item of items) {
933
+ if (levelIdOf(folderIdOf(item), known) === (here ? here.id : null)) leaves.push(item);
934
+ }
935
+ return { folder: here, folders: subfolders, leaves, parent, depth };
936
+ }
937
+
938
+ /**
939
+ * ⭐ WHAT IS THE PARENT OF THIS PATH, asked all the way up β€” the breadcrumb R12.1 renders as
940
+ * "one continuous path", outermost folder first, `at` itself last.
941
+ *
942
+ * ⚠ SAME `folderNesting` PARENT MAP as {@link levelAt}, walked upward with the same walk-guard
943
+ * every other walk in this file carries: a payload that arrived with a loop cannot hang the
944
+ * render. An empty array means the top level, so a caller renders the root crumb and nothing else.
945
+ */
946
+ export function folderPath<F extends PathFolder>(
947
+ at: string | null | undefined,
948
+ folders: readonly F[]
949
+ ): F[] {
950
+ const list: F[] = [...folders];
951
+ const byId = new Map<string, F>(list.map((f) => [f.id, f]));
952
+ const nesting = folderNesting(list);
953
+ const parentOf: Record<string, string | null> = nesting.parent;
954
+ let cursor: string | null = levelIdOf(at, new Set(byId.keys()));
955
+ const out: F[] = [];
956
+ const walked = new Set<string>();
957
+ while (cursor) {
958
+ if (walked.has(cursor)) break;
959
+ walked.add(cursor);
960
+ const f = byId.get(cursor);
961
+ if (!f) break;
962
+ out.unshift(f);
963
+ cursor = parentOf[cursor] ?? null;
964
+ }
965
+ return out;
966
+ }
web/src/customer-grid/formulaEngine.ts CHANGED
@@ -6,7 +6,11 @@
6
  //
7
  // GRAMMAR (v2 β€” the shared contract; v1 remains a strict subset):
8
  // numbers 1 0.5 .5 1200.75 (no separators, no exponents)
9
- // strings "text" with "" escaping a quote β€” Excel's own rule
 
 
 
 
10
  // booleans TRUE FALSE (bare constants)
11
  // field refs {revenue_ytd} (slug charset [A-Za-z0-9_])
12
  // arithmetic + - * / ^ ( ) (usual precedence; ^ is
@@ -21,7 +25,29 @@
21
  // logic IF AND OR NOT IFERROR ISBLANK
22
  // text CONCATENATE/CONCAT LEFT RIGHT MID LEN TRIM
23
  // UPPER LOWER PROPER VALUE TEXT
 
 
24
  // date TODAY YEAR MONTH DAY DAYS (ISO YYYY-MM-DD)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
25
  //
26
  // THE ONE RULE, unchanged: **any error β†’ BLANK, never a wrong number.** An
27
  // unknown ref, a divide-by-zero, a boolean fed to arithmetic, an unreadable
@@ -67,10 +93,12 @@ export type FormulaAst =
67
  export type FormulaFn =
68
  | "ABS" | "ROUND" | "ROUNDUP" | "ROUNDDOWN" | "INT" | "MOD" | "SQRT" | "POWER"
69
  | "EXP" | "LN" | "SUM" | "AVERAGE" | "COUNT" | "COUNTA" | "MIN" | "MAX"
70
- | "IF" | "AND" | "OR" | "NOT" | "IFERROR" | "ISBLANK"
71
  | "CONCATENATE" | "LEFT" | "RIGHT" | "MID" | "LEN" | "TRIM"
72
  | "UPPER" | "LOWER" | "PROPER" | "VALUE" | "TEXT"
73
- | "TODAY" | "YEAR" | "MONTH" | "DAY" | "DAYS";
 
 
74
 
75
  const MANY = 30; // variadic cap β€” bounded, far above any honest use
76
 
@@ -97,6 +125,9 @@ const FN_ARITY: Record<FormulaFn, [number, number]> = {
97
  NOT: [1, 1],
98
  IFERROR: [2, 2],
99
  ISBLANK: [1, 1],
 
 
 
100
  CONCATENATE: [1, MANY],
101
  LEFT: [1, 2],
102
  RIGHT: [1, 2],
@@ -108,11 +139,23 @@ const FN_ARITY: Record<FormulaFn, [number, number]> = {
108
  PROPER: [1, 1],
109
  VALUE: [1, 1],
110
  TEXT: [2, 2],
 
 
 
 
 
 
 
111
  TODAY: [0, 0],
112
  YEAR: [1, 1],
113
  MONTH: [1, 1],
114
  DAY: [1, 1],
115
  DAYS: [2, 2],
 
 
 
 
 
116
  };
117
 
118
  /** Excel spells it CONCAT in modern versions; both names, one function. */
@@ -153,15 +196,20 @@ function tokenize(src: string): Token[] | string {
153
  i = end + 1;
154
  continue;
155
  }
156
- // "string" β€” Excel's own escape: "" inside a string is one quote
157
- if (c === '"') {
 
 
 
 
 
158
  let j = i + 1;
159
  let s = "";
160
  for (;;) {
161
  if (j >= src.length) return "a text value is missing its closing quote";
162
- if (src[j] === '"') {
163
- if (src[j + 1] === '"') {
164
- s += '"';
165
  j += 2;
166
  continue;
167
  }
@@ -354,7 +402,9 @@ export function parseFormula(src: string): ParseResult {
354
  }
355
  const fn = (FN_ALIASES[upper] ?? upper) as FormulaFn;
356
  if (!(fn in FN_ARITY))
357
- return fail(`unknown function ${upper} β€” see the formula help for what is available`);
 
 
358
  pos += 1;
359
  if (!isOp("(")) return fail(`${fn} must be called with parentheses: ${fn}(…)`);
360
  pos += 1;
@@ -501,6 +551,187 @@ function dateSerial(p: { y: number; m: number; d: number }): number {
501
  return Date.UTC(p.y, p.m - 1, p.d) / 86_400_000;
502
  }
503
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
504
  /**
505
  * TEXT(value, format) β€” the common Excel number formats, fail-closed:
506
  * "0" "0.00" fixed decimals
@@ -709,6 +940,18 @@ function evalNode(n: FormulaAst, get: (key: string) => unknown, env: FormulaEnv)
709
  const v = ev(n.args[0]);
710
  return v == null || v === "";
711
  }
 
 
 
 
 
 
 
 
 
 
 
 
712
  case "CONCATENATE":
713
  return n.args.map((a) => asText(ev(a))).join("");
714
  case "LEFT":
@@ -750,6 +993,75 @@ function evalNode(n: FormulaAst, get: (key: string) => unknown, env: FormulaEnv)
750
  if (v == null || typeof fmt !== "string") return null;
751
  return textFormat(v, fmt);
752
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
753
  case "TODAY":
754
  return typeof env.today === "string" && dateParts(env.today) ? env.today : null;
755
  case "YEAR":
@@ -766,6 +1078,46 @@ function evalNode(n: FormulaAst, get: (key: string) => unknown, env: FormulaEnv)
766
  if (!end || !start) return null;
767
  return Math.round(dateSerial(end) - dateSerial(start));
768
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
769
  }
770
  return null;
771
  }
@@ -774,6 +1126,25 @@ function evalNode(n: FormulaAst, get: (key: string) => unknown, env: FormulaEnv)
774
  }
775
  }
776
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
777
  function cmpNums(op: "<" | "<=" | ">" | ">=" | "=" | "!=", l: number, r: number): boolean {
778
  switch (op) {
779
  case "<": return l < r;
@@ -855,6 +1226,58 @@ export function orderFormulas(sources: ReadonlyMap<string, string>): {
855
  * can walk the graph; `selfKey` names the field being edited (absent on
856
  * create, where no cycle is possible yet).
857
  */
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
858
  export function validateFormula(
859
  src: string,
860
  knownKeys: ReadonlySet<string>,
@@ -863,6 +1286,8 @@ export function validateFormula(
863
  ): { ok: boolean; error?: string; refs: string[] } {
864
  const parsed = parseFormula(src);
865
  if (!parsed.ok) return { ok: false, error: parsed.error, refs: [] };
 
 
866
  for (const k of parsed.refs) {
867
  if (!knownKeys.has(k) && !formulaSources.has(k))
868
  return { ok: false, error: `{${k}} is not a field of this table`, refs: parsed.refs };
 
6
  //
7
  // GRAMMAR (v2 β€” the shared contract; v1 remains a strict subset):
8
  // numbers 1 0.5 .5 1200.75 (no separators, no exponents)
9
+ // strings "text" with "" escaping a quote β€” Excel's own rule.
10
+ // 'text' with '' escaping a quote β€” the SAME literal, in
11
+ // the spelling Airtable's own docs use for a unit or format
12
+ // argument: DATETIME_DIFF({a}, {b}, 'days'). A formula the
13
+ // user copies out of that documentation must parse.
14
  // booleans TRUE FALSE (bare constants)
15
  // field refs {revenue_ytd} (slug charset [A-Za-z0-9_])
16
  // arithmetic + - * / ^ ( ) (usual precedence; ^ is
 
25
  // logic IF AND OR NOT IFERROR ISBLANK
26
  // text CONCATENATE/CONCAT LEFT RIGHT MID LEN TRIM
27
  // UPPER LOWER PROPER VALUE TEXT
28
+ // SUBSTITUTE FIND REGEX_EXTRACT REGEX_REPLACE
29
+ // logic SWITCH
30
  // date TODAY YEAR MONTH DAY DAYS (ISO YYYY-MM-DD)
31
+ // DATEADD DATETIME_DIFF DATETIME_FORMAT
32
+ //
33
+ // WAVE 42 G7 β€” REGEX, SUBSTITUTION AND DATE ARITHMETIC. Three notes that are
34
+ // load-bearing rather than decorative:
35
+ //
36
+ // 1. A REGEX PATTERN IS USER INPUT REACHING A REGEX ENGINE. This runs in the
37
+ // tenant's one process, so an unbounded pattern is a denial of service and
38
+ // not merely a slow cell. `safeRegex` below is the ONLY door to `RegExp`:
39
+ // it caps the pattern, caps the SUBJECT (backtracking is exponential in
40
+ // the input, so this cap does more work than any shape test), and refuses
41
+ // the (a+)+ / (a*)* nested-unbounded-quantifier shape outright.
42
+ // 2. A PATTERN MAY NOT CONTAIN `{`. The host's structural validator reads
43
+ // `{...}` as a FIELD REFERENCE wherever it appears, including inside a
44
+ // string, so `"[0-9]{3}"` is refused on save. Refusing it here too means
45
+ // the user gets an error while typing instead of a save that fails later.
46
+ // The cost is that the `\d{4}` idiom is unavailable; `\d\d\d\d` works.
47
+ // 3. DATES ARE CALENDAR DATES. DATEADD/DATETIME_DIFF/DATETIME_FORMAT take and
48
+ // return the ISO day this engine already speaks. Time units (hours,
49
+ // minutes, seconds) are BLANK rather than approximated, and bare 'm' is
50
+ // refused because it means minutes to some readers and months to others.
51
  //
52
  // THE ONE RULE, unchanged: **any error β†’ BLANK, never a wrong number.** An
53
  // unknown ref, a divide-by-zero, a boolean fed to arithmetic, an unreadable
 
93
  export type FormulaFn =
94
  | "ABS" | "ROUND" | "ROUNDUP" | "ROUNDDOWN" | "INT" | "MOD" | "SQRT" | "POWER"
95
  | "EXP" | "LN" | "SUM" | "AVERAGE" | "COUNT" | "COUNTA" | "MIN" | "MAX"
96
+ | "IF" | "AND" | "OR" | "NOT" | "IFERROR" | "ISBLANK" | "SWITCH"
97
  | "CONCATENATE" | "LEFT" | "RIGHT" | "MID" | "LEN" | "TRIM"
98
  | "UPPER" | "LOWER" | "PROPER" | "VALUE" | "TEXT"
99
+ | "SUBSTITUTE" | "FIND" | "REGEX_EXTRACT" | "REGEX_REPLACE"
100
+ | "TODAY" | "YEAR" | "MONTH" | "DAY" | "DAYS"
101
+ | "DATEADD" | "DATETIME_DIFF" | "DATETIME_FORMAT";
102
 
103
  const MANY = 30; // variadic cap β€” bounded, far above any honest use
104
 
 
125
  NOT: [1, 1],
126
  IFERROR: [2, 2],
127
  ISBLANK: [1, 1],
128
+ // SWITCH(subject, pattern, result, [pattern, result]…, [fallback]) β€” at least
129
+ // one pair, so three arguments is the floor.
130
+ SWITCH: [3, MANY],
131
  CONCATENATE: [1, MANY],
132
  LEFT: [1, 2],
133
  RIGHT: [1, 2],
 
139
  PROPER: [1, 1],
140
  VALUE: [1, 1],
141
  TEXT: [2, 2],
142
+ // SUBSTITUTE(text, old, new, [occurrence]) β€” the 4th argument picks ONE
143
+ // occurrence, 1-based; without it every occurrence is replaced.
144
+ SUBSTITUTE: [3, 4],
145
+ // FIND(stringToFind, whereToSearch, [startFromPosition]) β€” NEEDLE FIRST.
146
+ FIND: [2, 3],
147
+ REGEX_EXTRACT: [2, 2],
148
+ REGEX_REPLACE: [3, 3],
149
  TODAY: [0, 0],
150
  YEAR: [1, 1],
151
  MONTH: [1, 1],
152
  DAY: [1, 1],
153
  DAYS: [2, 2],
154
+ // DATEADD(date, count, units) and DATETIME_DIFF(date1, date2, [units]) β€”
155
+ // Airtable's own order, confirmed against its documentation screenshots.
156
+ DATEADD: [3, 3],
157
+ DATETIME_DIFF: [2, 3],
158
+ DATETIME_FORMAT: [2, 2],
159
  };
160
 
161
  /** Excel spells it CONCAT in modern versions; both names, one function. */
 
196
  i = end + 1;
197
  continue;
198
  }
199
+ // "string" / 'string' β€” Excel's own escape: a doubled quote is one quote.
200
+ // ONE literal in two spellings: Airtable's documentation writes a unit or a
201
+ // date format in single quotes ('days', 'MM/DD/YYYY') and a user pastes it
202
+ // exactly as printed, so both must parse. A quote of the OTHER kind inside
203
+ // is an ordinary character, which is what makes "it's" and 'say "hi"' work.
204
+ if (c === '"' || c === "'") {
205
+ const q = c;
206
  let j = i + 1;
207
  let s = "";
208
  for (;;) {
209
  if (j >= src.length) return "a text value is missing its closing quote";
210
+ if (src[j] === q) {
211
+ if (src[j + 1] === q) {
212
+ s += q;
213
  j += 2;
214
  continue;
215
  }
 
402
  }
403
  const fn = (FN_ALIASES[upper] ?? upper) as FormulaFn;
404
  if (!(fn in FN_ARITY))
405
+ // β›” STANDING RULE 2. This message carried an em dash until wave 42; it is
406
+ // user-facing copy, so the sentence is rewritten rather than the character dropped.
407
+ return fail(`${upper} is not a function this engine knows. The formula help lists what is available.`);
408
  pos += 1;
409
  if (!isOp("(")) return fail(`${fn} must be called with parentheses: ${fn}(…)`);
410
  pos += 1;
 
551
  return Date.UTC(p.y, p.m - 1, p.d) / 86_400_000;
552
  }
553
 
554
+ // ---------------------------------------------------------------------------
555
+ // WAVE 42 G7 β€” the bounded regex door.
556
+ // ---------------------------------------------------------------------------
557
+
558
+ /** Longest pattern a formula may hand to the regex engine. */
559
+ export const MAX_REGEX_PATTERN = 200;
560
+ /** Longest subject a pattern may run OVER. Catastrophic backtracking is
561
+ * exponential in the INPUT length, so this cap is the load-bearing one: a
562
+ * pathological pattern over 4 000 characters is slow, over a 100 KB long-text
563
+ * field it is a hung tab. */
564
+ export const MAX_REGEX_SUBJECT = 4_000;
565
+ /** Longest text result a substitution may produce, so a replacement cannot be
566
+ * used to inflate one cell into megabytes. */
567
+ export const MAX_TEXT_RESULT = 20_000;
568
+
569
+ /**
570
+ * The catastrophic shape: a parenthesised group whose body already carries an
571
+ * unbounded quantifier, quantified AGAIN. `(a+)+`, `(a*)*`, `(?:\d+)*` and
572
+ * friends. Matching those against a non-matching subject is exponential.
573
+ *
574
+ * ⚠ It is applied ONLY to a pattern, never to whole formula source. `({a} + {b}) * 2`
575
+ * has exactly this character shape and is ordinary arithmetic.
576
+ */
577
+ const NESTED_QUANT = /\((?:[^()\\]|\\.)*[*+](?:[^()\\]|\\.)*\)\??\s*[*+]/;
578
+
579
+ /** Compiled patterns, so a formula re-evaluated per row per render compiles
580
+ * once rather than once per cell. Bounded, and cleared wholesale when full. */
581
+ const RX_CACHE = new Map<string, RegExp | null>();
582
+ const RX_CACHE_MAX = 200;
583
+
584
+ /**
585
+ * The ONE door to `RegExp` in this engine. Returns null (which is BLANK, the
586
+ * engine's one rule) for anything unbounded, malformed, or carrying `{`.
587
+ */
588
+ function safeRegex(pattern: string, flags: string): RegExp | null {
589
+ if (typeof pattern !== "string") return null;
590
+ if (pattern === "" || pattern.length > MAX_REGEX_PATTERN) return null;
591
+ // `{` cannot appear: the host reads `{...}` as a field reference wherever it
592
+ // sits, so a pattern containing one is refused on SAVE. Refusing it here
593
+ // keeps both sides saying the same thing.
594
+ if (pattern.includes("{") || pattern.includes("}")) return null;
595
+ if (NESTED_QUANT.test(pattern)) return null;
596
+ // The separator is written as an ESCAPE, not as a literal NUL byte. A raw NUL byte in the
597
+ // source makes every `grep` classify this file as BINARY and skip it silently, which
598
+ // blinds any gate or reader that searches it -- the file is unsearchable, not merely
599
+ // odd. The runtime value is identical; only the source encoding changes.
600
+ const key = flags + "\u0000" + pattern;
601
+ const hit = RX_CACHE.get(key);
602
+ if (hit !== undefined) return hit;
603
+ let rx: RegExp | null = null;
604
+ try {
605
+ rx = new RegExp(pattern, flags);
606
+ } catch {
607
+ rx = null;
608
+ }
609
+ if (RX_CACHE.size >= RX_CACHE_MAX) RX_CACHE.clear();
610
+ RX_CACHE.set(key, rx);
611
+ return rx;
612
+ }
613
+
614
+ // ---------------------------------------------------------------------------
615
+ // WAVE 42 G7 β€” calendar arithmetic over the ISO day this engine already speaks.
616
+ // ---------------------------------------------------------------------------
617
+
618
+ type DateUnit = "d" | "w" | "M" | "Q" | "y";
619
+
620
+ /**
621
+ * Airtable's unit words, plus the unambiguous single letters. Bare 'm' is
622
+ * ABSENT on purpose: it reads as minutes to one person and months to another,
623
+ * and a date silently off by 30 days is exactly the wrong-number-with-a-
624
+ * confident-face this engine refuses to produce.
625
+ */
626
+ const DATE_UNITS: Record<string, DateUnit> = {
627
+ day: "d", days: "d", d: "d",
628
+ week: "w", weeks: "w", w: "w",
629
+ month: "M", months: "M",
630
+ quarter: "Q", quarters: "Q", q: "Q",
631
+ year: "y", years: "y", y: "y",
632
+ };
633
+
634
+ function dateUnit(v: Value): DateUnit | null {
635
+ if (typeof v !== "string") return null;
636
+ const k = v.trim().toLowerCase();
637
+ return DATE_UNITS[k] ?? null;
638
+ }
639
+
640
+ function pad(n: number, width: number): string {
641
+ const s = String(Math.abs(n));
642
+ return (n < 0 ? "-" : "") + (s.length >= width ? s : "0".repeat(width - s.length) + s);
643
+ }
644
+
645
+ function isoFromParts(p: { y: number; m: number; d: number }): string {
646
+ return pad(p.y, 4) + "-" + pad(p.m, 2) + "-" + pad(p.d, 2);
647
+ }
648
+
649
+ function daysInMonth(y: number, m: number): number {
650
+ return new Date(Date.UTC(y, m, 0)).getUTCDate();
651
+ }
652
+
653
+ /** Calendar month arithmetic with Excel's clamp: 31 Jan plus one month is the
654
+ * 28th (or 29th) of February, never the 3rd of March. */
655
+ function addMonths(p: { y: number; m: number; d: number }, k: number) {
656
+ const total = p.y * 12 + (p.m - 1) + k;
657
+ const y = Math.floor(total / 12);
658
+ const m = total - y * 12 + 1;
659
+ return { y, m, d: Math.min(p.d, daysInMonth(y, m)) };
660
+ }
661
+
662
+ function partsFromSerial(serial: number) {
663
+ const d = new Date(serial * 86_400_000);
664
+ return { y: d.getUTCFullYear(), m: d.getUTCMonth() + 1, d: d.getUTCDate() };
665
+ }
666
+
667
+ /** Whole months from `b` to `a`, the calendar way: 31 Jan to 28 Feb is 0. */
668
+ function wholeMonths(
669
+ a: { y: number; m: number; d: number },
670
+ b: { y: number; m: number; d: number }
671
+ ): number {
672
+ let n = (a.y - b.y) * 12 + (a.m - b.m);
673
+ if (n > 0 && a.d < b.d) n -= 1;
674
+ if (n < 0 && a.d > b.d) n += 1;
675
+ return n;
676
+ }
677
+
678
+ const MONTH_NAMES = [
679
+ "January", "February", "March", "April", "May", "June",
680
+ "July", "August", "September", "October", "November", "December",
681
+ ];
682
+ const DAY_NAMES = [
683
+ "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday",
684
+ ];
685
+
686
+ /** Longest format string DATETIME_FORMAT will look at. */
687
+ const MAX_DATE_FORMAT = 64;
688
+
689
+ /**
690
+ * DATETIME_FORMAT's token set: YYYY YY MMMM MMM MM M DD D dddd ddd Q, with
691
+ * `[literal]` escaping a run of text. Punctuation passes through. An
692
+ * UNRECOGNISED letter is BLANK, never a guess at what it meant, which is
693
+ * `textFormat`'s convention one function up and the same reason for it.
694
+ */
695
+ function formatDate(p: { y: number; m: number; d: number }, fmt: string): string | null {
696
+ if (fmt.length === 0 || fmt.length > MAX_DATE_FORMAT) return null;
697
+ const dow = ((Math.round(dateSerial(p)) % 7) + 7 + 4) % 7; // serial 0 was a Thursday
698
+ let out = "";
699
+ let i = 0;
700
+ while (i < fmt.length) {
701
+ const ch = fmt[i];
702
+ if (ch === "[") {
703
+ const end = fmt.indexOf("]", i + 1);
704
+ if (end < 0) return null;
705
+ out += fmt.slice(i + 1, end);
706
+ i = end + 1;
707
+ continue;
708
+ }
709
+ const m = /^(YYYY|YY|MMMM|MMM|MM|M|DDDD|DD|D|dddd|ddd|Q)/.exec(fmt.slice(i));
710
+ if (m) {
711
+ switch (m[0]) {
712
+ case "YYYY": out += pad(p.y, 4); break;
713
+ case "YY": out += pad(p.y % 100, 2); break;
714
+ case "MMMM": out += MONTH_NAMES[p.m - 1]; break;
715
+ case "MMM": out += MONTH_NAMES[p.m - 1].slice(0, 3); break;
716
+ case "MM": out += pad(p.m, 2); break;
717
+ case "M": out += String(p.m); break;
718
+ case "DDDD":
719
+ case "dddd": out += DAY_NAMES[dow]; break;
720
+ case "ddd": out += DAY_NAMES[dow].slice(0, 3); break;
721
+ case "DD": out += pad(p.d, 2); break;
722
+ case "D": out += String(p.d); break;
723
+ case "Q": out += String(Math.floor((p.m - 1) / 3) + 1); break;
724
+ }
725
+ i += m[0].length;
726
+ continue;
727
+ }
728
+ if (/[A-Za-z]/.test(ch)) return null; // an unknown token is blank, not a literal
729
+ out += ch;
730
+ i += 1;
731
+ }
732
+ return out;
733
+ }
734
+
735
  /**
736
  * TEXT(value, format) β€” the common Excel number formats, fail-closed:
737
  * "0" "0.00" fixed decimals
 
940
  const v = ev(n.args[0]);
941
  return v == null || v === "";
942
  }
943
+ case "SWITCH": {
944
+ // SWITCH(subject, pattern, result, [pattern, result]…, [fallback]).
945
+ // LAZY like IF: only the arm that wins is evaluated, so a guard arm
946
+ // can protect the arithmetic in the arm beside it.
947
+ const subject = ev(n.args[0]);
948
+ let i = 1;
949
+ for (; i + 1 < n.args.length; i += 2) {
950
+ if (switchMatch(subject, ev(n.args[i]))) return ev(n.args[i + 1]);
951
+ }
952
+ // A leftover odd argument is the fallback; without one, blank.
953
+ return i < n.args.length ? ev(n.args[i]) : null;
954
+ }
955
  case "CONCATENATE":
956
  return n.args.map((a) => asText(ev(a))).join("");
957
  case "LEFT":
 
993
  if (v == null || typeof fmt !== "string") return null;
994
  return textFormat(v, fmt);
995
  }
996
+ case "SUBSTITUTE": {
997
+ // SUBSTITUTE(text, oldText, newText, [occurrence]) β€” plain text, no
998
+ // pattern, so nothing here reaches the regex engine.
999
+ const s = asText(ev(n.args[0]));
1000
+ const oldText = asText(ev(n.args[1]));
1001
+ const newText = asText(ev(n.args[2]));
1002
+ if (oldText === "") return s; // replacing nothing is the identity
1003
+ let out: string = s;
1004
+ if (n.args.length > 3) {
1005
+ const k = asNumber(ev(n.args[3]));
1006
+ if (k == null || !Number.isInteger(k) || k < 1) return null;
1007
+ let from = 0;
1008
+ let seen = 0;
1009
+ for (;;) {
1010
+ const at = s.indexOf(oldText, from);
1011
+ if (at < 0) return s; // fewer than k occurrences: unchanged
1012
+ seen += 1;
1013
+ if (seen === k) {
1014
+ out = s.slice(0, at) + newText + s.slice(at + oldText.length);
1015
+ break;
1016
+ }
1017
+ from = at + oldText.length;
1018
+ }
1019
+ } else {
1020
+ out = s.split(oldText).join(newText);
1021
+ }
1022
+ return out.length > MAX_TEXT_RESULT ? null : out;
1023
+ }
1024
+ case "FIND": {
1025
+ // FIND(stringToFind, whereToSearch, [startFromPosition]) β€” NEEDLE
1026
+ // FIRST, 1-based, and 0 (not blank) when it is not there, because
1027
+ // "absent" is an answer and callers test it with = 0.
1028
+ // Case-SENSITIVE, as FIND is in both Excel and Airtable.
1029
+ const needle = asText(ev(n.args[0]));
1030
+ const hay = asText(ev(n.args[1]));
1031
+ let start = 1;
1032
+ if (n.args.length > 2) {
1033
+ const k = asNumber(ev(n.args[2]));
1034
+ if (k == null || !Number.isInteger(k) || k < 1) return null;
1035
+ start = k;
1036
+ }
1037
+ const at = hay.indexOf(needle, start - 1);
1038
+ return at < 0 ? 0 : at + 1;
1039
+ }
1040
+ case "REGEX_EXTRACT": {
1041
+ // REGEX_EXTRACT(text, pattern) -> the FIRST WHOLE MATCH, blank when
1042
+ // the pattern does not match. (Airtable returns the whole match, not
1043
+ // a capture group; a group is still useful for grouping alternation.)
1044
+ const s = asText(ev(n.args[0]));
1045
+ const pat = ev(n.args[1]);
1046
+ if (typeof pat !== "string" || s.length > MAX_REGEX_SUBJECT) return null;
1047
+ const rx = safeRegex(pat, "");
1048
+ if (!rx) return null;
1049
+ const m = rx.exec(s);
1050
+ return m ? m[0] : null;
1051
+ }
1052
+ case "REGEX_REPLACE": {
1053
+ // REGEX_REPLACE(text, pattern, replacement) -> EVERY match replaced.
1054
+ const s = asText(ev(n.args[0]));
1055
+ const pat = ev(n.args[1]);
1056
+ const rep = asText(ev(n.args[2]));
1057
+ if (typeof pat !== "string" || s.length > MAX_REGEX_SUBJECT) return null;
1058
+ if (rep.length > MAX_REGEX_PATTERN) return null;
1059
+ const rx = safeRegex(pat, "g");
1060
+ if (!rx) return null;
1061
+ rx.lastIndex = 0; // a cached /g/ regex carries state between calls
1062
+ const out = s.replace(rx, rep);
1063
+ return out.length > MAX_TEXT_RESULT ? null : out;
1064
+ }
1065
  case "TODAY":
1066
  return typeof env.today === "string" && dateParts(env.today) ? env.today : null;
1067
  case "YEAR":
 
1078
  if (!end || !start) return null;
1079
  return Math.round(dateSerial(end) - dateSerial(start));
1080
  }
1081
+ case "DATEADD": {
1082
+ // DATEADD(date, count, units) -> the ISO day, shifted. Airtable's own
1083
+ // argument order, read off its documentation.
1084
+ const p = dateParts(ev(n.args[0]));
1085
+ const count = asNumber(ev(n.args[1]));
1086
+ const unit = dateUnit(ev(n.args[2]));
1087
+ if (!p || count == null || !unit) return null;
1088
+ const k = Math.trunc(count);
1089
+ if (!Number.isFinite(k) || Math.abs(k) > 1_000_000) return null;
1090
+ if (unit === "M") return isoFromParts(addMonths(p, k));
1091
+ if (unit === "Q") return isoFromParts(addMonths(p, k * 3));
1092
+ if (unit === "y") return isoFromParts(addMonths(p, k * 12));
1093
+ const shifted = dateSerial(p) + (unit === "w" ? k * 7 : k);
1094
+ if (!Number.isFinite(shifted) || Math.abs(shifted) > 3_000_000) return null;
1095
+ return isoFromParts(partsFromSerial(shifted));
1096
+ }
1097
+ case "DATETIME_DIFF": {
1098
+ // DATETIME_DIFF(date1, date2, [units]) = date1 MINUS date2, so a due
1099
+ // date ahead of a start date is POSITIVE. Units default to days.
1100
+ // Truncated toward zero: a part-week is not a week.
1101
+ const a = dateParts(ev(n.args[0]));
1102
+ const b = dateParts(ev(n.args[1]));
1103
+ if (!a || !b) return null;
1104
+ const unit = n.args.length > 2 ? dateUnit(ev(n.args[2])) : "d";
1105
+ if (!unit) return null;
1106
+ const days = Math.round(dateSerial(a) - dateSerial(b));
1107
+ if (unit === "d") return days;
1108
+ if (unit === "w") return Math.trunc(days / 7);
1109
+ const months = wholeMonths(a, b);
1110
+ if (unit === "M") return months;
1111
+ if (unit === "Q") return Math.trunc(months / 3);
1112
+ return Math.trunc(months / 12);
1113
+ }
1114
+ case "DATETIME_FORMAT": {
1115
+ // DATETIME_FORMAT(date, format) -> text in the caller's spelling.
1116
+ const p = dateParts(ev(n.args[0]));
1117
+ const fmt = ev(n.args[1]);
1118
+ if (!p || typeof fmt !== "string") return null;
1119
+ return formatDate(p, fmt);
1120
+ }
1121
  }
1122
  return null;
1123
  }
 
1126
  }
1127
  }
1128
 
1129
+ /**
1130
+ * SWITCH's arm test. It follows the engine's OWN equality rather than inventing
1131
+ * a second one: numbers (and numeric text) compare numerically, text compares
1132
+ * case-insensitively after trimming, and blank matches blank. A mixed pair does
1133
+ * NOT match, so it simply falls through to the next arm or the fallback.
1134
+ */
1135
+ function switchMatch(subject: Value, pattern: Value): boolean {
1136
+ if (subject == null || subject === "") return pattern == null || pattern === "";
1137
+ if (pattern == null || pattern === "") return false;
1138
+ if (typeof subject === "boolean" || typeof pattern === "boolean")
1139
+ return subject === pattern;
1140
+ const a = asNumber(subject);
1141
+ const b = asNumber(pattern);
1142
+ if (a != null && b != null) return a === b;
1143
+ if (typeof subject === "string" && typeof pattern === "string")
1144
+ return subject.trim().toLowerCase() === pattern.trim().toLowerCase();
1145
+ return false;
1146
+ }
1147
+
1148
  function cmpNums(op: "<" | "<=" | ">" | ">=" | "=" | "!=", l: number, r: number): boolean {
1149
  switch (op) {
1150
  case "<": return l < r;
 
1226
  * can walk the graph; `selfKey` names the field being edited (absent on
1227
  * create, where no cycle is possible yet).
1228
  */
1229
+ /**
1230
+ * β›”β›” THE COMPOSITE HOLE, closed at AUTHORING time (wave 42 G7).
1231
+ *
1232
+ * A pattern this engine refuses at EVALUATION time is still a formula that parses, and the
1233
+ * host's wall is structural, so `REGEX_EXTRACT({notes}, "[0-9]{3}")` SAVES and then reads
1234
+ * blank forever with nothing going red. That is this ticket's own scar wearing the other
1235
+ * face: last time a legal formula could not be stored, this time an unusable one can.
1236
+ *
1237
+ * So a pattern written as a LITERAL is put through `safeRegex` here, where the author is
1238
+ * still looking at it. A pattern assembled at run time cannot be judged from the tree and
1239
+ * degrades to blank, which is the engine's one rule and the honest answer.
1240
+ */
1241
+ function badPattern(ast: FormulaAst): string | null {
1242
+ let problem: string | null = null;
1243
+ const walk = (n: FormulaAst): void => {
1244
+ if (problem) return;
1245
+ switch (n.t) {
1246
+ case "neg":
1247
+ walk(n.e);
1248
+ return;
1249
+ case "bin":
1250
+ case "cmp":
1251
+ walk(n.l);
1252
+ walk(n.r);
1253
+ return;
1254
+ case "call": {
1255
+ if (n.fn === "REGEX_EXTRACT" || n.fn === "REGEX_REPLACE") {
1256
+ const p = n.args[1];
1257
+ if (p && p.t === "str") {
1258
+ if (p.v.includes("{") || p.v.includes("}"))
1259
+ problem =
1260
+ "a search pattern cannot contain { or }, because a formula reads those as a " +
1261
+ "field name. Write \\d\\d\\d rather than \\d{3}.";
1262
+ else if (p.v === "" || p.v.length > MAX_REGEX_PATTERN)
1263
+ problem = `a search pattern must be 1 to ${MAX_REGEX_PATTERN} characters long`;
1264
+ else if (safeRegex(p.v, "") === null)
1265
+ problem =
1266
+ "that search pattern is either not valid or could run for an unbounded time. " +
1267
+ "A repeat inside a repeated group, such as (a+)+, is refused.";
1268
+ }
1269
+ }
1270
+ n.args.forEach(walk);
1271
+ return;
1272
+ }
1273
+ default:
1274
+ return;
1275
+ }
1276
+ };
1277
+ walk(ast);
1278
+ return problem;
1279
+ }
1280
+
1281
  export function validateFormula(
1282
  src: string,
1283
  knownKeys: ReadonlySet<string>,
 
1286
  ): { ok: boolean; error?: string; refs: string[] } {
1287
  const parsed = parseFormula(src);
1288
  if (!parsed.ok) return { ok: false, error: parsed.error, refs: [] };
1289
+ const patternError = badPattern(parsed.ast);
1290
+ if (patternError) return { ok: false, error: patternError, refs: parsed.refs };
1291
  for (const k of parsed.refs) {
1292
  if (!knownKeys.has(k) && !formulaSources.has(k))
1293
  return { ok: false, error: `{${k}} is not a field of this table`, refs: parsed.refs };
web/src/customer-grid/types.ts CHANGED
@@ -102,7 +102,21 @@ export const AI_STATE_PREFIX = "_ai_";
102
  /** What `_ai_<colId>` can say. `empty` is never stamped: an absent key IS empty. */
103
  export type AiCellState = "agent" | "human" | "stale" | "error";
104
 
105
- export type FieldSource = "odoo" | "overlay";
 
 
 
 
 
 
 
 
 
 
 
 
 
 
106
 
107
  /**
108
  * R13 β€” the languages a `code` column may declare. Mirrors `aios_grid.CODE_LANGUAGES`
@@ -227,7 +241,18 @@ export const CREATABLE_TYPES: readonly FieldType[] = [
227
  * asymmetry is honest rather than an oversight, and it is the reason the exported set below is
228
  * `string[]` while its first half is not.
229
  */
230
- const ADVANCED_FIELD_KINDS: readonly FieldType[] = ["automation", "json", "code", "ai_enrich"];
 
 
 
 
 
 
 
 
 
 
 
231
 
232
  /** The advanced set the picker groups on: the four real types above plus the geocode pseudo-kind,
233
  * which joins by VALUE because it cannot join by type. */
@@ -241,6 +266,87 @@ export const ADVANCED_CREATE_KINDS: readonly string[] = [...ADVANCED_FIELD_KINDS
241
  */
242
  export const ADVANCED_TYPES_HEADING = "Advanced";
243
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
244
  /** A run of field-type picker rows under an optional heading. `heading: null` is the ordinary
245
  * group, deliberately unlabelled: naming the majority case is chrome nobody reads, and the
246
  * divider under it already says where the ordinary list ends. */
@@ -331,14 +437,49 @@ export function isPickType(t: FieldType): boolean {
331
  }
332
 
333
  /**
334
- * One choice per line, blanks dropped, duplicates collapsed, order preserved, capped at 50.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
335
  * Case-INSENSITIVE dedupe: "Blocked" and "blocked" are one choice to a human, so the first
336
  * spelling wins rather than the column growing two pills that look like a typo.
337
  *
338
  * Lives here, not in ColumnMenu.tsx β€” a component file that also exports plain functions
339
  * breaks React fast refresh (the same reason counts.ts is its own module).
340
  */
341
- export function parseOptions(text: string): string[] {
342
  const seen = new Set<string>();
343
  const out: string[] = [];
344
  for (const raw of text.split("\n")) {
@@ -349,7 +490,19 @@ export function parseOptions(text: string): string[] {
349
  seen.add(k);
350
  out.push(v);
351
  }
352
- return out.slice(0, 50);
 
 
 
 
 
 
 
 
 
 
 
 
353
  }
354
 
355
  /**
@@ -385,7 +538,44 @@ export function uniqueDisplayName(
385
  * condition on it reads as a fact about the customer. It still displays and still sorts.
386
  */
387
  export function filterableFields(fields: Field[]): Field[] {
388
- return fields.filter((f) => f.filterable !== false);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
389
  }
390
 
391
  /** Wave-5 item 10 β€” per-field display format. One optional bag; each type reads its half. */
@@ -2062,6 +2252,11 @@ export function directionLabel(t: FieldType, dir: "asc" | "desc"): string {
2062
  * "(empty)" group every other type uses.
2063
  */
2064
  export function isGroupableField(field: Field, lockedKey: string): boolean {
 
 
 
 
 
2065
  return (
2066
  field.type === "status" ||
2067
  field.type === "select" ||
@@ -2105,6 +2300,17 @@ export interface Field {
2105
  * reason (see `runPipeline`).
2106
  */
2107
  multi?: boolean;
 
 
 
 
 
 
 
 
 
 
 
2108
  /** header pin hint from the API (unused in Inc 0) */
2109
  pinned?: boolean;
2110
  /** default-visible unless explicitly false */
@@ -2145,6 +2351,16 @@ export interface Field {
2145
  preset?: boolean;
2146
  /** Choices for a `select` / `multiselect` field. Ignored for every other type. */
2147
  options?: string[];
 
 
 
 
 
 
 
 
 
 
2148
  /**
2149
  * Whether select-family choices render with coloured pills. Absent means true so legacy
2150
  * fields keep their existing appearance; an explicit false is the user's opt-out.
@@ -2393,6 +2609,42 @@ export interface Field {
2393
  reciprocal?: string;
2394
  /** Airtable's `prefersSingleRecordLink` */
2395
  single?: boolean;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2396
  };
2397
  /**
2398
  * ⭐ 2026-08-07 β€” an AGGREGATE over the rows a `link` column resolves (Airtable's `rollup`).
@@ -2532,6 +2784,58 @@ export const ROLLUP_FNS = [
2532
  ] as const;
2533
  export type RollupFn = (typeof ROLLUP_FNS)[number];
2534
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2535
  /** The rollup functions whose RESULT is a number β€” the render/align/sort family. */
2536
  export const ROLLUP_NUMERIC_FNS: ReadonlySet<string> =
2537
  new Set(["sum", "average", "stdev", "min", "max", "count", "counta", "countall"]);
@@ -3355,6 +3659,143 @@ export function filterTreeConj(tree: FilterTree | null | undefined): Conjunction
3355
  return tree?.conj === "or" ? "or" : "and";
3356
  }
3357
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3358
  export type RowHeightMode = "short" | "medium" | "tall";
3359
  export type ThemeMode = "light" | "dark";
3360
 
@@ -3442,13 +3883,20 @@ export interface ViewConfig {
3442
  * the primary filter carried across. Absent = the ordinary view of its own table, which is
3443
  * every view saved before this wave (no migration, the `memberPids` precedent).
3444
  *
3445
- * β›” **THE CLIENT HALF OF C6 IS ONLY HALF THE ROUND TRIP, AND THE OTHER HALF IS NOT IN THIS
3446
- * WAVE.** `normalizeConfig` spreads, so this key survives the read; `sameConfig` is a whole
3447
- * object compare, so it is picked up free. But the SERVER rebuilds the stored config from a
3448
- * name allowlist in `platform/core/grid_events.py::handle_one` (`kind == 'view_upsert'`), and
3449
- * that literal's own comment says a key it does not name is silently dropped while the write
3450
- * still answers 200. No wave-41 ticket names that file. Until one does, a pivot renders and
3451
- * does not persist [[two-lanes-one-contract-dead-feature]].
 
 
 
 
 
 
 
3452
  */
3453
  secondaryView?: SecondaryView;
3454
  }
@@ -3580,6 +4028,13 @@ export function cleanSecondaryView(raw: unknown): SecondaryView | undefined {
3580
  *
3581
  * ⚠ AN EMPTY LIST IS A TRUTHFUL ANSWER, not a failure: it means this table has no link field
3582
  * yet. The control says so rather than offering a pivot that cannot be resolved.
 
 
 
 
 
 
 
3583
  */
3584
  export function relationalTargets(fields: Field[]): RelationalTarget[] {
3585
  const out: RelationalTarget[] = [];
@@ -3654,6 +4109,13 @@ export interface PivotResponse {
3654
  * ⚠ `filters` is the SOURCE view's tree, passed straight through. That is how the primary filter
3655
  * is carried across (owner instruction 23) and it is also T44's door: one record is one filter
3656
  * naming it, not a new request shape.
 
 
 
 
 
 
 
3657
  */
3658
  export function buildPivotRequest(
3659
  source: string,
@@ -3715,6 +4177,65 @@ export function pivotResponse(body: unknown): PivotResponse | null {
3715
  };
3716
  }
3717
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3718
  /**
3719
  * wave17 R1 / contract C-LOCKV β€” **`"locked"` joins the vocabulary, and it is the whole of the
3720
  * client's model of a locked view.**
 
102
  /** What `_ai_<colId>` can say. `empty` is never stamped: an absent key IS empty. */
103
  export type AiCellState = "agent" | "human" | "stale" | "error";
104
 
105
+ /**
106
+ * ⭐⭐ W42-T09 (contract C2) β€” `"topic"` JOINS THE VOCABULARY, and the reason it must be widened
107
+ * HERE rather than loosened at the boundary that consumes it is the whole point of the ticket.
108
+ *
109
+ * `GET /grid/hop-topics` hands the client a governed topic's dimensions already shaped as
110
+ * `Field[]` so the existing condition builder can take them as its `fields` prop with no adapter
111
+ * in between; those fields describe a column of the SEMANTIC MODEL, not a column of this
112
+ * workspace, and `"odoo"` would be a lie about where they come from while `"overlay"` would make
113
+ * them look editable.
114
+ *
115
+ * ⚠ NOTHING RENDERS ONE AS A GRID COLUMN. A topic dim reaches only `hopTopics[].dims`, which the
116
+ * link editor feeds to `FilterBuilderPanel` as an operand list; it never enters the grid's own
117
+ * `fields` array, so no editability, permission or formatting path is asked about `"topic"`.
118
+ */
119
+ export type FieldSource = "odoo" | "overlay" | "topic";
120
 
121
  /**
122
  * R13 β€” the languages a `code` column may declare. Mirrors `aios_grid.CODE_LANGUAGES`
 
241
  * asymmetry is honest rather than an oversight, and it is the reason the exported set below is
242
  * `string[]` while its first half is not.
243
  */
244
+ const ADVANCED_FIELD_KINDS: readonly FieldType[] = [
245
+ "automation", "json", "code", "ai_enrich",
246
+ // ⭐⭐ W42-T37 (owner instruction 20) β€” AND IT IS SEVEN. The relational pair and the formula
247
+ // column join the group, so the unheaded list above it holds only the kinds somebody types a
248
+ // value into. Named outright by the instruction, like the five before them, and READ from that
249
+ // ruling rather than inferred from any property these three share.
250
+ //
251
+ // ⚠ THEY GO HERE, IN THE TYPED HALF, AND NOT IN THE EXPORTED `string[]` BELOW. This array is
252
+ // `readonly FieldType[]`, so a misspelling fails `tsc`; the exported set is `string[]` because
253
+ // one PSEUDO-kind cannot be typed, and a name added there groups nothing and says nothing.
254
+ "link", "rollup", "formula",
255
+ ];
256
 
257
  /** The advanced set the picker groups on: the four real types above plus the geocode pseudo-kind,
258
  * which joins by VALUE because it cannot join by type. */
 
266
  */
267
  export const ADVANCED_TYPES_HEADING = "Advanced";
268
 
269
+ /**
270
+ * ⭐⭐ W42-T37 (ruling R24) β€” THE PICKER'S PLAIN-LANGUAGE LINE, one per type, under its label.
271
+ *
272
+ * β›”β›” IT IS A CORRECTION, NOT POLISH, AND `rollup` IS WHY THE TABLE EXISTS. The owner chose to
273
+ * KEEP the label "Rollup from another record", and that label is wrong twice: singular, where a
274
+ * rollup folds MANY records, and false for the read-through mode, whose bag needs a topic, a
275
+ * measure, a grouping and a matching column and NO LINK AT ALL. The label is settled, so this
276
+ * line is the only place the truth gets told, and its entry must cover both modes or the type
277
+ * still ships mis-described.
278
+ *
279
+ * ⚠ NO DASH OF ANY KIND IN ANY SENTENCE HERE (standing rule 2). Every one of these reaches a
280
+ * screen, and a description is exactly where an em dash reads naturally; use a colon, a
281
+ * semicolon, or two sentences.
282
+ *
283
+ * β›” IT LIVES HERE RATHER THAN BESIDE `TYPE_LABELS` for the reason this file's grouping helper
284
+ * already gives: `iconShapes.ts` and `ColumnMenu.tsx` are not loadable by the node gates, and a
285
+ * sentence no gate can read is a sentence that silently rots. `Record<..., string>` over the
286
+ * whole picker vocabulary is what makes `tsc` the enforcer: a new kind with no description here
287
+ * does not compile.
288
+ */
289
+ export const TYPE_DESCRIPTIONS: Record<
290
+ FieldType | "measure" | "geocode" | "count" | "lookup",
291
+ string
292
+ > = {
293
+ text: "Words typed in by hand: a name, a note, a reference.",
294
+ status: "A workflow state chosen from a fixed list.",
295
+ select: "One choice from a list you define.",
296
+ multiselect: "Any number of choices from a list you define.",
297
+ user: "The person a record belongs to.",
298
+ int: "A whole number, with no decimals.",
299
+ currency: "An amount of money, shown with its symbol.",
300
+ pct: "A percentage, stored as the number people say out loud.",
301
+ date: "A calendar date, with an optional time of day.",
302
+ checkbox: "A yes or no box.",
303
+ phone: "A phone number, dialable from the cell.",
304
+ email: "An email address, ready to write to.",
305
+ url: "A web address that opens in a new tab.",
306
+ rating: "A score out of five, drawn as stars.",
307
+ created_time: "When the record was first created. Filled in for you.",
308
+ formula: "A value calculated from this row's other columns.",
309
+ automation: "A value a scheduled job writes; nobody types into it.",
310
+ metric: "A business number over a time window, computed at read time.",
311
+ image: "A picture: uploaded here, or named from the catalog.",
312
+ json: "A structured document such as an API response or a webhook body.",
313
+ code: "A snippet of code, shown in the language you choose.",
314
+ ai_enrich: "A value the assistant fills in from a prompt you write.",
315
+ link: "Points at rows of another database, so this row can reach them.",
316
+ // β›” BOTH MODES, IN ONE LINE, AND IT IS THE ONLY CORRECT DESCRIPTION OF THIS KIND ON SCREEN.
317
+ rollup: "Folds MANY records into one number: the records this row links to, or a live topic "
318
+ + "matched on a column of this database.",
319
+ measure: "A business number this workspace already publishes, over a period you pick.",
320
+ geocode: "Latitude and longitude, read from an address column of this database.",
321
+ count: "How many records this row links to. A rollup, with the folding already chosen.",
322
+ lookup: "Shows a column of the records this row links to. A rollup, with the folding already "
323
+ + "chosen.",
324
+ };
325
+
326
+ /**
327
+ * ⭐⭐ W42-T37 (D-497) β€” THE KINDS A `ut_*` DATABASE REFUSES, so the picker stops offering one.
328
+ *
329
+ * β›” THE SERVER IS RIGHT AND SO IS ITS GATE. `_created` is stamped by the connector modules and a
330
+ * row of a runtime database never has one, so `user_tables.UT_FIELD_TYPES` leaves `created_time`
331
+ * out on purpose and `verify_fields_contract.py` exempts it deliberately. The defect was on THIS
332
+ * side: `ColumnMenu.FIELD_TYPES` maps `CREATABLE_TYPES` with no user-table filter, so the menu
333
+ * offered a kind `_clean_field` then returns `None` for. The fix is to stop offering it, never to
334
+ * teach the server the kind.
335
+ *
336
+ * β›” AND THIS IS A MIRROR WITH AN ENFORCER, NOT A SECOND OPINION. TypeScript cannot import the
337
+ * server's set, so `verify_rollup_editor.py` holds this list to `CREATABLE_TYPES - UT_FIELD_TYPES`
338
+ * read from `user_tables` itself, with a server-side negative control that widens that set and
339
+ * requires the leg to go red. A mirror nobody diffs is how the two ends drift
340
+ * ([[limit-with-no-enforcer]]).
341
+ */
342
+ export const UT_UNSUPPORTED_CREATE_KINDS: readonly string[] = ["created_time"];
343
+
344
+ /** Whether a create-menu row may be offered on this surface. `isUserTable` is the `ut_*` runtime
345
+ * database; every other grid is Odoo-backed and offers the whole vocabulary. */
346
+ export function offerableCreateKind(value: string, isUserTable: boolean): boolean {
347
+ return !isUserTable || !UT_UNSUPPORTED_CREATE_KINDS.includes(value);
348
+ }
349
+
350
  /** A run of field-type picker rows under an optional heading. `heading: null` is the ordinary
351
  * group, deliberately unlabelled: naming the majority case is chrome nobody reads, and the
352
  * divider under it already says where the ordinary list ends. */
 
437
  }
438
 
439
  /**
440
+ * ⭐⭐ W42-T37 (contract C8b) β€” THE DECLARED OPTION CAP, CLIENT HALF.
441
+ *
442
+ * β›” THE NUMBER BELONGS TO THE WAVE CONTRACT, NOT TO THIS FILE AND NOT TO THE SERVER. The server
443
+ * half (`core.user_tables`) pins the same integer independently, in its own lane, with its own
444
+ * gate leg. There is deliberately NO cross-language grep between the two: a leg asserting this
445
+ * literal against a Python symbol is red until the other lane merges, and a leg softened to
446
+ * tolerate the symbol's absence passes when the two ends pick different numbers. So
447
+ * `verify_rollup_editor.py` reads the integer out of `CONTRACTS.md` and compares it to this
448
+ * declaration; the contract is the single source and each end answers to it separately.
449
+ *
450
+ * β›”β›” AND THE CAP IS REPORTED, NEVER SILENTLY APPLIED. This used to be a bare tail slice: paste
451
+ * 300 statuses, save, and the column came back holding the first fifty with nothing said. That is
452
+ * standing rule 1's second half exactly ("a limit that genuinely cannot be removed must be
453
+ * REPORTED, with cause and a recommended fix, never silently enforced"), so raising the ceiling
454
+ * without changing the behaviour would only have moved where the silence happened.
455
+ */
456
+ export const MAX_OPTIONS = 200;
457
+
458
+ /**
459
+ * What `parseOptions` hands back: the cleaned list, how many choices sit beyond the cap, and the
460
+ * sentence to show when any do. `message` is `null` on the ordinary path, which is what the save
461
+ * doors test.
462
+ *
463
+ * ⚠ `options` IS NOT TRUNCATED. The surplus is refused rather than dropped, so the list a person
464
+ * typed is still the list they see while the message tells them what to remove; a truncated array
465
+ * here would put the silence back one layer down.
466
+ */
467
+ export interface ParsedOptions {
468
+ options: string[];
469
+ refused: number;
470
+ message: string | null;
471
+ }
472
+
473
+ /**
474
+ * One choice per line, blanks dropped, duplicates collapsed, order preserved, and the declared
475
+ * cap REFUSED rather than applied.
476
  * Case-INSENSITIVE dedupe: "Blocked" and "blocked" are one choice to a human, so the first
477
  * spelling wins rather than the column growing two pills that look like a typo.
478
  *
479
  * Lives here, not in ColumnMenu.tsx β€” a component file that also exports plain functions
480
  * breaks React fast refresh (the same reason counts.ts is its own module).
481
  */
482
+ export function parseOptions(text: string): ParsedOptions {
483
  const seen = new Set<string>();
484
  const out: string[] = [];
485
  for (const raw of text.split("\n")) {
 
490
  seen.add(k);
491
  out.push(v);
492
  }
493
+ const refused = Math.max(0, out.length - MAX_OPTIONS);
494
+ return {
495
+ options: out,
496
+ refused,
497
+ // ⚠ THE COUNT IS IN THE SENTENCE, both of them: how many were given and how many may stay.
498
+ // "Too many choices" is a refusal a person cannot act on.
499
+ message: refused
500
+ // ⚠ "this column", not "a select column": the same parser serves the multi select editor,
501
+ // and a sentence that names the wrong kind is wrong for half the people who see it.
502
+ ? `This list has ${out.length} choices and a column holds ${MAX_OPTIONS}. `
503
+ + `Remove ${refused} of them, then save.`
504
+ : null,
505
+ };
506
  }
507
 
508
  /**
 
538
  * condition on it reads as a fact about the customer. It still displays and still sorts.
539
  */
540
  export function filterableFields(fields: Field[]): Field[] {
541
+ return offerableFields(fields).filter((f) => f.filterable !== false);
542
+ }
543
+
544
+ /**
545
+ * ⭐⭐ WAVE-42 C11 β€” THE KEY OF THE ONE PRE-SET ROUTE PROJECTION COLUMN (W42-T20).
546
+ *
547
+ * The contract spells this literal so that neither end invents a name: the server serves ~64
548
+ * `route_order` columns with `offerable: false`, and this ONE column, which lists every route a
549
+ * record is on with its stop position, must pass THROUGH the same filter that withholds them.
550
+ */
551
+ export const ROUTE_PROJECTION_KEY = "routes";
552
+
553
+ /**
554
+ * ⭐⭐ WAVE-42 C11 β€” IS THIS FIELD OFFERED IN A FIELD PICKER?
555
+ *
556
+ * β›” PRESENTATION ONLY. Not a permission and not a deletion: the payload still carries every
557
+ * withheld field, the grid still stores and renders it, and its own doors are untouched. What
558
+ * this answers is whether a person is offered it in a list of columns to pick from.
559
+ *
560
+ * β›” THE FLAG IS OPTIONAL AND ABSENT MEANS OFFERABLE, deliberately, so that every field that
561
+ * predates it and every stored fixture stays byte-identical. Only an explicit `false` withholds
562
+ * (same reasoning as `colorCodeOptions` and C-A2's `strict?`); the alternative silently
563
+ * reclassifies the whole existing field list.
564
+ *
565
+ * β›” THE PROJECTION COLUMN IS EXEMPT, IN CODE, NOT BY CONVENTION. C11's positive half is a
566
+ * contract clause in its own right: withholding `routes` fails the ticket exactly as surely as
567
+ * withholding nothing does. Reading that off the server's flag alone would make the positive
568
+ * half depend on lane D never over-stamping the column it is itself minting, and there is no
569
+ * client-side signal left to catch it if it does.
570
+ */
571
+ export function isOfferableField(field: Field): boolean {
572
+ if (field.key === ROUTE_PROJECTION_KEY) return true;
573
+ return field.offerable !== false;
574
+ }
575
+
576
+ /** C11 β€” the columns a field picker may offer. See `isOfferableField`. */
577
+ export function offerableFields(fields: Field[]): Field[] {
578
+ return fields.filter(isOfferableField);
579
  }
580
 
581
  /** Wave-5 item 10 β€” per-field display format. One optional bag; each type reads its half. */
 
2252
  * "(empty)" group every other type uses.
2253
  */
2254
  export function isGroupableField(field: Field, lockedKey: string): boolean {
2255
+ // C11 (W42-T54) β€” a withheld field is not offered in ANY field picker, and the group picker
2256
+ // is one. Composed here rather than at the two call sites (this Toolbar's radio list and the
2257
+ // column menu's "Group by this field") for the reason the note above already gives: two
2258
+ // copies of a predicate drift.
2259
+ if (!isOfferableField(field)) return false;
2260
  return (
2261
  field.type === "status" ||
2262
  field.type === "select" ||
 
2300
  * reason (see `runPipeline`).
2301
  */
2302
  multi?: boolean;
2303
+ /**
2304
+ * ⭐⭐ WAVE-42 C11 β€” WHETHER ANY FIELD PICKER OFFERS THIS COLUMN. Absent or `true` means it
2305
+ * does; an explicit `false` WITHHOLDS it. Served by `routes_customers.py` on every field of
2306
+ * kind `route_order` (~64 of them on a 53-field grid, 99.4% blank), because a route is
2307
+ * something you plan on a map, not something you pick out of a field list.
2308
+ *
2309
+ * β›” Presentation only: not a permission, not a deletion, and the payload still carries the
2310
+ * field. Read it through `isOfferableField`, never directly, so the projection column's
2311
+ * exemption travels with the question.
2312
+ */
2313
+ offerable?: boolean;
2314
  /** header pin hint from the API (unused in Inc 0) */
2315
  pinned?: boolean;
2316
  /** default-visible unless explicitly false */
 
2351
  preset?: boolean;
2352
  /** Choices for a `select` / `multiselect` field. Ignored for every other type. */
2353
  options?: string[];
2354
+ /** Stored default for a newly created row, in the field's wire vocabulary. */
2355
+ defaultValue?: string | number | boolean | string[];
2356
+ /** A user field accepts one person rather than a comma-joined set. */
2357
+ single?: boolean;
2358
+ /** A rating field's declared symbol. */
2359
+ symbol?: string;
2360
+ /** A checkbox field's declared mark. */
2361
+ icon?: string;
2362
+ /** A checkbox field's declared colour. */
2363
+ color?: string;
2364
  /**
2365
  * Whether select-family choices render with coloured pills. Absent means true so legacy
2366
  * fields keep their existing appearance; an explicit false is the user's opt-out.
 
2609
  reciprocal?: string;
2610
  /** Airtable's `prefersSingleRecordLink` */
2611
  single?: boolean;
2612
+ /**
2613
+ * ⭐⭐ W42-T09 (R1, contract C1) β€” THE TWO-HOP JOIN, DECLARED. **Absent is today's one-hop
2614
+ * link and is byte-identical to every link stored before the hop existed**, so there is no
2615
+ * migration and no default: a bag that never carried a `via` still does not.
2616
+ *
2617
+ * A hop says *reach the target through a governed topic*: customers to products is two hops
2618
+ * through `sales_lines`, and the naive one-hop join yields a column of nulls that reads as
2619
+ * never sold. `topic` names the bridge; `source_dim` and `target_dim` are the bridge's own
2620
+ * dimensions; `target_key` is the TARGET GRID's join column and `scope_key` is this cohort's
2621
+ * scope β€” neither of those two is a dim, and both are required, because a bag missing
2622
+ * `scope_key` loses every cohort leaf without a word.
2623
+ *
2624
+ * β›” DECLARED HERE, RE-DECLARED RATHER THAN IMPORTED, and that is deliberate. The editor's
2625
+ * `HopViaBag` lives in `ColumnMenu.tsx`, which imports from this file; importing back would
2626
+ * close a cycle. The two are STRUCTURALLY IDENTICAL key for key, which is what makes the
2627
+ * editor's emitted bag assignable here with no cast and no adapter.
2628
+ *
2629
+ * ⚠ `window` IS A BARE `string`, ON PURPOSE. C1 spells whole history `"all"` and the live
2630
+ * validator `core.user_tables.ROLLUP_SOURCE_WINDOWS` spells it `"all_time"`, which is what
2631
+ * `ColumnMenu.HOP_WINDOW_ALL` emits. A literal union here would have to pick one and turn a
2632
+ * known, unruled deviation into a compile error against the value actually shipped.
2633
+ *
2634
+ * β›” ONE HOP ONLY. There is no `via` inside a `via`: the server refuses a nested one whole,
2635
+ * and `source_key` is deliberately absent from the bag rather than missing from it.
2636
+ */
2637
+ via?: {
2638
+ topic: string;
2639
+ source_dim: string;
2640
+ target_dim: string;
2641
+ target_key: string;
2642
+ scope_key: string;
2643
+ measure: string;
2644
+ filter: FilterNode[];
2645
+ filterConj: Conjunction;
2646
+ window: string;
2647
+ };
2648
  };
2649
  /**
2650
  * ⭐ 2026-08-07 β€” an AGGREGATE over the rows a `link` column resolves (Airtable's `rollup`).
 
2784
  ] as const;
2785
  export type RollupFn = (typeof ROLLUP_FNS)[number];
2786
 
2787
+ /**
2788
+ * ⭐⭐ W42-T37 (`airtable-field-parity.md` G3) β€” COUNT AND LOOKUP, WHICH ARE MENU PRESETS OVER THE
2789
+ * ROLLUP AND NOT NEW FIELD KINDS.
2790
+ *
2791
+ * β›”β›” THE DISTINCTION IS CONTRACT C8's AND IT IS NOT COSMETIC. A KIND is a member of five
2792
+ * vocabularies at once (`FieldType`, `CREATABLE_TYPES`, `user_tables.UT_FIELD_TYPES`,
2793
+ * `aios_grid.CUSTOM_FIELD_TYPES` and the shape/label tables) plus a cell renderer, and that
2794
+ * landing cannot be split across tickets: wave 34 took `api_api` from 969/969 to 968/969 on a
2795
+ * server half alone. Wave 42 ships no new kind. So neither name appears in any of those five
2796
+ * lists; both save a `rollup` and both re-open as a rollup.
2797
+ *
2798
+ * ⭐ AND THE FEATURE IS DISCOVERABILITY, NOT CAPABILITY. Our rollup is already a strict superset
2799
+ * of Airtable's fold (16 folds, rank-and-limit, sigma thresholds, a read-through source mode), so
2800
+ * a person migrating searched the menu for "Count", found nothing, and concluded the product
2801
+ * could not do the one thing it does best. These two rows are that search hitting.
2802
+ */
2803
+ export const ROLLUP_PRESETS = ["count", "lookup"] as const;
2804
+ export type RollupPreset = (typeof ROLLUP_PRESETS)[number];
2805
+
2806
+ /** The fold each preset fixes, so the editor can ask only what the preset still needs.
2807
+ * `countall` counts linked RECORDS and takes no column; `arrayjoin` is the one fold whose result
2808
+ * is the linked values themselves, which is what a lookup is. */
2809
+ export const ROLLUP_PRESET_FNS: Record<RollupPreset, RollupFn> = {
2810
+ count: "countall",
2811
+ lookup: "arrayjoin",
2812
+ };
2813
+
2814
+ /**
2815
+ * Which preset a stored bag IS, or `null` for a rollup that is simply a rollup.
2816
+ *
2817
+ * β›”β›” EXACT, NEVER "STARTS WITH". A bag that also carries a window, a de-duplication or either
2818
+ * condition list is NOT a preset, and answering `"count"` for one would open it in the reduced
2819
+ * editor with those controls hidden and their values still in the bag: configuration a person can
2820
+ * no longer see, edit or remove. So every key outside the preset's own shape disqualifies it.
2821
+ *
2822
+ * ⚠ THIS IS ALSO THE ROUND-TRIP'S OWN READING. `_clean_rollup` rebuilds its output key by key and
2823
+ * drops anything it does not know, so a preset bag survives it unchanged and comes back through
2824
+ * this function as the same preset. `verify_rollup_editor.py` asserts exactly that composition.
2825
+ */
2826
+ export function rollupPresetOf(
2827
+ bag: NonNullable<Field["rollup"]> | null | undefined
2828
+ ): RollupPreset | null {
2829
+ if (!bag || bag.source) return null;
2830
+ const plain =
2831
+ !bag.limit && !bag.sortBy && !bag.sortDir && !bag.distinctBy
2832
+ && !(bag.where && bag.where.length) && !(bag.conditions && bag.conditions.length);
2833
+ if (!plain || !bag.link) return null;
2834
+ if (bag.fn === ROLLUP_PRESET_FNS.count && !bag.field) return "count";
2835
+ if (bag.fn === ROLLUP_PRESET_FNS.lookup && !!bag.field) return "lookup";
2836
+ return null;
2837
+ }
2838
+
2839
  /** The rollup functions whose RESULT is a number β€” the render/align/sort family. */
2840
  export const ROLLUP_NUMERIC_FNS: ReadonlySet<string> =
2841
  new Set(["sum", "average", "stdev", "min", "max", "count", "counta", "countall"]);
 
3659
  return tree?.conj === "or" ? "or" : "and";
3660
  }
3661
 
3662
+ /* --- WAVE-42 R22 β€” route order sorts only where it means something ------------- */
3663
+
3664
+ /**
3665
+ * The one value `Field.kind` takes today (`routes_customers.ROUTE_KIND`). β›” READ, NEVER
3666
+ * INFERRED FROM THE KEY: `route_` is a naming convention and the server says so in as many
3667
+ * words. See `Field.kind`.
3668
+ */
3669
+ export const ROUTE_ORDER_KIND = "route_order";
3670
+
3671
+ /**
3672
+ * β›”β›” WAVE-42 R22 β€” WHY THIS IS A REFUSAL AND NOT A FALLBACK.
3673
+ *
3674
+ * A stop position is an ordinal INSIDE one route. Across two routes it is not a scale, and the
3675
+ * projection column's cell is text (`Route A - 10, Route B - 2`), so the only thing an ordinary
3676
+ * sort could do with it is compare strings: `Route A - 10` would land BEFORE `Route A - 2`. No
3677
+ * numeric-aware comparator exists anywhere in this codebase (`useVisibleRows.ts`, `export.ts`,
3678
+ * `folders.ts`), so there is nothing to fall back TO that would be correct, and a silent
3679
+ * fallback is a wrong answer that looks like an answer.
3680
+ *
3681
+ * β›” NO EM DASH OR EN DASH (standing rule 2): two sentences, because the natural "because"
3682
+ * clause here wants one.
3683
+ */
3684
+ export const ROUTE_SORT_REFUSAL_TEXT =
3685
+ "Route order only means something inside one route. Filter this view to a single route, then sort by it.";
3686
+
3687
+ /** Why a route-order sort was refused, or which route it is allowed inside. */
3688
+ export type RouteSortVerdict =
3689
+ | { ok: true; routeKey: string }
3690
+ | { ok: false; reason: "no-route" | "many-routes" | "not-narrowing" };
3691
+
3692
+ /**
3693
+ * The ops on a route-order column that imply MEMBERSHIP of that route. A stop position is
3694
+ * written only for a record that is ON the route, so any op asserting a value narrows to it.
3695
+ *
3696
+ * β›” `isEmpty` and `neq` are deliberately absent: "not on route A" is the whole rest of the
3697
+ * world, which is the permissive direction the ticket names as the failure.
3698
+ */
3699
+ const ROUTE_MEMBERSHIP_OPS: ReadonlySet<string> = new Set([
3700
+ "isNotEmpty", "eq", "gt", "gte", "lt", "lte", "between",
3701
+ ]);
3702
+
3703
+ /** C11/R20 β€” a per-route stop-position column, matched on the DECLARED kind. */
3704
+ export function isRouteOrderField(field: Field): boolean {
3705
+ return field.kind === ROUTE_ORDER_KIND;
3706
+ }
3707
+
3708
+ /** Does anything anywhere under this node condition a route column? Fail-closed helper. */
3709
+ function nodeTouchesRoute(node: FilterNode, routeKeys: ReadonlySet<string>): boolean {
3710
+ if (isFilterGroup(node)) {
3711
+ return node.children.some((child) => nodeTouchesRoute(child, routeKeys));
3712
+ }
3713
+ return routeKeys.has(node.colId);
3714
+ }
3715
+
3716
+ /**
3717
+ * ⭐⭐ WAVE-42 R22 β€” IS THIS VIEW NARROWED TO EXACTLY ONE ROUTE?
3718
+ *
3719
+ * PURE and EXPORTED on purpose: nothing in a lane may start a server, so the only way this
3720
+ * decision is OBSERVED rather than asserted is a gate leg or a probe calling it directly.
3721
+ *
3722
+ * The boundary cases, each named, all failing CLOSED:
3723
+ * - no filter at all, or no leaf on any route column -> `no-route`.
3724
+ * - two or more route columns conditioned -> `many-routes`.
3725
+ * - a route leaf inside a nested condition GROUP -> `not-narrowing`. A group carries its own
3726
+ * conjunction and this walk does not evaluate filters; treating it as narrowing would be a
3727
+ * guess in the permissive direction.
3728
+ * - the ROOT list joined by `or` with more than one node -> `not-narrowing`, because anything
3729
+ * ORed beside the route condition puts other routes' records back in.
3730
+ * - a leaf on some other column entirely -> ignored. Under an `and` root it can only narrow
3731
+ * further, and a narrower set is still inside the one route.
3732
+ * - a route leaf whose op does not assert membership (`isEmpty`, `neq`) -> not counted, so the
3733
+ * verdict falls through to `no-route`.
3734
+ */
3735
+ export function singleRouteScope(
3736
+ tree: FilterTree | null | undefined,
3737
+ fields: Field[],
3738
+ ): RouteSortVerdict {
3739
+ const routeKeys = new Set(fields.filter(isRouteOrderField).map((f) => f.key));
3740
+ const nodes = filterTreeNodes(tree);
3741
+ if (filterTreeConj(tree) === "or" && nodes.length > 1) {
3742
+ return { ok: false, reason: "not-narrowing" };
3743
+ }
3744
+ const named = new Set<string>();
3745
+ for (const node of nodes) {
3746
+ if (isFilterGroup(node)) {
3747
+ if (nodeTouchesRoute(node, routeKeys)) return { ok: false, reason: "not-narrowing" };
3748
+ continue;
3749
+ }
3750
+ if (!routeKeys.has(node.colId)) continue;
3751
+ if (!ROUTE_MEMBERSHIP_OPS.has(node.op)) continue;
3752
+ named.add(node.colId);
3753
+ }
3754
+ if (named.size === 0) return { ok: false, reason: "no-route" };
3755
+ if (named.size > 1) return { ok: false, reason: "many-routes" };
3756
+ return { ok: true, routeKey: [...named][0] };
3757
+ }
3758
+
3759
+ /**
3760
+ * R22 β€” the sentence to show, or `null` when this sort is allowed. Only the ONE projection
3761
+ * column is judged; the per-route stop columns each hold a plain integer inside one route and
3762
+ * sort correctly on their own.
3763
+ */
3764
+ export function routeSortRefusal(
3765
+ colId: string,
3766
+ tree: FilterTree | null | undefined,
3767
+ fields: Field[],
3768
+ ): string | null {
3769
+ if (colId !== ROUTE_PROJECTION_KEY) return null;
3770
+ return singleRouteScope(tree, fields).ok ? null : ROUTE_SORT_REFUSAL_TEXT;
3771
+ }
3772
+
3773
+ /**
3774
+ * R22, the POSITIVE half β€” the stop position this record holds on ONE named route, read out of
3775
+ * the projection cell (`Route A - 3, Route B - 7`), or `null` when the record is not on it.
3776
+ *
3777
+ * ⚠ The cell is CSV by contract (W42-T20 chose it so `groupRows`' `cell.split(",")` fans out),
3778
+ * and the separator between name and position is a plain ASCII hyphen, so a route whose NAME
3779
+ * contains one still resolves: the position is taken from the LAST separator in the entry.
3780
+ *
3781
+ * β›” EXPORTED WITH NO CALL SITE IN THIS LANE. Ordering the grid by it happens in
3782
+ * `useVisibleRows.ts`, which is outside this ticket's fence. See the handoff.
3783
+ */
3784
+ export function routeStopPosition(cell: unknown, routeLabel: string): number | null {
3785
+ if (typeof cell !== "string") return null;
3786
+ const want = routeLabel.trim();
3787
+ if (!want) return null;
3788
+ for (const entry of cell.split(",")) {
3789
+ const text = entry.trim();
3790
+ const cut = text.lastIndexOf(" - ");
3791
+ if (cut < 0) continue;
3792
+ if (text.slice(0, cut).trim() !== want) continue;
3793
+ const n = Number.parseInt(text.slice(cut + 3).trim(), 10);
3794
+ if (Number.isFinite(n)) return n;
3795
+ }
3796
+ return null;
3797
+ }
3798
+
3799
  export type RowHeightMode = "short" | "medium" | "tall";
3800
  export type ThemeMode = "light" | "dark";
3801
 
 
3883
  * the primary filter carried across. Absent = the ordinary view of its own table, which is
3884
  * every view saved before this wave (no migration, the `memberPids` precedent).
3885
  *
3886
+ * ⭐⭐ **THE ROUND TRIP IS CLOSED β€” CORRECTED 2026-08-25 (W42-T09).** The note here used to
3887
+ * say the server half was "not in this wave" and that a pivot rendered but did not persist.
3888
+ * That was true when it was written and is false now: `grid_events.py::handle_one` names
3889
+ * `secondaryView` in the `view_upsert` allowlist and runs it through `_clean_secondary_view`,
3890
+ * so the key survives the write as well as the read.
3891
+ *
3892
+ * β›” THE STALE HALF IS THE DANGEROUS HALF, which is why it is corrected rather than deleted. A
3893
+ * comment saying a feature does not persist is exactly what a later session greps before
3894
+ * deciding a defect is already known, and it would have sent one hunting for a dropped write
3895
+ * that no longer happens [[two-lanes-one-contract-dead-feature]].
3896
+ *
3897
+ * ⚠ The client half is unchanged and still carries its own weight: `normalizeConfig` spreads,
3898
+ * so this key survives the read, and `sameConfig` is a whole-object compare, so it is picked
3899
+ * up free. `cleanSecondaryView` below fails it closed on either half of the relation.
3900
  */
3901
  secondaryView?: SecondaryView;
3902
  }
 
4028
  *
4029
  * ⚠ AN EMPTY LIST IS A TRUTHFUL ANSWER, not a failure: it means this table has no link field
4030
  * yet. The control says so rather than offering a pivot that cannot be resolved.
4031
+ *
4032
+ * ⭐⭐ W42-T09 (R1, C1) β€” A TWO-HOP LINK IS OFFERED HERE WITH NO CHANGE AT ALL, AND THAT IS THE
4033
+ * FINDING, not an oversight. Eligibility is purely structural β€” `type === "link"` and a truthy
4034
+ * `link.table` β€” so a field carrying `link.via` satisfies both tests exactly as a one-hop link
4035
+ * does and joins the offer beside it. Adding a `via` branch here would be a SECOND opinion about
4036
+ * what can be pivoted to, and the two would drift; the hop changes how the server RESOLVES the
4037
+ * relation, never whether the relation exists. `Toolbar.tsx` renders this list unchanged.
4038
  */
4039
  export function relationalTargets(fields: Field[]): RelationalTarget[] {
4040
  const out: RelationalTarget[] = [];
 
4109
  * ⚠ `filters` is the SOURCE view's tree, passed straight through. That is how the primary filter
4110
  * is carried across (owner instruction 23) and it is also T44's door: one record is one filter
4111
  * naming it, not a new request shape.
4112
+ *
4113
+ * β›”β›” W42-T09 β€” **`viaField` IS LOAD-BEARING NOW, NOT ADVISORY.** It has always been sent, and
4114
+ * until the hop existed the server could resolve the relation from `source` and `target` alone,
4115
+ * so dropping it would have cost nothing visible. It cannot be dropped any more: a link field
4116
+ * carrying a `via` is the ONLY thing that says which governed topic to travel through, and the
4117
+ * server reads that bag off the field this key names. Two link columns may point at the same
4118
+ * target through different topics, so `target` no longer identifies the relation on its own.
4119
  */
4120
  export function buildPivotRequest(
4121
  source: string,
 
4177
  };
4178
  }
4179
 
4180
+ /**
4181
+ * ⭐⭐ W42-T09 β€” READ THE SERVER'S OWN REASON OFF A NON-2xx BODY, or answer `null`.
4182
+ *
4183
+ * β›”β›” THE DEFECT THIS CLOSES, AND IT IS HALF OF WHY D-484 READ AS "NOTHING WORKS". The grid's
4184
+ * pivot fetch collapsed **every** non-2xx into `absent` and printed one generic sentence, so a
4185
+ * server that had walled the reader out, refused the route, or found more related records than
4186
+ * one answer can carry was indistinguishable on screen from a feature that had never been built.
4187
+ * The server authored a reason every time and nobody read it.
4188
+ *
4189
+ * β›” IT IS THE SERVER'S WORDS OR NOTHING. `null` means the body carries no usable reason at all
4190
+ * (an HTML error page, a proxy, a session redirect), and the caller then falls back to the
4191
+ * generic "not available yet" line β€” which stays TRUE for exactly that case. Authoring a
4192
+ * sentence here instead would make this client guess at a wall it did not hit, which is the rule
4193
+ * `PivotRefusal` has carried since W41-T43.
4194
+ *
4195
+ * ⚠ EVERY SPELLING THE ANSWER CAN ARRIVE IN IS READ, because three of them are live at once and
4196
+ * the ticket named a fourth. In order:
4197
+ * β€’ `refusal: {reason, subject}` β€” C10's own channel, if a refusal ever rides a non-2xx;
4198
+ * β€’ `error: {message, code}` β€” X2, THE shape this app's `main.py::_error_shape` returns for
4199
+ * every non-2xx (`deps.err` raises the detail and the handler unwraps it), so this is the
4200
+ * arm that actually fires today for `no_pivot_route`, `pivot_unavailable`, `pivot_truncated`
4201
+ * and `forbidden`. Its `code` is NOT carried onto the screen β€” see the clause at that arm;
4202
+ * β€’ bare `reason` / `detail` / `message`, with `subject` beside it β€” FastAPI's own unwrapped
4203
+ * `detail` and the two keys the ticket named.
4204
+ * The subject is only ever a NAME the reader can go and ask for, never a machine code and never
4205
+ * a second authored sentence.
4206
+ */
4207
+ export function pivotRefusalFromBody(body: unknown): PivotRefusal | null {
4208
+ if (!body || typeof body !== "object" || Array.isArray(body)) return null;
4209
+ const b = body as Record<string, unknown>;
4210
+ const text = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
4211
+
4212
+ const nested = b.refusal;
4213
+ if (nested && typeof nested === "object" && !Array.isArray(nested)) {
4214
+ const r = nested as Record<string, unknown>;
4215
+ if (text(r.reason)) return { reason: text(r.reason), subject: text(r.subject) };
4216
+ }
4217
+ const wrapped = b.error;
4218
+ if (wrapped && typeof wrapped === "object" && !Array.isArray(wrapped)) {
4219
+ const e = wrapped as Record<string, unknown>;
4220
+ /* β›” THE `code` IS DELIBERATELY NOT CARRIED INTO `subject`, and this is a copy decision, not
4221
+ an oversight. The renderer prints `${subject}: ${reason}`, and `subject` has only ever held
4222
+ a DATABASE NAME there ("product_data: you may not open this database"). X2's `code` is a
4223
+ snake_case machine token, so carrying it would put "no_pivot_route: there is no declared
4224
+ way…" on a user's screen β€” developer vocabulary in the one sentence a walled-out reader
4225
+ gets, against DESIGN.md Β§2's sentence case and Β§4's "say what stopped it and what to do".
4226
+ Every message `routes_grid` authors already names its own subject inside the sentence, so
4227
+ nothing actionable is lost. The code stays in the response for anyone reading the network
4228
+ tab, which is where a machine token belongs. */
4229
+ if (text(e.message)) return { reason: text(e.message), subject: "" };
4230
+ }
4231
+ /* ⚠ `detail` is read as a STRING ONLY. FastAPI hands back whatever was raised, and this app
4232
+ raises a DICT β€” already handled by the `error` arm above β€” so an object here is a shape
4233
+ nobody declared and stating it would print `[object Object]` at a reader. */
4234
+ const flat = text(b.reason) || text(b.detail) || text(b.message);
4235
+ if (flat) return { reason: flat, subject: text(b.subject) };
4236
+ return null;
4237
+ }
4238
+
4239
  /**
4240
  * wave17 R1 / contract C-LOCKV β€” **`"locked"` joins the vocabulary, and it is the whole of the
4241
  * client's model of a locked view.**
web/src/customer-grid/useVisibleRows.ts CHANGED
@@ -278,6 +278,44 @@ function cmpText(op: FilterRule["op"], a: string, v: string): boolean {
278
  * A group's own conjunction (`and`/`or`) combines only its ACTIVE children; a
279
  * group with no active children is itself inactive. This is what keeps a
280
  * half-built group from either zeroing the grid (`and`) or disabling it (`or`).
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
281
  */
282
  function evalNode(
283
  node: FilterNode,
@@ -285,6 +323,11 @@ function evalNode(
285
  fieldByKey: Map<string, Field>,
286
  ctx?: EvalCtx
287
  ): boolean | null {
 
 
 
 
 
288
  if (isFilterGroup(node)) {
289
  let sawActive = false;
290
  let allTrue = true;
@@ -296,10 +339,30 @@ function evalNode(
296
  allTrue = allTrue && v;
297
  anyTrue = anyTrue || v;
298
  }
299
- if (!sawActive) return null;
 
 
 
300
  return node.conj === "or" ? anyTrue : allTrue;
301
  }
302
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
303
  // --- owner item 5: a COHORT leaf, also before the column lookup ------------------------
304
  // Same trap as the measure leaf below: `__cohort__` is not a column, so `fieldByKey.has`
305
  // would say INACTIVE, and inactive means every row on screen under a count nobody doubts.
@@ -307,7 +370,12 @@ function evalNode(
307
  // `is not` as well as for `is`. The host drops rules naming a cohort the user does not
308
  // have (see aios_grid.clean_filter_tree), so this is a backstop, not the behaviour.
309
  if (isCohortRule(node)) {
310
- if (!isRuleActive(node)) return null;
 
 
 
 
 
311
  // A SET of cohorts since 2026-07-27 (`is any of` / `is all of` / `is none of`). A single id
312
  // parses to a one-element list, so the shipped `is part of` is the same code path.
313
  const ids = cohortIds(node.value);
@@ -333,7 +401,16 @@ function evalNode(
333
  // names. `unresolvedConditions` counts the same case, so the toolbar's "Filter unresolved"
334
  // chip explains the empty table instead of leaving it a mystery (D-124's shape, one leaf over).
335
  if (isViewRule(node)) {
336
- if (!isRuleActive(node)) return null;
 
 
 
 
 
 
 
 
 
337
  const set = ctx?.viewSets?.[viewRuleId(node.value)];
338
  if (!set) return false;
339
  return normalizeViewOp(node.op) === "notInView" ? !set.has(r.pid) : set.has(r.pid);
@@ -349,14 +426,18 @@ function evalNode(
349
  // half-typed rule is inactive exactly as a column rule is. An ACTIVE rule with no set yet is
350
  // PENDING and matches NOTHING β€” never everything (see types.ts `Measure`).
351
  if (isMeasureRule(node)) {
352
- if (!isRuleActive(node)) return null;
 
353
  const set = node.id ? ctx?.measureSets?.[node.id] : undefined;
354
  if (!set) return false;
355
  return set.has(r.pid);
356
  }
357
 
358
  // leaf
359
- if (!fieldByKey.has(node.colId)) return null; // unknown column -> ignored
 
 
 
360
  // An rhs naming a column this table does not have is ignored for the SAME reason and by the
361
  // SAME rule as an unknown LEFT column β€” a condition whose comparand does not exist is not a
362
  // condition. Consistency here is the point: treating one side as "ignore" and the other as
@@ -366,8 +447,10 @@ function evalNode(
366
  // as a deleted column.
367
  // A STATISTIC names no column β€” it is server-resolved on a measure leaf, which was
368
  // handled above, so one reaching here is as unusable as a deleted column.
369
- if (node.rhs && !fieldByKey.has(rhsColId(node.rhs) ?? "")) return null;
370
- if (!isRuleActive(node)) return null;
 
 
371
 
372
  // --- C-OPS: a RANK leaf is a MEMBERSHIP test, like a cohort or a measure ------------------
373
  // The set was computed in a prior pass over the residue-filtered domain (see rankOps.ts),
@@ -451,11 +534,19 @@ export interface EvalCtx {
451
  * nothing anywhere says so. Supplying this map is what lets `unresolvedConditions` say it.
452
  * ⚠ OPTIONAL BY DESIGN. Absent = the old behaviour exactly, so every existing caller and every
453
  * stored fixture is byte-identical; the pipeline and the grid supply it.
454
- * ⚠ And it is deliberately NOT used to change what `evalNode` RETURNS. Flipping these leaves to
455
- * `false` would empty every grid holding a view that outlived one of its columns, which is a
456
- * far larger and much worse behaviour change than the silence it would cure.
 
 
 
 
457
  */
458
  fieldByKey?: Map<string, Field>;
 
 
 
 
459
  }
460
 
461
  /**
@@ -870,15 +961,26 @@ export interface PipelineInput {
870
  /** The TENANT'S today, from the payload. Required by every relative-date condition and
871
  * never defaulted to the browser clock β€” see CustomersPayload.today. */
872
  today?: string;
 
 
 
 
 
 
 
 
 
 
 
873
  }
874
 
875
  export function runPipeline(input: PipelineInput): VisibleRowsResult {
876
  const {
877
  rawRows, fields, filters, search, sorts, groupBy, collapsed,
878
  memberPids = [], filterConj = "and", serverWindowed = false, measureSets,
879
- cohortSets, viewSets, today, cohortLock,
880
  } = input;
881
- const ctx: EvalCtx = { measureSets, cohortSets, today, viewSets };
882
 
883
  let unresolvedRank = 0;
884
 
@@ -1029,12 +1131,15 @@ export function useVisibleRows(
1029
  measureSets?: MeasureSets,
1030
  cohortSets?: CohortSets,
1031
  today?: string,
1032
- cohortLock?: string
 
 
 
1033
  ): VisibleRowsResult {
1034
  return useMemo(
1035
  () => runPipeline({ rawRows, fields, filters, search, sorts, groupBy, collapsed,
1036
  memberPids, filterConj, serverWindowed, measureSets,
1037
- cohortSets, today, cohortLock }),
1038
  [rawRows, fields, filters, filterConj, search, sorts, groupBy, collapsed,
1039
- memberPids, serverWindowed, measureSets, cohortSets, today, cohortLock]);
1040
  }
 
278
  * A group's own conjunction (`and`/`or`) combines only its ACTIVE children; a
279
  * group with no active children is itself inactive. This is what keeps a
280
  * half-built group from either zeroing the grid (`and`) or disabling it (`or`).
281
+ *
282
+ * ⭐⭐ W42-T27 β€” `ctx.strict` is the PERMISSION mode, and it is the exact mirror of
283
+ * `platform/harness/filter_eval.py::_eval`'s `strict` parameter (wave 15). Read the two files
284
+ * side by side: `ignore` below is that file's line 296, and EVERY `return ignore` here answers one
285
+ * of its SEVEN β€” derive the list from the file (`grep -n "return ignore"`), never from a summary,
286
+ * because two successive summaries of it were short:
287
+ * `:313` group, no active children `:317` node is not an object at all
288
+ * `:323` cohort leaf, inactive `:346` measure leaf, inactive
289
+ * `:356` unknown colId `:361` unknown rhs col `:363` plain leaf, inactive
290
+ * Every `null` this function would return becomes `false` instead, so a viewer who CANNOT RESOLVE
291
+ * a leaf is narrowed by it rather than widened.
292
+ *
293
+ * ⚠ TS has EIGHT sites to Python's seven. The extra is the VIEW leaf's `!isRuleActive`, which has
294
+ * no Python counterpart because `filter_eval.py` has no view branch at all β€” see that branch.
295
+ *
296
+ * β›” THE MIRROR MUST BE COMPLETE, AND A PARTIAL ONE LOOKS FINISHED. Converting only the group and
297
+ * the three PLAIN-leaf sites leaves the cohort and measure `isRuleActive` guards returning
298
+ * `null`, and then `and` [half-built cohort, state is FL] lets the plain leaf carry the group to
299
+ * TRUE under strict β€” the receiver sees every FL row the wall meant to withhold, while
300
+ * `filter_eval.permits` on the identical tree returns False. The two engines disagreeing under
301
+ * strict destroys the parity this design rests on. A tree of ONLY inactive rules does not expose
302
+ * it (the group site rescues those); it takes a MIXED tree, which is why the fixture pins one.
303
+ *
304
+ * β›” THE GROUP SITE IS LOAD-BEARING AND IS THE ONE THAT LOOKS OPTIONAL. With only the leaf sites
305
+ * flipped, a tree whose single leaf is unresolvable already returns `false` β€” the leaf sets
306
+ * `sawActive` and clears `allTrue` β€” so the obvious negative control passes without it. What it
307
+ * does NOT cover is a tree of only genuinely-INACTIVE rules, an EMPTY group, or a nested group
308
+ * whose children are all inactive: those still return `null`, and `matchFilterTree`'s
309
+ * `v === null ? true : v` then shows EVERY row, with the flag reading as correct.
310
+ *
311
+ * ⚠ ONE site has no Python counterpart at all: the VIEW leaf's `!isRuleActive`. `filter_eval.py`
312
+ * has no view branch (C4 is TS-only and postdates it), so it is decided from the principle and
313
+ * the reasoning is written at the branch itself rather than left to be re-derived.
314
+ *
315
+ * ⚠ Everything a receiver cannot RESOLVE β€” a missing cohort, view, measure or rank set β€” already
316
+ * returned `false` before this change, via its own `if (!set) return false`. Those leaves are
317
+ * untouched here and stay refusals in BOTH modes; `strict` governs only the leaves that used to
318
+ * stand aside.
319
  */
320
  function evalNode(
321
  node: FilterNode,
 
323
  fieldByKey: Map<string, Field>,
324
  ctx?: EvalCtx
325
  ): boolean | null {
326
+ // `filter_eval.py:296`. In DISPLAY mode this is literally `null`, which makes every `return
327
+ // ignore` below a `return null` β€” so display semantics are byte-identical by CONSTRUCTION,
328
+ // not by test.
329
+ const ignore = ctx?.strict ? false : null;
330
+
331
  if (isFilterGroup(node)) {
332
  let sawActive = false;
333
  let allTrue = true;
 
339
  allTrue = allTrue && v;
340
  anyTrue = anyTrue || v;
341
  }
342
+ // `filter_eval.py:309-313`. A group with no active children is itself inactive. In strict
343
+ // mode an empty or wholly-unanswerable permission group DENIES: a wall that evaluates to
344
+ // "nothing to say" must not mean "let them through".
345
+ if (!sawActive) return ignore;
346
  return node.conj === "or" ? anyTrue : allTrue;
347
  }
348
 
349
+ // `filter_eval.py:317` β€” A NODE THAT IS NOT AN OBJECT AT ALL, and it is NOT unreachable on a
350
+ // typing argument. Filter trees are STORED JSON, so this is a runtime shape rather than a
351
+ // type-system impossibility: a truncated write, a hand-edited view or an older saved shape can
352
+ // put `null` in a `children` array, and `{"conj":"and","children":[null]}` is valid JSON.
353
+ //
354
+ // β›” TODAY THAT THROWS, it does not merely diverge. `isFilterGroup` is null-safe
355
+ // (`node != null && Array.isArray(...)`), but `isCohortRule` immediately below reads
356
+ // `(node as FilterRule).colId` on the raw node β€” `null.colId` is a TypeError out of the render
357
+ // path. Other non-objects (`42`, `"str"`) fall through harmlessly to the colId guard. So this
358
+ // line converts a live crash into defined behaviour: display IGNORES the junk node, which is
359
+ // what `filter_eval.matches` has always done, and strict DENIES it, because a node we cannot
360
+ // even parse must not be a node we let the reader past.
361
+ //
362
+ // ⚠ This is the ONE place the change touches DISPLAY mode β€” from throwing to ignoring. A crash
363
+ // is not a row set, so no fixture case can have covered it and nothing that passes today moves.
364
+ if (node == null || typeof node !== "object") return ignore;
365
+
366
  // --- owner item 5: a COHORT leaf, also before the column lookup ------------------------
367
  // Same trap as the measure leaf below: `__cohort__` is not a column, so `fieldByKey.has`
368
  // would say INACTIVE, and inactive means every row on screen under a count nobody doubts.
 
370
  // `is not` as well as for `is`. The host drops rules naming a cohort the user does not
371
  // have (see aios_grid.clean_filter_tree), so this is a backstop, not the behaviour.
372
  if (isCohortRule(node)) {
373
+ // `filter_eval.py:322-323`. Under strict an INACTIVE cohort rule DENIES rather than standing
374
+ // aside, and the case that forces it is a MIXED tree: `and` [half-built cohort, state is FL]
375
+ // would otherwise let the plain leaf carry the group to TRUE, showing the receiver every FL
376
+ // row the sharer's wall meant to withhold β€” the widening sin arriving through the leaf next
377
+ // door. Display mode is unmoved: `ignore` is `null` there.
378
+ if (!isRuleActive(node)) return ignore;
379
  // A SET of cohorts since 2026-07-27 (`is any of` / `is all of` / `is none of`). A single id
380
  // parses to a one-element list, so the shipped `is part of` is the same code path.
381
  const ids = cohortIds(node.value);
 
401
  // names. `unresolvedConditions` counts the same case, so the toolbar's "Filter unresolved"
402
  // chip explains the empty table instead of leaving it a mystery (D-124's shape, one leaf over).
403
  if (isViewRule(node)) {
404
+ // ⚠ NO PYTHON LINE TO MIRROR β€” `filter_eval.py` has no view branch at all (C4 is a TS-only
405
+ // construct that postdates it), so this one is decided from the PRINCIPLE rather than the
406
+ // table, and the reasoning is recorded here so the next reader does not read it as drift.
407
+ // A view leaf is a MEMBERSHIP test, exactly like the cohort leaf above and the rank leaf
408
+ // below: its unresolvable case already `return false`s, byte-for-byte the cohort posture.
409
+ // Its INACTIVE case therefore belongs with its neighbours β€” leaving it `null` would make
410
+ // `View is [nothing chosen] AND state is FL` behave differently under strict from
411
+ // `Cohort is [nothing chosen] AND state is FL`, an asymmetry with no principle under it and
412
+ // one no user could predict.
413
+ if (!isRuleActive(node)) return ignore;
414
  const set = ctx?.viewSets?.[viewRuleId(node.value)];
415
  if (!set) return false;
416
  return normalizeViewOp(node.op) === "notInView" ? !set.has(r.pid) : set.has(r.pid);
 
426
  // half-typed rule is inactive exactly as a column rule is. An ACTIVE rule with no set yet is
427
  // PENDING and matches NOTHING β€” never everything (see types.ts `Measure`).
428
  if (isMeasureRule(node)) {
429
+ // `filter_eval.py:345-346` β€” same rule, same reason as the cohort leaf above.
430
+ if (!isRuleActive(node)) return ignore;
431
  const set = node.id ? ctx?.measureSets?.[node.id] : undefined;
432
  if (!set) return false;
433
  return set.has(r.pid);
434
  }
435
 
436
  // leaf
437
+ // `filter_eval.py:353-356` β€” THE LEAF THE `strict` FLAG EXISTS FOR. Display: ignore it, so a
438
+ // view that outlived one of its columns still paints. Permission: DENY, so a shared view whose
439
+ // filter names a field the RECEIVER cannot see shows fewer rows, never more.
440
+ if (!fieldByKey.has(node.colId)) return ignore; // unknown column -> ignored (display) / denied (strict)
441
  // An rhs naming a column this table does not have is ignored for the SAME reason and by the
442
  // SAME rule as an unknown LEFT column β€” a condition whose comparand does not exist is not a
443
  // condition. Consistency here is the point: treating one side as "ignore" and the other as
 
447
  // as a deleted column.
448
  // A STATISTIC names no column β€” it is server-resolved on a measure leaf, which was
449
  // handled above, so one reaching here is as unusable as a deleted column.
450
+ // `filter_eval.py:357-361`
451
+ if (node.rhs && !fieldByKey.has(rhsColId(node.rhs) ?? "")) return ignore;
452
+ // `filter_eval.py:362-363`
453
+ if (!isRuleActive(node)) return ignore;
454
 
455
  // --- C-OPS: a RANK leaf is a MEMBERSHIP test, like a cohort or a measure ------------------
456
  // The set was computed in a prior pass over the residue-filtered domain (see rankOps.ts),
 
534
  * nothing anywhere says so. Supplying this map is what lets `unresolvedConditions` say it.
535
  * ⚠ OPTIONAL BY DESIGN. Absent = the old behaviour exactly, so every existing caller and every
536
  * stored fixture is byte-identical; the pipeline and the grid supply it.
537
+ * ⚠ W42-T27 REWROTE THE SENTENCE THAT USED TO SIT HERE. It said this map is "deliberately NOT
538
+ * used to change what `evalNode` RETURNS", because flipping these leaves to `false` would empty
539
+ * every grid holding a view that outlived one of its columns. That worry was right and it is
540
+ * exactly why the flip is CONDITIONAL rather than global: in DISPLAY mode (no `strict`) nothing
541
+ * moved β€” an unresolvable leaf is still ignored, still counted here, and the deletion case still
542
+ * paints. Under `strict` the same leaf DENIES. Two semantics, one evaluator; the difference
543
+ * between them IS the security property.
544
  */
545
  fieldByKey?: Map<string, Field>;
546
+ /** PERMISSION mode. Mirrors `platform/harness/filter_eval.py`'s `strict`: every `null` this
547
+ * evaluator would return becomes `false` instead. Absent or false = today's DISPLAY semantics,
548
+ * byte-identical. True = a viewer who may not resolve a leaf is NARROWED by it, never widened. */
549
+ strict?: boolean;
550
  }
551
 
552
  /**
 
961
  /** The TENANT'S today, from the payload. Required by every relative-date condition and
962
  * never defaulted to the browser clock β€” see CustomersPayload.today. */
963
  today?: string;
964
+ /**
965
+ * ⭐⭐ W42-T27 β€” PERMISSION mode for this whole run. Forwarded verbatim onto `EvalCtx.strict`
966
+ * (read its docstring for the semantics); absent or false = today's DISPLAY behaviour,
967
+ * byte-identical.
968
+ *
969
+ * β›” IT HAS TO LIVE HERE, and that is the point of the field existing. `runPipeline` builds its
970
+ * OWN `EvalCtx` below rather than accepting one, so a caller setting `strict` on some other ctx
971
+ * literal β€” the one `CustomerGrid` hands `unresolvedConditions`, say β€” would move a COUNT and
972
+ * not a single row: the flag reads as wired, the wall is open, and every gate stays green.
973
+ */
974
+ strict?: boolean;
975
  }
976
 
977
  export function runPipeline(input: PipelineInput): VisibleRowsResult {
978
  const {
979
  rawRows, fields, filters, search, sorts, groupBy, collapsed,
980
  memberPids = [], filterConj = "and", serverWindowed = false, measureSets,
981
+ cohortSets, viewSets, today, cohortLock, strict,
982
  } = input;
983
+ const ctx: EvalCtx = { measureSets, cohortSets, today, viewSets, strict };
984
 
985
  let unresolvedRank = 0;
986
 
 
1131
  measureSets?: MeasureSets,
1132
  cohortSets?: CohortSets,
1133
  today?: string,
1134
+ cohortLock?: string,
1135
+ /** ⭐⭐ W42-T27 β€” PERMISSION mode; see `EvalCtx.strict` and `PipelineInput.strict`. LAST and
1136
+ * OPTIONAL, so every existing call site is unchanged and defaults to DISPLAY semantics. */
1137
+ strict?: boolean
1138
  ): VisibleRowsResult {
1139
  return useMemo(
1140
  () => runPipeline({ rawRows, fields, filters, search, sorts, groupBy, collapsed,
1141
  memberPids, filterConj, serverWindowed, measureSets,
1142
+ cohortSets, today, cohortLock, strict }),
1143
  [rawRows, fields, filters, filterConj, search, sorts, groupBy, collapsed,
1144
+ memberPids, serverWindowed, measureSets, cohortSets, today, cohortLock, strict]);
1145
  }
web/src/customer-grid/viewEcho.ts CHANGED
@@ -38,7 +38,7 @@
38
  // that re-associates the server's answers β€” never by position.
39
  // ---------------------------------------------------------------------------
40
 
41
- import type { FilterNode, FilterRule, SavedView } from "./types";
42
  import { isFilterGroup, isMeasureRule, isRuleActive } from "./types";
43
 
44
  /**
@@ -270,3 +270,161 @@ export function reconcileEchoView(
270
  },
271
  };
272
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
38
  // that re-associates the server's answers β€” never by position.
39
  // ---------------------------------------------------------------------------
40
 
41
+ import type { FilterNode, FilterRule, GridFolder, SavedView } from "./types";
42
  import { isFilterGroup, isMeasureRule, isRuleActive } from "./types";
43
 
44
  /**
 
270
  },
271
  };
272
  }
273
+
274
+ // ── WAVE 42 Β· T15 (contract C5): the workspace half of the views resolver ───────────────────
275
+ //
276
+ // ⭐⭐ WHY THIS IS SPLIT ACROSS TWO FILES. C5 asks for ONE named resolver answering "the views
277
+ // and folders for THIS DATABASE KEY", called from outside `CustomerGrid`. Two questions hide in
278
+ // that sentence, and they belong to two layers: which payload does a database key name (the
279
+ // SHELL's question, answered by `shell/nav.ts::viewsForDb`), and what does a workspace-bearing
280
+ // payload hold (the GRID's question, answered here). That is the same split T41 made for the
281
+ // path model, where `folders.ts::levelAt` is the resolver and `nav.ts::navLevelAt` supplies the
282
+ // one thing that genuinely differs.
283
+ //
284
+ // β›” IT READS, IT NEVER FETCHES. The page payload already carries `workspace.views` β€” the grid
285
+ // reads exactly these two paths at `CustomerGrid.tsx:1516` (`payload.workspace?.views ?? []`)
286
+ // and `:5159` (`payload?.workspace?.folders`). A second fetch from the shell would ask the
287
+ // server for bytes the browser is already holding, and would answer at a different instant from
288
+ // the grid rendering beside it.
289
+ //
290
+ // β›” WHAT THIS RETURNS IS THE PERSISTED LIST (wave 42, AMENDMENT A6). T15's done-when originally
291
+ // said "the same list `CustomerGrid` renders"; that is unsatisfiable from a pure module, so A6
292
+ // amended it to the persisted `SavedView[]` / `GridFolder[]` for the key, on condition that the
293
+ // exclusions are NAMED here rather than left as a silent shortfall. They are:
294
+ //
295
+ // β›” THREE TRANSFORMS ARE DELIBERATELY NOT REPRODUCED, and none of them is reachable from a pure
296
+ // module β€” they are one browser's localStorage layered onto a MOUNTED grid's state:
297
+ // Β· the synthesized "All records" tab (`CustomerGrid.tsx::allRecordsView`, module-private and
298
+ // therefore unimportable, and it needs the grid's resolved `fields`);
299
+ // Β· `seedLocalViews` + the tombstone/`viewWrites` pruning that keeps an optimistic create alive;
300
+ // Β· `reconcileFolders`' optimistic-create layer over `workspace.folders`.
301
+ // What is returned is the HOST list β€” the same list the grid starts from, and the only one that
302
+ // exists outside a mounted grid.
303
+
304
+ /** The two lists a database's view rail is drawn from. Both ALWAYS present, `[]` when empty:
305
+ * a key a consumer has to test for is a key a consumer forgets to test for. */
306
+ export interface WorkspaceViews {
307
+ views: SavedView[];
308
+ folders: GridFolder[];
309
+ }
310
+
311
+ /**
312
+ * The minimum shape this resolver reads. Structural on purpose rather than `CustomersPayload`:
313
+ * the caller is the SHELL, which must be able to hand over whatever workspace-bearing object it
314
+ * is holding without importing the grid's payload type.
315
+ */
316
+ export interface WorkspaceHolder {
317
+ workspace?: { views?: SavedView[]; folders?: GridFolder[] } | null;
318
+ }
319
+
320
+ /**
321
+ * One workspace-bearing payload to its rail lists. Nothing throws: an absent payload, an absent
322
+ * `workspace`, an absent `views` and an absent `folders` are all legal shapes on this wire
323
+ * (`GridWorkspace.folders` is documented as "Absent = no folders, the pre-wave-8 shape"), and
324
+ * each answers `[]`. `Array.isArray` rather than `?? []` because a drifted host sending a
325
+ * non-array must not be handed to a renderer that will call `.map` on it.
326
+ */
327
+ export function viewsOfWorkspace(payload: WorkspaceHolder | null | undefined): WorkspaceViews {
328
+ const ws = payload?.workspace;
329
+ return {
330
+ views: Array.isArray(ws?.views) ? ws!.views : [],
331
+ folders: Array.isArray(ws?.folders) ? ws!.folders : [],
332
+ };
333
+ }
334
+
335
+ // ── WAVE 42 Β· T45 (ruling R12, contract C9): THE PATH IS WHERE I LEFT IT AFTER A RELOAD ──────
336
+ //
337
+ // R12.6 chose PER-BROWSER persistence of the rail's current folder over always resetting to the
338
+ // top level, and over putting the path in the URL. The URL option was judged more useful and is
339
+ // booked as O4; it is deliberately NOT built here.
340
+ //
341
+ // β›”β›” THIS FILE HOLDS THE PURE HALF ONLY, AND THE REASON IS A GATE, NOT AN AESTHETIC.
342
+ // `verify_view_echo.py` compiles `_test/viewEcho.test.ts` and runs it under BARE NODE
343
+ // (`subprocess.run(["node", str(built)], cwd=WEB)`) β€” no jsdom, no `window`, no `localStorage`,
344
+ // and the test file installs no shim. So anything in here that touched `window` would be
345
+ // UNTESTABLE BY ITS OWN GATE: under node both databases fall into the same `catch` and answer
346
+ // identically, and "two databases keep separate positions" would go green over nothing.
347
+ // Therefore the browser half β€” the hash read, `getItem`, `setItem`, `removeItem` β€” lives in
348
+ // `ViewSidebar.tsx`, beside the `aios-views-rail` try/catch it already owns (`:762`/`:771`), and
349
+ // what stays here is what node can execute and the gate can therefore prove:
350
+ //
351
+ // 1. `pathStorageKey` β€” TWO DIFFERENT DATABASE KEYS PRODUCE TWO DIFFERENT STORAGE KEYS. That
352
+ // is the per-database clause in its node-runnable form, which is why it is exported.
353
+ // 2. `resolveStoredPath` β€” THE STORED ID IS NEVER TRUSTED. A folder deleted by another session
354
+ // (or by this account on another machine) leaves a stored id pointing at nothing. Restoring
355
+ // it blind renders an empty list inside a folder that does not exist, with no way back
356
+ // except a manual reset. So it is resolved against the live standable set on every read,
357
+ // and anything that does not resolve falls back to the top level (`null`).
358
+ //
359
+ // ⚠ THE DEFENSIVE RULE THE OTHER HALF CARRIES, recorded here because this is where the reader
360
+ // looks: in a private window, with site data cleared, or in a browser configured to block
361
+ // storage, `window.localStorage` throws on PROPERTY ACCESS β€” not on `getItem`. So the usual
362
+ // `typeof window !== "undefined" && window.localStorage` feature test IS the throwing
363
+ // expression and must sit INSIDE the try. A nav that throws on mount is a blank shell.
364
+ //
365
+ // Absent, malformed, wrong type and empty string all mean THE TOP LEVEL. Never an error, never a
366
+ // guess at some other folder.
367
+
368
+ /** Namespace for the per-database stored path. Sibling of the rail's existing `aios-views-rail`
369
+ * fold-state key, which is GLOBAL rather than per database and is not touched from here. */
370
+ const VIEW_PATH_KEY_PREFIX = "aios-views-at";
371
+
372
+ /**
373
+ * The storage key this browser remembers ONE database's open folder under. Lower-case and
374
+ * hyphenated like its `aios-views-rail` sibling, and STABLE: changing it silently forgets every
375
+ * viewer's position.
376
+ *
377
+ * ⭐ EXPORTED SO THE GATE CAN PROVE THE PER-DATABASE CLAUSE. "Two databases keep separate
378
+ * positions" reduces, without a browser, to `pathStorageKey(a) !== pathStorageKey(b)` β€” which is
379
+ * the whole of that clause that a node process can observe, and the reason this string builder
380
+ * is a named export rather than a template literal inlined at the call site.
381
+ *
382
+ * Total by construction: a non-string key degrades to the empty key rather than throwing, so an
383
+ * unidentifiable route loses its memory instead of taking the rail down.
384
+ */
385
+ export function pathStorageKey(dbKey: string): string {
386
+ return `${VIEW_PATH_KEY_PREFIX}-${typeof dbKey === "string" ? dbKey : ""}`;
387
+ }
388
+
389
+ /**
390
+ * β›” THE CLAUSE THAT SHIPS BROKEN IF IT IS SKIPPED. Answers `stored` only when it is one of the
391
+ * ids the caller says are STANDABLE RIGHT NOW, and `null` otherwise β€” so a folder deleted by
392
+ * another session lands the viewer at that database's top level instead of inside a folder that
393
+ * no longer exists.
394
+ *
395
+ * β›”β›” THE ARGUMENT IS A SET OF VALID IDS, NOT THE `GridFolder[]` LIST, AND THAT IS THE WHOLE
396
+ * POINT. This module deliberately does not know what a valid destination is, because the rail
397
+ * ALREADY has exactly one definition of it and a second one here is the drift contract C9 exists
398
+ * to prevent. The existing definition is W42-T43's `ViewSidebar.tsx::atId`, which validates
399
+ * against the rendered GROUPS rather than against `folders` β€” on purpose, because a SYNTHESISED
400
+ * group ("Shared with me", and one per shared folder via `sharedFolderGroupId`) owns a head on
401
+ * this rail while having NO record in the stored `folders` list. Validating a stored path
402
+ * against `folders` would therefore call a live shared folder deleted and bounce the viewer
403
+ * straight out of a folder they had just opened β€” the stale-path guard MISFIRING on a real
404
+ * place, which reads to a user as "reload sometimes forgets where I was" and is close to
405
+ * unreportable. So the caller passes the same standable set `atId` derives, and there is ONE
406
+ * answer to "is this a place I can stand", not two.
407
+ *
408
+ * ⚠ ONE ID IS ENOUGH, ANCESTORS NEED NO WALK, and that is scouted rather than assumed: folder
409
+ * delete does NOT cascade (`folders.ts:17-23` β€” `folder_delete` moves contents to the top level
410
+ * instead), and `folders.ts::folderNesting` re-roots any `parent` pointing at an unknown id to
411
+ * `null`. So a folder whose ancestor was deleted is still a real, standable place at the root,
412
+ * and checking the leaf is checking the whole chain.
413
+ *
414
+ * Run on EVERY read, not once at mount: the standable set arrives and changes over a session's
415
+ * life, and a path resolved against an earlier set is the same untrusted id one tick later.
416
+ * Absent or drifted input answers the top level rather than throwing.
417
+ */
418
+ export function resolveStoredPath(
419
+ stored: string | null | undefined,
420
+ validIds: Iterable<string> | null | undefined
421
+ ): string | null {
422
+ if (typeof stored !== "string" || stored === "") return null;
423
+ if (!validIds || typeof (validIds as Iterable<string>)[Symbol.iterator] !== "function") {
424
+ return null;
425
+ }
426
+ for (const id of validIds) {
427
+ if (id === stored) return stored;
428
+ }
429
+ return null;
430
+ }
web/src/customer-grid/viewModes.tsx CHANGED
@@ -106,22 +106,23 @@ function IconDayCells() {
106
  mode-independent: `<ViewSidebar>` renders under `!hideViews` and never consults `displayMode`,
107
  so it is reachable from Map exactly as it is from Grid. Verified before removal, not assumed. */
108
 
 
 
 
 
 
 
 
 
109
  export function ModeSwitch({
110
  mode,
111
  onMode,
112
  locked = false,
113
- dateField,
114
- dateChoices,
115
  stackField,
116
  stackChoices,
117
  onPickField,
118
  clamped = true,
119
  onClamp,
120
- calendarMode = "records",
121
- onCalendarMode,
122
- calendarMetrics = [],
123
- metricChoices = [],
124
- onCalendarMetrics,
125
  }: {
126
  mode: DisplayMode;
127
  onMode: (m: DisplayMode) => void;
@@ -251,15 +252,10 @@ export function ModeSwitch({
251
  date field and a board without a stack field are not modes, so the picker is never
252
  in its placeholder state here unless the view names a field the table has lost β€”
253
  which it now SHOWS rather than silently replacing with the first choice. */}
254
- {mode === "calendar" && dateChoices.length > 0 && (
255
- <FieldSelectButton
256
- className="cg-mode-field"
257
- ariaLabel="Calendar date field"
258
- value={dateField?.key}
259
- onChange={(key) => onPickField("dateField", key)}
260
- fields={dateChoices.map((f) => ({ key: f.key, label: f.label, type: f.type }))}
261
- />
262
- )}
263
  {mode === "kanban" && stackChoices.length > 0 && (
264
  <FieldSelectButton
265
  className="cg-mode-field"
@@ -293,6 +289,82 @@ export function ModeSwitch({
293
  {clamped ? "Short cards" : "Full cards"}
294
  </button>
295
  )}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
296
  {/* Owner item 4 (C-DISP) β€” records vs summaries.
297
  wave17 owner item 8 β€” it WAS a bare toggle whose label was its own state, sitting in a
298
  bar where every other control opens a panel. Two things were wrong with that beyond
@@ -303,7 +375,7 @@ export function ModeSwitch({
303
  A `Popover` with radio rows fixes both β€” the trigger keeps ONE name and both choices
304
  are visible with the current one marked β€” and it is the same component Filter / Sort /
305
  Group / Totals mount, which is what item 8 asks for. */}
306
- {mode === "calendar" && onCalendarMode && (
307
  <Popover
308
  label={`Day cells Β· ${calendarMode === "summary" ? "Summaries" : "Records"}`}
309
  icon={<IconDayCells />}
@@ -350,7 +422,7 @@ export function ModeSwitch({
350
  the feature would be half-delivered.
351
 
352
  Only shown in summary mode: a picker for a thing that is not on screen is noise. */}
353
- {mode === "calendar" && calendarMode === "summary" && onCalendarMetrics && (
354
  <Popover
355
  label={`Totals Β· ${calendarMetrics.length + 1}`}
356
  icon={<ModeIcon mode="chart" />}
@@ -420,11 +492,11 @@ export function ModeSwitch({
420
  )}
421
  </Popover>
422
  )}
423
- </span>
 
424
  );
425
  }
426
 
427
- /** Map-only settings live in their own row beneath the main Filter / Sort / Group navigation. */
428
  export function MapSettings({
429
  coordField,
430
  coordChoices,
@@ -446,7 +518,27 @@ export function MapSettings({
446
  selectedCount: number;
447
  onToggleRoute: () => void;
448
  }) {
449
- if (coordChoices.length === 0 && sizeChoices.length === 0 && selectedCount < 1) return null;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
450
  return (
451
  <div className="cg-map-settings" aria-label="Map settings">
452
  <span className="cg-map-settings-label">Map</span>
@@ -456,7 +548,7 @@ export function MapSettings({
456
  aria-expanded={routeOpen}
457
  aria-controls="cg-route-popover"
458
  onClick={onToggleRoute}
459
- title="Show or hide route planning"
460
  >
461
  Route{selectedCount >= 2 ? ` Β· ${selectedCount} selected` : ""}
462
  </button>
 
106
  mode-independent: `<ViewSidebar>` renders under `!hideViews` and never consults `displayMode`,
107
  so it is reachable from Map exactly as it is from Grid. Verified before removal, not assumed. */
108
 
109
+ /**
110
+ * ⭐⭐ W42-T19 β€” CALENDAR'S THREE SUB-CONTROLS NO LONGER DESTRUCTURE HERE, and the props they used
111
+ * deliberately STAY in the type below rather than being deleted with them. `CustomerGrid.tsx` is
112
+ * another lane's file this wave and still passes all eight; narrowing the type would turn that
113
+ * untouchable call site into a compile error. So the contract is unchanged and only the BODY moved
114
+ * (to `CalendarSettings`). ⚠ `noUnusedLocals` is on, which is why the names come out of the
115
+ * destructuring pattern instead of being left bound and unread.
116
+ */
117
  export function ModeSwitch({
118
  mode,
119
  onMode,
120
  locked = false,
 
 
121
  stackField,
122
  stackChoices,
123
  onPickField,
124
  clamped = true,
125
  onClamp,
 
 
 
 
 
126
  }: {
127
  mode: DisplayMode;
128
  onMode: (m: DisplayMode) => void;
 
252
  date field and a board without a stack field are not modes, so the picker is never
253
  in its placeholder state here unless the view names a field the table has lost β€”
254
  which it now SHOWS rather than silently replacing with the first choice. */}
255
+ {/* β›” W42-T19 β€” the CALENDAR date-field button that stood here now lives in
256
+ `CalendarSettings`, on the second row. The kanban one below stays: only Calendar was
257
+ named by owner instruction 11, and moving Kanban's too would be a scope the owner did
258
+ not ask for. */}
 
 
 
 
 
259
  {mode === "kanban" && stackChoices.length > 0 && (
260
  <FieldSelectButton
261
  className="cg-mode-field"
 
289
  {clamped ? "Short cards" : "Full cards"}
290
  </button>
291
  )}
292
+ {/* β›” W42-T19 β€” the Day cells records/summaries popover AND the summary-mode Totals picker
293
+ that stood here now live in `CalendarSettings`, on the second row, beside the date-field
294
+ button. Nothing calendar-only is left in `cg-modes`; what remains is the universal
295
+ "View Β· mode" trigger plus Kanban's two controls. */}
296
+ </span>
297
+ );
298
+ }
299
+
300
+ /** Map-only settings live in their own row beneath the main Filter / Sort / Group navigation. */
301
+ /**
302
+ * ⭐⭐ WAVE 42 Β· W42-T19 (owner instruction 11) β€” CALENDAR'S OWN CONTROLS, ON THEIR OWN ROW.
303
+ *
304
+ * Owner: *"Under Calendar View, I see that the toggle navigation for Choose dates and
305
+ * Records/Summaries still live at the same line as Filter/Sort/Group. Move this downward exactly
306
+ * how Time-series and Map view has it."*
307
+ *
308
+ * β›” THIS COMPONENT LANDED EMPTY IN THE WAVE'S BASELINE COMMIT, AND THAT WAS THE WHOLE POINT. IT IS
309
+ * NOW FILLED (lane D), and the mount was never touched. It was already MOUNTED in
310
+ * `CustomerGrid.tsx` beside `MapSettings` under `displayMode === "calendar" && !pivotOn`, so the
311
+ * lane that filled it never had to open that file. `CustomerGrid.tsx` is another lane's, and a
312
+ * cross-lane mount is exactly how wave 41 shipped a whole feature that nothing ever rendered.
313
+ *
314
+ * β›” WHAT THE FILLING LANE MUST NOT DO, AND DID NOT: relocate the whole `modeControl` prop out of
315
+ * `<Toolbar>`.
316
+ * `ModeSwitch` bundles the UNIVERSAL "View Β· mode" trigger together with Calendar's sub-controls in
317
+ * one `<span className="cg-modes">`, so moving the lot deletes the mode switcher from row one for
318
+ * EVERY view, not just Calendar. Extract only the three `mode === "calendar"` blocks: the date
319
+ * field button, the `Day cells` records/summary toggle, and the summary-mode totals picker.
320
+ *
321
+ * ⭐ COPY MAP'S MECHANISM, NOT TIME-SERIES'. `MapSettings` is a sibling of `<Toolbar>` in
322
+ * `CustomerGrid.tsx`, rendered after it and before `.cg-grid-box`. `TimeSeriesPanel`'s `.cg-ts-bar`
323
+ * only LOOKS the same: it lives inside the view component and mounts inside `.cg-grid-box`.
324
+ *
325
+ * ⚠ AND SAY THIS OUT LOUD WHEN IT LANDS, because it is a behaviour change rather than a move:
326
+ * leaving `.cg-toolbar` leaves the `cgtoolbar` container query, so these controls stop collapsing
327
+ * to icons at 1080px and 480px. `.cg-map-settings` never had that collapse, so this matches Map.
328
+ */
329
+ export function CalendarSettings({
330
+ dateField,
331
+ dateChoices,
332
+ onPickField,
333
+ calendarMode = "records",
334
+ onCalendarMode,
335
+ calendarMetrics = [],
336
+ metricChoices = [],
337
+ onCalendarMetrics,
338
+ }: {
339
+ dateField?: Field;
340
+ dateChoices: Field[];
341
+ onPickField: (k: "dateField" | "stackField", key: string) => void;
342
+ calendarMode?: "records" | "summary";
343
+ onCalendarMode?: (next: "records" | "summary") => void;
344
+ calendarMetrics?: { id: string; field: string; agg: string }[];
345
+ metricChoices?: Field[];
346
+ onCalendarMetrics?: (next: { id: string; field: string; agg: string }[]) => void;
347
+ }) {
348
+ /* ⚠ The HOST already guards on `displayMode === "calendar" && !pivotOn`, so there is no mode
349
+ test in here: repeating it would be a second place to get the condition wrong. What is kept is
350
+ each control's OWN precondition, unchanged from where it used to live in `ModeSwitch`. */
351
+ if (dateChoices.length === 0 && !onCalendarMode) return null;
352
+ return (
353
+ <div className="cg-cal-settings" aria-label="Calendar settings">
354
+ <span className="cg-cal-settings-label">Calendar</span>
355
+ {/* Item 20 (C-FLDSEL) β€” the date picker wears the type mark, same control as the filter and
356
+ sort rows. It has no "none" state: a calendar without a date field is not a mode, so the
357
+ picker sits in its placeholder state only when the view names a field the table has lost,
358
+ which it now SHOWS rather than silently replacing with the first choice. */}
359
+ {dateChoices.length > 0 && (
360
+ <FieldSelectButton
361
+ className="cg-mode-field"
362
+ ariaLabel="Calendar date field"
363
+ value={dateField?.key}
364
+ onChange={(key) => onPickField("dateField", key)}
365
+ fields={dateChoices.map((f) => ({ key: f.key, label: f.label, type: f.type }))}
366
+ />
367
+ )}
368
  {/* Owner item 4 (C-DISP) β€” records vs summaries.
369
  wave17 owner item 8 β€” it WAS a bare toggle whose label was its own state, sitting in a
370
  bar where every other control opens a panel. Two things were wrong with that beyond
 
375
  A `Popover` with radio rows fixes both β€” the trigger keeps ONE name and both choices
376
  are visible with the current one marked β€” and it is the same component Filter / Sort /
377
  Group / Totals mount, which is what item 8 asks for. */}
378
+ {onCalendarMode && (
379
  <Popover
380
  label={`Day cells Β· ${calendarMode === "summary" ? "Summaries" : "Records"}`}
381
  icon={<IconDayCells />}
 
422
  the feature would be half-delivered.
423
 
424
  Only shown in summary mode: a picker for a thing that is not on screen is noise. */}
425
+ {calendarMode === "summary" && onCalendarMetrics && (
426
  <Popover
427
  label={`Totals Β· ${calendarMetrics.length + 1}`}
428
  icon={<ModeIcon mode="chart" />}
 
492
  )}
493
  </Popover>
494
  )}
495
+
496
+ </div>
497
  );
498
  }
499
 
 
500
  export function MapSettings({
501
  coordField,
502
  coordChoices,
 
518
  selectedCount: number;
519
  onToggleRoute: () => void;
520
  }) {
521
+ /**
522
+ * ⭐⭐ W42-T24 (instruction 10) β€” THE ROW NO LONGER SELF-HIDES, and that is the whole
523
+ * reachability half of the route navigation.
524
+ *
525
+ * The old guard returned null on a database with no coordinate or size columns and nothing
526
+ * selected. That was right while the Route button opened a PLANNER, which needs stops to plan
527
+ * over; it is wrong now that the button opens a NAVIGATION, whose entire job is to list routes
528
+ * a colleague already saved. A rep opening the map to drive somebody else's Monday has nothing
529
+ * selected by definition, so the old guard hid the control precisely when it was needed.
530
+ *
531
+ * ⚠ THE ROW IS NEVER EMPTY, so nothing is traded away: the Route toggle below renders
532
+ * unconditionally, and it was the only reason the guard's other two clauses were ever checked.
533
+ *
534
+ * β›” WHERE THIS RAIL LIVES WHEN THE VIEW IS NOT MAP: IT DOES NOT, DELIBERATELY.
535
+ * Opening a route SELECTS records and DRAWS a sequence, and neither has a referent on a grid,
536
+ * a calendar or a kanban board; a listing whose one-click action could not do the thing it
537
+ * names would be a menu of dead rows. A route's non-map identity is a COLUMN of visit numbers,
538
+ * and that is already reachable in every display mode through the grid's own column header
539
+ * menu, which is where its share dialog lives too. So the navigation is Map's, the column is
540
+ * everywhere, and neither is a copy of the other.
541
+ */
542
  return (
543
  <div className="cg-map-settings" aria-label="Map settings">
544
  <span className="cg-map-settings-label">Map</span>
 
548
  aria-expanded={routeOpen}
549
  aria-controls="cg-route-popover"
550
  onClick={onToggleRoute}
551
+ title="Show or hide the route navigation and planner"
552
  >
553
  Route{selectedCount >= 2 ? ` Β· ${selectedCount} selected` : ""}
554
  </button>
web/src/filter-kit/FieldsHidePanel.tsx CHANGED
@@ -13,7 +13,7 @@
13
  // happens to store the other polarity.
14
  // ---------------------------------------------------------------------------
15
 
16
- import { useState } from "react";
17
  // ⚠ W40-T16 β€” the bare `Field` type import is GONE, not misplaced: the prop below is
18
  // `PermsField[]` now, which extends it, so importing both would leave one unread and
19
  // `tsconfig.app.json`'s `noUnusedLocals` reds the build on exactly that.
@@ -27,9 +27,22 @@ import { useState } from "react";
27
  // miniature, where what a user searches and what they read answer the same question
28
  // differently. It lives in `types.ts` so the node harness can run it: this panel is JSX and
29
  // its search path only fires once somebody types, which no static render can do.
30
- import { fieldEditMode, fieldLabel, isPresetField } from "../customer-grid/types";
 
 
31
  import { FieldTypeIcon } from "../customer-grid/icons";
32
  import { TYPE_LABELS } from "../customer-grid/iconShapes";
 
 
 
 
 
 
 
 
 
 
 
33
  // ⭐⭐ W40-T16 (owner instruction 13) β€” A METRIC IS A ROW LIKE ANY OTHER, and the ONE thing that
34
  // makes it read differently is its NAME. `metricLabel` is that rule, declared once beside the
35
  // flag it depends on, and it is a pure string function so this panel does not acquire a runtime
@@ -57,7 +70,9 @@ import {
57
  bulkOutcomeLine,
58
  deleteImpactTitle,
59
  deleteRefusalReason,
 
60
  fieldClassOf,
 
61
  fieldUsageOf,
62
  fieldUsageTitle,
63
  fieldUsageTotal,
@@ -66,14 +81,21 @@ import {
66
  originBadge,
67
  permRuleWarningTitle,
68
  shareMarkTitle,
 
69
  valuesBadge,
 
70
  LOCKED_HIDE_REFUSAL,
71
  PRESET_BADGE_TITLE,
72
  REMOVE_FIELD_HINT,
73
  REMOVE_FIELD_LABEL,
74
  } from "./fieldClass";
75
 
76
- export interface FieldsHidePanelProps {
 
 
 
 
 
77
  /** Owner item 23 β€” in the view's COLUMN ORDER, not definition order. Dragging a row here
78
  * rewrites `config.order`, so a list showing a different sequence from the one it edits
79
  * would move a field to a position the user never pointed at.
@@ -108,7 +130,10 @@ export interface FieldsHidePanelProps {
108
  * colleague owns is in the set and looks deletable to a non-owner today. The narrowing has to
109
  * happen here, against C1's classification, because the set cannot express who is asking.
110
  *
111
- * ⚠ NO MOUNT PASSES ONE YET, and the render below is built for that. All four call sites
 
 
 
112
  * (`customer-grid/Toolbar.tsx`, `settings/DatabasePermsPane.tsx`, `settings/ModulePermsList.tsx`
113
  * and the `web_grid_ux` render) are outside this ticket's fence. See the row map for the split
114
  * that keeps an unwired viewer from silently withdrawing a delete that ships today.
@@ -121,19 +146,21 @@ export interface FieldsHidePanelProps {
121
  * a destructive act, which is the one thing this ticket must not ship, so the affordance
122
  * renders only where a host supplied this door.
123
  *
124
- * ⚠ NO MOUNT PASSES ONE YET EITHER, and no endpoint exists for it (searched: nothing in
 
 
125
  * `aios-web/api` unshares a field). The half of R6(b) that IS enforced today is the refusal:
126
  * a shared-with-me field loses its Delete whether or not this handler arrives.
127
  */
128
- onRemoveField?: (key: string) => void;
129
  /**
130
  * ⭐⭐ W41-T30 (R3, R8) - THE TWO BULK ACTS THAT HAVE NO CALLER YET, and they take the
131
  * WHOLE selection rather than one key, because that is what makes them one act: a share
132
  * dialog opened once over five fields is the feature; five dialogs is the thing R3 asked
133
  * to be replaced.
134
  *
135
- * β›” OPTIONAL, AND ABSENT MEANS THE BUTTON IS NOT THERE. This panel's four mount sites are
136
- * all outside this ticket's fence (see `viewer`'s JSDoc for the list), so no host can supply
137
  * either door today. R8 forbids the alternative outright: an affordance that renders and does
138
  * nothing is worse than one that is missing, because a missing one is visibly missing. The
139
  * house posture this file already states for `onShowAll` / `onHideAll` applies unchanged -
@@ -143,8 +170,8 @@ export interface FieldsHidePanelProps {
143
  * for an admin viewer, because "an admin can reassign a field's owner" is the whole of the
144
  * ruling and a non-admin has no version of the act to offer.
145
  */
146
- onShareFields?: (keys: string[]) => void;
147
- onReassignFields?: (keys: string[]) => void;
148
  /**
149
  * ⭐⭐ W41-T30 - BULK HIDE AND SHOW NEED A PLURAL DOOR, AND THIS IS THE TICKET'S BIGGEST
150
  * MEASURED FINDING. The wave board's premise was that bulk visibility "can be wired for real:
@@ -165,7 +192,7 @@ export interface FieldsHidePanelProps {
165
  * builds `onShowAll` out of `onColumnsVisible(keys: string[])`. Wiring this prop to it is the
166
  * whole of the caller change, and it is outside this ticket's fence.
167
  */
168
- onSetFieldsHidden?: (keys: string[], hidden: boolean) => void;
169
  /**
170
  * THE BATCH DELETE DOOR, AND BULK DELETE IS ABSENT WITHOUT IT, ON PURPOSE.
171
  *
@@ -188,7 +215,7 @@ export interface FieldsHidePanelProps {
188
  * offers no bulk delete at all, which is the posture this file already keeps for every other
189
  * handler ("a missing prop makes the action ABSENT, never present-and-inert").
190
  */
191
- onDeleteFields?: (keys: string[]) => void;
192
  /**
193
  * ⭐⭐ W40-T17 (owner instruction 15) β€” DOES THIS MOUNT FILE ROWS UNDER "Shared with me" AND
194
  * "Shared with everyone"? Absent means YES, which is the grid's behaviour and every behaviour
@@ -229,6 +256,198 @@ export interface FieldsHidePanelProps {
229
  manager?: boolean;
230
  }
231
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
232
  /**
233
  * The Fields show/hide panel (owner item 7 remainder, wave 2 2026-07-27): a SEARCH box over the
234
  * field list, and a small muted `Pre-set` chip on every Odoo-precomputed field. The chip's
@@ -238,7 +457,7 @@ export interface FieldsHidePanelProps {
238
  * labels say "all", and a narrowed meaning under an active search would be a quiet lie.
239
  */
240
  export function FieldsHidePanel({
241
- fields,
242
  hidden,
243
  onToggle,
244
  onHideAll,
@@ -265,6 +484,17 @@ export function FieldsHidePanel({
265
  // already made: swap the two lines and this is `undefined` on every mount.
266
  manager = sharedSections,
267
  }: FieldsHidePanelProps) {
 
 
 
 
 
 
 
 
 
 
 
268
  /** W41-T27 - one name for "this mount is the Fields manager", so the title, the width class
269
  * and anything a later ticket adds all key off the same answer instead of re-deriving it. */
270
  const managerMode = manager;
@@ -314,8 +544,10 @@ export function FieldsHidePanel({
314
  * A field with no metric flag comes back byte-identical to `fieldLabel(f)` β€” which is what
315
  * keeps the GRID's mount of this panel unchanged, since grid fields never carry the flag.
316
  */
317
- const rowLabel = (f: PermsField): string =>
318
- f.isMetric ? metricLabel(fieldLabel(f)) : fieldLabel(f);
 
 
319
  /**
320
  * ⭐⭐ W41-T30 (contract C2) - EVERY RIGHT THIS PANEL ASKS ABOUT ONE FIELD, ASKED IN ONE
321
  * PLACE, so the ROW and the BULK BAR cannot answer the same question differently.
@@ -348,35 +580,56 @@ export function FieldsHidePanel({
348
  return { fc, presetRefusal, canRemove, deletable, removable, hideable };
349
  };
350
  const q = query.trim().toLowerCase();
351
- const shown = q ? fields.filter((f) => rowLabel(f).toLowerCase().includes(q)) : fields;
 
 
 
 
 
 
 
 
 
352
  /**
353
  * ⭐⭐ W40-T17 (owner instruction 15) β€” TWO MOUNTS, TWO QUESTIONS, ONE PANEL.
354
  *
355
  * The GRID asks "whose column is this?" and answers it with three sections, because a person
356
- * looking at their own table needs to tell their columns from the tenant's. The PERMISSION
357
- * EDITOR asks "which columns may an admin set a rule on?", and AM-2 answers that with
358
- * `metric || !custom` β€” the database's own pre-set columns, plus every bound measure. They are
359
- * not the same list narrowed; they are different questions with different answers.
 
 
 
 
 
 
 
 
 
 
360
  *
361
- * β›” THE THREE-SECTION ARM IS UNCHANGED AND MUST STAY SPELLED EXACTLY THIS WAY.
362
- * `verify_map.py`'s `private-by-default-is-anchored` leg reads this file for the literal
363
- * `fieldEditMode(field) === "collaborative"`: it is what pins "Shared with everyone" to the
364
- * `collaborative` answer, so a route column stamped `edit: personal` is filed as private by
365
- * rule rather than by luck. Rename the parameter or move the predicate and that gate reports a
366
- * fact about route columns going stale, one surface away from here.
 
 
367
  *
368
  * ⚠ THE NARROW ARM RENDERS ONE UNTITLED SECTION, which is what the first section has always
369
- * been. No heading appears and no heading disappears: `section.title` is falsy, so the rows sit
370
- * directly under the search box exactly as the personal rows do on the grid today.
371
  */
372
  const sections = sharedSections
373
  ? [
374
- { key: "personal", title: "", fields: shown.filter((field) =>
375
- (!field.custom && !field.shared) || fieldEditMode(field) === "personal") },
376
- { key: "me", title: "Shared with me", fields: shown.filter((field) =>
377
- (field.custom || field.shared) && fieldEditMode(field) === "users") },
378
- { key: "everyone", title: "Shared with everyone", fields: shown.filter((field) =>
379
- (field.custom || field.shared) && fieldEditMode(field) === "collaborative") },
380
  ]
381
  : [{ key: "personal", title: "", fields: presetHideFields(shown) }];
382
  /**
@@ -542,7 +795,14 @@ export function FieldsHidePanel({
542
  onChange={(e) => setQuery(e.target.value)}
543
  />
544
  <div className="cg-pop-list">
545
- {sections.map((section) => (
 
 
 
 
 
 
 
546
  <div key={section.key} className="cg-fields-section">
547
  {section.title && <div className="cg-fields-section-title">{section.title}</div>}
548
  {section.fields.map((f) => {
@@ -566,11 +826,25 @@ export function FieldsHidePanel({
566
  // `fieldRights` above). The row used to derive C2's terms inline, where no
567
  // footer button could reach them.
568
  const rights = fieldRights(f);
 
 
 
 
 
569
  const fc = rights.fc;
570
  const originText = fc && originBadge(fc);
571
  const audienceText = fc && audienceBadge(fc);
572
  const valuesText = fc && valuesBadge(fc);
573
  const shareTitle = fc && shareMarkTitle(fc);
 
 
 
 
 
 
 
 
 
574
  // ⭐⭐ W41-T28 (R3, R8) - WHERE THIS FIELD IS USED, read off C8's `usage`
575
  // block and NEVER counted here. This component can see one user's field list
576
  // and nothing else: not the other users' saved views, not the automations, not
@@ -798,6 +1072,27 @@ export function FieldsHidePanel({
798
  vocabulary is learned. */}
799
  <FieldTypeIcon type={f.type} title={TYPE_LABELS[f.type]} />
800
  <span className="cg-check-label">{rowLabel(f)}</span>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
801
  {/* ⭐ OWNER ITEM 3 (2026-08-06): *"it doesn't show pre-set when I hide fields just
802
  like how Odoo fields are. This is always the standard label."* Right β€” the chip
803
  asked `source === "odoo"`, so a column an AUTOMATION fills (source `overlay`)
@@ -836,6 +1131,33 @@ export function FieldsHidePanel({
836
  {audienceText && (
837
  <span className="cg-preset-tag cg-field-audience">{audienceText}</span>
838
  )}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
839
  {/* ⭐⭐ W41-T27 (owner instruction 8) β€” THE HOVER CHIP. A shared row carries a small
840
  share mark whose title names WHO shared it and to whom. A mark and a tooltip,
841
  never a sentence on the row (DESIGN Β§4); inline SVG in the house vocabulary,
 
13
  // happens to store the other polarity.
14
  // ---------------------------------------------------------------------------
15
 
16
+ import { useMemo, useState } from "react";
17
  // ⚠ W40-T16 β€” the bare `Field` type import is GONE, not misplaced: the prop below is
18
  // `PermsField[]` now, which extends it, so importing both would leave one unread and
19
  // `tsconfig.app.json`'s `noUnusedLocals` reds the build on exactly that.
 
27
  // miniature, where what a user searches and what they read answer the same question
28
  // differently. It lives in `types.ts` so the node harness can run it: this panel is JSX and
29
  // its search path only fires once somebody types, which no static render can do.
30
+ import { fieldEditMode, fieldLabel, isPresetField, offerableFields,
31
+ FIELD_EDIT_BLURBS, FIELD_EDIT_LABELS }
32
+ from "../customer-grid/types";
33
  import { FieldTypeIcon } from "../customer-grid/icons";
34
  import { TYPE_LABELS } from "../customer-grid/iconShapes";
35
+ // ⭐⭐ W42-T38 β€” THE FORMULA HALF OF THE BROKEN-FIELD MARK, CONSUMED RATHER THAN RESPELLED.
36
+ // `validateFormula` already owns "does every {ref} this source names exist on this table", and it
37
+ // is the rule the column menu validates a formula WITH; a second copy here would be the shape
38
+ // [[two-enumerations-from-different-anchors]] describes, where one of the two later learns
39
+ // something the other does not. `parseFormula` comes with it only to tell a SOURCE THAT CANNOT BE
40
+ // READ apart from a source that reads a column this table is not offering, because those two
41
+ // deserve different sentences and `validateFormula` returns one `error` string for both.
42
+ // ⚠ SAFE FOR THE KIT'S MODULE GRAPH: `formulaEngine.ts` has NO imports at all (it is the leaf the
43
+ // Python port mirrors), so nothing here can close a cycle and `verify_ui.py`'s render smoke,
44
+ // which reaches this file by mounting `PermsEditor` under bare node, still resolves.
45
+ import { parseFormula, validateFormula } from "../customer-grid/formulaEngine";
46
  // ⭐⭐ W40-T16 (owner instruction 13) β€” A METRIC IS A ROW LIKE ANY OTHER, and the ONE thing that
47
  // makes it read differently is its NAME. `metricLabel` is that rule, declared once beside the
48
  // flag it depends on, and it is a pure string function so this panel does not acquire a runtime
 
70
  bulkOutcomeLine,
71
  deleteImpactTitle,
72
  deleteRefusalReason,
73
+ fieldAuthorBadge,
74
  fieldClassOf,
75
+ fieldSectionOf,
76
  fieldUsageOf,
77
  fieldUsageTitle,
78
  fieldUsageTotal,
 
81
  originBadge,
82
  permRuleWarningTitle,
83
  shareMarkTitle,
84
+ supersededNoteOf,
85
  valuesBadge,
86
+ FIELD_SECTION_TITLES,
87
  LOCKED_HIDE_REFUSAL,
88
  PRESET_BADGE_TITLE,
89
  REMOVE_FIELD_HINT,
90
  REMOVE_FIELD_LABEL,
91
  } from "./fieldClass";
92
 
93
+ /**
94
+ * ⭐⭐ W42-T12 β€” THE BASE ARM. Everything a mount may pass, with the six manager doors still
95
+ * OPTIONAL here, because the two permission rooms genuinely have no version of them. What makes
96
+ * the manager mount unable to drop one is the union at the bottom of this block, not this shape.
97
+ */
98
+ interface FieldsHidePanelBase {
99
  /** Owner item 23 β€” in the view's COLUMN ORDER, not definition order. Dragging a row here
100
  * rewrites `config.order`, so a list showing a different sequence from the one it edits
101
  * would move a field to a position the user never pointed at.
 
130
  * colleague owns is in the set and looks deletable to a non-owner today. The narrowing has to
131
  * happen here, against C1's classification, because the set cannot express who is asking.
132
  *
133
+ * ⭐ W42-T12 CORRECTS THE PARAGRAPH BELOW: the grid's mount passes one now, and the manager arm
134
+ * of this file's props union makes it unable to stop. The render below is still built for an
135
+ * absent viewer, because the two permission rooms match the plain arm and pass nothing.
136
+ * ⚠ WHEN THIS WAS WRITTEN, NO MOUNT PASSED ONE. All four call sites
137
  * (`customer-grid/Toolbar.tsx`, `settings/DatabasePermsPane.tsx`, `settings/ModulePermsList.tsx`
138
  * and the `web_grid_ux` render) are outside this ticket's fence. See the row map for the split
139
  * that keeps an unwired viewer from silently withdrawing a delete that ships today.
 
146
  * a destructive act, which is the one thing this ticket must not ship, so the affordance
147
  * renders only where a host supplied this door.
148
  *
149
+ * ⭐ W42-T12 β€” THE GRID'S MOUNT PASSES ONE NOW (`CustomerGrid::useFieldBulkDoors`); the
150
+ * sentence below records what was true before it.
151
+ * ⚠ NO ENDPOINT EXISTS FOR IT STILL (searched: nothing in
152
  * `aios-web/api` unshares a field). The half of R6(b) that IS enforced today is the refusal:
153
  * a shared-with-me field loses its Delete whether or not this handler arrives.
154
  */
155
+ onRemoveField?: ((key: string) => void) | null;
156
  /**
157
  * ⭐⭐ W41-T30 (R3, R8) - THE TWO BULK ACTS THAT HAVE NO CALLER YET, and they take the
158
  * WHOLE selection rather than one key, because that is what makes them one act: a share
159
  * dialog opened once over five fields is the feature; five dialogs is the thing R3 asked
160
  * to be replaced.
161
  *
162
+ * β›” OPTIONAL ON THE BASE, REQUIRED ON THE MANAGER ARM (W42-T12), AND ABSENT STILL MEANS THE
163
+ * BUTTON IS NOT THERE. When this was written, all four mount sites were outside the fence (see `viewer`'s JSDoc for the list), so no host can supply
164
  * either door today. R8 forbids the alternative outright: an affordance that renders and does
165
  * nothing is worse than one that is missing, because a missing one is visibly missing. The
166
  * house posture this file already states for `onShowAll` / `onHideAll` applies unchanged -
 
170
  * for an admin viewer, because "an admin can reassign a field's owner" is the whole of the
171
  * ruling and a non-admin has no version of the act to offer.
172
  */
173
+ onShareFields?: ((keys: string[]) => void) | null;
174
+ onReassignFields?: ((keys: string[]) => void) | null;
175
  /**
176
  * ⭐⭐ W41-T30 - BULK HIDE AND SHOW NEED A PLURAL DOOR, AND THIS IS THE TICKET'S BIGGEST
177
  * MEASURED FINDING. The wave board's premise was that bulk visibility "can be wired for real:
 
192
  * builds `onShowAll` out of `onColumnsVisible(keys: string[])`. Wiring this prop to it is the
193
  * whole of the caller change, and it is outside this ticket's fence.
194
  */
195
+ onSetFieldsHidden?: ((keys: string[], hidden: boolean) => void) | null;
196
  /**
197
  * THE BATCH DELETE DOOR, AND BULK DELETE IS ABSENT WITHOUT IT, ON PURPOSE.
198
  *
 
215
  * offers no bulk delete at all, which is the posture this file already keeps for every other
216
  * handler ("a missing prop makes the action ABSENT, never present-and-inert").
217
  */
218
+ onDeleteFields?: ((keys: string[]) => void) | null;
219
  /**
220
  * ⭐⭐ W40-T17 (owner instruction 15) β€” DOES THIS MOUNT FILE ROWS UNDER "Shared with me" AND
221
  * "Shared with everyone"? Absent means YES, which is the grid's behaviour and every behaviour
 
256
  manager?: boolean;
257
  }
258
 
259
+ /**
260
+ * ⭐⭐ W42-T12 (D-485) β€” THE MANAGER ARM, AND ITS SIX MEMBERS ARE REQUIRED ON PURPOSE.
261
+ *
262
+ * Six optional doors degrade to "the feature does not exist", which reads on screen exactly like
263
+ * "nobody built it" β€” a Fields manager offering Share, Reassign, Hide, Show and Delete over a
264
+ * ticked selection, and doing none of them. That is the defect this arm ends: a mount that says
265
+ * `manager` and then forgets one door does not compile.
266
+ *
267
+ * β›” THE DISCRIMINANT HAS TO BE PASSED, NOT DEFAULTED. `manager` defaults to `sharedSections`
268
+ * below, and TypeScript cannot narrow a union on a runtime default, so the grid's mount states
269
+ * `manager` explicitly. The two permission rooms (`settings/DatabasePermsPane.tsx`,
270
+ * `settings/ModulePermsList.tsx`) pass no `manager` at all and therefore match the plain arm,
271
+ * untouched β€” which is what lets this land without editing a file outside the fence.
272
+ *
273
+ * ⚠ REQUIRED KEY, NULLABLE VALUE, AND THE TWO ARE DIFFERENT PROPERTIES. What D-485 costs is the
274
+ * host that never DECIDED; `| null` still forces the decision to be written down, and a mount
275
+ * that genuinely has no version of an act says so in one greppable word instead of in silence.
276
+ * `null` and absent behave identically in the body below β€” every use is truthiness-guarded β€” so
277
+ * the house posture holds: a door nobody supplied makes the control ABSENT, never inert.
278
+ * `viewer` takes `undefined` rather than `null` because that is the value the grid already holds
279
+ * for "not signed in / not told", and inventing one would invent the rights answer itself.
280
+ */
281
+ export interface FieldsHidePanelManagerProps extends FieldsHidePanelBase {
282
+ manager: true;
283
+ viewer: FieldViewer | undefined;
284
+ onRemoveField: ((key: string) => void) | null;
285
+ onShareFields: ((keys: string[]) => void) | null;
286
+ onReassignFields: ((keys: string[]) => void) | null;
287
+ onSetFieldsHidden: ((keys: string[], hidden: boolean) => void) | null;
288
+ onDeleteFields: ((keys: string[]) => void) | null;
289
+ }
290
+
291
+ /** Every mount that is NOT the field manager: the bulk bar never renders, so the six doors stay
292
+ * as optional as they have always been and an absent one still means the act is ABSENT. */
293
+ export interface FieldsHidePanelPlainProps extends FieldsHidePanelBase {
294
+ manager?: false;
295
+ }
296
+
297
+ export type FieldsHidePanelProps =
298
+ | FieldsHidePanelManagerProps
299
+ | FieldsHidePanelPlainProps;
300
+
301
+ /**
302
+ * ⭐⭐ W42-T38 β€” **A COMPUTED COLUMN WHOSE CONFIGURATION NO LONGER RESOLVES, AND WHY.** Returns the
303
+ * REASON as a finished sentence, or `null` for every ordinary column. Pure and exported, so the
304
+ * answer can be exercised directly instead of being read out of a rendered row: `gridUx.test.ts`
305
+ * already imports this panel under bare node, which is what makes an export here reachable at all.
306
+ *
307
+ * β›”β›” IT NAMES NON-RESOLUTION AND NEVER DELETION, and that is the whole of the wording rule.
308
+ * `fields` is the list the server sent THIS VIEWER: a column narrowed away by a permission rule,
309
+ * a column dropped since this definition was written, and a definition that never pointed
310
+ * anywhere all arrive here as the same absent key. W41-T43 hit this exact fork on the pivot note
311
+ * (`CustomerGrid.tsx`) and refused a cause for the same reason: a sentence naming any one of the
312
+ * three is a false claim on the other two. So every sentence below says what is observable, which
313
+ * is that the table is not offering the column the configuration names.
314
+ *
315
+ * β›” AND IT MARKS A REFERENCE THAT DOES NOT RESOLVE, NEVER A BAG THAT IS ABSENT. A `link` column
316
+ * carrying no `link` bag is UNCONFIGURED, which is a different fact with a different remedy, and
317
+ * the fixture `gridUx.test.ts` renders this panel with is exactly that shape (`customer_link`,
318
+ * typed `link`, no bag) β€” marking it would put new markup inside a row that test reads.
319
+ *
320
+ * ⚠ EVERY READ IS GUARDED, because none of this arrives typed: `type`, `label`, and every key
321
+ * inside the three bags are `string` by declaration and whatever the wire sent in fact. The early
322
+ * return also keeps the cost off the ordinary column, which is all but a handful of them.
323
+ *
324
+ * ⚠ WHAT THIS CANNOT SEE, stated rather than guessed at. Four references resolve against THIS
325
+ * table and are answered here: a formula's `{ref}`s, `rollup.link`, `rollup.source.on` and
326
+ * `link.from`. The rest name things this panel is never passed β€” `rollup.field`, `rollup.sortBy`
327
+ * and the rollup conditions live in the LINKED table; `link.table`, `link.reciprocal` and
328
+ * `link.inverse` name another database; `rollup.source.topic|measure|groupBy` and every key of
329
+ * `link.via` name the governed topic catalogue. Answering those needs a table list and a topic
330
+ * catalogue, and inventing either would be this panel asserting a wall it did not hit.
331
+ *
332
+ * ⚠ NO `selfKey` IS PASSED TO `validateFormula`, deliberately. Its two other refusals (a formula
333
+ * referencing itself, a loop between formulas) are states the WRITE DOOR already refuses, so a
334
+ * chip claiming one on a saved column asserts something unreachable, and the cycle walk it costs
335
+ * would run per column per keystroke to say so.
336
+ */
337
+ export function brokenFieldReason(
338
+ field: PermsField,
339
+ fields: readonly PermsField[]
340
+ ): string | null {
341
+ const formula = typeof field.formula === "string" ? field.formula : "";
342
+ const rollup = field.rollup;
343
+ const link = field.link;
344
+ if (!formula && !rollup && !link) return null;
345
+ const known = new Set<string>();
346
+ for (const f of fields) if (typeof f?.key === "string") known.add(f.key);
347
+ // ⚠ AN ABSENT COLUMN IS QUOTED BY ITS KEY, and there is no softer option: every sentence below
348
+ // that names one has already established the key is not in `fields`, so there is no label
349
+ // anywhere on this payload to borrow. The one branch that HAS the field quotes it by name.
350
+ if (formula) {
351
+ const parsed = parseFormula(formula);
352
+ if (!parsed.ok) return "This formula cannot be read as written, so it computes nothing.";
353
+ const sources = new Map<string, string>();
354
+ for (const f of fields) {
355
+ if (typeof f?.key === "string" && typeof f.formula === "string" && f.formula)
356
+ sources.set(f.key, f.formula);
357
+ }
358
+ const checked = validateFormula(formula, known, sources);
359
+ if (!checked.ok && checked.error)
360
+ return `This formula cannot be resolved: ${checked.error}.`;
361
+ }
362
+ if (rollup) {
363
+ // The READ-THROUGH kind. `source.on` is the column on THIS table whose value matches the group
364
+ // key, and it is the one half of a source rollup this panel can answer for.
365
+ const on = rollup.source?.on;
366
+ if (typeof on === "string" && on && !known.has(on))
367
+ return `This rollup matches on the column "${on}", which this table is not `
368
+ + "offering, so it folds nothing.";
369
+ // The LINK FOLD. Two ways it stops resolving, and they are different facts: the link column is
370
+ // not on this table at all, or it is here and is no longer a link.
371
+ const via = rollup.link;
372
+ if (typeof via === "string" && via) {
373
+ const hit = fields.find((f) => f?.key === via);
374
+ if (!hit)
375
+ return `This rollup folds the link column "${via}", which this table is not `
376
+ + "offering, so it has no records to summarise.";
377
+ if (hit.type !== "link")
378
+ return `This rollup folds "${rowLabelOf(hit)}", which is not a link column any more, so `
379
+ + "it has no records to summarise.";
380
+ }
381
+ }
382
+ if (link) {
383
+ // `from` is the column on THIS table supplying the join value. Absent is not broken: the
384
+ // profile or pinned column is the documented default, so only a NAMED missing one is a fault.
385
+ const from = link.from;
386
+ if (typeof from === "string" && from && !known.has(from))
387
+ return `This link joins on the column "${from}", which this table is not offering, `
388
+ + "so it matches no records.";
389
+ }
390
+ return null;
391
+ }
392
+
393
+ /**
394
+ * ⭐ W42-T38 β€” HOW A ROW IS NAMED, hoisted out of the component so `brokenFieldReason` can quote a
395
+ * column by the name the reader sees without either of them growing a second naming rule. The
396
+ * component's own `rowLabel` is this function, and wave 30's R5 plus W40-T16's metric prefix are
397
+ * still the only two things in it.
398
+ */
399
+ function rowLabelOf(f: PermsField): string {
400
+ return f.isMetric ? metricLabel(fieldLabel(f)) : fieldLabel(f);
401
+ }
402
+
403
+ /**
404
+ * ⭐⭐ W42-T48 (R14) - EDITABILITY IS A BADGE NOW, NOT A SECTION, and this is where that
405
+ * fact moved to. The panel used to answer "who may change this column" BY POSITION: a row
406
+ * sat under "Shared with everyone" because `fieldEditMode(field)` answered `collaborative`.
407
+ * R14 gives the position to OWNERSHIP instead (`fieldSectionOf`), so the same fact now
408
+ * rides the row as a chip and NOTHING about it is lost.
409
+ *
410
+ * β›”β›” THIS IS THE PANEL HALF `verify_map.py`'s `private-by-default-is-anchored` LEG READS.
411
+ * Its subject is unchanged and is worth restating: a route column is stored with
412
+ * `permissions: {edit: "personal"}` and `types.ts::fieldEditMode` falls back to
413
+ * `cleanFieldPermissions(field.permissions, "collaborative")` for a definition carrying no
414
+ * bag at all, so the stamp is what keeps a route reading as private BY RULE rather than by
415
+ * luck. The leg follows that fact HERE rather than dying with the section it used to live in.
416
+ *
417
+ * β›” THE STAMP, NEVER THE FALLBACK, IS WHAT EARNS A CHIP. A definition with no `permissions`
418
+ * bag would take `collaborative` from the fallback, and painting `Collaborative` on every
419
+ * unstamped column in the product would be a claim derived from a default - the same failure
420
+ * C8 refuses for `class`. No bag, no badge; the row then says nothing rather than something
421
+ * wrong.
422
+ */
423
+ export function fieldEditBadge(field: PermsField): { text: string; title: string } | null {
424
+ const bag: unknown = field.permissions;
425
+ if (typeof bag !== "object" || bag === null) return null;
426
+ if (typeof (bag as { edit?: unknown }).edit !== "string") return null;
427
+ const mode = fieldEditMode(field);
428
+ return { text: FIELD_EDIT_LABELS[mode], title: FIELD_EDIT_BLURBS[mode] };
429
+ }
430
+
431
+ /**
432
+ * ⭐ W42-T38 β€” WHAT A PERSON WOULD TYPE FOR A TYPE, as one lower-cased haystack.
433
+ *
434
+ * BOTH the human name and the raw kind, deliberately. `TYPE_LABELS[f.type]` is the word this
435
+ * product shows for the kind β€” the icon's own tooltip on the row two hundred lines below reads it,
436
+ * and so does the column menu β€” so it is what somebody hunting "every currency column" will type.
437
+ * The raw kind is the second spelling the SAME user meets, in a formula's `{ref}` vocabulary, in a
438
+ * saved view's payload and in the API; matching it costs one token and cannot produce a hit the
439
+ * label would not, since every kind is a single lower-case word.
440
+ *
441
+ * ⚠ GUARDED THE WAY `rowLabel` IS, and for the same reported crash: `TYPE_LABELS` is declared
442
+ * `Record<FieldType, string>`, so `tsc` sees a `string` where an off-union wire value gives
443
+ * `undefined`, and `.toLowerCase()` on that is the throw wave 30's R5 fixed for labels.
444
+ */
445
+ function typeTerms(f: PermsField): string {
446
+ const label = TYPE_LABELS[f?.type] ?? "";
447
+ const kind = typeof f?.type === "string" ? f.type : "";
448
+ return `${label} ${kind}`.toLowerCase();
449
+ }
450
+
451
  /**
452
  * The Fields show/hide panel (owner item 7 remainder, wave 2 2026-07-27): a SEARCH box over the
453
  * field list, and a small muted `Pre-set` chip on every Odoo-precomputed field. The chip's
 
457
  * labels say "all", and a narrowed meaning under an active search would be a quiet lie.
458
  */
459
  export function FieldsHidePanel({
460
+ fields: allFields,
461
  hidden,
462
  onToggle,
463
  onHideAll,
 
484
  // already made: swap the two lines and this is `undefined` on every mount.
485
  manager = sharedSections,
486
  }: FieldsHidePanelProps) {
487
+ /**
488
+ * ⭐⭐ WAVE-42 C11 (W42-T54) β€” THE FIELDS MANAGER IS A FIELD PICKER, so it lists the OFFERABLE
489
+ * columns. The prop is shadowed once, here, rather than narrowed at each of the four places
490
+ * below that partition, search, order, tick and render it: this panel derives its list five
491
+ * ways and a filter added to four of them is the fifth one still offering ~64 route columns.
492
+ *
493
+ * β›” PRESENTATION ONLY. Nothing is deleted and nothing is walled: the payload still carries
494
+ * every withheld field, the grid still renders any that are visible, and a route column's own
495
+ * doors (its column menu, `patchRouteOrderField`, `deleteRouteOrderField`) are untouched.
496
+ */
497
+ const fields = useMemo(() => offerableFields(allFields), [allFields]);
498
  /** W41-T27 - one name for "this mount is the Fields manager", so the title, the width class
499
  * and anything a later ticket adds all key off the same answer instead of re-deriving it. */
500
  const managerMode = manager;
 
544
  * A field with no metric flag comes back byte-identical to `fieldLabel(f)` β€” which is what
545
  * keeps the GRID's mount of this panel unchanged, since grid fields never carry the flag.
546
  */
547
+ // ⭐ W42-T38 β€” the rule MOVED to module scope (`rowLabelOf`) and did not change: the broken-field
548
+ // reason quotes a column by the name a reader sees, and a helper outside the component cannot
549
+ // reach a binding declared inside it. This name stays because six call sites below spell it.
550
+ const rowLabel = rowLabelOf;
551
  /**
552
  * ⭐⭐ W41-T30 (contract C2) - EVERY RIGHT THIS PANEL ASKS ABOUT ONE FIELD, ASKED IN ONE
553
  * PLACE, so the ROW and the BULK BAR cannot answer the same question differently.
 
580
  return { fc, presetRefusal, canRemove, deletable, removable, hideable };
581
  };
582
  const q = query.trim().toLowerCase();
583
+ // ⭐⭐ W42-T38 β€” BY LABEL **AND BY TYPE NAME**. "currency" now finds every currency column on a
584
+ // table where none of them says so in its label, which is the search a person actually runs when
585
+ // they are looking for a kind rather than a name. See `typeTerms` for which spellings count and
586
+ // for the guard, which is wave 30's R5 guard applied to the second field this line now reads.
587
+ // ⚠ `shown` STILL FEEDS THE SECTIONS AND NOTHING ELSE. Show all / Hide all keep acting on
588
+ // `fields` (see this function's own doc comment): their labels say "all", and a wider search
589
+ // must not quietly widen or narrow what a bulk button touches.
590
+ const shown = q
591
+ ? fields.filter((f) => rowLabel(f).toLowerCase().includes(q) || typeTerms(f).includes(q))
592
+ : fields;
593
  /**
594
  * ⭐⭐ W40-T17 (owner instruction 15) β€” TWO MOUNTS, TWO QUESTIONS, ONE PANEL.
595
  *
596
  * The GRID asks "whose column is this?" and answers it with three sections, because a person
597
+ * looking at their own table needs to tell their columns from their colleagues' and from the
598
+ * tenant's. The PERMISSION EDITOR asks "which columns may an admin set a rule on?", and AM-2
599
+ * answers that with `metric || !custom` β€” the database's own pre-set columns, plus every bound
600
+ * measure. They are not the same list narrowed; they are different questions with different
601
+ * answers.
602
+ *
603
+ * ⭐⭐ W42-T48 (R14) β€” AND THE THREE SECTIONS ARE CUT ON OWNERSHIP, not on who may edit.
604
+ * `My fields` / `From my colleagues` / `Built in`, decided by `fieldClass::fieldSectionOf`,
605
+ * which is C1/C10's `class` first and the shipped stratum stamps (`custom`, `shared`,
606
+ * `createdBy`) as the C8 fallback while the server half is late. What LEFT the layout is
607
+ * `fieldEditMode`: who may CHANGE a column and who may SEE it are BADGES on the row now
608
+ * (`fieldEditBadge`, `audienceBadge`), so neither fact is lost and neither one decides where a
609
+ * row sits. A colleague's route column therefore reads as theirs, with their name on the row,
610
+ * instead of sitting untitled at the top because its stamp happened to say `personal`.
611
  *
612
+ * β›” THE TWO-MOUNT SEAM IS UNTOUCHED BY THAT RE-CUT. `sharedSections` still declares the
613
+ * question, still defaults to true so the grid needs no edit, and still selects between the
614
+ * wide arm and AM-2's narrow one. `verify_ui.py::hide_panel_is_mount_scoped` checks each of
615
+ * those separately and every one of them is still correct after R14.
616
+ *
617
+ * β›” THE MEMBERSHIP IS A PURE, EXPORTED FUNCTION AND THAT IS DELIBERATE. Nobody can click this
618
+ * panel on a branch whose store is tenant #0's production data, so the sectioning has to be
619
+ * executable directly, on a hand-built field, without React and without a server.
620
  *
621
  * ⚠ THE NARROW ARM RENDERS ONE UNTITLED SECTION, which is what the first section has always
622
+ * been. `section.title` is falsy there, so the rows sit directly under the search box exactly
623
+ * as they do in the two permission rooms today.
624
  */
625
  const sections = sharedSections
626
  ? [
627
+ { key: "mine", title: FIELD_SECTION_TITLES.mine,
628
+ fields: shown.filter((field) => fieldSectionOf(field, viewer) === "mine") },
629
+ { key: "colleagues", title: FIELD_SECTION_TITLES.colleagues,
630
+ fields: shown.filter((field) => fieldSectionOf(field, viewer) === "colleagues") },
631
+ { key: "builtin", title: FIELD_SECTION_TITLES.builtin,
632
+ fields: shown.filter((field) => fieldSectionOf(field, viewer) === "builtin") },
633
  ]
634
  : [{ key: "personal", title: "", fields: presetHideFields(shown) }];
635
  /**
 
795
  onChange={(e) => setQuery(e.target.value)}
796
  />
797
  <div className="cg-pop-list">
798
+ {/* ⭐⭐ W42-T48 (R14) - AN EMPTY SECTION DOES NOT RENDER ITS HEADING. Three titled
799
+ sections where one used to be untitled means the common account, with no columns of
800
+ its own and none from a colleague, would open this panel on two empty headings and
801
+ have to scroll past them to reach the rows. The heading earns its line by having
802
+ something under it.
803
+ ⚠ THE PANEL-WIDE EMPTY STATE IS A DIFFERENT QUESTION and is untouched: it asks
804
+ whether EVERY section is empty, which is the search-matched-nothing case. */}
805
+ {sections.filter((section) => section.fields.length > 0).map((section) => (
806
  <div key={section.key} className="cg-fields-section">
807
  {section.title && <div className="cg-fields-section-title">{section.title}</div>}
808
  {section.fields.map((f) => {
 
826
  // `fieldRights` above). The row used to derive C2's terms inline, where no
827
  // footer button could reach them.
828
  const rights = fieldRights(f);
829
+ /** ⭐⭐ W42-T38 β€” the reason this computed column resolves against nothing, or null for
830
+ * every ordinary one. Asked here, per row, from the SAME `fields` list the panel is
831
+ * rendering: `shown` is a search narrowing and would make the mark blink on and off as
832
+ * a query hid the very column a rollup reads. */
833
+ const brokenReason = brokenFieldReason(f, fields);
834
  const fc = rights.fc;
835
  const originText = fc && originBadge(fc);
836
  const audienceText = fc && audienceBadge(fc);
837
  const valuesText = fc && valuesBadge(fc);
838
  const shareTitle = fc && shareMarkTitle(fc);
839
+ // ⭐⭐ W42-T48 (R14, R16) - THE THREE FACTS THE SECTION NO LONGER CARRIES.
840
+ // `authorBadge` is the name on a colleague's row, worded by which fact was read
841
+ // (`Shared by` off C1, `Added by` off the `createdBy` stamp); `editBadge` is the
842
+ // editability stamp that used to decide the section; `supersededNote` is R16's
843
+ // sentence, which paints nothing until a producer marks the collision (see
844
+ // `supersededNoteOf`, and the handoff, for the wire key nobody sends yet).
845
+ const authorBadge = fieldAuthorBadge(f, viewer);
846
+ const editBadge = fieldEditBadge(f);
847
+ const supersededNote = supersededNoteOf(f);
848
  // ⭐⭐ W41-T28 (R3, R8) - WHERE THIS FIELD IS USED, read off C8's `usage`
849
  // block and NEVER counted here. This component can see one user's field list
850
  // and nothing else: not the other users' saved views, not the automations, not
 
1072
  vocabulary is learned. */}
1073
  <FieldTypeIcon type={f.type} title={TYPE_LABELS[f.type]} />
1074
  <span className="cg-check-label">{rowLabel(f)}</span>
1075
+ {/* ⭐⭐ W42-T38 β€” THE BROKEN COMPUTED COLUMN SAYS SO, AND SAYS WHY. A mark plus a
1076
+ tooltip, never a sentence laid across the row (DESIGN Β§4) β€” the same shape the
1077
+ share mark above uses, so a list of forty columns does not become forty
1078
+ paragraphs. The chip word is the JUDGEMENT and the title is the REASON, which is
1079
+ what makes the mark worth trusting: "Broken" on its own is the kind of badge a
1080
+ reader learns to ignore.
1081
+ ⚠ `aria-label` CARRIES THE REASON, not the word. A tooltip is a hover, and a
1082
+ reader who cannot hover would otherwise get the judgement with none of the
1083
+ evidence behind it.
1084
+ β›” THE SENTENCE IS `brokenFieldReason`'s AND IS COMPOSED NOWHERE ELSE, so the one
1085
+ place that knows which reference failed is the one place that words it. */}
1086
+ {brokenReason && (
1087
+ <span
1088
+ className="cg-preset-tag cg-field-broken"
1089
+ role="img"
1090
+ aria-label={brokenReason}
1091
+ title={brokenReason}
1092
+ >
1093
+ Broken
1094
+ </span>
1095
+ )}
1096
  {/* ⭐ OWNER ITEM 3 (2026-08-06): *"it doesn't show pre-set when I hide fields just
1097
  like how Odoo fields are. This is always the standard label."* Right β€” the chip
1098
  asked `source === "odoo"`, so a column an AUTOMATION fills (source `overlay`)
 
1131
  {audienceText && (
1132
  <span className="cg-preset-tag cg-field-audience">{audienceText}</span>
1133
  )}
1134
+ {/* ⭐⭐ W42-T48 (R14) - WHOSE COLUMN THIS IS, ON THE ROW. The section already
1135
+ says a colleague put it in your list; the row says WHICH colleague, which is
1136
+ the half a section title cannot carry. Rendered only under `From my
1137
+ colleagues`, because a name on your own row would be chrome. */}
1138
+ {authorBadge && (
1139
+ <span className="cg-preset-tag cg-field-author" title={authorBadge.title}>
1140
+ {authorBadge.text}
1141
+ </span>
1142
+ )}
1143
+ {/* ⭐⭐ W42-T48 (R14) - EDITABILITY, AS A BADGE. This is the fact that used to
1144
+ BE the section ("Shared with everyone" was `fieldEditMode` answering
1145
+ `collaborative`). It is a chip now, it reads the STAMP and never the fallback,
1146
+ and the blurb under `title` is the same sentence the column menu shows. */}
1147
+ {editBadge && (
1148
+ <span className="cg-preset-tag cg-field-edit" title={editBadge.title}>
1149
+ {editBadge.text}
1150
+ </span>
1151
+ )}
1152
+ {/* β›” W42-T48 (R16) - THE SUPERSEDED LOCAL COLUMN SAYS SO. Null on every field
1153
+ on today's wire, by C8: no producer marks a key collision yet, and inventing
1154
+ the state client side would be asserting a second definition the server never
1155
+ sent. The reader is here so the sentence lands the day one does. */}
1156
+ {supersededNote && (
1157
+ <span className="cg-preset-tag cg-field-superseded" title={supersededNote}>
1158
+ Superseded
1159
+ </span>
1160
+ )}
1161
  {/* ⭐⭐ W41-T27 (owner instruction 8) β€” THE HOVER CHIP. A shared row carries a small
1162
  share mark whose title names WHO shared it and to whom. A mark and a tooltip,
1163
  never a sentence on the row (DESIGN Β§4); inline SVG in the house vocabulary,
web/src/filter-kit/fieldClass.ts CHANGED
@@ -710,3 +710,182 @@ export const PRESET_DESCRIPTION_ONLY_HINT =
710
 
711
  /** R19's undo, in the words the rest of the product uses for the same act. */
712
  export const DESCRIPTION_RESET_LABEL = "Reset to default";
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
710
 
711
  /** R19's undo, in the words the rest of the product uses for the same act. */
712
  export const DESCRIPTION_RESET_LABEL = "Reset to default";
713
+
714
+ // ---------------------------------------------------------------------------
715
+ // W42-T48 (R14, R15, R16 / contract C10) - WHOSE FIELD IS THIS, and it is the
716
+ // question the Fields panel now sections on.
717
+ //
718
+ // R14 re-cuts the panel's three sections on OWNERSHIP: `My fields`, `From my
719
+ // colleagues`, `Built in`. What a section NEVER says again is who may SEE the
720
+ // column or who may CHANGE it: those two are BADGES on the row (`audienceBadge`
721
+ // above, and the panel's own edit-stamp badge), because a person reading their
722
+ // field list is asking "is this mine" first and "who else sees it" second, and
723
+ // one list cannot answer both by position.
724
+ //
725
+ // β›” ONE PRODUCER, THEN ONE C8 FALLBACK, IN THAT ORDER. C1/C10's `class` is the
726
+ // authority the moment it answers; while it is absent this reads the SHIPPED
727
+ // stratum stamps (`custom`, `shared`, `createdBy`) and nothing else. That is
728
+ // exactly the shape W41-T27 sanctioned for the origin badge, where
729
+ // `isPresetField` answers only while `class` is absent. It is NOT a defaulted
730
+ // class: no origin, audience or values is invented for a field the server has
731
+ // not classified, and every badge those three drive still paints nothing.
732
+ //
733
+ // ⚠ THE VIEWER IS THE MISSING HALF AND IT IS SAID OUT LOUD RATHER THAN GUESSED.
734
+ // No mount passes `viewer` today (`customer-grid/Toolbar.tsx`,
735
+ // `settings/DatabasePermsPane.tsx`, `settings/ModulePermsList.tsx` all pass
736
+ // none, and all three are outside this ticket's fence). With no viewer, "is
737
+ // this author me?" has no answer, so a definition read from the TENANT-WIDE
738
+ // stratum and stamped with a person's name files under `From my colleagues`.
739
+ // That is the honest reading of "somebody put this in my list" without an
740
+ // identity to compare against; wire one mount's `viewer` and the same function
741
+ // files that person's own shared column back under `My fields` with no other
742
+ // change. Stated, not papered over.
743
+ //
744
+ // STILL NO RUNTIME IMPORTS (see this file's header): the stratum stamps are
745
+ // read STRUCTURALLY off an `unknown`, exactly as `fieldClassOf` reads `class`.
746
+ // ---------------------------------------------------------------------------
747
+
748
+ /** R14's three sections, as keys. The titles are `FIELD_SECTION_TITLES`. */
749
+ export const FIELD_SECTIONS = ["mine", "colleagues", "builtin"] as const;
750
+ export type FieldSection = (typeof FIELD_SECTIONS)[number];
751
+
752
+ /**
753
+ * The words on screen. Sentence case, DESIGN section 2 (no ALL-CAPS chrome),
754
+ * and no em dash or en dash anywhere in them (standing rule 2).
755
+ */
756
+ export const FIELD_SECTION_TITLES: Record<FieldSection, string> = {
757
+ mine: "My fields",
758
+ colleagues: "From my colleagues",
759
+ builtin: "Built in",
760
+ };
761
+
762
+ /** Where a name may come from, so a caller can word the row honestly. */
763
+ export interface FieldAuthor {
764
+ name: string;
765
+ /** `owner` and `sharedBy` are C1's; `createdBy` is the C8 fallback stamp. */
766
+ from: "owner" | "sharedBy" | "createdBy";
767
+ }
768
+
769
+ /**
770
+ * WHO PUT THIS COLUMN HERE, or nothing.
771
+ *
772
+ * β›” THE SOURCE TRAVELS WITH THE NAME, because the three do not mean the same
773
+ * thing and the row must not claim one while reading another. W41-T27 refused
774
+ * `field.createdBy` as a producer of the OWNER badge and that refusal stands:
775
+ * C1 derives `owner` from grants plus the shared stratum, and the two disagree
776
+ * on a transferred, an admin-seeded or a shared-values column. What this adds
777
+ * is a DIFFERENT claim with its own word: while `class` is absent, `createdBy`
778
+ * says who CREATED the definition, which is all the row then asserts.
779
+ */
780
+ export function fieldAuthorOf(field: unknown): FieldAuthor | null {
781
+ const fc = fieldClassOf(field);
782
+ if (fc) {
783
+ if (fc.owner) return { name: fc.owner, from: "owner" };
784
+ if (fc.sharedBy) return { name: fc.sharedBy, from: "sharedBy" };
785
+ return null;
786
+ }
787
+ if (typeof field !== "object" || field === null) return null;
788
+ const made = nameOrNull((field as { createdBy?: unknown }).createdBy);
789
+ return made ? { name: made, from: "createdBy" } : null;
790
+ }
791
+
792
+ /** Was this definition read from the TENANT-WIDE stratum rather than yours? */
793
+ function fromSharedStratum(field: unknown, fc: FieldClass | null): boolean {
794
+ if (fc) return fc.audience !== "private";
795
+ if (typeof field !== "object" || field === null) return false;
796
+ return (field as { shared?: unknown }).shared === true;
797
+ }
798
+
799
+ /**
800
+ * ⭐⭐ R14 IN ONE PURE FUNCTION, exported so it can be executed directly rather
801
+ * than inferred from a screenshot nobody can take on this branch.
802
+ *
803
+ * The order of the branches IS the rule:
804
+ * 1. C1 says the platform made the column, and that beats every stamp below.
805
+ * 2. a named author who IS this viewer: yours, wherever it lives.
806
+ * 3. a named author on a definition read from the tenant-wide stratum:
807
+ * somebody else put it in your list. A route column is this case
808
+ * (`shared: true`, stamped with the person who solved the route), which
809
+ * is why a colleague's route reads as theirs rather than as the
810
+ * database's own.
811
+ * 4. an overlay column created from the table UI lives in YOUR workspace
812
+ * document, so it is yours even with no name on it.
813
+ * 5. a named author with no stratum stamp is still a person's column.
814
+ * 6. nobody authored it and you did not add it: the database's own.
815
+ *
816
+ * β›” A NULL `class` NEVER LANDS A ROW NOWHERE. Every field the panel holds is
817
+ * placed by branch 3, 4, 5 or 6 off the shipped stamps, so today's wire renders
818
+ * a complete list: custom columns under `My fields`, shared columns carrying a
819
+ * creator under `From my colleagues`, and the database's own contract columns
820
+ * under `Built in`. The C10 half only makes the same answer authoritative.
821
+ */
822
+ export function fieldSectionOf(
823
+ field: unknown,
824
+ viewer?: FieldViewer | null
825
+ ): FieldSection {
826
+ const fc = fieldClassOf(field);
827
+ if (fc && fc.origin === "preset") return "builtin";
828
+ const author = fieldAuthorOf(field);
829
+ if (author && sameUser(author.name, viewer?.name)) return "mine";
830
+ if (author && fromSharedStratum(field, fc)) return "colleagues";
831
+ if (typeof field === "object" && field !== null
832
+ && (field as { custom?: unknown }).custom === true) return "mine";
833
+ if (author) return "colleagues";
834
+ return "builtin";
835
+ }
836
+
837
+ /**
838
+ * THE NAME ON THE ROW, in the ONE case where nothing else on the row carries it.
839
+ *
840
+ * β›”β›” NEVER BESIDE A C1 CHIP THAT ALREADY SAYS IT, which is the whole of the
841
+ * guard below. The moment `class` ships, the row already names the person twice
842
+ * over: `audienceBadge` renders `Shared by Karen` for an `audience: "users"`
843
+ * column, and the panel's own `cg-field-owner` chip renders `class.owner`
844
+ * verbatim. A third chip repeating that name is what "nothing else derives a
845
+ * badge independently" looks like on screen, and it would appear on the exact
846
+ * deployed build this ticket is observed against rather than on this branch.
847
+ *
848
+ * So this fires ONLY on the C8 fallback: no `class`, no C1 chip, nobody named,
849
+ * and a `createdBy` stamp that says who CREATED the definition. `Added by` is
850
+ * that weaker claim worded as itself, never as an ownership or a share claim.
851
+ * Null on your own rows and on the database's own columns, where there is no
852
+ * whose to name.
853
+ */
854
+ export function fieldAuthorBadge(
855
+ field: unknown,
856
+ viewer?: FieldViewer | null
857
+ ): { text: string; title: string } | null {
858
+ if (fieldSectionOf(field, viewer) !== "colleagues") return null;
859
+ const author = fieldAuthorOf(field);
860
+ if (!author || author.from !== "createdBy") return null;
861
+ return { text: `Added by ${author.name}`, title: "Who created this column" };
862
+ }
863
+
864
+ /**
865
+ * β›”β›” R16, AND THE PAYLOAD CANNOT EXPRESS IT YET. The ruling: a SHARED
866
+ * definition wins a key collision, the local one is superseded rather than
867
+ * deleted, and the field manager says so. The first two halves are real
868
+ * server-side facts (`core.field_permissions.migrate_legacy_fields` re-promotes
869
+ * a per-user fork of a key on every read, and `routes_tables`' delete door
870
+ * clears both strata precisely because a fork survives), but NOTHING ON THE
871
+ * WIRE MARKS THE ROW: `routes_customers._merge_shared_fields` skips a shared
872
+ * definition whose key the canonical contract already declares (`if k in have:
873
+ * continue`) and `routes_tables`' field index is deduped first writer wins, so
874
+ * the client receives exactly one entry per key and no record that a second one
875
+ * exists.
876
+ *
877
+ * So this is a C8 READER, not an invented state: it returns the sentence when a
878
+ * producer ships `supersededLocal: true` on the entry, and null on every field
879
+ * today, which paints nothing. The missing half is named in the handoff rather
880
+ * than guessed at here, because the only client-side alternative would be to
881
+ * decide a collision happened from a key the server never sent.
882
+ */
883
+ export const SUPERSEDED_NOTE =
884
+ "Superseded: the shared version of this column is the one in use, and your own copy is kept rather than deleted.";
885
+
886
+ export function supersededNoteOf(field: unknown): string | null {
887
+ if (typeof field !== "object" || field === null) return null;
888
+ return (field as { supersededLocal?: unknown }).supersededLocal === true
889
+ ? SUPERSEDED_NOTE
890
+ : null;
891
+ }
web/src/index.css CHANGED
@@ -12,6 +12,14 @@
12
  @import "./styles/wave41/rail-nav.css";
13
  @import "./styles/wave41/relational.css";
14
  @import "./styles/wave41/map.css";
 
 
 
 
 
 
 
 
15
 
16
  @font-face {
17
  font-family: "Inter";
@@ -1299,7 +1307,15 @@ body {
1299
  the owner's "the Route one is the only one with smaller font". The row now declares the SAME
1300
  size the controls in it use, so a control written with `font: inherit` lands on it by
1301
  construction rather than by being told twice. */
1302
- .cg-map-settings {
 
 
 
 
 
 
 
 
1303
  flex: 0 0 auto;
1304
  min-height: 40px;
1305
  display: flex;
@@ -1313,7 +1329,8 @@ body {
1313
  font-size: var(--lp-fs-xs);
1314
  line-height: 1.3;
1315
  }
1316
- .cg-map-settings-label {
 
1317
  margin-right: 2px;
1318
  font-weight: 600;
1319
  letter-spacing: 0.02em;
@@ -5701,8 +5718,14 @@ a.cg-map-ctl-b { text-decoration: none; }
5701
  measured numbers on `padding` below. */
5702
  gap: 8px;
5703
  min-width: 0;
5704
- /* the disclosure chevron is positioned against this box */
5705
- position: relative;
 
 
 
 
 
 
5706
  border: none;
5707
  background: transparent;
5708
  font: inherit;
@@ -5734,18 +5757,15 @@ a.cg-map-ctl-b { text-decoration: none; }
5734
  cursor: pointer;
5735
  }
5736
  .cg-fold-toggle:hover { background: var(--lp-blue-tint); color: var(--lp-ink); }
5737
- .cg-fold-chev {
5738
- position: absolute;
5739
- left: -8px;
5740
- top: 50%;
5741
- transform: translateY(-50%);
5742
- transition: transform 0.12s ease;
5743
- font-size: var(--lp-fs-4xs);
5744
- }
5745
- /* ⚠ the translate MUST be repeated, not appended: `transform` is ONE property, so a bare
5746
- `rotate(-90deg)` here would drop the centring and the collapsed chevron would jump half its
5747
- own height. Measured both states in the harness. */
5748
- .cg-fold-chev.is-shut { transform: translateY(-50%) rotate(-90deg); }
5749
  .cg-fold-name {
5750
  flex: 1 1 auto;
5751
  overflow: hidden;
 
12
  @import "./styles/wave41/rail-nav.css";
13
  @import "./styles/wave41/relational.css";
14
  @import "./styles/wave41/map.css";
15
+ /* ⭐ WAVE 42 lane stylesheets, landed EMPTY in the baseline commit for the same reason wave 41's
16
+ were: index.css is the single worst coupler on a parallel plan, so a lane gets its own sheet and
17
+ never opens this file. β›” THE ONE EXCEPTION IS LANE D and it is deliberate: owner instruction 11
18
+ moves Calendar's controls to a second row, and that rule must sit BESIDE `.cg-map-settings` here
19
+ to inherit its spacing -- an @imported sheet loses every equal-specificity fight with this one. */
20
+ @import "./styles/wave42/hop-editor.css";
21
+ @import "./styles/wave42/rail-views.css";
22
+ @import "./styles/wave42/route-nav.css";
23
 
24
  @font-face {
25
  font-family: "Inter";
 
1307
  the owner's "the Route one is the only one with smaller font". The row now declares the SAME
1308
  size the controls in it use, so a control written with `font: inherit` lands on it by
1309
  construction rather than by being told twice. */
1310
+ /* ⭐⭐ W42-T19 (owner instruction 11) β€” CALENDAR'S SECOND ROW SHARES THIS RULE RATHER THAN COPYING
1311
+ IT. `.cg-cal-settings` is a selector added to Map's own declaration block, not a duplicate set of
1312
+ values beside it, so the two rows cannot drift: one change moves both. The owner asked for
1313
+ "exactly how Time-series and Map view has it", and identical-by-construction is the only spelling
1314
+ of that which survives a later spacing tweak.
1315
+ ⚠ `.cg-cal-bar` is NOT this and must not be reused: it is the month navigator INSIDE `.cg-calview`
1316
+ (see its rule further down), a different row in a different box. */
1317
+ .cg-map-settings,
1318
+ .cg-cal-settings {
1319
  flex: 0 0 auto;
1320
  min-height: 40px;
1321
  display: flex;
 
1329
  font-size: var(--lp-fs-xs);
1330
  line-height: 1.3;
1331
  }
1332
+ .cg-map-settings-label,
1333
+ .cg-cal-settings-label {
1334
  margin-right: 2px;
1335
  font-weight: 600;
1336
  letter-spacing: 0.02em;
 
5718
  measured numbers on `padding` below. */
5719
  gap: 8px;
5720
  min-width: 0;
5721
+ /* ⭐ W42-T43 / R12.2 β€” `position: relative` REMOVED WITH THE CHEVRON IT ANCHORED. Its comment
5722
+ read "the disclosure chevron is positioned against this box", and `.cg-fold-chev` was the ONLY
5723
+ absolutely-positioned descendant of this button (checked: the three rules naming
5724
+ `.cg-fold-toggle` are this one, `:hover`, and `.cg-folder-mark`, which is `flex: 0 0 auto`).
5725
+ With the chevron gone it anchored nothing and created a stacking context nothing used.
5726
+ β›” The comment goes WITH it rather than being left behind: a comment naming a deleted element
5727
+ is a tombstone that reads as intent, which is how T43's own ticket came to call this button
5728
+ "the twisty" when it is the folder header. */
5729
  border: none;
5730
  background: transparent;
5731
  font: inherit;
 
5757
  cursor: pointer;
5758
  }
5759
  .cg-fold-toggle:hover { background: var(--lp-blue-tint); color: var(--lp-ink); }
5760
+ /* ⭐⭐ W42-T43 / R12.2 β€” `.cg-fold-chev` AND `.cg-fold-chev.is-shut` ARE DELETED. The disclosure
5761
+ chevron is gone: R12 replaced expand/collapse with a PATH, so `.cg-fold-toggle` is now the DRILL
5762
+ button and there is no open/shut state left to rotate. Lane C removed the `<span>` and the whole
5763
+ `opened`/`collapsed` machinery from `ViewSidebar.tsx` (commit `7f6a1c0`); this is the CSS half of
5764
+ that one change, landed second by ruling so the rule never outlives its markup.
5765
+ ⭐ THE MEASURED INDENT FIX ABOVE IS UNAFFECTED, and that is a fact about the box model rather
5766
+ than care taken: the chevron was `position: absolute; left: -8px`, i.e. already OUT OF FLOW, so
5767
+ removing it moves the folder mark and the name by ZERO pixels and the `7 + 2 + 8 = 17px`
5768
+ arithmetic in `.cg-fold-toggle`'s padding still holds. */
 
 
 
5769
  .cg-fold-name {
5770
  flex: 1 1 auto;
5771
  overflow: hidden;
web/src/shell/NavExtras.tsx CHANGED
@@ -735,9 +735,8 @@ export function CreateNewRow({
735
  export function FolderHead({
736
  folder,
737
  count,
738
- open,
739
  collapsed,
740
- onToggle,
741
  onRename,
742
  onDelete,
743
  isDrop,
@@ -748,9 +747,18 @@ export function FolderHead({
748
  /* β›” WAVE 35 Β· T07 (owner item 9) β€” the `important?: NavImportant` prop is DELETED. It carried
749
  wave-34 R1's per-folder SUM of mark-important numbers; item 9 retires that badge, and `tsc`'s
750
  unused-locals check is what named this prop the moment its only reader went. */
751
- open: boolean;
 
 
 
 
 
 
 
752
  collapsed: boolean;
753
- onToggle: () => void;
 
 
754
  onRename: (name: string) => void;
755
  onDelete: () => void;
756
  /** Wave 14 C-NAVFOLD β€” a database row is being dragged over this folder. */
@@ -777,13 +785,16 @@ export function FolderHead({
777
  className={"shell-nav-folder" + (isDrop ? " is-drop" : "")}
778
  {...(dropProps ?? {})}
779
  >
780
- {/* R3: no chevron β€” the Views-rail folder look. Open state reads from the members
781
- below it (and aria-expanded says it aloud); the mark + bold label ARE the row. */}
 
 
 
782
  <button
783
  type="button"
784
  className="shell-nav-folderbtn"
785
- aria-expanded={open}
786
- onClick={onToggle}
787
  >
788
  <FolderIcon />
789
  <span className="shell-nav-label">{folder.name}</span>
 
735
  export function FolderHead({
736
  folder,
737
  count,
 
738
  collapsed,
739
+ onOpen,
740
  onRename,
741
  onDelete,
742
  isDrop,
 
747
  /* β›” WAVE 35 Β· T07 (owner item 9) β€” the `important?: NavImportant` prop is DELETED. It carried
748
  wave-34 R1's per-folder SUM of mark-important numbers; item 9 retires that badge, and `tsc`'s
749
  unused-locals check is what named this prop the moment its only reader went. */
750
+ /* β›”β›” W42-T42 (ruling R12.2) β€” `open` and `onToggle` are DELETED, and so is the
751
+ `aria-expanded` they fed. A nav folder no longer expands in place: it is a step on a path, and
752
+ pressing it walks INTO it. Announcing an expanded or collapsed state for a list that has
753
+ neither is the wrong sentence read aloud, and the views half of the rail (W42-T43) removed the
754
+ same line, so the two folder systems now read the same way to a screen reader. R12 exists to
755
+ end that difference.
756
+ ⚠ `collapsed` IS A DIFFERENT QUESTION AND IT STAYS. It asks whether the RAIL is folded to its
757
+ narrow strip, not whether this folder is shut, and it was never part of the expand state. */
758
  collapsed: boolean;
759
+ /** Walk into this folder. Named for the walk rather than reusing `onToggle`, so a reader cannot
760
+ * mistake a drill for a state flip that no longer exists. */
761
+ onOpen: () => void;
762
  onRename: (name: string) => void;
763
  onDelete: () => void;
764
  /** Wave 14 C-NAVFOLD β€” a database row is being dragged over this folder. */
 
785
  className={"shell-nav-folder" + (isDrop ? " is-drop" : "")}
786
  {...(dropProps ?? {})}
787
  >
788
+ {/* R3: no chevron β€” the Views-rail folder look; the mark + bold label ARE the row.
789
+ ⭐ W42-T42 (R12.2) β€” and no twisty was ever drawn here, so there is nothing left to
790
+ remove: what went is the expand STATE behind it. The accessible name says what the press
791
+ does, in the same words the views rail uses, because one gesture read aloud two ways is
792
+ the difference R12 is closing. */}
793
  <button
794
  type="button"
795
  className="shell-nav-folderbtn"
796
+ aria-label={`Open folder ${folder.name}`}
797
+ onClick={onOpen}
798
  >
799
  <FolderIcon />
800
  <span className="shell-nav-label">{folder.name}</span>
web/src/shell/ShareDialog.tsx CHANGED
@@ -66,6 +66,78 @@ const ROLE_BLURB: Record<ShareKind, Record<ShareRole, string>> = {
66
  },
67
  };
68
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
69
  export default function ShareDialog({
70
  kind,
71
  id,
@@ -100,6 +172,10 @@ export default function ShareDialog({
100
  const [busy, setBusy] = useState(false);
101
  const [pick, setPick] = useState("");
102
  const [pickRole, setPickRole] = useState<ShareRole>("view");
 
 
 
 
103
 
104
  const path = `${API_V1}/share/${encodeURIComponent(kind)}/${encodeURIComponent(id)}`;
105
 
@@ -171,6 +247,10 @@ export default function ShareDialog({
171
  const body = (await res.json().catch(() => null)) as
172
  | { error?: { message?: string } }
173
  | null;
 
 
 
 
174
  setError(
175
  res.status >= 500
176
  ? "Something went wrong on our side. Try again in a moment."
@@ -190,6 +270,11 @@ export default function ShareDialog({
190
  // promote anybody, and this line must never be the reason it looks like it can.
191
  const saved = parseShare({ ...(body as object), mayAdminister: true });
192
  setEntries(saved.entries);
 
 
 
 
 
193
  return true;
194
  } catch {
195
  setError("Cannot reach the server.");
@@ -242,10 +327,20 @@ export default function ShareDialog({
242
  : "Sharing never widens past this workspace: everyone here can already open the surface it lives on."}
243
  </p>
244
  {kind === "view" ? (
245
- <p className="shell-share-note">
246
- View access is the general rule. A field's own Share field access takes precedence, so
247
- a field shared as Can view stays read-only even inside an editable view.
248
- </p>
 
 
 
 
 
 
 
 
 
 
249
  ) : kind === "field" ? (
250
  <p className="shell-share-note">
251
  Field access takes precedence over the view. Can view keeps values and field settings
@@ -266,6 +361,31 @@ export default function ShareDialog({
266
  one-line answer above it, since the fact that changes everything
267
  ("Everyone can edit") is the one a list of rows buries. */}
268
  <p className="shell-share-summary">{shareSummary(entries)}</p>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
269
  <div className="shell-share-list">
270
  {state.owner ? (
271
  <div className="shell-share-row is-owner">
 
66
  },
67
  };
68
 
69
+ /**
70
+ * ⭐⭐ W42-T26 (owner instruction 8, R9, contract C7) β€” THE SHARER IS TOLD WHICH FIELDS TRAVEL.
71
+ * Sharing a view grants every field the view NAMES, and until this landed the dialog said nothing
72
+ * about fields at all. The trap the ticket names: T25 makes the behaviour correct and nothing on
73
+ * screen changes, so the disclosure is the half that gets dropped.
74
+ *
75
+ * β›” THESE ARE CONSTANTS, NOT INLINE JSX TEXT, FOR TWO REASONS. (1) `verify_prose`'s JSX pass skips
76
+ * any run containing a newline [[web-prose-blind-to-wrapped-jsx]], and this file's own comments
77
+ * record that blind spot twice; a `const` string literal is seen by the gate whatever prettier does
78
+ * to the markup around it. (2) `wiring_rows/wave42_g.py` pins this copy by regex, and a regex
79
+ * cannot span a JSX line wrap. Standing rule 2: no em dash and no en dash below.
80
+ */
81
+ const VIEW_FIELD_TRAVEL =
82
+ "Sharing a view also shares the fields it uses: the columns it shows, and the columns it groups by, colors by and sorts by.";
83
+ /** ⚠ ITS OWN SENTENCE ON PURPOSE, and the non-obvious half of the disclosure. A sharer reasons
84
+ * about the columns they can SEE; a condition may name one they never put on screen, and the
85
+ * grant covers it all the same. The done-when calls this clause out separately, so it has to be
86
+ * readable on its own rather than being a word inside a list.
87
+ * β›” Do NOT restate the literal below in prose here: `wave42_g.py` pins it, and the WIRINGS loop
88
+ * matches raw file text (comments included), so a paraphrase close enough to match would let the
89
+ * row pass off its own explanation. */
90
+ const VIEW_FILTER_FIELDS =
91
+ "The filters count too. A filter can test a column that is not on screen, and sharing this view hands that column over as well.";
92
+ /** ⚠ The grant is TOPIC-WIDE by construction (C7), so the dialog has to say so in the reader's
93
+ * terms rather than let them assume it stops at this view. */
94
+ const VIEW_FIELD_TOPIC_WIDE =
95
+ "Each of those fields then shows on every view of this database, not only on this one.";
96
+ const SHARED_FIELDS_LEAD = "Fields shared with this view:";
97
+ const REFUSED_FIELDS_LEAD = "These fields could not be included:";
98
+
99
+ /** One field the server named in its answer, with the reason it gave for refusing it. */
100
+ type FieldNote = { key: string; reason: string };
101
+
102
+ /**
103
+ * `sharedFieldKeys` / `refusedFieldKeys` off the RAW PUT body, normalised.
104
+ *
105
+ * β›” BOTH KEYS ARE OPTIONAL AND ABSENT TODAY. C7 splits this feature across two lanes and the
106
+ * server half is not this fence; a grep for either name has zero code hits at the time of writing.
107
+ * So the contract here is: render NOTHING when the key is missing or unusable, never throw, and
108
+ * light up unchanged the moment the server starts answering. `shareModel.parseShare` cannot carry
109
+ * these (it builds a new object with five fixed keys and drops the rest) and is out of fence, so
110
+ * the raw body is the door.
111
+ *
112
+ * ⚠ The shape is read defensively rather than assumed: `string[]`, `{key|colId|field, reason|why}[]`
113
+ * and `Record<key, string | {reason}>` all normalise. The REASON TEXT IS THE SERVER'S, never
114
+ * invented here, so a new refusal cause needs no client change.
115
+ */
116
+ function fieldNotes(raw: unknown): FieldNote[] {
117
+ const out: FieldNote[] = [];
118
+ const push = (key: unknown, reason: unknown) => {
119
+ const k = typeof key === "string" ? key.trim() : "";
120
+ if (!k) return;
121
+ out.push({ key: k, reason: typeof reason === "string" ? reason.trim() : "" });
122
+ };
123
+ if (Array.isArray(raw)) {
124
+ for (const item of raw) {
125
+ if (typeof item === "string") {
126
+ push(item, "");
127
+ } else if (item && typeof item === "object") {
128
+ const rec = item as Record<string, unknown>;
129
+ push(rec.key ?? rec.colId ?? rec.field, rec.reason ?? rec.why);
130
+ }
131
+ }
132
+ } else if (raw && typeof raw === "object") {
133
+ for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
134
+ if (v && typeof v === "object") push(k, (v as Record<string, unknown>).reason);
135
+ else push(k, typeof v === "string" ? v : "");
136
+ }
137
+ }
138
+ return out;
139
+ }
140
+
141
  export default function ShareDialog({
142
  kind,
143
  id,
 
172
  const [busy, setBusy] = useState(false);
173
  const [pick, setPick] = useState("");
174
  const [pickRole, setPickRole] = useState<ShareRole>("view");
175
+ // W42-T26 β€” the RESULT half: what the last successful save actually granted, and what it
176
+ // refused. Empty until a save answers, and empty again whenever one answers without the keys.
177
+ const [sharedFields, setSharedFields] = useState<FieldNote[]>([]);
178
+ const [refusedFields, setRefusedFields] = useState<FieldNote[]>([]);
179
 
180
  const path = `${API_V1}/share/${encodeURIComponent(kind)}/${encodeURIComponent(id)}`;
181
 
 
247
  const body = (await res.json().catch(() => null)) as
248
  | { error?: { message?: string } }
249
  | null;
250
+ // β›” CLEARED ON FAILURE TOO. A refusal list left standing beside a change that did not
251
+ // happen describes a grant nobody made.
252
+ setSharedFields([]);
253
+ setRefusedFields([]);
254
  setError(
255
  res.status >= 500
256
  ? "Something went wrong on our side. Try again in a moment."
 
270
  // promote anybody, and this line must never be the reason it looks like it can.
271
  const saved = parseShare({ ...(body as object), mayAdminister: true });
272
  setEntries(saved.entries);
273
+ // ⭐ W42-T26 / C7 β€” read STRAIGHT OFF THE RAW BODY, because `parseShare` keeps five keys
274
+ // and drops everything else, and `shareModel.ts` is another lane's file this wave.
275
+ const answered = (body ?? null) as Record<string, unknown> | null;
276
+ setSharedFields(fieldNotes(answered?.sharedFieldKeys));
277
+ setRefusedFields(fieldNotes(answered?.refusedFieldKeys));
278
  return true;
279
  } catch {
280
  setError("Cannot reach the server.");
 
327
  : "Sharing never widens past this workspace: everyone here can already open the surface it lives on."}
328
  </p>
329
  {kind === "view" ? (
330
+ <>
331
+ <p className="shell-share-note">
332
+ View access is the general rule. A field's own Share field access takes precedence, so
333
+ a field shared as Can view stays read-only even inside an editable view.
334
+ </p>
335
+ {/* ⭐⭐ W42-T26 / C7 β€” WHICH FIELDS TRAVEL, and how far. Two paragraphs, not one and
336
+ not four: the done-when reads for three statements (what travels, the FILTER's
337
+ fields by name, and the topic-wide reach), and a sharer must be able to point at a
338
+ sentence for each without reading an essay in a dialog subtitle. */}
339
+ <p className="shell-share-note">
340
+ {VIEW_FIELD_TRAVEL} {VIEW_FIELD_TOPIC_WIDE}
341
+ </p>
342
+ <p className="shell-share-note">{VIEW_FILTER_FIELDS}</p>
343
+ </>
344
  ) : kind === "field" ? (
345
  <p className="shell-share-note">
346
  Field access takes precedence over the view. Can view keeps values and field settings
 
361
  one-line answer above it, since the fact that changes everything
362
  ("Everyone can edit") is the one a list of rows buries. */}
363
  <p className="shell-share-summary">{shareSummary(entries)}</p>
364
+ {/* ⭐⭐ W42-T26 / C7 β€” THE RESULT: which fields actually travelled, and which could not,
365
+ each with the reason the SERVER gave. Absent both keys this renders nothing at all
366
+ and the dialog looks exactly as it did before the ticket, which is today's state:
367
+ the server half is lane A's and has not landed.
368
+ ⚠ NO NEW CLASSES. `index.css` is another lane's file this wave and a lane sheet
369
+ loses every equal-specificity fight with it [[a-lane-stylesheet-cannot-override-index-css]],
370
+ so a refusal reuses the row/who/role anatomy the entries list already paints. */}
371
+ {kind === "view" && sharedFields.length > 0 ? (
372
+ <p className="shell-share-note">
373
+ {SHARED_FIELDS_LEAD} {sharedFields.map((f) => f.key).join(", ")}
374
+ </p>
375
+ ) : null}
376
+ {kind === "view" && refusedFields.length > 0 ? (
377
+ <>
378
+ <p className="shell-share-note">{REFUSED_FIELDS_LEAD}</p>
379
+ <div className="shell-share-list">
380
+ {refusedFields.map((f) => (
381
+ <div className="shell-share-row" key={f.key}>
382
+ <span className="shell-share-who">{f.key}</span>
383
+ {f.reason ? <span className="shell-share-role">{f.reason}</span> : null}
384
+ </div>
385
+ ))}
386
+ </div>
387
+ </>
388
+ ) : null}
389
  <div className="shell-share-list">
390
  {state.owner ? (
391
  <div className="shell-share-row is-owner">
web/src/shell/Shell.tsx CHANGED
@@ -64,7 +64,7 @@ const AutomationSurface = lazy(() => import("../automation/AutomationSurface"));
64
  // ⚠ IT JOINS `Lazily`, NOT A BARE `Suspense`: the shared wrapper carries the ErrorBoundary, so a
65
  // chunk that fails to load names the surface it was for instead of blanking the frame.
66
  const CustomerGrid = lazy(() => import("../customer-grid/CustomerGrid"));
67
- import { clearCustomersCache, currentSurfaceScope } from "../customer-grid/apiBridge";
68
  import { OverlayProvider } from "../customer-grid/OverlaySurface";
69
  // ROWS_STALE_EVENT left with `addRecord` (wave 20 item 4): the shell no longer writes rows,
70
  // so it no longer has to tell the grid that it did.
@@ -76,8 +76,14 @@ import type { SettingsSection } from "../settings/SettingsModal";
76
  import { Brand } from "./Brand";
77
  import { ErrorBoundary } from "./ErrorBoundary";
78
  import LoginPage from "./LoginPage";
79
- import { ASSISTANT_ROUTE, CONNECTORS_ROUTE, EMPTY_NAV_PREFS, ENVELOPE_KEYS, FEEDBACK_ROUTE, HOME_ROUTE, INBOX_ROUTE, NO_SUBSCRIPTION_TENANT, STARRED_ROUTE, SUBSCRIPTION_ROUTE, USAGE_ROUTE, MAX_NAV_FOLDERS, NAV_TIMEOUT_STATUS, appLink, canonicalRoute, databaseEntries, defaultRoute, deleteTable, fetchNav, fetchNavPrefs, fetchTableFootprint, foldNav, postOpened, QUERY_ROUTE, resolveRoute, rewrittenHash, routeKeyOf, saveNavMeta, saveNavPrefs, shapeNav, splitChrome } from "./nav";
80
- import type { NavEntry, NavMetaPatch, NavPage, NavPrefs, Recent } from "./nav";
 
 
 
 
 
 
81
  // ⭐ 2026-08-14 β€” the database frame, extracted so the Query module can wear the SAME one.
82
  import { DbIcon, gridScopeFor } from "./dbFrame";
83
  /* ⭐ W35-T09 β€” the app's own star (B-3): one mark, one meaning (DESIGN.md Β§4). */
@@ -333,6 +339,12 @@ type Nav =
333
  const NO_UTILITY: NavPage[] = [];
334
  /** Stable identity, like `NO_ENTRIES` β€” a fresh `[]` per render would re-run Home's memo. */
335
  const NO_RECENTS: Recent[] = [];
 
 
 
 
 
 
336
 
337
  /**
338
  * ⭐⭐ W33-T22 (owner item 1) β€” THE TWO ROWS THE PAYLOAD DECIDES, FOUND IN ONE PLACE.
@@ -1202,7 +1214,24 @@ function ShellFrame() {
1202
  // route has to join, and a route that joins it must also RENDER something. A drill is a rail
1203
  // STATE: the content pane keeps showing whatever it was showing, which is also the honest
1204
  // answer to "I opened the navigation, I did not leave the page".
1205
- type RailLevel = { kind: "root" } | { kind: "data" } | { kind: "db"; key: string };
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1206
  const [rail, setRail] = useState<{ hist: RailLevel[]; at: number }>(
1207
  () => ({ hist: [{ kind: "root" }], at: 0 })
1208
  );
@@ -1229,18 +1258,40 @@ function ShellFrame() {
1229
  setRail((s) =>
1230
  s.hist.length > 1
1231
  ? { ...s, at: 1 }
1232
- : { hist: [s.hist[0], { kind: "data" }], at: 1 }
1233
  );
1234
  }, []);
1235
- /** Drill from the list into ONE database. The row's own `href` does the navigating; this records
1236
- * where the click went, so `<` and `>` can walk back to it.
1237
  * ⚠ It TRUNCATES anything ahead of the cursor, which is what a browser's forward button does
1238
  * after you take a new branch: a forward entry you can no longer reach by going back is a
1239
- * destination the history is lying about. */
1240
- const pushDb = useCallback((key: string) => {
1241
- setRail((s) => ({ hist: [...s.hist.slice(0, s.at + 1), { kind: "db", key }], at: s.at + 1 }));
 
 
1242
  setDbQuery("");
1243
  }, []);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1244
  // ⚠ Declared here and READ inside the Escape effect below, because that effect must not
1245
  // re-subscribe on every drag state change β€” and because the guard it needs is "a drag is in
1246
  // flight", which is state this component already holds (`dragKey`, declared further down with
@@ -1435,7 +1486,12 @@ function ShellFrame() {
1435
  const [navPrefs, setNavPrefs] = useState<NavPrefs>(EMPTY_NAV_PREFS);
1436
  const navPrefsRef = useRef(navPrefs);
1437
  navPrefsRef.current = navPrefs;
1438
- const [closedFolders, setClosedFolders] = useState<ReadonlySet<string>>(new Set());
 
 
 
 
 
1439
  const [schemaFor, setSchemaFor] = useState<string | null>(null);
1440
  useEffect(() => {
1441
  if (who === null) {
@@ -1495,14 +1551,8 @@ function ShellFrame() {
1495
  },
1496
  [commitPrefs]
1497
  );
1498
- const toggleFolder = useCallback((id: string) => {
1499
- setClosedFolders((prev) => {
1500
- const next = new Set(prev);
1501
- if (next.has(id)) next.delete(id);
1502
- else next.add(id);
1503
- return next;
1504
- });
1505
- }, []);
1506
  // ── Wave 14 C-NAVFOLD (items 4/6): drag replaces the menu's Move-to-folder. A PRIVATE
1507
  // dataTransfer MIME so a drop anywhere text-editable types nothing (the wave-13 C-LAYOUT
1508
  // scar); `dropTarget` is a folder id or "__root__" (drag out = drop on the list itself).
@@ -2116,14 +2166,22 @@ function ShellFrame() {
2116
  // most a few dozen rows, so anything cleverer (fuzzy, ranked) would be a scoring function
2117
  // nobody can predict over a set small enough to read.
2118
  //
2119
- // ⚠ SEARCHING RENDERS FLAT. `foldNav` is called with EMPTY prefs while a query is live,
2120
- // because a folder head whose members were filtered out would report a count it is not
2121
- // showing β€” the same "count derived from one list, rows from another" defect the R10
2122
- // relocation note two blocks up already documents.
 
 
 
 
 
 
 
 
 
 
 
2123
  const dbQ = dbQuery.trim().toLowerCase();
2124
- const shownEntries = dbQ
2125
- ? dbEntries.filter((e) => e.label.toLowerCase().includes(dbQ))
2126
- : dbEntries;
2127
  // WAVE 23 C10 β€” what Home draws: the server's recents plus this session's own stamps.
2128
  const recents = mergeRecents(nav.phase === "ready" ? nav.recents : NO_RECENTS, opened);
2129
 
@@ -2140,6 +2198,98 @@ function ShellFrame() {
2140
  // from `rail.at`, and everything reads it.
2141
  const railLevel: RailLevel = rail.hist[rail.at] ?? { kind: "root" };
2142
  const dbAt = railLevel.kind !== "root";
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2143
  const canRailBack = rail.at > 0;
2144
  const canRailForward = rail.at < rail.hist.length - 1;
2145
  /**
@@ -2147,10 +2297,17 @@ function ShellFrame() {
2147
  * Connectors back on screen β€” a level replaces the rail's rows, so this is the way out, not a
2148
  * convenience.
2149
  *
2150
- * ⚠ A `db` step RE-NAVIGATES, because that is what the entry MEANS. The owner asked to *"go to
2151
- * the previous path"*, and for a database the path IS the open surface; a back button that
2152
- * changed the rail while leaving the grid on another table would be showing a path nobody is
2153
- * standing on.
 
 
 
 
 
 
 
2154
  * ⚠ A plain function, not a `useCallback`: it reads `rail` from this render and every click
2155
  * gets a fresh one, so there is no stale-cursor window between two human clicks β€” and a hook
2156
  * here would have to be declared 900 lines up, away from the thing it walks.
@@ -2161,13 +2318,32 @@ function ShellFrame() {
2161
  if (!dest) return;
2162
  setRail({ hist: rail.hist, at });
2163
  setDbQuery("");
2164
- if (dest.kind === "db") window.location.hash = `#/${dest.key}`;
2165
  };
2166
  /** The level's own name, and the only header a level gets (DESIGN Β§2: a short plain noun). */
 
 
 
 
 
 
 
2167
  const railLevelName =
2168
- railLevel.kind === "db"
2169
- ? (dbEntries.find((e) => e.key === railLevel.key)?.label ?? "Data")
2170
- : "Data";
 
 
 
 
 
 
 
 
 
 
 
 
2171
  /**
2172
  * ⭐ OWNER INSTRUCTION 4 β€” `Loopable / Odoo customer`, the topbar path.
2173
  *
@@ -2619,8 +2795,20 @@ function ShellFrame() {
2619
  exact 12x12 box for the Data row's disclosure; one mark, one meaning
2620
  (DESIGN Β§4). The buttons wear the quiet-button register `.shell-newfolder`
2621
  established, per DESIGN Β§4's "new nav joins the existing rhythm".
2622
- ⚠ A DISABLED END OF THE WALK, not a hidden one: a control that vanishes when
2623
- it cannot act moves the other one under the reader's cursor. */}
 
 
 
 
 
 
 
 
 
 
 
 
2624
  <div className="shell-path">
2625
  <button
2626
  type="button"
@@ -2632,18 +2820,109 @@ function ShellFrame() {
2632
  >
2633
  <PathCaret back />
2634
  </button>
2635
- <button
2636
- type="button"
2637
- className="shell-path-step"
2638
- aria-label="Forward"
2639
- title="Forward"
2640
- disabled={!canRailForward}
2641
- onClick={() => stepRail(1)}
2642
- >
2643
- <PathCaret />
2644
- </button>
 
2645
  <span className="shell-path-here">{railLevelName}</span>
2646
  </div>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2647
  <div className="shell-dbfly-head">
2648
  <input
2649
  autoFocus
@@ -2671,6 +2950,13 @@ function ShellFrame() {
2671
  if (e.currentTarget.contains(e.relatedTarget as Node)) return;
2672
  setDropTarget(null);
2673
  }}
 
 
 
 
 
 
 
2674
  onDrop={(e) => {
2675
  const key = e.dataTransfer.getData(NAV_DRAG_TYPE);
2676
  setDropTarget(null);
@@ -2680,58 +2966,95 @@ function ShellFrame() {
2680
  movePage(key, null);
2681
  }}
2682
  >
2683
- {/* C-SCHEMA: the list folds under the user's folders.
2684
- ⭐ WAVE 23 C10 β€” the `navCollapsed ? EMPTY_NAV_PREFS :` gate is GONE with the band
2685
- it belonged to. It existed because the 44px strip had no room for folder chrome;
2686
- this panel is 268px wide whatever the rail is doing, so the folders always render
2687
- and the reason for the gate no longer exists. A SEARCH still flattens (see
2688
- `shownEntries`) β€” that is a different fact about a different state. */}
2689
- {foldNav(shownEntries, dbQ ? EMPTY_NAV_PREFS : navPrefs, closedFolders).map(
2690
- (row) => {
2691
- if (row.kind === "folder") {
2692
- return (
2693
- <FolderHead
2694
- key={`folder:${row.folder.id}`}
2695
- folder={row.folder}
2696
- count={row.count}
2697
- // ⭐ W34-T11 / C1 β€” `foldNav` sets this only for a CLOSED folder, so the
2698
- // "an expanded one does not double-count" clause is decided where the
2699
- // members are known rather than re-derived here.
2700
- open={row.open}
2701
- // WAVE 23 C10 β€” always false in the flyout: the panel has full width in
2702
- // either rail state, so folder chrome is never the thing being squeezed.
2703
- collapsed={false}
2704
- onToggle={() => toggleFolder(row.folder.id)}
2705
- onRename={(name) => renameFolder(row.folder.id, name)}
2706
- onDelete={() => deleteFolder(row.folder.id)}
2707
- isDrop={dropTarget === row.folder.id}
2708
- dropProps={{
2709
- onDragOver: (e) => {
2710
- if (!e.dataTransfer.types.includes(NAV_DRAG_TYPE)) return;
2711
- e.preventDefault();
2712
- e.stopPropagation();
2713
- e.dataTransfer.dropEffect = "move";
2714
- setDropTarget(row.folder.id);
2715
- },
2716
- onDrop: (e) => {
2717
- const key = e.dataTransfer.getData(NAV_DRAG_TYPE);
2718
- setDropTarget(null);
2719
- setDragKey(null);
2720
- if (!key) return;
2721
- e.preventDefault();
2722
- e.stopPropagation();
2723
- movePage(key, row.folder.id);
2724
- },
2725
- }}
2726
- />
2727
- );
2728
- }
2729
- const item = row.entry;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2730
  // Wave 17 item 12 β€” ONE answer, read by the row AND the link.
2731
  // The row paints the tint (so it reaches under the β‹―, matching
2732
  // the Views rail); the link keeps the class because the weight
2733
  // and the full-strength icon hang off `.shell-nav-item.is-active`.
2734
  const isActive = !!active && active.key === item.key;
 
 
 
 
 
 
2735
  const cls =
2736
  "shell-nav-item" +
2737
  (item.depth > 0 ? " is-child" : "") +
@@ -2839,7 +3162,19 @@ function ShellFrame() {
2839
  className={
2840
  "shell-nav-row" +
2841
  (isActive ? " is-active" : "") +
2842
- (row.folderId ? " is-foldered" : "") +
 
 
 
 
 
 
 
 
 
 
 
 
2843
  (dragKey === item.key ? " is-dragging" : "")
2844
  }
2845
  // WAVE 23 C10 β€” `!navCollapsed &&` dropped from both gates below: the panel
@@ -2929,13 +3264,20 @@ function ShellFrame() {
2929
  );
2930
  }
2931
  )}
2932
- {/* The panel's own empty state: ONE line, and it is different from "this
2933
  workspace has none" β€” a search that matched nothing is not a workspace
2934
  with nothing in it, and saying the second when the first is true is how a
2935
- reader concludes their data is gone. */}
2936
- {shownEntries.length === 0 ? (
 
 
 
2937
  <p className="shell-dbfly-empty">
2938
- {dbQuery ? "No database matches that." : "No databases yet."}
 
 
 
 
2939
  </p>
2940
  ) : null}
2941
  </div>
@@ -2977,6 +3319,8 @@ function ShellFrame() {
2977
  canFolder={entries.length > 0}
2978
  />
2979
  </div>
 
 
2980
  </div>
2981
  ) : null}
2982
  {/* W33-T75: loading is represented only by the two row-local slots above. A separate
 
64
  // ⚠ IT JOINS `Lazily`, NOT A BARE `Suspense`: the shared wrapper carries the ErrorBoundary, so a
65
  // chunk that fails to load names the surface it was for instead of blanking the frame.
66
  const CustomerGrid = lazy(() => import("../customer-grid/CustomerGrid"));
67
+ import { clearCustomersCache, currentSurfaceScope, peekWorkspace } from "../customer-grid/apiBridge";
68
  import { OverlayProvider } from "../customer-grid/OverlaySurface";
69
  // ROWS_STALE_EVENT left with `addRecord` (wave 20 item 4): the shell no longer writes rows,
70
  // so it no longer has to tell the grid that it did.
 
76
  import { Brand } from "./Brand";
77
  import { ErrorBoundary } from "./ErrorBoundary";
78
  import LoginPage from "./LoginPage";
79
+ import { ASSISTANT_ROUTE, CONNECTORS_ROUTE, EMPTY_NAV_PREFS, ENVELOPE_KEYS, FEEDBACK_ROUTE, HOME_ROUTE, INBOX_ROUTE, NO_SUBSCRIPTION_TENANT, STARRED_ROUTE, SUBSCRIPTION_ROUTE, USAGE_ROUTE, MAX_NAV_FOLDERS, NAV_TIMEOUT_STATUS, appLink, canonicalRoute, databaseEntries, defaultRoute, deleteTable, fetchNav, fetchNavPrefs, fetchTableFootprint, navFolderIdOf, navLevelAt, postOpened, QUERY_ROUTE, resolveRoute, rewrittenHash, routeKeyOf, saveNavMeta, saveNavPrefs, shapeNav, splitChrome, viewsForDb } from "./nav";
80
+ import type { DbWorkspaces, NavEntry, NavFolder, NavMetaPatch, NavPage, NavPrefs, Recent } from "./nav";
81
+ // ⭐⭐ WAVE 42 Β· T16 (contract C5) β€” the rail's views level walks the SAME path resolver the
82
+ // grid's view rail walks (W42-T41). One walk, two callers: a level here and a level there can
83
+ // never disagree about what is filed where, because neither of them re-derives it.
84
+ import { levelAt } from "../customer-grid/folders";
85
+ import type { GridFolder, SavedView } from "../customer-grid/types";
86
+ import type { WorkspaceHolder } from "../customer-grid/viewEcho";
87
  // ⭐ 2026-08-14 β€” the database frame, extracted so the Query module can wear the SAME one.
88
  import { DbIcon, gridScopeFor } from "./dbFrame";
89
  /* ⭐ W35-T09 β€” the app's own star (B-3): one mark, one meaning (DESIGN.md Β§4). */
 
339
  const NO_UTILITY: NavPage[] = [];
340
  /** Stable identity, like `NO_ENTRIES` β€” a fresh `[]` per render would re-run Home's memo. */
341
  const NO_RECENTS: Recent[] = [];
342
+ /** W42-T42 β€” the rail's folder heads while a search needle is live: none, flattened away. Same
343
+ * stable-identity rule as the two above. */
344
+ const NO_NAV_FOLDERS: NavFolder[] = [];
345
+ /** The same, for the rail's VIEW folders β€” a flattened search shows no folder heads on either
346
+ * level, because the two levels answer the search box one way (W42-T42). */
347
+ const NO_VIEW_FOLDERS: GridFolder[] = [];
348
 
349
  /**
350
  * ⭐⭐ W33-T22 (owner item 1) β€” THE TWO ROWS THE PAYLOAD DECIDES, FOUND IN ONE PLACE.
 
1214
  // route has to join, and a route that joins it must also RENDER something. A drill is a rail
1215
  // STATE: the content pane keeps showing whatever it was showing, which is also the honest
1216
  // answer to "I opened the navigation, I did not leave the page".
1217
+ // ⭐⭐ WAVE 42 Β· T16 (owner instructions 4 + 16, contract C5, amendment A1) β€” THE KINDS ARE
1218
+ // ONE CONTINUOUS PATH, AND EACH STEP CARRIES WHERE IT STANDS INSIDE ITSELF.
1219
+ //
1220
+ // β›” `{kind:"db"}` IS REPLACED BY `{kind:"views"}`, and that is the contract rather than
1221
+ // tidying. A `db` step was a DESTINATION the rail recorded and then re-navigated to, which is
1222
+ // why `stepRail` used to write the hash; a `views` step is a place the rail STANDS, drawing
1223
+ // that database's view folders and saved views in the rail itself. The old kind was named in
1224
+ // exactly four places, all in this file, so nothing outside it has to learn a new word.
1225
+ //
1226
+ // ⭐ `at` IS THE PATH VARIANT W42-T41's MODEL ASKS FOR. `folders.ts::levelAt` answers "what is
1227
+ // at this path" from a FOLDER ID, `null` meaning the top of that level, so a step that means to
1228
+ // be walked has to be able to say which folder it is in. On `views` it is a view folder
1229
+ // (`GridFolder.id`) and is walked below; on `data` it is a NAV folder, declared here so both
1230
+ // halves of the path share ONE shape, and walked by W42-T42, which owns that generalisation.
1231
+ type RailLevel =
1232
+ | { kind: "root" }
1233
+ | { kind: "data"; at: string | null }
1234
+ | { kind: "views"; dbKey: string; at: string | null };
1235
  const [rail, setRail] = useState<{ hist: RailLevel[]; at: number }>(
1236
  () => ({ hist: [{ kind: "root" }], at: 0 })
1237
  );
 
1258
  setRail((s) =>
1259
  s.hist.length > 1
1260
  ? { ...s, at: 1 }
1261
+ : { hist: [s.hist[0], { kind: "data", at: null }], at: 1 }
1262
  );
1263
  }, []);
1264
+ /** Take ONE step along the path, whatever the step is.
 
1265
  * ⚠ It TRUNCATES anything ahead of the cursor, which is what a browser's forward button does
1266
  * after you take a new branch: a forward entry you can no longer reach by going back is a
1267
+ * destination the history is lying about.
1268
+ * ⭐ W42-T16 β€” one pusher for every kind of step. Two of them would be two places to remember
1269
+ * the truncation rule, and the second one is where it gets forgotten. */
1270
+ const pushLevel = useCallback((level: RailLevel) => {
1271
+ setRail((s) => ({ hist: [...s.hist.slice(0, s.at + 1), level], at: s.at + 1 }));
1272
  setDbQuery("");
1273
  }, []);
1274
+ /** Step from the database list into ONE database's VIEWS. The row's own `href` still opens the
1275
+ * database in the content pane; this moves the RAIL to that database's views, which is what
1276
+ * makes the click one step along a path rather than a departure from it (W42-T16, C5). */
1277
+ const pushDb = useCallback(
1278
+ (key: string) => pushLevel({ kind: "views", dbKey: key, at: null }),
1279
+ [pushLevel]
1280
+ );
1281
+ /** Step INTO a view folder, staying in the same database. `at` is a `GridFolder.id`, exactly
1282
+ * what `levelAt` reads, and `<` walks back out of it like any other step. */
1283
+ const pushViewFolder = useCallback(
1284
+ (dbKey: string, at: string | null) => pushLevel({ kind: "views", dbKey, at }),
1285
+ [pushLevel]
1286
+ );
1287
+ /** Step INTO a DATABASE folder, staying in the database half of the path. `at` is a
1288
+ * `NavFolder.id`, the same shape `navLevelAt` reads, and `<` walks back out of it like every
1289
+ * other step (W42-T42, R12.1). It is the third caller of the ONE pusher rather than a second
1290
+ * history: the truncation rule lives in exactly one place. */
1291
+ const pushNavFolder = useCallback(
1292
+ (at: string | null) => pushLevel({ kind: "data", at }),
1293
+ [pushLevel]
1294
+ );
1295
  // ⚠ Declared here and READ inside the Escape effect below, because that effect must not
1296
  // re-subscribe on every drag state change β€” and because the guard it needs is "a drag is in
1297
  // flight", which is state this component already holds (`dragKey`, declared further down with
 
1486
  const [navPrefs, setNavPrefs] = useState<NavPrefs>(EMPTY_NAV_PREFS);
1487
  const navPrefsRef = useRef(navPrefs);
1488
  navPrefsRef.current = navPrefs;
1489
+ // β›”β›” W42-T42 (ruling R12.2) β€” THE `closedFolders` SET IS DELETED, AND SO IS THE TREE IT DREW.
1490
+ // A nav folder used to expand in place: a twisty, an open/closed set, and its members drawn
1491
+ // underneath it. R12 replaces expand and collapse with a PATH in both folder systems, so a
1492
+ // folder is a step you walk into and there is no open state left for anything to hold. It was
1493
+ // local `useState` and reached neither `saveNavPrefs` nor `postOpened`, so nothing persisted
1494
+ // goes with it and no migration is owed.
1495
  const [schemaFor, setSchemaFor] = useState<string | null>(null);
1496
  useEffect(() => {
1497
  if (who === null) {
 
1551
  },
1552
  [commitPrefs]
1553
  );
1554
+ // β›” W42-T42 (R12.2) β€” `toggleFolder` is deleted with `closedFolders`. A folder head opens a
1555
+ // LEVEL now (`pushNavFolder`); there is no second state for it to flip.
 
 
 
 
 
 
1556
  // ── Wave 14 C-NAVFOLD (items 4/6): drag replaces the menu's Move-to-folder. A PRIVATE
1557
  // dataTransfer MIME so a drop anywhere text-editable types nothing (the wave-13 C-LAYOUT
1558
  // scar); `dropTarget` is a folder id or "__root__" (drag out = drop on the list itself).
 
2166
  // most a few dozen rows, so anything cleverer (fuzzy, ranked) would be a scoring function
2167
  // nobody can predict over a set small enough to read.
2168
  //
2169
+ // β›”β›” W42-T42 (R12) β€” A LIVE QUERY FLATTENS ACROSS EVERY FOLDER, AND THAT IS THE WHOLE POINT.
2170
+ // The path decides what the list shows only while the search box is EMPTY. The moment a needle
2171
+ // is live the level stops deciding: the list is every matching database from every folder, with
2172
+ // no folder heads and no level, because a search that quietly saw only the folder you happen to
2173
+ // be standing in would answer "no such database" about a database that exists.
2174
+ // β›” IT MIRRORS `customer-grid/ViewSidebar.tsx::levelGroups`, WHICH DOES EXACTLY THIS FOR VIEWS
2175
+ // (W42-T43, same lane) β€” R12 asks the two folder systems to behave identically, and a rail whose
2176
+ // two halves searched differently would breach it inside one wave. An earlier draft of this
2177
+ // ticket scoped the search to the level and justified it by claiming parity with the views
2178
+ // level; the views level does the OPPOSITE, and the claim was simply false. It was also a
2179
+ // REGRESSION: the tree this replaced passed `EMPTY_NAV_PREFS` to `foldNav` precisely so a query
2180
+ // flattened it, so scoping would have removed a behaviour that already worked.
2181
+ // ⚠ THE PATH SURVIVES THE SEARCH. Typing never touches `rail`, so clearing the box puts the
2182
+ // reader back on the level they were standing on rather than at the top β€” the third thing T43
2183
+ // does, for the same reason.
2184
  const dbQ = dbQuery.trim().toLowerCase();
 
 
 
2185
  // WAVE 23 C10 β€” what Home draws: the server's recents plus this session's own stamps.
2186
  const recents = mergeRecents(nav.phase === "ready" ? nav.recents : NO_RECENTS, opened);
2187
 
 
2198
  // from `rail.at`, and everything reads it.
2199
  const railLevel: RailLevel = rail.hist[rail.at] ?? { kind: "root" };
2200
  const dbAt = railLevel.kind !== "root";
2201
+ // ── W42-T16 (contract C5) β€” WHAT VIEWS IS THE RAIL STANDING IN? ───────────────────────────
2202
+ //
2203
+ // `viewsForDb` is a LOOKUP over payloads the client already holds, never a fetch β€” C5 forbids a
2204
+ // second read. `peekWorkspace` exposes that existing cache without reading through it: absence
2205
+ // stays absent, so an unvisited database renders PENDING rather than an untrue "no views".
2206
+ const dbWorkspaces: DbWorkspaces = (() => {
2207
+ const out: Record<string, WorkspaceHolder> = {};
2208
+ for (const e of dbEntries) {
2209
+ const ws = peekWorkspace(e.key);
2210
+ if (ws) out[e.key] = { workspace: ws }; // ABSENT, never null
2211
+ }
2212
+ return out;
2213
+ })();
2214
+ // ⚠ CALLED UNCONDITIONALLY, with an empty key off the views level. Both resolvers answer a
2215
+ // well-formed empty result for a key that names nothing, so there is no branch here to get
2216
+ // wrong and no hook rule to trip over β€” the render simply ignores them anywhere else.
2217
+ const railViewsLevel = railLevel.kind === "views" ? railLevel : null;
2218
+ const railViews = viewsForDb(dbWorkspaces, railViewsLevel?.dbKey ?? "");
2219
+ const viewLevel = levelAt<GridFolder, SavedView>(
2220
+ railViewsLevel?.at ?? null,
2221
+ railViews.folders,
2222
+ railViews.views,
2223
+ (v) => v.folderId
2224
+ );
2225
+ // β›”β›” W42-T42 EDIT, INSIDE W42-T16's BLOCK, AND THE ATTRIBUTION IS DELIBERATE. T16 owns this
2226
+ // level and is still open; what it has left to do is the `dbWorkspaces` wiring above, which is
2227
+ // untouched here. Only the SEARCH changed, and it changed because T42 changed the database
2228
+ // level's search three lines down. Whoever finishes T16 must be able to see that.
2229
+ //
2230
+ // ⭐⭐ T16 WROTE HERE: "a level is one anatomy, so its search behaves one way." That sentence was
2231
+ // TRUE when it was written and T42's first draft made it FALSE, by flattening the database
2232
+ // level's search while this one still filtered its own level. The sentence is kept, because the
2233
+ // principle is right and it is the reason for this edit; what changed is that the ONE WAY is now
2234
+ // FLATTENING, on both levels, matching `customer-grid/ViewSidebar.tsx::levelGroups` on the views
2235
+ // rail. Three surfaces, one meaning for the search box, which is what R12's "both folder systems
2236
+ // behave identically" asks for.
2237
+ //
2238
+ // β›” THE FILTER RUNS OVER `railViews`, THE WHOLE DATABASE'S SET, NOT OVER `viewLevel`. Filtering
2239
+ // the level's own arrays is the level-scoped search R12 forbids: it answers "no such view" about
2240
+ // a view that exists one folder away. `viewsForDb` already handed us every folder and every view
2241
+ // for this database, so the whole population is in hand and no second read is needed (C5).
2242
+ // ⚠ NO FOLDER HEADS WHILE A NEEDLE IS LIVE, the same rule the database level applies: a
2243
+ // flattened list has no levels in it, and a head sitting above matches drawn from other folders
2244
+ // would imply they were its members.
2245
+ //
2246
+ // ⚠ UNOBSERVABLE ON THIS TREE, AND THAT IS THE REASON TO WRITE IT NOW RATHER THAN A REASON TO
2247
+ // WAIT. `dbWorkspaces` is empty until T16 is wired, so `railViews` is empty, so no screen, gate
2248
+ // or probe can tell this version from the one it replaces. It becomes visible the moment the
2249
+ // integrator lands that wiring, which is exactly when nobody is looking for it.
2250
+ const shownViewFolders = dbQ ? NO_VIEW_FOLDERS : viewLevel.folders;
2251
+ const shownViews = dbQ
2252
+ ? railViews.views.filter((v) => v.name.toLowerCase().includes(dbQ))
2253
+ : viewLevel.leaves;
2254
+ // ── W42-T42 (ruling R12, contracts C5 + C9) β€” THE DATABASE LEVEL IS A PATH TOO ─────────────
2255
+ //
2256
+ // ⭐⭐ ONE RESOLVER, TWO FOLDER SYSTEMS. `navLevelAt` is W42-T41's adapter over the SAME
2257
+ // `levelAt` the views level three lines up calls; the two halves of the rail therefore answer
2258
+ // "what is at this path" with one piece of code and one shape, which is the whole of C9.
2259
+ // β›” RAW `entries`, NOT a pre-filtered list: `navLevelAt` calls `databaseEntries` itself, so
2260
+ // handing it a filtered list would filter twice and, worse, would decide a folder's membership
2261
+ // from a list the level is not drawing.
2262
+ // ⚠ CALLED UNCONDITIONALLY with `null` off a `data` level, the same way the views resolvers
2263
+ // above are: a well-formed top level for a path nobody is standing on costs one pass over a few
2264
+ // dozen rows and saves a hook-order branch.
2265
+ const navLevel = navLevelAt(
2266
+ railLevel.kind === "data" ? railLevel.at : null,
2267
+ entries,
2268
+ navPrefs
2269
+ );
2270
+ // β›” NO FOLDER HEADS WHILE A NEEDLE IS LIVE. A flattened list has no levels in it, so a head
2271
+ // would be a step into a place the list is already showing you the contents of β€” and it would
2272
+ // sit above matches drawn from OTHER folders, implying they were its members.
2273
+ const shownNavFolders = dbQ ? NO_NAV_FOLDERS : navLevel.folders;
2274
+ // β›”β›” `dbEntries`, THE WHOLE SET β€” NOT `navLevel.leaves`. This is the flatten. Filtering the
2275
+ // level's own leaves is the level-scoped search R12 forbids and reads as "no such database"
2276
+ // over a database sitting one folder away. `dbEntries` is every database the viewer is granted,
2277
+ // which is exactly the population a search should answer over, and `databaseEntries` has
2278
+ // already removed the surfaces that are not databases (D-54).
2279
+ const shownDbs = dbQ
2280
+ ? dbEntries.filter((e) => e.label.toLowerCase().includes(dbQ))
2281
+ : navLevel.leaves;
2282
+ // β›” A FOLDER HEAD COUNTS **BLOCKS**, AND IT MUST KEEP DOING SO. `.shell-nav-foldercount` has
2283
+ // meant "how many databases are filed here" since wave 14 (`verify_ui.py` W35-T07 pins that it
2284
+ // survives), and `foldNav` counted a BLOCK β€” a family head, its depth-1 children riding with
2285
+ // it. `navFolderIdOf` mirrors that same block rule, so counting depth-0 heads through it gives
2286
+ // the number the head has always shown.
2287
+ // ⚠ COUNTED OVER THE UNFILTERED LIST ON PURPOSE. The folder's members are not rendered at this
2288
+ // level at all, so a search over THIS level's rows says nothing about how many things are
2289
+ // inside the folder; filtering the count would make the head lie about the place it leads to.
2290
+ const navFolderIdFor = navFolderIdOf(entries, navPrefs);
2291
+ const navFolderCount = (id: string) =>
2292
+ dbEntries.filter((e) => e.depth === 0 && navFolderIdFor(e) === id).length;
2293
  const canRailBack = rail.at > 0;
2294
  const canRailForward = rail.at < rail.hist.length - 1;
2295
  /**
 
2297
  * Connectors back on screen β€” a level replaces the rail's rows, so this is the way out, not a
2298
  * convenience.
2299
  *
2300
+ * β›”β›” W42-T16 (contract C5) β€” A STEP NEVER NAVIGATES NOW, AND THE ARGUMENT THAT SAID IT MUST
2301
+ * IS RETIRED RATHER THAN DELETED. W41-T32 wrote here that a `db` step had to re-navigate
2302
+ * "because that is what the entry MEANS": for a database the path WAS the open surface, so
2303
+ * moving the rail without moving the grid would have shown a path nobody was standing on. That
2304
+ * held only while a level had nothing of the database in it. It no longer does. A `views` level
2305
+ * RENDERS that database's view folders and saved views in the rail, so the rail is showing the
2306
+ * place the reader is standing in, and `<` walking out of it is a walk out of a level rather
2307
+ * than a lie about the content pane. Re-navigating would now be the defect: it would throw the
2308
+ * grid to another table every time somebody backed out of a folder.
2309
+ * ⚠ And a step that writes `window.location.hash` is a real browser navigation β€” a page load
2310
+ * on the way to a rail render, which is what the owner asked this level not to be.
2311
  * ⚠ A plain function, not a `useCallback`: it reads `rail` from this render and every click
2312
  * gets a fresh one, so there is no stale-cursor window between two human clicks β€” and a hook
2313
  * here would have to be declared 900 lines up, away from the thing it walks.
 
2318
  if (!dest) return;
2319
  setRail({ hist: rail.hist, at });
2320
  setDbQuery("");
2321
+ // β›” NOTHING ELSE. See the note above: the walk moves the RAIL and only the rail.
2322
  };
2323
  /** The level's own name, and the only header a level gets (DESIGN Β§2: a short plain noun). */
2324
+ // ⭐ W42-T16 β€” a view FOLDER is a level of its own and says its own name; the database names
2325
+ // the level at the top of its views. Falling back to the key's label keeps the header honest
2326
+ // for a database whose row is filtered out of the list behind it.
2327
+ // ⭐ W42-T42 β€” a DATABASE folder is a level of its own too, and says its own name. The header is
2328
+ // the only thing on screen that answers "where am I", so a level standing inside a nav folder
2329
+ // reading "Data" would be the same word for every step of the walk. `navLevel.folder` is `null`
2330
+ // at the top, which is the one place that word is right.
2331
  const railLevelName =
2332
+ railLevel.kind === "views"
2333
+ // β›” THE VIEW FOLDER'S NAME GOES AWAY WHILE A SEARCH IS LIVE, exactly as the folder name
2334
+ // does on the database arm below. The list is flattened across every folder of this
2335
+ // database then, so naming the folder you walked into would be the claim the scope note
2336
+ // denies. The DATABASE's own label is the honest word here, because the database is the
2337
+ // population being searched, the way "Data" is on the other arm.
2338
+ ? ((dbQ ? undefined : viewLevel.folder?.name) ??
2339
+ dbEntries.find((e) => e.key === railLevel.dbKey)?.label ??
2340
+ "Data")
2341
+ // β›” AND IT STOPS NAMING THE FOLDER WHILE A SEARCH IS LIVE. The list is flattened across
2342
+ // every folder then, so a header reading the folder's name would be the exact claim the
2343
+ // scope note below exists to deny. "Data" is the honest word for the whole database half,
2344
+ // which is what is being searched; the path itself is untouched, so clearing the box brings
2345
+ // the folder's name straight back.
2346
+ : (dbQ ? "Data" : (navLevel.folder?.name ?? "Data"));
2347
  /**
2348
  * ⭐ OWNER INSTRUCTION 4 β€” `Loopable / Odoo customer`, the topbar path.
2349
  *
 
2795
  exact 12x12 box for the Data row's disclosure; one mark, one meaning
2796
  (DESIGN Β§4). The buttons wear the quiet-button register `.shell-newfolder`
2797
  established, per DESIGN Β§4's "new nav joins the existing rhythm".
2798
+ β›”β›” W42-T42 (ruling R13) β€” THE FORWARD CARET HIDES WHEN THERE IS NOTHING
2799
+ AHEAD, AND THIS NOTE REPLACES THE ONE R13 OVERTURNS BY NAME. The old rule
2800
+ here was "a disabled end of the walk, not a hidden one", on the reasoning
2801
+ that a vanishing control moves its neighbour under the reader's cursor. R13
2802
+ rules the other way: a control that cannot act does not render. It costs
2803
+ nothing to obey, because the geometry the old note worried about does not
2804
+ arise β€” BACK is the LEADING caret and never moves, so removing the trailing
2805
+ one leaves every remaining control exactly where it was.
2806
+ ⚠ THE BACK CARET IS UNCHANGED, and the asymmetry is the point rather than an
2807
+ oversight. Inside a rendered level there is ALWAYS somewhere back to go: the
2808
+ level only exists when the cursor has left the root, so back can always act
2809
+ and hiding it would be hiding a live control. Forward is the only one that
2810
+ runs out of path, and it comes back the moment going back gives it a
2811
+ destination again. */}
2812
  <div className="shell-path">
2813
  <button
2814
  type="button"
 
2820
  >
2821
  <PathCaret back />
2822
  </button>
2823
+ {canRailForward ? (
2824
+ <button
2825
+ type="button"
2826
+ className="shell-path-step"
2827
+ aria-label="Forward"
2828
+ title="Forward"
2829
+ onClick={() => stepRail(1)}
2830
+ >
2831
+ <PathCaret />
2832
+ </button>
2833
+ ) : null}
2834
  <span className="shell-path-here">{railLevelName}</span>
2835
  </div>
2836
+ {/* ⭐⭐ WAVE 42 Β· T16 (owner instructions 4 + 16, contract C5, amendment A1) β€”
2837
+ ONE LEVEL, TWO CONTENTS, AND THE SECOND IS THE NEXT STEP OF THE SAME PATH.
2838
+ Clicking a database no longer leaves the rail behind: the level stays, the
2839
+ caret still walks out of it, and what it lists is that database's view
2840
+ folders and saved views.
2841
+ β›”β›” THE VIEW ROWS ARE `.shell-rail-view`, NOT `.shell-nav-item`, AND THAT IS
2842
+ A GATE CONTRACT RATHER THAN A STYLE CHOICE. `verify_live.py` waits on
2843
+ `.shell-dbfly .shell-nav-item, .shell-level .shell-nav-item` and then CLICKS
2844
+ the first match expecting a DATABASE to open, on its own documented
2845
+ invariant that every such row beneath this container is a database by
2846
+ construction. A view wearing that class would keep the selector matching and
2847
+ break the invariant instead, which is the worse of the two failures. The
2848
+ database branch below keeps every one of its rows, so the selector still
2849
+ matches; a probe that stalls 120 s on a healthy build is what that costs.
2850
+ ⚠ SAME ANATOMY, DIFFERENT CONTENTS (DESIGN §4): the header, one search box,
2851
+ rows. No new control shape, and no second create footer β€” making a view is
2852
+ the database's own rail's door, and a second one here would be a second
2853
+ answer to one question. */}
2854
+ {railLevel.kind === "views" ? (
2855
+ <>
2856
+ <div className="shell-dbfly-head">
2857
+ <input
2858
+ autoFocus
2859
+ className="shell-dbfly-search"
2860
+ placeholder="Search views"
2861
+ value={dbQuery}
2862
+ maxLength={60}
2863
+ onChange={(e) => setDbQuery(e.target.value)}
2864
+ onKeyDown={(e) => {
2865
+ if (e.key === "Escape") closeDbFly();
2866
+ }}
2867
+ />
2868
+ </div>
2869
+ <div className="shell-nav-list">
2870
+ {railViews.known ? (
2871
+ <>
2872
+ {/* β›” THE SCOPE IS STATED HERE TOO β€” same sentence, same class, same
2873
+ place above the rows as the database level and as `ViewSidebar`'s
2874
+ views rail. A live search flattens across every folder of this
2875
+ database, so the list below is not the level the path names. Three
2876
+ surfaces, one sentence, because a reader who learns what the box does
2877
+ on one level must not have to learn it again on another. */}
2878
+ {dbQ ? (
2879
+ <p className="shell-dbfly-empty">Showing matches in every folder</p>
2880
+ ) : null}
2881
+ {shownViewFolders.map((f) => (
2882
+ <button
2883
+ key={`viewfolder:${f.id}`}
2884
+ type="button"
2885
+ className="shell-rail-view is-folder"
2886
+ onClick={() => pushViewFolder(railLevel.dbKey, f.id)}
2887
+ >
2888
+ <span className="shell-nav-mark" aria-hidden="true">
2889
+ <FolderMark {...(f.icon ? { icon: f.icon } : {})} size={16} />
2890
+ </span>
2891
+ <span className="shell-nav-label">{f.name}</span>
2892
+ </button>
2893
+ ))}
2894
+ {shownViews.map((v) => (
2895
+ <button
2896
+ key={v.id}
2897
+ type="button"
2898
+ className="shell-rail-view"
2899
+ /* The one forward door this ticket owns: opening a view is what the
2900
+ level is FOR. `openViewInDatabase` is the shell's existing opener,
2901
+ scope-mapped and retry-laddered β€” a second way to open a view is a
2902
+ second way to get the scope spelling wrong. */
2903
+ onClick={() => openViewInDatabase(railLevel.dbKey, v.id)}
2904
+ >
2905
+ <span className="shell-nav-label">{v.name}</span>
2906
+ </button>
2907
+ ))}
2908
+ {shownViewFolders.length === 0 && shownViews.length === 0 ? (
2909
+ <p className="shell-dbfly-empty">
2910
+ {dbQuery
2911
+ ? "No view matches that."
2912
+ : "No saved views here yet."}
2913
+ </p>
2914
+ ) : null}
2915
+ </>
2916
+ ) : (
2917
+ /* β›” PENDING, NOT EMPTY, and `known` is the field that tells them apart. An
2918
+ empty list drawn over a payload nobody has read yet is a confident zero
2919
+ for a database with ten views, and nothing downstream could tell. */
2920
+ <p className="shell-dbfly-empty">Reading this database's views.</p>
2921
+ )}
2922
+ </div>
2923
+ </>
2924
+ ) : (
2925
+ <>
2926
  <div className="shell-dbfly-head">
2927
  <input
2928
  autoFocus
 
2950
  if (e.currentTarget.contains(e.relatedTarget as Node)) return;
2951
  setDropTarget(null);
2952
  }}
2953
+ // ⚠ W42-T42 β€” DELIBERATELY STILL `null`, INSIDE A FOLDER TOO. The background of the
2954
+ // list is the "drag it out" target and has been since wave 14. Now that a level can BE
2955
+ // a folder, an alternative reading appears β€” drop on the background means "file it
2956
+ // here" β€” and it was rejected: taking it would leave a database filed in a folder with
2957
+ // no drag gesture at all for getting it out again, because the row is not visible from
2958
+ // the level above. Unfiling makes the row leave this level, which is exactly what the
2959
+ // gesture looks like it is doing.
2960
  onDrop={(e) => {
2961
  const key = e.dataTransfer.getData(NAV_DRAG_TYPE);
2962
  setDropTarget(null);
 
2966
  movePage(key, null);
2967
  }}
2968
  >
2969
+ {/* ⭐⭐ W42-T42 (ruling R12, contracts C5 + C9) β€” THE DATABASE LIST IS A LEVEL OF A
2970
+ PATH, AND THE TREE THAT USED TO BE HERE IS GONE. `foldNav` drew folder heads with
2971
+ their members underneath and an open or closed state per head; R12 replaces expand
2972
+ and collapse with a walk, in BOTH folder systems, so this list draws only what is
2973
+ AT the current path. Clicking a folder takes a step into it; the back caret above
2974
+ walks out again. `foldNav` itself stays exported and unit-tested in `nav.ts` β€” this
2975
+ ticket removes its CALL, not the function.
2976
+
2977
+ ⭐ FOLDERS FIRST, THEN THE DATABASES (R12.4). They arrive as two arrays from
2978
+ `navLevelAt` for exactly that reason, so the order is a property of the render and
2979
+ never a sort over a mixed list that a later edit can quietly disturb.
2980
+
2981
+ β›”β›” EVERY DATABASE ROW BENEATH THIS CONTAINER IS A DATABASE, AND A DEPLOY PROBE
2982
+ RESTS ON IT. The live verification script waits on the database row class scoped to
2983
+ this level, then CLICKS the first one expecting a grid to open, on its own written
2984
+ invariant that the class cannot appear here on anything but a database. Folder heads
2985
+ wear the folder classes `FolderHead` renders and must NEVER be given the row class:
2986
+ that would keep the probe matching while breaking what it matches, which is worse
2987
+ than not matching at all. The needles are described here, never spelled β€” prose
2988
+ about a pattern IS the pattern to a text scan.
2989
+ ⚠ AND AFTER THIS TICKET THE COUNT OF THOSE ROWS CAN LEGITIMATELY BE ZERO at the
2990
+ top level, because a viewer who has filed every database into folders should see
2991
+ folders there and nothing else. That is the instruction working, not a defect; it
2992
+ is a known hazard for a probe that assumes at least one row and it is booked with
2993
+ the integrator, who owns the deploy. Do not code around it here. */}
2994
+ {/* β›” THE SCOPE IS STATED, never implied β€” W42-T42, mirroring W42-T43's line on the
2995
+ views rail. A live search flattens across every folder, so the list below is NOT
2996
+ the level the path names, and leaving that unsaid while the header still names a
2997
+ folder would claim otherwise. It rides ABOVE the rows, where it is read before
2998
+ them rather than as a footnote to them. Clearing the box is the action that
2999
+ resolves it, so it is a note in the list's own note class and not a control. */}
3000
+ {dbQ ? (
3001
+ <p className="shell-dbfly-empty">Showing matches in every folder</p>
3002
+ ) : null}
3003
+ {shownNavFolders.map((f) => (
3004
+ <FolderHead
3005
+ key={`folder:${f.id}`}
3006
+ folder={f}
3007
+ // β›” BLOCKS, not rendered rows, and counted over the whole list β€” see
3008
+ // `navFolderCount`. The head names a place you have not walked into yet.
3009
+ count={navFolderCount(f.id)}
3010
+ // WAVE 23 C10 β€” always false here: the panel has full width in either rail state,
3011
+ // so folder chrome is never the thing being squeezed. It asks whether the RAIL is
3012
+ // folded to its narrow strip, which is a different question from anything R12
3013
+ // retired.
3014
+ collapsed={false}
3015
+ // ⭐ R12.2 β€” the head DRILLS. It used to flip an open state; there is no open
3016
+ // state left, and the prop is named for the walk so the two cannot be confused.
3017
+ onOpen={() => pushNavFolder(f.id)}
3018
+ onRename={(name) => renameFolder(f.id, name)}
3019
+ onDelete={() => deleteFolder(f.id)}
3020
+ isDrop={dropTarget === f.id}
3021
+ // β›” A FOLDER YOU CAN WALK INTO IS STILL A FOLDER YOU CAN DROP A DATABASE ONTO.
3022
+ // The drag keys off the folder ID exactly as it always has (C9: the path model is
3023
+ // ADDED over the placement data, it does not replace it), so filing by drag and
3024
+ // walking by click are two things one row does.
3025
+ dropProps={{
3026
+ onDragOver: (e) => {
3027
+ if (!e.dataTransfer.types.includes(NAV_DRAG_TYPE)) return;
3028
+ e.preventDefault();
3029
+ e.stopPropagation();
3030
+ e.dataTransfer.dropEffect = "move";
3031
+ setDropTarget(f.id);
3032
+ },
3033
+ onDrop: (e) => {
3034
+ const key = e.dataTransfer.getData(NAV_DRAG_TYPE);
3035
+ setDropTarget(null);
3036
+ setDragKey(null);
3037
+ if (!key) return;
3038
+ e.preventDefault();
3039
+ e.stopPropagation();
3040
+ movePage(key, f.id);
3041
+ },
3042
+ }}
3043
+ />
3044
+ ))}
3045
+ {shownDbs.map(
3046
+ (item) => {
3047
  // Wave 17 item 12 β€” ONE answer, read by the row AND the link.
3048
  // The row paints the tint (so it reaches under the β‹―, matching
3049
  // the Views rail); the link keeps the class because the weight
3050
  // and the full-strength icon hang off `.shell-nav-item.is-active`.
3051
  const isActive = !!active && active.key === item.key;
3052
+ // β›”β›” `is-child` IS NOT THE INDENTATION R12.2 DELETES, and the next reader greps
3053
+ // "indent", lands here, and needs this sentence. It marks a database's own
3054
+ // SUB-PAGE β€” `NavEntry.depth`, a family the server sends as a head plus its
3055
+ // children β€” and it has never had anything to do with folder nesting: even under
3056
+ // the old tree a folder's members were drawn flush. R12.2 removes the twisty and
3057
+ // the expand state; a family staying visibly a family is untouched by it.
3058
  const cls =
3059
  "shell-nav-item" +
3060
  (item.depth > 0 ? " is-child" : "") +
 
3162
  className={
3163
  "shell-nav-row" +
3164
  (isActive ? " is-active" : "") +
3165
+ // β›”β›” W42-T42 (R12.2) β€” `is-foldered` IS GONE, AND IT IS THE INDENTATION
3166
+ // THE RULING DELETES. It was set for a row drawn UNDERNEATH its folder's
3167
+ // head and `navExtras.css` pays it as `padding-left: 30px` β€” a row stepped
3168
+ // in to say "I belong to the head above me". A level has no head above it:
3169
+ // the folder is the header of the whole screen, every row on it is inside
3170
+ // that folder, and indenting all of them would step the entire list in
3171
+ // against nothing. Translating the flag to "this level IS a folder" was the
3172
+ // mechanical move and it is the wrong one β€” it keeps the indent and merely
3173
+ // widens it. `is-child` below is a different flag for a different fact and
3174
+ // stays; see its note.
3175
+ // ⚠ The rule in `navExtras.css` is now unrendered. That file is off this
3176
+ // ticket's fence, so its deletion is BOOKED rather than taken: an orphan
3177
+ // rule is an invitation to re-add the class it styles.
3178
  (dragKey === item.key ? " is-dragging" : "")
3179
  }
3180
  // WAVE 23 C10 β€” `!navCollapsed &&` dropped from both gates below: the panel
 
3264
  );
3265
  }
3266
  )}
3267
+ {/* The level's own empty state: ONE line, and it is different from "this
3268
  workspace has none" β€” a search that matched nothing is not a workspace
3269
  with nothing in it, and saying the second when the first is true is how a
3270
+ reader concludes their data is gone.
3271
+ ⭐ W42-T42 β€” a THIRD sentence, because a level can now be empty for a third
3272
+ reason: you walked into a folder and it holds nothing. Saying "no databases
3273
+ yet" there would tell somebody with twenty databases that they have none. */}
3274
+ {shownNavFolders.length === 0 && shownDbs.length === 0 ? (
3275
  <p className="shell-dbfly-empty">
3276
+ {dbQuery
3277
+ ? "No database matches that."
3278
+ : navLevel.folder
3279
+ ? "This folder is empty."
3280
+ : "No databases yet."}
3281
  </p>
3282
  ) : null}
3283
  </div>
 
3319
  canFolder={entries.length > 0}
3320
  />
3321
  </div>
3322
+ </>
3323
+ )}
3324
  </div>
3325
  ) : null}
3326
  {/* W33-T75: loading is represented only by the two row-local slots above. A separate
web/src/shell/nav.ts CHANGED
@@ -30,6 +30,19 @@ import { API_V1, CREDENTIALS } from "../apiContract";
30
  // `appBase` being a parameter for exactly that reason).
31
  import { FOLDER_SHAPES, FOLDER_TONES } from "../customer-grid/types";
32
  import type { FolderIcon } from "../customer-grid/types";
 
 
 
 
 
 
 
 
 
 
 
 
 
33
 
34
  /** One entry of X2's nav payload. `source` is the registry's connector fact
35
  * (wave-9 I8: "Sales Β· Odoo"); `parent` names a sub-module's family head. */
@@ -1365,3 +1378,150 @@ export function resolveRoute(entries: NavEntry[], route: string): NavEntry | und
1365
  const fallback = defaultRoute(entries);
1366
  return entries.find((e) => e.key === fallback);
1367
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
30
  // `appBase` being a parameter for exactly that reason).
31
  import { FOLDER_SHAPES, FOLDER_TONES } from "../customer-grid/types";
32
  import type { FolderIcon } from "../customer-grid/types";
33
+ // ⭐⭐ WAVE 42 Β· T41 (R12 / C9) β€” the ONE path model, imported rather than re-spelled. See the
34
+ // adapter block at the foot of this file. `customer-grid/folders` is pure and React-free by its
35
+ // own header (it exists so `verify_folders.py` can run it under node) and its only imports are
36
+ // `./viewEcho` and `./types`, both of which bottom out in `./windows`; so this import keeps
37
+ // nav.ts runnable under plain node, which `verify_login.py` depends on.
38
+ import { folderPath, levelAt } from "../customer-grid/folders";
39
+ import type { FolderLevel } from "../customer-grid/folders";
40
+ // ⭐⭐ WAVE 42 Β· T15 (C5) β€” the workspace-to-rail-lists resolver, imported rather than re-spelled.
41
+ // See the `viewsForDb` block at the foot of this file. `customer-grid/viewEcho` is pure by its own
42
+ // header and imports only `./types`, which bottoms out in `./windows`, so this keeps nav.ts
43
+ // runnable under plain node the way `verify_login.py` depends on.
44
+ import { viewsOfWorkspace } from "../customer-grid/viewEcho";
45
+ import type { WorkspaceHolder, WorkspaceViews } from "../customer-grid/viewEcho";
46
 
47
  /** One entry of X2's nav payload. `source` is the registry's connector fact
48
  * (wave-9 I8: "Sales Β· Odoo"); `parent` names a sub-module's family head. */
 
1378
  const fallback = defaultRoute(entries);
1379
  return entries.find((e) => e.key === fallback);
1380
  }
1381
+
1382
+ // ── ⭐⭐ WAVE 42 Β· T41 (ruling R12, contract C9) β€” THE DATABASE FOLDERS, ON THE ONE PATH MODEL ──
1383
+ //
1384
+ // β›” THIS IS AN ADAPTER, NOT A SECOND MODEL. `foldNav` above is untouched and every one of its
1385
+ // callers keeps working: it still answers "draw me the rail as rows". What was missing is the
1386
+ // OTHER question, the one R12 turns the navigation into β€” "what is at this path, and what is one
1387
+ // step out" β€” and answering it here in nav's own spelling would have rebuilt the very duplication
1388
+ // R12.3 exists to end. So the answer comes from `customer-grid/folders.ts::levelAt`, the single
1389
+ // resolver, and this file supplies only the two things that genuinely differ.
1390
+ //
1391
+ // ⚠ WHAT DIFFERS IS EXACTLY ONE THING: WHERE MEMBERSHIP IS STORED. A view carries its own
1392
+ // `folderId`; a database's placement lives in the per-user `NavPrefs.placement` map, keyed by page
1393
+ // key. {@link navFolderIdOf} closes over that map and hands `levelAt` the same
1394
+ // item-to-folder-id function a view rail hands it. Nothing else about a database folder is
1395
+ // special, which is the claim R12.3 makes and this adapter is how it becomes true.
1396
+ //
1397
+ // ⚠ NAV FOLDERS ARE FLAT AND STAY FLAT. `NavFolder` has no `parent` and must not grow one here:
1398
+ // `parseNavPrefs` mirrors the server's `_clean_nav_prefs`, which builds a strict `{id, name}` row,
1399
+ // so the value would be dropped on the next save. A parentless folder resolves through
1400
+ // `folderNesting` at level 1 with a `null` parent, so `levelAt` drills it with the same code that
1401
+ // drills a ten-deep view folder β€” it simply never has subfolders to list. `MAX_NAV_FOLDERS` (16,
1402
+ // a COUNT) and `FOLDER_DEPTH_MAX` (10, a DEPTH) are different numbers and neither bounds the other.
1403
+
1404
+ /**
1405
+ * Where a nav entry is filed, in the shape {@link levelAt} asks for.
1406
+ *
1407
+ * β›” IT MIRRORS `foldNav`'s BLOCK RULE rather than reading `placement` raw, and that is the whole
1408
+ * of its correctness. A depth-1 entry is a sub-module of the entry above it, `foldNav` moves the
1409
+ * two as ONE unit ("filing a family head files the family"), and `placement` only ever names the
1410
+ * head. Reading the map directly would leave every child at the top level while its parent sat in
1411
+ * a folder β€” the family split in half, on a rail that has never shown one.
1412
+ *
1413
+ * ⚠ A placement naming a folder that no longer exists returns `null`, the same dangling rule
1414
+ * `foldNav` applies (`ids.has(fid)`) and the same one `levelAt` applies one layer down.
1415
+ */
1416
+ export function navFolderIdOf(
1417
+ entries: NavEntry[],
1418
+ prefs: NavPrefs
1419
+ ): (entry: NavEntry) => string | null {
1420
+ const ids = new Set(prefs.folders.map((f) => f.id));
1421
+ const owner = new Map<string, string | null>();
1422
+ let headKey: string | null = null;
1423
+ for (const e of entries) {
1424
+ if (e.depth > 0 && headKey) {
1425
+ owner.set(e.key, owner.get(headKey) ?? null);
1426
+ continue;
1427
+ }
1428
+ headKey = e.key;
1429
+ const fid = prefs.placement[e.key];
1430
+ owner.set(e.key, fid && ids.has(fid) ? fid : null);
1431
+ }
1432
+ return (entry: NavEntry) => owner.get(entry.key) ?? null;
1433
+ }
1434
+
1435
+ /**
1436
+ * ⭐⭐ WHAT IS AT THIS PATH, for the DATABASE half of the navigation β€” the same
1437
+ * `{folders, leaves, parent}` a view folder answers with, from the same resolver.
1438
+ *
1439
+ * `at` is the nav folder the user has drilled into, absent/`null` being the top level. Leaves are
1440
+ * {@link DatabaseEntry}s, so the surfaces that are not databases (D-54's `SURFACE_KEYS`) are
1441
+ * already out: a path that drills into folders of databases must not hand back a row that is not
1442
+ * one, and `databaseEntries` is the only supported way to obtain that list.
1443
+ */
1444
+ export function navLevelAt(
1445
+ at: string | null | undefined,
1446
+ entries: NavEntry[],
1447
+ prefs: NavPrefs
1448
+ ): FolderLevel<NavFolder, DatabaseEntry> {
1449
+ const folderIdOf = navFolderIdOf(entries, prefs);
1450
+ return levelAt<NavFolder, DatabaseEntry>(
1451
+ at,
1452
+ prefs.folders,
1453
+ databaseEntries(entries),
1454
+ folderIdOf
1455
+ );
1456
+ }
1457
+
1458
+ /**
1459
+ * The breadcrumb trail to a nav folder, outermost first β€” R12.1's "one continuous path", the
1460
+ * database half of it. Flat today, so it is at most one folder long; it is the shared walk rather
1461
+ * than a `[folder]` literal so that the day nav folders nest, this needs no second thought.
1462
+ */
1463
+ export function navFolderPath(
1464
+ at: string | null | undefined,
1465
+ prefs: NavPrefs
1466
+ ): NavFolder[] {
1467
+ return folderPath<NavFolder>(at, prefs.folders);
1468
+ }
1469
+
1470
+ // ── WAVE 42 Β· T15 (contract C5): the rail's views level, from OUTSIDE the grid ──────────────
1471
+ //
1472
+ // ⭐⭐ THE ONE RESOLVER FOR "WHAT VIEWS DOES THIS DATABASE HAVE?". C5's views level puts a
1473
+ // database's `SavedView[]`/`GridFolder[]` on the rail, where no `CustomerGrid` is mounted to be
1474
+ // asked. Before this there was NO db-key-to-views symbol anywhere: the lists were a `useState`
1475
+ // seeded from the page payload inside the grid's content component, reachable only by being that
1476
+ // component.
1477
+ //
1478
+ // β›” IT IS A LOOKUP, NOT A FETCH, and that is the trap this ticket names by name. The data
1479
+ // already arrives with the page; a second `GET` issued from the shell would re-download bytes the
1480
+ // browser holds and would answer at a different instant from the grid rendering beside it. So the
1481
+ // caller passes what it is already holding and this narrows it.
1482
+ //
1483
+ // The workspace-to-lists half lives in `customer-grid/viewEcho.ts::viewsOfWorkspace`, beside the
1484
+ // other SavedView-shaped resolution and beside the reads it mirrors. Same split as T41's
1485
+ // `levelAt`/`navLevelAt`: the generic in the grid, the adapter here, and what differs is only
1486
+ // where the thing is keyed from.
1487
+
1488
+ /** What the shell holds: a workspace-bearing payload per database key, whatever it has so far.
1489
+ * A key with no entry is not an error β€” see {@link DbViews.known}. */
1490
+ export type DbWorkspaces = Readonly<Record<string, WorkspaceHolder | null | undefined>>;
1491
+
1492
+ /**
1493
+ * β›” `known` IS THE LOAD-BEARING FIELD, exactly as `NavPage.important`'s absence is one level up:
1494
+ * an empty list must not be reported for a database whose payload has simply not been read yet.
1495
+ * `false` means THIS SOURCE HOLDS NO WORKSPACE FOR THAT KEY β€” the caller draws a pending state,
1496
+ * never "no views". `true` with `views: []` is a real, checkable claim that the database has no
1497
+ * saved views. Conflating the two would put a confident zero on screen for a database with ten,
1498
+ * and nothing downstream could tell the difference.
1499
+ */
1500
+ export interface DbViews extends WorkspaceViews {
1501
+ known: boolean;
1502
+ }
1503
+
1504
+ /**
1505
+ * ⭐⭐ THE VIEWS AND FOLDERS OF ONE DATABASE, from the payload the page already carries.
1506
+ *
1507
+ * The lists are the HOST's β€” `payload.workspace.views` / `.folders`, the same two reads
1508
+ * `CustomerGrid` starts from (`CustomerGrid.tsx:1516` and `:5159`). A mounted grid then layers
1509
+ * this browser's own localStorage over them (an optimistic create, a tombstoned delete, the
1510
+ * synthesized "All records" tab); that layer is per-browser state owned by a mounted component
1511
+ * and is not reproducible β€” nor desirable β€” from here.
1512
+ *
1513
+ * Nothing throws. An absent source, an absent payload, an absent `workspace`, an absent `views`,
1514
+ * an absent `folders` and a key naming nothing all answer a well-formed empty result.
1515
+ */
1516
+ export function viewsForDb(source: DbWorkspaces | null | undefined, dbKey: string): DbViews {
1517
+ const held =
1518
+ source && typeof source === "object" && dbKey
1519
+ ? (Object.prototype.hasOwnProperty.call(source, dbKey) ? source[dbKey] : undefined)
1520
+ : undefined;
1521
+ // ⚠ `hasOwnProperty`, not a truthiness test on the value: a key present with an explicit
1522
+ // `null` (a payload that was read and came back empty) is KNOWN, and it is the one case a
1523
+ // truthiness test would misfile as pending for ever.
1524
+ const known = !!source && typeof source === "object" && !!dbKey &&
1525
+ Object.prototype.hasOwnProperty.call(source, dbKey);
1526
+ return { ...viewsOfWorkspace(held), known };
1527
+ }
web/src/styles/wave42/hop-editor.css ADDED
@@ -0,0 +1,67 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /* wave 42 lane stylesheet: hop-editor. OWNED BY LANE B. No other lane writes here, and no lane
2
+ writes index.css except D (see PRD.md FILE OWNERSHIP).
3
+ Tokens live in index.css :root and customer-grid/theme.ts -- declare there, consume here.
4
+
5
+ IMPORTANT, AND IT IS A RULE ABOUT TIES: index.css @imports this sheet from the top of the file,
6
+ because an @import must precede every other at-rule. Everything index.css declares is therefore
7
+ LATER than everything here, so at EQUAL specificity index.css WINS and a rule written here is
8
+ dead on arrival. Raise specificity deliberately, or put the rule in index.css and say so in the
9
+ ticket. Landed EMPTY in the baseline commit so lane B never has to touch index.css to be seen. */
10
+
11
+ /* ─────────────────────────────────────────────────────────────────────────────────────────────
12
+ W42-T08 (ruling R1) β€” THE HOP QUESTION, inside the link field editor.
13
+
14
+ The hop is ONE added question in the panel that already asks which database, so it wears the
15
+ panel's own controls (`.cg-input`, `.cg-field-hint`, `.cg-type-title`) untouched and adds only
16
+ the containment that says "these settings belong to the answer above". That is the layout the
17
+ reference art uses for a link field's own condition block: indented, hairline-ruled, inline,
18
+ never a second modal.
19
+
20
+ β›” EVERY RULE IS SCOPED UNDER `.cg-hop`, DELIBERATELY. index.css @imports this sheet from its
21
+ very first lines, so everything index.css declares is LATER than everything here and wins every
22
+ equal-specificity tie. Two classes deep is what keeps these rules alive; a bare `.cg-input`
23
+ rule written here would be dead on arrival, which is why none of them restyle a shared control.
24
+ ───────────────────────────────────────────────────────────────────────────────────────────── */
25
+
26
+ .cg-hop {
27
+ display: flex;
28
+ flex-direction: column;
29
+ gap: 6px;
30
+ margin-top: 8px;
31
+ padding-top: 8px;
32
+ border-top: 1px solid var(--cg-line);
33
+ }
34
+
35
+ /* The question itself sits flush with the database question above it: same label, same control,
36
+ because it is the same kind of question and a new shape would read as a different feature. */
37
+ .cg-hop .cg-hop-question {
38
+ display: flex;
39
+ flex-direction: column;
40
+ gap: 4px;
41
+ }
42
+
43
+ /* The answer's settings, indented under it. ONE containment layer: a rule and an inset, not a
44
+ card inside the card the editor already is. */
45
+ .cg-hop .cg-hop-body {
46
+ display: flex;
47
+ flex-direction: column;
48
+ gap: 6px;
49
+ margin-top: 4px;
50
+ padding-left: 12px;
51
+ border-left: 2px solid var(--cg-line);
52
+ }
53
+
54
+ .cg-hop .cg-hop-body > label {
55
+ display: flex;
56
+ flex-direction: column;
57
+ gap: 4px;
58
+ }
59
+
60
+ /* The condition builder keeps its own anatomy; this only gives it the breathing room that
61
+ separates "narrow the middle step" from the pickers that chose it. */
62
+ .cg-hop .cg-hop-filter {
63
+ display: flex;
64
+ flex-direction: column;
65
+ gap: 4px;
66
+ margin-top: 4px;
67
+ }
web/src/styles/wave42/rail-views.css ADDED
@@ -0,0 +1,125 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /* wave 42 lane stylesheet: rail-views. OWNED BY LANE C. No other lane writes here, and no lane
2
+ writes index.css except D (see PRD.md FILE OWNERSHIP).
3
+ Tokens live in index.css :root and customer-grid/theme.ts -- declare there, consume here.
4
+
5
+ IMPORTANT, AND IT IS A RULE ABOUT TIES: index.css @imports this sheet from the top of the file,
6
+ because an @import must precede every other at-rule. Everything index.css declares is therefore
7
+ LATER than everything here, so at EQUAL specificity index.css WINS and a rule written here is
8
+ dead on arrival. Raise specificity deliberately, or put the rule in index.css and say so in the
9
+ ticket. Landed EMPTY in the baseline commit so lane C never has to touch index.css to be seen. */
10
+
11
+ /* ── W42-T16 (owner instructions 4 + 16, contract C5) β€” THE RAIL'S VIEW ROWS ──────────────────
12
+ A view row is a nav row: same height, same padding, same gap, same hover, same focus ring, so
13
+ walking from the database list into a database's views changes the CONTENTS of the level and
14
+ nothing about its rhythm (DESIGN Β§4, "new nav joins the existing rhythm, never a new control
15
+ shape"). It is written out here rather than borrowed by adding `.shell-nav-item` to the row,
16
+ because `verify_live.py` clicks the first `.shell-level .shell-nav-item` expecting a DATABASE
17
+ to open and documents that invariant in its own comment; a view wearing that class breaks the
18
+ probe on a healthy build. So the row shares the look and not the hook, and this file is where
19
+ that decision is paid for.
20
+
21
+ ⚠ SPECIFICITY IS RAISED ON PURPOSE, AND THIS IS THE RULE ABOUT TIES. index.css @imports this
22
+ sheet at the top, so at EQUAL specificity index.css wins every fight and a rule here is dead on
23
+ arrival. `.shell-rail-view` is a new class with nothing to collide with today, but the rows sit
24
+ inside `.shell-level`, whose descendants index.css styles freely β€” so every selector below is
25
+ scoped `.shell-level .shell-rail-view` (0,2,0) rather than bare (0,1,0), which is what keeps
26
+ them alive if a later rule in index.css reaches into this container.
27
+
28
+ ⚠ THE UA RESET IS NOT OPTIONAL. These rows are `<button>`s, and a button that does not reset
29
+ `font`, `border` and `background` renders the user agent's outset border over ButtonFace beside
30
+ the `<a>` rows above it (index.css:3687 carries the same scar). `font` goes FIRST: the
31
+ shorthand resets size and weight to inherited values, so declared after the longhands it would
32
+ silently undo both. */
33
+ .shell-level .shell-rail-view {
34
+ font: inherit;
35
+ border: 0;
36
+ background: transparent;
37
+ text-align: left;
38
+ display: flex;
39
+ align-items: center;
40
+ gap: 8px;
41
+ width: 100%;
42
+ min-height: 34px;
43
+ padding: 7px 8px;
44
+ font-size: var(--lp-fs-xs);
45
+ font-weight: 500;
46
+ color: var(--lp-ink);
47
+ text-decoration: none;
48
+ border-radius: var(--lp-r-sm);
49
+ cursor: pointer;
50
+ }
51
+ .shell-level .shell-rail-view:hover {
52
+ background: var(--lp-surface-2);
53
+ }
54
+ .shell-level .shell-rail-view:focus-visible {
55
+ outline: 2px solid var(--lp-blue-deep);
56
+ outline-offset: -2px;
57
+ }
58
+ /* A folder is a step, not a destination, and the mark is the only thing that says so before the
59
+ click. `FolderMark` paints its own fill and stroke, so the wrapper carries the BOX only and
60
+ never `.shell-nav-icon`, which would repaint a deliberately coloured glyph in the row's ink and
61
+ then dim it to 0.55 (the same note the database rows carry one screen up). */
62
+ .shell-level .shell-rail-view.is-folder .shell-nav-mark {
63
+ flex: 0 0 auto;
64
+ display: inline-flex;
65
+ width: 16px;
66
+ height: 16px;
67
+ }
68
+
69
+ /* ── W42-T55 (ruling R25) β€” THE CHANGE-ICON PANEL'S OWN CHROME ────────────────────────────────
70
+ R25: "that navigation already exist, no need to reinvent the wheel." The PICKER was already
71
+ shared (W41-T35 mounts one `FolderIconPicker` in both doors); the defect was the CHROME. The
72
+ change path wore `cg-view-menu`, a class built for MENU ROWS β€” 4px padding, a 186/260px row
73
+ ceiling and a `button` rule that repaints anything button-shaped inside it β€” so the same swatch
74
+ grid arrived narrower and tighter than the create step's, and it read as a different control.
75
+
76
+ β›” `cg-view-menu` IS NOT TOUCHED, and that is the point. It is worn by the view menu, the folder
77
+ menu, the column menu and the create flyout; restyling it to fix ONE panel restyles all of them.
78
+ This panel gets its own class instead, and the values below are READ from the create step's
79
+ rules in index.css rather than eyeballed:
80
+ `.cg-view-create` (index.css:886) β€” padding: 9px; border: 1px solid var(--lp-line);
81
+ border-radius: var(--lp-r-lg); background: var(--cg-white)
82
+ `.cg-view-create label` (index.css:893) β€” color: var(--cg-muted); font-size: var(--lp-fs-3xs)
83
+ So the surround around the swatch grid is the same 9px on the same 1px hairline at the same
84
+ radius on the same surface, and the heading is the same muted 3xs the create step's label is.
85
+
86
+ ⚠ THE WIDTH IS DERIVED, NOT INVENTED. The create pane is in normal flow inside `.cg-views`
87
+ (`width: var(--lp-rail-w)`, `padding: 0 8px 10px`) and `.cg-view-create` adds `margin: 0 2px`,
88
+ so its border box is `--lp-rail-w` minus 16px of rail padding minus 4px of its own margin. An
89
+ anchored overlay has no such parent to inherit from, so the same box is computed here. It
90
+ matters because the swatch rows WRAP: at this width the twelve shapes break into the same rows
91
+ the create step shows, and a content-sized panel would lay them out in one long line instead.
92
+
93
+ ⚠ NO `z-index` HERE ON PURPOSE. `body > .cg-overlay` (index.css:1490) sets `--cg-z-overlay` at
94
+ (0,1,1) and is deliberately above `.cg-pop`/`.cg-view-menu`'s menu layer; declaring one at
95
+ (0,2,0) here would silently demote this panel out of that layer.
96
+
97
+ ⚠ SPECIFICITY, per this file's header: index.css @imports this sheet at the top, so at EQUAL
98
+ specificity index.css wins. `.cg-overlay` is stamped unconditionally by `OverlaySurface`, so the
99
+ selectors below are written `.cg-overlay.cg-fold-icon-pop` (0,2,0) rather than bare (0,1,0), and
100
+ the picker override is (0,3,0) so it outranks `.cg-fold-pick` (0,1,0) in index.css. */
101
+ .cg-overlay.cg-fold-icon-pop {
102
+ width: calc(var(--lp-rail-w) - 20px);
103
+ max-width: calc(100vw - 16px);
104
+ padding: 9px;
105
+ border: 1px solid var(--lp-line);
106
+ border-radius: var(--lp-r-lg);
107
+ background: var(--cg-white);
108
+ /* The one thing the create pane cannot lend: it sits in the rail, this floats over the grid.
109
+ The literal is `.cg-view-menu`'s own shadow verbatim (index.css:816), so the panel keeps the
110
+ elevation every other overlay in this rail has. There is no shadow token to name yet. */
111
+ box-shadow: 0 8px 24px rgba(20, 24, 40, 0.13);
112
+ }
113
+ /* The create step's picker is followed by the form's Create/Cancel row, so its 6px bottom margin
114
+ is a GAP between two things. Here it is the last child and that margin would sit on top of the
115
+ 9px padding, leaving the grid off-centre in its own box. */
116
+ .cg-overlay.cg-fold-icon-pop .cg-fold-pick {
117
+ margin: 0;
118
+ }
119
+ /* Sentence case, one line, the folder's own name and no explanation of what an icon is
120
+ (DESIGN.md Β§4). Same muted 3xs the create step's label wears. */
121
+ .cg-overlay.cg-fold-icon-pop .cg-fold-icon-title {
122
+ margin: 0 0 5px;
123
+ color: var(--cg-muted);
124
+ font-size: var(--lp-fs-3xs);
125
+ }
web/src/styles/wave42/route-nav.css ADDED
@@ -0,0 +1,244 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /* wave 42 lane stylesheet: route-nav. OWNED BY LANE D. No other lane writes here, and no lane
2
+ writes index.css except D (see PRD.md FILE OWNERSHIP).
3
+ Tokens live in index.css :root and customer-grid/theme.ts -- declare there, consume here.
4
+
5
+ IMPORTANT, AND IT IS A RULE ABOUT TIES: index.css @imports this sheet from the top of the file,
6
+ because an @import must precede every other at-rule. Everything index.css declares is therefore
7
+ LATER than everything here, so at EQUAL specificity index.css WINS and a rule written here is
8
+ dead on arrival. Raise specificity deliberately, or put the rule in index.css and say so in the
9
+ ticket. Landed EMPTY in the baseline commit so lane D never has to touch index.css to be seen. */
10
+
11
+ /* ── W42-T24 (instruction 10, contract C6): the route navigation ────────────────────────────────
12
+ EVERY selector below is prefixed with `#cg-route-popover`, and that is the tie rule above being
13
+ obeyed rather than worked around. The rail deliberately REUSES `ViewSidebar`'s class names
14
+ (`cg-view-row`, `cg-view-main`, `cg-view-more`, `cg-fold-head`, `cg-view-menu`) so a route row
15
+ and a view row are one component to the eye and to the stylesheet; an id prefix is what lets the
16
+ handful of context differences win against index.css's own rules for those same classes.
17
+ β›” NOTHING HERE INVENTS A COLOUR. Navy, gold, ink, muted and line all come from the tokens. */
18
+
19
+ #cg-route-popover .cg-route-nav {
20
+ display: flex;
21
+ flex-direction: column;
22
+ gap: 4px;
23
+ padding-bottom: 8px;
24
+ margin-bottom: 8px;
25
+ border-bottom: 1px solid var(--cg-line);
26
+ }
27
+
28
+ /* The rail's own message slot. It is on screen whether or not a plan exists, so it is the one
29
+ place a refusal raised before a route is solved can actually be read. */
30
+ #cg-route-popover .cg-route-nav-notice {
31
+ padding: 4px 6px;
32
+ border-radius: 5px;
33
+ background: var(--cg-soft);
34
+ color: var(--cg-muted);
35
+ font-size: var(--lp-fs-3xs);
36
+ line-height: 1.35;
37
+ }
38
+
39
+ #cg-route-popover .cg-route-nav-head {
40
+ display: flex;
41
+ align-items: center;
42
+ justify-content: space-between;
43
+ gap: 8px;
44
+ }
45
+
46
+ #cg-route-popover .cg-route-nav-head .cg-create-btn {
47
+ display: inline-flex;
48
+ align-items: center;
49
+ gap: 4px;
50
+ font-size: var(--lp-fs-2xs);
51
+ color: var(--cg-navy);
52
+ }
53
+
54
+ #cg-route-popover .cg-route-nav-head .cg-create-icon {
55
+ font-weight: 600;
56
+ line-height: 1;
57
+ }
58
+
59
+ /* The list scrolls on its own so a workspace with forty routes cannot push the planner off the
60
+ bottom of the overlay. The cap is generous: a rail that scrolls at four rows reads as broken. */
61
+ #cg-route-popover .cg-route-nav-list {
62
+ display: flex;
63
+ flex-direction: column;
64
+ gap: 2px;
65
+ max-height: 220px;
66
+ overflow-y: auto;
67
+ }
68
+
69
+ #cg-route-popover .cg-route-nav-root,
70
+ #cg-route-popover .cg-route-nav-group {
71
+ display: flex;
72
+ flex-direction: column;
73
+ gap: 2px;
74
+ }
75
+
76
+ /* A route row is a view row in a narrower box: same anatomy, same hit targets, less padding. */
77
+ #cg-route-popover .cg-route-row {
78
+ display: flex;
79
+ align-items: center;
80
+ gap: 4px;
81
+ padding: 2px 4px;
82
+ border-radius: 5px;
83
+ cursor: grab;
84
+ }
85
+
86
+ #cg-route-popover .cg-route-row:hover {
87
+ background: var(--cg-soft);
88
+ }
89
+
90
+ #cg-route-popover .cg-route-row.is-active {
91
+ background: color-mix(in srgb, var(--cg-navy) 10%, transparent);
92
+ }
93
+
94
+ #cg-route-popover .cg-route-row.is-viewdrag {
95
+ opacity: 0.45;
96
+ }
97
+
98
+ /* The insertion rule, gold, on the edge the drop lands against. Same mark the views rail uses,
99
+ so a person who has reordered views once already knows what this line means. */
100
+ #cg-route-popover .cg-route-row.is-drop-above {
101
+ box-shadow: inset 0 2px 0 0 var(--cg-gold);
102
+ }
103
+
104
+ #cg-route-popover .cg-route-row .cg-view-main {
105
+ display: flex;
106
+ align-items: center;
107
+ gap: 6px;
108
+ flex: 1 1 auto;
109
+ min-width: 0;
110
+ padding: 2px 2px;
111
+ background: none;
112
+ border: 0;
113
+ font: inherit;
114
+ color: var(--cg-text);
115
+ text-align: left;
116
+ cursor: pointer;
117
+ }
118
+
119
+ #cg-route-popover .cg-route-row .cg-view-text {
120
+ display: flex;
121
+ flex-direction: column;
122
+ min-width: 0;
123
+ }
124
+
125
+ #cg-route-popover .cg-route-row .cg-view-name {
126
+ font-size: var(--lp-fs-2xs);
127
+ line-height: 1.25;
128
+ white-space: nowrap;
129
+ overflow: hidden;
130
+ text-overflow: ellipsis;
131
+ }
132
+
133
+ #cg-route-popover .cg-route-row .cg-view-desc {
134
+ font-size: var(--lp-fs-3xs);
135
+ line-height: 1.25;
136
+ color: var(--cg-muted);
137
+ white-space: nowrap;
138
+ overflow: hidden;
139
+ text-overflow: ellipsis;
140
+ }
141
+
142
+ /* The share mark is the SAME glyph a shared view and a shared field wear; only its box is local. */
143
+ #cg-route-popover .cg-route-row .cg-view-shared {
144
+ display: inline-flex;
145
+ align-items: center;
146
+ flex: 0 0 auto;
147
+ color: var(--cg-navy);
148
+ }
149
+
150
+ #cg-route-popover .cg-route-row .cg-view-more,
151
+ #cg-route-popover .cg-fold-head .cg-view-more {
152
+ flex: 0 0 auto;
153
+ padding: 0 4px;
154
+ background: none;
155
+ border: 0;
156
+ color: var(--cg-muted);
157
+ font: inherit;
158
+ line-height: 1;
159
+ letter-spacing: 1px;
160
+ cursor: pointer;
161
+ }
162
+
163
+ #cg-route-popover .cg-route-row .cg-view-more:hover,
164
+ #cg-route-popover .cg-fold-head .cg-view-more:hover {
165
+ color: var(--cg-text);
166
+ }
167
+
168
+ #cg-route-popover .cg-route-nav .cg-fold-head {
169
+ display: flex;
170
+ align-items: center;
171
+ gap: 6px;
172
+ padding: 3px 4px;
173
+ color: var(--cg-text);
174
+ font-size: var(--lp-fs-2xs);
175
+ font-weight: 600;
176
+ cursor: grab;
177
+ }
178
+
179
+ #cg-route-popover .cg-route-nav .cg-fold-head.is-drop-above {
180
+ box-shadow: inset 0 2px 0 0 var(--cg-gold);
181
+ }
182
+
183
+ #cg-route-popover .cg-route-nav .cg-fold-head.is-viewdrag {
184
+ opacity: 0.45;
185
+ }
186
+
187
+ #cg-route-popover .cg-route-nav .cg-fold-name {
188
+ flex: 1 1 auto;
189
+ min-width: 0;
190
+ white-space: nowrap;
191
+ overflow: hidden;
192
+ text-overflow: ellipsis;
193
+ }
194
+
195
+ #cg-route-popover .cg-route-nav .cg-fold-empty {
196
+ padding: 4px 8px;
197
+ color: var(--cg-muted);
198
+ font-size: var(--lp-fs-3xs);
199
+ }
200
+
201
+ #cg-route-popover .cg-route-nav .cg-route-rename,
202
+ #cg-route-popover .cg-route-nav .cg-fold-rename {
203
+ flex: 1 1 auto;
204
+ min-width: 0;
205
+ font-size: var(--lp-fs-2xs);
206
+ }
207
+
208
+ /* ── the share prompt a newly created route raises ──────────────────────────────────────────────
209
+ It is a PROMPT, so it reads as a question with two equal answers rather than as a banner with a
210
+ dismiss. Gold hairline because it is transient and asks for something; navy would read as the
211
+ panel's own chrome and get ignored. */
212
+ #cg-route-popover .cg-route-share-prompt {
213
+ display: flex;
214
+ flex-direction: column;
215
+ gap: 6px;
216
+ padding: 8px;
217
+ border: 1px solid color-mix(in srgb, var(--cg-gold) 55%, var(--cg-line));
218
+ border-radius: 6px;
219
+ background: color-mix(in srgb, var(--cg-gold) 8%, var(--cg-white));
220
+ }
221
+
222
+ #cg-route-popover .cg-route-share-line {
223
+ font-size: var(--lp-fs-2xs);
224
+ line-height: 1.35;
225
+ color: var(--cg-text);
226
+ }
227
+
228
+ #cg-route-popover .cg-route-share-prompt .cg-form-actions {
229
+ display: flex;
230
+ gap: 6px;
231
+ }
232
+
233
+ /* The menus and the create flyout are portalled to `<body>`, so they are OUTSIDE `#cg-route-popover`
234
+ and cannot be reached by the prefix above. `.cg-overlay` is the class `AnchoredOverlay` always
235
+ puts first, which gives the same two-class specificity index.css's own menu rules carry, and the
236
+ only declaration needed is the one index.css has no reason to hold: a route note's measure. */
237
+ .cg-overlay.cg-route-create .cg-create-note {
238
+ max-width: 240px;
239
+ margin: 6px 0 0;
240
+ padding: 0 8px 4px;
241
+ color: var(--cg-muted);
242
+ font-size: var(--lp-fs-3xs);
243
+ line-height: 1.35;
244
+ }
web/src/viz/types.ts CHANGED
@@ -82,7 +82,16 @@ export type FieldType =
82
  // STATEMENT-TERMINATOR CHARACTER, as the four notes above say
83
  | "ai_enrich";
84
 
85
- export type FieldSource = "odoo" | "overlay";
 
 
 
 
 
 
 
 
 
86
 
87
  /** Display format, the half of it the shared formatter reads. */
88
  export interface FieldFormat {
 
82
  // STATEMENT-TERMINATOR CHARACTER, as the four notes above say
83
  | "ai_enrich";
84
 
85
+ /** ⭐⭐ W42-T09 (contract C2) β€” `"topic"` joins because the GRID's union gained it.
86
+ * A topic dim reaches the client from `GET /grid/hop-topics` as a `Field` with
87
+ * `source: "topic"`, so `customer-grid/types.ts::FieldSource` widened, and
88
+ * `GridFieldFitsViz` below is the assertion that REQUIRES this file to follow. That
89
+ * assertion is the intended alarm and it fired: `npm run build` (`tsc -b`) went red
90
+ * while `npx tsc --noEmit` stayed green, because the assertion lives across the
91
+ * project-reference seam that only the build walks.
92
+ * ⚠ This file belonged to no lane when the alarm fired. AMENDMENT A9 puts it in
93
+ * W42-T09's `files:` and in lane B's FILE OWNERSHIP, which is why the line is here. */
94
+ export type FieldSource = "odoo" | "overlay" | "topic";
95
 
96
  /** Display format, the half of it the shared formatter reads. */
97
  export interface FieldFormat {
web/wiring_rows/wave42_c.py ADDED
@@ -0,0 +1,174 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Wave 42, lane B β€” cross-fence wiring rows.
2
+
3
+ β›” ONE LANE OWNS THIS FILE. A row lands in the SAME change as the wiring it asserts; the worker who
4
+ REQUESTS a wiring may not be the one who verifies it. Shape is `verify_wiring.py`'s exactly:
5
+ (feature, declaring_file, declaring_regex, mounting_file, mounting_regex)
6
+ Paths are relative to `aios-web/web/src/`.
7
+
8
+ ⚠ THE FILE NAME SAYS `_c` AND THE LANE IS B. The docstring said "lane C" until W42-T09 corrected
9
+ it; the module NAME is left alone deliberately, because `wiring_rows/__init__.py::collect` walks
10
+ the package and every other lane's module is already pinned by its own name. One wrong word in a
11
+ docstring is cheap; renaming a module three lanes import through is not.
12
+ """
13
+ from __future__ import annotations
14
+
15
+ ROWS: list[tuple[str, str, str, str, str]] = [
16
+ # ⭐⭐ W42-T09 (R1, contracts C1 + C2) β€” THE HOP QUESTION IS ALIVE AT **BOTH** DOORS.
17
+ #
18
+ # T08 built the two-hop editor inside `ColumnMenu` and gave `ColumnMenuProps` two OPTIONAL
19
+ # props to feed it; optional is what its own fence could afford, and optional means an unfed
20
+ # menu compiles, renders the Through question, and offers nothing β€” indistinguishable on
21
+ # screen from a feature nobody built. T09 feeds them. These rows are what keeps them fed.
22
+ #
23
+ # β›”β›” THE MOUNTING NEEDLE ASSERTS THE PROP **TWICE**, and that is the whole design of the row
24
+ # rather than belt-and-braces. `CustomerGrid.tsx` mounts `<ColumnMenu>` at TWO sites (the full
25
+ # column menu and the "+" create menu) and this file's own comments record the same defect
26
+ # landing twice there: a prop passed at one site and not its twin, so a column created through
27
+ # one door came out different from a column created through the other, caught by grepping and
28
+ # never by the build. `verify_wiring.py`'s loop is a single `re.search` over the raw file, so a
29
+ # one-occurrence needle goes GREEN with the hop dead at one door β€” the exact half-landing this
30
+ # repo keeps paying for. `[\s\S]*` walks across the ~340 lines between the two mounts.
31
+ #
32
+ # β›” AND IT NEEDLES THE JSX ATTRIBUTE, NEVER THE BARE NAME (D-498). The WIRINGS loop reads the
33
+ # file RAW β€” it does not run `code_only()` β€” so a needle of the bare word `hopTopics` would be
34
+ # satisfied by the JSDoc in `ColumnMenu.tsx` that EXPLAINS `hopTopics`, and deleting the real
35
+ # prop pass would leave this row green off its own documentation. `hopTopics={` is code-shaped
36
+ # and cannot be written in prose. The declaring needle carries `?:` for the same reason.
37
+ ("W42-T09 hopTopics: the hop's topic list reaches BOTH ColumnMenu mounts",
38
+ "customer-grid/ColumnMenu.tsx", r"hopTopics\?:",
39
+ "customer-grid/CustomerGrid.tsx", r"hopTopics=\{[\s\S]*hopTopics=\{"),
40
+ # β›” `hopScopeKey` IS CONTRACT C1's `scope_key`, NOT `tableKey`. It is the COHORT scope
41
+ # (`customer`, `product`, a `ut_*` key); `tableKey` is `payload.workspace.storageKey`
42
+ # (`product_table_workspace`). A bag missing `scope_key` loses every cohort leaf without a
43
+ # word, and the editor refuses to emit a `via` at all β€” so an unpassed prop here is not a
44
+ # degraded hop, it is no hop, silently, at whichever door was missed.
45
+ ("W42-T09 hopScopeKey: C1's scope_key reaches BOTH ColumnMenu mounts",
46
+ "customer-grid/ColumnMenu.tsx", r"hopScopeKey\?:",
47
+ "customer-grid/CustomerGrid.tsx", r"hopScopeKey=\{[\s\S]*hopScopeKey=\{"),
48
+
49
+ # ⭐⭐ W42-T12 (instruction 2, D-485) β€” SIX ROWS, ONE PER CONTROL THE FIELD MANAGER OFFERS.
50
+ #
51
+ # β›” WHY ROWS AT ALL WHEN THE TYPES ARE REQUIRED. `FieldsHidePanelProps` is a discriminated
52
+ # union on `manager`, and the manager arm demands all six β€” so dropping one from the mount in
53
+ # `customer-grid/Toolbar.tsx` fails `tsc -p tsconfig.app.json` today. What that CANNOT survive
54
+ # is somebody restoring the pre-T12 shape: move `manager` off the mount, or fold the arm back
55
+ # into six optional props, and the whole guarantee evaporates with every file still compiling
56
+ # and the bulk bar rendering five buttons that do nothing. These rows outlive that edit,
57
+ # because they name the required DECLARATION and the actual ATTRIBUTE, not the type system.
58
+ #
59
+ # β›” THE DECLARING NEEDLE MUST HIT THE **REQUIRED ARM**, NOT THE OPTIONAL BASE. Both spellings
60
+ # live in `FieldsHidePanel.tsx`: `onShareFields?: ((keys: string[]) => void) | null` in
61
+ # `FieldsHidePanelBase` and `onShareFields: ...` in `FieldsHidePanelManagerProps`. A needle
62
+ # that matched the base would stay green with the manager arm deleted β€” the row asserting the
63
+ # exact thing it was written to prevent. The `?` is therefore excluded by writing the colon
64
+ # immediately after the name.
65
+ #
66
+ # β›” AND THE MOUNTING NEEDLE IS THE JSX ATTRIBUTE (D-498). `verify_wiring.py`'s WIRINGS loop
67
+ # reads the file RAW β€” it has a `code_only()` stripper and does not use it β€” so a bare
68
+ # `onDeleteFields` would be satisfied by the JSDoc above `ToolbarProps` that EXPLAINS
69
+ # `onDeleteFields`, and deleting the real pass would leave the row green off its own prose.
70
+ # `onDeleteFields={onDeleteFields}` also pins that the toolbar FORWARDS its prop rather than
71
+ # inventing a local: a hand-rolled loop over the per-key handler is the one implementation
72
+ # `FieldBulkDoors` exists to forbid (N calls in a tick collapse to one stale write).
73
+ #
74
+ # β›”β›” THE FIVE DOOR ROWS WATCH THE **GRID** HOP, NOT THE TOOLBAR HOP, AND THAT IS THE WHOLE
75
+ # VALUE OF THEM. Toolbar -> panel is already tsc-enforced: drop `onDeleteFields={...}` from the
76
+ # panel mount and the `manager: true` arm errors on a missing property, so a row there watches
77
+ # a hop that cannot break. CustomerGrid -> Toolbar CAN break while compiling, because the prop
78
+ # is required but NULLABLE: `onDeleteFields={null}` at the grid mount type-checks, satisfies
79
+ # `ToolbarProps`, and renders five bulk buttons that do nothing β€” D-485 restored with the whole
80
+ # battery green. Needling the door off the BUNDLE (`fieldBulkDoors.`) is what closes that: the
81
+ # row goes red on a deletion AND on a nulling, and it also pins that the handler comes from
82
+ # `useFieldBulkDoors` rather than from a loop over the per-key prop.
83
+ # ⚠ `viewer`'S ROW STAYS ON `Toolbar.tsx` for a reason of discrimination, not of principle:
84
+ # `viewer={viewer}` appears at five sites in `CustomerGrid.tsx` (the record drawer, the share
85
+ # dialog, the column menu and both `<Toolbar>` mounts), so a needle there would be satisfied by
86
+ # any of them. In `Toolbar.tsx` the attribute occurs exactly once, at the panel mount.
87
+ ("W42-T12 viewer: the manager knows who is looking, so C2's rights pair can be asked",
88
+ "filter-kit/FieldsHidePanel.tsx", r"viewer: FieldViewer \| undefined;",
89
+ "customer-grid/Toolbar.tsx", r"viewer=\{viewer\}"),
90
+ ("W42-T12 onSetFieldsHidden: bulk hide and show reach the plural door",
91
+ "filter-kit/FieldsHidePanel.tsx",
92
+ r"onSetFieldsHidden: \(\(keys: string\[\], hidden: boolean\) => void\) \| null;",
93
+ "customer-grid/CustomerGrid.tsx", r"onSetFieldsHidden=\{fieldBulkDoors\.onSetFieldsHidden\}"),
94
+ ("W42-T12 onShareFields: one share dialog over the whole selection",
95
+ "filter-kit/FieldsHidePanel.tsx",
96
+ r"onShareFields: \(\(keys: string\[\]\) => void\) \| null;",
97
+ "customer-grid/CustomerGrid.tsx", r"onShareFields=\{fieldBulkDoors\.onShareFields\}"),
98
+ ("W42-T12 onReassignFields: R6(d)'s admin-only reassign has a handler",
99
+ "filter-kit/FieldsHidePanel.tsx",
100
+ r"onReassignFields: \(\(keys: string\[\]\) => void\) \| null;",
101
+ "customer-grid/CustomerGrid.tsx", r"onReassignFields=\{fieldBulkDoors\.onReassignFields\}"),
102
+ ("W42-T12 onDeleteFields: the batch delete door, never a loop over the per-key one",
103
+ "filter-kit/FieldsHidePanel.tsx",
104
+ r"onDeleteFields: \(\(keys: string\[\]\) => void\) \| null;",
105
+ "customer-grid/CustomerGrid.tsx", r"onDeleteFields=\{fieldBulkDoors\.onDeleteFields\}"),
106
+ ("W42-T12 onRemoveField: R6(b)'s other door, distinct from a delete",
107
+ "filter-kit/FieldsHidePanel.tsx",
108
+ r"onRemoveField: \(\(key: string\) => void\) \| null;",
109
+ "customer-grid/CustomerGrid.tsx", r"onRemoveField=\{fieldBulkDoors\.onRemoveField\}"),
110
+
111
+ # ⭐⭐ W42-T13 (instruction 2, D-485) β€” THE SEVENTH HANDLER, AND IT LIVES ON A DIFFERENT
112
+ # COMPONENT FROM T12's SIX. `onRemoveFromMine` is a `ColumnMenuProps` member, not a
113
+ # `FieldsHidePanel` one; the register's "seven handlers" span two components, which is why it
114
+ # is its own row rather than a seventh line in the block above.
115
+ #
116
+ # β›”β›” WHAT WENT WRONG IS THE GATE ON THE CONTROL ITSELF. `ColumnMenu.tsx` renders the row
117
+ # behind `!schemaLocked && canRemoveFromMine && onRemoveFromMine`, so an unfed prop does not
118
+ # degrade the control, it DELETES it β€” on screen, indistinguishable from a feature nobody
119
+ # built, and greppable only by somebody who already suspected. Neither mount fed it.
120
+ #
121
+ # β›” THE DECLARING NEEDLE PINS THE **REQUIRED** SPELLING, and the `?` is excluded by writing
122
+ # the colon straight after the name. T13 changed `onRemoveFromMine?:` to `onRemoveFromMine:`,
123
+ # so a needle carrying `\?:` (the shape T09's two rows above must use, because those props are
124
+ # still optional) would go GREEN on the exact regression this row exists to catch: put the `?`
125
+ # back and both mounts may quietly stop passing it while every file still compiles.
126
+ #
127
+ # β›” AND THE MOUNTING NEEDLE IS THE JSX ATTRIBUTE, NEVER THE BARE NAME (D-498). The WIRINGS
128
+ # loop reads the file RAW β€” it owns a `code_only()` stripper and does not use it β€” so a bare
129
+ # `onRemoveFromMine` would be satisfied by the JSDoc in `ColumnMenu.tsx` that EXPLAINS the
130
+ # prop, and deleting both real passes would leave this row green off its own documentation.
131
+ #
132
+ # β›”β›” IT WATCHES THE VALUE, NOT THE KEY, AND IT ASSERTS IT **TWICE**. `CustomerGrid.tsx`
133
+ # mounts `<ColumnMenu>` at two sites (the full column menu and the "+" create menu) and this
134
+ # file's own comments record the same prop landing at one and not its twin, repeatedly. A
135
+ # one-occurrence needle stays green with the control dead at one door, so `[\s\S]*` walks the
136
+ # ~340 lines between the mounts and demands both. Needling the BUNDLE call
137
+ # (`fieldBulkDoors.onRemoveField`) rather than `onRemoveFromMine={` alone is the other half:
138
+ # `onRemoveFromMine={() => undefined}` type-checks against the required prop, renders the row,
139
+ # and does nothing when pressed β€” D-485 turned from an absent control into the WORSE defect of
140
+ # a silent one, with the whole battery green. The bundle door is the only thing on this
141
+ # surface that speaks the refusal out loud, so pinning it pins the behaviour.
142
+ ("W42-T13 onRemoveFromMine: R6(b)'s column-menu door is fed at BOTH ColumnMenu mounts",
143
+ "customer-grid/ColumnMenu.tsx", r"onRemoveFromMine: \(\) => void;",
144
+ "customer-grid/CustomerGrid.tsx",
145
+ r"onRemoveFromMine=\{\(\) => \{[\s\S]*?fieldBulkDoors\.onRemoveField\("
146
+ r"[\s\S]*onRemoveFromMine=\{\(\) => \{[\s\S]*?fieldBulkDoors\.onRemoveField\("),
147
+
148
+ # ⭐⭐ W42-T58 (contract C4) β€” THE PER KEY VERDICT IS DECLARED IN ONE FILE AND READ IN ANOTHER.
149
+ #
150
+ # β›” THIS IS THE D-485 SHAPE AGAIN, ONE LAYER DOWN. T58 replaced N calls through the per key
151
+ # delete door with ONE call to the plural door, whose answer carries a `status`, a `code` and a
152
+ # `reason` PER KEY. The improvement is ENTIRELY in the reading: an outcome that explains every
153
+ # refusal and a caller that destructures only `deleted` compiles, ships, and leaves the person
154
+ # with exactly the silence the ticket existed to end. `tsc` cannot see that, because reading
155
+ # fewer members of a returned object is legal β€” so a row is the only thing that can.
156
+ #
157
+ # β›” THE DECLARING NEEDLE HITS THE **REQUIRED** MEMBER. `FieldDeleteResult` has four optional
158
+ # fields (`code?`, `reason?`, `contract?`, `removed?`) and this file's own T12 rows record what
159
+ # an optional-arm needle costs: it stays green while the guarantee is gone. The colon written
160
+ # immediately after the name excludes the `?` spelling, so folding `results` back to optional
161
+ # takes the row red.
162
+ #
163
+ # β›” AND THE MOUNTING NEEDLE IS THE PROPERTY ACCESS, NEVER THE BARE WORD (D-498). The WIRINGS
164
+ # loop reads the file RAW, so a needle of `results` alone would be satisfied by any prose in
165
+ # `CustomerGrid.tsx`. `outcome\.results` is code-shaped, occurs exactly once, and cannot be
166
+ # written in a sentence.
167
+ ("W42-T58 field-delete results: the plural door's per key verdict is DECLARED required and "
168
+ "READ by the grid, so a refusal reaches the person naming its own column",
169
+ "customer-grid/apiBridge.ts", r"results: FieldDeleteResult\[\];",
170
+ "customer-grid/CustomerGrid.tsx", r"outcome\.results"),
171
+ ]
172
+
173
+ #: (what was deleted, file, the pattern that must NOT match, why it matters)
174
+ DELETIONS: list[tuple[str, str, str, str]] = []
web/wiring_rows/wave42_d.py ADDED
@@ -0,0 +1,71 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Wave 42, lane D β€” cross-fence wiring rows.
2
+
3
+ β›” ONE LANE OWNS THIS FILE. A row lands in the SAME change as the wiring it asserts; the worker who
4
+ REQUESTS a wiring may not be the one who verifies it. Shape is `verify_wiring.py`'s exactly:
5
+ (feature, declaring_file, declaring_regex, mounting_file, mounting_regex)
6
+ Paths are relative to `aios-web/web/src/`.
7
+ """
8
+ from __future__ import annotations
9
+
10
+ ROWS: list[tuple[str, str, str, str, str]] = [
11
+ # ⭐⭐ W42-T16 (contract C5, lane C) β€” THE RAIL'S VIEWS LEVEL RESOLVES THROUGH ONE NAMED
12
+ # RESOLVER, AND THE SHELL ACTUALLY CALLS IT. C5's parity clause verbatim: "a
13
+ # `wiring_rows/wave42_d.py` row asserting the resolver is DECLARED and MOUNTED". Declared by
14
+ # W42-T15 in `shell/nav.ts`; mounted by W42-T16 in the shell's level.
15
+ #
16
+ # β›”β›” THE MOUNTING NEEDLE IS THE CALL WITH ITS ARGUMENT, NEVER THE BARE NAME, and that is a
17
+ # wave-wide finding rather than fussiness: the WIRINGS loop reads the file RAW (`read(dfile)`,
18
+ # no `code_only()`), so a bare identifier matches JSDoc, a `{@link}`, a type import and a
19
+ # comment. Lane E's first draft needled bare identifiers and they matched the very prose that
20
+ # EXPLAINED them, which would have held this row GREEN over deleted code. `viewsForDb\(dbWorkspaces,`
21
+ # is the call site and its first argument: `Shell.tsx` names the resolver in exactly two places,
22
+ # a comment and this call, and only the call carries `(dbWorkspaces,`.
23
+ #
24
+ # ⚠ The DECLARING needle is anchored on `export function` for the same reason: `nav.ts` writes
25
+ # the word `viewsForDb` five times in its own block comment above the definition.
26
+ (
27
+ "W42-C5: the rail's views level resolves views through `viewsForDb`",
28
+ "shell/nav.ts",
29
+ r"export function viewsForDb\(",
30
+ "shell/Shell.tsx",
31
+ r"viewsForDb\(dbWorkspaces,",
32
+ ),
33
+ # The resolver above can be mounted over an empty object and still green. This row proves the
34
+ # post-merge handover reads the existing workspace cache rather than rendering PENDING forever.
35
+ (
36
+ "W42-C5: the shell reads the cached workspace it renders the level from",
37
+ "customer-grid/apiBridge.ts",
38
+ r"export function peekWorkspace\(",
39
+ "shell/Shell.tsx",
40
+ r"peekWorkspace\(e\.key\)",
41
+ ),
42
+ # ⭐⭐ W42-T44 (ruling R12, contract C9, lane C) β€” A VIEW CAN BE MOVED TO A FOLDER THAT IS
43
+ # NOT ON SCREEN. R12 verbatim: "an item moves by drag onto a visible folder row OR a `Move
44
+ # to` picker". The drag door has been shipped since wave 32 and `verify_grid_ux` watches it;
45
+ # this row is about the SECOND door, which is the one the path navigation made necessary and
46
+ # which nothing else in the harness can see.
47
+ #
48
+ # β›”β›” THE MOUNTING NEEDLE IS THE CALL WITH ITS ARGUMENT, NEVER THE BARE NAME β€” the WIRINGS
49
+ # loop reads the file RAW (`read(mfile)`, no `code_only()`), so `setMoveFor` on its own would
50
+ # match the block comment that explains the picker and hold this row green over a menu with
51
+ # no row in it. `setMoveFor\(\{ viewId: menuView\.id,` is the menu entry's click handler and
52
+ # its first argument, and `menuView` exists nowhere but inside that menu.
53
+ #
54
+ # ⚠ BOTH HALVES LIVE IN ONE FILE, and that is the honest description of this wiring rather
55
+ # than a shortcut. What can silently break here is not two fences drifting apart: it is a
56
+ # picker that renders with no way to open it, or a row that opens nothing. So DECLARED is the
57
+ # picker's own move call (the expression that must stay identical to the drop handler's, or
58
+ # the two doors write two shapes) and MOUNTED is the menu row that reaches it. The `WIRINGS`
59
+ # loop is agnostic about the two paths being different; only the coverage leg reads them, and
60
+ # `ViewSidebar.tsx` is already listed there by three wave-20 rows.
61
+ (
62
+ "W42-R12: the view's `Move to` picker files into a folder that is not on screen",
63
+ "customer-grid/ViewSidebar.tsx",
64
+ r"onItemMove\?\.\(moveFor\.viewId, folderId \?\? ROOT_FOLDER_ID\)",
65
+ "customer-grid/ViewSidebar.tsx",
66
+ r"setMoveFor\(\{ viewId: menuView\.id,",
67
+ ),
68
+ ]
69
+
70
+ #: (what was deleted, file, the pattern that must NOT match, why it matters)
71
+ DELETIONS: list[tuple[str, str, str, str]] = []
web/wiring_rows/wave42_f.py ADDED
@@ -0,0 +1,101 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Wave 42, lane F β€” cross-fence wiring rows.
2
+
3
+ β›” ONE LANE OWNS THIS FILE. A row lands in the SAME change as the wiring it asserts; the worker who
4
+ REQUESTS a wiring may not be the one who verifies it. Shape is `verify_wiring.py`'s exactly:
5
+ (feature, declaring_file, declaring_regex, mounting_file, mounting_regex)
6
+ Paths are relative to `aios-web/web/src/`.
7
+
8
+ β›”β›” EVERY NEEDLE BELOW IS A CALL SITE, NEVER A NAME, AND THAT IS NOT STYLE.
9
+ `verify_wiring.py:1799` runs `re.search(dsym, read(dfile))` where `read()` is a plain `read_text`.
10
+ The file HAS a `code_only()` comment stripper and uses it at 1840, 1870 and 2037 β€” but NOT in this
11
+ loop. So a row needling a bare identifier matches that identifier inside its own JSDoc, and
12
+ deleting the real call site changes nothing at all: the row stays green over a dead feature. Lane E
13
+ lost a row to exactly this. Each declaring needle here therefore pins an INVOCATION with its
14
+ argument list, and each mounting needle pins a JSX prop ASSIGNMENT naming the handler it receives.
15
+ """
16
+ from __future__ import annotations
17
+
18
+ #: W42-T24 (owner instruction 10, contract C6) β€” the route navigation, one row per affordance.
19
+ #:
20
+ #: ⚠ THE MOUNTING NEEDLES USE `<RouteNav\b[^>]*` ON PURPOSE. `[^>]` cannot cross the tag's closing
21
+ #: bracket, so the match is proof the prop sits on THIS element and not on some other component
22
+ #: further down the file. It works only because every prop on the mount is a bare identifier: an
23
+ #: inline arrow would put a `>` inside the tag and break every row at once. That is a constraint on
24
+ #: `MapView.tsx`, and it is stated here because this is where it would be discovered.
25
+ _T24: list[tuple[str, str, str, str, str]] = [
26
+ (
27
+ "route-nav-opens-from-the-route-button",
28
+ "customer-grid/viewModes.tsx", r'aria-controls="cg-route-popover"',
29
+ "customer-grid/MapView.tsx", r'id="cg-route-popover"',
30
+ ),
31
+ (
32
+ "route-nav-open-is-one-click",
33
+ "customer-grid/RouteNav.tsx", r"onOpenRoute\(route\.key\)",
34
+ "customer-grid/MapView.tsx", r"<RouteNav\b[^>]*\bonOpenRoute=\{openSavedRoute\}",
35
+ ),
36
+ (
37
+ "route-nav-create-is-its-own-affordance",
38
+ "customer-grid/RouteNav.tsx", r"onCreateRoute\(\);",
39
+ "customer-grid/MapView.tsx", r"<RouteNav\b[^>]*\bonCreateRoute=\{startNewRoute\}",
40
+ ),
41
+ (
42
+ "route-nav-rename-takes-the-route-door",
43
+ "customer-grid/RouteNav.tsx", r"onRenameRoute\(renamingKey, name\)",
44
+ "customer-grid/MapView.tsx", r"<RouteNav\b[^>]*\bonRenameRoute=\{renameRoute\}",
45
+ ),
46
+ (
47
+ "route-nav-duplicate",
48
+ "customer-grid/RouteNav.tsx", r"onDuplicateRoute\(menuRoute\.key\)",
49
+ "customer-grid/MapView.tsx", r"<RouteNav\b[^>]*\bonDuplicateRoute=\{duplicateRoute\}",
50
+ ),
51
+ (
52
+ "route-nav-delete-takes-the-route-door",
53
+ "customer-grid/RouteNav.tsx", r"onDeleteRoute\(menuRoute\.key\)",
54
+ "customer-grid/MapView.tsx", r"<RouteNav\b[^>]*\bonDeleteRoute=\{removeRoute\}",
55
+ ),
56
+ (
57
+ "route-nav-share-rides-the-generic-field-door",
58
+ "customer-grid/RouteNav.tsx", r"onShareRoute\(menuRoute\.key, menuRoute\.label\)",
59
+ "customer-grid/MapView.tsx", r'kind: "field", id: `customer_data:\$\{key\}`',
60
+ ),
61
+ (
62
+ "route-nav-create-prompts-to-share",
63
+ "customer-grid/RouteNav.tsx", r"onShareRoute\(created\.key, created\.label\)",
64
+ "customer-grid/MapView.tsx", r"<RouteNav\b[^>]*\bcreated=\{createdRoute\}",
65
+ ),
66
+ (
67
+ "route-nav-reorder-prop-is-required-and-wired",
68
+ "customer-grid/RouteNav.tsx", r"onRouteReorder\(next\)",
69
+ "customer-grid/MapView.tsx", r"<RouteNav\b[^>]*\bonRouteReorder=\{reorderRail\}",
70
+ ),
71
+ (
72
+ "route-nav-folder-reorder-prop-is-required-and-wired",
73
+ "customer-grid/RouteNav.tsx", r"onFolderReorder\(next\)",
74
+ "customer-grid/MapView.tsx", r"<RouteNav\b[^>]*\bonFolderReorder=\{reorderRouteFolders\}",
75
+ ),
76
+ (
77
+ "route-nav-drag-into-a-folder",
78
+ "customer-grid/RouteNav.tsx", r"onRouteMove\(dragged, target\)",
79
+ "customer-grid/MapView.tsx", r"<RouteNav\b[^>]*\bonRouteMove=\{moveRoute\}",
80
+ ),
81
+ (
82
+ "route-nav-folder-create",
83
+ "customer-grid/RouteNav.tsx", r'onFolderCreate\("New folder", null\)',
84
+ "customer-grid/MapView.tsx", r"<RouteNav\b[^>]*\bonFolderCreate=\{createRouteFolder\}",
85
+ ),
86
+ (
87
+ "route-nav-folder-rename",
88
+ "customer-grid/RouteNav.tsx", r"onFolderRename\(renamingFolder, name\)",
89
+ "customer-grid/MapView.tsx", r"<RouteNav\b[^>]*\bonFolderRename=\{renameRouteFolder\}",
90
+ ),
91
+ (
92
+ "route-nav-folder-delete",
93
+ "customer-grid/RouteNav.tsx", r"onFolderDelete\(folderRow\.id\)",
94
+ "customer-grid/MapView.tsx", r"<RouteNav\b[^>]*\bonFolderDelete=\{deleteRouteFolder\}",
95
+ ),
96
+ ]
97
+
98
+ ROWS: list[tuple[str, str, str, str, str]] = [*_T24]
99
+
100
+ #: (what was deleted, file, the pattern that must NOT match, why it matters)
101
+ DELETIONS: list[tuple[str, str, str, str]] = []
web/wiring_rows/wave42_g.py ADDED
@@ -0,0 +1,57 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Wave 42, lane G β€” cross-fence wiring rows.
2
+
3
+ β›” ONE LANE OWNS THIS FILE. A row lands in the SAME change as the wiring it asserts; the worker who
4
+ REQUESTS a wiring may not be the one who verifies it. Shape is `verify_wiring.py`'s exactly:
5
+ (feature, declaring_file, declaring_regex, mounting_file, mounting_regex)
6
+ Paths are relative to `aios-web/web/src/`.
7
+ """
8
+ from __future__ import annotations
9
+
10
+ ROWS: list[tuple[str, str, str, str, str]] = [
11
+ # ⭐⭐ W42-T26 (owner instruction 8, R9, contract C7) β€” THE SHARE DIALOG'S FIELD DISCLOSURE.
12
+ # C7's last line says these rows PIN THE COPY, and the reason is the ticket's own trap: T25
13
+ # makes the behaviour correct while nothing on screen changes, so the disclosure is the half
14
+ # that gets quietly reworded away by a later tidy-up with every other gate still green.
15
+ #
16
+ # ⚠ BOTH HALVES NAME THE SAME FILE, WHICH IS LEGITIMATE HERE AND ONLY BECAUSE THE TWO REGEXES
17
+ # ASSERT DIFFERENT FACTS: the declaring side proves the SENTENCE still exists verbatim, the
18
+ # mounting side proves the branch that RENDERS it is still wired. A row whose two halves assert
19
+ # one fact proves half of what it claims.
20
+ #
21
+ # β›” THE COPY LIVES IN `const` STRING LITERALS, NOT IN JSX TEXT, AND THAT IS WHAT MAKES THESE
22
+ # ROWS POSSIBLE. `re.search` runs over the literal file text and prettier wraps JSX text across
23
+ # lines, so a needle spanning a wrap never matches. A string literal is never re-wrapped.
24
+ ("W42-T26/C7 the shared view names WHICH FIELDS TRAVEL with it",
25
+ "shell/ShareDialog.tsx", r"Sharing a view also shares the fields it uses",
26
+ "shell/ShareDialog.tsx", r"\{VIEW_FIELD_TRAVEL\}"),
27
+ # ⚠ THE NON-OBVIOUS CLAUSE, PINNED ON ITS OWN. A sharer reasons about the columns they can SEE;
28
+ # a filter can test a column that is not on screen and the grant hands that column over too.
29
+ # The done-when names it separately, so it gets its own row rather than riding on the one above.
30
+ ("W42-T26/C7 the FILTER's fields are named specifically",
31
+ "shell/ShareDialog.tsx", r"A filter can test a column that is not on screen",
32
+ "shell/ShareDialog.tsx", r"\{VIEW_FILTER_FIELDS\}"),
33
+ ("W42-T26/C7 the grant is disclosed as TOPIC-WIDE, not view-only",
34
+ "shell/ShareDialog.tsx", r"shows on every view of this database, not only on this one",
35
+ "shell/ShareDialog.tsx", r"\{VIEW_FIELD_TOPIC_WIDE\}"),
36
+ # β›” THE REFUSAL HALF IS THE ONE THAT CANNOT BE OBSERVED ON SCREEN YET: `refusedFieldKeys` is
37
+ # lane A's server work under the same contract and returns nothing today, so the block renders
38
+ # nothing. That is exactly why it needs a row. The declaring side proves the client still READS
39
+ # the response key; the mounting side proves the list is still RENDERED with the server's own
40
+ # reason beside each key. Without this pair, "correct on arrival" is an unchecked claim
41
+ # [[a-declared-gate-is-an-unchecked-claim]].
42
+ #
43
+ # β›” THE NEEDLE IS THE CALL SITE, NOT THE BARE KEY NAME, AND THAT IS NOT A STYLE CHOICE. The
44
+ # WIRINGS loop matches against `read(dfile)` RAW, never `code_only()`, so comments are in
45
+ # scope: a bare `refusedFieldKeys` matched the JSDoc in `ShareDialog.tsx` that EXPLAINS the
46
+ # key, and the row would have stayed green off its own explanation with the read deleted. Same
47
+ # root cause as `code_only`'s docstring records, opposite sign.
48
+ ("W42-T26/C7 a field that could NOT be included is listed with its reason",
49
+ "shell/ShareDialog.tsx", r"fieldNotes\(answered\?\.refusedFieldKeys\)",
50
+ "shell/ShareDialog.tsx", r"refusedFields\.map\("),
51
+ ("W42-T26/C7 the fields that DID travel are named after a save",
52
+ "shell/ShareDialog.tsx", r"fieldNotes\(answered\?\.sharedFieldKeys\)",
53
+ "shell/ShareDialog.tsx", r"\{SHARED_FIELDS_LEAD\}"),
54
+ ]
55
+
56
+ #: (what was deleted, file, the pattern that must NOT match, why it matters)
57
+ DELETIONS: list[tuple[str, str, str, str]] = []