fsanyoto commited on
Commit
f5696cb
·
verified ·
1 Parent(s): e13472e

Deploy AIOS web (React glide grid + FastAPI slice)

Browse files
This view is limited to 50 files because it contains too many changes.   See raw diff
Files changed (50) hide show
  1. RELEASES.json +2 -429
  2. VERSION +1 -1
  3. api/routes_admin.py +73 -14
  4. api/routes_auth.py +260 -1
  5. api/routes_connectors.py +95 -0
  6. api/routes_keychain.py +227 -5
  7. api/routes_sheet.py +5 -0
  8. platform/aios_grid_fields.json +16 -11
  9. platform/core/measure_resolve.py +22 -8
  10. platform/core/perm_migrate.py +2 -2
  11. platform/core/relations.py +206 -0
  12. platform/core/user_tables.py +143 -0
  13. platform/core/users.py +358 -2
  14. platform/harness/amazon_client.py +195 -87
  15. platform/harness/measure_filter.py +70 -25
  16. platform/model/topics/odoo_customers.yml +10 -5
  17. platform/modules/customer_data.py +16 -104
  18. platform/modules/customers.py +3 -7
  19. platform/modules/digest.py +1 -2
  20. platform/modules/outreach.py +1 -1
  21. web/public/sample_customers.json +32 -35
  22. web/src/automation/AutomationSurface.tsx +46 -13
  23. web/src/connectors/DatabasesTab.tsx +72 -19
  24. web/src/customer-grid/CustomerGrid.tsx +27 -3
  25. web/src/customer-grid/RecordDetail.tsx +121 -6
  26. web/src/customer-grid/apiBridge.ts +50 -6
  27. web/src/customer-grid/timeSeriesData.ts +2 -1
  28. web/src/home/HomePage.tsx +18 -6
  29. web/src/settings/SecurityPane.tsx +147 -0
  30. web/src/settings/SettingsModal.tsx +10 -0
  31. web/src/settings/permsModel.ts +3 -0
  32. web/src/sheet/BindingEditor.tsx +572 -453
  33. web/src/sheet/DrillModal.tsx +48 -118
  34. web/src/sheet/KeyTips.tsx +32 -20
  35. web/src/sheet/Ribbon.tsx +112 -7
  36. web/src/sheet/SheetGrid.tsx +198 -25
  37. web/src/sheet/SheetPage.tsx +180 -21
  38. web/src/sheet/a1.ts +9 -0
  39. web/src/sheet/bindingRefs.ts +92 -0
  40. web/src/sheet/formulaAssist.ts +47 -4
  41. web/src/sheet/formulaEval.ts +431 -31
  42. web/src/sheet/functionCatalog.ts +62 -0
  43. web/src/sheet/ribbonData.tsx +596 -10
  44. web/src/sheet/ribbonInsert.tsx +10 -2
  45. web/src/sheet/ribbonView.tsx +25 -4
  46. web/src/sheet/rules.ts +13 -0
  47. web/src/sheet/sheetState.ts +165 -91
  48. web/src/sheet/shortcuts.ts +39 -1
  49. web/src/sheet/types.ts +17 -1
  50. web/src/shell/LoginPage.tsx +334 -65
RELEASES.json CHANGED
@@ -1,431 +1,4 @@
1
  {
2
- "current": "25a941a",
3
- "releases": [
4
- {
5
- "version": "v71",
6
- "sha": "96143dc",
7
- "date": "2026-09-04",
8
- "subject": "release v71 - wave 51, QA'd 24 PASS / 6 FAIL / 5 UNPROVEN"
9
- },
10
- {
11
- "version": "v70",
12
- "sha": "eedfb6a",
13
- "date": "2026-09-03",
14
- "subject": "release v70 - wave 50 (grid analytics, the Sheet as a spreadsheet, view trash and audit)"
15
- },
16
- {
17
- "version": "v69",
18
- "sha": "8598f56",
19
- "date": "2026-09-02",
20
- "subject": "release v69: wave48-continuation validated + hotfixes v67/v68/d4e3e31 + go-live QA repairs (Supplier option limit, optio"
21
- },
22
- {
23
- "version": "v68",
24
- "sha": "62b065a",
25
- "date": "2026-09-01",
26
- "subject": "release v68: unified holiday date offsets"
27
- },
28
- {
29
- "version": "v67",
30
- "sha": "3b22419",
31
- "date": "2026-09-01",
32
- "subject": "release v67"
33
- },
34
- {
35
- "version": "v66",
36
- "sha": "73c94f0",
37
- "date": "2026-08-31",
38
- "subject": "release v66"
39
- },
40
- {
41
- "version": "v65",
42
- "sha": "9f6cfed",
43
- "date": "2026-08-31",
44
- "subject": "release v65"
45
- },
46
- {
47
- "version": "v64",
48
- "sha": "bb8985c",
49
- "date": "2026-08-31",
50
- "subject": "release v64"
51
- },
52
- {
53
- "version": "v63",
54
- "sha": "ec75cb8",
55
- "date": "2026-08-31",
56
- "subject": "release v63"
57
- },
58
- {
59
- "version": "v62",
60
- "sha": "2c8f702",
61
- "date": "2026-08-31",
62
- "subject": "release v62"
63
- },
64
- {
65
- "version": "v61",
66
- "sha": "bbc4c07",
67
- "date": "2026-08-30",
68
- "subject": "v61 - wave 46 hotfix: D-590 schema overlay reaches the grid read (all three assemblies), D-599 route to zone association"
69
- },
70
- {
71
- "version": "v60",
72
- "sha": "dd1b062",
73
- "date": "2026-08-30",
74
- "subject": "v60 - wave 46"
75
- },
76
- {
77
- "version": "v59",
78
- "sha": "3cb73ce",
79
- "date": "2026-08-29",
80
- "subject": "release v59"
81
- },
82
- {
83
- "version": "v58",
84
- "sha": "c526ced",
85
- "date": "2026-08-29",
86
- "subject": "release v58"
87
- },
88
- {
89
- "version": "v57",
90
- "sha": "4859c03",
91
- "date": "2026-08-29",
92
- "subject": "release v57"
93
- },
94
- {
95
- "version": "v56",
96
- "sha": "2970b72",
97
- "date": "2026-08-28",
98
- "subject": "release v56"
99
- },
100
- {
101
- "version": "v55",
102
- "sha": "b766b90",
103
- "date": "2026-08-28",
104
- "subject": "release v55"
105
- },
106
- {
107
- "version": "v54",
108
- "sha": "6a8e99a",
109
- "date": "2026-08-27",
110
- "subject": "release v54"
111
- },
112
- {
113
- "version": "v53",
114
- "sha": "89ed2cb",
115
- "date": "2026-08-24",
116
- "subject": "release v53"
117
- },
118
- {
119
- "version": "v52",
120
- "sha": "8263493",
121
- "date": "2026-08-23",
122
- "subject": "release v52"
123
- },
124
- {
125
- "version": "v51",
126
- "sha": "5740d20",
127
- "date": "2026-08-23",
128
- "subject": "release v51"
129
- },
130
- {
131
- "version": "v50",
132
- "sha": "8027c83",
133
- "date": "2026-08-23",
134
- "subject": "release v50"
135
- },
136
- {
137
- "version": "v49",
138
- "sha": "9a14c01",
139
- "date": "2026-08-23",
140
- "subject": "release v49"
141
- },
142
- {
143
- "version": "v48",
144
- "sha": "3c69fd9",
145
- "date": "2026-08-23",
146
- "subject": "release v48"
147
- },
148
- {
149
- "version": "v47",
150
- "sha": "917f9a0",
151
- "date": "2026-08-23",
152
- "subject": "release v47"
153
- },
154
- {
155
- "version": "v46",
156
- "sha": "a8dc531",
157
- "date": "2026-08-23",
158
- "subject": "release v46"
159
- },
160
- {
161
- "version": "v45",
162
- "sha": "0b2b501",
163
- "date": "2026-08-23",
164
- "subject": "release v45"
165
- },
166
- {
167
- "version": "v44",
168
- "sha": "a7877aa",
169
- "date": "2026-08-23",
170
- "subject": "Hotfix: allow renaming the active Map view"
171
- },
172
- {
173
- "version": "v43",
174
- "sha": "e2ba461",
175
- "date": "2026-08-23",
176
- "subject": "release v43"
177
- },
178
- {
179
- "version": "v42",
180
- "sha": "25b885e",
181
- "date": "2026-08-23",
182
- "subject": "release v42"
183
- },
184
- {
185
- "version": "v41",
186
- "sha": "1d6adcc",
187
- "date": "2026-08-22",
188
- "subject": "v41 vertical route navigation"
189
- },
190
- {
191
- "version": "v40",
192
- "sha": "1451837",
193
- "date": "2026-08-22",
194
- "subject": "release v40 route UI correction"
195
- },
196
- {
197
- "version": "v39",
198
- "sha": "a78bdf0",
199
- "date": "2026-08-21",
200
- "subject": "W39 clean stale migration targets"
201
- },
202
- {
203
- "version": "v38",
204
- "sha": "a556631",
205
- "date": "2026-08-21",
206
- "subject": "W39 reversible Live store cutover"
207
- },
208
- {
209
- "version": "v37",
210
- "sha": "1ddd8cf",
211
- "date": "2026-08-21",
212
- "subject": "W39: coalesce derived workspace reads"
213
- },
214
- {
215
- "version": "v36",
216
- "sha": "51db3b7",
217
- "date": "2026-08-21",
218
- "subject": "W39 share-field oid repair"
219
- },
220
- {
221
- "version": "v35",
222
- "sha": "0f64212",
223
- "date": "2026-08-21",
224
- "subject": "W39 visual QA fixture"
225
- },
226
- {
227
- "version": "v34",
228
- "sha": "cb4caa1",
229
- "date": "2026-08-21",
230
- "subject": "W39 Staging PostgreSQL egress controls"
231
- },
232
- {
233
- "version": "v33",
234
- "sha": "2b115e5",
235
- "date": "2026-08-21",
236
- "subject": "W39: stop nonproduction Postgres background egress"
237
- },
238
- {
239
- "version": "v32",
240
- "sha": "b47b27c",
241
- "date": "2026-08-21",
242
- "subject": "W39: repair Staging Postgres projection"
243
- },
244
- {
245
- "version": "v31",
246
- "sha": "8880a49",
247
- "date": "2026-08-21",
248
- "subject": "v31: Wave 39 staging candidate"
249
- },
250
- {
251
- "version": "v30",
252
- "sha": "71776ca",
253
- "date": "2026-08-20",
254
- "subject": "v30: W39-T29 Member-owned View first-share hotfix"
255
- },
256
- {
257
- "version": "v29",
258
- "sha": "55ced50",
259
- "date": "2026-08-18",
260
- "subject": "v29: the build staging has been running since 2026-08-18 (55ced50)."
261
- },
262
- {
263
- "version": "v28",
264
- "sha": "2793e4b",
265
- "date": "2026-08-18",
266
- "subject": "release v28"
267
- },
268
- {
269
- "version": "v27",
270
- "sha": "c05a794",
271
- "date": "2026-08-18",
272
- "subject": "release v27"
273
- },
274
- {
275
- "version": "v25",
276
- "sha": "bc24829",
277
- "date": "2026-08-14",
278
- "subject": "v25 - wave 32's LIVE build (deployed 2026-08-13, bc24829)"
279
- },
280
- {
281
- "version": "v26",
282
- "sha": "6a642e1",
283
- "date": "2026-08-14",
284
- "subject": "v26 - wave 33's build (deployed 2026-08-14, 6a642e1)"
285
- },
286
- {
287
- "version": "v24",
288
- "sha": "514d829",
289
- "date": "2026-08-09",
290
- "subject": "release v24"
291
- },
292
- {
293
- "version": "v23",
294
- "sha": "44cc283",
295
- "date": "2026-08-09",
296
- "subject": "release v23"
297
- },
298
- {
299
- "version": "v22",
300
- "sha": "f14e199",
301
- "date": "2026-08-09",
302
- "subject": "release v22"
303
- },
304
- {
305
- "version": "v21",
306
- "sha": "5fdffce",
307
- "date": "2026-08-09",
308
- "subject": "release v21"
309
- },
310
- {
311
- "version": "v20",
312
- "sha": "442e4a1",
313
- "date": "2026-08-09",
314
- "subject": "release v20"
315
- },
316
- {
317
- "version": "v19",
318
- "sha": "94cb4a4",
319
- "date": "2026-08-09",
320
- "subject": "release v19"
321
- },
322
- {
323
- "version": "v18",
324
- "sha": "0106ef9",
325
- "date": "2026-08-09",
326
- "subject": "release v18"
327
- },
328
- {
329
- "version": "v17",
330
- "sha": "308240c",
331
- "date": "2026-08-09",
332
- "subject": "release v17"
333
- },
334
- {
335
- "version": "v16",
336
- "sha": "a804df5",
337
- "date": "2026-08-09",
338
- "subject": "release v16"
339
- },
340
- {
341
- "version": "v15",
342
- "sha": "6b84d72",
343
- "date": "2026-08-09",
344
- "subject": "release v15"
345
- },
346
- {
347
- "version": "v14",
348
- "sha": "bee5eaf",
349
- "date": "2026-08-07",
350
- "subject": "release v14"
351
- },
352
- {
353
- "version": "v13",
354
- "sha": "314c0e3",
355
- "date": "2026-08-06",
356
- "subject": "release v13"
357
- },
358
- {
359
- "version": "v12",
360
- "sha": "4908f39",
361
- "date": "2026-08-06",
362
- "subject": "release v12"
363
- },
364
- {
365
- "version": "v11",
366
- "sha": "3126617",
367
- "date": "2026-08-05",
368
- "subject": "release v11"
369
- },
370
- {
371
- "version": "v10",
372
- "sha": "43f8042",
373
- "date": "2026-08-05",
374
- "subject": "release v10"
375
- },
376
- {
377
- "version": "v9",
378
- "sha": "2e26f57",
379
- "date": "2026-08-05",
380
- "subject": "release v9"
381
- },
382
- {
383
- "version": "v8",
384
- "sha": "8073b3e",
385
- "date": "2026-08-05",
386
- "subject": "release v8"
387
- },
388
- {
389
- "version": "v7",
390
- "sha": "b1c5a7e",
391
- "date": "2026-08-05",
392
- "subject": "release v7"
393
- },
394
- {
395
- "version": "v6",
396
- "sha": "a344020",
397
- "date": "2026-08-05",
398
- "subject": "release v6"
399
- },
400
- {
401
- "version": "v5",
402
- "sha": "c0b0fbb",
403
- "date": "2026-08-05",
404
- "subject": "release v5"
405
- },
406
- {
407
- "version": "v4",
408
- "sha": "de5037f",
409
- "date": "2026-08-05",
410
- "subject": "release v4"
411
- },
412
- {
413
- "version": "v3",
414
- "sha": "6b9fa62",
415
- "date": "2026-08-05",
416
- "subject": "release v3"
417
- },
418
- {
419
- "version": "v2",
420
- "sha": "fd05861",
421
- "date": "2026-08-04",
422
- "subject": "release v2"
423
- },
424
- {
425
- "version": "v1",
426
- "sha": "5b4e2c4",
427
- "date": "2026-08-04",
428
- "subject": "release v1"
429
- }
430
- ]
431
  }
 
1
  {
2
+ "current": "d605a17",
3
+ "releases": []
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4
  }
VERSION CHANGED
@@ -1 +1 @@
1
- 25a941a
 
1
+ d605a17
api/routes_admin.py CHANGED
@@ -75,10 +75,7 @@ def system_data_inspector(session: Session = Depends(require_session)):
75
  _UNAME_EMAIL_RE = re.compile(r"^[a-z0-9][a-z0-9._%+-]*@[a-z0-9][a-z0-9.-]*\.[a-z]{2,24}$")
76
  #: RFC 5321's cap on a whole address. The slug form keeps its own 32 via `_UNAME_RE`.
77
  _UNAME_MAX = 254
78
- #: Passwords are PBKDF2-200k, which is only as strong as what it is given. The Streamlit dialog
79
- #: enforces nothing; this does, and the two are allowed to differ because only one of them is
80
- #: reachable from the internet.
81
- _MIN_PW = 8
82
  _ROLES = ("user", "admin")
83
 
84
 
@@ -131,6 +128,12 @@ def _view(uname, rec, governed=None, st=None, surface_keys=None):
131
  # The session-revocation handle. An admin needs it: it is the only visible evidence
132
  # that "sign them out everywhere" actually happened.
133
  "epoch": int(rec.get("epoch") or 0),
 
 
 
 
 
 
134
  # S3 ask 4 — one sentence for the roster's Access column, so the list does not need
135
  # a /perms round trip per row to fill one cell. Computed from the same record the
136
  # editor will open, so the two cannot disagree.
@@ -213,10 +216,14 @@ def _clean_username(v):
213
  return uname
214
 
215
 
216
- def _clean_password(v):
217
  pw = str(v or "")
218
- if len(pw) < _MIN_PW:
219
- raise err(400, "weak_password", f"a password must be at least {_MIN_PW} characters")
 
 
 
 
220
  return pw
221
 
222
 
@@ -326,13 +333,13 @@ def create_user(body: dict = Body(default=None), session: Session = Depends(admi
326
  body = body or {}
327
  _require_store()
328
  uname = _clean_username(body.get("username"))
329
- pw = _clean_password(body.get("password"))
 
 
330
  role = _clean_role(body.get("role") or "user")
331
  bus = _clean_bus(body.get("bus") if body.get("bus") is not None else "all")
332
  modules = _clean_modules(body.get("modules") if body.get("modules") is not None else "all")
333
- name = str(body.get("name") or "").strip() or uname
334
  agent = str(body.get("agent") or "").strip() or None
335
- email = str(body.get("email") or "").strip() or None
336
 
337
  _reg_before = _registry()
338
  if uname in _reg_before:
@@ -365,8 +372,11 @@ def create_user(body: dict = Body(default=None), session: Session = Depends(admi
365
  f"address for this account.")
366
  # Wave 18 (C1-TENANT): an admin creates accounts in their OWN company, never another's —
367
  # the tenant is stamped from the session, not taken from the body.
368
- users.create_user(uname, pw, name, role=role, bus=bus, modules=modules,
369
- agent=agent, email=email, tenant=_tenant_of(session.user))
 
 
 
370
  reg = _registry()
371
  if uname not in reg:
372
  # The store accepted the write and does not have it. Reporting 201 here would be the
@@ -456,9 +466,15 @@ def set_password(username: str, body: dict = Body(default=None),
456
  # Wave 18 (C1-TENANT): a cross-tenant username answers exactly like a missing one —
457
  # 404, never 403, because "that account exists in another company" is itself a leak.
458
  raise err(404, "no_such_user", f"no account named {uname!r}")
459
- pw = _clean_password((body or {}).get("password"))
 
460
  before = int(reg[uname].get("epoch") or 0)
461
- users.set_password(uname, pw)
 
 
 
 
 
462
  after = int((_registry().get(uname) or {}).get("epoch") or 0)
463
  if after <= before:
464
  # The whole value of this route is the revocation. If the epoch did not move, the sessions
@@ -468,6 +484,49 @@ def set_password(username: str, body: dict = Body(default=None),
468
  return Response(status_code=204)
469
 
470
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
471
  # ── C-PERM (wave 15): per-module access + permanent filters + hidden fields ──────────────────
472
  #: The modules the permission editor governs — the GRID surfaces, the ones with a field schema
473
  #: to filter and hide. Amendment 6 shipped the wall on `customer_data` alone and said this list
 
75
  _UNAME_EMAIL_RE = re.compile(r"^[a-z0-9][a-z0-9._%+-]*@[a-z0-9][a-z0-9.-]*\.[a-z]{2,24}$")
76
  #: RFC 5321's cap on a whole address. The slug form keeps its own 32 via `_UNAME_RE`.
77
  _UNAME_MAX = 254
78
+ #: Password policy lives in core.users so this route and self-service rotation cannot disagree.
 
 
 
79
  _ROLES = ("user", "admin")
80
 
81
 
 
128
  # The session-revocation handle. An admin needs it: it is the only visible evidence
129
  # that "sign them out everywhere" actually happened.
130
  "epoch": int(rec.get("epoch") or 0),
131
+ # Administrators need the rotation state, never the credential history behind it.
132
+ "passwordChangedAt": users.password_changed_at(rec),
133
+ "passwordExpired": users.password_expired(rec),
134
+ # The reset controls need enrolment state, never the secret, hashes or code count.
135
+ "mfaEnrolled": users.mfa_enrolled(rec),
136
+ "mfaEnrolledAt": rec.get("mfa_enrolled_at") or None,
137
  # S3 ask 4 — one sentence for the roster's Access column, so the list does not need
138
  # a /perms round trip per row to fill one cell. Computed from the same record the
139
  # editor will open, so the two cannot disagree.
 
216
  return uname
217
 
218
 
219
+ def _clean_password(v, username=None, name=None, email=None, record=None):
220
  pw = str(v or "")
221
+ failures = users.password_failures(pw, username=username, name=name, email=email,
222
+ record=record)
223
+ if failures:
224
+ # Name every broken rule so the caller can correct the value without guessing the policy.
225
+ raise err(400, "weak_password",
226
+ "That password does not meet the policy: " + str(users.PasswordPolicyError(failures)))
227
  return pw
228
 
229
 
 
333
  body = body or {}
334
  _require_store()
335
  uname = _clean_username(body.get("username"))
336
+ name = str(body.get("name") or "").strip() or uname
337
+ email = str(body.get("email") or "").strip() or None
338
+ pw = _clean_password(body.get("password"), username=uname, name=name, email=email)
339
  role = _clean_role(body.get("role") or "user")
340
  bus = _clean_bus(body.get("bus") if body.get("bus") is not None else "all")
341
  modules = _clean_modules(body.get("modules") if body.get("modules") is not None else "all")
 
342
  agent = str(body.get("agent") or "").strip() or None
 
343
 
344
  _reg_before = _registry()
345
  if uname in _reg_before:
 
372
  f"address for this account.")
373
  # Wave 18 (C1-TENANT): an admin creates accounts in their OWN company, never another's —
374
  # the tenant is stamped from the session, not taken from the body.
375
+ try:
376
+ users.create_user(uname, pw, name, role=role, bus=bus, modules=modules,
377
+ agent=agent, email=email, tenant=_tenant_of(session.user))
378
+ except users.PasswordPolicyError as exc:
379
+ raise err(400, "weak_password", "That password does not meet the policy: " + str(exc))
380
  reg = _registry()
381
  if uname not in reg:
382
  # The store accepted the write and does not have it. Reporting 201 here would be the
 
466
  # Wave 18 (C1-TENANT): a cross-tenant username answers exactly like a missing one —
467
  # 404, never 403, because "that account exists in another company" is itself a leak.
468
  raise err(404, "no_such_user", f"no account named {uname!r}")
469
+ pw = _clean_password((body or {}).get("password"), username=uname,
470
+ name=reg[uname].get("name"), email=reg[uname].get("email"), record=reg[uname])
471
  before = int(reg[uname].get("epoch") or 0)
472
+ try:
473
+ # This route just checked strength AND reuse against its record. Spend the history's
474
+ # PBKDF2 passes once; the core still merges the rotation into the fresh update document.
475
+ users.set_password(uname, pw, enforce=False)
476
+ except users.PasswordPolicyError as exc:
477
+ raise err(400, "weak_password", "That password does not meet the policy: " + str(exc))
478
  after = int((_registry().get(uname) or {}).get("epoch") or 0)
479
  if after <= before:
480
  # The whole value of this route is the revocation. If the epoch did not move, the sessions
 
484
  return Response(status_code=204)
485
 
486
 
487
+ @router.post("/admin/users/{username}/mfa/reset", status_code=204)
488
+ def reset_mfa(username: str, session: Session = Depends(admin_gate)):
489
+ """Clear a lost factor and revoke every session; the person enrols their own phone again.
490
+
491
+ The administrator never sees or sets a user's secret. Removing it opens the enrolment door
492
+ at next sign-in; the atomic epoch bump closes every session that predates this reset.
493
+ """
494
+ reg = _registry()
495
+ uname = str(username or "").strip().lower()
496
+ if uname not in reg or _tenant_of(reg[uname]) != _tenant_of(session.user):
497
+ # A cross-tenant username answers exactly like a missing one: naming another company's
498
+ # account, even only to refuse the reset, would itself disclose that the account exists.
499
+ raise err(404, "no_such_user", f"no account named {uname!r}")
500
+ before = int(reg[uname].get("epoch") or 0)
501
+ users.clear_mfa(uname)
502
+ after = int((_registry().get(uname) or {}).get("epoch") or 0)
503
+ if after <= before:
504
+ # Revocation is the whole value of this door. A 204 without a moved epoch would claim
505
+ # the lost phone's sessions died when the store did not persist that change.
506
+ raise err(503, "store_unavailable", "the reset did not persist - outstanding sessions were NOT "
507
+ "revoked")
508
+ return Response(status_code=204)
509
+
510
+
511
+ @router.post("/admin/users/{username}/password/expire", status_code=204)
512
+ def expire_password(username: str, session: Session = Depends(admin_gate)):
513
+ """Force the account through password rotation without choosing its replacement secret."""
514
+ reg = _registry()
515
+ uname = str(username or "").strip().lower()
516
+ if uname not in reg or _tenant_of(reg[uname]) != _tenant_of(session.user):
517
+ # Same missing-account answer across tenants: the reset door cannot enumerate others.
518
+ raise err(404, "no_such_user", f"no account named {uname!r}")
519
+ before = int(reg[uname].get("epoch") or 0)
520
+ users.set_must_change_password(uname, True)
521
+ after = int((_registry().get(uname) or {}).get("epoch") or 0)
522
+ if after <= before:
523
+ # A flag without revocation would leave the old sessions usable. Prove the write before
524
+ # telling an administrator the reset is in effect, just like the password setter above.
525
+ raise err(503, "store_unavailable",
526
+ "the forced password rotation did not persist. Outstanding sessions were NOT revoked")
527
+ return Response(status_code=204)
528
+
529
+
530
  # ── C-PERM (wave 15): per-module access + permanent filters + hidden fields ──────────────────
531
  #: The modules the permission editor governs — the GRID surfaces, the ones with a field schema
532
  #: to filter and hide. Amendment 6 shipped the wall on `customer_data` alone and said this list
api/routes_auth.py CHANGED
@@ -143,6 +143,7 @@ def login(request: Request, response: Response, body: dict = Body(default=None))
143
  body = body or {}
144
  uname = str(body.get("username") or "").strip().lower()
145
  pw = str(body.get("password") or "")
 
146
 
147
  # Throttle on the IDENTIFIER alone: the tenant is not known until the credential resolves,
148
  # and a per-(tenant, uname) key would let an attacker reset their budget by rotating slugs.
@@ -179,7 +180,48 @@ def login(request: Request, response: Response, body: dict = Body(default=None))
179
  _note_failure(throttle_key)
180
  raise err(401, "invalid_credentials", "that username and password do not match")
181
 
182
- _clear_failures(throttle_key)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
183
 
184
  # ⭐ WAVE 40, R2 — SINGLE SESSION, NEWEST WINS. Signing in here signs out every session this
185
  # account already holds, so a forgotten sign-in on someone else's computer cannot lock the
@@ -231,9 +273,226 @@ def login(request: Request, response: Response, body: dict = Body(default=None))
231
  import deps as _deps
232
  if not user.get("qa_runner"):
233
  _deps.note_active(user["username"])
 
 
 
234
  return {"user": _public_user(user)}
235
 
236
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
237
  @router.post("/logout", status_code=204)
238
  def logout(request: Request):
239
  """204 and the cookie is cleared. Deliberately NOT session-gated: logging out must work from
 
143
  body = body or {}
144
  uname = str(body.get("username") or "").strip().lower()
145
  pw = str(body.get("password") or "")
146
+ code = str(body.get("mfaCode") or "").strip()
147
 
148
  # Throttle on the IDENTIFIER alone: the tenant is not known until the credential resolves,
149
  # and a per-(tenant, uname) key would let an attacker reset their budget by rotating slugs.
 
180
  _note_failure(throttle_key)
181
  raise err(401, "invalid_credentials", "that username and password do not match")
182
 
183
+ # W57-T35 / C12: a correct credential may still need rotation. Check BEFORE bumping or
184
+ # minting so an expired password gets the change door and no session, without counting a
185
+ # successful authentication against the guessing budget. Neither synthetic identity has a
186
+ # stored password clock, and the emergency master must keep its store-outage escape path.
187
+ if not (user.get("qa_runner") or user.get("emergency_master")):
188
+ try:
189
+ rec = (users.registry() or {}).get(user["username"])
190
+ except Exception:
191
+ rec = None
192
+ if users.password_expired(rec):
193
+ raise err(403, "password_expired", "Your password has expired. Set a new one to continue.")
194
+ if rec and not users.password_changed_at(rec):
195
+ # Legacy records start their clock at first sign-in after this ships. The background
196
+ # merge is fail-silent like touch_login, so backfilling can never deny a good login.
197
+ try:
198
+ users.stamp_password_age(user["username"])
199
+ except Exception:
200
+ pass
201
+
202
+ # W57-T36 / C12: every STORED account needs its second factor before any cookie is minted.
203
+ # The same TWO identities as the epoch bump are exempt: qa_runner has no registry record
204
+ # at all; emergency_master must keep the break-glass path that exists for a store outage.
205
+ # Neither has a stored factor this route can require without defeating its existing purpose.
206
+ if not (user.get("qa_runner") or user.get("emergency_master")):
207
+ try:
208
+ rec = (users.registry() or {}).get(user["username"])
209
+ except Exception:
210
+ rec = None
211
+ if not users.mfa_enrolled(rec):
212
+ # Correct credentials needing setup are not a guess. Counting them would lock the
213
+ # person out of the unauthenticated enrolment door that repairs their account.
214
+ raise err(403, "mfa_enrolment_required", "This account needs two step sign in. Set up your "
215
+ "authenticator app to continue.")
216
+ if not code:
217
+ # A missing factor is a prompt, not a failed attempt at guessing one.
218
+ raise err(401, "mfa_required", "Enter the 6 digit code from your authenticator app.")
219
+ # TOTP FIRST: redemption consumes a recovery code. Do not spend one when the app's
220
+ # ordinary code already proves the factor, and never reset the guess budget on password.
221
+ if not (users.totp_valid(rec.get("mfa_secret"), code)
222
+ or users.consume_recovery_code(user["username"], code)):
223
+ _note_failure(throttle_key)
224
+ raise err(401, "mfa_invalid", _MFA_INVALID)
225
 
226
  # ⭐ WAVE 40, R2 — SINGLE SESSION, NEWEST WINS. Signing in here signs out every session this
227
  # account already holds, so a forgotten sign-in on someone else's computer cannot lock the
 
273
  import deps as _deps
274
  if not user.get("qa_runner"):
275
  _deps.note_active(user["username"])
276
+ # MOVED from password success: only a WHOLE successful login clears the budget. Otherwise
277
+ # a known password would reset the counter before every wrong second-factor guess.
278
+ _clear_failures(throttle_key)
279
  return {"user": _public_user(user)}
280
 
281
 
282
+ # ------------------------------------------------------------------ second factor (W57-T36 / C12)
283
+ _MFA_INVALID = ("That code is not right. Check your authenticator app and try the next one.")
284
+ _MFA_ALREADY_ENROLLED = ("Two step sign in is already on for this account. Ask an administrator "
285
+ "to reset it if you lost your phone.")
286
+
287
+
288
+ def _mfa_credentials(uname, password):
289
+ """The MFA doors share login's credential check and guessing budget, including aliases."""
290
+ throttle_key = ("*", uname)
291
+ wait = _throttled(throttle_key)
292
+ if wait:
293
+ raise err(429, "too_many_attempts",
294
+ f"too many failed attempts. Try again in {wait} seconds")
295
+ # Resolve the staging identity without touching tenant #0's store, then REFUSE it: no
296
+ # record exists to enrol. The emergency master is refused for the same no-stored-factor rule.
297
+ user = users.qa_identity(uname, password) if (uname and password) else None
298
+ if not user:
299
+ user = users.verify(uname, password) if (uname and password) else None
300
+ if not user:
301
+ try:
302
+ users._hash(password or "x", "00" * 16)
303
+ except Exception:
304
+ pass
305
+ _note_failure(throttle_key)
306
+ raise err(401, "invalid_credentials", "that username and password do not match")
307
+ if user.get("qa_runner") or user.get("emergency_master"):
308
+ raise err(400, "no_stored_account", "That sign in cannot enrol a second factor.")
309
+ return user
310
+
311
+
312
+ def _mfa_record(uname):
313
+ """A stored identity was already proved. Failure to re-read it cannot assert absence."""
314
+ try:
315
+ rec = (users.registry() or {}).get(uname)
316
+ except Exception:
317
+ rec = None
318
+ if not rec:
319
+ raise err(503, "store_unavailable", "the account could not be read. Try again")
320
+ return rec
321
+
322
+
323
+ def _mfa_session_tenant(user, rec, throttle_key):
324
+ """Both MFA cookie writers retain login's tenant and T35 password-expiry walls."""
325
+ tenant = str(user.get("tenant") or "royal-imports").strip().lower()
326
+ from harness import runtime
327
+ try:
328
+ runtime.get_runtime(tenant)
329
+ except KeyError:
330
+ _note_failure(throttle_key)
331
+ raise err(401, "invalid_credentials", "that username and password do not match")
332
+ # Confirming a phone must not become a second login door that accepts an expired password.
333
+ # Check before writing the factor, so the person can rotate and resume the same setup.
334
+ if users.password_expired(rec):
335
+ raise err(403, "password_expired", "Your password has expired. Set a new one to continue.")
336
+ return tenant
337
+
338
+
339
+ def _mfa_set(user, secret, codes, *, require_unenrolled=False):
340
+ """Translate a raced credential change into a retry, never a claimed successful setup."""
341
+ try:
342
+ # Use the RESOLVED username: the posted identifier can be an email alias with no record.
343
+ return users.set_mfa(user["username"], secret, codes,
344
+ require_unenrolled=require_unenrolled,
345
+ expected_epoch=int(user.get("epoch") or 0))
346
+ except users.MFAStateError as exc:
347
+ if str(exc) == "already_enrolled":
348
+ raise err(409, "mfa_already_enrolled", _MFA_ALREADY_ENROLLED)
349
+ raise err(409, "mfa_changed", "This account changed during setup. Sign in again to continue.")
350
+
351
+
352
+ def _mfa_session(request, response, user, rec, tenant, landed, throttle_key):
353
+ """Mint only from the MFA write's landed epoch, never the stale login projection."""
354
+ if landed is None:
355
+ # A missing record/no-op write cannot support a cookie or a promise that codes were saved.
356
+ raise err(503, "store_unavailable", "the second factor was not saved. Try again")
357
+ value, _claims = aios_session.mint(tenant, user["username"], int(landed))
358
+ aios_session.set_cookie(response, request, value)
359
+ users.touch_login(user["username"])
360
+ import deps as _deps
361
+ _deps.note_active(user["username"])
362
+ if not users.password_changed_at(rec):
363
+ # This is a successful first sign-in too: preserve T35's legacy clock backfill.
364
+ users.stamp_password_age(user["username"])
365
+ _clear_failures(throttle_key)
366
+ # Responses carrying a new secret or recovery codes must not survive in an HTTP cache.
367
+ response.headers["Cache-Control"] = "no-store"
368
+
369
+
370
+ @router.post("/mfa/enroll")
371
+ def mfa_enroll(response: Response, body: dict = Body(default=None)):
372
+ """Offer a candidate secret without changing the account or issuing recovery codes.
373
+
374
+ Stateless by design: the client posts this candidate back with its password and phone code.
375
+ A pending-secret dict would belong to one worker and fail when confirmation reaches another.
376
+ """
377
+ body = body or {}
378
+ uname = str(body.get("username") or "").strip().lower()
379
+ user = _mfa_credentials(uname, str(body.get("password") or ""))
380
+ rec = _mfa_record(user["username"])
381
+ if users.mfa_enrolled(rec):
382
+ raise err(409, "mfa_already_enrolled", _MFA_ALREADY_ENROLLED)
383
+ secret = users.new_mfa_secret()
384
+ response.headers["Cache-Control"] = "no-store"
385
+ return {"secret": secret, "otpauthUri": users.otpauth_uri(secret, user["username"]),
386
+ "issuer": users.MFA_ISSUER, "digits": users.MFA_DIGITS, "period": users.MFA_PERIOD}
387
+
388
+
389
+ @router.post("/mfa/enroll/confirm")
390
+ def mfa_enroll_confirm(request: Request, response: Response, body: dict = Body(default=None)):
391
+ """Prove installation, enrol once and sign in under the new epoch.
392
+
393
+ This response is the only time those codes exist in clear anywhere. The record holds SHA-256
394
+ hashes. No other route returns them, no log line prints them, and there is no way to read them
395
+ back. Explicit regeneration issues a DIFFERENT set, never a second reading of this one.
396
+ """
397
+ body = body or {}
398
+ uname = str(body.get("username") or "").strip().lower()
399
+ throttle_key = ("*", uname)
400
+ user = _mfa_credentials(uname, str(body.get("password") or ""))
401
+ rec = _mfa_record(user["username"])
402
+ if users.mfa_enrolled(rec):
403
+ raise err(409, "mfa_already_enrolled", _MFA_ALREADY_ENROLLED)
404
+ secret = str(body.get("secret") or "").strip().upper()
405
+ if not users.totp_valid(secret, str(body.get("code") or "")):
406
+ _note_failure(throttle_key)
407
+ raise err(401, "mfa_invalid", _MFA_INVALID)
408
+ tenant = _mfa_session_tenant(user, rec, throttle_key)
409
+ codes = users.new_recovery_codes()
410
+ # The store guard repeats the check atomically: two workers cannot issue two first sets.
411
+ landed = _mfa_set(user, secret, codes, require_unenrolled=True)
412
+ _mfa_session(request, response, user, rec, tenant, landed, throttle_key)
413
+ return {"user": _public_user(user), "recoveryCodes": codes}
414
+
415
+
416
+ @router.get("/mfa")
417
+ def mfa_status(session: Session = Depends(require_session)):
418
+ """The calling account's state only: never a secret, code or hash."""
419
+ # These two identities have no stored factor; do not read tenant #0 for the QA runner.
420
+ if session.user.get("qa_runner") or session.user.get("emergency_master"):
421
+ rec = {}
422
+ else:
423
+ rec = _mfa_record(session.uname)
424
+ return {"enrolled": users.mfa_enrolled(rec), "enrolledAt": rec.get("mfa_enrolled_at") or None,
425
+ "recoveryCodesRemaining": users.recovery_codes_remaining(rec)}
426
+
427
+
428
+ @router.post("/mfa/recovery-codes")
429
+ def mfa_recovery_codes(request: Request, response: Response, body: dict = Body(default=None),
430
+ session: Session = Depends(require_session)):
431
+ """Issue a new set once after password re-authentication, keeping the installed phone.
432
+
433
+ Regeneration is a credential change: set_mfa bumps the epoch and signs OTHER sessions out.
434
+ Re-mint the CALLING session from that landed epoch or the user's own action signs them out.
435
+ The clear codes appear only in this response; the store and all later reads hold only hashes.
436
+ """
437
+ uname = session.uname
438
+ throttle_key = ("*", uname)
439
+ user = _mfa_credentials(uname, str((body or {}).get("password") or ""))
440
+ # The session supplies the identity. Body username/tenant fields can never choose a target.
441
+ rec = _mfa_record(uname)
442
+ if not users.mfa_enrolled(rec):
443
+ raise err(409, "mfa_not_enrolled", "Set up your authenticator app before making recovery codes.")
444
+ tenant = _mfa_session_tenant(user, rec, throttle_key)
445
+ codes = users.new_recovery_codes()
446
+ landed = _mfa_set(user, rec["mfa_secret"], codes)
447
+ _mfa_session(request, response, user, rec, tenant, landed, throttle_key)
448
+ return {"recoveryCodes": codes}
449
+
450
+
451
+ @router.get("/password-policy")
452
+ def password_policy():
453
+ """An account-independent checklist the sign-in page can show before authentication."""
454
+ return {"rules": users.password_rules(), "minLength": users.PASSWORD_MIN_LENGTH,
455
+ "maxAgeDays": users.PASSWORD_MAX_AGE_DAYS, "historyCount": users.PASSWORD_HISTORY}
456
+
457
+
458
+ @router.post("/password", status_code=204)
459
+ def change_password(body: dict = Body(default=None)):
460
+ """Rotate with the current credential, including when expiry refuses a login session."""
461
+ body = body or {}
462
+ uname = str(body.get("username") or "").strip().lower()
463
+ pw = str(body.get("currentPassword") or "")
464
+ new_pw = str(body.get("newPassword") or "")
465
+ # Share login's identifier bucket: a second unauthenticated door must not buy a second
466
+ # password-guessing budget, and failures must not disclose whether an account exists.
467
+ throttle_key = ("*", uname)
468
+ wait = _throttled(throttle_key)
469
+ if wait:
470
+ raise err(429, "too_many_attempts",
471
+ f"too many failed attempts. Try again in {wait} seconds")
472
+ # Resolve the staging runner without registry I/O, exactly as login does. Its credential
473
+ # authenticates, but no stored password exists here, so reporting a rotation would be false.
474
+ user = users.qa_identity(uname, pw) if (uname and pw) else None
475
+ if not user:
476
+ user = users.verify(uname, pw) if (uname and pw) else None
477
+ if not user:
478
+ try:
479
+ users._hash(pw or "x", "00" * 16)
480
+ except Exception:
481
+ pass
482
+ _note_failure(throttle_key)
483
+ raise err(401, "invalid_credentials", "that username and password do not match")
484
+ if user.get("emergency_master") or user.get("qa_runner"):
485
+ raise err(400, "no_stored_password", "This account has no stored password to change here.")
486
+ try:
487
+ # verify accepts email addresses too. Rotate the RESOLVED registry key, never the typed
488
+ # alias, or this door could return 204 without changing any password or revoking sessions.
489
+ users.set_password(user["username"], new_pw)
490
+ except users.PasswordPolicyError as exc:
491
+ raise err(400, "weak_password", "That password does not meet the policy: " + str(exc))
492
+ _clear_failures(throttle_key)
493
+ return Response(status_code=204)
494
+
495
+
496
  @router.post("/logout", status_code=204)
497
  def logout(request: Request):
498
  """204 and the cookie is cleared. Deliberately NOT session-gated: logging out must work from
api/routes_connectors.py CHANGED
@@ -21,6 +21,7 @@ that reported another user's Gmail as "connected" would be both wrong and a smal
21
  from __future__ import annotations
22
 
23
  import os
 
24
 
25
  from fastapi import APIRouter, Body, Depends
26
 
@@ -1376,6 +1377,38 @@ def _evict_odoo_product_pools(rt):
1376
  rt.pool_cache.pop(cache_key, None)
1377
 
1378
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1379
  def _enable_odoo_database(table_key, session):
1380
  """Turn on one declared Odoo database and materialise it before reporting success."""
1381
  if not session.admin:
@@ -1389,6 +1422,20 @@ def _enable_odoo_database(table_key, session):
1389
  raise err(404, "unknown_odoo_database",
1390
  f"Odoo does not declare a database with key {key!r}")
1391
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1392
  # ⭐ W56-T31: before this door, enabled meant only "will be included in the next sync".
1393
  # `canRename` then correctly stayed false because there was no table. The flag remains in the
1394
  # connector's one CONFIG_KEY document, but this door also creates the database before it can
@@ -1396,6 +1443,8 @@ def _enable_odoo_database(table_key, session):
1396
  def _up(cur):
1397
  cur = cur if isinstance(cur, dict) else {}
1398
  cur.setdefault("grids", {}).update({key: True})
 
 
1399
  return cur
1400
 
1401
  failure = None
@@ -1510,6 +1559,52 @@ def odoo_database_enable(table_key: str, session: Session = Depends(require_sess
1510
  return _enable_odoo_database(table_key, session)
1511
 
1512
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1513
  @router.patch("/connectors/odoo/schema/{field_key}")
1514
  def odoo_schema_enable(field_key: str, body: dict = Body(default=None),
1515
  session: Session = Depends(require_session)):
 
21
  from __future__ import annotations
22
 
23
  import os
24
+ import time
25
 
26
  from fastapi import APIRouter, Body, Depends
27
 
 
1377
  rt.pool_cache.pop(cache_key, None)
1378
 
1379
 
1380
+ # W57-T31 / R10 / C9: switching off starts a seven-day lock to prevent repeated toggling.
1381
+ # The config document is shared with read_config, which ignores unknown keys: disabledAt
1382
+ # belongs beside grids, not in a second document that could drift from enablement.
1383
+ _RELOCK_DAYS = 7
1384
+ _RELOCK_SECONDS = _RELOCK_DAYS * 86400
1385
+
1386
+
1387
+ def _relock_stamps(rt):
1388
+ """Read disable epochs without letting an absent or malformed map break a request."""
1389
+ try:
1390
+ import odoo_relational
1391
+ stamps = (rt.get(odoo_relational.CONFIG_KEY) or {}).get("disabledAt", {})
1392
+ if not isinstance(stamps, dict):
1393
+ return {}
1394
+ return {str(key): int(value) for key, value in stamps.items()
1395
+ if isinstance(value, (int, float)) and not isinstance(value, bool)}
1396
+ except Exception: # noqa: BLE001
1397
+ return {}
1398
+
1399
+
1400
+ def _relock_days_left(stamp, now=None):
1401
+ """Round any remaining part of a lock day up to a whole day."""
1402
+ if isinstance(stamp, bool) or not isinstance(stamp, (int, float)):
1403
+ return 0
1404
+ try:
1405
+ from math import ceil
1406
+ remaining = stamp + _RELOCK_SECONDS - (time.time() if now is None else now)
1407
+ return max(0, ceil(remaining / 86400))
1408
+ except Exception: # noqa: BLE001
1409
+ return 0
1410
+
1411
+
1412
  def _enable_odoo_database(table_key, session):
1413
  """Turn on one declared Odoo database and materialise it before reporting success."""
1414
  if not session.admin:
 
1422
  raise err(404, "unknown_odoo_database",
1423
  f"Odoo does not declare a database with key {key!r}")
1424
 
1425
+ # R10 / C9: only a transition back on is locked; an already-enabled database may retry
1426
+ # materialisation. A successful enable clears its stamp so the next switch-off starts fresh.
1427
+ # The provider's own enabled is authoritative; re-deriving defaults is wrong for the discovered long tail.
1428
+ if choices[key].get("enabled") is not True:
1429
+ days = _relock_days_left(_relock_stamps(session.runtime).get(key))
1430
+ if days > 0:
1431
+ label = str(choices[key].get("label") or key)
1432
+ unit = "day" if days == 1 else "days"
1433
+ raise err(409, "database_relocked",
1434
+ f"{label} was switched off less than {_RELOCK_DAYS} days ago. "
1435
+ f"It cannot be switched back on for another {days} {unit}. "
1436
+ f"The {_RELOCK_DAYS} day lock is what stops a database being switched "
1437
+ "on and off repeatedly.")
1438
+
1439
  # ⭐ W56-T31: before this door, enabled meant only "will be included in the next sync".
1440
  # `canRename` then correctly stayed false because there was no table. The flag remains in the
1441
  # connector's one CONFIG_KEY document, but this door also creates the database before it can
 
1443
  def _up(cur):
1444
  cur = cur if isinstance(cur, dict) else {}
1445
  cur.setdefault("grids", {}).update({key: True})
1446
+ if isinstance(cur.get("disabledAt"), dict):
1447
+ cur["disabledAt"].pop(key, None)
1448
  return cur
1449
 
1450
  failure = None
 
1559
  return _enable_odoo_database(table_key, session)
1560
 
1561
 
1562
+ def _disable_odoo_database(table_key, session):
1563
+ """Turn off one declared Odoo database and persist its re-enable lock."""
1564
+ if not session.admin:
1565
+ raise err(403, "not_admin", "only an administrator can disable an Odoo database")
1566
+
1567
+ import odoo_relational
1568
+ key = str(table_key or "").strip()
1569
+ choices = {str(choice.get("key") or ""): choice
1570
+ for choice in odoo_relational.grid_choices(session.runtime)}
1571
+ if key not in choices:
1572
+ raise err(404, "unknown_odoo_database",
1573
+ f"Odoo does not declare a database with key {key!r}")
1574
+
1575
+ # W57-T31 / R10 / C9: one config-only write starts the lock, with no sync or row deletion.
1576
+ # The provider's own enabled is authoritative; re-deriving defaults is wrong for the discovered long tail.
1577
+ # Repeating a disable must preserve the original deadline.
1578
+ was_enabled = choices[key].get("enabled") is True
1579
+ def _up(cur):
1580
+ cur = cur if isinstance(cur, dict) else {}
1581
+ grids = cur.get("grids")
1582
+ grids = grids if isinstance(grids, dict) else {}
1583
+ grids[key] = False
1584
+ cur["grids"] = grids
1585
+ if was_enabled:
1586
+ if not isinstance(cur.get("disabledAt"), dict):
1587
+ cur["disabledAt"] = {}
1588
+ cur["disabledAt"][key] = int(time.time())
1589
+ return cur
1590
+
1591
+ try:
1592
+ session.runtime.update(odoo_relational.CONFIG_KEY, _up, flush="sync")
1593
+ except Exception: # noqa: BLE001
1594
+ raise err(503, "store_unavailable", "the database setting was not saved. Try again.")
1595
+
1596
+ stamp = _relock_stamps(session.runtime).get(key)
1597
+ return {"key": key, "enabled": False, "relockDays": _RELOCK_DAYS,
1598
+ "disabledAt": stamp,
1599
+ "canEnableAt": stamp + _RELOCK_SECONDS if stamp is not None else None}
1600
+
1601
+
1602
+ @router.post("/connectors/odoo/databases/{table_key}/disable")
1603
+ def odoo_database_disable(table_key: str, session: Session = Depends(require_session)):
1604
+ """Disable one declared Odoo database in this tenant's governed store."""
1605
+ return _disable_odoo_database(table_key, session)
1606
+
1607
+
1608
  @router.patch("/connectors/odoo/schema/{field_key}")
1609
  def odoo_schema_enable(field_key: str, body: dict = Body(default=None),
1610
  session: Session = Depends(require_session)):
api/routes_keychain.py CHANGED
@@ -10,6 +10,7 @@ in the payload (`pausedNote`): pausing marks intent and warns; the source cutove
10
  the keychain cutover wave R3 staged.
11
  """
12
  import os
 
13
 
14
  from fastapi import Body, Depends
15
  from fastapi import APIRouter
@@ -695,6 +696,132 @@ def _with_connector(rows):
695
  return out
696
 
697
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
698
  @router.get("/admin/keychain")
699
  def list_keychain(session: Session = Depends(require_session)):
700
  """⭐ W32-T11 / R4 — SESSION-GATED, NOT ADMIN-GATED, and that is the ruling not a relaxation.
@@ -867,17 +994,112 @@ def update_key(entry_id: str, body: dict = Body(default=None),
867
  "owner": owner if scope == "personal" else ""}}
868
 
869
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
870
  @router.delete("/admin/keychain/{entry_id}")
871
- def delete_key(entry_id: str, session: Session = Depends(require_session)):
 
 
 
 
 
 
 
 
 
872
  row = _own_row(session, entry_id)
873
  if not _may_touch(session, row):
874
  raise err(403, "not_yours", "this connection is not yours to delete")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
875
  try:
876
- _kc().delete_entry(session.runtime, entry_id)
877
- _write_scope(session.runtime, entry_id, DEFAULT_SCOPE, "") # drop the side row with it
878
  except Exception:
879
- raise err(503, "store_unavailable", "the delete did not land — try again")
880
- return {"ok": True}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
881
 
882
 
883
  @router.post("/admin/keychain/{entry_id}/test")
 
10
  the keychain cutover wave R3 staged.
11
  """
12
  import os
13
+ import time
14
 
15
  from fastapi import Body, Depends
16
  from fastapi import APIRouter
 
696
  return out
697
 
698
 
699
+ _REGISTERED = {"done": False}
700
+ # A stale Remove must not inherit consent forever; ten minutes leaves time to read the warning
701
+ # and retry the existing client while binding that consent to the same user and database set.
702
+ REVOKE_CONFIRM_SECONDS = 600
703
+ _REVOCATIONS_KEY = "keychain_revocations"
704
+
705
+
706
+ def _odoo_table_owner():
707
+ """Odoo's per-connection table resolver, or None when it cannot be imported.
708
+
709
+ ⛔ ITS ABSENCE MUST NOT TAKE THE REGISTRY DOWN WITH IT, and that is why this is a function
710
+ rather than one more name in the block below's `import`. `odoo_relational` is the heavy end of
711
+ this codebase (it pulls the mirror and the connector spec); a failure to import it inside one
712
+ `try` around all three families would leave AMAZON unregistered, and an unregistered Amazon
713
+ family is a revocation that purges nothing while reporting a clean `registry: True`. That is
714
+ the silent-no-op shape instruction 30 exists to remove.
715
+ ⚠ Falling back to None is a REAL degradation and a safe one: without the resolver every
716
+ `ut_odoo_*` table resolves to the tenant's designated default connection instead of its own,
717
+ which can only ever widen the KEEP list a disclosure prints. Odoo purges nothing (R10), so a
718
+ coarse answer here cannot delete a row.
719
+ """
720
+ try:
721
+ import odoo_relational
722
+ return odoo_relational.connection_for_table_key
723
+ except Exception: # noqa: BLE001
724
+ return None
725
+
726
+
727
+ def _register_credential_tables():
728
+ """Declare revocation policy lazily; a failed import remains retryable and reportable.
729
+
730
+ routes_connectors imports this module at boot, and odoo_relational is heavy. An import-time
731
+ registration would put a cycle on every route before anyone even opens Keychain.
732
+ """
733
+ if _REGISTERED["done"]:
734
+ return True
735
+ try:
736
+ from core import user_tables as ut
737
+ import routes_connectors as rc
738
+ # Instruction 30 / C13 names the Amazon Data Protection Policy, not every connector.
739
+ ut.register_credential_tables(
740
+ "amazon_sp", rc.CONNECTED_PREFIXES["amazon_sp"], on_revoke=ut.REVOKE_PURGE,
741
+ why="The Amazon Data Protection Policy requires deleting the seller data "
742
+ "authorised by a revoked credential.")
743
+ # W32 R10's second sentence and D-259 require these grids to survive a reconnect.
744
+ ut.register_credential_tables(
745
+ "odoo", rc.CONNECTED_PREFIXES["odoo"], on_revoke=ut.REVOKE_KEEP,
746
+ owner=_odoo_table_owner(),
747
+ why="Wave 32 R10 says reconnecting resumes into the same tables. Use "
748
+ "POST /admin/connectors/odoo/disconnect to freeze the data "
749
+ "instead of deleting it.")
750
+ # No Meta ruling exists this wave. KEEP records the reversible direction explicitly.
751
+ ut.register_credential_tables(
752
+ "meta_ads", rc.CONNECTED_PREFIXES["meta_ads"], on_revoke=ut.REVOKE_KEEP,
753
+ why="No ruling has decided Meta Ads data deletion on revocation, so the reversible "
754
+ "direction is taken and its databases are kept.")
755
+ except Exception as exc:
756
+ _REGISTERED["error"] = type(exc).__name__
757
+ return False
758
+ _REGISTERED["done"] = True
759
+ _REGISTERED.pop("error", None)
760
+ return True
761
+
762
+
763
+ def _credential_revocation(row, rt):
764
+ """A failed census is UNKNOWN, never evidence of an empty seller footprint."""
765
+ registered = _register_credential_tables()
766
+ etype, cid = str(row.get("type") or ""), str(row["id"])
767
+ if registered:
768
+ try:
769
+ from core import user_tables as ut
770
+ return registered, ut.credential_footprint(etype, cid, rt=rt, st=rt)
771
+ except Exception as exc:
772
+ why = f"The credential footprint could not be read ({type(exc).__name__})."
773
+ else:
774
+ failure = _REGISTERED.get("error", "unavailable")
775
+ why = f"The credential table registry could not be built ({failure})."
776
+ return registered, {
777
+ "type": etype, "connectionId": cid, "action": "none", "purge": [], "keep": [],
778
+ "rows": 0, "rowsKnown": False,
779
+ "why": why + " Data cleanup is not known. "
780
+ "Restore the store or registry and retry cleanup.",
781
+ }
782
+
783
+
784
+ def _revocation_residue(entry_type):
785
+ """Standing rule 1 requires the cause AND a fix for the mirror this route cannot clear.
786
+
787
+ amazon_store.py --help exposes sync/status/validate/selftest, but no deletion flag.
788
+ Clearing the app's materialised copy is not evidence that the raw reports disappeared.
789
+ """
790
+ if entry_type != "amazon_sp":
791
+ return []
792
+ return [{
793
+ "where": "The tenant DuckDB mirror",
794
+ "why": "The API process opens the mirror read only, so a route cannot clear it.",
795
+ "fix": "An operator must delete the tenant's Amazon mirror tables. "
796
+ "platform/harness/amazon_store.py has no flag to do this today.",
797
+ }]
798
+
799
+
800
+ def _write_revocation_warning(rt, entry_id, warning=None):
801
+ """Prune expired consent on every write; failed persistence requires explicit confirmation."""
802
+ now = int(time.time())
803
+
804
+ def _up(cur):
805
+ kept = {}
806
+ for key, value in (cur or {}).items():
807
+ try:
808
+ age = now - int(value.get("at", 0))
809
+ except (AttributeError, TypeError, ValueError):
810
+ continue
811
+ if 0 <= age < REVOKE_CONFIRM_SECONDS:
812
+ kept[key] = value
813
+ kept.pop(str(entry_id), None)
814
+ if warning is not None:
815
+ kept[str(entry_id)] = warning
816
+ return kept
817
+
818
+ try:
819
+ rt.update(_REVOCATIONS_KEY, _up, flush="sync")
820
+ return True
821
+ except Exception:
822
+ return False
823
+
824
+
825
  @router.get("/admin/keychain")
826
  def list_keychain(session: Session = Depends(require_session)):
827
  """⭐ W32-T11 / R4 — SESSION-GATED, NOT ADMIN-GATED, and that is the ruling not a relaxation.
 
994
  "owner": owner if scope == "personal" else ""}}
995
 
996
 
997
+ @router.get("/admin/keychain/{entry_id}/revocation")
998
+ def key_revocation(entry_id: str, session: Session = Depends(require_session)):
999
+ """Disclose what revocation removes, behind the delete's own visibility and ownership walls.
1000
+
1001
+ Like table_footprint, only someone who could delete may case the joint. An unavailable
1002
+ census carries rowsKnown=False, because an empty list alone would fabricate reassurance.
1003
+ """
1004
+ row = _own_row(session, entry_id)
1005
+ if not _may_touch(session, row):
1006
+ raise err(403, "not_yours", "this connection is not yours to delete")
1007
+ registered, footprint = _credential_revocation(row, session.runtime)
1008
+ residue = (_revocation_residue(row["type"])
1009
+ if footprint["purge"] or not footprint["rowsKnown"] else [])
1010
+ return {"entry": {key: row.get(key, "") for key in ("id", "label", "type")},
1011
+ **footprint, "registry": registered, "residue": residue}
1012
+
1013
+
1014
  @router.delete("/admin/keychain/{entry_id}")
1015
+ def delete_key(entry_id: str, session: Session = Depends(require_session), confirm: str = ""):
1016
+ kc, rt = _kc(), session.runtime
1017
+ entries = kc.list_entries(rt)
1018
+ # Instruction 30 needs idempotent revocation. An absent id's 200 is distinguishable from
1019
+ # another person's personal entry's 404, but ids have 12 random hex characters and are not
1020
+ # enumerable. A 404 on a lost response's retry would break this policy path's idempotence.
1021
+ if not any(entry["id"] == str(entry_id) for entry in entries):
1022
+ return {"ok": True, "alreadyGone": True,
1023
+ "purged": {"tables": [], "rows": 0, "rowsKnown": True,
1024
+ "refused": [], "failed": []}}
1025
  row = _own_row(session, entry_id)
1026
  if not _may_touch(session, row):
1027
  raise err(403, "not_yours", "this connection is not yours to delete")
1028
+ registered, footprint = _credential_revocation(row, rt)
1029
+ tables = sorted(table["key"] for table in footprint["purge"])
1030
+ purges = footprint["action"] == "purge" and bool(tables)
1031
+ if purges and confirm != "purge":
1032
+ now = int(time.time())
1033
+ try:
1034
+ warning = (rt.get(_REVOCATIONS_KEY) or {}).get(str(entry_id)) or {}
1035
+ repeated = (warning.get("user") == session.uname
1036
+ and 0 <= now - int(warning.get("at", 0)) < REVOKE_CONFIRM_SECONDS
1037
+ and warning.get("tables") == tables)
1038
+ except Exception:
1039
+ repeated = False
1040
+ if not repeated:
1041
+ # No lane owns KeychainTab.tsx this wave. Its dialog still says "Data already read
1042
+ # stays; nothing new will be read." Purging silently behind that sentence would make
1043
+ # the product lie on screen. Refusing once with the count makes disclosure true for
1044
+ # the client that exists; a repeat by this user over this set is the second door.
1045
+ stored = _write_revocation_warning(rt, entry_id, {
1046
+ "user": session.uname, "at": now, "tables": tables,
1047
+ })
1048
+ # ⚠ THE KIND COMES FROM THE CREDENTIAL, NOT FROM A LITERAL. Amazon is the only
1049
+ # family that purges today, so "Amazon databases" would have read correctly and
1050
+ # become a lie in the one change that flips a second family to REVOKE_PURGE.
1051
+ kind = kc.kind_label(row.get("type") or "")
1052
+ noun = "database" if len(tables) == 1 else "databases"
1053
+ count = (f" holding {footprint['rows']:,} rows. " if footprint["rowsKnown"]
1054
+ else ". The row count is not known. ")
1055
+ next_step = ("Choose Remove again within 10 minutes to confirm, or pass confirm=purge."
1056
+ if stored else "The warning could not be saved. "
1057
+ "Pass confirm=purge to confirm explicitly.")
1058
+ raise err(409, "confirm_purge",
1059
+ f"Removing this connection also deletes {len(tables):,} {kind} {noun}"
1060
+ + count + "That data cannot be recovered. " + next_step)
1061
+
1062
+ class _Ownership:
1063
+ # Revoking the default changes keychain's resolver immediately. Lend only metadata from
1064
+ # BEFORE revocation so core can recompute ownership after the credential is gone. Table
1065
+ # definitions and deletions still use the live tenant runtime; no caller-supplied plan
1066
+ # and no encrypted credential is carried into the purge.
1067
+ def get(self, name):
1068
+ if name == kc.KEY:
1069
+ return {"entries": {entry["id"]: entry for entry in entries}}
1070
+ return rt.get(name)
1071
+
1072
+ # Credential FIRST, data second. A crash leaves revoked access and residual tables that can
1073
+ # be swept again; the reverse leaves live credentials over deleted data we cannot read back.
1074
+ # The absent-id retry above is only a no-op receipt, not proof that a crashed sweep completed.
1075
  try:
1076
+ kc.delete_entry(rt, entry_id)
1077
+ _write_scope(rt, entry_id, DEFAULT_SCOPE, "")
1078
  except Exception:
1079
+ raise err(503, "store_unavailable", "The delete did not land. Try again.")
1080
+ if not purges:
1081
+ _write_revocation_warning(rt, entry_id)
1082
+ if footprint["rowsKnown"]:
1083
+ return {"ok": True}
1084
+ # Fail soft costs the census, never the ability to revoke access. Standing rule 1 makes
1085
+ # that incomplete cleanup explicit instead of returning an invented "nothing to purge".
1086
+ return {"ok": True, "registry": registered, "footprint": footprint,
1087
+ "purged": {"tables": [], "rows": 0, "rowsKnown": False,
1088
+ "refused": [], "failed": []},
1089
+ "residue": _revocation_residue(row["type"])}
1090
+ from core import user_tables as ut
1091
+ try:
1092
+ result = ut.purge_credential_tables(row["type"], entry_id, rt=_Ownership(), st=rt)
1093
+ except Exception as exc:
1094
+ # Access is already revoked. Report every unresolved table without leaking a store path.
1095
+ result = {"purged": [], "rows": 0, "rowsKnown": False, "refused": [],
1096
+ "failed": [{"key": key, "error": type(exc).__name__} for key in tables]}
1097
+ _write_revocation_warning(rt, entry_id)
1098
+ return {"ok": True,
1099
+ "purged": {"tables": result["purged"], "rows": result["rows"],
1100
+ "rowsKnown": result["rowsKnown"], "refused": result["refused"],
1101
+ "failed": result["failed"]},
1102
+ "residue": _revocation_residue(row["type"])}
1103
 
1104
 
1105
  @router.post("/admin/keychain/{entry_id}/test")
api/routes_sheet.py CHANGED
@@ -1841,6 +1841,11 @@ def _resolve_binding(session: Session, raw_binding, *, today=None, view_memo=Non
1841
  agg_refusal = sheet_mod.aggregate_refusal(binding["aggregate"], bound_field)
1842
  if agg_refusal is not None:
1843
  raise err(409, agg_refusal.code, agg_refusal.message)
 
 
 
 
 
1844
 
1845
  # ── the ROW wall, fail-closed ────────────────────────────────────────────────────────────
1846
  if wall_nodes:
 
1841
  agg_refusal = sheet_mod.aggregate_refusal(binding["aggregate"], bound_field)
1842
  if agg_refusal is not None:
1843
  raise err(409, agg_refusal.code, agg_refusal.message)
1844
+ if bound_field and bound_field.get("measure") and not binding.get("period"):
1845
+ label = bound_field.get("label") or bound_field.get("key")
1846
+ raise err(409, "metric_period_required",
1847
+ f"{label} is measured over a period, so this cell needs one. "
1848
+ "Open the cell's Period section and choose a period.")
1849
 
1850
  # ── the ROW wall, fail-closed ────────────────────────────────────────────────────────────
1851
  if wall_nodes:
platform/aios_grid_fields.json CHANGED
@@ -118,6 +118,22 @@
118
  "default": true,
119
  "description": "A Google Maps link to this customer's address."
120
  },
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
121
  {
122
  "key": "customer_since",
123
  "label": "Customer since",
@@ -166,17 +182,6 @@
166
  "default": true,
167
  "description": "How many days late this customer is running against their own usual ordering rhythm."
168
  },
169
- {
170
- "_note": "filterable:false — DERIVED ANALYTIC: est_missed is min(cycles missed, 3) x AOV, a score we compute rather than an object the business has, so a condition on it would read as a fact about the customer when it is a fact about our arithmetic. It still displays and still sorts. Until wave 6 this flag also covered the frozen-window presets (revenue_ytd / revenue_ly / orders_24m / aov / yoy_pct); those are now DELETED outright under the owner's no-buildable-presets rule — see _comment. est_missed itself STAYS: no creatable measure or formula reproduces the cadence model behind it.",
171
- "key": "est_missed",
172
- "label": "Est. missed $",
173
- "type": "currency",
174
- "source": "odoo",
175
- "default": true,
176
- "agg": "sum",
177
- "filterable": false,
178
- "description": "Estimated sales missed while quiet: missed orders (capped at 3) times average order value. An estimate, not money owed."
179
- },
180
  {
181
  "_note": "wave 21 R1 — KEY UNCHANGED, LABEL RENAMED. The computation is a DISJOINT split (ar.py credit_exposure): this column is only the not-yet-due residual, its sibling is the past-grace residual, and the two sum to the total. Under the label 'AR open $' the majority-late book read as 'Overdue > Open', which is nonsense in AR vocabulary — 'open' universally means the total. The label now says what the number is; the key stays so saved views and filters keep working.",
182
  "key": "ar_open",
 
118
  "default": true,
119
  "description": "A Google Maps link to this customer's address."
120
  },
121
+ {
122
+ "key": "lat",
123
+ "label": "Latitude",
124
+ "type": "text",
125
+ "source": "odoo",
126
+ "default": false,
127
+ "description": "Latitude of this customer's address, from Odoo when it has one and otherwise from our geocode of the address."
128
+ },
129
+ {
130
+ "key": "lon",
131
+ "label": "Longitude",
132
+ "type": "text",
133
+ "source": "odoo",
134
+ "default": false,
135
+ "description": "Longitude of this customer's address, from Odoo when it has one and otherwise from our geocode of the address."
136
+ },
137
  {
138
  "key": "customer_since",
139
  "label": "Customer since",
 
182
  "default": true,
183
  "description": "How many days late this customer is running against their own usual ordering rhythm."
184
  },
 
 
 
 
 
 
 
 
 
 
 
185
  {
186
  "_note": "wave 21 R1 — KEY UNCHANGED, LABEL RENAMED. The computation is a DISJOINT split (ar.py credit_exposure): this column is only the not-yet-due residual, its sibling is the past-grace residual, and the two sum to the total. Under the label 'AR open $' the majority-late book read as 'Overdue > Open', which is nonsense in AR vocabulary — 'open' universally means the total. The label now says what the number is; the key stays so saved views and filters keep working.",
187
  "key": "ar_open",
platform/core/measure_resolve.py CHANGED
@@ -19,6 +19,7 @@ Memo discipline (unchanged from the app.py originals):
19
  not leaks.
20
  """
21
  import hashlib
 
22
 
23
 
24
  def offer(team_id=None, on_error=None):
@@ -43,7 +44,7 @@ def _pool_key(allowed_pids):
43
 
44
 
45
  def condition_sets(view_configs, pending_cfg, team_id, allowed_pids, today, stamp, memo,
46
- on_error=None):
47
  """Every measure condition across `view_configs` (+ the optional pending config, which goes
48
  LAST and overwrites — the freshest statement of what the user wants) -> `{ruleId: [pid,…]}`.
49
 
@@ -64,20 +65,24 @@ def condition_sets(view_configs, pending_cfg, team_id, allowed_pids, today, stam
64
  if not rules:
65
  return {}
66
  pk = _pool_key(allowed_pids)
67
- out = {}
 
68
  for rule in rules:
69
  if not _mf.rule_complete(rule):
70
  continue
71
- key = (stamp, team_id, pk, _mf.signature(rule))
72
  if key not in memo:
73
  try:
74
- memo[key] = _mf.resolve_rule(rule, today, team_id, allowed_pids)
75
  except Exception as e:
76
  # An unresolvable condition must NOT become "everything" or "nothing" silently.
77
  if on_error:
78
  on_error('measure-resolve', e)
79
  continue
80
  out[str(rule['id'])] = sorted(memo[key])
 
 
 
81
  if len(memo) > 200: # a lifetime cache, not a leak
82
  memo.clear()
83
  return out
@@ -137,13 +142,18 @@ def series_values(fields, bucket, buckets, team_id, allowed_pids, today, stamp,
137
  return out
138
 
139
 
140
- def column_values(fields, team_id, allowed_pids, today, stamp, memo, on_error=None):
141
  """Values for every FORMULA-MEASURE column among `fields` -> `{pid: {field key: value}}`,
142
  handed to `rows_from_pool(derived=…)` beside the cohort cells.
143
 
144
  A column that cannot be computed (store down, BU scope on a company-level measure,
145
  unresolvable window) degrades to BLANK — the value dict simply omits that field key, and
146
  the client renders empty cells, never $0: blank is "could not compute", 0 is a real zero.
 
 
 
 
 
147
  """
148
  mfields = [f for f in fields or [] if isinstance(f.get('measure'), dict)]
149
  if not mfields:
@@ -151,16 +161,17 @@ def column_values(fields, team_id, allowed_pids, today, stamp, memo, on_error=No
151
  from harness import measure_filter as _mf
152
  from harness import windows as _wn
153
  pk = _pool_key(allowed_pids)
154
- out = {}
 
155
  for f in mfields:
156
  spec = f['measure']
157
  w = _wn.normalize(spec.get('window'))
158
  key = (stamp, team_id, pk, spec.get('key'),
159
- None if w is None else tuple(sorted(w.items())))
160
  if key not in memo:
161
  try:
162
  memo[key] = _mf.resolve_values(spec.get('key'), spec.get('window'),
163
- today, team_id, allowed_pids)
164
  except Exception as e:
165
  if on_error:
166
  on_error('measure-column', e)
@@ -183,6 +194,9 @@ def column_values(fields, team_id, allowed_pids, today, stamp, memo, on_error=No
183
  if vals is None:
184
  continue
185
  fkey = f['key']
 
 
 
186
  for pid, v in vals.items():
187
  out.setdefault(pid, {})[fkey] = v
188
  if len(memo) > 100:
 
19
  not leaks.
20
  """
21
  import hashlib
22
+ from core import relations as _relations
23
 
24
 
25
  def offer(team_id=None, on_error=None):
 
44
 
45
 
46
  def condition_sets(view_configs, pending_cfg, team_id, allowed_pids, today, stamp, memo,
47
+ on_error=None, related=None):
48
  """Every measure condition across `view_configs` (+ the optional pending config, which goes
49
  LAST and overwrites — the freshest statement of what the user wants) -> `{ruleId: [pid,…]}`.
50
 
 
65
  if not rules:
66
  return {}
67
  pk = _pool_key(allowed_pids)
68
+ out = _relations.MeasureAnswer() if related is not None else {}
69
+ rkey = _relations.measure_pin_key(related)
70
  for rule in rules:
71
  if not _mf.rule_complete(rule):
72
  continue
73
+ key = (stamp, team_id, pk, _mf.signature(rule), rkey)
74
  if key not in memo:
75
  try:
76
+ memo[key] = _mf.resolve_rule(rule, today, team_id, allowed_pids, related=related)
77
  except Exception as e:
78
  # An unresolvable condition must NOT become "everything" or "nothing" silently.
79
  if on_error:
80
  on_error('measure-resolve', e)
81
  continue
82
  out[str(rule['id'])] = sorted(memo[key])
83
+ if related is not None:
84
+ out.refusals.extend(dict(marker, rule=str(rule['id']))
85
+ for marker in getattr(memo[key], 'refusals', ()))
86
  if len(memo) > 200: # a lifetime cache, not a leak
87
  memo.clear()
88
  return out
 
142
  return out
143
 
144
 
145
+ def column_values(fields, team_id, allowed_pids, today, stamp, memo, on_error=None, related=None):
146
  """Values for every FORMULA-MEASURE column among `fields` -> `{pid: {field key: value}}`,
147
  handed to `rows_from_pool(derived=…)` beside the cohort cells.
148
 
149
  A column that cannot be computed (store down, BU scope on a company-level measure,
150
  unresolvable window) degrades to BLANK — the value dict simply omits that field key, and
151
  the client renders empty cells, never $0: blank is "could not compute", 0 is a real zero.
152
+
153
+ `related` is the row-window {table, record, via} pin. The host binds its scoped readers
154
+ with relations.measure_pin_context and publishes the returned mapping's `refusals` beside
155
+ its cells. A refused pin retains unscoped values plus a per-field named marker, on memo
156
+ hits too. Every measure and its conditions use the same query scope and caller's pool.
157
  """
158
  mfields = [f for f in fields or [] if isinstance(f.get('measure'), dict)]
159
  if not mfields:
 
161
  from harness import measure_filter as _mf
162
  from harness import windows as _wn
163
  pk = _pool_key(allowed_pids)
164
+ out = _relations.MeasureAnswer() if related is not None else {}
165
+ rkey = _relations.measure_pin_key(related)
166
  for f in mfields:
167
  spec = f['measure']
168
  w = _wn.normalize(spec.get('window'))
169
  key = (stamp, team_id, pk, spec.get('key'),
170
+ None if w is None else tuple(sorted(w.items())), rkey)
171
  if key not in memo:
172
  try:
173
  memo[key] = _mf.resolve_values(spec.get('key'), spec.get('window'),
174
+ today, team_id, allowed_pids, related=related)
175
  except Exception as e:
176
  if on_error:
177
  on_error('measure-column', e)
 
194
  if vals is None:
195
  continue
196
  fkey = f['key']
197
+ if related is not None:
198
+ out.refusals.extend(dict(marker, field=fkey)
199
+ for marker in getattr(vals, 'refusals', ()))
200
  for pid, v in vals.items():
201
  out.setdefault(pid, {})[fkey] = v
202
  if len(memo) > 100:
platform/core/perm_migrate.py CHANGED
@@ -8,7 +8,7 @@ no-op before anything relies on it.
8
  ⛔ WHY THE PROOF IS ABOUT VALUES AND NOT ABOUT ROWS (C-PERM amendment 3).
9
  `modules/customer_data._pool_build` passes `team_id` into `cust._cust_rev` three times (YTD, LY,
10
  LTM) and into `cust._cadence_bulk`. It therefore decides what `rev`, `ly`, `ltm`, `aov`,
11
- `est_missed` and the derived `status` MEAN — it is not a row filter. Swap it for a post-filter
12
  and a Fisch-only user keeps a plausible row LIST while every number on it quietly becomes
13
  Fisch+Royal, worst for `dba = Both` customers, who are precisely the ones a BU filter admits.
14
  A pid-set reconciliation reports GREEN on that. So `reconcile()` compares VALUES.
@@ -97,7 +97,7 @@ def plan(registry_dict, modules=(MODULE,)):
97
 
98
  #: The row members whose meaning depends on `team_id` — the ones amendment 3 is about. A
99
  #: reconciliation that skipped these would be the pid-only gate that cannot see the leak.
100
- VALUE_KEYS = ('rev', 'ly', 'ltm', 'aov', 'est_missed', 'status', 'orders', 'last_order')
101
 
102
 
103
  def reconcile(rec, pool_fn, modules=(MODULE,)):
 
8
  ⛔ WHY THE PROOF IS ABOUT VALUES AND NOT ABOUT ROWS (C-PERM amendment 3).
9
  `modules/customer_data._pool_build` passes `team_id` into `cust._cust_rev` three times (YTD, LY,
10
  LTM) and into `cust._cadence_bulk`. It therefore decides what `rev`, `ly`, `ltm`, `aov`,
11
+ and the derived `status` MEAN; it is not a row filter. Swap it for a post-filter
12
  and a Fisch-only user keeps a plausible row LIST while every number on it quietly becomes
13
  Fisch+Royal, worst for `dba = Both` customers, who are precisely the ones a BU filter admits.
14
  A pid-set reconciliation reports GREEN on that. So `reconcile()` compares VALUES.
 
97
 
98
  #: The row members whose meaning depends on `team_id` — the ones amendment 3 is about. A
99
  #: reconciliation that skipped these would be the pid-only gate that cannot see the leak.
100
+ VALUE_KEYS = ('rev', 'ly', 'ltm', 'aov', 'status', 'orders', 'last_order')
101
 
102
 
103
  def reconcile(rec, pool_fn, modules=(MODULE,)):
platform/core/relations.py CHANGED
@@ -56,6 +56,12 @@ asserted in a comment), and ANDed into the read ahead of the client predicate.
56
  booked in this ticket's handoff), ``pin_sql`` delegates to it and this note is deleted.
57
  """
58
 
 
 
 
 
 
 
59
  #: The three ways a database can be related to another. `via.direction` is always one of these.
60
  DIRECTIONS = ('forward', 'reverse', 'bridge')
61
 
@@ -191,18 +197,21 @@ OPEN_INVOICE_WHERE = ("state = 'posted' AND move_type IN ('out_invoice','out_ref
191
  BRIDGES = (
192
  {'key': 'bridge_customer_orders',
193
  'label': 'Orders',
 
194
  'source': 'customer_data', 'target': 'ut_odoo_orders',
195
  'source_col': IDENTITY_COL, 'target_col': 'partner_id',
196
  'where': None, 'served': True, 'cardinality': 'one_to_many'},
197
 
198
  {'key': 'bridge_customer_order_lines',
199
  'label': 'Order lines',
 
200
  'source': 'customer_data', 'target': 'ut_odoo_order_lines',
201
  'source_col': IDENTITY_COL, 'target_col': 'partner_id',
202
  'where': None, 'served': True, 'cardinality': 'one_to_many'},
203
 
204
  {'key': 'bridge_customer_open_invoices',
205
  'label': 'Open invoices',
 
206
  'source': 'customer_data', 'target': 'ut_odoo_invoices',
207
  'source_col': IDENTITY_COL, 'target_col': 'partner_id',
208
  # ⭐ W53-T19 / R5: `served` flipped to True when `ut_odoo_invoices` gained its read-through
@@ -222,12 +231,14 @@ BRIDGES = (
222
  # column to join to.
223
  {'key': 'bridge_product_order_lines',
224
  'label': 'Order lines',
 
225
  'source': 'product_data', 'target': 'ut_odoo_order_lines',
226
  'source_col': 'product_id', 'target_col': 'product_id',
227
  'where': None, 'served': True, 'cardinality': 'one_to_many'},
228
 
229
  {'key': 'bridge_order_order_lines',
230
  'label': 'Order lines',
 
231
  'source': 'ut_odoo_orders', 'target': 'ut_odoo_order_lines',
232
  'source_col': IDENTITY_COL, 'target_col': 'order_id',
233
  'where': None, 'served': True, 'cardinality': 'one_to_many'},
@@ -675,6 +686,184 @@ def pin_sql(id_sql, member_ids):
675
  return member_ids_tail(id_sql, member_ids)
676
 
677
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
678
  def compiled_pin_matches_filter_sql(id_sql, member_ids, columns=None):
679
  """Does `pin_sql` still spell the member tail exactly as `filter_sql` spells it?
680
 
@@ -941,6 +1130,23 @@ def one_hop(table, fields=None, defs=None, include_retired=False):
941
  entry['cardinality'] = str(got or 'many_to_many')
942
  out.append(entry)
943
  seen = {edge_identity(e) for e in out}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
944
  for entry in spec_entries(table, include_retired=include_retired):
945
  if edge_identity(entry) in seen:
946
  continue
 
56
  booked in this ticket's handoff), ``pin_sql`` delegates to it and this note is deleted.
57
  """
58
 
59
+ from contextlib import contextmanager
60
+ from contextvars import ContextVar
61
+ from dataclasses import dataclass
62
+ import json
63
+
64
+
65
  #: The three ways a database can be related to another. `via.direction` is always one of these.
66
  DIRECTIONS = ('forward', 'reverse', 'bridge')
67
 
 
197
  BRIDGES = (
198
  {'key': 'bridge_customer_orders',
199
  'label': 'Orders',
200
+ 'source_label': 'Customers',
201
  'source': 'customer_data', 'target': 'ut_odoo_orders',
202
  'source_col': IDENTITY_COL, 'target_col': 'partner_id',
203
  'where': None, 'served': True, 'cardinality': 'one_to_many'},
204
 
205
  {'key': 'bridge_customer_order_lines',
206
  'label': 'Order lines',
207
+ 'source_label': 'Customers',
208
  'source': 'customer_data', 'target': 'ut_odoo_order_lines',
209
  'source_col': IDENTITY_COL, 'target_col': 'partner_id',
210
  'where': None, 'served': True, 'cardinality': 'one_to_many'},
211
 
212
  {'key': 'bridge_customer_open_invoices',
213
  'label': 'Open invoices',
214
+ 'source_label': 'Customers',
215
  'source': 'customer_data', 'target': 'ut_odoo_invoices',
216
  'source_col': IDENTITY_COL, 'target_col': 'partner_id',
217
  # ⭐ W53-T19 / R5: `served` flipped to True when `ut_odoo_invoices` gained its read-through
 
231
  # column to join to.
232
  {'key': 'bridge_product_order_lines',
233
  'label': 'Order lines',
234
+ 'source_label': 'Products',
235
  'source': 'product_data', 'target': 'ut_odoo_order_lines',
236
  'source_col': 'product_id', 'target_col': 'product_id',
237
  'where': None, 'served': True, 'cardinality': 'one_to_many'},
238
 
239
  {'key': 'bridge_order_order_lines',
240
  'label': 'Order lines',
241
+ 'source_label': 'Orders',
242
  'source': 'ut_odoo_orders', 'target': 'ut_odoo_order_lines',
243
  'source_col': IDENTITY_COL, 'target_col': 'order_id',
244
  'where': None, 'served': True, 'cardinality': 'one_to_many'},
 
686
  return member_ids_tail(id_sql, member_ids)
687
 
688
 
689
+ class PinRefusal(ValueError):
690
+ """A named refusal that accompanies an explicitly unscoped measure answer."""
691
+
692
+ def __init__(self, code, message, path=()):
693
+ super().__init__(message)
694
+ self.marker = {'code': code, 'message': message, 'path': list(path),
695
+ 'scoped': False}
696
+
697
+
698
+ class MeasureAnswer(dict):
699
+ """Ordinary value mapping plus `refusals` for the host's response envelope.
700
+
701
+ Hosts must serialize `refusals` alongside the values when accepting a related pin.
702
+ Keeping metadata out of the pid/field namespace preserves every existing mapping consumer.
703
+ """
704
+
705
+ def __init__(self, values=(), refusals=()):
706
+ super().__init__(values)
707
+ self.refusals = list(refusals)
708
+
709
+
710
+ class MeasureMatches(set):
711
+ """Condition membership with the same refusal channel as MeasureAnswer."""
712
+
713
+ def __init__(self, values=(), refusals=()):
714
+ super().__init__(values)
715
+ self.refusals = list(refusals)
716
+
717
+
718
+ _MEASURE_PIN_CONTEXT = ContextVar('measure_pin_context', default=None)
719
+
720
+
721
+ @contextmanager
722
+ def measure_pin_context(*, read, bindings, may_open, fields_for=None, defs=None):
723
+ """Bind the host's permission-checked relation reads to this request only.
724
+
725
+ `read(table, column, values, where)` returns canonical rows, including pid and join
726
+ columns, through the SAME scoped reader used by row windows. It must AND the named
727
+ edge's predicate and membership with the account's wall, without a row-window limit.
728
+ `bindings[semantic_store_table]` declares `{table, column, sql}` rows mapping those
729
+ canonical ids to a metric's SQL. `sql` may contain `{alias}` from the semantic model.
730
+ Neither callbacks nor SQL bindings come from the client's related object.
731
+
732
+ This adapter is necessary because core has no session and cannot import API readers.
733
+ Missing context refuses by name; it never guesses a join or reads an unscoped store.
734
+ """
735
+ token = _MEASURE_PIN_CONTEXT.set(dict(read=read, bindings=bindings, may_open=may_open,
736
+ fields_for=fields_for, defs=defs, cache_key=object()))
737
+ try:
738
+ yield
739
+ finally:
740
+ _MEASURE_PIN_CONTEXT.reset(token)
741
+
742
+
743
+ def measure_pin_key(related):
744
+ """Wire identity plus the trusted read context; permission contexts never share answers."""
745
+ if related is None:
746
+ return None
747
+ ctx = _MEASURE_PIN_CONTEXT.get() or {}
748
+ return json.dumps(related, sort_keys=True, separators=(',', ':')), ctx.get('cache_key')
749
+
750
+
751
+ @dataclass
752
+ class MeasurePin:
753
+ path: list
754
+ rows: dict
755
+ bindings: dict
756
+ refusal: dict = None
757
+
758
+ def predicate(self, store):
759
+ """AND every declared, traversed member set into this metric's raw rows."""
760
+ if self.refusal is not None:
761
+ return None, []
762
+ parts, params = [], []
763
+ for binding in self.bindings.get(store['table'], ()):
764
+ table, column = binding['table'], binding['column']
765
+ if table not in self.rows:
766
+ continue
767
+ values = []
768
+ for row in self.rows[table]:
769
+ if row.get(column) in (None, ''):
770
+ raise PinRefusal('relation_source_unavailable',
771
+ f"The related metric needs '{column}' on '{table}', "
772
+ "but that value could not be read. Values are unscoped.",
773
+ self.path)
774
+ values.append(row[column])
775
+ try:
776
+ sql, args = pin_sql(binding['sql'].format(alias=store['alias']), values)
777
+ except (TypeError, ValueError) as exc:
778
+ raise PinRefusal('relation_binding_unavailable',
779
+ f"The metric binding on '{table}' cannot carry this pin. "
780
+ "Values are unscoped.", self.path) from exc
781
+ parts.append(f'({sql})')
782
+ params.extend(args)
783
+ if not parts:
784
+ raise PinRefusal('relation_binding_unavailable',
785
+ f"The metric source '{store['table']}' has no declared binding "
786
+ "to this record path. Values are unscoped.", self.path)
787
+ return ' AND '.join(parts), params
788
+
789
+
790
+ def measure_pin(related):
791
+ """Resolve only the requested named edges, retaining intermediate row membership.
792
+
793
+ Retaining the intermediate is essential: customer -> lines -> products must not expand
794
+ back to every customer's lines for those products. Empty membership remains a real pin.
795
+ """
796
+ if isinstance(related, MeasurePin):
797
+ return related
798
+ if not isinstance(related, dict):
799
+ raise PinRefusal('bad_relation', 'A related metric needs {table, record, via}.')
800
+ table, record, via = related.get('table'), related.get('record'), related.get('via')
801
+ path = via.get('path') if isinstance(via, dict) else via
802
+ if isinstance(path, str):
803
+ path = [path]
804
+ if isinstance(path, (list, tuple)) and len(path) > MAX_DEPTH:
805
+ raise PinRefusal('over_depth', over_depth_refusal(table, path), path)
806
+ if not isinstance(table, str) or not table or record in (None, ''):
807
+ raise PinRefusal('bad_relation', 'A related metric needs {table, record, via}.')
808
+ ctx = _MEASURE_PIN_CONTEXT.get() or {}
809
+ if ctx and not ctx['may_open'](table):
810
+ raise PinRefusal('forbidden_table',
811
+ f"'{table}' cannot be opened for this record scope. "
812
+ 'Metric values are unscoped.')
813
+ fields_for = ctx.get('fields_for')
814
+ fields = fields_for(table) if fields_for else None
815
+ entries = related_paths(table, fields=fields, defs=ctx.get('defs'),
816
+ may_open=ctx.get('may_open'), fields_for=fields_for)
817
+ if isinstance(via, dict) and path is None:
818
+ # Bag matching still requires an edge name, never just a join-column heuristic.
819
+ entry = pick([e for e in entries if e['hops'] == 1], via) if via.get('key') else None
820
+ else:
821
+ entry = pick_path(entries, path)
822
+ if entry is None:
823
+ if isinstance(path, (list, tuple)) and path:
824
+ diagnosis = diagnose_path(table, path, fields=fields, defs=ctx.get('defs'),
825
+ may_open=ctx.get('may_open'), fields_for=fields_for,
826
+ entries=entries)
827
+ raise PinRefusal(diagnosis['code'], diagnosis['message'], path)
828
+ raise PinRefusal('unknown_relation', unknown_via_refusal(table, via))
829
+ path = entry['path']
830
+ # Resolve each leg before reading. A composite's target is not necessarily the target
831
+ # whose binding is absent; the refusal must name the actual unserved leg.
832
+ hops = [pick_path(entries, path[:1])]
833
+ if len(path) == 2:
834
+ mid = hops[0]['target']
835
+ hops.append(pick_path(related_paths(
836
+ mid, fields=fields_for(mid) if fields_for else None, defs=ctx.get('defs'),
837
+ depth=1, may_open=ctx.get('may_open'), fields_for=fields_for), path[1:]))
838
+ for hop in hops:
839
+ if hop is None:
840
+ raise PinRefusal('unknown_relation', unknown_via_refusal(table, path), path)
841
+ if not hop.get('served'):
842
+ raise PinRefusal('relation_not_served',
843
+ unserved_target_refusal(hop) + '. Metric values are unscoped.', path)
844
+ if not ctx:
845
+ raise PinRefusal('relation_context_required',
846
+ 'This request has no scoped relation reader for metrics. '
847
+ 'Metric values are unscoped.', path)
848
+ rows = {table: list(ctx['read'](table, IDENTITY_COL, [record], None))}
849
+ if not rows[table]:
850
+ raise PinRefusal('relation_source_unavailable',
851
+ f"The origin record could not be read from '{table}'. "
852
+ 'Metric values are unscoped.', path)
853
+ source = table
854
+ for hop in hops:
855
+ frm = hop['via'].get('from') or IDENTITY_COL
856
+ values = [r.get(frm) for r in rows[source]]
857
+ if any(v in (None, '') for v in values):
858
+ raise PinRefusal('relation_source_unavailable',
859
+ unresolvable_source_refusal(source, hop), path)
860
+ target = hop['target']
861
+ rows[target] = list(ctx['read'](target, hop['via'].get('on') or IDENTITY_COL,
862
+ values, hop.get('where'))) if values else []
863
+ source = target
864
+ return MeasurePin(path, rows, ctx['bindings'])
865
+
866
+
867
  def compiled_pin_matches_filter_sql(id_sql, member_ids, columns=None):
868
  """Does `pin_sql` still spell the member tail exactly as `filter_sql` spells it?
869
 
 
1130
  entry['cardinality'] = str(got or 'many_to_many')
1131
  out.append(entry)
1132
  seen = {edge_identity(e) for e in out}
1133
+ # A product bridge is also the declared line -> product hop. Reverse the declared
1134
+ # columns, including product_id, rather than inventing a pid join or searching a path.
1135
+ for bridge in bridges_into(table):
1136
+ entry = _entry(key=f"{bridge['source']}__{bridge['key']}",
1137
+ label=bridge.get('source_label') or bridge['source'],
1138
+ target=bridge['source'], direction='reverse',
1139
+ on=bridge['source_col'], frm=bridge['target_col'],
1140
+ served=bridge['served'],
1141
+ cardinality=_INVERSE.get(_bridge_cardinality(bridge), 'many_to_many'))
1142
+ # A predicate belongs to the forward target; reversing it needs an explicit binding.
1143
+ # Keep such reverse edges absent instead of applying the predicate on the wrong table.
1144
+ if bridge.get('where') or edge_identity(entry) in seen:
1145
+ continue
1146
+ if not _live([entry], include_retired):
1147
+ continue
1148
+ seen.add(edge_identity(entry))
1149
+ out.append(entry)
1150
  for entry in spec_entries(table, include_retired=include_retired):
1151
  if edge_identity(entry) in seen:
1152
  continue
platform/core/user_tables.py CHANGED
@@ -377,6 +377,149 @@ def limit_report(table_key, st=None):
377
  }
378
 
379
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
380
  MAX_FIELDS = 60
381
  #: the badge the nav paints for a table with no connector behind it
382
  BLANK_SOURCE = 'Blank'
 
377
  }
378
 
379
 
380
+ # W57-T37 / instruction 30 / C13: revocation policy belongs to a CREDENTIAL TYPE, not to
381
+ # every connected table. W32 R10 keeps Odoo data for reconnect; Meta has no purge ruling.
382
+ # The API declares its families here because core must never import the connector layer.
383
+ REVOKE_PURGE = 'purge'
384
+ REVOKE_KEEP = 'keep'
385
+ _CREDENTIAL_TABLES = {}
386
+
387
+
388
+ def register_credential_tables(entry_type, prefix, *, on_revoke=REVOKE_KEEP, why='', owner=None):
389
+ """Declare a credential's table family and revocation rule; repeat declarations overwrite.
390
+
391
+ Empty types/prefixes and unknown policies raise ValueError: a typo must not silently KEEP
392
+ data that revocation promised to remove. Without an owner resolver, fixed-key families
393
+ belong to the tenant's designated default connection, as Amazon and Meta do today.
394
+ """
395
+ etype = str(entry_type or '').strip().lower()
396
+ prefix = str(prefix or '').strip().lower()
397
+ if not etype or not prefix:
398
+ raise ValueError('credential type and table prefix must not be empty')
399
+ if on_revoke not in (REVOKE_PURGE, REVOKE_KEEP):
400
+ raise ValueError('credential revocation must be purge or keep')
401
+ if owner is not None and not callable(owner):
402
+ raise ValueError('credential table owner must be callable')
403
+ _CREDENTIAL_TABLES[etype] = {
404
+ 'prefix': prefix, 'on_revoke': on_revoke, 'why': str(why or ''), 'owner': owner,
405
+ }
406
+ return dict(_CREDENTIAL_TABLES[etype])
407
+
408
+
409
+ def credential_table_types():
410
+ """Copy the declarations; a disclosure caller must not be able to rewrite purge policy."""
411
+ return {etype: dict(spec) for etype, spec in _CREDENTIAL_TABLES.items()}
412
+
413
+
414
+ def connection_of_table(table_key, rt=None, st=None):
415
+ """Return (credential type, connection id), or (None, None) outside declared families.
416
+
417
+ The longest prefix wins, never registration order. A broken owner resolver falls back to
418
+ the designated default: calling its tables ownerless would quietly turn a purge into nothing.
419
+ """
420
+ specs = sorted(_CREDENTIAL_TABLES.items(), key=lambda item: -len(item[1]['prefix']))
421
+ for etype, spec in specs:
422
+ if not str(table_key).startswith(spec['prefix']):
423
+ continue
424
+ if rt is None:
425
+ return etype, None
426
+ if spec['owner'] is not None:
427
+ try:
428
+ return etype, spec['owner'](table_key, rt)
429
+ except Exception:
430
+ pass
431
+ # keychain imports the store too; importing sideways here avoids a boot-time cycle.
432
+ from core import keychain
433
+ return etype, keychain.default_connection_id(rt, etype)
434
+ return None, None
435
+
436
+
437
+ def credential_footprint(entry_type, connection_id, rt=None, st=None):
438
+ """Disclose what revoking this ONE credential purges and what its policy keeps.
439
+
440
+ A read-through table's row count is UNKNOWN, not zero: its rows live in the mirror.
441
+ That distinction is the point of [[no-unverifiable-aggregates]] in a deletion dialog;
442
+ a fabricated zero invites consent under the false promise that no records will be lost.
443
+ """
444
+ etype = str(entry_type or '').strip().lower()
445
+ cid = str(connection_id or '')
446
+ spec = credential_table_types().get(etype)
447
+ out = {'type': etype, 'connectionId': cid, 'action': 'none', 'purge': [], 'keep': [],
448
+ 'rows': 0, 'rowsKnown': True, 'why': 'This credential type spawns no databases.'}
449
+ if spec is None:
450
+ return out
451
+ out.update(action=spec['on_revoke'], why=spec['why'])
452
+ if not cid:
453
+ return out
454
+
455
+ class _Reads:
456
+ # all_defs/all_tables serve display fallbacks on store errors. A revocation cannot
457
+ # mistake that empty fallback for proof there is nothing to delete. Projection failure
458
+ # may still recover through the whole read; only failure of that read is fatal here.
459
+ error = None
460
+
461
+ def get_projection(self, name, drop=()):
462
+ return _st(st).get_projection(name, drop=drop)
463
+
464
+ def get(self, name):
465
+ try:
466
+ return _st(st).get(name)
467
+ except Exception as exc:
468
+ self.error = exc
469
+ raise
470
+
471
+ reads = _Reads()
472
+ defs = all_defs(reads)
473
+ if reads.error is not None:
474
+ raise reads.error
475
+ candidates = []
476
+ for key, defn in defs.items():
477
+ if (str(key).startswith(spec['prefix'])
478
+ and connection_of_table(key, rt, st)[1] == cid):
479
+ candidates.append((key, defn, materialises(key, st=st, defn=defn)))
480
+ # all_tables is a 28.6 MB deep copy on tenant #0. No materialised candidate means no row
481
+ # count needs that document, so the disclosure must not pay for it merely to list labels.
482
+ tables = all_tables(reads) if any(known for _, _, known in candidates) else {}
483
+ if reads.error is not None:
484
+ raise reads.error
485
+ for key, defn, known in candidates:
486
+ if known and key not in tables:
487
+ raise RuntimeError('credential table rows could not be read')
488
+ rows = len(tables[key].get('rows') or {}) if known else 0
489
+ out[spec['on_revoke']].append({
490
+ 'key': key, 'label': defn.get('label') or key, 'rows': rows, 'rowsKnown': known,
491
+ })
492
+ for action in (REVOKE_PURGE, REVOKE_KEEP):
493
+ out[action].sort(key=lambda table: table['key'])
494
+ out['rows'] = sum(table['rows'] for table in out['purge'])
495
+ out['rowsKnown'] = all(table['rowsKnown'] for table in out['purge'])
496
+ return out
497
+
498
+
499
+ def purge_credential_tables(entry_type, connection_id, rt=None, st=None):
500
+ """Recompute this credential's footprint, then use the existing artifact-family sweep.
501
+
502
+ A refused or failed delete is residue, never a success count. Exception text may contain
503
+ a store path, so the report carries only its type. A second sweep finds no deleted tables.
504
+ """
505
+ footprint = credential_footprint(entry_type, connection_id, rt=rt, st=st)
506
+ out = {'purged': [], 'refused': [], 'failed': [], 'rows': 0, 'rowsKnown': True,
507
+ 'footprint': footprint}
508
+ for table in footprint['purge']:
509
+ key = table['key']
510
+ try:
511
+ if delete(key, st=st) is False:
512
+ out['refused'].append(key)
513
+ continue
514
+ except Exception as exc:
515
+ out['failed'].append({'key': key, 'error': type(exc).__name__})
516
+ continue
517
+ out['purged'].append(key)
518
+ out['rows'] += table['rows']
519
+ out['rowsKnown'] = out['rowsKnown'] and table['rowsKnown']
520
+ return out
521
+
522
+
523
  MAX_FIELDS = 60
524
  #: the badge the nav paints for a table with no connector behind it
525
  BLANK_SOURCE = 'Blank'
platform/core/users.py CHANGED
@@ -11,6 +11,12 @@ import os
11
  import hmac
12
  import hashlib
13
  import secrets
 
 
 
 
 
 
14
 
15
  import core.store as store
16
 
@@ -70,10 +76,309 @@ def _hash(pw, salt):
70
  return hashlib.pbkdf2_hmac('sha256', str(pw).encode('utf-8'), bytes.fromhex(salt), _ITER).hex()
71
 
72
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
73
  def _record(pw, name, role, bus, active=True, modules='all', agent=None, email=None,
74
  perms=None, tenant='royal-imports', platform_admin=False):
75
  salt = secrets.token_hex(16)
76
  rec = {'salt': salt, 'hash': _hash(pw, salt), 'name': name, 'role': role,
 
77
  'bus': bus, 'active': active, 'modules': modules,
78
  'agent': agent or None, 'email': email or None,
79
  # Wave 18 (C1-TENANT, R1): the account's COMPANY. Absent == 'royal-imports' on every
@@ -121,6 +426,8 @@ def ensure_bootstrap():
121
  master = os.environ.get('APP_PASSWORD', '')
122
  if not master:
123
  return
 
 
124
  try:
125
  store.put('users', {'admin': _record(master, 'Administrator', 'admin', 'all')})
126
  except Exception:
@@ -297,8 +604,12 @@ def create_user(username, pw, name, role='user', bus='all', modules='all',
297
  session-invalidating as a password change, and it usually IS one.
298
  """
299
  username = (username or '').strip().lower()
300
- if not username or not pw:
301
  raise ValueError('username and password are required')
 
 
 
 
302
 
303
  def _add(reg):
304
  prior = reg.get(username) or {}
@@ -321,14 +632,36 @@ def create_user(username, pw, name, role='user', bus='all', modules='all',
321
  store.update('users', _add)
322
 
323
 
324
- def set_password(username, pw):
 
 
 
 
 
325
  username = (username or '').strip().lower()
 
 
 
 
 
 
 
 
 
 
 
326
 
327
  def _set(reg):
328
  u = reg.get(username)
329
  if u:
 
 
 
 
330
  u['salt'] = secrets.token_hex(16)
331
  u['hash'] = _hash(pw, u['salt'])
 
 
332
  # X3: a password change revokes every outstanding API session for the account. Bumped
333
  # INSIDE the same read-modify-write as the hash so the two can never disagree — a
334
  # separate update() could rotate the password and leave old cookies live if the second
@@ -338,6 +671,24 @@ def set_password(username, pw):
338
  store.update('users', _set)
339
 
340
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
341
  def set_active(username, active):
342
  username = (username or '').strip().lower()
343
 
@@ -454,6 +805,11 @@ def flush_stamps(timeout=10.0):
454
  return all(not t.is_alive() for t in pending)
455
 
456
 
 
 
 
 
 
457
  def touch_login(username, when=None):
458
  """Stamp `last_login` (ISO-8601, UTC, OFFSET-BEARING) on a SUCCESSFUL login.
459
 
 
11
  import hmac
12
  import hashlib
13
  import secrets
14
+ import re
15
+ import base64
16
+ import binascii
17
+ import struct
18
+ import time
19
+ from urllib.parse import quote
20
 
21
  import core.store as store
22
 
 
76
  return hashlib.pbkdf2_hmac('sha256', str(pw).encode('utf-8'), bytes.fromhex(salt), _ITER).hex()
77
 
78
 
79
+ # ------------------------------------------------------------------ password policy (W57-T35 / C12)
80
+ # ONE policy for account creation and both rotation doors. Login only reads the age: checking
81
+ # history there would spend six PBKDF2 passes on every sign-in without improving authentication.
82
+ PASSWORD_MIN_LENGTH = 12
83
+ PASSWORD_MAX_LENGTH = 256 # bound PBKDF2 input, not a claim about strength
84
+ PASSWORD_HISTORY = 5
85
+ PASSWORD_MAX_AGE_DAYS = 90
86
+
87
+
88
+ class PasswordPolicyError(ValueError):
89
+ """Raised with FAILED RULES attached, never a bare message.
90
+
91
+ `.failures` is a list of {"rule": <stable id>, "message": <the rule in words>}.
92
+ """
93
+ def __init__(self, failures):
94
+ self.failures = [dict(failure) for failure in failures]
95
+ super().__init__('; '.join(failure['message'] for failure in self.failures))
96
+
97
+
98
+ def password_rules():
99
+ """The public checklist, including the rules enforced over an account's lifetime."""
100
+ return [
101
+ {'rule': 'length', 'message': f'it must be at least {PASSWORD_MIN_LENGTH} characters'},
102
+ {'rule': 'max_length',
103
+ 'message': f'it must be no longer than {PASSWORD_MAX_LENGTH} characters'},
104
+ {'rule': 'uppercase', 'message': 'it must contain at least one capital letter'},
105
+ {'rule': 'lowercase', 'message': 'it must contain at least one small letter'},
106
+ {'rule': 'digit', 'message': 'it must contain at least one number'},
107
+ {'rule': 'symbol',
108
+ 'message': 'it must contain at least one character that is not a letter or a number'},
109
+ {'rule': 'identifier',
110
+ 'message': 'it must not contain the username, the email local part, or any word of '
111
+ 'the display name that is 3 characters or longer'},
112
+ {'rule': 'reuse',
113
+ 'message': f'it must not repeat the current password or any of the last '
114
+ f'{PASSWORD_HISTORY} passwords'},
115
+ {'rule': 'expiry', 'message': f'it must be changed every {PASSWORD_MAX_AGE_DAYS} days'},
116
+ ]
117
+
118
+
119
+ def password_failures(pw, username=None, name=None, email=None, record=None):
120
+ """Every rule this password breaks, in policy order. Empty list means it passes."""
121
+ pw = str(pw or '')
122
+ # Case-fold identifiers, but never the credential being hashed. Name punctuation separates
123
+ # words too, so a hyphenated display name cannot slip through a whitespace-only split.
124
+ identifiers = [str(username or '').strip().casefold(),
125
+ str(email or '').strip().split('@', 1)[0].casefold()]
126
+ identifiers.extend(word.casefold() for word in re.findall(r'[^\W_]+', str(name or ''))
127
+ if len(word) >= 3)
128
+ folded = pw.casefold()
129
+ broken = {
130
+ 'length': len(pw) < PASSWORD_MIN_LENGTH,
131
+ 'max_length': len(pw) > PASSWORD_MAX_LENGTH,
132
+ 'uppercase': not any(c.isupper() for c in pw),
133
+ 'lowercase': not any(c.islower() for c in pw),
134
+ 'digit': not any(c.isdigit() for c in pw),
135
+ 'symbol': not any(not c.isalnum() for c in pw),
136
+ 'identifier': any(identifier and identifier in folded for identifier in identifiers),
137
+ }
138
+ # An oversized value is already refused; do not feed it to PBKDF2 merely to describe reuse.
139
+ # Every history entry owns its own salt, so comparing against only today's salt proves nothing.
140
+ if record is not None and len(pw) <= PASSWORD_MAX_LENGTH:
141
+ for credential in [record, *(record.get('password_history') or [])]:
142
+ if (credential.get('salt') and credential.get('hash')
143
+ and hmac.compare_digest(_hash(pw, credential['salt']), credential['hash'])):
144
+ broken['reuse'] = True
145
+ break
146
+ return [rule for rule in password_rules() if broken.get(rule['rule'])]
147
+
148
+
149
+ def password_changed_at(record):
150
+ """The stored ISO timestamp, or None when absent or unreadable."""
151
+ import datetime as _dt
152
+ stamp = (record or {}).get('password_changed_at')
153
+ try:
154
+ parsed = _dt.datetime.fromisoformat(stamp)
155
+ # Our writer always includes an offset. A partial legacy/manual stamp must never raise
156
+ # while comparing it with UTC on the login path; treat it like an absent stamp instead.
157
+ if parsed.utcoffset() is None:
158
+ return None
159
+ except (TypeError, ValueError, OverflowError):
160
+ return None
161
+ return stamp
162
+
163
+
164
+ def password_age_days(record):
165
+ """Fractional days since the last password change, or None without a readable stamp."""
166
+ import datetime as _dt
167
+ stamp = password_changed_at(record)
168
+ if stamp is None:
169
+ return None
170
+ return (_dt.datetime.now(_dt.timezone.utc) - _dt.datetime.fromisoformat(stamp)).total_seconds() / 86400
171
+
172
+
173
+ def password_expired(record):
174
+ """Whether a forced rotation or the password's age requires the change door."""
175
+ if (record or {}).get('must_change_password') is True:
176
+ return True
177
+ age = password_age_days(record)
178
+ # ABSENT STAMP IS NOT EXPIRED: pre-wave accounts have none, and deploying this policy must
179
+ # not force the whole tenant to reset. Their first successful sign-in starts the clock.
180
+ return age is not None and age > PASSWORD_MAX_AGE_DAYS
181
+
182
+
183
+ def generate_password():
184
+ """A random credential that SATISFIES the policy above, for a caller that has none to offer.
185
+
186
+ ⛔ IT EXISTS BECAUSE A GENERATOR AND A VALIDATOR THAT DISAGREE FAIL AT PROVISIONING TIME.
187
+ `provision_web_tenant.py` and `ops/provision_user.py` both defaulted to
188
+ `secrets.token_urlsafe(12)`, whose alphabet contains no symbol and need not contain an
189
+ uppercase letter or a digit in any given draw. Under the policy that is a tenant that
190
+ provisions on Monday and refuses on Tuesday, for no reason anyone could see. So the default
191
+ is built to the rules rather than checked against them, and asserted before it is returned.
192
+
193
+ ⚠ NOT a password anybody types: it is handed to the operator to hand on, and the account is
194
+ expected to rotate it. Entropy is what matters here, which is why the bulk of it is
195
+ `token_urlsafe`.
196
+ """
197
+ for _ in range(8):
198
+ candidate = f"A{secrets.token_urlsafe(16)}9!"
199
+ if not password_failures(candidate):
200
+ return candidate
201
+ # Unreachable in practice; a loop that can silently fall out of the bottom and return a
202
+ # policy-breaking string is exactly the defect this function exists to remove.
203
+ raise RuntimeError('could not generate a password that satisfies the policy')
204
+
205
+
206
+ # ------------------------------------------------------------------ second factor (W57-T36 / C12)
207
+ # RFC 6238: SHA-1, six digits and a 30-second step are what authenticator apps assume.
208
+ # They are constants, not account options: two parameter sets would make a scanned secret
209
+ # produce codes the server never accepts. Twenty random bytes is RFC 4226's reference length.
210
+ MFA_DIGITS = 6
211
+ MFA_PERIOD = 30
212
+ MFA_DRIFT = 1 # accept the previous and next window: phones drift
213
+ MFA_ISSUER = 'Loopable'
214
+ RECOVERY_CODE_COUNT = 10
215
+
216
+
217
+ def new_mfa_secret() -> str:
218
+ return base64.b32encode(secrets.token_bytes(20)).decode('ascii').rstrip('=').upper()
219
+
220
+
221
+ def totp_code(secret, at=None, offset=0) -> str:
222
+ key = base64.b32decode(secret + '=' * (-len(secret) % 8), casefold=True)
223
+ if not key:
224
+ # Padding alone decodes to empty bytes, which is not an authenticator secret.
225
+ raise ValueError('missing authenticator secret')
226
+ counter = int(time.time() if at is None else at) // MFA_PERIOD + offset
227
+ digest = hmac.new(key, struct.pack('>Q', counter), hashlib.sha1).digest()
228
+ start = digest[-1] & 0x0f
229
+ number = struct.unpack('>I', digest[start:start + 4])[0] & 0x7fffffff
230
+ return str(number % (10 ** MFA_DIGITS)).zfill(MFA_DIGITS)
231
+
232
+
233
+ def totp_valid(secret, code, at=None) -> bool:
234
+ if not isinstance(secret, str) or not secret:
235
+ return False
236
+ code = str(code or '').replace(' ', '')
237
+ if len(code) != MFA_DIGITS or not code.isascii() or not code.isdigit():
238
+ return False
239
+ try:
240
+ # Capture the time once: crossing a step boundary mid-loop must not change the window.
241
+ at = time.time() if at is None else at
242
+ valid = False
243
+ for offset in range(-MFA_DRIFT, MFA_DRIFT + 1):
244
+ # There is no counter before the Unix epoch; this only matters for boundary tests.
245
+ expected = (totp_code(secret, at=at, offset=offset)
246
+ if int(at) // MFA_PERIOD + offset >= 0 else '')
247
+ # Compare EVERY window, even after a match. Early return leaks which window matched.
248
+ valid |= hmac.compare_digest(expected, code)
249
+ return valid
250
+ except (ValueError, TypeError, binascii.Error, struct.error, OverflowError):
251
+ # A malformed stored/candidate secret is an invalid factor, never a login-path 500.
252
+ return False
253
+
254
+
255
+ def otpauth_uri(secret, username, issuer=MFA_ISSUER) -> str:
256
+ label = quote(f'{issuer}:{username}', safe='')
257
+ return (f'otpauth://totp/{label}?secret={quote(secret, safe="")}'
258
+ f'&issuer={quote(issuer, safe="")}&algorithm=SHA1'
259
+ f'&digits={MFA_DIGITS}&period={MFA_PERIOD}')
260
+
261
+
262
+ def new_recovery_codes(n=RECOVERY_CODE_COUNT) -> list[str]:
263
+ codes = []
264
+ while len(codes) < n:
265
+ raw = secrets.token_hex(5).upper()
266
+ code = f'{raw[:5]}-{raw[5:]}'
267
+ # Even the unlikely duplicate must not make one printed code redeemable twice.
268
+ if code not in codes:
269
+ codes.append(code)
270
+ return codes
271
+
272
+
273
+ def _recovery_key(code) -> str:
274
+ # NOT PBKDF2: a recovery code is 40 bits of CSPRNG output with no user-chosen structure,
275
+ # so there is no password dictionary to run against it. Stretching adds no entropy; the
276
+ # codes use SHA-256 here. A PASSWORD is different and stays on PBKDF2-200k.
277
+ normal = str(code or '').strip().upper().replace('-', '').replace(' ', '')
278
+ return hashlib.sha256(normal.encode('utf-8')).hexdigest()
279
+
280
+
281
+ def mfa_enrolled(record) -> bool:
282
+ secret = (record or {}).get('mfa_secret')
283
+ return isinstance(secret, str) and bool(secret.strip())
284
+
285
+
286
+ class MFAStateError(ValueError):
287
+ """A concurrent enrolment or credential change refused an MFA write, before mutation."""
288
+
289
+
290
+ def set_mfa(username, secret, recovery_codes, *, require_unenrolled=False, expected_epoch=None):
291
+ """Store the factor and hashed codes together, returning the LANDED revocation epoch.
292
+
293
+ The optional guards bind the HTTP door's decision to the actual write. A route-only
294
+ enrolment check lets two workers both issue a first set of codes; an epoch check prevents
295
+ regeneration racing an admin reset from silently reinstalling the lost factor.
296
+ """
297
+ username = (username or '').strip().lower()
298
+ # The replay closure captures only hashes, never printable recovery codes: the HF store
299
+ # journals closures for conflict replay, and that journal must not retain clear codes.
300
+ hashes = [_recovery_key(c) for c in recovery_codes]
301
+ bumped = {}
302
+
303
+ def _set(reg):
304
+ bumped.clear() # a replay may find the account gone
305
+ u = reg.get(username)
306
+ if u:
307
+ if require_unenrolled and mfa_enrolled(u):
308
+ raise MFAStateError('already_enrolled')
309
+ if expected_epoch is not None and int(u.get('epoch') or 0) != expected_epoch:
310
+ raise MFAStateError('changed')
311
+ u['mfa_secret'] = secret
312
+ u['recovery_codes'] = list(hashes)
313
+ u['mfa_enrolled_at'] = _now_iso()
314
+ # C12: enrolment and code rotation revoke old cookies in the SAME update as the
315
+ # secret. A separate bump could fail after enrolment and leave every old cookie live.
316
+ u['epoch'] = int(u.get('epoch') or 0) + 1
317
+ bumped['epoch'] = u['epoch']
318
+ return reg
319
+ landed = store.update('users', _set)
320
+ if 'epoch' not in bumped:
321
+ return None
322
+ # As with bump_epoch, a rebased document can land at a newer epoch than our first attempt.
323
+ try:
324
+ rec = (landed or {}).get(username) or {}
325
+ if rec.get('epoch') is not None:
326
+ return int(rec['epoch'])
327
+ except Exception:
328
+ pass
329
+ return int(bumped['epoch'])
330
+
331
+
332
+ def clear_mfa(username):
333
+ """Admin lost-factor reset: remove enrolment and revoke every session in one write."""
334
+ username = (username or '').strip().lower()
335
+
336
+ def _set(reg):
337
+ u = reg.get(username)
338
+ if u:
339
+ for key in ('mfa_secret', 'recovery_codes', 'mfa_enrolled_at'):
340
+ u.pop(key, None)
341
+ # Absence sends the next login through phone enrolment; the bump kills old cookies.
342
+ u['epoch'] = int(u.get('epoch') or 0) + 1
343
+ return reg
344
+ store.update('users', _set)
345
+
346
+
347
+ def consume_recovery_code(username, code) -> bool:
348
+ username = (username or '').strip().lower()
349
+ wanted = _recovery_key(code)
350
+ consumed = [False]
351
+
352
+ def _set(reg):
353
+ consumed[0] = False # report the final replay, not an earlier attempt
354
+ u = reg.get(username)
355
+ if u:
356
+ hashes = u.get('recovery_codes') or []
357
+ matched = None
358
+ for i, stored in enumerate(hashes):
359
+ equal = hmac.compare_digest(stored, wanted)
360
+ # Compare EVERY entry, retaining only the first match; never leak its position.
361
+ if equal and matched is None:
362
+ matched = i
363
+ if matched is not None:
364
+ u['recovery_codes'] = hashes[:matched] + hashes[matched + 1:]
365
+ consumed[0] = True
366
+ # NO EPOCH BUMP: this runs during sign-in. Login owns the bump and the cookie it
367
+ # is about to mint; consuming a code must not independently invalidate that cookie.
368
+ return reg
369
+ store.update('users', _set)
370
+ return consumed[0]
371
+
372
+
373
+ def recovery_codes_remaining(record) -> int:
374
+ return len((record or {}).get('recovery_codes') or [])
375
+
376
+
377
  def _record(pw, name, role, bus, active=True, modules='all', agent=None, email=None,
378
  perms=None, tenant='royal-imports', platform_admin=False):
379
  salt = secrets.token_hex(16)
380
  rec = {'salt': salt, 'hash': _hash(pw, salt), 'name': name, 'role': role,
381
+ 'password_changed_at': _now_iso(),
382
  'bus': bus, 'active': active, 'modules': modules,
383
  'agent': agent or None, 'email': email or None,
384
  # Wave 18 (C1-TENANT, R1): the account's COMPANY. Absent == 'royal-imports' on every
 
426
  master = os.environ.get('APP_PASSWORD', '')
427
  if not master:
428
  return
429
+ # Keep the fresh-store break-glass seed exempt from the password policy. Rejecting whatever
430
+ # APP_PASSWORD holds here could leave a new deployment with nobody able to sign in.
431
  try:
432
  store.put('users', {'admin': _record(master, 'Administrator', 'admin', 'all')})
433
  except Exception:
 
604
  session-invalidating as a password change, and it usually IS one.
605
  """
606
  username = (username or '').strip().lower()
607
+ if not username:
608
  raise ValueError('username and password are required')
609
+ # Refuse before the update so even an empty password names its broken rules and writes nothing.
610
+ failures = password_failures(pw, username=username, name=name, email=email)
611
+ if failures:
612
+ raise PasswordPolicyError(failures)
613
 
614
  def _add(reg):
615
  prior = reg.get(username) or {}
 
632
  store.update('users', _add)
633
 
634
 
635
+ def set_password(username, pw, enforce=True):
636
+ """Rotate the credential, bounded history, age and epoch in one write.
637
+
638
+ `enforce=False` is only for a caller that already validated (or a future migration) to rotate
639
+ without re-reading. The admin password route is that one caller; all others enforce here.
640
+ """
641
  username = (username or '').strip().lower()
642
+ if enforce:
643
+ try:
644
+ reg = store.get('users', fresh=True) or {}
645
+ except Exception:
646
+ reg = {}
647
+ rec = reg.get(username) or {}
648
+ # This must happen BEFORE store.update: refusing a rule may never leave half a rotation.
649
+ failures = password_failures(pw, username=username, name=rec.get('name'),
650
+ email=rec.get('email'), record=rec)
651
+ if failures:
652
+ raise PasswordPolicyError(failures)
653
 
654
  def _set(reg):
655
  u = reg.get(username)
656
  if u:
657
+ # Merge into the fresh record rather than rebuilding it: access and concurrent
658
+ # activity stamps must survive, and each retired credential keeps the salt it used.
659
+ u['password_history'] = ([{'salt': u['salt'], 'hash': u['hash'], 'at': _now_iso()}]
660
+ + (u.get('password_history') or []))[:PASSWORD_HISTORY]
661
  u['salt'] = secrets.token_hex(16)
662
  u['hash'] = _hash(pw, u['salt'])
663
+ u['password_changed_at'] = _now_iso()
664
+ u.pop('must_change_password', None)
665
  # X3: a password change revokes every outstanding API session for the account. Bumped
666
  # INSIDE the same read-modify-write as the hash so the two can never disagree — a
667
  # separate update() could rotate the password and leave old cookies live if the second
 
671
  store.update('users', _set)
672
 
673
 
674
+ def set_must_change_password(username, on):
675
+ """Require a new password at next login, revoking existing sessions in the same write."""
676
+ username = (username or '').strip().lower()
677
+
678
+ def _set(reg):
679
+ u = reg.get(username)
680
+ if u:
681
+ if on:
682
+ u['must_change_password'] = True
683
+ else:
684
+ u.pop('must_change_password', None)
685
+ # The flag blocks FUTURE logins; the epoch kills sessions already issued. Clearing
686
+ # the flag also bumps so it can never resurrect a cookie from before the forced reset.
687
+ u['epoch'] = int(u.get('epoch') or 0) + 1
688
+ return reg
689
+ store.update('users', _set)
690
+
691
+
692
  def set_active(username, active):
693
  username = (username or '').strip().lower()
694
 
 
805
  return all(not t.is_alive() for t in pending)
806
 
807
 
808
+ def stamp_password_age(username, when=None):
809
+ """Backfill a legacy account's clock through the same fail-silent merge as login activity."""
810
+ return _stamp(username, {'password_changed_at': when or _now_iso()})
811
+
812
+
813
  def touch_login(username, when=None):
814
  """Stamp `last_login` (ISO-8601, UTC, OFFSET-BEARING) on a SUCCESSFUL login.
815
 
platform/harness/amazon_client.py CHANGED
@@ -46,7 +46,10 @@ Ideation record, with every owner ruling: `AutoWiki/research/ideation/amazon-con
46
  """
47
  from __future__ import annotations
48
 
 
49
  import json
 
 
50
  import time
51
  import urllib.error
52
  import urllib.parse
@@ -55,6 +58,33 @@ import urllib.request
55
  KEY = "amazon_sp"
56
  LABEL = "Amazon"
57
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
58
  #: ⚠ MUST MATCH `core.keychain.ENTRY_TYPES` OR `add_entry` 400s with a message about our data
59
  #: structure on a screen about their Amazon account. That was the wave-31 Meta defect and the
60
  #: comments in `keychain.py` warn about it in as many words.
@@ -165,13 +195,13 @@ REPORT_TYPES = {
165
  "report": "GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL",
166
  "report_incremental": "GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL",
167
  "validates_against": "order report totals vs our order rows",
168
- "role": "Inventory and Order Management",
169
  },
170
  "order_items": {
171
  "report": "GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL",
172
  "report_incremental": "GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL",
173
  "validates_against": "order report line totals vs our item rows",
174
- "role": "Inventory and Order Management",
175
  },
176
  "listings": {
177
  "report": "GET_MERCHANT_LISTINGS_ALL_DATA",
@@ -203,7 +233,7 @@ REPORT_TYPES = {
203
  # ⛔⛔ O5 IS CLOSED AND THE ANSWER IS NO (researched 2026-09-04). All 101 report types were
204
  # enumerated and ZERO contain BUYBOX, PRICING, PRICE or COMPETITIVE. So this table SPLITS:
205
  # Buy Box SHARE -> GET_SALES_AND_TRAFFIC_REPORT.salesAndTrafficByAsin.buyBoxPercentage,
206
- # which IS bulk. ⚠ needs the BrandAnalytics role, the same one R5 marks
207
  # UNPROVEN, so this row inherits that risk.
208
  # Buy Box PRICE -> Product Pricing entity endpoints ONLY. No bulk path exists.
209
  # ⛔ STANDING RULE 1'S SECOND HALF: the ceiling is Amazon's and cannot be removed, so it is
@@ -218,7 +248,7 @@ REPORT_TYPES = {
218
  "report_covers": "buy box SHARE only; PRICE has no bulk path",
219
  "price_path": "productPricing/2022-05-01 getCompetitiveSummary (batch 20, 0.033/sec)",
220
  "validates_against": "sales and traffic report totals vs our rows",
221
- "role": "Pricing + BrandAnalytics",
222
  },
223
  "brand_analytics": {
224
  # ⚠ Returns data only for Brand Registry brand owners (owner ruling R5). Carried as the
@@ -226,7 +256,7 @@ REPORT_TYPES = {
226
  # for any registered brand, else demote to a declared-but-unsynced stub.
227
  "report": "GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT",
228
  "validates_against": "report period totals vs our search-term rows",
229
- "role": "BrandAnalytics",
230
  },
231
  }
232
 
@@ -236,9 +266,9 @@ REPORT_TYPES = {
236
  #: architecture review over screen share at developer registration.
237
  #: · https://developer-docs.amazon.com/sp-api/docs/register-as-a-public-developer
238
  ROLES_TAKEN = (
239
- "Inventory and Order Management", "Amazon Fulfillment",
240
  "Amazon Warehousing and Distribution", "Finance and Accounting",
241
- "Pricing", "Product Listing", "BrandAnalytics", "Selling Partner Insights",
242
  )
243
  ROLES_REFUSED = ("Buyer Communication", "Buyer Solicitation")
244
 
@@ -250,6 +280,17 @@ class AmazonError(RuntimeError):
250
  """Any refusal from LWA or SP-API, already stripped of anything secret."""
251
 
252
 
 
 
 
 
 
 
 
 
 
 
 
253
  def _safe(url):
254
  """A URL fit to appear in an error message: query string dropped entirely.
255
 
@@ -264,6 +305,49 @@ def _safe(url):
264
  return "<url>"
265
 
266
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
267
  def _post_form(url, data, timeout=_TIMEOUT):
268
  body = urllib.parse.urlencode(data).encode("ascii")
269
  req = urllib.request.Request(url, data=body, method="POST")
@@ -318,43 +402,51 @@ def _request(path, token, region=DEFAULT_REGION, method="GET", timeout=_TIMEOUT,
318
  """
319
  if str(method).upper() != "GET":
320
  raise AmazonError("this connector is read-only: only GET is permitted")
321
- # ⚠ AN EXPLICIT FLAG, NOT A `fields` DICT. This function is handed a TOKEN, never the
322
- # credential -- deliberately, so a secret cannot reach the request builder at all -- so the
323
- # sandbox decision is made by the caller that does hold the credential and passed in as one
324
- # boolean. A first draft reached for `fields` here, which does not exist in this scope.
325
- base = (SANDBOX_ENDPOINTS if sandbox else ENDPOINTS).get(
326
- str(region or DEFAULT_REGION).lower())
327
- if not base:
328
- raise AmazonError(f"unknown region `{region}`")
329
- clean = {k: v for k, v in (params or {}).items() if v not in (None, "")}
330
- url = f"{base}/{str(path).lstrip('/')}"
331
- if clean:
332
- url += "?" + urllib.parse.urlencode(clean, doseq=True)
333
- req = urllib.request.Request(url, method="GET")
334
- req.add_header("x-amz-access-token", token)
335
- req.add_header("Accept", "application/json")
336
- req.add_header("User-Agent", _UA)
337
- try:
338
- with urllib.request.urlopen(req, timeout=timeout) as r:
339
- return json.loads(r.read().decode("utf-8") or "{}")
340
- except urllib.error.HTTPError as e:
341
- detail = ""
342
  try:
343
- payload = json.loads((e.read() or b"").decode("utf-8") or "{}")
344
- errs = payload.get("errors") or []
345
- if errs:
346
- detail = str((errs[0] or {}).get("message") or "")[:200]
347
- except Exception: # noqa: BLE001
348
  detail = ""
349
- # 429 is the rate limiter, and standing rule 1 wants it NAMED rather than swallowed.
350
- if e.code == 429:
351
- raise AmazonError(
352
- f"{_safe(url)} was throttled (429). SP-API is token-bucket limited per operation; "
353
- "the fix is the Reports API bulk path, not a slower page loop") from None
354
- raise AmazonError(f"{_safe(url)} answered {e.code}"
355
- + (f": {detail}" if detail else "")) from None
356
- except Exception as e: # noqa: BLE001
357
- raise AmazonError(f"{_safe(url)} unreachable: {type(e).__name__}") from None
 
 
 
 
 
 
 
 
 
 
 
 
358
 
359
 
360
  #: ⛔⛔ THE ONE NON-GET PATH IN THIS MODULE, AND IT IS A CONSTANT RATHER THAN A PARAMETER.
@@ -384,51 +476,60 @@ def _create_report(token, report_type, marketplace_ids, region=DEFAULT_REGION,
384
  ⛔ NO `path` PARAMETER, ON PURPOSE. See `_REPORTS_CREATE_PATH` above: the whole safety argument
385
  is that this function can reach exactly one operation and a caller cannot redirect it.
386
  """
387
- base = (SANDBOX_ENDPOINTS if sandbox else ENDPOINTS).get(
388
- str(region or DEFAULT_REGION).lower())
389
- if not base:
390
- raise AmazonError(f"unknown region `{region}`")
391
- body = {"reportType": str(report_type),
392
- "marketplaceIds": list(marketplace_ids or [US_MARKETPLACE_ID])}
393
- if start:
394
- body["dataStartTime"] = str(start)
395
- if end:
396
- body["dataEndTime"] = str(end)
397
- if options:
398
- body["reportOptions"] = dict(options)
399
- url = f"{base}/{_REPORTS_CREATE_PATH}"
400
- req = urllib.request.Request(url, data=json.dumps(body).encode("utf-8"), method="POST")
401
- req.add_header("x-amz-access-token", token)
402
- req.add_header("Content-Type", "application/json")
403
- req.add_header("Accept", "application/json")
404
- req.add_header("User-Agent", _UA)
405
- try:
406
- with urllib.request.urlopen(req, timeout=timeout) as r:
407
- got = json.loads(r.read().decode("utf-8") or "{}")
408
- except urllib.error.HTTPError as e:
409
- detail = ""
410
  try:
411
- errs = (json.loads((e.read() or b"").decode("utf-8") or "{}").get("errors") or [])
412
- detail = str((errs[0] or {}).get("message") or "")[:200] if errs else ""
413
- except Exception: # noqa: BLE001
414
  detail = ""
415
- if e.code == 429:
416
- raise AmazonError(
417
- f"{_safe(url)} was throttled (429) creating a {report_type} report. Report "
418
- "creation is limited to about one call every 60 seconds with a burst of 15; the "
419
- "fix is fewer, wider report windows, not more frequent requests") from None
420
- if e.code == 403:
421
- raise AmazonError(
422
- f"{_safe(url)} refused a {report_type} report (403). That is a ROLE answer: this "
423
- "report needs a role the application was not granted") from None
424
- raise AmazonError(f"{_safe(url)} answered {e.code}"
425
- + (f": {detail}" if detail else "")) from None
426
- except Exception as e: # noqa: BLE001
427
- raise AmazonError(f"{_safe(url)} unreachable: {type(e).__name__}") from None
428
- rid = str(got.get("reportId") or "")
429
- if not rid:
430
- raise AmazonError(f"Amazon accepted the {report_type} request but returned no reportId")
431
- return rid
 
 
 
 
 
 
 
 
 
 
 
 
432
 
433
 
434
  #: Terminal processing states. `DONE` is the only one that yields a document.
@@ -454,8 +555,15 @@ def report_document(fields, report_type, start=None, end=None, options=None,
454
  region = str((fields or {}).get("region") or DEFAULT_REGION)
455
  mkts = [str((fields or {}).get("marketplace_id") or US_MARKETPLACE_ID)]
456
  sbx = is_sandbox(fields)
457
- rid = _create_report(token, report_type, mkts, region=region, start=start, end=end,
458
- options=options, timeout=timeout, sandbox=sbx)
 
 
 
 
 
 
 
459
  say(f" {report_type}: reportId {rid}")
460
 
461
  waited, state, doc_id = 0, "", ""
 
46
  """
47
  from __future__ import annotations
48
 
49
+ import contextvars
50
  import json
51
+ import random
52
+ import threading
53
  import time
54
  import urllib.error
55
  import urllib.parse
 
58
  KEY = "amazon_sp"
59
  LABEL = "Amazon"
60
 
61
+ #: W57-T38/C13: five total attempts, including the first, bound one throttled operation.
62
+ RETRY_MAX_ATTEMPTS = 5
63
+ #: W57-T38/C13: exponential backoff starts at one second after the first 429.
64
+ RETRY_BASE_SECONDS = 1.0
65
+ #: W57-T38/C13: no individual retry sleep exceeds one minute, including Retry-After/jitter.
66
+ RETRY_MAX_SECONDS = 60.0
67
+ #: W57-T38/C13: randomize each wait by up to half its value to separate competing clients.
68
+ RETRY_JITTER = 0.5
69
+ #: W57-T38/C13: separate consecutive table report creations by at least five seconds.
70
+ REPORT_STAGGER_SECONDS = 5.0
71
+ #: Amazon createReport usage plan: 15 initial tokens, shared by callers in this process.
72
+ #: https://developer-docs.amazon.com/sp-api/reference/createreport
73
+ REPORT_BURST = 15
74
+ #: Amazon createReport usage plan: 0.0167 requests/second, approximately one token/minute.
75
+ #: https://developer-docs.amazon.com/sp-api/reference/createreport
76
+ REPORT_SUSTAINED_SECONDS = 60.0
77
+
78
+ # ⭐ One process-wide bucket and lock prevent concurrent syncs from spending the same token.
79
+ # The contextual wait belongs to the current report_document logger, never another sync's log.
80
+ _report_pacer = {
81
+ "tokens": float(REPORT_BURST),
82
+ "updated": None,
83
+ "last_create": None,
84
+ "lock": threading.Lock(),
85
+ "waited": contextvars.ContextVar("amazon_report_create_waited", default=0.0),
86
+ }
87
+
88
  #: ⚠ MUST MATCH `core.keychain.ENTRY_TYPES` OR `add_entry` 400s with a message about our data
89
  #: structure on a screen about their Amazon account. That was the wave-31 Meta defect and the
90
  #: comments in `keychain.py` warn about it in as many words.
 
195
  "report": "GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL",
196
  "report_incremental": "GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL",
197
  "validates_against": "order report totals vs our order rows",
198
+ "role": "Inventory and Order Tracking",
199
  },
200
  "order_items": {
201
  "report": "GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL",
202
  "report_incremental": "GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL",
203
  "validates_against": "order report line totals vs our item rows",
204
+ "role": "Inventory and Order Tracking",
205
  },
206
  "listings": {
207
  "report": "GET_MERCHANT_LISTINGS_ALL_DATA",
 
233
  # ⛔⛔ O5 IS CLOSED AND THE ANSWER IS NO (researched 2026-09-04). All 101 report types were
234
  # enumerated and ZERO contain BUYBOX, PRICING, PRICE or COMPETITIVE. So this table SPLITS:
235
  # Buy Box SHARE -> GET_SALES_AND_TRAFFIC_REPORT.salesAndTrafficByAsin.buyBoxPercentage,
236
+ # which IS bulk. ⚠ needs the Brand Analytics role, the same one R5 marks
237
  # UNPROVEN, so this row inherits that risk.
238
  # Buy Box PRICE -> Product Pricing entity endpoints ONLY. No bulk path exists.
239
  # ⛔ STANDING RULE 1'S SECOND HALF: the ceiling is Amazon's and cannot be removed, so it is
 
248
  "report_covers": "buy box SHARE only; PRICE has no bulk path",
249
  "price_path": "productPricing/2022-05-01 getCompetitiveSummary (batch 20, 0.033/sec)",
250
  "validates_against": "sales and traffic report totals vs our rows",
251
+ "role": "Pricing + Brand Analytics",
252
  },
253
  "brand_analytics": {
254
  # ⚠ Returns data only for Brand Registry brand owners (owner ruling R5). Carried as the
 
256
  # for any registered brand, else demote to a declared-but-unsynced stub.
257
  "report": "GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT",
258
  "validates_against": "report period totals vs our search-term rows",
259
+ "role": "Brand Analytics",
260
  },
261
  }
262
 
 
266
  #: architecture review over screen share at developer registration.
267
  #: · https://developer-docs.amazon.com/sp-api/docs/register-as-a-public-developer
268
  ROLES_TAKEN = (
269
+ "Inventory and Order Tracking", "Amazon Fulfillment",
270
  "Amazon Warehousing and Distribution", "Finance and Accounting",
271
+ "Pricing", "Product Listing", "Brand Analytics", "Selling Partner Insights",
272
  )
273
  ROLES_REFUSED = ("Buyer Communication", "Buyer Solicitation")
274
 
 
280
  """Any refusal from LWA or SP-API, already stripped of anything secret."""
281
 
282
 
283
+ class AmazonThrottled(AmazonError):
284
+ """An SP-API 429, with an optional Retry-After delay in seconds."""
285
+
286
+ def __init__(self, message, retry_after=None):
287
+ super().__init__(message)
288
+ try:
289
+ self.retry_after = max(0.0, float(retry_after)) if retry_after is not None else None
290
+ except (TypeError, ValueError):
291
+ self.retry_after = None
292
+
293
+
294
  def _safe(url):
295
  """A URL fit to appear in an error message: query string dropped entirely.
296
 
 
305
  return "<url>"
306
 
307
 
308
+ def _retry(attempt_fn, what, *, sleep=time.sleep, rand=random.random):
309
+ """Retry only SP-API throttling; return successes and propagate other refusals unchanged."""
310
+ for n in range(1, RETRY_MAX_ATTEMPTS + 1):
311
+ try:
312
+ return attempt_fn()
313
+ except AmazonThrottled as e:
314
+ if n == RETRY_MAX_ATTEMPTS:
315
+ # ⛔ probe_credential exposes str(e)[:200]; amazon_store.sync stores str(e)[:160].
316
+ # Throttle, cause AND the complete fix must fit in the first 160 characters;
317
+ # this head is 152 with the named cap. Operation/URL detail must stay AFTER it.
318
+ raise AmazonThrottled(
319
+ f"Amazon throttled (429); {n - 1} retries spent. "
320
+ "Cause: SP-API limits per operation, app and seller. "
321
+ "Fix: sync fewer tables at once and widen the report window. "
322
+ f"Operation: {_safe(what)}", retry_after=e.retry_after) from None
323
+ wait = min(RETRY_MAX_SECONDS, RETRY_BASE_SECONDS * 2 ** (n - 1))
324
+ floor = min(RETRY_MAX_SECONDS, e.retry_after or 0.0)
325
+ wait = max(wait, floor)
326
+ wait *= 1 - RETRY_JITTER + RETRY_JITTER * rand() * 2
327
+ # ⭐ Negative jitter must not undo Amazon's Retry-After floor; the named cap wins.
328
+ sleep(min(RETRY_MAX_SECONDS, max(0.0, floor, wait)))
329
+
330
+
331
+ def _pace_report_create(*, sleep=time.sleep, now=time.monotonic):
332
+ """Reserve one report creation under the burst, refill rate and minimum gap; return its wait."""
333
+ with _report_pacer["lock"]:
334
+ stamp = now()
335
+ updated = _report_pacer["updated"]
336
+ elapsed = max(0.0, stamp - updated) if updated is not None else 0.0
337
+ tokens = min(REPORT_BURST, _report_pacer["tokens"] + elapsed / REPORT_SUSTAINED_SECONDS)
338
+ last = _report_pacer["last_create"]
339
+ gap = last + REPORT_STAGGER_SECONDS - stamp if last is not None else 0.0
340
+ wait = max(0.0, gap, (1.0 - tokens) * REPORT_SUSTAINED_SECONDS)
341
+ if wait:
342
+ sleep(wait)
343
+ # ⭐ Count refill during the wait too. A late wake may refill up to the burst, never more.
344
+ issued = max(stamp + wait, now())
345
+ _report_pacer.update(
346
+ tokens=min(REPORT_BURST, tokens + (issued - stamp) / REPORT_SUSTAINED_SECONDS) - 1.0,
347
+ updated=issued, last_create=issued)
348
+ return wait
349
+
350
+
351
  def _post_form(url, data, timeout=_TIMEOUT):
352
  body = urllib.parse.urlencode(data).encode("ascii")
353
  req = urllib.request.Request(url, data=body, method="POST")
 
402
  """
403
  if str(method).upper() != "GET":
404
  raise AmazonError("this connector is read-only: only GET is permitted")
405
+
406
+ def attempt():
407
+ """One raw read-only SP-API attempt, with no retry or pacing policy."""
408
+ # ⚠ AN EXPLICIT FLAG, NOT A `fields` DICT. This function is handed a TOKEN, never the
409
+ # credential -- deliberately, so a secret cannot reach the request builder at all -- so the
410
+ # sandbox decision is made by the caller that does hold the credential and passed in as one
411
+ # boolean. A first draft reached for `fields` here, which does not exist in this scope.
412
+ base = (SANDBOX_ENDPOINTS if sandbox else ENDPOINTS).get(
413
+ str(region or DEFAULT_REGION).lower())
414
+ if not base:
415
+ raise AmazonError(f"unknown region `{region}`")
416
+ clean = {k: v for k, v in (params or {}).items() if v not in (None, "")}
417
+ url = f"{base}/{str(path).lstrip('/')}"
418
+ if clean:
419
+ url += "?" + urllib.parse.urlencode(clean, doseq=True)
420
+ req = urllib.request.Request(url, method="GET")
421
+ req.add_header("x-amz-access-token", token)
422
+ req.add_header("Accept", "application/json")
423
+ req.add_header("User-Agent", _UA)
 
 
424
  try:
425
+ with urllib.request.urlopen(req, timeout=timeout) as r:
426
+ return json.loads(r.read().decode("utf-8") or "{}")
427
+ except urllib.error.HTTPError as e:
 
 
428
  detail = ""
429
+ try:
430
+ payload = json.loads((e.read() or b"").decode("utf-8") or "{}")
431
+ errs = payload.get("errors") or []
432
+ if errs:
433
+ detail = str((errs[0] or {}).get("message") or "")[:200]
434
+ except Exception: # noqa: BLE001
435
+ detail = ""
436
+ # 429 is the rate limiter, and standing rule 1 wants it NAMED rather than swallowed.
437
+ if e.code == 429:
438
+ raise AmazonThrottled(
439
+ f"{_safe(url)} was throttled (429). SP-API is token-bucket limited per operation; "
440
+ "the fix is the Reports API bulk path, not a slower page loop",
441
+ retry_after=(e.headers or {}).get("Retry-After")) from None
442
+ raise AmazonError(f"{_safe(url)} answered {e.code}"
443
+ + (f": {detail}" if detail else "")) from None
444
+ except Exception as e: # noqa: BLE001
445
+ raise AmazonError(f"{_safe(url)} unreachable: {type(e).__name__}") from None
446
+
447
+ base = (SANDBOX_ENDPOINTS if sandbox else ENDPOINTS).get(
448
+ str(region or DEFAULT_REGION).lower(), "")
449
+ return _retry(attempt, f"{base}/{str(path).lstrip('/')}")
450
 
451
 
452
  #: ⛔⛔ THE ONE NON-GET PATH IN THIS MODULE, AND IT IS A CONSTANT RATHER THAN A PARAMETER.
 
476
  ⛔ NO `path` PARAMETER, ON PURPOSE. See `_REPORTS_CREATE_PATH` above: the whole safety argument
477
  is that this function can reach exactly one operation and a caller cannot redirect it.
478
  """
479
+ def attempt():
480
+ """One raw attempt at the declared report-creation POST."""
481
+ base = (SANDBOX_ENDPOINTS if sandbox else ENDPOINTS).get(
482
+ str(region or DEFAULT_REGION).lower())
483
+ if not base:
484
+ raise AmazonError(f"unknown region `{region}`")
485
+ body = {"reportType": str(report_type),
486
+ "marketplaceIds": list(marketplace_ids or [US_MARKETPLACE_ID])}
487
+ if start:
488
+ body["dataStartTime"] = str(start)
489
+ if end:
490
+ body["dataEndTime"] = str(end)
491
+ if options:
492
+ body["reportOptions"] = dict(options)
493
+ url = f"{base}/{_REPORTS_CREATE_PATH}"
494
+ req = urllib.request.Request(url, data=json.dumps(body).encode("utf-8"), method="POST")
495
+ req.add_header("x-amz-access-token", token)
496
+ req.add_header("Content-Type", "application/json")
497
+ req.add_header("Accept", "application/json")
498
+ req.add_header("User-Agent", _UA)
 
 
 
499
  try:
500
+ with urllib.request.urlopen(req, timeout=timeout) as r:
501
+ got = json.loads(r.read().decode("utf-8") or "{}")
502
+ except urllib.error.HTTPError as e:
503
  detail = ""
504
+ try:
505
+ errs = (json.loads((e.read() or b"").decode("utf-8") or "{}").get("errors") or [])
506
+ detail = str((errs[0] or {}).get("message") or "")[:200] if errs else ""
507
+ except Exception: # noqa: BLE001
508
+ detail = ""
509
+ if e.code == 429:
510
+ raise AmazonThrottled(
511
+ f"{_safe(url)} was throttled (429) creating a {report_type} report. Report "
512
+ "creation is limited to about one call every 60 seconds with a burst of 15; the "
513
+ "fix is fewer, wider report windows, not more frequent requests",
514
+ retry_after=(e.headers or {}).get("Retry-After")) from None
515
+ if e.code == 403:
516
+ raise AmazonError(
517
+ f"{_safe(url)} refused a {report_type} report (403). That is a ROLE answer: this "
518
+ "report needs a role the application was not granted") from None
519
+ raise AmazonError(f"{_safe(url)} answered {e.code}"
520
+ + (f": {detail}" if detail else "")) from None
521
+ except Exception as e: # noqa: BLE001
522
+ raise AmazonError(f"{_safe(url)} unreachable: {type(e).__name__}") from None
523
+ rid = str(got.get("reportId") or "")
524
+ if not rid:
525
+ raise AmazonError(f"Amazon accepted the {report_type} request but returned no reportId")
526
+ return rid
527
+
528
+ base = (SANDBOX_ENDPOINTS if sandbox else ENDPOINTS).get(
529
+ str(region or DEFAULT_REGION).lower(), "")
530
+ # ⭐ Pace once per new report. Retrying that same report pays only the shared backoff.
531
+ _report_pacer["waited"].set(_pace_report_create())
532
+ return _retry(attempt, f"{base}/{_REPORTS_CREATE_PATH}")
533
 
534
 
535
  #: Terminal processing states. `DONE` is the only one that yields a document.
 
555
  region = str((fields or {}).get("region") or DEFAULT_REGION)
556
  mkts = [str((fields or {}).get("marketplace_id") or US_MARKETPLACE_ID)]
557
  sbx = is_sandbox(fields)
558
+ pace_context = _report_pacer["waited"].set(0.0)
559
+ try:
560
+ rid = _create_report(token, report_type, mkts, region=region, start=start, end=end,
561
+ options=options, timeout=timeout, sandbox=sbx)
562
+ finally:
563
+ paced = _report_pacer["waited"].get()
564
+ _report_pacer["waited"].reset(pace_context)
565
+ if paced:
566
+ say(f" {report_type}: waited {paced:.2f}s to stagger report creation")
567
  say(f" {report_type}: reportId {rid}")
568
 
569
  waited, state, doc_id = 0, "", ""
platform/harness/measure_filter.py CHANGED
@@ -46,6 +46,7 @@ count that looks authoritative. `ModelError` is the only safe failure.
46
  """
47
  from harness import semantic as _sem
48
  from harness import windows as _win
 
49
 
50
  #: metric key -> how it reads in the condition builder. ONLY metrics with an independent
51
  #: validation contract (semantic.store_parity / a metric `validate:` block) appear here.
@@ -299,7 +300,29 @@ def _base_topic(key):
299
  return topic
300
 
301
 
302
- def _query_parts(key, window, today, team_id):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
303
  """The FROM / GROUP-BY id / aggregate / WHERE for one (measure, window), shared by the
304
  one-sided and the two-sided resolver so there is one definition of the scope."""
305
  topic = _base_topic(key)
@@ -325,6 +348,12 @@ def _query_parts(key, window, today, team_id):
325
  agg = f"COALESCE({_sem._measure_sql(m, s['alias'])}, 0)"
326
 
327
  where, params = [_sem.render_scope(s['scope_sql'].strip())], []
 
 
 
 
 
 
328
  if date_from:
329
  where.append(f"CAST({s['date_col']} AS TIMESTAMP) >= ?")
330
  params.append(f"{date_from} 00:00:00")
@@ -352,7 +381,7 @@ def _scaled(key, value):
352
  return (value / scale) if scale else value
353
 
354
 
355
- def resolve_stat(rule, today, team_id=None, allowed_pids=None):
356
  """`Where [Sales] [this year] [>] [the 75th percentile]` — the top quartile of the pool.
357
 
358
  One totals query for the measure, the statistic taken over the CALLER'S POOL (see the STATS
@@ -363,6 +392,7 @@ def resolve_stat(rule, today, team_id=None, allowed_pids=None):
363
  raise _sem.ModelError(f"{stat!r} is not a statistic. Offered: {sorted(STATS)}")
364
  key = rule.get('colId')
365
  topic_for(key)
 
366
  op = rule.get('op')
367
  if op not in PAIR_OPS:
368
  raise _sem.ModelError(
@@ -376,7 +406,7 @@ def resolve_stat(rule, today, team_id=None, allowed_pids=None):
376
  "which would be a different question with an authoritative-looking answer")
377
  con = _sem._store_con()
378
  try:
379
- totals = _totals(con, key, rule.get('window'), today, team_id)
380
  finally:
381
  con.close()
382
  # ⚠ THE POPULATION IS THE CUSTOMERS WHO HAVE THIS MEASURE AT ALL — owner's decision,
@@ -398,8 +428,8 @@ def resolve_stat(rule, today, team_id=None, allowed_pids=None):
398
  population = {pid: v for pid, v in totals.items() if pid in pool and v}
399
  cut = percentile(list(population.values()), stat)
400
  if cut is None: # nobody has this measure -> nobody qualifies
401
- return set()
402
- return {pid for pid, v in population.items() if _CMP[op](v, cut)}
403
 
404
 
405
  def _pool_of(allowed_pids):
@@ -445,7 +475,7 @@ def rule_complete(rule):
445
  return v is not None and str(v).strip() != ''
446
 
447
 
448
- def resolve_rule(rule, today, team_id=None, allowed_pids=None):
449
  """One measure condition -> the SET OF CUSTOMER IDS satisfying it.
450
 
451
  `rule` = {colId: <measure key>, window: <window spec>, op: <numeric op>, value: <str|num>},
@@ -467,11 +497,12 @@ def resolve_rule(rule, today, team_id=None, allowed_pids=None):
467
  'refusing to answer a question that has not been fully asked')
468
  rhs = rule.get('rhs')
469
  if isinstance(rhs, dict) and rhs.get('kind') == 'measure':
470
- return resolve_pair(rule, today, team_id, allowed_pids)
471
  if isinstance(rhs, dict) and rhs.get('kind') == 'stat':
472
- return resolve_stat(rule, today, team_id, allowed_pids)
473
  key = rule.get('colId')
474
  topic_for(key) # raises for anything not admitted
 
475
  op = rule.get('op')
476
  if op not in OPS:
477
  raise _sem.ModelError(f"{op!r} is not a numeric comparison ({sorted(OPS)})")
@@ -492,17 +523,18 @@ def resolve_rule(rule, today, team_id=None, allowed_pids=None):
492
  # compare in Python — the same shape `resolve_pair` uses, and for the same reason.
493
  con = _sem._store_con()
494
  try:
495
- totals = _totals(con, key, rule.get('window'), today, team_id)
496
  finally:
497
  con.close()
498
  # No pool means we can only speak about customers a base has seen. WITH a pool, everyone
499
  # else scores 0 through the ratio's guard — which is what makes the zero-group work for a
500
  # ratio exactly as it does for a sum ("AOV <= 250" includes those who bought nothing).
501
  universe = pool if pool is not None else set(totals)
502
- return {pid for pid in universe if _CMP[op](totals.get(pid, 0.0), value)}
 
503
 
504
  frm, id_col, agg, where_sql, params = _query_parts(
505
- key, rule.get('window'), today, team_id)
506
  sql = (f"SELECT {id_col} AS pid, {agg} AS v FROM {frm} WHERE {where_sql} "
507
  f"GROUP BY {id_col} HAVING {agg} {OPS[op]} ?")
508
 
@@ -524,10 +556,10 @@ def resolve_rule(rule, today, team_id=None, allowed_pids=None):
524
  con.close()
525
  if pool is not None:
526
  matched &= pool
527
- return matched
528
 
529
 
530
- def _totals(con, key, window, today, team_id):
531
  """`{pid: value}` for one (measure, window), COMPOSITES included.
532
 
533
  For a plain aggregate this is resolve_rule's query minus the HAVING. For a ratio or a derived
@@ -541,13 +573,13 @@ def _totals(con, key, window, today, team_id):
541
  """
542
  if is_composite(key):
543
  bases, _ = _sem._expand_measures([key])
544
- parts = {b: _totals(con, b, window, today, team_id) for b in bases}
545
  pids = set()
546
  for got in parts.values():
547
  pids |= set(got)
548
  return {pid: _sem._post_compute({b: parts[b].get(pid, 0.0) for b in bases}, key)
549
  for pid in pids}
550
- frm, id_col, agg, where_sql, params = _query_parts(key, window, today, team_id)
551
  sql = (f"SELECT {id_col} AS pid, {agg} AS v FROM {frm} WHERE {where_sql} GROUP BY {id_col}")
552
  # `float(r[1])`, not `float(r[1] or 0.0)`: `_query_parts` already wraps the aggregate in
553
  # COALESCE(..., 0), so a NULL cannot arrive here — a second guard would be unreachable, and
@@ -558,7 +590,7 @@ def _totals(con, key, window, today, team_id):
558
  for r in con.execute(sql, params).fetchall() if r[0] is not None}
559
 
560
 
561
- def resolve_pair(rule, today, team_id=None, allowed_pids=None):
562
  """CG-9 — `Where [Sales] [this year] [>] [Sales] [year to date, last year]`.
563
 
564
  TWO QUERIES, compared in Python. The obvious alternative — one query with two conditional
@@ -576,6 +608,7 @@ def resolve_pair(rule, today, team_id=None, allowed_pids=None):
576
  rhs = rule.get('rhs') or {}
577
  lkey, rkey = rule.get('colId'), rhs.get('colId')
578
  topic_for(lkey), topic_for(rkey) # raises for anything not admitted
 
579
  op = rule.get('op')
580
  if op not in PAIR_OPS:
581
  raise _sem.ModelError(
@@ -587,14 +620,15 @@ def resolve_pair(rule, today, team_id=None, allowed_pids=None):
587
  pool = _pool_of(allowed_pids)
588
  con = _sem._store_con()
589
  try:
590
- left = _totals(con, lkey, rule.get('window'), today, team_id)
591
- right = _totals(con, rkey, rhs.get('window'), today, team_id)
592
  finally:
593
  con.close()
594
  # With no pool we can only speak about customers at least one side has seen — the zero-vs-
595
  # zero group is unknowable without being told who exists. With a pool, it is every member.
596
  universe = pool if pool is not None else (set(left) | set(right))
597
- return {pid for pid in universe if cmp(left.get(pid, 0.0), right.get(pid, 0.0))}
 
598
 
599
 
600
  def _zero_satisfies(op, value):
@@ -602,7 +636,7 @@ def _zero_satisfies(op, value):
602
  return _CMP[op](0.0, value)
603
 
604
 
605
- def resolve_values(key, window, today, team_id=None, allowed_pids=None):
606
  """`{pid: display value}` for one (measure, window) over the caller's pool — the COLUMN
607
  version of `resolve_rule` (owner item 7, 2026-07-27: a formula-measure FIELD).
608
 
@@ -621,6 +655,10 @@ def resolve_values(key, window, today, team_id=None, allowed_pids=None):
621
 
622
  Raises for anything not admitted / an unresolvable window — the caller degrades that column
623
  to blank rather than to a number nobody computed.
 
 
 
 
624
  """
625
  topic_for(key) # raises for anything not admitted
626
  # The window must RESOLVE before any query runs — same refusal as `_query_parts`, checked
@@ -630,10 +668,11 @@ def resolve_values(key, window, today, team_id=None, allowed_pids=None):
630
  raise _sem.ModelError(
631
  f"unresolvable window {window!r} for the {key!r} column: refusing rather than "
632
  f"defaulting to all time")
 
633
  pool = _pool_of(allowed_pids)
634
  con = _sem._store_con()
635
  try:
636
- totals = _totals(con, key, window, today, team_id)
637
  finally:
638
  con.close()
639
  scale = ADMITTED.get(key, {}).get('input_scale') or 1.0
@@ -641,7 +680,9 @@ def resolve_values(key, window, today, team_id=None, allowed_pids=None):
641
  nd = 1 if mtype == 'pct' else None # money/counts whole, percents one decimal
642
  universe = pool if pool is not None else set(totals)
643
  # round(x, None) returns an int — exactly the pool's `_round` convention for money/counts.
644
- return {int(p): round(float(totals.get(p, 0.0)) * scale, nd) for p in universe}
 
 
645
 
646
 
647
  #: The series channel's calendar buckets. `date_trunc` names in DuckDB; 'week' truncates to
@@ -766,19 +807,23 @@ def resolve_series_slid(key, window_spec, buckets, today, team_id=None, allowed_
766
  return {'values': values, 'agg': agg_kind}
767
 
768
 
769
- def resolve_tree(rules, today, team_id=None, allowed_pids=None):
770
  """{rule_id: sorted pids} for every measure condition in a tree.
771
 
772
  Keyed by the rule's client-generated `id` so the browser can map an answer back to the
773
  condition that asked it — positional matching would silently re-associate every answer the
774
  moment a user deleted a condition.
775
  """
776
- out = {}
777
  for r in rules or []:
778
  rid = str(r.get('id') or '')
779
  if not rid:
780
  raise _sem.ModelError('a measure condition needs a stable id to carry its answer back')
781
- out[rid] = sorted(resolve_rule(r, today, team_id, allowed_pids))
 
 
 
 
782
  return out
783
 
784
 
 
46
  """
47
  from harness import semantic as _sem
48
  from harness import windows as _win
49
+ from core import relations as _relations
50
 
51
  #: metric key -> how it reads in the condition builder. ONLY metrics with an independent
52
  #: validation contract (semantic.store_parity / a metric `validate:` block) appear here.
 
300
  return topic
301
 
302
 
303
+ def _related_scope(related, keys):
304
+ """Prepare all bases before querying: a refused composite must be wholly unscoped."""
305
+ if related is None or isinstance(related, _relations.MeasurePin):
306
+ return related
307
+ try:
308
+ pin = _relations.measure_pin(related)
309
+ bases, _ = _sem._expand_measures(list(keys))
310
+ for key in bases:
311
+ _, _, store = _entity_sql(_base_topic(key))
312
+ pin.predicate(store)
313
+ return pin
314
+ except _relations.PinRefusal as exc:
315
+ return _relations.MeasurePin(exc.marker['path'], {}, {}, exc.marker)
316
+
317
+
318
+ def _related_answer(values, related):
319
+ if related is None:
320
+ return values
321
+ cls = _relations.MeasureMatches if isinstance(values, set) else _relations.MeasureAnswer
322
+ return cls(values, [related.refusal] if related.refusal else ())
323
+
324
+
325
+ def _query_parts(key, window, today, team_id, related=None):
326
  """The FROM / GROUP-BY id / aggregate / WHERE for one (measure, window), shared by the
327
  one-sided and the two-sided resolver so there is one definition of the scope."""
328
  topic = _base_topic(key)
 
348
  agg = f"COALESCE({_sem._measure_sql(m, s['alias'])}, 0)"
349
 
350
  where, params = [_sem.render_scope(s['scope_sql'].strip())], []
351
+ related = _related_scope(related, [key])
352
+ if related is not None:
353
+ pin_sql, pin_params = related.predicate(s)
354
+ if pin_sql is not None:
355
+ where.append(f'({pin_sql})')
356
+ params.extend(pin_params)
357
  if date_from:
358
  where.append(f"CAST({s['date_col']} AS TIMESTAMP) >= ?")
359
  params.append(f"{date_from} 00:00:00")
 
381
  return (value / scale) if scale else value
382
 
383
 
384
+ def resolve_stat(rule, today, team_id=None, allowed_pids=None, related=None):
385
  """`Where [Sales] [this year] [>] [the 75th percentile]` — the top quartile of the pool.
386
 
387
  One totals query for the measure, the statistic taken over the CALLER'S POOL (see the STATS
 
392
  raise _sem.ModelError(f"{stat!r} is not a statistic. Offered: {sorted(STATS)}")
393
  key = rule.get('colId')
394
  topic_for(key)
395
+ related = _related_scope(related, [key])
396
  op = rule.get('op')
397
  if op not in PAIR_OPS:
398
  raise _sem.ModelError(
 
406
  "which would be a different question with an authoritative-looking answer")
407
  con = _sem._store_con()
408
  try:
409
+ totals = _totals(con, key, rule.get('window'), today, team_id, related)
410
  finally:
411
  con.close()
412
  # ⚠ THE POPULATION IS THE CUSTOMERS WHO HAVE THIS MEASURE AT ALL — owner's decision,
 
428
  population = {pid: v for pid, v in totals.items() if pid in pool and v}
429
  cut = percentile(list(population.values()), stat)
430
  if cut is None: # nobody has this measure -> nobody qualifies
431
+ return _related_answer(set(), related)
432
+ return _related_answer({pid for pid, v in population.items() if _CMP[op](v, cut)}, related)
433
 
434
 
435
  def _pool_of(allowed_pids):
 
475
  return v is not None and str(v).strip() != ''
476
 
477
 
478
+ def resolve_rule(rule, today, team_id=None, allowed_pids=None, related=None):
479
  """One measure condition -> the SET OF CUSTOMER IDS satisfying it.
480
 
481
  `rule` = {colId: <measure key>, window: <window spec>, op: <numeric op>, value: <str|num>},
 
497
  'refusing to answer a question that has not been fully asked')
498
  rhs = rule.get('rhs')
499
  if isinstance(rhs, dict) and rhs.get('kind') == 'measure':
500
+ return resolve_pair(rule, today, team_id, allowed_pids, related)
501
  if isinstance(rhs, dict) and rhs.get('kind') == 'stat':
502
+ return resolve_stat(rule, today, team_id, allowed_pids, related)
503
  key = rule.get('colId')
504
  topic_for(key) # raises for anything not admitted
505
+ related = _related_scope(related, [key])
506
  op = rule.get('op')
507
  if op not in OPS:
508
  raise _sem.ModelError(f"{op!r} is not a numeric comparison ({sorted(OPS)})")
 
523
  # compare in Python — the same shape `resolve_pair` uses, and for the same reason.
524
  con = _sem._store_con()
525
  try:
526
+ totals = _totals(con, key, rule.get('window'), today, team_id, related)
527
  finally:
528
  con.close()
529
  # No pool means we can only speak about customers a base has seen. WITH a pool, everyone
530
  # else scores 0 through the ratio's guard — which is what makes the zero-group work for a
531
  # ratio exactly as it does for a sum ("AOV <= 250" includes those who bought nothing).
532
  universe = pool if pool is not None else set(totals)
533
+ return _related_answer(
534
+ {pid for pid in universe if _CMP[op](totals.get(pid, 0.0), value)}, related)
535
 
536
  frm, id_col, agg, where_sql, params = _query_parts(
537
+ key, rule.get('window'), today, team_id, related)
538
  sql = (f"SELECT {id_col} AS pid, {agg} AS v FROM {frm} WHERE {where_sql} "
539
  f"GROUP BY {id_col} HAVING {agg} {OPS[op]} ?")
540
 
 
556
  con.close()
557
  if pool is not None:
558
  matched &= pool
559
+ return _related_answer(matched, related)
560
 
561
 
562
+ def _totals(con, key, window, today, team_id, related=None):
563
  """`{pid: value}` for one (measure, window), COMPOSITES included.
564
 
565
  For a plain aggregate this is resolve_rule's query minus the HAVING. For a ratio or a derived
 
573
  """
574
  if is_composite(key):
575
  bases, _ = _sem._expand_measures([key])
576
+ parts = {b: _totals(con, b, window, today, team_id, related) for b in bases}
577
  pids = set()
578
  for got in parts.values():
579
  pids |= set(got)
580
  return {pid: _sem._post_compute({b: parts[b].get(pid, 0.0) for b in bases}, key)
581
  for pid in pids}
582
+ frm, id_col, agg, where_sql, params = _query_parts(key, window, today, team_id, related)
583
  sql = (f"SELECT {id_col} AS pid, {agg} AS v FROM {frm} WHERE {where_sql} GROUP BY {id_col}")
584
  # `float(r[1])`, not `float(r[1] or 0.0)`: `_query_parts` already wraps the aggregate in
585
  # COALESCE(..., 0), so a NULL cannot arrive here — a second guard would be unreachable, and
 
590
  for r in con.execute(sql, params).fetchall() if r[0] is not None}
591
 
592
 
593
+ def resolve_pair(rule, today, team_id=None, allowed_pids=None, related=None):
594
  """CG-9 — `Where [Sales] [this year] [>] [Sales] [year to date, last year]`.
595
 
596
  TWO QUERIES, compared in Python. The obvious alternative — one query with two conditional
 
608
  rhs = rule.get('rhs') or {}
609
  lkey, rkey = rule.get('colId'), rhs.get('colId')
610
  topic_for(lkey), topic_for(rkey) # raises for anything not admitted
611
+ related = _related_scope(related, [lkey, rkey])
612
  op = rule.get('op')
613
  if op not in PAIR_OPS:
614
  raise _sem.ModelError(
 
620
  pool = _pool_of(allowed_pids)
621
  con = _sem._store_con()
622
  try:
623
+ left = _totals(con, lkey, rule.get('window'), today, team_id, related)
624
+ right = _totals(con, rkey, rhs.get('window'), today, team_id, related)
625
  finally:
626
  con.close()
627
  # With no pool we can only speak about customers at least one side has seen — the zero-vs-
628
  # zero group is unknowable without being told who exists. With a pool, it is every member.
629
  universe = pool if pool is not None else (set(left) | set(right))
630
+ return _related_answer(
631
+ {pid for pid in universe if cmp(left.get(pid, 0.0), right.get(pid, 0.0))}, related)
632
 
633
 
634
  def _zero_satisfies(op, value):
 
636
  return _CMP[op](0.0, value)
637
 
638
 
639
+ def resolve_values(key, window, today, team_id=None, allowed_pids=None, related=None):
640
  """`{pid: display value}` for one (measure, window) over the caller's pool — the COLUMN
641
  version of `resolve_rule` (owner item 7, 2026-07-27: a formula-measure FIELD).
642
 
 
655
 
656
  Raises for anything not admitted / an unresolvable window — the caller degrades that column
657
  to blank rather than to a number nobody computed.
658
+
659
+ Related pins use the request's relations.measure_pin_context. A refused pin returns
660
+ unscoped numbers in a MeasureAnswer with named `refusals`; hosts must publish that channel.
661
+ A pin never replaces `allowed_pids`, including when its member set is empty.
662
  """
663
  topic_for(key) # raises for anything not admitted
664
  # The window must RESOLVE before any query runs — same refusal as `_query_parts`, checked
 
668
  raise _sem.ModelError(
669
  f"unresolvable window {window!r} for the {key!r} column: refusing rather than "
670
  f"defaulting to all time")
671
+ related = _related_scope(related, [key])
672
  pool = _pool_of(allowed_pids)
673
  con = _sem._store_con()
674
  try:
675
+ totals = _totals(con, key, window, today, team_id, related)
676
  finally:
677
  con.close()
678
  scale = ADMITTED.get(key, {}).get('input_scale') or 1.0
 
680
  nd = 1 if mtype == 'pct' else None # money/counts whole, percents one decimal
681
  universe = pool if pool is not None else set(totals)
682
  # round(x, None) returns an int — exactly the pool's `_round` convention for money/counts.
683
+ # The pin narrows SQL input only. Keep the caller's entire pool for zero reconstruction.
684
+ return _related_answer(
685
+ {int(p): round(float(totals.get(p, 0.0)) * scale, nd) for p in universe}, related)
686
 
687
 
688
  #: The series channel's calendar buckets. `date_trunc` names in DuckDB; 'week' truncates to
 
807
  return {'values': values, 'agg': agg_kind}
808
 
809
 
810
+ def resolve_tree(rules, today, team_id=None, allowed_pids=None, related=None):
811
  """{rule_id: sorted pids} for every measure condition in a tree.
812
 
813
  Keyed by the rule's client-generated `id` so the browser can map an answer back to the
814
  condition that asked it — positional matching would silently re-associate every answer the
815
  moment a user deleted a condition.
816
  """
817
+ out = _relations.MeasureAnswer() if related is not None else {}
818
  for r in rules or []:
819
  rid = str(r.get('id') or '')
820
  if not rid:
821
  raise _sem.ModelError('a measure condition needs a stable id to carry its answer back')
822
+ matched = resolve_rule(r, today, team_id, allowed_pids, related)
823
+ out[rid] = sorted(matched)
824
+ if related is not None:
825
+ out.refusals.extend(dict(marker, rule=rid)
826
+ for marker in getattr(matched, 'refusals', ()))
827
  return out
828
 
829
 
platform/model/topics/odoo_customers.yml CHANGED
@@ -144,6 +144,16 @@ fields:
144
  type: url
145
  kind: data
146
  means: "A Google Maps link to this customer's address."
 
 
 
 
 
 
 
 
 
 
147
  - key: customer_since
148
  label: "Customer since"
149
  type: date
@@ -174,11 +184,6 @@ fields:
174
  type: int
175
  kind: data
176
  means: "How many days late this customer is running against their own usual ordering rhythm."
177
- - key: est_missed
178
- label: "Est. missed $"
179
- type: currency
180
- kind: data
181
- means: "Estimated sales missed while quiet: missed orders (capped at 3) times average order value. An estimate, not money owed."
182
  - key: ar_open
183
  label: "AR current $"
184
  type: currency
 
144
  type: url
145
  kind: data
146
  means: "A Google Maps link to this customer's address."
147
+ - key: lat
148
+ label: "Latitude"
149
+ type: text
150
+ kind: data
151
+ means: "Latitude of this customer's address, from Odoo when it has one and otherwise from our geocode of the address."
152
+ - key: lon
153
+ label: "Longitude"
154
+ type: text
155
+ kind: data
156
+ means: "Longitude of this customer's address, from Odoo when it has one and otherwise from our geocode of the address."
157
  - key: customer_since
158
  label: "Customer since"
159
  type: date
 
184
  type: int
185
  kind: data
186
  means: "How many days late this customer is running against their own usual ordering rhythm."
 
 
 
 
 
187
  - key: ar_open
188
  label: "AR current $"
189
  type: currency
platform/modules/customer_data.py CHANGED
@@ -1,21 +1,16 @@
1
- """Customer List — build, filter and save customer lists (replaces My Day, owner IA 2026-07-23).
2
-
3
- The page is a customer-list WORKBENCH in two parts:
4
- 1. BUILDER — the whole scoped book, one row per customer with a consistent metric surface
5
- (YTD / LY revenue, at-risk $, cadence, overdue days, estimated missed $ …): filter, sort,
6
- SELECT customers and add them to a list.
7
- 2. LISTS — saved lists whose membership is a visible, editable FORMULA (a rule set over the
8
- metric columns) plus hand-picked members. 'Call list' and 'Win-back' ship as TEMPLATES —
9
- the exact formulas the old My Day queues used — and the user can change or reset them.
10
-
11
- Composes already-validated customers-module functions, so the page's counts derive FROM the
12
- lists it renders (rule 8b). ⚠ **This header used to end "no separate validate()" and W30-T33
13
- made that false** — see `validate()` below. The claim held only while every column composed an
14
- already-reconciled customers-module function; the ADDRESS family does not, so it needed its own
15
- tie. Persistence: HF store key 'customer_lists'
16
- ({username: {list_name: {rules, sort, members, note}}}); templates are virtual until edited.
17
-
18
- The user↔agent link (users.py 'agent' field) scopes the pool to that agent's book; users with
19
  no link (owner/CFO/admin) see the whole book.
20
  """
21
  import re
@@ -31,6 +26,7 @@ import modules.map as map_mod
31
  import modules.sales as S
32
 
33
  LIMIT = 500 # honest builder display cap — always shown with the full count, never silent
 
34
  KEY = 'customer_lists'
35
  TABLE_KEY = 'customer_table_workspace'
36
 
@@ -104,7 +100,6 @@ FIELDS = {
104
  'days_since': ('Days since last order', 'num'),
105
  'typical_gap_days': ('Typical gap (days)', 'num'),
106
  'overdue_days': ('Overdue vs cadence (days)', 'num'),
107
- 'est_missed': ('Est. missed $', 'num'),
108
  }
109
  NUM_OPS = ('>=', '<=', '>', '<', '=')
110
  TEXT_OPS = ('contains', '=')
@@ -289,14 +284,14 @@ def pool(agent_name=None, team_id=None):
289
  buyers and anyone with an order in the 24-month cadence window — so lapsed/win-back
290
  accounts are in the pool, not just YTD actives. Reuses the customers module's validated
291
  building blocks (_cust_rev / _cadence_bulk / _partner_attrs) so every metric matches the
292
- Customers page definitions; est_missed is the Call-list formula (min(cycles missed, 3) × AOV)."""
293
  return _pool_build(agent_name, team_id, limit=None)['rows']
294
 
295
 
296
  def pool_first(agent_name=None, team_id=None, limit=100):
297
  """Wave-7 W1 (C1 as amended): the cold-load FAST SLICE — the pool's first `limit` rows in
298
  its own default order + the true total, built from the CHEAP families only (revenue ×3,
299
- cadence, status, est_missed, partner attributes ≈ 12s measured). The AR / product-mix /
300
  salesperson / coords columns stay BLANK until the full build swaps in: `_mix_attrs` alone
301
  is a whole-book 20s read_group whose domain must never be pid-narrowed (502 — see its
302
  docstring), so "all columns on 100 rows" measured 44.6s vs 45.1s full — no win. A partial
@@ -603,7 +598,6 @@ def _pool_build(agent_name, team_id, limit, fast=False):
603
  gap = c.get('typical_gap_days')
604
  overdue = c.get('overdue_days')
605
  aov = c.get('aov', 0.0)
606
- est = (min(overdue / gap, 3.0) * aov) if (gap and overdue and overdue > 0) else 0.0
607
  status = ('New' if rev > 0 and ly <= 0 else
608
  'Lost' if ly > 0 and rev <= 0 else
609
  'Declining' if 0 < rev < ly else
@@ -671,7 +665,6 @@ def _pool_build(agent_name, team_id, limit, fast=False):
671
  'last_order': c.get('last_order', ''),
672
  'days_since': c.get('days_since'),
673
  'typical_gap_days': gap, 'overdue_days': overdue,
674
- 'est_missed': est,
675
  })
676
  for r in rows:
677
  r['odoo_status'] = 'Active'
@@ -760,7 +753,6 @@ def _reconcile_ledger(rows, total, agent_name, team_id):
760
  'revenue_ytd': 0.0, 'revenue_ly': 0.0, 'yoy_pct': None, 'at_risk': 0.0,
761
  'ltm_rev': 0.0, 'orders_24m': 0, 'aov': 0.0, 'last_order': '',
762
  'days_since': None, 'typical_gap_days': None, 'overdue_days': None,
763
- 'est_missed': 0.0,
764
  })
765
  if store.available():
766
  try:
@@ -770,86 +762,6 @@ def _reconcile_ledger(rows, total, agent_name, team_id):
770
  return rows + revived, total + len(revived)
771
 
772
 
773
- # ------------------------------------------------------------------ the rule engine
774
- # A list's formula = [{'field','op','value'}, ...] over FIELDS + a 'sort' key ('-x' = desc).
775
- # The two templates ARE the old My Day queue formulas, expressed as visible rules.
776
- #
777
- # 'note' is a SEED, not the source of truth (owner 2026-07-25). It is what a list reads
778
- # BEFORE anyone edits it; the moment a user saves a description the stored one wins, and
779
- # an empty stored description stays empty — the template must never resurrect. That
780
- # precedence lives in aios_grid.views_from_defs (a saved view replaces its template-derived
781
- # one wholesale) and is pinned by _qa_grid_view_note.py. Edit the prose here only to change
782
- # what a NEW user starts with.
783
- TEMPLATES = {
784
- 'Call list': {
785
- 'rules': [{'field': 'orders_24m', 'op': '>=', 'value': 3},
786
- {'field': 'overdue_days', 'op': '>', 'value': 0},
787
- {'field': 'days_since', 'op': '<=', 'value': 365}],
788
- 'sort': '-est_missed',
789
- 'note': 'Customers overdue against their OWN reorder cadence (3+ orders, a real gap '
790
- 'pattern, ordered within 365d), ranked by estimated missed revenue.'},
791
- 'Win-back': {
792
- 'rules': [{'field': 'revenue_ly', 'op': '>=', 'value': 2000},
793
- {'field': 'at_risk', 'op': '>', 'value': 0}],
794
- 'sort': '-at_risk',
795
- 'note': 'Bought materially last year (over $2,000), down or gone this year, ranked by '
796
- 'dollars at risk.'},
797
- }
798
-
799
-
800
- def _match(row, rule):
801
- """One rule against one row. None/missing numeric values fail every numeric comparison
802
- (a customer with no cadence is never 'overdue'); text ops are case-insensitive."""
803
- field, op, val = rule.get('field'), rule.get('op'), rule.get('value')
804
- if field not in FIELDS:
805
- return True # unknown field → rule is inert, not a crash
806
- v = row.get(field)
807
- if FIELDS[field][1] == 'text':
808
- s, q = str(v or '').lower(), str(val or '').lower()
809
- return q in s if op == 'contains' else s == q
810
- try:
811
- v, val = float(v), float(val)
812
- except (TypeError, ValueError):
813
- return False
814
- return {'>=': v >= val, '<=': v <= val, '>': v > val, '<': v < val,
815
- '=': v == val}.get(op, False)
816
-
817
-
818
- def apply_rules(rows, rules, sort=None):
819
- """Filter the pool through a formula (AND of all rules) and apply the list's sort."""
820
- out = [r for r in rows if all(_match(r, ru) for ru in (rules or []))]
821
- if sort:
822
- key = sort.lstrip('-')
823
- out.sort(key=lambda r: (r.get(key) is None,
824
- -(r.get(key) or 0) if sort.startswith('-') else (r.get(key) or 0))
825
- if FIELDS.get(key, ('', 'num'))[1] == 'num'
826
- else str(r.get(key) or '').lower(), reverse=False)
827
- return out
828
-
829
-
830
- # ------------------------------------------------------------------ persistence (HF store)
831
- def saved_lists(username):
832
- """{list_name: {'rules','sort','members','note'}} for one user ({} when none / store down)."""
833
- try:
834
- return (store.get(KEY) or {}).get(username, {}) or {}
835
- except Exception:
836
- return {}
837
-
838
-
839
- def save_list(username, name, definition):
840
- def _up(d):
841
- d.setdefault(username, {})[name] = definition
842
- return d
843
- store.update(KEY, _up)
844
-
845
-
846
- def delete_list(username, name):
847
- def _up(d):
848
- (d.get(username) or {}).pop(name, None)
849
- return d
850
- store.update(KEY, _up)
851
-
852
-
853
  # ------------------------------------------------------------------ Airtable-style table workspace
854
  # This is intentionally separate from `customer_lists`: a LIST owns membership/formula
855
  # semantics, while a VIEW owns presentation/query state (filters, multi-sort, grouping,
 
1
+ """Customer data: a scoped metric pool and saved table workspaces.
2
+
3
+ 1. POOL: one row per customer, composing sales, cadence, receivables and address data.
4
+ 2. VIEWS: ordinary saved table views hold filters, sorts, layout and selected members in
5
+ 'customer_table_workspace'. The old rule-formula list readers and shipped list templates
6
+ were retired in wave 57 under R13. The 'customer_lists' bucket is retained without reads
7
+ or writes here so existing tenant data is preserved.
8
+
9
+ The pool composes already-validated customers-module functions. Its own validate() also
10
+ reconciles the address family independently. The daily digest still uses queues(), which calls
11
+ the customers module's contact recommendations and at-risk calculations directly.
12
+
13
+ The user-to-agent link (users.py 'agent' field) scopes the pool to that agent's book; users with
 
 
 
 
 
14
  no link (owner/CFO/admin) see the whole book.
15
  """
16
  import re
 
26
  import modules.sales as S
27
 
28
  LIMIT = 500 # honest builder display cap — always shown with the full count, never silent
29
+ # Rule-formula readers retired in wave 57 under R13; keep the bucket so no tenant data is dropped.
30
  KEY = 'customer_lists'
31
  TABLE_KEY = 'customer_table_workspace'
32
 
 
100
  'days_since': ('Days since last order', 'num'),
101
  'typical_gap_days': ('Typical gap (days)', 'num'),
102
  'overdue_days': ('Overdue vs cadence (days)', 'num'),
 
103
  }
104
  NUM_OPS = ('>=', '<=', '>', '<', '=')
105
  TEXT_OPS = ('contains', '=')
 
284
  buyers and anyone with an order in the 24-month cadence window — so lapsed/win-back
285
  accounts are in the pool, not just YTD actives. Reuses the customers module's validated
286
  building blocks (_cust_rev / _cadence_bulk / _partner_attrs) so every metric matches the
287
+ Customers page definitions."""
288
  return _pool_build(agent_name, team_id, limit=None)['rows']
289
 
290
 
291
  def pool_first(agent_name=None, team_id=None, limit=100):
292
  """Wave-7 W1 (C1 as amended): the cold-load FAST SLICE — the pool's first `limit` rows in
293
  its own default order + the true total, built from the CHEAP families only (revenue ×3,
294
+ cadence, status, partner attributes ≈ 12s measured). The AR / product-mix /
295
  salesperson / coords columns stay BLANK until the full build swaps in: `_mix_attrs` alone
296
  is a whole-book 20s read_group whose domain must never be pid-narrowed (502 — see its
297
  docstring), so "all columns on 100 rows" measured 44.6s vs 45.1s full — no win. A partial
 
598
  gap = c.get('typical_gap_days')
599
  overdue = c.get('overdue_days')
600
  aov = c.get('aov', 0.0)
 
601
  status = ('New' if rev > 0 and ly <= 0 else
602
  'Lost' if ly > 0 and rev <= 0 else
603
  'Declining' if 0 < rev < ly else
 
665
  'last_order': c.get('last_order', ''),
666
  'days_since': c.get('days_since'),
667
  'typical_gap_days': gap, 'overdue_days': overdue,
 
668
  })
669
  for r in rows:
670
  r['odoo_status'] = 'Active'
 
753
  'revenue_ytd': 0.0, 'revenue_ly': 0.0, 'yoy_pct': None, 'at_risk': 0.0,
754
  'ltm_rev': 0.0, 'orders_24m': 0, 'aov': 0.0, 'last_order': '',
755
  'days_since': None, 'typical_gap_days': None, 'overdue_days': None,
 
756
  })
757
  if store.available():
758
  try:
 
762
  return rows + revived, total + len(revived)
763
 
764
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
765
  # ------------------------------------------------------------------ Airtable-style table workspace
766
  # This is intentionally separate from `customer_lists`: a LIST owns membership/formula
767
  # semantics, while a VIEW owns presentation/query state (filters, multi-sort, grouping,
platform/modules/customers.py CHANGED
@@ -527,7 +527,7 @@ def _cadence_bulk(t=None, team_id=None, months=24, agent_pids=None):
527
 
528
  def contact_recommendations(t=None, team_id=None, limit=40, months=24, agent_pids=None):
529
  """Prioritised follow-up list: customers overdue against their OWN purchase cadence, ranked by
530
- estimated missed revenue (how far past due × their average order value). Reps' call list."""
531
  t = t or P.today()
532
  cad = _cadence_bulk(t, team_id, months, agent_pids=agent_pids)
533
  attrs = _partner_attrs(list(cad))
@@ -546,17 +546,13 @@ def contact_recommendations(t=None, team_id=None, limit=40, months=24, agent_pid
546
  if c['days_since'] > 365:
547
  continue # long-dead → not a cadence follow-up
548
  ltm_rev = rev_map.get(pid, {}).get('rev', 0.0)
549
- cycles_missed = overdue / gap # how many reorder cycles past due
550
- # cap at 3 cycles so a long-churned account (belongs in win-back) doesn't dominate the
551
- # "call them now" list; this rewards valuable regulars who are RECENTLY due.
552
- est_missed = min(cycles_missed, 3.0) * c['aov']
553
  rows.append({
554
  'pid': pid, 'customer': rev_map.get(pid, {}).get('name', '?'),
555
  'last_order': c['last_order'], 'typical_gap_days': gap, 'overdue_days': overdue,
556
- 'ltm_rev': ltm_rev, 'orders': c['n_orders'], 'est_missed': est_missed,
557
  'agent': (attrs.get(pid) or {}).get('agent', '(none)'),
558
  })
559
- rows.sort(key=lambda x: -x['est_missed'])
560
  return rows[:limit]
561
 
562
 
 
527
 
528
  def contact_recommendations(t=None, team_id=None, limit=40, months=24, agent_pids=None):
529
  """Prioritised follow-up list: customers overdue against their OWN purchase cadence, ranked by
530
+ how far past their own reorder cadence they are. Reps' call list."""
531
  t = t or P.today()
532
  cad = _cadence_bulk(t, team_id, months, agent_pids=agent_pids)
533
  attrs = _partner_attrs(list(cad))
 
546
  if c['days_since'] > 365:
547
  continue # long-dead → not a cadence follow-up
548
  ltm_rev = rev_map.get(pid, {}).get('rev', 0.0)
 
 
 
 
549
  rows.append({
550
  'pid': pid, 'customer': rev_map.get(pid, {}).get('name', '?'),
551
  'last_order': c['last_order'], 'typical_gap_days': gap, 'overdue_days': overdue,
552
+ 'ltm_rev': ltm_rev, 'orders': c['n_orders'],
553
  'agent': (attrs.get(pid) or {}).get('agent', '(none)'),
554
  })
555
+ rows.sort(key=lambda x: -(x['overdue_days'] or 0))
556
  return rows[:limit]
557
 
558
 
platform/modules/digest.py CHANGED
@@ -106,8 +106,7 @@ def build(user, t=None):
106
  rows.append(_sec('Call today — overdue vs their own cadence'))
107
  for r in calls:
108
  href = links.deeplink('customer_data', 'customer', r['pid'], src='digest')
109
- meta = (f"{int(r.get('overdue_days') or 0)}d past cycle · "
110
- f"est. missed {_m(r.get('est_missed'))}")
111
  rows.append(_line(r.get('customer', '?'), href, meta))
112
  if risk:
113
  rows.append(_sec('Win-back — down vs last year'))
 
106
  rows.append(_sec('Call today — overdue vs their own cadence'))
107
  for r in calls:
108
  href = links.deeplink('customer_data', 'customer', r['pid'], src='digest')
109
+ meta = f"{int(r.get('overdue_days') or 0)}d past cycle"
 
110
  rows.append(_line(r.get('customer', '?'), href, meta))
111
  if risk:
112
  rows.append(_sec('Win-back — down vs last year'))
platform/modules/outreach.py CHANGED
@@ -193,7 +193,7 @@ def build_audience(source, team_id=None, agent=None, limit=500):
193
  if source == 'reorder':
194
  rows = cust.contact_recommendations(team_id=team_id, limit=limit, agent_pids=pids_scope)
195
  return [{'pid': r['pid'], 'customer': r['customer'], 'agent': r.get('agent', ''),
196
- 'metric': r.get('est_missed', 0.0), 'metric_label': 'est. missed $'}
197
  for r in rows]
198
  if source == 'winback':
199
  rows = cust.at_risk(team_id=team_id, limit=limit, agent_pids=pids_scope)
 
193
  if source == 'reorder':
194
  rows = cust.contact_recommendations(team_id=team_id, limit=limit, agent_pids=pids_scope)
195
  return [{'pid': r['pid'], 'customer': r['customer'], 'agent': r.get('agent', ''),
196
+ 'metric': r.get('overdue_days', 0), 'metric_label': 'days past cadence'}
197
  for r in rows]
198
  if source == 'winback':
199
  rows = cust.at_risk(team_id=team_id, limit=limit, agent_pids=pids_scope)
web/public/sample_customers.json CHANGED
@@ -116,6 +116,22 @@
116
  "default": true,
117
  "description": "A Google Maps link to this customer's address."
118
  },
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
119
  {
120
  "key": "customer_since",
121
  "label": "Customer since",
@@ -164,17 +180,6 @@
164
  "default": true,
165
  "description": "How many days late this customer is running against their own usual ordering rhythm."
166
  },
167
- {
168
- "_note": "filterable:false — DERIVED ANALYTIC: est_missed is min(cycles missed, 3) x AOV, a score we compute rather than an object the business has, so a condition on it would read as a fact about the customer when it is a fact about our arithmetic. It still displays and still sorts. Until wave 6 this flag also covered the frozen-window presets (revenue_ytd / revenue_ly / orders_24m / aov / yoy_pct); those are now DELETED outright under the owner's no-buildable-presets rule — see _comment. est_missed itself STAYS: no creatable measure or formula reproduces the cadence model behind it.",
169
- "key": "est_missed",
170
- "label": "Est. missed $",
171
- "type": "currency",
172
- "source": "odoo",
173
- "default": true,
174
- "agg": "sum",
175
- "filterable": false,
176
- "description": "Estimated sales missed while quiet: missed orders (capped at 3) times average order value. An estimate, not money owed."
177
- },
178
  {
179
  "_note": "wave 21 R1 — KEY UNCHANGED, LABEL RENAMED. The computation is a DISJOINT split (ar.py credit_exposure): this column is only the not-yet-due residual, its sibling is the past-grace residual, and the two sum to the total. Under the label 'AR open $' the majority-late book read as 'Overdue > Open', which is nonsense in AR vocabulary — 'open' universally means the total. The label now says what the number is; the key stays so saved views and filters keep working.",
180
  "key": "ar_open",
@@ -323,7 +328,6 @@
323
  "city": "Charlottesville",
324
  "state": "Virginia (US)",
325
  "last_order": "2026-07-21",
326
- "est_missed": 0,
327
  "notes": "",
328
  "country": "United States",
329
  "zip": "02720",
@@ -341,8 +345,8 @@
341
  "top_sku": "AQUAFOAM FLORAL FOAM BRICK | 48-Piece per Pack",
342
  "days_to_pay": 34,
343
  "_created": "2023-01-15 09:10:00",
344
- "lat": 25.7617,
345
- "lon": -80.1918,
346
  "odoo_status": "Archived",
347
  "dba": "Royal",
348
  "ar_outstanding": 0
@@ -355,7 +359,6 @@
355
  "city": "Portland",
356
  "state": "Oregon (US)",
357
  "last_order": "2026-07-19",
358
- "est_missed": 0,
359
  "notes": "Expanding to a second storefront.",
360
  "country": "United States",
361
  "zip": "77041",
@@ -373,8 +376,8 @@
373
  "top_sku": "2\" X 24\" X 36\" GREEN STYROFOAM BOARD",
374
  "days_to_pay": null,
375
  "_created": "2023-02-15 09:11:00",
376
- "lat": 27.9506,
377
- "lon": -82.4572,
378
  "odoo_status": "Active",
379
  "dba": "Fisch",
380
  "ar_outstanding": 1240.5
@@ -387,7 +390,6 @@
387
  "city": "Kansas City",
388
  "state": "Missouri (US)",
389
  "last_order": "2026-07-17",
390
- "est_missed": 0,
391
  "notes": "",
392
  "country": "United States",
393
  "zip": "11219",
@@ -405,8 +407,8 @@
405
  "top_sku": "SATIN RIBBON 2IN",
406
  "days_to_pay": 61,
407
  "_created": "2023-03-15 09:12:00",
408
- "lat": 28.5384,
409
- "lon": -81.3789,
410
  "odoo_status": "Active",
411
  "dba": "Both",
412
  "ar_outstanding": 5120.25
@@ -419,7 +421,6 @@
419
  "city": "Savannah",
420
  "state": "Georgia (US)",
421
  "last_order": "2026-05-30",
422
- "est_missed": 41200,
423
  "notes": "Switched some volume to a local grower.",
424
  "country": "United States",
425
  "zip": "07649",
@@ -437,8 +438,8 @@
437
  "top_sku": "(none)",
438
  "days_to_pay": 12,
439
  "_created": "2023-04-15 09:13:00",
440
- "lat": 30.3322,
441
- "lon": -81.6557,
442
  "odoo_status": "Active",
443
  "dba": "Royal",
444
  "ar_outstanding": 9240
@@ -451,7 +452,6 @@
451
  "city": "Seattle",
452
  "state": "Washington (US)",
453
  "last_order": "2026-07-22",
454
- "est_missed": 0,
455
  "notes": "Top-10 account.",
456
  "country": "United States",
457
  "zip": "33125",
@@ -469,8 +469,8 @@
469
  "top_sku": "AQUAFOAM FLORAL FOAM BRICK | 48-Piece per Pack",
470
  "days_to_pay": 34,
471
  "_created": "2023-05-15 09:14:00",
472
- "lat": 26.1224,
473
- "lon": -80.1373,
474
  "odoo_status": "Active",
475
  "dba": "",
476
  "ar_outstanding": 0
@@ -483,7 +483,6 @@
483
  "city": "Asheville",
484
  "state": "North Carolina (US)",
485
  "last_order": "2026-02-11",
486
- "est_missed": 52400,
487
  "notes": "No spring order this year.",
488
  "country": "United States",
489
  "zip": "90210",
@@ -501,8 +500,8 @@
501
  "top_sku": "2\" X 24\" X 36\" GREEN STYROFOAM BOARD",
502
  "days_to_pay": null,
503
  "_created": "2023-06-15 09:15:00",
504
- "lat": 27.3364,
505
- "lon": -82.5307,
506
  "odoo_status": "Active",
507
  "dba": "Fisch",
508
  "ar_outstanding": 1240.5
@@ -515,7 +514,6 @@
515
  "city": "Austin",
516
  "state": "Texas (US)",
517
  "last_order": "2025-11-04",
518
- "est_missed": 78300,
519
  "notes": "Went with a competitor on freight terms.",
520
  "country": "United States",
521
  "zip": "08701",
@@ -533,8 +531,8 @@
533
  "top_sku": "SATIN RIBBON 2IN",
534
  "days_to_pay": 61,
535
  "_created": "2023-07-15 09:16:00",
536
- "lat": null,
537
- "lon": null,
538
  "odoo_status": "Active",
539
  "dba": "Both",
540
  "ar_outstanding": 5120.25
@@ -547,7 +545,6 @@
547
  "city": "Denver",
548
  "state": "Colorado (US)",
549
  "last_order": "2026-07-14",
550
- "est_missed": 0,
551
  "notes": "First order in April.",
552
  "country": "United States",
553
  "zip": "60614",
@@ -565,8 +562,8 @@
565
  "top_sku": "(none)",
566
  "days_to_pay": 12,
567
  "_created": "2023-08-15 09:17:00",
568
- "lat": 33.749,
569
- "lon": -84.388,
570
  "odoo_status": "Active",
571
  "dba": "Royal",
572
  "ar_outstanding": 9240
 
116
  "default": true,
117
  "description": "A Google Maps link to this customer's address."
118
  },
119
+ {
120
+ "key": "lat",
121
+ "label": "Latitude",
122
+ "type": "text",
123
+ "source": "odoo",
124
+ "default": false,
125
+ "description": "Latitude of this customer's address, from Odoo when it has one and otherwise from our geocode of the address."
126
+ },
127
+ {
128
+ "key": "lon",
129
+ "label": "Longitude",
130
+ "type": "text",
131
+ "source": "odoo",
132
+ "default": false,
133
+ "description": "Longitude of this customer's address, from Odoo when it has one and otherwise from our geocode of the address."
134
+ },
135
  {
136
  "key": "customer_since",
137
  "label": "Customer since",
 
180
  "default": true,
181
  "description": "How many days late this customer is running against their own usual ordering rhythm."
182
  },
 
 
 
 
 
 
 
 
 
 
 
183
  {
184
  "_note": "wave 21 R1 — KEY UNCHANGED, LABEL RENAMED. The computation is a DISJOINT split (ar.py credit_exposure): this column is only the not-yet-due residual, its sibling is the past-grace residual, and the two sum to the total. Under the label 'AR open $' the majority-late book read as 'Overdue > Open', which is nonsense in AR vocabulary — 'open' universally means the total. The label now says what the number is; the key stays so saved views and filters keep working.",
185
  "key": "ar_open",
 
328
  "city": "Charlottesville",
329
  "state": "Virginia (US)",
330
  "last_order": "2026-07-21",
 
331
  "notes": "",
332
  "country": "United States",
333
  "zip": "02720",
 
345
  "top_sku": "AQUAFOAM FLORAL FOAM BRICK | 48-Piece per Pack",
346
  "days_to_pay": 34,
347
  "_created": "2023-01-15 09:10:00",
348
+ "lat": 38.029306,
349
+ "lon": -78.476678,
350
  "odoo_status": "Archived",
351
  "dba": "Royal",
352
  "ar_outstanding": 0
 
359
  "city": "Portland",
360
  "state": "Oregon (US)",
361
  "last_order": "2026-07-19",
 
362
  "notes": "Expanding to a second storefront.",
363
  "country": "United States",
364
  "zip": "77041",
 
376
  "top_sku": "2\" X 24\" X 36\" GREEN STYROFOAM BOARD",
377
  "days_to_pay": null,
378
  "_created": "2023-02-15 09:11:00",
379
+ "lat": 45.515232,
380
+ "lon": -122.678385,
381
  "odoo_status": "Active",
382
  "dba": "Fisch",
383
  "ar_outstanding": 1240.5
 
390
  "city": "Kansas City",
391
  "state": "Missouri (US)",
392
  "last_order": "2026-07-17",
 
393
  "notes": "",
394
  "country": "United States",
395
  "zip": "11219",
 
407
  "top_sku": "SATIN RIBBON 2IN",
408
  "days_to_pay": 61,
409
  "_created": "2023-03-15 09:12:00",
410
+ "lat": 39.099727,
411
+ "lon": -94.578567,
412
  "odoo_status": "Active",
413
  "dba": "Both",
414
  "ar_outstanding": 5120.25
 
421
  "city": "Savannah",
422
  "state": "Georgia (US)",
423
  "last_order": "2026-05-30",
 
424
  "notes": "Switched some volume to a local grower.",
425
  "country": "United States",
426
  "zip": "07649",
 
438
  "top_sku": "(none)",
439
  "days_to_pay": 12,
440
  "_created": "2023-04-15 09:13:00",
441
+ "lat": 32.083541,
442
+ "lon": -81.099834,
443
  "odoo_status": "Active",
444
  "dba": "Royal",
445
  "ar_outstanding": 9240
 
452
  "city": "Seattle",
453
  "state": "Washington (US)",
454
  "last_order": "2026-07-22",
 
455
  "notes": "Top-10 account.",
456
  "country": "United States",
457
  "zip": "33125",
 
469
  "top_sku": "AQUAFOAM FLORAL FOAM BRICK | 48-Piece per Pack",
470
  "days_to_pay": 34,
471
  "_created": "2023-05-15 09:14:00",
472
+ "lat": 47.606209,
473
+ "lon": -122.332071,
474
  "odoo_status": "Active",
475
  "dba": "",
476
  "ar_outstanding": 0
 
483
  "city": "Asheville",
484
  "state": "North Carolina (US)",
485
  "last_order": "2026-02-11",
 
486
  "notes": "No spring order this year.",
487
  "country": "United States",
488
  "zip": "90210",
 
500
  "top_sku": "2\" X 24\" X 36\" GREEN STYROFOAM BOARD",
501
  "days_to_pay": null,
502
  "_created": "2023-06-15 09:15:00",
503
+ "lat": 35.595058,
504
+ "lon": -82.551487,
505
  "odoo_status": "Active",
506
  "dba": "Fisch",
507
  "ar_outstanding": 1240.5
 
514
  "city": "Austin",
515
  "state": "Texas (US)",
516
  "last_order": "2025-11-04",
 
517
  "notes": "Went with a competitor on freight terms.",
518
  "country": "United States",
519
  "zip": "08701",
 
531
  "top_sku": "SATIN RIBBON 2IN",
532
  "days_to_pay": 61,
533
  "_created": "2023-07-15 09:16:00",
534
+ "lat": 30.267153,
535
+ "lon": -97.743061,
536
  "odoo_status": "Active",
537
  "dba": "Both",
538
  "ar_outstanding": 5120.25
 
545
  "city": "Denver",
546
  "state": "Colorado (US)",
547
  "last_order": "2026-07-14",
 
548
  "notes": "First order in April.",
549
  "country": "United States",
550
  "zip": "60614",
 
562
  "top_sku": "(none)",
563
  "days_to_pay": 12,
564
  "_created": "2023-08-15 09:17:00",
565
+ "lat": 39.739236,
566
+ "lon": -104.990251,
567
  "odoo_status": "Active",
568
  "dba": "Royal",
569
  "ar_outstanding": 9240
web/src/automation/AutomationSurface.tsx CHANGED
@@ -41,6 +41,7 @@ import {
41
  import type { VoiceAgent } from "./voiceAgentTypes";
42
  import "../styles/wave44/voice-agent.css";
43
  import "../styles/wave45/agent-operator.css";
 
44
 
45
  /**
46
  * ⭐⭐ WAVE 30 · T21 (owner items 4 + 5) — THE EDITOR STOPS SHIPPING INSIDE THE LIST.
@@ -248,6 +249,7 @@ export default function AutomationSurface() {
248
  const [activeId, setActiveId] = useState<string>("");
249
  const [activeVoiceId, setActiveVoiceId] = useState<string>("");
250
  const [railShut, setRailShut] = useState(false);
 
251
  const [busy, setBusy] = useState("");
252
  /**
253
  * ⭐ WAVE 24 / C-CREATE — a create is now a ROUND TRIP, not a local wizard, so the door has to
@@ -542,6 +544,9 @@ export default function AutomationSurface() {
542
  */
543
  const fieldAgents = items.filter((agent) => agent.system === "field_agent");
544
  const active = items.find((a) => a.id === activeId) || null;
 
 
 
545
  const activeVoice = voiceAgents.find((agent) => agent.automationId === activeVoiceId) || null;
546
 
547
  /**
@@ -641,38 +646,65 @@ export default function AutomationSurface() {
641
  </button>
642
  </div>
643
 
644
- <div className="auto-create">
645
  <button
646
  type="button"
647
- className="auto-create-btn"
648
  disabled={creatingNow}
649
  onClick={() => void createAndOpen()}
650
  >
651
- <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
652
- <path
653
- d="M8 3.4v9.2M3.4 8h9.2"
654
- stroke="currentColor"
655
- strokeWidth="1.5"
656
- strokeLinecap="round"
657
- />
658
- </svg>
659
- New agent
660
  </button>
661
  <button
662
  type="button"
663
- className="auto-create-btn"
664
  onClick={() => {
665
  setActiveId("");
666
  setActiveVoiceId("");
667
  setSlackOpen(true);
668
  }}
669
  >
670
- Channel agents
 
671
  </button>
672
  </div>
673
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
674
  <div className="auto-list" ref={listRef} onKeyDown={onRailKey}>
 
 
 
675
  {items.map((a) => {
 
676
  return (
677
  <div
678
  key={a.id}
@@ -714,6 +746,7 @@ export default function AutomationSurface() {
714
  );
715
  })}
716
  {voiceAgents.map((agent) => {
 
717
  const isActive = agent.lifecycle === "active";
718
  return (
719
  <div
 
41
  import type { VoiceAgent } from "./voiceAgentTypes";
42
  import "../styles/wave44/voice-agent.css";
43
  import "../styles/wave45/agent-operator.css";
44
+ import "../styles/wave57/agents-rail.css";
45
 
46
  /**
47
  * ⭐⭐ WAVE 30 · T21 (owner items 4 + 5) — THE EDITOR STOPS SHIPPING INSIDE THE LIST.
 
249
  const [activeId, setActiveId] = useState<string>("");
250
  const [activeVoiceId, setActiveVoiceId] = useState<string>("");
251
  const [railShut, setRailShut] = useState(false);
252
+ const [railQuery, setRailQuery] = useState("");
253
  const [busy, setBusy] = useState("");
254
  /**
255
  * ⭐ WAVE 24 / C-CREATE — a create is now a ROUND TRIP, not a local wizard, so the door has to
 
544
  */
545
  const fieldAgents = items.filter((agent) => agent.system === "field_agent");
546
  const active = items.find((a) => a.id === activeId) || null;
547
+ const railNeedle = railQuery.trim().toLowerCase();
548
+ const railMatches = (label: string) =>
549
+ !railNeedle || label.toLowerCase().includes(railNeedle);
550
  const activeVoice = voiceAgents.find((agent) => agent.automationId === activeVoiceId) || null;
551
 
552
  /**
 
646
  </button>
647
  </div>
648
 
649
+ <div className="cg-create-new">
650
  <button
651
  type="button"
652
+ className="cg-link-btn cg-create-btn"
653
  disabled={creatingNow}
654
  onClick={() => void createAndOpen()}
655
  >
656
+ <span className="cg-create-icon" aria-hidden="true">+</span>
657
+ <span className="cg-create-label">Create new…</span>
 
 
 
 
 
 
 
658
  </button>
659
  <button
660
  type="button"
661
+ className="cg-link-btn cg-create-btn"
662
  onClick={() => {
663
  setActiveId("");
664
  setActiveVoiceId("");
665
  setSlackOpen(true);
666
  }}
667
  >
668
+ <span className="cg-create-icon" aria-hidden="true">#</span>
669
+ <span className="cg-create-label">Channel agents</span>
670
  </button>
671
  </div>
672
 
673
+ <div className="cg-find-view">
674
+ <svg
675
+ className="cg-find-view-icon"
676
+ width="14"
677
+ height="14"
678
+ viewBox="0 0 16 16"
679
+ fill="none"
680
+ aria-hidden="true"
681
+ >
682
+ <circle cx="7" cy="7" r="4.4" stroke="currentColor" strokeWidth="1.35" />
683
+ <path
684
+ d="m10.4 10.4 3.1 3.1"
685
+ stroke="currentColor"
686
+ strokeWidth="1.35"
687
+ strokeLinecap="round"
688
+ />
689
+ </svg>
690
+ <input
691
+ type="text"
692
+ value={railQuery}
693
+ placeholder="Find…"
694
+ aria-label="Find an agent"
695
+ onChange={(event) => setRailQuery(event.target.value)}
696
+ onKeyDown={(event) => {
697
+ if (event.key === "Escape") setRailQuery("");
698
+ }}
699
+ />
700
+ </div>
701
+
702
  <div className="auto-list" ref={listRef} onKeyDown={onRailKey}>
703
+ {/* Keep both find guards inside the callbacks: verify_automation_ui.py's W44
704
+ check reads the literal voiceAgents.map. Chaining a filter ahead of it
705
+ takes a green gate red even though it renders the same rows. */}
706
  {items.map((a) => {
707
+ if (!railMatches(a.name)) return null;
708
  return (
709
  <div
710
  key={a.id}
 
746
  );
747
  })}
748
  {voiceAgents.map((agent) => {
749
+ if (!railMatches(agent.displayName)) return null;
750
  const isActive = agent.lifecycle === "active";
751
  return (
752
  <div
web/src/connectors/DatabasesTab.tsx CHANGED
@@ -58,6 +58,7 @@
58
 
59
  import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useState } from "react";
60
  import { API_V1, CREDENTIALS, WORKSPACE_STALE_EVENT, signal } from "../apiContract";
 
61
  import type { ConnectorDatabase, ConnectorDetail } from "./ConnectorModal";
62
  import type { ConnectorRow } from "./ConnectorsPage";
63
 
@@ -171,6 +172,27 @@ async function enableDatabase(tableKey: string): Promise<EnableDatabaseAnswer> {
171
  }
172
  }
173
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
174
  function sentenceList(values: string[]): string {
175
  if (values.length < 2) return values[0] || "";
176
  if (values.length === 2) return `${values[0]} and ${values[1]}`;
@@ -473,8 +495,9 @@ function DatabasePanel({
473
  * remounted, and so this whole tab still paints under `renderToStaticMarkup`.
474
  *
475
  * ⛔ NO CONTROL AT ALL FOR A READER WHO MAY NOT RENAME (`canRename` is the server's own `may_open`
476
- * answer). When `exists` is false, that is a different fact: the table is still waiting for a
477
- * sync, so the cell says why the control is absent instead of presenting a permission refusal.
 
478
  */
479
  function NameCell({
480
  database,
@@ -516,8 +539,6 @@ function NameCell({
516
  >
517
  {database.override ? "Change" : "Rename"}
518
  </button>
519
- ) : database.enabled && !database.exists ? (
520
- <span className="conn-db-state">Available after the first sync.</span>
521
  ) : null}
522
  </div>
523
  );
@@ -589,6 +610,7 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
589
  }, ref) {
590
  const { databases, introspection } = detail;
591
  const showsPopulation = row.key === "odoo";
 
592
  /**
593
  * ⚠ W53-T27 — EVERY ROW STARTS CLOSED, and that changed here. Until this ticket the first
594
  * database was opened for you, because the field list WAS the content of this tab. The content
@@ -599,6 +621,7 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
599
  () => reveal?.key ? { [reveal.key]: true } : {}
600
  );
601
  const [busy, setBusy] = useState("");
 
602
  const [refusals, setRefusals] = useState<Record<string, string>>({});
603
  const [autoEnableResults, setAutoEnableResults] = useState<Record<string, string>>(
604
  () => reveal?.key && reveal.status ? { [reveal.key]: reveal.status } : {}
@@ -646,11 +669,22 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
646
  [databases, pending.tables]
647
  );
648
 
 
 
 
 
 
 
 
 
 
 
 
 
649
  /**
650
- * ⛔⛔ R23's OFF ENFORCEMENT, AND TODAY IT LIVES HERE. Turning a database off keeps using
651
- * `PUT /admin/connectors/odoo/config`, which knows nothing about dependents, so the ASK has to
652
- * happen before the change enters the pending diff. Turning one on is queued for the
653
- * materialising door; mixing the two would bypass the only dependents check on the off path.
654
  *
655
  * ⛔ AND A FAILED CHECK IS NOT A PASSED ONE. Any non-answer leaves the table on and prints the
656
  * cause; proceeding would turn "REFUSED" into "usually refused".
@@ -678,16 +712,16 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
678
  setRefusals((current) => ({ ...current, [database.key]: answer.refusal }));
679
  return;
680
  }
 
 
 
 
 
681
  }
682
  setBusy("");
683
- setPending((current) => {
684
- const tables = { ...current.tables };
685
- if (next === database.enabled) delete tables[database.key];
686
- else tables[database.key] = next;
687
- return { ...current, tables };
688
- });
689
  },
690
- []
691
  );
692
 
693
  const flipField = useCallback(
@@ -776,10 +810,9 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
776
  if (answer.workspaceChanged) signal(WORKSPACE_STALE_EVENT);
777
  continue;
778
  }
779
- const message = await write("/admin/connectors/odoo/config", "PUT", {
780
- grids: { [databaseKey]: false },
781
- });
782
- if (message) {
783
  failed.tables[databaseKey] = next;
784
  failures.push(`${label}: ${message}`);
785
  }
@@ -1085,6 +1118,26 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
1085
  );
1086
  })}
1087
  </table>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1088
  </div>
1089
  );
1090
  });
 
58
 
59
  import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useState } from "react";
60
  import { API_V1, CREDENTIALS, WORKSPACE_STALE_EVENT, signal } from "../apiContract";
61
+ import { ConfirmDialog } from "../ui/ConfirmDialog";
62
  import type { ConnectorDatabase, ConnectorDetail } from "./ConnectorModal";
63
  import type { ConnectorRow } from "./ConnectorsPage";
64
 
 
172
  }
173
  }
174
 
175
+ async function disableDatabase(
176
+ tableKey: string
177
+ ): Promise<{ ok: true } | { ok: false; message: string }> {
178
+ try {
179
+ const res = await fetch(
180
+ `${API_V1}/connectors/odoo/databases/${encodeURIComponent(tableKey)}/disable`,
181
+ { method: "POST", credentials: CREDENTIALS }
182
+ );
183
+ const payload = (await res.json().catch(() => null)) as
184
+ | { error?: { message?: string } }
185
+ | null;
186
+ if (res.ok) return { ok: true };
187
+ return {
188
+ ok: false,
189
+ message: payload?.error?.message || `The server answered ${res.status}.`,
190
+ };
191
+ } catch {
192
+ return { ok: false, message: "Cannot reach the server." };
193
+ }
194
+ }
195
+
196
  function sentenceList(values: string[]): string {
197
  if (values.length < 2) return values[0] || "";
198
  if (values.length === 2) return `${values[0]} and ${values[1]}`;
 
495
  * remounted, and so this whole tab still paints under `renderToStaticMarkup`.
496
  *
497
  * ⛔ NO CONTROL AT ALL FOR A READER WHO MAY NOT RENAME (`canRename` is the server's own `may_open`
498
+ * answer). Enabling one Odoo database materialises it in the same request (W56-T31,
499
+ * `routes_connectors.py::_enable_odoo_database`), so there is no waiting state left to describe.
500
+ * A reader who may not rename gets no control at all, rather than a sentence about a wait.
501
  */
502
  function NameCell({
503
  database,
 
539
  >
540
  {database.override ? "Change" : "Rename"}
541
  </button>
 
 
542
  ) : null}
543
  </div>
544
  );
 
610
  }, ref) {
611
  const { databases, introspection } = detail;
612
  const showsPopulation = row.key === "odoo";
613
+ const usesProviderEnablement = Boolean(detail.enablement?.canManage && detail.enablement.updatePath);
614
  /**
615
  * ⚠ W53-T27 — EVERY ROW STARTS CLOSED, and that changed here. Until this ticket the first
616
  * database was opened for you, because the field list WAS the content of this tab. The content
 
621
  () => reveal?.key ? { [reveal.key]: true } : {}
622
  );
623
  const [busy, setBusy] = useState("");
624
+ const [confirmOff, setConfirmOff] = useState<ConnectorDatabase | null>(null);
625
  const [refusals, setRefusals] = useState<Record<string, string>>({});
626
  const [autoEnableResults, setAutoEnableResults] = useState<Record<string, string>>(
627
  () => reveal?.key && reveal.status ? { [reveal.key]: reveal.status } : {}
 
669
  [databases, pending.tables]
670
  );
671
 
672
+ const stageTable = useCallback(
673
+ (database: ConnectorDatabase, next: boolean) => {
674
+ setPending((current) => {
675
+ const tables = { ...current.tables };
676
+ if (next === database.enabled) delete tables[database.key];
677
+ else tables[database.key] = next;
678
+ return { ...current, tables };
679
+ });
680
+ },
681
+ []
682
+ );
683
+
684
  /**
685
+ * R23: the dependents check precedes staging because the disable door only writes config.
686
+ * W57-T31 / R10 / C9: Odoo also warns about the lock before accepting an off change.
687
+ * Provider-managed enablement keeps its existing staging path.
 
688
  *
689
  * ⛔ AND A FAILED CHECK IS NOT A PASSED ONE. Any non-answer leaves the table on and prints the
690
  * cause; proceeding would turn "REFUSED" into "usually refused".
 
712
  setRefusals((current) => ({ ...current, [database.key]: answer.refusal }));
713
  return;
714
  }
715
+ if (!usesProviderEnablement) {
716
+ setBusy("");
717
+ setConfirmOff(database);
718
+ return;
719
+ }
720
  }
721
  setBusy("");
722
+ stageTable(database, next);
 
 
 
 
 
723
  },
724
+ [stageTable, usesProviderEnablement]
725
  );
726
 
727
  const flipField = useCallback(
 
810
  if (answer.workspaceChanged) signal(WORKSPACE_STALE_EVENT);
811
  continue;
812
  }
813
+ const answer = await disableDatabase(databaseKey);
814
+ if (!answer.ok) {
815
+ const message = answer.message;
 
816
  failed.tables[databaseKey] = next;
817
  failures.push(`${label}: ${message}`);
818
  }
 
1118
  );
1119
  })}
1120
  </table>
1121
+ <ConfirmDialog
1122
+ open={confirmOff !== null}
1123
+ title="Switch off this database"
1124
+ tone="destructive"
1125
+ confirmLabel="Switch off"
1126
+ body={
1127
+ <>
1128
+ <p>{confirmOff?.label} stops being materialised from Odoo when you save this change.</p>
1129
+ <p>
1130
+ Switching a database off starts a 7 day lock. It cannot be switched back on until
1131
+ the week is up, and nobody can shorten it.
1132
+ </p>
1133
+ </>
1134
+ }
1135
+ onConfirm={() => {
1136
+ if (confirmOff) stageTable(confirmOff, false);
1137
+ setConfirmOff(null);
1138
+ }}
1139
+ onCancel={() => setConfirmOff(null)}
1140
+ />
1141
  </div>
1142
  );
1143
  });
web/src/customer-grid/CustomerGrid.tsx CHANGED
@@ -1699,6 +1699,8 @@ interface CustomerGridProps {
1699
  * and edit the reason the rows are here. Only meaningful with `cellView`.
1700
  */
1701
  cellFilter?: FilterTree;
 
 
1702
  /** Report a filter edit from the cell View data surface; its Sheet caller owns settling. */
1703
  onCellFilterChange?: (tree: FilterTree) => void;
1704
  /**
@@ -1759,12 +1761,15 @@ interface LinkGridModalProps {
1759
  cellView?: boolean;
1760
  /** W56-T25: the Sheet cell's own filter, shown in the grid's standard filter control. */
1761
  cellFilter?: FilterTree;
 
 
1762
  /** W56-T25: report a grid filter edit so the Sheet caller can settle and persist it. */
1763
  onCellFilterChange?: (tree: FilterTree) => void;
1764
  /** W56-T24: chrome the caller owns, in the header, right of the title and left of Close. */
1765
  headerActions?: ReactNode;
1766
  /** W56-T24: a statement under the rows. Only rendered on a non-editable modal. */
1767
  footer?: ReactNode;
 
1768
  onSave?: (recordIds: number[]) => void;
1769
  onClose: () => void;
1770
  }
@@ -1774,8 +1779,8 @@ interface LinkGridModalProps {
1774
  // the two surfaces cannot drift into two popups that behave almost alike. W56-T24 adds optional
1775
  // chrome slots and a `cellView` modifier while leaving existing callers and the focus trap intact.
1776
  export function LinkGridModal({ label, table, recordIds, editable = false, single = false,
1777
- excludeRecordId, cellView = false, cellFilter, onCellFilterChange, headerActions, footer,
1778
- onSave, onClose }: LinkGridModalProps) {
1779
  const panelRef = useRef<HTMLDivElement>(null);
1780
  const [selectedIds, setSelectedIds] = useState<number[]>(() => [...recordIds]);
1781
  const changeSelectedIds = useCallback((ids: number[]) => {
@@ -1831,12 +1836,14 @@ export function LinkGridModal({ label, table, recordIds, editable = false, singl
1831
  embedded
1832
  cellView={cellView}
1833
  cellFilter={cellFilter}
 
1834
  onCellFilterChange={onCellFilterChange}
1835
  embeddedRecordIds={editable ? undefined : recordIds}
1836
  embeddedExcludeRecordId={editable ? excludeRecordId : undefined}
1837
  embeddedSelectable={editable}
1838
  embeddedSelectedIds={selectedIds}
1839
  onEmbeddedSelectionChange={changeSelectedIds}
 
1840
  />
1841
  </div>
1842
  {editable ? (
@@ -1983,6 +1990,7 @@ function CustomerGridSurface({
1983
  related,
1984
  cellView = false,
1985
  cellFilter,
 
1986
  onCellFilterChange,
1987
  onOpenRecord,
1988
  relatedViewId,
@@ -2620,6 +2628,7 @@ function CustomerGridSurface({
2620
  // A parent may rebuild an equivalent tree on every render. Depend on its value, not its identity,
2621
  // so the initialization effect cannot re-seed over an edit still settling in this surface.
2622
  const cellFilterKey = useMemo(() => JSON.stringify(cellFilter ?? null), [cellFilter]);
 
2623
 
2624
  // Initialize once per permission/data scope. Host state wins; local state
2625
  // fills only missing objects and keeps the standalone path useful.
@@ -2769,6 +2778,10 @@ function CustomerGridSurface({
2769
  ...active.config,
2770
  filters: cellFilter.nodes ?? [],
2771
  filterConj: cellFilter.conj ?? "and",
 
 
 
 
2772
  } : active.config);
2773
  setWorkspaceReady(true);
2774
  initializedKey.current = storageKey;
@@ -2810,7 +2823,18 @@ function CustomerGridSurface({
2810
  reemittedRef.current = { ...(local?.reemitted ?? {}) };
2811
  }
2812
  }, [payload, payloadFields, storageKey, hostWorkspace, scope, isQueryPreview, queryBinding,
2813
- cellView, cellFilterKey]);
 
 
 
 
 
 
 
 
 
 
 
2814
 
2815
  /**
2816
  * ⭐ W36-T03 — the view-preference stamp, and it is its OWN effect on purpose.
 
1699
  * and edit the reason the rows are here. Only meaningful with `cellView`.
1700
  */
1701
  cellFilter?: FilterTree;
1702
+ /** The Sheet cell's ordered visible field keys. Only meaningful with `cellView`. */
1703
+ cellFields?: string[];
1704
  /** Report a filter edit from the cell View data surface; its Sheet caller owns settling. */
1705
  onCellFilterChange?: (tree: FilterTree) => void;
1706
  /**
 
1761
  cellView?: boolean;
1762
  /** W56-T25: the Sheet cell's own filter, shown in the grid's standard filter control. */
1763
  cellFilter?: FilterTree;
1764
+ /** W57-T22: the Sheet cell's ordered visible field keys, shown in the grid's columns. */
1765
+ cellFields?: string[];
1766
  /** W56-T25: report a grid filter edit so the Sheet caller can settle and persist it. */
1767
  onCellFilterChange?: (tree: FilterTree) => void;
1768
  /** W56-T24: chrome the caller owns, in the header, right of the title and left of Close. */
1769
  headerActions?: ReactNode;
1770
  /** W56-T24: a statement under the rows. Only rendered on a non-editable modal. */
1771
  footer?: ReactNode;
1772
+ onOpenRecord?: CustomerGridProps["onOpenRecord"];
1773
  onSave?: (recordIds: number[]) => void;
1774
  onClose: () => void;
1775
  }
 
1779
  // the two surfaces cannot drift into two popups that behave almost alike. W56-T24 adds optional
1780
  // chrome slots and a `cellView` modifier while leaving existing callers and the focus trap intact.
1781
  export function LinkGridModal({ label, table, recordIds, editable = false, single = false,
1782
+ excludeRecordId, cellView = false, cellFilter, cellFields, onCellFilterChange, headerActions, footer,
1783
+ onOpenRecord, onSave, onClose }: LinkGridModalProps) {
1784
  const panelRef = useRef<HTMLDivElement>(null);
1785
  const [selectedIds, setSelectedIds] = useState<number[]>(() => [...recordIds]);
1786
  const changeSelectedIds = useCallback((ids: number[]) => {
 
1836
  embedded
1837
  cellView={cellView}
1838
  cellFilter={cellFilter}
1839
+ cellFields={cellFields}
1840
  onCellFilterChange={onCellFilterChange}
1841
  embeddedRecordIds={editable ? undefined : recordIds}
1842
  embeddedExcludeRecordId={editable ? excludeRecordId : undefined}
1843
  embeddedSelectable={editable}
1844
  embeddedSelectedIds={selectedIds}
1845
  onEmbeddedSelectionChange={changeSelectedIds}
1846
+ onOpenRecord={onOpenRecord}
1847
  />
1848
  </div>
1849
  {editable ? (
 
1990
  related,
1991
  cellView = false,
1992
  cellFilter,
1993
+ cellFields,
1994
  onCellFilterChange,
1995
  onOpenRecord,
1996
  relatedViewId,
 
2628
  // A parent may rebuild an equivalent tree on every render. Depend on its value, not its identity,
2629
  // so the initialization effect cannot re-seed over an edit still settling in this surface.
2630
  const cellFilterKey = useMemo(() => JSON.stringify(cellFilter ?? null), [cellFilter]);
2631
+ const cellFieldsKey = useMemo(() => JSON.stringify(cellFields ?? []), [cellFields]);
2632
 
2633
  // Initialize once per permission/data scope. Host state wins; local state
2634
  // fills only missing objects and keeps the standalone path useful.
 
2778
  ...active.config,
2779
  filters: cellFilter.nodes ?? [],
2780
  filterConj: cellFilter.conj ?? "and",
2781
+ ...(cellFields?.length ? {
2782
+ order: [...cellFields, ...active.config.order.filter((key) => !cellFields.includes(key))],
2783
+ visible: cellFields,
2784
+ } : {}),
2785
  } : active.config);
2786
  setWorkspaceReady(true);
2787
  initializedKey.current = storageKey;
 
2823
  reemittedRef.current = { ...(local?.reemitted ?? {}) };
2824
  }
2825
  }, [payload, payloadFields, storageKey, hostWorkspace, scope, isQueryPreview, queryBinding,
2826
+ cellView, cellFilterKey, cellFieldsKey]);
2827
+
2828
+ // Initialization runs once per scope. Keep the columns current after a cell filter settles,
2829
+ // retaining hidden keys in the order so the reader can show them again.
2830
+ useEffect(() => {
2831
+ if (!workspaceReady || !cellView || !cellFields?.length) return;
2832
+ setConfig((current) => ({
2833
+ ...current,
2834
+ order: [...cellFields, ...current.order.filter((key) => !cellFields.includes(key))],
2835
+ visible: cellFields,
2836
+ }));
2837
+ }, [workspaceReady, cellView, cellFieldsKey]);
2838
 
2839
  /**
2840
  * ⭐ W36-T03 — the view-preference stamp, and it is its OWN effect on purpose.
web/src/customer-grid/RecordDetail.tsx CHANGED
@@ -21,6 +21,9 @@ import { BodyPortal, useOverlayLayer } from "./OverlaySurface";
21
  * who never opens a related tab never downloads a second copy of anything.
22
  */
23
  const RelatedGrid = lazy(() => import("./CustomerGrid"));
 
 
 
24
  import {
25
  automationDetail,
26
  automationState,
@@ -59,7 +62,7 @@ import type { CustomerDoc, DisplayMode, Field, RelatedEntry, RelatedPin, Related
59
  /* ⭐ W53-T22 adds a FOURTH and a FIFTH, and for the same reason: `fetchTableWindow` +
60
  `WINDOW_ROWS` are the one windowed read this product owns, and the sibling set a pushed
61
  frame's chevrons page is that read with the frame's own pin on it. */
62
- import { fetchLinkTargets, fetchRelated, fetchTableWindow, fetchTopicRows, probeRelatedRead,
63
  readThroughTables, WINDOW_ROWS } from "./apiBridge";
64
  import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal } from "../apiContract";
65
 
@@ -723,6 +726,10 @@ interface RecordFrame {
723
  * chevrons go disabled and the caption says nothing, rather than paging a guess.
724
  */
725
  pin: RelatedPin | null;
 
 
 
 
726
  }
727
 
728
  /**
@@ -989,6 +996,10 @@ export default function RecordDetail({
989
  */
990
  const [stack, setStack] = useState<RecordFrame[]>([]);
991
  const frame = stack.length > 0 ? stack[stack.length - 1] : null;
 
 
 
 
992
  const navigationSequence = useRef(0);
993
  const [recordNavigation, setRecordNavigation] = useState<RecordNavigationIntent | null>(null);
994
  const beginRecordNavigation = useCallback((fromPid: number, targetPid?: number) => {
@@ -1007,9 +1018,44 @@ export default function RecordDetail({
1007
  * way in, which is a filter that matches everything.
1008
  */
1009
  const fields = frame ? frame.fields : baseFields;
1010
- const record = frame ? frame.record : baseRecord;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1011
  useEffect(() => {
1012
  setStack((prev) => (prev.length ? [] : prev));
 
1013
  }, [baseRecord.pid, scope]);
1014
  /**
1015
  * ⭐⭐ W53-T22 (R4) — THE ONE PLACE THE STACK IS SHORTENED, and it is one place on purpose.
@@ -1474,10 +1520,37 @@ export default function RecordDetail({
1474
  * upwards would be the same stale read this ticket exists to delete, one indirection along.
1475
  */
1476
  const pushFrame = useCallback(
1477
- (pid: number, table: string, row?: Row, rowFields?: Field[]) => {
1478
  if (!row || !rowFields || rowFields.length === 0) return;
1479
  const first = rowFields[0];
1480
  const named = first ? String(row[first.key] ?? "") : "";
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1481
  setStack((prev) => [...prev, {
1482
  table,
1483
  pid,
@@ -1490,9 +1563,11 @@ export default function RecordDetail({
1490
  pin: relatedPin
1491
  ? { table: relatedPin.table, record: relatedPin.record, via: relatedPin.via }
1492
  : null,
 
 
1493
  }]);
1494
  },
1495
- [relatedPin]
1496
  );
1497
 
1498
  /* ═══════════════════════════════════════════════════════════════════════════════════════
@@ -1536,7 +1611,7 @@ export default function RecordDetail({
1536
  // ⛔ Not read through ⇒ no request at all. See the guard note above.
1537
  if (!live || !through.has(asked.table)) return;
1538
  const payload = await fetchTableWindow(asked.table,
1539
- { offset: 0, limit: WINDOW_ROWS, related: asked.pin });
1540
  if (!live || !payload) return;
1541
  setSiblings({ key: framePinKey, rows: payload.rows, fields: payload.fields });
1542
  })();
@@ -1592,6 +1667,8 @@ export default function RecordDetail({
1592
  record: next,
1593
  fields: siblings.fields,
1594
  pin: frame.pin,
 
 
1595
  }]));
1596
  },
1597
  [beginRecordNavigation, frame, framePinKey, siblingIndex, siblingRows, siblings.fields]
@@ -2074,6 +2151,7 @@ export default function RecordDetail({
2074
  // thing the viewer's parse-on-save exists to prevent, sitting one panel away from it.
2075
  // It joins the constrained-control family: preview + "Open", and the viewer owns the edit.
2076
  field.type !== "json" &&
 
2077
  field.type !== "pct";
2078
  const isControl = editable && !isEdit;
2079
  const cls =
@@ -2094,7 +2172,21 @@ export default function RecordDetail({
2094
  (dragKey === field.key ? " is-dragging" : "");
2095
 
2096
  let slot: ReactNode;
2097
- if (isEdit) {
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2098
  const raw = String(record[field.key] ?? "");
2099
  const href = actionHref(field, raw);
2100
  slot = (
@@ -3087,6 +3179,11 @@ export default function RecordDetail({
3087
  <>
3088
  {/* C-LAYOUT — ONE list, this user's order, every type interleaved. */}
3089
  <section className="cg-detail-section cg-detail-fieldlist">
 
 
 
 
 
3090
  {orderedKeys.map((key, index) => {
3091
  const field = fieldByKey.get(key);
3092
  return field ? renderRow(field, index) : null;
@@ -3145,6 +3242,24 @@ export default function RecordDetail({
3145
  {/* ⭐ Wave-23 C7 — the document viewer, INSIDE this portal and therefore stacked above
3146
  this modal. `useOverlayLayer`'s stack is what makes that work: it registers on top, so
3147
  Escape closes the viewer and leaves the record open rather than dismissing both. */}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3148
  {jsonKey && (() => {
3149
  const field = fields.find((f) => f.key === jsonKey);
3150
  if (!field) return null;
 
21
  * who never opens a related tab never downloads a second copy of anything.
22
  */
23
  const RelatedGrid = lazy(() => import("./CustomerGrid"));
24
+ const LinkedRecordGrid = lazy(() => import("./CustomerGrid").then((module) => ({
25
+ default: module.LinkGridModal,
26
+ })));
27
  import {
28
  automationDetail,
29
  automationState,
 
62
  /* ⭐ W53-T22 adds a FOURTH and a FIFTH, and for the same reason: `fetchTableWindow` +
63
  `WINDOW_ROWS` are the one windowed read this product owns, and the sibling set a pushed
64
  frame's chevrons page is that read with the frame's own pin on it. */
65
+ import { fetchLinkTargets, fetchRecordMeasureValues, fetchRelated, fetchTableWindow, fetchTopicRows, probeRelatedRead,
66
  readThroughTables, WINDOW_ROWS } from "./apiBridge";
67
  import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal } from "../apiContract";
68
 
 
726
  * chevrons go disabled and the caption says nothing, rather than paging a guess.
727
  */
728
  pin: RelatedPin | null;
729
+ /** `pin` is the parent's pin for paging siblings; `originPin` is the record every
730
+ * measure on this frame must be counted within. It never changes the stored fields. */
731
+ originPin: RelatedPin | null;
732
+ originReason: string;
733
  }
734
 
735
  /**
 
996
  */
997
  const [stack, setStack] = useState<RecordFrame[]>([]);
998
  const frame = stack.length > 0 ? stack[stack.length - 1] : null;
999
+ const [frameMeasures, setFrameMeasures] = useState<{
1000
+ frame: RecordFrame; values: Partial<Row> | null; reason: string;
1001
+ } | null>(null);
1002
+ const [openLinkField, setOpenLinkField] = useState<Field | null>(null);
1003
  const navigationSequence = useRef(0);
1004
  const [recordNavigation, setRecordNavigation] = useState<RecordNavigationIntent | null>(null);
1005
  const beginRecordNavigation = useCallback((fromPid: number, targetPid?: number) => {
 
1018
  * way in, which is a filter that matches everything.
1019
  */
1020
  const fields = frame ? frame.fields : baseFields;
1021
+ // The source row stays intact while enrichment is pending or fails. Only Metric keys from
1022
+ // this exact frame's read may overlay it; a late response cannot paint another frame's values.
1023
+ const record = useMemo(() => (frame
1024
+ ? { ...frame.record, ...(frameMeasures?.frame === frame ? frameMeasures.values : null) }
1025
+ : baseRecord), [baseRecord, frame, frameMeasures]);
1026
+ useEffect(() => {
1027
+ if (!frame?.originPin || !frame.fields.some((field) => field.measure)) return;
1028
+ const asked = frame;
1029
+ const pin = frame.originPin;
1030
+ let live = true;
1031
+ void (async () => {
1032
+ const through = await readThroughTables();
1033
+ if (!live) return;
1034
+ if (!through.has(asked.table)) {
1035
+ setFrameMeasures({ frame: asked, values: null,
1036
+ reason: "Metric values are unscoped because filtering support for this database could not be confirmed." });
1037
+ return;
1038
+ }
1039
+ const result = await fetchRecordMeasureValues(
1040
+ asked.table, asked.pid, asked.fields, pin, () => live
1041
+ );
1042
+ if (live) setFrameMeasures({ frame: asked, ...result });
1043
+ })().catch(() => {
1044
+ if (live) setFrameMeasures({ frame: asked, values: null,
1045
+ reason: "Metric values are unscoped because the related record read failed." });
1046
+ });
1047
+ return () => { live = false; };
1048
+ }, [frame]);
1049
+ const metricScopeNote = frame && fields.some((field) => field.measure)
1050
+ ? !frame.originPin
1051
+ ? frame.originReason
1052
+ : frameMeasures?.frame === frame
1053
+ ? frameMeasures.reason
1054
+ : "Metric values are unscoped while the values for the linked record load."
1055
+ : "";
1056
  useEffect(() => {
1057
  setStack((prev) => (prev.length ? [] : prev));
1058
+ setOpenLinkField(null);
1059
  }, [baseRecord.pid, scope]);
1060
  /**
1061
  * ⭐⭐ W53-T22 (R4) — THE ONE PLACE THE STACK IS SHORTENED, and it is one place on purpose.
 
1520
  * upwards would be the same stale read this ticket exists to delete, one indirection along.
1521
  */
1522
  const pushFrame = useCallback(
1523
+ (pid: number, table: string, row?: Row, rowFields?: Field[], linkField?: Field) => {
1524
  if (!row || !rowFields || rowFields.length === 0) return;
1525
  const first = rowFields[0];
1526
  const named = first ? String(row[first.key] ?? "") : "";
1527
+ // Carry the parent's origin down the stack unless this hop establishes a nearer origin.
1528
+ // An explicitly unnamed or unserved link breaks that inheritance: it cannot carry a pin.
1529
+ let originPin = frame?.originPin ?? null;
1530
+ let originReason = frame?.originReason
1531
+ || "Metric values are unscoped because this link does not declare a relation path.";
1532
+ if (linkField) {
1533
+ // Match the actual Link field's declaration to a registry entry, never a target-only
1534
+ // guess or an assembled path. Ambiguous declarations remain unscoped.
1535
+ const link = linkField.link;
1536
+ const matches = entries.filter((entry) => entry.target === table && link?.table === table
1537
+ && (entry.via.field === linkField.key
1538
+ || (link.on && entry.via.on === link.on && entry.via.from === link.from)));
1539
+ const edge = matches.length === 1 ? matches[0] : null;
1540
+ originPin = edge?.served ? {
1541
+ table: recordTable,
1542
+ record: Number(record.pid),
1543
+ via: edge.hops === 2 ? edge.path : edge.via,
1544
+ } : null;
1545
+ originReason = edge && !edge.served
1546
+ ? "Metric values are unscoped because this link cannot filter the destination database yet."
1547
+ : "Metric values are unscoped because this link field does not declare one identifiable relation path.";
1548
+ } else if (activeRelated?.entry.target === table && relatedPin) {
1549
+ originPin = activeRelated.entry.served
1550
+ ? { table: relatedPin.table, record: relatedPin.record, via: relatedPin.via }
1551
+ : null;
1552
+ originReason = "Metric values are unscoped because this link cannot filter the destination database yet.";
1553
+ }
1554
  setStack((prev) => [...prev, {
1555
  table,
1556
  pid,
 
1563
  pin: relatedPin
1564
  ? { table: relatedPin.table, record: relatedPin.record, via: relatedPin.via }
1565
  : null,
1566
+ originPin,
1567
+ originReason,
1568
  }]);
1569
  },
1570
+ [activeRelated, entries, frame, record.pid, recordTable, relatedPin]
1571
  );
1572
 
1573
  /* ═══════════════════════════════════════════════════════════════════════════════════════
 
1611
  // ⛔ Not read through ⇒ no request at all. See the guard note above.
1612
  if (!live || !through.has(asked.table)) return;
1613
  const payload = await fetchTableWindow(asked.table,
1614
+ { offset: 0, limit: WINDOW_ROWS, related: asked.pin }, () => {});
1615
  if (!live || !payload) return;
1616
  setSiblings({ key: framePinKey, rows: payload.rows, fields: payload.fields });
1617
  })();
 
1667
  record: next,
1668
  fields: siblings.fields,
1669
  pin: frame.pin,
1670
+ originPin: frame.originPin,
1671
+ originReason: frame.originReason,
1672
  }]));
1673
  },
1674
  [beginRecordNavigation, frame, framePinKey, siblingIndex, siblingRows, siblings.fields]
 
2151
  // thing the viewer's parse-on-save exists to prevent, sitting one panel away from it.
2152
  // It joins the constrained-control family: preview + "Open", and the viewer owns the edit.
2153
  field.type !== "json" &&
2154
+ field.type !== "link" &&
2155
  field.type !== "pct";
2156
  const isControl = editable && !isEdit;
2157
  const cls =
 
2172
  (dragKey === field.key ? " is-dragging" : "");
2173
 
2174
  let slot: ReactNode;
2175
+ if (field.type === "link" && field.link) {
2176
+ slot = (
2177
+ <span className="cg-detail-value cg-detail-jsonslot">
2178
+ <span>{formatDisplay(field, record[field.key]) || "No linked records"}</span>
2179
+ <button
2180
+ id={inputId}
2181
+ type="button"
2182
+ className="cg-detail-imagebtn"
2183
+ onClick={() => setOpenLinkField(field)}
2184
+ >
2185
+ Open
2186
+ </button>
2187
+ </span>
2188
+ );
2189
+ } else if (isEdit) {
2190
  const raw = String(record[field.key] ?? "");
2191
  const href = actionHref(field, raw);
2192
  slot = (
 
3179
  <>
3180
  {/* C-LAYOUT — ONE list, this user's order, every type interleaved. */}
3181
  <section className="cg-detail-section cg-detail-fieldlist">
3182
+ {metricScopeNote && (
3183
+ <p className="cg-record-related-note" role="status">
3184
+ {metricScopeNote}
3185
+ </p>
3186
+ )}
3187
  {orderedKeys.map((key, index) => {
3188
  const field = fieldByKey.get(key);
3189
  return field ? renderRow(field, index) : null;
 
3242
  {/* ⭐ Wave-23 C7 — the document viewer, INSIDE this portal and therefore stacked above
3243
  this modal. `useOverlayLayer`'s stack is what makes that work: it registers on top, so
3244
  Escape closes the viewer and leaves the record open rather than dismissing both. */}
3245
+ {openLinkField?.link && (
3246
+ <Suspense fallback={null}>
3247
+ <LinkedRecordGrid
3248
+ label={openLinkField.label}
3249
+ table={relatedScope(openLinkField.link.table)}
3250
+ recordIds={linkedPids(record[openLinkField.key])}
3251
+ editable={!frame && mayEditField(openLinkField, viewer) && !openLinkField.link.on}
3252
+ single={openLinkField.link.single === true}
3253
+ excludeRecordId={openLinkField.link.table === recordTable ? Number(record.pid) : undefined}
3254
+ onSave={(ids) => onNotesCommit(openLinkField.key, ids.join(","))}
3255
+ onOpenRecord={(pid, table, row, rowFields) => {
3256
+ pushFrame(pid, table, row, rowFields, openLinkField);
3257
+ setOpenLinkField(null);
3258
+ }}
3259
+ onClose={() => setOpenLinkField(null)}
3260
+ />
3261
+ </Suspense>
3262
+ )}
3263
  {jsonKey && (() => {
3264
  const field = fields.find((f) => f.key === jsonKey);
3265
  if (!field) return null;
web/src/customer-grid/apiBridge.ts CHANGED
@@ -496,12 +496,15 @@ export function readThroughTables(): Promise<Set<string>> {
496
  return readThroughMemo;
497
  }
498
 
499
- /** `GET /api/v1/odoo-tables/<key>/rows?…` — one window, mapped. Null on any failure, having
500
- * raised the matching signal (a null is a failure, never an empty table). */
501
  export async function fetchTableWindow(
502
  tableKey: string,
503
- req: RowWindowRequest
 
504
  ): Promise<CustomersPayload | null> {
 
 
505
  const path = windowRowsPath(tableKey, req);
506
  const cached = rowsCache.get(path);
507
  if (cached && Date.now() - cached.at < CUSTOMERS_FRESH_MS) return cached.payload;
@@ -509,7 +512,7 @@ export async function fetchTableWindow(
509
  try {
510
  res = await fetch(`${API_V1}/${path}`, { credentials: CREDENTIALS });
511
  } catch {
512
- signal(DATA_ERROR_EVENT, "Cannot reach the server.");
513
  return null;
514
  }
515
  if (handledSession(res)) return null;
@@ -518,18 +521,59 @@ export async function fetchTableWindow(
518
  // condition has no SQL form and what to use instead; "The server answered 400." explains
519
  // nothing, which is the defect `refusalMessage` was extracted for one wave ago.
520
  const body = await readJson(res);
521
- signal(DATA_ERROR_EVENT, refusalMessage(body, res.status));
522
  return null;
523
  }
524
  const payload = windowPayload(await readJson(res));
525
  if (!payload) {
526
- signal(DATA_ERROR_EVENT, "The server sent an unreadable payload.");
527
  return null;
528
  }
529
  rowsCache.set(path, { at: Date.now(), payload });
530
  return payload;
531
  }
532
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
533
  // ═══════════════════════════════════════════════════════════════════════════════════════════
534
  // ⭐⭐ WAVE 50 · W50-T03 — CONTRACT C1: THE WINDOWED AGGREGATE (owner ruling R1, second half).
535
  // ═══════════════════════════════════════════════════════════════════════════════════════════
 
496
  return readThroughMemo;
497
  }
498
 
499
+ /** One window, mapped. A failure returns null and reports through the caller's handler or
500
+ * the default data-error signal; null is never an empty table. */
501
  export async function fetchTableWindow(
502
  tableKey: string,
503
+ req: RowWindowRequest,
504
+ onFailure?: (reason: string) => void
505
  ): Promise<CustomersPayload | null> {
506
+ // Optional record enrichment reports its failure inline without replacing the open drawer.
507
+ const fail = onFailure ?? ((reason: string) => signal(DATA_ERROR_EVENT, reason));
508
  const path = windowRowsPath(tableKey, req);
509
  const cached = rowsCache.get(path);
510
  if (cached && Date.now() - cached.at < CUSTOMERS_FRESH_MS) return cached.payload;
 
512
  try {
513
  res = await fetch(`${API_V1}/${path}`, { credentials: CREDENTIALS });
514
  } catch {
515
+ fail("Cannot reach the server.");
516
  return null;
517
  }
518
  if (handledSession(res)) return null;
 
521
  // condition has no SQL form and what to use instead; "The server answered 400." explains
522
  // nothing, which is the defect `refusalMessage` was extracted for one wave ago.
523
  const body = await readJson(res);
524
+ fail(refusalMessage(body, res.status));
525
  return null;
526
  }
527
  const payload = windowPayload(await readJson(res));
528
  if (!payload) {
529
+ fail("The server sent an unreadable payload.");
530
  return null;
531
  }
532
  rowsCache.set(path, { at: Date.now(), payload });
533
  return payload;
534
  }
535
 
536
+ /** C10: find this exact record within the named pin, then return only its Metric values.
537
+ * No pid filter: undeclared filter keys can be dropped by the rows door. Each page uses the
538
+ * existing window path/cache, including `related`, and stops when the drawer leaves this frame.
539
+ */
540
+ export async function fetchRecordMeasureValues(
541
+ tableKey: string,
542
+ pid: number,
543
+ fields: Field[],
544
+ related: RelatedPin,
545
+ isCurrent: () => boolean
546
+ ): Promise<{ values: Partial<Row> | null; reason: string }> {
547
+ const measureKeys = fields.filter((field) => field.measure).map((field) => field.key);
548
+ let offset = 0;
549
+ while (isCurrent()) {
550
+ let reason = "Metric values are unscoped because the related record read failed.";
551
+ const payload = await fetchTableWindow(tableKey, { offset, limit: WINDOW_ROWS, related },
552
+ (failure) => { reason = `Metric values are unscoped because the related record read failed: ${failure}`; });
553
+ if (!payload || !isCurrent()) return { values: null, reason };
554
+ // A successful HTTP response can still report a refused or incomplete calculation.
555
+ const limit = payload.limits?.find((item) => item.effect !== "none");
556
+ if (limit) return {
557
+ values: null,
558
+ reason: `Metric values are unscoped because the related read is limited: ${limit.cause}`,
559
+ };
560
+ const row = payload.rows.find((candidate) => Number(candidate.pid) === pid);
561
+ if (row) {
562
+ if (measureKeys.some((key) => !Object.prototype.hasOwnProperty.call(row, key))) {
563
+ return { values: null,
564
+ reason: "Metric values are unscoped because the related read did not return every metric field." };
565
+ }
566
+ const values: Partial<Row> = {};
567
+ for (const key of measureKeys) values[key] = row[key];
568
+ return { values, reason: "" };
569
+ }
570
+ offset += payload.rows.length;
571
+ if (!payload.rows.length || offset >= (payload.counts?.matched ?? offset)) break;
572
+ }
573
+ return { values: null,
574
+ reason: "Metric values are unscoped because this record was not found within the related records." };
575
+ }
576
+
577
  // ═══════════════════════════════════════════════════════════════════════════════════════════
578
  // ⭐⭐ WAVE 50 · W50-T03 — CONTRACT C1: THE WINDOWED AGGREGATE (owner ruling R1, second half).
579
  // ═══════════════════════════════════════════════════════════════════════════════════════════
web/src/customer-grid/timeSeriesData.ts CHANGED
@@ -451,7 +451,8 @@ const TS_SNAPSHOT_TYPES: ReadonlySet<string> = new Set(["currency", "int", "pct"
451
  * `overdue_days`, `days_since` and `typical_gap_days` are all `int`, and the sum of "days to pay"
452
  * across 1,500 customers is a number with no meaning that would nonetheless print, in bold, under
453
  * a month heading. Matched on the KEY because the contract does not distinguish them by type and
454
- * mostly leaves `agg` unset (measured: only `est_missed` declares one).
 
455
  *
456
  * A field's OWN declared `agg` wins when it has one — the contract saying so beats a heuristic.
457
  */
 
451
  * `overdue_days`, `days_since` and `typical_gap_days` are all `int`, and the sum of "days to pay"
452
  * across 1,500 customers is a number with no meaning that would nonetheless print, in bold, under
453
  * a month heading. Matched on the KEY because the contract does not distinguish them by type and
454
+ * no contract field declares `agg` today: the last one was removed at the owner's instruction
455
+ * in wave 57. The `field.agg` branch supports user-created or future fields.
456
  *
457
  * A field's OWN declared `agg` wins when it has one — the contract saying so beats a heuristic.
458
  */
web/src/home/HomePage.tsx CHANGED
@@ -34,6 +34,7 @@ import { DatabaseMark } from "../customer-grid/iconShapes";
34
  // `.home-db-glyph` box that replaces `.shell-db-chip` below, and Home never loads the grid chunk
35
  // that ViewSidebar's copy of this import lives in.
36
  import "../styles/wave50/rail.css";
 
37
  // ⭐ WAVE 26 · ITEM 18 / R14 + C7 — THE LOOP MARK ON HOME'S FOURTH `.auto-dot` SITE.
38
  // The scout table named three call sites; this is the fourth, found by SESSION B and handed over
39
  // rather than reached across the fence. Same rule as the rail: consume the component that points
@@ -374,11 +375,6 @@ export function HomeSurface({
374
  <div className="shell-home">
375
  <div className="home-page-head">
376
  <h1 className="home-title">{mode === "app" ? "App" : "Home"}</h1>
377
- {mode === "app" ? (
378
- <button type="button" className="home-app-create" onClick={onTemplates}>
379
- Create new
380
- </button>
381
- ) : null}
382
  </div>
383
 
384
  {mode === "home" ? <div className="home-cards">
@@ -428,7 +424,23 @@ export function HomeSurface({
428
  detail="Browse the connectors this workspace can use."
429
  onClick={onConnectors}
430
  />
431
- </div> : null}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
432
 
433
  <div className="home-recents-bar">
434
  {/* The reference puts an "Opened anytime" filter here. We do not have one and do not
 
34
  // `.home-db-glyph` box that replaces `.shell-db-chip` below, and Home never loads the grid chunk
35
  // that ViewSidebar's copy of this import lives in.
36
  import "../styles/wave50/rail.css";
37
+ import "../styles/wave57/home-app.css";
38
  // ⭐ WAVE 26 · ITEM 18 / R14 + C7 — THE LOOP MARK ON HOME'S FOURTH `.auto-dot` SITE.
39
  // The scout table named three call sites; this is the fourth, found by SESSION B and handed over
40
  // rather than reached across the fence. Same rule as the rail: consume the component that points
 
375
  <div className="shell-home">
376
  <div className="home-page-head">
377
  <h1 className="home-title">{mode === "app" ? "App" : "Home"}</h1>
 
 
 
 
 
378
  </div>
379
 
380
  {mode === "home" ? <div className="home-cards">
 
424
  detail="Browse the connectors this workspace can use."
425
  onClick={onConnectors}
426
  />
427
+ </div> : <div className="home-cards is-app">
428
+ {/* ⭐ W57-T28 (owner instruction 26): *"The APP module, the 'Create new' should look
429
+ exactly like how the create new button looks like under Home page."* It was a filled
430
+ pill in the header while Home offered a card, and BOTH OPEN THE SAME DOOR: `Shell.tsx`
431
+ hands `openApplicationWizard` to each of them and says so in its own comment. One door
432
+ wearing two looks is the defect, so App now wears Home's card: same component, same
433
+ glyph, same tokens. The two ghosts below are layout, not content (see
434
+ `styles/wave57/home-app.css` for why they cannot be `display: none`). */}
435
+ <QuickCard
436
+ icon={<TemplateIcon />}
437
+ title="Create new"
438
+ detail="Build an app over a database in this workspace."
439
+ onClick={onTemplates}
440
+ />
441
+ <span className="home-card-ghost" aria-hidden="true" />
442
+ <span className="home-card-ghost" aria-hidden="true" />
443
+ </div>}
444
 
445
  <div className="home-recents-bar">
446
  {/* The reference puts an "Opened anytime" filter here. We do not have one and do not
web/src/settings/SecurityPane.tsx ADDED
@@ -0,0 +1,147 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // settings / SecurityPane.tsx - W57-T36, R15 / C12.
3
+ //
4
+ // Every stored account owns its second factor, so this is a session-scoped
5
+ // room for every user. It reads status, never the installed secret. A new phone
6
+ // goes through the admin reset and the login enrolment door, not a second editor.
7
+ // ---------------------------------------------------------------------------
8
+
9
+ import { useEffect, useRef, useState } from "react";
10
+ import type { FormEvent } from "react";
11
+ import { mfaStatus, regenerateRecoveryCodes } from "../shell/session";
12
+ import type { MFAStatus } from "../shell/session";
13
+ import { RecoveryCodes } from "../shell/LoginPage";
14
+ import { useEscapeClose } from "../ui/useEscapeClose";
15
+ import "../styles/wave57/login-mfa.css";
16
+
17
+ export default function SecurityPane() {
18
+ const [status, setStatus] = useState<MFAStatus | null>(null);
19
+ const [loading, setLoading] = useState<boolean>(true);
20
+ const [reload, setReload] = useState<number>(0);
21
+ const [password, setPassword] = useState<string>("");
22
+ const [busy, setBusy] = useState<boolean>(false);
23
+ const [codes, setCodes] = useState<string[] | null>(null);
24
+ const [error, setError] = useState<string>("");
25
+ const flight = useRef<boolean>(false);
26
+ const dialog = useRef<HTMLDialogElement>(null);
27
+ const passwordField = useRef<HTMLInputElement>(null);
28
+ const locked = busy || codes !== null;
29
+
30
+ useEffect(() => {
31
+ let current = true;
32
+ setLoading(true);
33
+ setError("");
34
+ void mfaStatus().then((next) => {
35
+ if (!current) return;
36
+ setStatus(next);
37
+ setLoading(false);
38
+ if (!next) setError("Security status could not be loaded. Try again.");
39
+ });
40
+ return () => { current = false; };
41
+ }, [reload]);
42
+
43
+ // Lock BEFORE issuing codes, not only after receiving them: closing Settings
44
+ // during the POST would throw away its only clear response. A native modal
45
+ // makes the rail, close button and backdrop inert without changing the parent.
46
+ // The shared Escape arbiter stops Settings' older window listener as well.
47
+ useEscapeClose(busy, () => setError("Wait for your recovery codes before leaving."));
48
+ useEffect(() => {
49
+ if (!locked) return;
50
+ const node = dialog.current;
51
+ if (!node) return;
52
+ node.showModal();
53
+ return () => {
54
+ node.close();
55
+ passwordField.current?.focus();
56
+ };
57
+ }, [locked]);
58
+
59
+ async function generate(event: FormEvent) {
60
+ event.preventDefault();
61
+ if (flight.current || codes || !status?.enrolled || !password) return;
62
+ flight.current = true;
63
+ setBusy(true);
64
+ setError("");
65
+ const result = await regenerateRecoveryCodes(password);
66
+ // No password survives a write attempt. The response is the new set only;
67
+ // do not re-read or cache it, and do not offer generation while it is shown.
68
+ setPassword("");
69
+ if (result.ok === false) {
70
+ setError(result.message);
71
+ } else {
72
+ setCodes(result.recoveryCodes);
73
+ setStatus((previous) => previous
74
+ ? { ...previous, recoveryCodesRemaining: result.recoveryCodes.length } : null);
75
+ }
76
+ flight.current = false;
77
+ setBusy(false);
78
+ }
79
+
80
+ return (
81
+ <div className="set-pane login-form login-mfa-security">
82
+ <h3 className="set-h">Security</h3>
83
+ {loading ? <p className="login-mfa-help" role="status">Loading security status…</p> : status ? (
84
+ <>
85
+ <dl className="login-mfa-status">
86
+ <div><dt>Two step sign in</dt><dd>{status.enrolled ? "On" : "Off"}</dd></div>
87
+ {status.enrolled ? (
88
+ <div><dt>Turned on</dt><dd>{status.enrolledAt
89
+ ? <time dateTime={status.enrolledAt}>{new Date(status.enrolledAt).toLocaleString()}</time>
90
+ : "Date unavailable"}</dd></div>
91
+ ) : null}
92
+ <div><dt>Recovery codes left</dt><dd>{status.recoveryCodesRemaining}</dd></div>
93
+ </dl>
94
+ <p className="login-mfa-help">To enrol a new phone, ask an administrator to reset two step sign in, then sign in again.</p>
95
+ {status.enrolled ? (
96
+ <>
97
+ <p className="login-mfa-help">Generating new recovery codes replaces the old codes and signs this account's other sessions out.</p>
98
+ {!locked ? (
99
+ <form className="login-form login-mfa-regenerate" onSubmit={generate}>
100
+ <label className="login-mfa-label" htmlFor="security-password">Account password</label>
101
+ <input id="security-password" className="login-input" type="password" autoComplete="current-password"
102
+ ref={passwordField} value={password} disabled={busy} required
103
+ aria-invalid={error ? true : undefined} aria-describedby="security-message"
104
+ onChange={(event) => { setPassword(event.target.value); setError(""); }} />
105
+ <button type="submit" className="login-submit" disabled={!password || busy}>
106
+ Generate new recovery codes
107
+ </button>
108
+ </form>
109
+ ) : null}
110
+ </>
111
+ ) : <p className="login-mfa-help">Sign in again to set up your authenticator app.</p>}
112
+ </>
113
+ ) : (
114
+ <button type="button" className="login-mfa-quiet" onClick={() => setReload((value) => value + 1)}>
115
+ Try again
116
+ </button>
117
+ )}
118
+ <p className="login-msg" id="security-message" role="status" aria-live="polite">{locked ? "" : error}</p>
119
+
120
+ {/* R15/C12's explicit acknowledgement is the exception to ordinary
121
+ dismissible dialogs. Native cancel is prevented, outside clicks have
122
+ no close handler, and there is no close control or method=dialog form. */}
123
+ {locked ? (
124
+ <dialog ref={dialog} className="login-mfa-dialog" aria-labelledby="security-codes-heading"
125
+ onCancel={(event) => event.preventDefault()}>
126
+ <h4 id="security-codes-heading" className="login-mfa-heading" tabIndex={-1} autoFocus>Recovery codes</h4>
127
+ <div className="login-form">
128
+ {codes ? (
129
+ <RecoveryCodes codes={codes} onError={setError} onSaved={() => {
130
+ setCodes(null);
131
+ setError("");
132
+ // Count only, independently re-read after acknowledgement.
133
+ setReload((value) => value + 1);
134
+ }} />
135
+ ) : (
136
+ <>
137
+ <p className="login-mfa-help" role="status">Generating your recovery codes…</p>
138
+ <button type="button" className="login-submit" disabled>Generating codes…</button>
139
+ </>
140
+ )}
141
+ </div>
142
+ <p className="login-msg" role="status" aria-live="polite">{error}</p>
143
+ </dialog>
144
+ ) : null}
145
+ </div>
146
+ );
147
+ }
web/src/settings/SettingsModal.tsx CHANGED
@@ -77,6 +77,7 @@ import { ManageDatabasePane } from "./ManageDatabase";
77
  // client-local preference pane, self-contained like `ManageDatabasePane`; see the mount below.
78
  import ShortcutSettings from "./ShortcutSettings";
79
  import ExternalAccessPane from "./ExternalAccessPane";
 
80
  import OperatorPage from "../operator/OperatorPage";
81
  /* ⛔ `StatementsPane` LEFT WITH ITS RAIL ROW (wave 35 · T38): the file is DELETED, not merely
82
  unmounted. An orphaned component with no importer is the shape this repo books as
@@ -148,6 +149,13 @@ const IconAccess = (
148
  <path d="M5.6 7.1V5.3a2.4 2.4 0 0 1 4.8 0v1.8" />
149
  </RailIcon>
150
  );
 
 
 
 
 
 
 
151
  /** Sheet shortcuts — a small keyboard: a row of keys above a spacebar, not the padlock
152
  * "Your access" already wears (two authority glyphs in one rail would drift together). */
153
  const IconShortcuts = (
@@ -796,6 +804,7 @@ export function SettingsModal({
796
  const rail: Array<[SettingsSection, string, ReactNode]> = [
797
  ["account", "Account", IconAccount],
798
  ["scope", "Your access", IconAccess],
 
799
  // ⭐⭐ WAVE 52 · T19 (owner instruction 21) — NOT admin-gated, on the same footing as
800
  // `account` and `scope` immediately above: every user manages their own shortcut
801
  // preferences, and there is nothing behind this room a member's account cannot already do to
@@ -909,6 +918,7 @@ export function SettingsModal({
909
  `sheet/shortcuts.ts`'s own localStorage store directly and needs nothing passed
910
  in, because a keyboard preference is not server data. */}
911
  {active === "shortcuts" ? <ShortcutSettings /> : null}
 
912
  {active === "external" ? <ExternalAccessPane /> : null}
913
  {active === "keychains" ? <KeychainPane /> : null}
914
  {active === "connectors" ? <ConnectorsPane /> : null}
 
77
  // client-local preference pane, self-contained like `ManageDatabasePane`; see the mount below.
78
  import ShortcutSettings from "./ShortcutSettings";
79
  import ExternalAccessPane from "./ExternalAccessPane";
80
+ import SecurityPane from "./SecurityPane";
81
  import OperatorPage from "../operator/OperatorPage";
82
  /* ⛔ `StatementsPane` LEFT WITH ITS RAIL ROW (wave 35 · T38): the file is DELETED, not merely
83
  unmounted. An orphaned component with no importer is the shape this repo books as
 
149
  <path d="M5.6 7.1V5.3a2.4 2.4 0 0 1 4.8 0v1.8" />
150
  </RailIcon>
151
  );
152
+ /** Security - a shield protects the credential; access already wears the padlock. */
153
+ const IconSecurity = (
154
+ <RailIcon>
155
+ <path d="M8 1.8 13 3.9v4.2c0 2.7-2.1 4.6-5 6.1-2.9-1.5-5-3.4-5-6.1V3.9z" />
156
+ <path d="m5.5 7.9 1.7 1.7 3.4-3.4" />
157
+ </RailIcon>
158
+ );
159
  /** Sheet shortcuts — a small keyboard: a row of keys above a spacebar, not the padlock
160
  * "Your access" already wears (two authority glyphs in one rail would drift together). */
161
  const IconShortcuts = (
 
804
  const rail: Array<[SettingsSection, string, ReactNode]> = [
805
  ["account", "Account", IconAccount],
806
  ["scope", "Your access", IconAccess],
807
+ ["security", "Security", IconSecurity],
808
  // ⭐⭐ WAVE 52 · T19 (owner instruction 21) — NOT admin-gated, on the same footing as
809
  // `account` and `scope` immediately above: every user manages their own shortcut
810
  // preferences, and there is nothing behind this room a member's account cannot already do to
 
918
  `sheet/shortcuts.ts`'s own localStorage store directly and needs nothing passed
919
  in, because a keyboard preference is not server data. */}
920
  {active === "shortcuts" ? <ShortcutSettings /> : null}
921
+ {active === "security" ? <SecurityPane /> : null}
922
  {active === "external" ? <ExternalAccessPane /> : null}
923
  {active === "keychains" ? <KeychainPane /> : null}
924
  {active === "connectors" ? <ConnectorsPane /> : null}
web/src/settings/permsModel.ts CHANGED
@@ -40,6 +40,9 @@ import type { Field, FieldType, FilterTree } from "../customer-grid/types";
40
  export type SettingsSection =
41
  | "account"
42
  | "scope"
 
 
 
43
  /**
44
  * ⭐⭐ WAVE 52 (owner instruction 21, ruling R7) — SHEET SHORTCUTS: toggle any shortcut on or
45
  * off and rebind the eleven plain-Ctrl-letter ones. NOT admin-only — every user manages their
 
40
  export type SettingsSection =
41
  | "account"
42
  | "scope"
43
+ /** W57-T36 / R15: every user enrols their own factor, so every user needs
44
+ * this room. Like shortcuts, it is NOT admin-only; the session scopes it. */
45
+ | "security"
46
  /**
47
  * ⭐⭐ WAVE 52 (owner instruction 21, ruling R7) — SHEET SHORTCUTS: toggle any shortcut on or
48
  * off and rebind the eleven plain-Ctrl-letter ones. NOT admin-only — every user manages their
web/src/sheet/BindingEditor.tsx CHANGED
@@ -39,9 +39,10 @@
39
  import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
40
  import { fetchTopicRows, fetchWorkspace } from "../customer-grid/apiBridge";
41
  import type { SurfaceScope } from "../customer-grid/apiBridge";
 
42
  import { FieldTypeIcon } from "../customer-grid/icons";
43
  import { BodyPortal, OverlayProvider, useOverlayLayer } from "../customer-grid/OverlaySurface";
44
- import type { Field, FilterTree, Row } from "../customer-grid/types";
45
  import { choiceVocabulary, topicForScope } from "../customer-grid/types";
46
  import type { WindowSpec } from "../customer-grid/windows";
47
  import { normalizeWindow } from "../customer-grid/windows";
@@ -55,6 +56,14 @@ import { WindowPicker } from "../filter-kit/WindowPicker";
55
  import { useEscapeClose } from "../ui/useEscapeClose";
56
  import { previewCell } from "./sheetApi";
57
  import { bindingDisplay, bindingFilterClauses } from "./types";
 
 
 
 
 
 
 
 
58
 
59
  const AGGREGATES = [
60
  { fn: "sum", label: "Sum" },
@@ -97,10 +106,6 @@ const NUMERIC_ROLLUP_FNS = [
97
  * the field's `type` (the two live ones on `customer_data` are typed `currency` and `int`). */
98
  const isMetricField = (f: Field): boolean => Boolean(f.measure);
99
 
100
- /** ⭐ `custom`, not `measure`, identifies a Metric made in the table. `isMetricField` alone is the
101
- * trap: it includes exactly the user-created Metric columns the cell picker must exclude. */
102
- const isUserMetricField = (f: Field): boolean => isMetricField(f) && f.custom === true;
103
-
104
  /** ⭐ `custom`, not `measure`, separates supplied templates from table-made Metrics.
105
  * `isMetricField` alone is the trap because it includes both kinds. */
106
  const isTemplateMetricField = (f: Field): boolean => isMetricField(f) && f.custom !== true;
@@ -360,10 +365,21 @@ function savedViewOf(initial: Record<string, unknown> | null | undefined): {
360
  };
361
  }
362
 
363
- /** The `{id, name}` pairs a workspace payload offers, and nothing else off it. */
364
- function viewList(raw: unknown): { id: string; name: string }[] {
 
 
 
 
365
  if (!Array.isArray(raw)) return [];
366
- return (raw as { id: string; name: string }[]).map((v) => ({ id: v.id, name: v.name }));
 
 
 
 
 
 
 
367
  }
368
 
369
  // ══ ⭐⭐ W54-T31 (ruling R8; owner instructions 6 and 8) — THE AGGREGATE'S COLUMN LIST ═════════
@@ -436,9 +452,6 @@ function ColumnPickerDialog({
436
  });
437
 
438
  const offersTemplateMetric = offered.some(isTemplateMetricField);
439
- // ⛔ W56-T19 - A NARROWED LIST MUST SAY WHAT WAS WITHHELD. Without this cause, a database whose
440
- // only usable-looking Metrics were made here would present a silent empty picker as if it had none.
441
- const hasOnlyUnofferedUserMetrics = all.some(isUserMetricField) && !offersTemplateMetric;
442
 
443
  return (
444
  <BodyPortal>
@@ -541,9 +554,8 @@ function ColumnPickerDialog({
541
  </div>
542
  )}
543
 
544
- {/* ⛔ AN EMPTY LIST SAYS WHY (R16). The causes need different acts from the reader,
545
- and the user-Metric-only cause has its own honest explanation directly below. */}
546
- {shown.length === 0 && (offered.length > 0 || !hasOnlyUnofferedUserMetrics) && (
547
  <p className="sheet-pick-empty">
548
  {offered.length > 0
549
  ? "No column matches that search."
@@ -554,14 +566,6 @@ function ColumnPickerDialog({
554
  </p>
555
  )}
556
 
557
- {hasOnlyUnofferedUserMetrics && (
558
- <p className="sheet-pick-empty">
559
- This database&apos;s Metric columns were created here rather than supplied as templates,
560
- so they are not offered for a cell; a template metric is measured over the period this
561
- panel sets.
562
- </p>
563
- )}
564
-
565
  {/* ⭐ W56-T19, said where the choice is made: a template Metric is the one offered kind
566
  whose value is measured over the period the panel sets. */}
567
  {offersTemplateMetric && shown.length > 0 && (
@@ -633,6 +637,7 @@ export interface BindingEditorProps {
633
  export default function BindingEditor({
634
  workbookId, addr, databases, initial, onSave, onCancel,
635
  }: BindingEditorProps) {
 
636
  const [database, setDatabase] = useState<string>(
637
  String((initial?.database as string) ?? databases[0]?.key ?? ""),
638
  );
@@ -652,7 +657,9 @@ export default function BindingEditor({
652
  // built out of groups is not undercounted into reading as empty.
653
  const conditionCount = useMemo(() => countConditions(tree.nodes ?? []), [tree]);
654
  const [fields, setFields] = useState<Field[]>([]);
655
- const [views, setViews] = useState<{ id: string; name: string }[]>([]);
 
 
656
  // ⛔ THE NOTICE BELOW IS GATED ON THIS FLAG AND NOT ON `views.length`. Before the first answer
657
  // arrives the list is legitimately empty, and a notice keyed on emptiness would flash "that view
658
  // is gone" at every perfectly valid binding for as long as the fetch took.
@@ -726,6 +733,21 @@ export default function BindingEditor({
726
  migrated?.start ?? normalizePeriodStart("month", todayYm()),
727
  );
728
  const [locked, setLocked] = useState<boolean>(migrated?.locked ?? false);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
729
  const [periodRef, setPeriodRef] = useState<string>(migrated?.ref ?? "");
730
  // ⭐ C5 - THE TWO PERIOD SPELLINGS ARE SIBLINGS. The mode is seeded from the saved dialect so
731
  // opening and saving a rolling window cannot silently turn it into this month's calendar period.
@@ -793,6 +815,8 @@ export default function BindingEditor({
793
  const scope = scopeOf(database);
794
  setViewsLoaded(false);
795
  setOptionsResolved(false);
 
 
796
  // ⭐ W54-T36 — THE POOL BELONGS TO THE DATABASE THAT WAS OPEN. Switching database drops it, and
797
  // the rows effect below refetches only if the filter is still being used.
798
  setRawRows([]);
@@ -817,6 +841,7 @@ export default function BindingEditor({
817
  if (!live) return;
818
  if (ws) {
819
  setFields((ws.fields ?? []) as Field[]);
 
820
  setViews(viewList(ws.views));
821
  setUserOptions(ws.userOptions ?? []);
822
  setViewsLoaded(true);
@@ -829,6 +854,7 @@ export default function BindingEditor({
829
  }
830
  const list = viewList(fresh.views);
831
  setFields((fresh.fields ?? []) as Field[]);
 
832
  setViews(list);
833
  // ⚠ THE `user` FIELDS' VOCABULARY COMES OFF THIS ENVELOPE, not off the rows. It was read
834
  // from the rows payload with this as its fallback; the rows are no longer fetched here, so
@@ -902,22 +928,15 @@ export default function BindingEditor({
902
  return map;
903
  }, [fields, rawRows, userOptions]);
904
 
905
- // ⭐ THE PROJECT'S OWN PREDICATE, NOT A HAND-WRITTEN TYPE LIST. `isNumericType` is what the
906
- // filter kit already uses to decide numeric behaviour, so the columns this editor offers to SUM
907
- // are exactly the ones the filter engine treats as numbers. A local list would drift, and it was
908
- // wrong on its first attempt: the numeric family is `int` / `currency` / `pct`, and there is no
909
- // `"number"` in `FieldType` at all - tsc caught that before it could ship as an empty picker.
910
- // ⭐ W53-T13 — `canTotal` IS THE SECOND HALF OF THE SAME QUESTION. `isNumericType` says the
911
- // column behaves like a number; `canTotal` says this database holds a number to add up. Offering
912
- // a column that fails the second one hands back a refusal instead of a value, which is the exact
913
- // shape of the report this ticket answers.
914
- // ⛔ W56-T19 - METRICS MADE HERE ARE NOT TEMPLATE OFFERS. The `custom` flag is the separator;
915
- // testing `measure` alone would put every excluded user-created Metric straight back in the list.
916
  const numericFields = useMemo(
917
  () => fields.filter((f) => {
918
  // ⛔ DATE METRICS ARE EXCLUDED BY TYPE, never by a mutable label or key naming convention.
919
  if (isMetricField(f) && (f.type === "date" || f.type === "created_time")) return false;
920
- return isNumericType(f.type) && canTotal(f) && !isUserMetricField(f);
921
  }),
922
  [fields],
923
  );
@@ -954,9 +973,22 @@ export default function BindingEditor({
954
  * in this narrow panel without throwing that explanation away.
955
  */
956
  const filterClauseOffers = useMemo(() => {
 
 
 
 
 
 
 
 
 
 
 
 
 
957
  const fieldsByKey = new Map(fields.map((candidate) => [candidate.key, candidate]));
958
  const steppableKeys = new Set(dragDownFields.map((candidate) => candidate.key));
959
- return bindingFilterClauses(tree).map((clause) => {
960
  const clauseField = fieldsByKey.get(clause.colId);
961
  const label = clauseField?.label?.trim() || clause.colId;
962
  let reason = "";
@@ -986,16 +1018,15 @@ export default function BindingEditor({
986
  shortReason,
987
  };
988
  });
989
- }, [tree, fields, dragDownFields]);
990
 
991
  /**
992
  * ⛔ A SAVED DRIVER STAYS VISIBLE WHEN THE CURRENT OFFER SET NO LONGER CARRIES IT. Letting the
993
  * native select fall back to its first row would paint "Keep this filter" and silently overwrite
994
  * the saved choice on Save, the same narrowing failure shape as D-660.
995
  */
996
- const savedDragDriverMissing = Boolean(downField) && (scopeKind === "view"
997
- ? !dragDownFields.some((candidate) => candidate.key === downField)
998
- : !filterClauseOffers.some((clause) => clause.colId === downField));
999
 
1000
  /**
1001
  * ⭐⭐ W50-T21 (owner instruction 24: *"Sheet column picker (sum/count) shows the Field icons."*)
@@ -1030,13 +1061,13 @@ export default function BindingEditor({
1030
  const chosenField = useMemo(() => fields.find((f) => f.key === field), [fields, field]);
1031
  /** Metric columns step their period; every other aggregate steps one chosen filter driver. */
1032
  const chosenIsMetric = Boolean(chosenField && isMetricField(chosenField));
1033
- const chosenIsTemplateMetric = Boolean(chosenField && isTemplateMetricField(chosenField));
1034
 
1035
- // ⭐⭐ W56-T19 - A TEMPLATE METRIC HAS NO ALL-TIME READING. Raising the existing switch in an
1036
  // effect reveals the period controls immediately, while the ready gate below covers this render.
1037
  useEffect(() => {
1038
- if (chosenIsTemplateMetric) setPeriodOn(true);
1039
- }, [chosenIsTemplateMetric]);
1040
 
1041
  /** The database's own label, which the column list's heading names. Two databases can both
1042
  * carry a column called "Total", and the heading is where that ambiguity is answered. */
@@ -1108,7 +1139,7 @@ export default function BindingEditor({
1108
  // Save taken then would write back a binding assembled from a list nobody had seen yet.
1109
  const ready = optionsResolved && Boolean(database) && (fn === "count" || Boolean(field))
1110
  && (scopeKind === "filter" || Boolean(viewId))
1111
- && (!chosenIsTemplateMetric || periodOn);
1112
 
1113
  const { y: startYear, m: startMonth } = splitYm(start);
1114
  const thisYear = new Date().getFullYear();
@@ -1159,441 +1190,527 @@ export default function BindingEditor({
1159
  {!optionsResolved && <BindingSkeleton addr={addr} />}
1160
  {optionsResolved && (
1161
  <>
1162
- <label className="sheet-field">
1163
- <span>Database</span>
1164
- <select value={database} onChange={(e) => setDatabase(e.target.value)}>
1165
- {databases.map((d) => <option key={d.key} value={d.key}>{d.label}</option>)}
1166
- </select>
1167
- </label>
1168
-
1169
- <div className="sheet-field-row">
1170
- <label className="sheet-field">
1171
- <span>Aggregate</span>
1172
- <select value={fn} onChange={(e) => setFn(e.target.value)}>
1173
- {AGGREGATES.map((a) => <option key={a.fn} value={a.fn}>{a.label}</option>)}
1174
- </select>
1175
- </label>
1176
- {/* Count takes no column, and offering one would suggest count(column), which skips
1177
- blanks and answers a smaller number than the person meant. */}
1178
- {fn !== "count" && (
1179
- <div className="sheet-field sheet-field--pick">
1180
- <span id="sheet-col-pick-label">Column</span>
1181
- {/* ⭐⭐ W54-T31 (R8) — THE CONTROL SHOWS WHAT IS CHOSEN AND OPENS THE LIST; IT IS
1182
- NOT THE LIST. `cg-select cg-fsel` is the shipped footprint every replaced
1183
- `<select>` in this product already wears, so the Column line shares its height
1184
- and its baseline with the Aggregate select above it rather than introducing a
1185
- new control shape. The three states are `FieldSelect`'s own: unset reads as a
1186
- prompt, a resolved column shows its mark and its name, and a column this
1187
- database cannot offer shows its raw key in the amber `is-missing` slot instead
1188
- of a plausible substitute. */}
1189
  <button
 
1190
  type="button"
1191
- className={"cg-select cg-fsel sheet-col-open"
1192
- + (chosenField ? "" : field ? " is-missing" : " is-empty")}
1193
- aria-haspopup="dialog"
1194
- aria-expanded={colPickerOpen}
1195
- aria-labelledby="sheet-col-pick-label"
1196
- title={chosenField ? chosenField.key : undefined}
1197
- onClick={() => setColPickerOpen(true)}
1198
  >
1199
- {chosenField ? (
1200
- <FieldTypeIcon
1201
- type={isMetricField(chosenField) ? "measure" : chosenField.type}
1202
- title={isMetricField(chosenField) ? "Metric" : chosenField.type}
1203
- />
1204
- ) : (
1205
- // No mark, but the SLOT stays, so the name sits in the same column whether or
1206
- // not anything is chosen yet.
1207
- <span className="cg-fsel-nomark" aria-hidden />
1208
  )}
1209
- <span className="cg-fsel-label">
1210
- {chosenField?.label ?? (field || "Choose a column")}
1211
- </span>
1212
- <svg className="cg-fsel-caret" width="10" height="10" viewBox="0 0 16 16"
1213
- fill="none" aria-hidden>
1214
- <path d="M4 6l4 4 4-4" stroke="currentColor" strokeWidth="1.6"
1215
- strokeLinecap="round" strokeLinejoin="round" />
1216
- </svg>
1217
- </button>
1218
- {/* ⛔⛔ MOUNTED ONLY WHILE OPEN, which is what orders Escape. See the block above
1219
- `ColumnPickerDialog`: the editor's own Escape claim was pushed at mount, this
1220
- one is pushed on open, and unmounting hands the key straight back. */}
1221
- {colPickerOpen && (
1222
- <SheetColumnPicker
1223
- addr={addr}
1224
- aggregateNoun={AGGREGATE_NOUN[fn] ?? "total"}
1225
- databaseLabel={databaseLabel}
1226
- shown={shownFields}
1227
- offered={numericFields}
1228
- all={fields}
1229
- chosen={field}
1230
- query={fieldQuery}
1231
- onQuery={setFieldQuery}
1232
- onPick={(key) => {
1233
- setField(key);
1234
- setColPickerOpen(false);
1235
- }}
1236
- onClose={() => setColPickerOpen(false)}
1237
- />
1238
- )}
1239
- {/* ⭐⭐ THE BIND TIME REFUSAL, SURFACED WHERE THE PERSON CAN ACT ON IT. The server
1240
- refuses this column by name (`field_not_aggregable`), but only once a number is
1241
- asked for; saying it here means the choice is corrected before a save. */}
1242
- {savedFieldUnavailable && (
1243
- <p className="sheet-notice" role="alert">
1244
- {`The saved column ${field} cannot be totalled on this database. `
1245
- + "Pick a column from the list, or count the records instead."}
1246
- </p>
1247
- )}
1248
- </div>
1249
- )}
1250
- </div>
1251
-
1252
- <fieldset className="sheet-scope">
1253
- <legend>Rows to include</legend>
1254
- <label className="sheet-radio">
1255
- <input type="radio" checked={scopeKind === "view"}
1256
- onChange={() => setScopeKind("view")} />
1257
- <span>A saved view</span>
1258
- </label>
1259
- {scopeKind === "view" && (
1260
- <select value={viewId} onChange={(e) => setViewId(e.target.value)}>
1261
- <option value="">Choose a view</option>
1262
- {views.map((v) => <option key={v.id} value={v.id}>{v.name}</option>)}
1263
- </select>
1264
- )}
1265
- {/* ⭐ W53-T12 — SAID HERE, THE MOMENT THE LIST RESOLVES, rather than as a refusal after
1266
- a save or a refresh. `sheet-notice` with `role="alert"` is this panel's established
1267
- inline shape, so the sentence lands where the choice is made. */}
1268
- {savedViewMissing && (
1269
- <p className="sheet-notice" role="alert">
1270
- {`The saved view ${savedView.name || savedView.id} is not available any more. `
1271
- + "Pick a view that still exists, or build a filter here."}
1272
- </p>
1273
- )}
1274
- <label className="sheet-radio">
1275
- <input type="radio" checked={scopeKind === "filter"}
1276
- onChange={() => setScopeKind("filter")} />
1277
- <span>A filter I build here</span>
1278
- </label>
1279
- {/* ⭐⭐ W53-T15 (ruling R8) — A DOOR, NOT THE BUILDER. The same shared panel now opens
1280
- in a centred dialog: this column is `flex: 0 0 380px` and a condition row cannot fit
1281
- in it, so four conditions could only be reached by scrolling sideways. The button
1282
- says how many conditions the cell already carries, because the builder that used to
1283
- say so is now behind it. */}
1284
- {scopeKind === "filter" && (
1285
- <>
1286
- <button
1287
- type="button"
1288
- className="sheet-action"
1289
- style={{ alignSelf: "flex-start" }}
1290
- aria-haspopup="dialog"
1291
- aria-expanded={filterPopupOpen}
1292
- onClick={() => setFilterPopupOpen(true)}
1293
- >
1294
- {conditionCount === 0
1295
- ? "Build a filter"
1296
- : `Edit filter (${conditionCount === 1
1297
- ? "1 condition" : `${conditionCount} conditions`})`}
1298
  </button>
1299
- {/* ⛔⛔ MOUNTED ONLY WHILE OPEN, and that is what orders Escape correctly rather
1300
- than a flag inside the dialog. `useOverlayLayer` claims Escape as soon as it
1301
- runs and `ui/useEscapeClose` gives the key to the LAST entry pushed, so a
1302
- dialog mounted with the panel would have claimed Escape from the moment this
1303
- editor opened. Mounting it here, later in time, puts it ABOVE this panel's own
1304
- claim (pushed at mount, a few hundred lines up) and unmounting it hands Escape
1305
- straight back, so one press closes the filter and the next closes the panel. */}
1306
- {filterPopupOpen && (
1307
- <SheetFilterPopup
1308
- addr={addr}
1309
- fields={fields}
1310
- filters={tree}
1311
- onChange={setTree}
1312
- statusValues={statusValues}
1313
- onClose={() => setFilterPopupOpen(false)}
1314
- />
1315
- )}
1316
- </>
1317
- )}
1318
- </fieldset>
1319
-
1320
- {/* ══ R9: THE PERIOD ══════════════════════════════════════════════════════════════════ */}
1321
- <fieldset className="sheet-scope sheet-period">
1322
- <legend>Period</legend>
1323
-
1324
- {/* ⭐⭐ W53-T16 / D-660 - WHETHER THIS CELL HAS A PERIOD AT ALL, said out loud. The
1325
- pickers below show a unit and a month whether or not the cell is using them, so
1326
- without this switch an all-time total read as "September 2026" on screen and the next
1327
- save made that true. It is also the only way back to all time once a period is set. */}
1328
- <div className="sheet-period-lock">
1329
- <button
1330
- type="button"
1331
- role="switch"
1332
- aria-checked={periodOn}
1333
- aria-disabled={chosenIsTemplateMetric}
1334
- disabled={chosenIsTemplateMetric}
1335
- className={"sheet-lock-toggle" + (periodOn ? " is-on" : "")}
1336
- onClick={() => setPeriodOn((v) => !v)}
1337
- >
1338
- <span className="sheet-lock-dot" aria-hidden />
1339
- <span>Limit this cell to a period</span>
1340
- </button>
1341
- <p className="sheet-period-note">
1342
- {chosenIsTemplateMetric
1343
- ? "The period is required because this column is measured over one."
1344
- : (periodOn
1345
- ? "Only rows dated inside the period below are counted."
1346
- : "All time, so every row this cell's filter matches is counted whatever its date. "
1347
- + "Saving leaves it that way.")}
1348
- </p>
1349
- </div>
1350
-
1351
- {periodOn && (
1352
- <>
1353
- {/* ⭐ C5 - THE MODE LABELS SAY WHAT EACH CHOICE DOES. Internal dialect names
1354
- would make the reader guess which one can step and which one follows today. */}
1355
- <label className="sheet-field">
1356
- <span>How to choose the period</span>
1357
- <select
1358
- value={periodMode}
1359
- aria-label="How this period is chosen"
1360
- onChange={(e) => setPeriodMode(e.target.value as "calendar" | "window")}
1361
- >
1362
- <option value="calendar">Pick a calendar period by year and month</option>
1363
- <option value="window">Use a rolling window such as year to date</option>
1364
- </select>
1365
- </label>
1366
-
1367
- {periodMode === "window" ? (
1368
  <label className="sheet-field">
1369
- <span>Window</span>
1370
- <WindowPicker window={windowSpec} onWindow={setWindowSpec} />
 
 
1371
  </label>
1372
- ) : (
1373
- <>
1374
  <label className="sheet-field">
1375
- <span>Unit</span>
1376
- <select
1377
- value={unit}
1378
- aria-label="Period unit"
1379
- onChange={(e) => {
1380
- const next = e.target.value as PeriodUnit;
1381
- setUnit(next);
1382
- // Re-seat the start on the new unit's first month, or the pair stops naming one
1383
- // period: `2026-08` under `quarter` is not a quarter anybody can compile.
1384
- setStart(normalizePeriodStart(next, start));
1385
- }}
1386
- >
1387
- {PERIOD_UNITS.map((u) => <option key={u.unit} value={u.unit}>{u.label}</option>)}
1388
  </select>
1389
  </label>
1390
-
1391
- <div className="sheet-field-row">
1392
- <label className="sheet-field">
1393
- <span>Year</span>
1394
- <select
1395
- value={String(startYear)}
1396
- aria-label="Period year"
1397
- onChange={(e) => setYear(Number(e.target.value))}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1398
  >
1399
- {years.map((y) => <option key={y} value={String(y)}>{y}</option>)}
1400
- </select>
1401
- </label>
1402
- {unit === "month" && (
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1403
  <label className="sheet-field">
1404
- <span>Month</span>
1405
  <select
1406
- value={String(startMonth)}
1407
- aria-label="Period month"
1408
- onChange={(e) => setMonthOfYear(Number(e.target.value))}
1409
  >
1410
- {MONTH_NAMES.map((name, i) => (
1411
- <option key={name} value={String(i + 1)}>{name}</option>
1412
- ))}
1413
  </select>
1414
  </label>
1415
- )}
1416
- {unit === "quarter" && (
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1417
  <label className="sheet-field">
1418
- <span>Quarter</span>
1419
  <select
1420
- value={String(Math.floor((startMonth - 1) / 3) + 1)}
1421
- aria-label="Period quarter"
1422
- onChange={(e) => setMonthOfYear(1 + 3 * (Number(e.target.value) - 1))}
 
 
 
 
1423
  >
1424
- {[1, 2, 3, 4].map((q) => <option key={q} value={String(q)}>{`Q${q}`}</option>)}
 
1425
  </select>
1426
  </label>
1427
- )}
1428
- </div>
1429
-
1430
- {/* W56-T21 (owner instruction 13) - THE QUICK PICKS ARE GONE. Unit, year and
1431
- month-or-quarter already reach every period the This and Last buttons
1432
- could, so a second control for the same value was a second way to say one
1433
- thing. `normalizePeriodStart` still normalises all three selects, and
1434
- `shiftPeriodStart` stays exported for the drag arithmetic. */}
1435
-
1436
- {/* ⭐ R9's LOCK. A switch rather than a checkbox: it has two states with names, and the
1437
- sentence under it says what each one costs when the cell is copied. */}
1438
- {chosenIsMetric ? (
1439
- <div className="sheet-period-lock">
1440
- <button
1441
- type="button"
1442
- role="switch"
1443
- aria-checked={locked}
1444
- className={"sheet-lock-toggle" + (locked ? " is-on" : "")}
1445
- onClick={() => {
1446
- const next = !locked;
1447
- setLocked(next);
1448
- setAcross(next ? "none" : "period");
1449
- }}
1450
- >
1451
- <span className="sheet-lock-dot" aria-hidden />
1452
- <span>Lock this period</span>
1453
- </button>
1454
  <p className="sheet-period-note">
1455
- {locked
1456
- ? "Locked, so any copy of this cell keeps this period."
1457
- : `Not locked, so a stepped copy moves by one ${UNIT_NOUN[unit]} per cell. `
1458
- + "Right and down move forward. Left and up move backward."}
1459
  </p>
1460
- </div>
1461
- ) : (
 
 
 
 
1462
  <p className="sheet-period-note">
1463
- This period stays fixed when copied. The filter clause below is what
1464
- changes.
1465
  </p>
1466
  )}
1467
 
1468
- {/* ⭐ "Use a cell" STAYS A LINK (R9). It reveals the A1 input rather than replacing the
1469
- picker, so the ordinary reader never meets a cell reference and the person who wants
1470
- one is one click away from it. */}
1471
- {!refOpen && (
1472
- <button
1473
- type="button"
1474
- className="sheet-period-link"
1475
- onClick={() => setRefOpen(true)}
 
 
 
 
 
 
1476
  >
1477
- Use a cell
1478
- </button>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1479
  )}
1480
- {refOpen && (
1481
- <label className="sheet-field">
1482
- <span>Period from a cell</span>
1483
- <input
1484
- type="text"
1485
- value={periodRef}
1486
- onChange={(e) => setPeriodRef(e.target.value)}
1487
- placeholder="$B$1"
1488
- />
1489
- </label>
1490
  )}
1491
- </>
1492
- )}
1493
- </>
1494
- )}
1495
- </fieldset>
1496
-
1497
- {/* ══ R10: THE DRAG RULES ═════════════════════════════════════════════════════════════ */}
1498
- <fieldset className="sheet-scope sheet-drag">
1499
- <legend>When copied</legend>
1500
-
1501
- {chosenIsMetric && periodOn && periodMode === "calendar" && (
1502
- <>
1503
- <label className="sheet-field">
1504
- <span>Period</span>
1505
- <select
1506
- value={!locked && across === "period" ? "period" : "none"}
1507
- aria-label="Period step when copied"
1508
- onChange={(e) => {
1509
- const step = e.target.value === "period";
1510
- setAcross(step ? "period" : "none");
1511
- setLocked(!step);
1512
- }}
1513
- >
1514
- <option value="period">{`Step by ${UNIT_NOUN[unit]}`}</option>
1515
- <option value="none">Keep this period</option>
1516
- </select>
1517
- </label>
1518
- <p className="sheet-period-note">
1519
- Right and down move forward. Left and up move backward.
1520
- </p>
1521
- </>
1522
- )}
1523
-
1524
- {/* ⛔ C5 - A ROLLING WINDOW HAS NO START TO SHIFT. Offering the calendar step here
1525
- would promise an action `dragBoundCell` cannot perform. */}
1526
- {periodOn && periodMode === "window" && (
1527
- <p className="sheet-period-note">
1528
- A rolling window is measured from today, so every copy of this cell answers the
1529
- same window. Use a calendar period when the period should step as the cell is copied.
1530
- </p>
1531
- )}
1532
-
1533
- {/* ⚠ AN ALL-TIME METRIC SAYS WHY NO PERIOD PICKER IS PRESENT. Without this note the
1534
- absent control looks like a loading or configuration failure. */}
1535
- {chosenIsMetric && !periodOn && (
1536
- <p className="sheet-period-note">
1537
- This metric is all time, so copied cells keep the same all-time period.
1538
- </p>
1539
- )}
1540
-
1541
- <label className="sheet-field">
1542
- <span>Filter clause</span>
1543
- <select
1544
- value={downField}
1545
- aria-label="Filter clause when copied"
1546
- onChange={(e) => setDownField(e.target.value)}
1547
- >
1548
- <option value="">Keep this filter</option>
1549
- {/* ⛔ A SAVED VIEW'S FILTER IS NOT LOADED IN THIS PANEL. Restoring the database's
1550
- steppable columns for this branch prevents the working driver picker from
1551
- disappearing while materialisation continues to resolve the real view filter. */}
1552
- {scopeKind === "view"
1553
- ? dragDownFields.map((f) => (
1554
- <option key={f.key} value={f.key}>{`Step by ${f.label}`}</option>
1555
- ))
1556
- : filterClauseOffers.map((clause) => (
1557
- <option
1558
- key={clause.colId}
1559
- value={clause.colId}
1560
- disabled={!clause.canStep}
1561
- title={clause.canStep ? undefined : clause.reason}
1562
- >
1563
- {clause.canStep
1564
- ? `Step ${clause.label}, now ${clause.value || "no value"}`
1565
- : `${clause.label} cannot step: ${clause.shortReason}`}
1566
- </option>
1567
- ))}
1568
- {savedDragDriverMissing && (
1569
- <option value={downField}>
1570
- {`${downField}: not in this cell's filter any more`}
1571
- </option>
1572
- )}
1573
- </select>
1574
- </label>
1575
- {savedDragDriverMissing && (
1576
- <p className="sheet-notice" role="alert">
1577
- The saved driver is not in this cell&apos;s filter, so copying this cell will not
1578
- change it. Pick a driver that is in the filter, or keep the filter.
1579
- </p>
1580
- )}
1581
- {scopeKind === "view" ? (
1582
- <p className="sheet-period-note">
1583
- These rows come from a saved view, so the view&apos;s filter clauses cannot be listed
1584
- here. This database&apos;s steppable columns are offered instead. A driver that is not
1585
- in the view&apos;s filter changes nothing, and the sheet says so when dragged.
1586
- </p>
1587
- ) : filterClauseOffers.length === 0 ? (
1588
- <p className="sheet-period-note">
1589
- This cell has no filter clauses to step.
1590
- </p>
1591
- ) : (
1592
- <p className="sheet-period-note">
1593
- Right and down choose later options. Left and up choose earlier options.
1594
- </p>
1595
- )}
1596
- </fieldset>
1597
 
1598
  {/* ⛔⛔ W53-T16 (owner instruction 13) - THE FOUR SENTENCE SUMMARY IS DELETED, NOT HIDDEN.
1599
  It restated the period, the lock and the two drag rules that the controls immediately
@@ -1613,15 +1730,17 @@ export default function BindingEditor({
1613
  )}
1614
  </div>
1615
 
 
 
1616
  <div className="sheet-binding-actions">
1617
- <button type="button" className="sheet-action" onClick={runPreview} disabled={!ready}>
1618
  Preview
1619
  </button>
1620
- <button type="button" className="sheet-action" onClick={() => onSave(binding)}
1621
  disabled={!ready}>
1622
  Save
1623
  </button>
1624
- <button type="button" className="sheet-action" onClick={onCancel}>
1625
  Cancel
1626
  </button>
1627
  </div>
 
39
  import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
40
  import { fetchTopicRows, fetchWorkspace } from "../customer-grid/apiBridge";
41
  import type { SurfaceScope } from "../customer-grid/apiBridge";
42
+ import { FieldSelectButton } from "../customer-grid/FieldSelect";
43
  import { FieldTypeIcon } from "../customer-grid/icons";
44
  import { BodyPortal, OverlayProvider, useOverlayLayer } from "../customer-grid/OverlaySurface";
45
+ import type { Field, FilterTree, GridWorkspace, Measure, Row, SavedView } from "../customer-grid/types";
46
  import { choiceVocabulary, topicForScope } from "../customer-grid/types";
47
  import type { WindowSpec } from "../customer-grid/windows";
48
  import { normalizeWindow } from "../customer-grid/windows";
 
56
  import { useEscapeClose } from "../ui/useEscapeClose";
57
  import { previewCell } from "./sheetApi";
58
  import { bindingDisplay, bindingFilterClauses } from "./types";
59
+ import "../styles/wave57/binding-actions.css";
60
+
61
+ const BINDING_SECTIONS = [
62
+ { key: "data", label: "Data" },
63
+ { key: "rows", label: "Rows" },
64
+ { key: "period", label: "Period" },
65
+ { key: "copied", label: "When copied" },
66
+ ] as const;
67
 
68
  const AGGREGATES = [
69
  { fn: "sum", label: "Sum" },
 
106
  * the field's `type` (the two live ones on `customer_data` are typed `currency` and `int`). */
107
  const isMetricField = (f: Field): boolean => Boolean(f.measure);
108
 
 
 
 
 
109
  /** ⭐ `custom`, not `measure`, separates supplied templates from table-made Metrics.
110
  * `isMetricField` alone is the trap because it includes both kinds. */
111
  const isTemplateMetricField = (f: Field): boolean => isMetricField(f) && f.custom !== true;
 
365
  };
366
  }
367
 
368
+ type BindingView = Pick<SavedView, "id" | "name"> & {
369
+ config: Pick<SavedView["config"], "filterConj" | "filters">;
370
+ };
371
+
372
+ /** Workspace view names and the filter clauses a copied cell can step. */
373
+ function viewList(raw: unknown): BindingView[] {
374
  if (!Array.isArray(raw)) return [];
375
+ return (raw as GridWorkspace["views"]).map((v) => ({
376
+ id: v.id,
377
+ name: v.name,
378
+ config: {
379
+ filterConj: v.config?.filterConj === "or" ? "or" : "and",
380
+ filters: Array.isArray(v.config?.filters) ? v.config.filters : [],
381
+ },
382
+ }));
383
  }
384
 
385
  // ══ ⭐⭐ W54-T31 (ruling R8; owner instructions 6 and 8) — THE AGGREGATE'S COLUMN LIST ═════════
 
452
  });
453
 
454
  const offersTemplateMetric = offered.some(isTemplateMetricField);
 
 
 
455
 
456
  return (
457
  <BodyPortal>
 
554
  </div>
555
  )}
556
 
557
+ {/* AN EMPTY LIST SAYS WHY (R16). The causes need different acts from the reader. */}
558
+ {shown.length === 0 && (
 
559
  <p className="sheet-pick-empty">
560
  {offered.length > 0
561
  ? "No column matches that search."
 
566
  </p>
567
  )}
568
 
 
 
 
 
 
 
 
 
569
  {/* ⭐ W56-T19, said where the choice is made: a template Metric is the one offered kind
570
  whose value is measured over the period the panel sets. */}
571
  {offersTemplateMetric && shown.length > 0 && (
 
637
  export default function BindingEditor({
638
  workbookId, addr, databases, initial, onSave, onCancel,
639
  }: BindingEditorProps) {
640
+ const [activeSection, setActiveSection] = useState<typeof BINDING_SECTIONS[number]["key"]>("data");
641
  const [database, setDatabase] = useState<string>(
642
  String((initial?.database as string) ?? databases[0]?.key ?? ""),
643
  );
 
657
  // built out of groups is not undercounted into reading as empty.
658
  const conditionCount = useMemo(() => countConditions(tree.nodes ?? []), [tree]);
659
  const [fields, setFields] = useState<Field[]>([]);
660
+ const [measures, setMeasures] = useState<Measure[]>([]);
661
+ const [measureNotice, setMeasureNotice] = useState("");
662
+ const [views, setViews] = useState<BindingView[]>([]);
663
  // ⛔ THE NOTICE BELOW IS GATED ON THIS FLAG AND NOT ON `views.length`. Before the first answer
664
  // arrives the list is legitimately empty, and a notice keyed on emptiness would flash "that view
665
  // is gone" at every perfectly valid binding for as long as the fetch took.
 
733
  migrated?.start ?? normalizePeriodStart("month", todayYm()),
734
  );
735
  const [locked, setLocked] = useState<boolean>(migrated?.locked ?? false);
736
+ // ⛔⛔ W57-T17 - THE DATABASE IS SEEDED AT MOUNT OUT OF A LIST THAT ARRIVES LATER, AND AN EMPTY
737
+ // SEED NEVER HEALED. `databases` is fetched by `SheetPage` from `/api/v1/nav`; a panel opened
738
+ // before that answer lands seeds `database` to `""`, and nothing re-seeds it. A `<select>` whose
739
+ // value matches no option paints its FIRST option, so the panel then SHOWED "Odoo customers"
740
+ // while `database` was empty: `scopeOf("")` is null, the workspace effect takes its no-door
741
+ // branch, and every list in the panel is legitimately empty for a database the reader can see
742
+ // named above them. Observed on a lane screenshot, where the column list read "Fields on to take
743
+ // the sum over" with `databaseLabel` blank and "This database has no number column to total."
744
+ //
745
+ // ⭐ IT ONLY EVER FILLS AN EMPTY VALUE, which is what makes it safe beside the seed-once rule
746
+ // the block above states: a database the person chose is never overwritten, and neither is one
747
+ // read off `initial`. The condition can only be true before any choice has been made.
748
+ useEffect(() => {
749
+ if (!database && databases.length > 0) setDatabase(databases[0].key);
750
+ }, [database, databases]);
751
  const [periodRef, setPeriodRef] = useState<string>(migrated?.ref ?? "");
752
  // ⭐ C5 - THE TWO PERIOD SPELLINGS ARE SIBLINGS. The mode is seeded from the saved dialect so
753
  // opening and saving a rolling window cannot silently turn it into this month's calendar period.
 
815
  const scope = scopeOf(database);
816
  setViewsLoaded(false);
817
  setOptionsResolved(false);
818
+ setMeasures([]);
819
+ setMeasureNotice("");
820
  // ⭐ W54-T36 — THE POOL BELONGS TO THE DATABASE THAT WAS OPEN. Switching database drops it, and
821
  // the rows effect below refetches only if the filter is still being used.
822
  setRawRows([]);
 
841
  if (!live) return;
842
  if (ws) {
843
  setFields((ws.fields ?? []) as Field[]);
844
+ setMeasures(ws.measures ?? []);
845
  setViews(viewList(ws.views));
846
  setUserOptions(ws.userOptions ?? []);
847
  setViewsLoaded(true);
 
854
  }
855
  const list = viewList(fresh.views);
856
  setFields((fresh.fields ?? []) as Field[]);
857
+ setMeasures(fresh.measures ?? []);
858
  setViews(list);
859
  // ⚠ THE `user` FIELDS' VOCABULARY COMES OFF THIS ENVELOPE, not off the rows. It was read
860
  // from the rows payload with this as its fallback; the rows are no longer fetched here, so
 
928
  return map;
929
  }, [fields, rawRows, userOptions]);
930
 
931
+ // Offer every numeric column this database can total, including Metrics created in the app.
932
+ // `isNumericType` checks numeric behaviour and `canTotal` checks whether the database can
933
+ // aggregate the column. Date Metrics stay excluded; the server still refuses by name if
934
+ // these client checks ever disagree with it.
 
 
 
 
 
 
 
935
  const numericFields = useMemo(
936
  () => fields.filter((f) => {
937
  // ⛔ DATE METRICS ARE EXCLUDED BY TYPE, never by a mutable label or key naming convention.
938
  if (isMetricField(f) && (f.type === "date" || f.type === "created_time")) return false;
939
+ return isNumericType(f.type) && canTotal(f);
940
  }),
941
  [fields],
942
  );
 
973
  * in this narrow panel without throwing that explanation away.
974
  */
975
  const filterClauseOffers = useMemo(() => {
976
+ // ⭐⭐ W57-T20 (ruling R6) — ONE OFFER LIST FOR BOTH SCOPES, and the saved-view branch is new.
977
+ // The panel used to print "the view's filter clauses cannot be listed here" and fall back to
978
+ // the database's steppable COLUMNS, which is a different question and offered drivers that
979
+ // change nothing. The refusal was false: `DrillModal.tsx` reads the same view's filter off the
980
+ // same workspace envelope this panel already fetches, and `viewList` now keeps it. So a
981
+ // view-scoped cell offers the VIEW's own clauses, which is exactly what a copy of it will
982
+ // carry: `bindingRefs.ts::materializeLocalViewBinding` turns the copy into a build-here filter
983
+ // seeded from that tree, and `stepBindingFilter` steps the clause chosen here.
984
+ const selectedView = scopeKind === "view" ? views.find((v) => v.id === viewId) : undefined;
985
+ const clauseTree: FilterTree = scopeKind === "filter" ? tree : {
986
+ conj: selectedView?.config.filterConj ?? "and",
987
+ nodes: selectedView?.config.filters ?? [],
988
+ };
989
  const fieldsByKey = new Map(fields.map((candidate) => [candidate.key, candidate]));
990
  const steppableKeys = new Set(dragDownFields.map((candidate) => candidate.key));
991
+ return bindingFilterClauses(clauseTree).map((clause) => {
992
  const clauseField = fieldsByKey.get(clause.colId);
993
  const label = clauseField?.label?.trim() || clause.colId;
994
  let reason = "";
 
1018
  shortReason,
1019
  };
1020
  });
1021
+ }, [scopeKind, viewId, views, tree, fields, dragDownFields]);
1022
 
1023
  /**
1024
  * ⛔ A SAVED DRIVER STAYS VISIBLE WHEN THE CURRENT OFFER SET NO LONGER CARRIES IT. Letting the
1025
  * native select fall back to its first row would paint "Keep this filter" and silently overwrite
1026
  * the saved choice on Save, the same narrowing failure shape as D-660.
1027
  */
1028
+ const savedDragDriverMissing = Boolean(downField)
1029
+ && !filterClauseOffers.some((clause) => clause.colId === downField);
 
1030
 
1031
  /**
1032
  * ⭐⭐ W50-T21 (owner instruction 24: *"Sheet column picker (sum/count) shows the Field icons."*)
 
1061
  const chosenField = useMemo(() => fields.find((f) => f.key === field), [fields, field]);
1062
  /** Metric columns step their period; every other aggregate steps one chosen filter driver. */
1063
  const chosenIsMetric = Boolean(chosenField && isMetricField(chosenField));
1064
+ const periodClauseLabel = `Period of ${chosenField?.label || chosenField?.key || field}`;
1065
 
1066
+ // Every Metric needs a period. Raising the existing switch in an
1067
  // effect reveals the period controls immediately, while the ready gate below covers this render.
1068
  useEffect(() => {
1069
+ if (chosenIsMetric) setPeriodOn(true);
1070
+ }, [chosenIsMetric]);
1071
 
1072
  /** The database's own label, which the column list's heading names. Two databases can both
1073
  * carry a column called "Total", and the heading is where that ambiguity is answered. */
 
1139
  // Save taken then would write back a binding assembled from a list nobody had seen yet.
1140
  const ready = optionsResolved && Boolean(database) && (fn === "count" || Boolean(field))
1141
  && (scopeKind === "filter" || Boolean(viewId))
1142
+ && (!chosenIsMetric || periodOn);
1143
 
1144
  const { y: startYear, m: startMonth } = splitYm(start);
1145
  const thisYear = new Date().getFullYear();
 
1190
  {!optionsResolved && <BindingSkeleton addr={addr} />}
1191
  {optionsResolved && (
1192
  <>
1193
+ <div className="sheet-binding-body">
1194
+ <nav className="sheet-binding-rail" aria-label="Cell database sections">
1195
+ {BINDING_SECTIONS.map(({ key, label }) => (
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1196
  <button
1197
+ key={key}
1198
  type="button"
1199
+ className={"sheet-binding-rail-item" + (activeSection === key ? " is-active" : "")}
1200
+ aria-current={activeSection === key ? "page" : undefined}
1201
+ onClick={() => setActiveSection(key)}
 
 
 
 
1202
  >
1203
+ {label}
1204
+ {key === "period" && chosenIsMetric && !periodOn && (
1205
+ <>{" "}<span className="sheet-binding-rail-required">Required</span></>
 
 
 
 
 
 
1206
  )}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1207
  </button>
1208
+ ))}
1209
+ </nav>
1210
+ <div className="sheet-binding-section" data-section={activeSection}>
1211
+ {activeSection === "data" && (
1212
+ <>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1213
  <label className="sheet-field">
1214
+ <span>Database</span>
1215
+ <select value={database} onChange={(e) => setDatabase(e.target.value)}>
1216
+ {databases.map((d) => <option key={d.key} value={d.key}>{d.label}</option>)}
1217
+ </select>
1218
  </label>
1219
+
1220
+ <div className="sheet-field-row">
1221
  <label className="sheet-field">
1222
+ <span>Aggregate</span>
1223
+ <select value={fn} onChange={(e) => {
1224
+ setFn(e.target.value);
1225
+ setMeasureNotice("");
1226
+ }}>
1227
+ {AGGREGATES.map((a) => <option key={a.fn} value={a.fn}>{a.label}</option>)}
 
 
 
 
 
 
 
1228
  </select>
1229
  </label>
1230
+ {/* ⭐⭐ W57-T17 (R5, contract C3) - THE METRIC BUILDER, AND IT IS THE DATA
1231
+ MODULE'S OWN. `ColumnMenu.tsx`'s create pane builds a Metric out of exactly
1232
+ one control, a `FieldSelectButton` over the workspace's `measures` labelled
1233
+ "Number", and this is a second caller of that control rather than a second
1234
+ design of it. C3's "minus any period control" is why the `WindowPicker` that
1235
+ sits beside it there is not repeated here: the period is the panel's own
1236
+ fieldset below.
1237
+
1238
+ ⛔⛔ IT RESOLVES TO A METRIC COLUMN AND EMITS `{fn, field}` LIKE EVERY OTHER
1239
+ BINDING. `platform/modules/sheet.py::metric_key_refusal` refuses C2's
1240
+ `{metric_key}` arm BY NAME, so a builder that stored the chosen number
1241
+ directly would ship a cell that can never compute while tsc, the build and
1242
+ the picker all stayed green. `Field.measure.key` is the join, and it is the
1243
+ only one.
1244
+
1245
+ ⚠ THE STORED-COLUMN PICKER BESIDE IT STAYS. This is an additive second door
1246
+ to the same `field` value: somebody totalling an ordinary currency column
1247
+ must still be able to reach it. */}
1248
+ {fn !== "count" && measures.length > 0 && (
1249
+ <div className="sheet-field sheet-field--pick">
1250
+ <span>Number</span>
1251
+ <FieldSelectButton
1252
+ ariaLabel="Number to summarise"
1253
+ placeholder="Choose a number…"
1254
+ value={chosenField?.measure?.key}
1255
+ onChange={(key) => {
1256
+ const metricField = fields.find((f) => isMetricField(f)
1257
+ && f.measure?.key === key);
1258
+ if (!metricField) {
1259
+ const numberLabel = measures.find((m) => m.key === key)?.label ?? key;
1260
+ setMeasureNotice(
1261
+ `There is no Metric column for ${numberLabel} on this database. `
1262
+ + "Pick a column from the list instead, or add that Metric to the "
1263
+ + "database first.",
1264
+ );
1265
+ return;
1266
+ }
1267
+ setField(metricField.key);
1268
+ setMeasureNotice("");
1269
+ }}
1270
+ fields={measures.map((m) => ({
1271
+ key: m.key, label: m.label, type: "measure" as const,
1272
+ }))}
1273
+ />
1274
+ {measureNotice && (
1275
+ <p className="sheet-notice" role="alert">{measureNotice}</p>
1276
+ )}
1277
+ </div>
1278
+ )}
1279
+ {/* Count takes no column, and offering one would suggest count(column), which skips
1280
+ blanks and answers a smaller number than the person meant. */}
1281
+ {fn !== "count" && (
1282
+ <div className="sheet-field sheet-field--pick">
1283
+ <span id="sheet-col-pick-label">Column</span>
1284
+ {/* ⭐⭐ W54-T31 (R8) — THE CONTROL SHOWS WHAT IS CHOSEN AND OPENS THE LIST; IT IS
1285
+ NOT THE LIST. `cg-select cg-fsel` is the shipped footprint every replaced
1286
+ `<select>` in this product already wears, so the Column line shares its height
1287
+ and its baseline with the Aggregate select above it rather than introducing a
1288
+ new control shape. The three states are `FieldSelect`'s own: unset reads as a
1289
+ prompt, a resolved column shows its mark and its name, and a column this
1290
+ database cannot offer shows its raw key in the amber `is-missing` slot instead
1291
+ of a plausible substitute. */}
1292
+ <button
1293
+ type="button"
1294
+ className={"cg-select cg-fsel sheet-col-open"
1295
+ + (chosenField ? "" : field ? " is-missing" : " is-empty")}
1296
+ aria-haspopup="dialog"
1297
+ aria-expanded={colPickerOpen}
1298
+ aria-labelledby="sheet-col-pick-label"
1299
+ title={chosenField ? chosenField.key : undefined}
1300
+ onClick={() => setColPickerOpen(true)}
1301
  >
1302
+ {chosenField ? (
1303
+ <FieldTypeIcon
1304
+ type={isMetricField(chosenField) ? "measure" : chosenField.type}
1305
+ title={isMetricField(chosenField) ? "Metric" : chosenField.type}
1306
+ />
1307
+ ) : (
1308
+ // No mark, but the SLOT stays, so the name sits in the same column whether or
1309
+ // not anything is chosen yet.
1310
+ <span className="cg-fsel-nomark" aria-hidden />
1311
+ )}
1312
+ <span className="cg-fsel-label">
1313
+ {chosenField?.label ?? (field || "Choose a column")}
1314
+ </span>
1315
+ <svg className="cg-fsel-caret" width="10" height="10" viewBox="0 0 16 16"
1316
+ fill="none" aria-hidden>
1317
+ <path d="M4 6l4 4 4-4" stroke="currentColor" strokeWidth="1.6"
1318
+ strokeLinecap="round" strokeLinejoin="round" />
1319
+ </svg>
1320
+ </button>
1321
+ {/* ⛔⛔ MOUNTED ONLY WHILE OPEN, which is what orders Escape. See the block above
1322
+ `ColumnPickerDialog`: the editor's own Escape claim was pushed at mount, this
1323
+ one is pushed on open, and unmounting hands the key straight back. */}
1324
+ {colPickerOpen && (
1325
+ <SheetColumnPicker
1326
+ addr={addr}
1327
+ aggregateNoun={AGGREGATE_NOUN[fn] ?? "total"}
1328
+ databaseLabel={databaseLabel}
1329
+ shown={shownFields}
1330
+ offered={numericFields}
1331
+ all={fields}
1332
+ chosen={field}
1333
+ query={fieldQuery}
1334
+ onQuery={setFieldQuery}
1335
+ onPick={(key) => {
1336
+ setField(key);
1337
+ setMeasureNotice("");
1338
+ setColPickerOpen(false);
1339
+ }}
1340
+ onClose={() => setColPickerOpen(false)}
1341
+ />
1342
+ )}
1343
+ {/* ⭐⭐ THE BIND TIME REFUSAL, SURFACED WHERE THE PERSON CAN ACT ON IT. The server
1344
+ refuses this column by name (`field_not_aggregable`), but only once a number is
1345
+ asked for; saying it here means the choice is corrected before a save. */}
1346
+ {savedFieldUnavailable && (
1347
+ <p className="sheet-notice" role="alert">
1348
+ {`The saved column ${field} cannot be totalled on this database. `
1349
+ + "Pick a column from the list, or count the records instead."}
1350
+ </p>
1351
+ )}
1352
+ </div>
1353
+ )}
1354
+ </div>
1355
+ </>
1356
+ )}
1357
+ {activeSection === "rows" && (
1358
+ <>
1359
+ <fieldset className="sheet-scope">
1360
+ <legend>Rows to include</legend>
1361
+ <label className="sheet-radio">
1362
+ <input type="radio" checked={scopeKind === "view"}
1363
+ onChange={() => setScopeKind("view")} />
1364
+ <span>A saved view</span>
1365
+ </label>
1366
+ {scopeKind === "view" && (
1367
+ <select value={viewId} onChange={(e) => setViewId(e.target.value)}>
1368
+ <option value="">Choose a view</option>
1369
+ {views.map((v) => <option key={v.id} value={v.id}>{v.name}</option>)}
1370
+ </select>
1371
+ )}
1372
+ {/* ⭐ W53-T12 — SAID HERE, THE MOMENT THE LIST RESOLVES, rather than as a refusal after
1373
+ a save or a refresh. `sheet-notice` with `role="alert"` is this panel's established
1374
+ inline shape, so the sentence lands where the choice is made. */}
1375
+ {savedViewMissing && (
1376
+ <p className="sheet-notice" role="alert">
1377
+ {`The saved view ${savedView.name || savedView.id} is not available any more. `
1378
+ + "Pick a view that still exists, or build a filter here."}
1379
+ </p>
1380
+ )}
1381
+ <label className="sheet-radio">
1382
+ <input type="radio" checked={scopeKind === "filter"}
1383
+ onChange={() => setScopeKind("filter")} />
1384
+ <span>A filter I build here</span>
1385
+ </label>
1386
+ {/* ⭐⭐ W53-T15 (ruling R8) — A DOOR, NOT THE BUILDER. The same shared panel now opens
1387
+ in a centred dialog: this column is `flex: 0 0 380px` and a condition row cannot fit
1388
+ in it, so four conditions could only be reached by scrolling sideways. The button
1389
+ says how many conditions the cell already carries, because the builder that used to
1390
+ say so is now behind it. */}
1391
+ {scopeKind === "filter" && (
1392
+ <>
1393
+ <button
1394
+ type="button"
1395
+ className="sheet-action"
1396
+ style={{ alignSelf: "flex-start" }}
1397
+ aria-haspopup="dialog"
1398
+ aria-expanded={filterPopupOpen}
1399
+ onClick={() => setFilterPopupOpen(true)}
1400
+ >
1401
+ {conditionCount === 0
1402
+ ? "Build a filter"
1403
+ : `Edit filter (${conditionCount === 1
1404
+ ? "1 condition" : `${conditionCount} conditions`})`}
1405
+ </button>
1406
+ {/* ⛔⛔ MOUNTED ONLY WHILE OPEN, and that is what orders Escape correctly rather
1407
+ than a flag inside the dialog. `useOverlayLayer` claims Escape as soon as it
1408
+ runs and `ui/useEscapeClose` gives the key to the LAST entry pushed, so a
1409
+ dialog mounted with the panel would have claimed Escape from the moment this
1410
+ editor opened. Mounting it here, later in time, puts it ABOVE this panel's own
1411
+ claim (pushed at mount, a few hundred lines up) and unmounting it hands Escape
1412
+ straight back, so one press closes the filter and the next closes the panel. */}
1413
+ {filterPopupOpen && (
1414
+ <SheetFilterPopup
1415
+ addr={addr}
1416
+ fields={fields}
1417
+ filters={tree}
1418
+ onChange={setTree}
1419
+ statusValues={statusValues}
1420
+ onClose={() => setFilterPopupOpen(false)}
1421
+ />
1422
+ )}
1423
+ </>
1424
+ )}
1425
+ </fieldset>
1426
+ </>
1427
+ )}
1428
+ {activeSection === "period" && (
1429
+ <>
1430
+ {/* ══ R9: THE PERIOD ══════════════════════════════════════════════════════════════════ */}
1431
+ <fieldset className="sheet-scope sheet-period">
1432
+ <legend>Period</legend>
1433
+
1434
+ {/* ⭐⭐ W53-T16 / D-660 - WHETHER THIS CELL HAS A PERIOD AT ALL, said out loud. The
1435
+ pickers below show a unit and a month whether or not the cell is using them, so
1436
+ without this switch an all-time total read as "September 2026" on screen and the next
1437
+ save made that true. It is also the only way back to all time once a period is set. */}
1438
+ {/* ⛔⛔ W57-T18 (R5, C3) - THIS SWITCH IS NO LONGER DISABLED ON A METRIC, AND
1439
+ THAT IS THE TICKET RATHER THAN A REGRESSION. W56-T19 disabled it for a
1440
+ template Metric, which made an invalid binding UNREACHABLE instead of
1441
+ REFUSED. C3 asks for a refusal on both sides, and a control nobody can
1442
+ move produces no refusal anybody can see: `ready` would be permanently
1443
+ true for a Metric, the rail's Required tag could never paint, and the
1444
+ client half of the contract would be satisfied only by the state being
1445
+ impossible to enter. The effect above still raises the switch the moment a
1446
+ Metric is chosen, so the DEFAULT is a valid binding; turning it off is
1447
+ what the panel then refuses to save, and the rail says where to go. */}
1448
+ <div className="sheet-period-lock">
1449
+ <button
1450
+ type="button"
1451
+ role="switch"
1452
+ aria-checked={periodOn}
1453
+ className={"sheet-lock-toggle" + (periodOn ? " is-on" : "")}
1454
+ onClick={() => setPeriodOn((v) => !v)}
1455
+ >
1456
+ <span className="sheet-lock-dot" aria-hidden />
1457
+ <span>Limit this cell to a period</span>
1458
+ </button>
1459
+ <p className="sheet-period-note">
1460
+ {chosenIsMetric
1461
+ ? "The period is required because every Metric column is measured over one."
1462
+ : (periodOn
1463
+ ? "Only rows dated inside the period below are counted."
1464
+ : "All time, so every row this cell's filter matches is counted whatever its date. "
1465
+ + "Saving leaves it that way.")}
1466
+ </p>
1467
+ </div>
1468
+
1469
+ {periodOn && (
1470
+ <>
1471
+ {/* ⭐ C5 - THE MODE LABELS SAY WHAT EACH CHOICE DOES. Internal dialect names
1472
+ would make the reader guess which one can step and which one follows today. */}
1473
  <label className="sheet-field">
1474
+ <span>How to choose the period</span>
1475
  <select
1476
+ value={periodMode}
1477
+ aria-label="How this period is chosen"
1478
+ onChange={(e) => setPeriodMode(e.target.value as "calendar" | "window")}
1479
  >
1480
+ <option value="calendar">Pick a calendar period by year and month</option>
1481
+ <option value="window">Use a rolling window such as year to date</option>
 
1482
  </select>
1483
  </label>
1484
+
1485
+ {periodMode === "window" ? (
1486
+ <label className="sheet-field">
1487
+ <span>Window</span>
1488
+ <WindowPicker window={windowSpec} onWindow={setWindowSpec} />
1489
+ </label>
1490
+ ) : (
1491
+ <>
1492
+ <label className="sheet-field">
1493
+ <span>Unit</span>
1494
+ <select
1495
+ value={unit}
1496
+ aria-label="Period unit"
1497
+ onChange={(e) => {
1498
+ const next = e.target.value as PeriodUnit;
1499
+ setUnit(next);
1500
+ // Re-seat the start on the new unit's first month, or the pair stops naming one
1501
+ // period: `2026-08` under `quarter` is not a quarter anybody can compile.
1502
+ setStart(normalizePeriodStart(next, start));
1503
+ }}
1504
+ >
1505
+ {PERIOD_UNITS.map((u) => <option key={u.unit} value={u.unit}>{u.label}</option>)}
1506
+ </select>
1507
+ </label>
1508
+
1509
+ <div className="sheet-field-row">
1510
+ <label className="sheet-field">
1511
+ <span>Year</span>
1512
+ <select
1513
+ value={String(startYear)}
1514
+ aria-label="Period year"
1515
+ onChange={(e) => setYear(Number(e.target.value))}
1516
+ >
1517
+ {years.map((y) => <option key={y} value={String(y)}>{y}</option>)}
1518
+ </select>
1519
+ </label>
1520
+ {unit === "month" && (
1521
+ <label className="sheet-field">
1522
+ <span>Month</span>
1523
+ <select
1524
+ value={String(startMonth)}
1525
+ aria-label="Period month"
1526
+ onChange={(e) => setMonthOfYear(Number(e.target.value))}
1527
+ >
1528
+ {MONTH_NAMES.map((name, i) => (
1529
+ <option key={name} value={String(i + 1)}>{name}</option>
1530
+ ))}
1531
+ </select>
1532
+ </label>
1533
+ )}
1534
+ {unit === "quarter" && (
1535
+ <label className="sheet-field">
1536
+ <span>Quarter</span>
1537
+ <select
1538
+ value={String(Math.floor((startMonth - 1) / 3) + 1)}
1539
+ aria-label="Period quarter"
1540
+ onChange={(e) => setMonthOfYear(1 + 3 * (Number(e.target.value) - 1))}
1541
+ >
1542
+ {[1, 2, 3, 4].map((q) => <option key={q} value={String(q)}>{`Q${q}`}</option>)}
1543
+ </select>
1544
+ </label>
1545
+ )}
1546
+ </div>
1547
+
1548
+ {/* W56-T21 (owner instruction 13) - THE QUICK PICKS ARE GONE. Unit, year and
1549
+ month-or-quarter already reach every period the This and Last buttons
1550
+ could, so a second control for the same value was a second way to say one
1551
+ thing. `normalizePeriodStart` still normalises all three selects, and
1552
+ `shiftPeriodStart` stays exported for the drag arithmetic. */}
1553
+
1554
+ {/* ⭐ R9's LOCK. A switch rather than a checkbox: it has two states with names, and the
1555
+ sentence under it says what each one costs when the cell is copied. */}
1556
+ {chosenIsMetric ? (
1557
+ <div className="sheet-period-lock">
1558
+ <button
1559
+ type="button"
1560
+ role="switch"
1561
+ aria-checked={locked}
1562
+ className={"sheet-lock-toggle" + (locked ? " is-on" : "")}
1563
+ onClick={() => {
1564
+ const next = !locked;
1565
+ setLocked(next);
1566
+ setAcross(next ? "none" : "period");
1567
+ }}
1568
+ >
1569
+ <span className="sheet-lock-dot" aria-hidden />
1570
+ <span>Lock this period</span>
1571
+ </button>
1572
+ <p className="sheet-period-note">
1573
+ {locked
1574
+ ? "Locked, so any copy of this cell keeps this period."
1575
+ : `Not locked, so a stepped copy moves by one ${UNIT_NOUN[unit]} per cell. `
1576
+ + "Right and down move forward. Left and up move backward."}
1577
+ </p>
1578
+ </div>
1579
+ ) : (
1580
+ <p className="sheet-period-note">
1581
+ This period stays fixed when copied. The filter clause below is what
1582
+ changes.
1583
+ </p>
1584
+ )}
1585
+
1586
+ {/* ⭐ "Use a cell" STAYS A LINK (R9). It reveals the A1 input rather than replacing the
1587
+ picker, so the ordinary reader never meets a cell reference and the person who wants
1588
+ one is one click away from it. */}
1589
+ {!refOpen && (
1590
+ <button
1591
+ type="button"
1592
+ className="sheet-period-link"
1593
+ onClick={() => setRefOpen(true)}
1594
+ >
1595
+ Use a cell
1596
+ </button>
1597
+ )}
1598
+ {refOpen && (
1599
+ <label className="sheet-field">
1600
+ <span>Period from a cell</span>
1601
+ <input
1602
+ type="text"
1603
+ value={periodRef}
1604
+ onChange={(e) => setPeriodRef(e.target.value)}
1605
+ placeholder="$B$1"
1606
+ />
1607
+ </label>
1608
+ )}
1609
+ </>
1610
+ )}
1611
+ </>
1612
+ )}
1613
+ </fieldset>
1614
+ </>
1615
+ )}
1616
+ {activeSection === "copied" && (
1617
+ <>
1618
+ {/* ══ R10: THE DRAG RULES ═════════════════════════════════════════════════════════════ */}
1619
+ <fieldset className="sheet-scope sheet-drag">
1620
+ <legend>When copied</legend>
1621
+
1622
+ {chosenIsMetric && periodOn && periodMode === "calendar" && (
1623
+ <>
1624
  <label className="sheet-field">
1625
+ <span>{periodClauseLabel}</span>
1626
  <select
1627
+ value={!locked && across === "period" ? "period" : "none"}
1628
+ aria-label={periodClauseLabel}
1629
+ onChange={(e) => {
1630
+ const step = e.target.value === "period";
1631
+ setAcross(step ? "period" : "none");
1632
+ setLocked(!step);
1633
+ }}
1634
  >
1635
+ <option value="period">{`Step by ${UNIT_NOUN[unit]}`}</option>
1636
+ <option value="none">Keep this period</option>
1637
  </select>
1638
  </label>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1639
  <p className="sheet-period-note">
1640
+ Right and down move forward. Left and up move backward.
 
 
 
1641
  </p>
1642
+ </>
1643
+ )}
1644
+
1645
+ {/* ⛔ C5 - A ROLLING WINDOW HAS NO START TO SHIFT. Offering the calendar step here
1646
+ would promise an action `dragBoundCell` cannot perform. */}
1647
+ {periodOn && periodMode === "window" && (
1648
  <p className="sheet-period-note">
1649
+ A rolling window is measured from today, so every copy of this cell answers the
1650
+ same window. Use a calendar period when the period should step as the cell is copied.
1651
  </p>
1652
  )}
1653
 
1654
+ {/* ⚠ AN ALL-TIME METRIC SAYS WHY NO PERIOD PICKER IS PRESENT. Without this note the
1655
+ absent control looks like a loading or configuration failure. */}
1656
+ {chosenIsMetric && !periodOn && (
1657
+ <p className="sheet-period-note">
1658
+ This metric is all time, so copied cells keep the same all-time period.
1659
+ </p>
1660
+ )}
1661
+
1662
+ <label className="sheet-field">
1663
+ <span>Filter clause</span>
1664
+ <select
1665
+ value={downField}
1666
+ aria-label="Filter clause when copied"
1667
+ onChange={(e) => setDownField(e.target.value)}
1668
  >
1669
+ <option value="">Keep this filter</option>
1670
+ {filterClauseOffers.map((clause) => (
1671
+ <option
1672
+ key={clause.colId}
1673
+ value={clause.colId}
1674
+ disabled={!clause.canStep}
1675
+ title={clause.canStep ? undefined : clause.reason}
1676
+ >
1677
+ {clause.canStep
1678
+ ? `Step ${clause.label}, now ${clause.value || "no value"}`
1679
+ : `${clause.label} cannot step: ${clause.shortReason}`}
1680
+ </option>
1681
+ ))}
1682
+ {savedDragDriverMissing && (
1683
+ <option value={downField}>
1684
+ {`${downField}: not in this cell's filter any more`}
1685
+ </option>
1686
+ )}
1687
+ </select>
1688
+ </label>
1689
+ {savedDragDriverMissing && (
1690
+ <p className="sheet-notice" role="alert">
1691
+ The saved driver is not in this cell&apos;s filter, so copying this cell will not
1692
+ change it. Pick a driver that is in the filter, or keep the filter.
1693
+ </p>
1694
  )}
1695
+ {scopeKind === "view" && (
1696
+ <p className="sheet-period-note">
1697
+ A copy builds its own filter from the view&apos;s clauses and steps the clause chosen here.
1698
+ </p>
 
 
 
 
 
 
1699
  )}
1700
+ {filterClauseOffers.length === 0 ? (
1701
+ <p className="sheet-period-note">
1702
+ This cell has no filter clauses to step.
1703
+ </p>
1704
+ ) : (
1705
+ <p className="sheet-period-note">
1706
+ Right and down choose later options. Left and up choose earlier options.
1707
+ </p>
1708
+ )}
1709
+ </fieldset>
1710
+ </>
1711
+ )}
1712
+ </div>
1713
+ </div>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1714
 
1715
  {/* ⛔⛔ W53-T16 (owner instruction 13) - THE FOUR SENTENCE SUMMARY IS DELETED, NOT HIDDEN.
1716
  It restated the period, the lock and the two drag rules that the controls immediately
 
1730
  )}
1731
  </div>
1732
 
1733
+ {/* C7 and the owner's Apple principle: Save is this surface's ONE primary;
1734
+ Preview and Cancel are deliberately quiet. */}
1735
  <div className="sheet-binding-actions">
1736
+ <button type="button" className="lp-btn lp-btn-quiet" onClick={runPreview} disabled={!ready}>
1737
  Preview
1738
  </button>
1739
+ <button type="button" className="lp-btn lp-btn-primary" onClick={() => onSave(binding)}
1740
  disabled={!ready}>
1741
  Save
1742
  </button>
1743
+ <button type="button" className="lp-btn lp-btn-quiet" onClick={onCancel}>
1744
  Cancel
1745
  </button>
1746
  </div>
web/src/sheet/DrillModal.tsx CHANGED
@@ -38,9 +38,8 @@
38
  // when we click 'View row' so its easy for user also to know what this filter is. In fact, they
39
  // should be able to change the filter there too. And if they make a mistake etc, they can just
40
  // CTRL + Z to return the Cell to its original filter."* Three clauses, and each one is a decision
41
- // recorded beside the code that answers it: the BAND (`DrillFilterBand`) states it, the top-right
42
- // Edit filter action opens the shared `SheetFilterDialog`, and one cell-scoped step of undo takes
43
- // it back.
44
  //
45
  // ⭐⭐ W56-T24 / R4 / C4 — THE LINK MODAL NOW OWNS ORDINARY SLOTS FOR THE SHEET'S CHROME.
46
  // The toolbar and filter statement are children of the modal's header and footer, so they remain
@@ -60,12 +59,10 @@ import type { SurfaceScope } from "../customer-grid/apiBridge";
60
  import { dataPathHash } from "../customer-grid/dataPath";
61
  import { AnchoredOverlay, OverlayProvider } from "../customer-grid/OverlaySurface";
62
  import type { Field, FilterTree, GridWorkspace, Row } from "../customer-grid/types";
63
- import { choiceVocabulary, mayEditField, topicForScope } from "../customer-grid/types";
64
- import {
65
- SheetFilterDialog, conditionCountLabel, filterSentence,
66
- } from "../filter-kit/SheetFilterPopup";
67
  import { useEscapeClose } from "../ui/useEscapeClose";
68
- import { cellViewVisibleKeys, filterFieldKeys } from "./bindingRefs";
69
  import { drillCell } from "./sheetApi";
70
  import type { CellDrill } from "./sheetApi";
71
  import type { BindingDisplay } from "./types";
@@ -182,6 +179,10 @@ export type DrillCellScope = (
182
  & {
183
  /** W56-T24: accepted legacy cell display bag; the grid now owns presentation itself. */
184
  display?: BindingDisplay;
 
 
 
 
185
  };
186
 
187
  /** What the drill's own answer says about the scope, for a caller that passed none. */
@@ -207,8 +208,8 @@ const sameTree = (a: FilterTree | null, b: FilterTree | null): boolean =>
207
  *
208
  * The sentence is the whole of the owner's first clause, so it takes the width and truncates with
209
  * an ellipsis rather than being shortened into a count; the full text stays reachable as the
210
- * element's `title`. W55-T07 moves Edit filter to the top-right toolbar and leaves this band one
211
- * statement with one job. W56-T24 seats it inside `LinkGridModal`'s footer slot, so that shell now
212
  * supplies the `cg-link-grid-foot` paint instead of this child impersonating the footer itself.
213
  */
214
  function DrillFilterBand(
@@ -256,7 +257,7 @@ export interface DrillModalProps {
256
  */
257
  cellScope?: DrillCellScope | null;
258
  /**
259
- * W54-T35: persist a new filter for this cell and recompute it. Absent means no Edit door.
260
  *
261
  * ⛔ IT RESOLVES WHEN THE WRITE HAS SETTLED, which is what lets the rows be re-read afterwards
262
  * rather than immediately: `GET …/drill` reads the STORED binding, so a re-read fired before
@@ -291,18 +292,6 @@ export default function DrillModal(
291
  filterChangeRef.current = onFilterChange;
292
 
293
  // ── W54-T35 state ─────────────────────────────────────────────────────────────────────────
294
- /** Is the centred filter dialog on screen? */
295
- const [filterOpen, setFilterOpen] = useState(false);
296
- /**
297
- * ⛔⛔ THE DRAFT IS THIS COMPONENT'S, NOT THE DIALOG'S, AND THE DIALOG'S OWN CONTRACT IS WHY.
298
- * `SheetFilterPopup` holds no draft on purpose: `onChange` is the caller's setter and every
299
- * keystroke commits. The binding panel can afford that because its setter is a `useState`. Here
300
- * the setter would be a PUT plus a recompute, so a value typed into a condition box would be one
301
- * save per character. So the keystrokes land here, and the dialog closing is the commit.
302
- * ⚠ THAT IS ALSO WHY CLOSING IT IS NOT A CANCEL. Escape, an outside click and Done are the same
303
- * event with three names in that dialog, and they stay the same event here: all three APPLY.
304
- */
305
- const [draft, setDraft] = useState<FilterTree | null>(null);
306
  /**
307
  * ⭐⭐ THE UNDO, AND IT IS ONE STEP SCOPED TO THIS CELL. Owner: *"if they make a mistake etc,
308
  * they can just CTRL + Z to return the Cell to its original filter."*
@@ -311,21 +300,20 @@ export default function DrillModal(
311
  * array on every commit, so pushing a filter edit onto it would make one Ctrl+Z walk back
312
  * whatever else the reader had typed since - an undo that reaches past the surface it was
313
  * pressed on, into cells nobody was looking at. This holds ONE tree: the cell's filter as it
314
- * stood when the dialog was opened. A second Ctrl+Z therefore has nothing to pop and does not
315
  * go further back, which is the done-when clause spelled as a data structure rather than as a
316
  * guard somebody has to remember to write.
317
  */
318
  const [undoTree, setUndoTree] = useState<FilterTree | null>(null);
319
- /** The tree as it stood when the Edit door was last opened. See `openFilter`. */
320
  const preEditRef = useRef<FilterTree | null>(null);
321
  /** Latest grid-owned filter edit waiting for 800 ms of quiet before it reaches the cell. */
322
  const pendingCellFilterRef = useRef<FilterTree | null>(null);
323
  const cellFilterTimerRef = useRef<number | null>(null);
324
  /** Bumped when a filter change has landed, so the rows are read again. */
325
  const [reloadSeq, setReloadSeq] = useState(0);
326
- /** The filter kit's two vocabularies for this database. Fetched once the drill has answered. */
327
  const [fields, setFields] = useState<Field[]>([]);
328
- const [statusValues, setStatusValues] = useState<Record<string, string[]>>({});
329
  /** Raw, permission-scoped rows back the export projection. */
330
  const [rawRows, setRawRows] = useState<Row[]>([]);
331
  const [workspace, setWorkspace] = useState<GridWorkspace | null>(null);
@@ -411,7 +399,7 @@ export default function DrillModal(
411
  }, [workbookId, addr, reloadSeq]);
412
 
413
  /**
414
- * ⭐⭐ W54-T35 — WHAT THE BAND SAYS, AND WHAT THE DIALOG EDITS.
415
  *
416
  * The page's own reading of the cell wins, because it is the one that MOVES: it is rebuilt from
417
  * the workbook after every commit, so the sentence changes the moment a filter is applied. The
@@ -426,9 +414,7 @@ export default function DrillModal(
426
  shownTreeRef.current = shownTree;
427
 
428
  /**
429
- * ⭐ THE FIELD AND VALUE VOCABULARIES, FETCHED THE WAY `BindingEditor` FETCHES THEM, and warmed
430
- * on the drill's answer rather than on the Edit click for the reason `warmLinkChunk` is warmed
431
- * at mount: the two doors would otherwise run back to back for one gesture.
432
  *
433
  * ⛔ NEITHER CALL IS NEW TRAFFIC IN PRACTICE. `fetchWorkspace(scope, {allowCached: true})` is
434
  * served from `wsCache` inside its freshness window, and `fetchTopicRows` shares `rowsCache`
@@ -458,22 +444,9 @@ export default function DrillModal(
458
  }
459
  const list = ((rowsPayload?.fields?.length ? rowsPayload.fields : ws?.fields) ?? []) as Field[];
460
  const rows: Row[] = rowsPayload?.rows ?? [];
461
- const options: string[] = rowsPayload?.userOptions ?? ws?.userOptions ?? [];
462
- const map: Record<string, string[]> = {};
463
- // The same rule `Toolbar.tsx` and `BindingEditor.tsx` compute, through the same pure
464
- // function, so a server-computed select has a value list here as well.
465
- for (const f of list) {
466
- if (f.type === "user") {
467
- map[f.key] = options;
468
- continue;
469
- }
470
- if (f.type === "select" || f.type === "multiselect" || f.type === "status")
471
- map[f.key] = choiceVocabulary(f, rows);
472
- }
473
  setWorkspace(ws);
474
  setFields(list);
475
  setRawRows(rows);
476
- setStatusValues(map);
477
  setToday(rowsPayload?.today);
478
  setRowsResolved(true);
479
  })();
@@ -518,34 +491,6 @@ export default function DrillModal(
518
  pendingCellFilterRef.current = null;
519
  }, []);
520
 
521
- /**
522
- * ⛔ CLOSING THE DIALOG IS THE COMMIT, and an unchanged tree commits nothing. Without that test
523
- * every open-and-look would write the cell back to itself, which is a PUT, a recompute and a
524
- * spurious undo step for a gesture that changed nothing.
525
- */
526
- const closeFilter = useCallback(() => {
527
- setFilterOpen(false);
528
- const next = draft;
529
- setDraft(null);
530
- if (!next || sameTree(next, shownTree)) return;
531
- // ⛔ THE UNDO STEP IS RECORDED HERE AND NOT AT THE OPEN, because a door that was opened and
532
- // shut again changed nothing and must leave nothing to take back. Recording it on open would
533
- // arm Ctrl+Z after a look, and the press would then write the cell back to itself: a PUT, a
534
- // recompute and a stale mark, for a gesture that did nothing.
535
- setUndoTree(preEditRef.current);
536
- void applyTree(next);
537
- }, [applyTree, draft, shownTree]);
538
-
539
- const openFilter = useCallback(() => {
540
- if (!shownTree) return;
541
- // "The filter it had before the edit" is the filter it has at the moment the door opens. It
542
- // is held in a ref rather than in state because nothing renders it: it is read once, by the
543
- // close above, and putting it in state would re-render the drill for no visible reason.
544
- preEditRef.current = shownTree;
545
- setDraft(shownTree);
546
- setFilterOpen(true);
547
- }, [shownTree]);
548
-
549
  /**
550
  * ⭐⭐ WHERE THE KEYSTROKE ACTUALLY ARRIVES, WHICH IS NOT WHERE THE SHEET'S UNDO LIVES.
551
  *
@@ -574,7 +519,7 @@ export default function DrillModal(
574
  */
575
  const undoRef = useRef<() => void>(() => {});
576
  undoRef.current = () => {
577
- if (filterOpen || !undoTree) return;
578
  setUndoTree(null);
579
  void applyTree(undoTree);
580
  };
@@ -609,9 +554,13 @@ export default function DrillModal(
609
  : savedView
610
  ? { conj: savedView.config.filterConj, nodes: savedView.config.filters }
611
  : null;
612
- const forcedFieldKeys = filterFieldKeys(fieldFilter);
 
 
613
  const defaultFieldKeys = fields
614
- .filter((field) => field.default !== false && field.custom !== true && field.shared !== true)
 
 
615
  .map((field) => field.key);
616
  const visibleKeys = cellViewVisibleKeys(
617
  defaultFieldKeys,
@@ -665,11 +614,18 @@ export default function DrillModal(
665
  const bandText = !shown
666
  ? ""
667
  : shown.kind === "view"
668
- ? (shown.name ? `Rows come from the saved view ${shown.name}` : "Rows come from a saved view")
 
 
 
 
 
 
 
 
669
  // ⛔ THE FALLBACK IS THE COUNT, NOT A SECOND SENTENCE. `filterSentence` answers "" when the
670
  // filter narrows nothing, which covers both an empty tree and one whose conditions are all
671
- // still half typed; `conditionCountLabel` is the wording the dialog behind the Edit door
672
- // already uses for that, so the two surfaces say the same thing about the same tree.
673
  : said ? `Rows where ${said}` : conditionCountLabel(shown.tree);
674
 
675
  if (error) {
@@ -714,22 +670,21 @@ export default function DrillModal(
714
  // now would blink the screen back to empty at the last moment, which is the defect this ticket
715
  // exists to remove, arriving one step later.
716
  /**
717
- * ⭐⭐ W54-T35 — ONE `OverlayProvider` OVER BOTH SURFACES, AND WITHOUT IT THE EDIT DOOR CLOSES
718
- * THE DRILL. `useOverlayLayer` defers to a higher layer only when it can SEE one:
719
- * `if (!dismissOnOutside || (stack && !stack.isTop(id))) return;`, where `stack` is
720
- * `useContext(OverlayStackContext)`. The Sheet route mounts no provider, so `LinkGridModal`
721
- * ran with `stack === null` and treated a pointerdown ANYWHERE outside its own card as a
722
- * dismissal - including one inside a filter dialog opened on top of it. Both layers register
723
- * here instead, the dialog registers later, and the card stands down while it is up. This is
724
- * the same trap `filter-kit/SheetFilterPopup.tsx` documents at the top of its own file, one
725
- * layer further out, which is why the dialog is mounted through `SheetFilterDialog` (no
726
- * provider of its own) rather than through `SheetFilterPopup` (which brings one).
727
  *
728
  * ⛔ ESCAPE IS UNAFFECTED AND STILL RESOLVES TO EXACTLY ONE SURFACE. That is the module-level
729
- * stack in `ui/useEscapeClose`, not this one: the card claims when it mounts, the dialog
730
- * claims when it opens and is therefore topmost, so one press closes the filter and the next
731
- * closes the drill. The band claims nothing: it is a statement inside the card, not an
732
- * overlay, so the "exactly one claimant" property W51-T12 bought is unspent.
733
  */
734
  <OverlayProvider>
735
  <Suspense fallback={<DrillSkeleton label={label} nodeRef={skeletonRef} />}>
@@ -739,27 +694,12 @@ export default function DrillModal(
739
  recordIds={drill.record_ids}
740
  editable={false}
741
  cellView
 
742
  // A view-bound cell passes neither prop: its rows remain the saved view's business.
743
  cellFilter={shownTree ?? undefined}
744
  onCellFilterChange={shownKind === "filter" ? settleCellFilter : undefined}
745
  headerActions={(
746
  <div className="sheet-cell-view-toolbar" role="toolbar" aria-label="Cell View controls">
747
- <button
748
- type="button"
749
- className="sheet-cell-view-action"
750
- aria-haspopup="dialog"
751
- aria-expanded={filterOpen}
752
- disabled={shownKind !== "filter" || !onFilterChange}
753
- title={shownKind === "view"
754
- ? "This cell follows a saved view, so its filter is changed in Data."
755
- : undefined}
756
- onClick={openFilter}
757
- >
758
- <svg viewBox="0 0 16 16" aria-hidden="true">
759
- <path d="M2.5 3h11L9.2 8v4.2l-2.4 1V8z" />
760
- </svg>
761
- <span>Edit filter</span>
762
- </button>
763
  {canEditRows && (
764
  <button type="button" className="sheet-cell-view-action" onClick={editInData}>
765
  <svg viewBox="0 0 16 16" aria-hidden="true">
@@ -814,16 +754,6 @@ export default function DrillModal(
814
  ))}
815
  </AnchoredOverlay>
816
  )}
817
- {filterOpen && draft && (
818
- <SheetFilterDialog
819
- addr={addr}
820
- fields={fields}
821
- filters={draft}
822
- onChange={setDraft}
823
- statusValues={statusValues}
824
- onClose={closeFilter}
825
- />
826
- )}
827
  </OverlayProvider>
828
  );
829
  }
 
38
  // when we click 'View row' so its easy for user also to know what this filter is. In fact, they
39
  // should be able to change the filter there too. And if they make a mistake etc, they can just
40
  // CTRL + Z to return the Cell to its original filter."* Three clauses, and each one is a decision
41
+ // recorded beside the code that answers it: the BAND (`DrillFilterBand`) states it, the grid's
42
+ // Filter control edits it, and one cell-scoped step of undo takes it back.
 
43
  //
44
  // ⭐⭐ W56-T24 / R4 / C4 — THE LINK MODAL NOW OWNS ORDINARY SLOTS FOR THE SHEET'S CHROME.
45
  // The toolbar and filter statement are children of the modal's header and footer, so they remain
 
59
  import { dataPathHash } from "../customer-grid/dataPath";
60
  import { AnchoredOverlay, OverlayProvider } from "../customer-grid/OverlaySurface";
61
  import type { Field, FilterTree, GridWorkspace, Row } from "../customer-grid/types";
62
+ import { mayEditField, topicForScope } from "../customer-grid/types";
63
+ import { conditionCountLabel, filterSentence } from "../filter-kit/SheetFilterPopup";
 
 
64
  import { useEscapeClose } from "../ui/useEscapeClose";
65
+ import { cellForcedFieldKeys, cellViewVisibleKeys } from "./bindingRefs";
66
  import { drillCell } from "./sheetApi";
67
  import type { CellDrill } from "./sheetApi";
68
  import type { BindingDisplay } from "./types";
 
179
  & {
180
  /** W56-T24: accepted legacy cell display bag; the grid now owns presentation itself. */
181
  display?: BindingDisplay;
182
+ /** The host supplies these from the current binding alongside its filter or saved view. */
183
+ aggregateField?: string;
184
+ /** The Option step's binding.onDrag.down.field, when down is a field rule. */
185
+ stepField?: string;
186
  };
187
 
188
  /** What the drill's own answer says about the scope, for a caller that passed none. */
 
208
  *
209
  * The sentence is the whole of the owner's first clause, so it takes the width and truncates with
210
  * an ellipsis rather than being shortened into a count; the full text stays reachable as the
211
+ * element's `title`. The grid's Filter control owns editing; this band states the cell's scope
212
+ * and any editing limit. W56-T24 seats it inside `LinkGridModal`'s footer slot, so that shell now
213
  * supplies the `cg-link-grid-foot` paint instead of this child impersonating the footer itself.
214
  */
215
  function DrillFilterBand(
 
257
  */
258
  cellScope?: DrillCellScope | null;
259
  /**
260
+ * W54-T35: persist a new filter for this cell and recompute it.
261
  *
262
  * ⛔ IT RESOLVES WHEN THE WRITE HAS SETTLED, which is what lets the rows be re-read afterwards
263
  * rather than immediately: `GET …/drill` reads the STORED binding, so a re-read fired before
 
292
  filterChangeRef.current = onFilterChange;
293
 
294
  // ── W54-T35 state ─────────────────────────────────────────────────────────────────────────
 
 
 
 
 
 
 
 
 
 
 
 
295
  /**
296
  * ⭐⭐ THE UNDO, AND IT IS ONE STEP SCOPED TO THIS CELL. Owner: *"if they make a mistake etc,
297
  * they can just CTRL + Z to return the Cell to its original filter."*
 
300
  * array on every commit, so pushing a filter edit onto it would make one Ctrl+Z walk back
301
  * whatever else the reader had typed since - an undo that reaches past the surface it was
302
  * pressed on, into cells nobody was looking at. This holds ONE tree: the cell's filter as it
303
+ * stood before the latest grid filter edit. A second Ctrl+Z therefore has nothing to pop and does not
304
  * go further back, which is the done-when clause spelled as a data structure rather than as a
305
  * guard somebody has to remember to write.
306
  */
307
  const [undoTree, setUndoTree] = useState<FilterTree | null>(null);
308
+ /** The tree before the current grid filter edit burst, retained for its undo step. */
309
  const preEditRef = useRef<FilterTree | null>(null);
310
  /** Latest grid-owned filter edit waiting for 800 ms of quiet before it reaches the cell. */
311
  const pendingCellFilterRef = useRef<FilterTree | null>(null);
312
  const cellFilterTimerRef = useRef<number | null>(null);
313
  /** Bumped when a filter change has landed, so the rows are read again. */
314
  const [reloadSeq, setReloadSeq] = useState(0);
315
+ /** Fields for the filter sentence and export, fetched once the drill has answered. */
316
  const [fields, setFields] = useState<Field[]>([]);
 
317
  /** Raw, permission-scoped rows back the export projection. */
318
  const [rawRows, setRawRows] = useState<Row[]>([]);
319
  const [workspace, setWorkspace] = useState<GridWorkspace | null>(null);
 
399
  }, [workbookId, addr, reloadSeq]);
400
 
401
  /**
402
+ * W54-T35: what the band says, and what the grid's Filter control edits.
403
  *
404
  * The page's own reading of the cell wins, because it is the one that MOVES: it is rebuilt from
405
  * the workbook after every commit, so the sentence changes the moment a filter is applied. The
 
414
  shownTreeRef.current = shownTree;
415
 
416
  /**
417
+ * Fields and rows for the filter sentence and export are warmed on the drill's answer.
 
 
418
  *
419
  * ⛔ NEITHER CALL IS NEW TRAFFIC IN PRACTICE. `fetchWorkspace(scope, {allowCached: true})` is
420
  * served from `wsCache` inside its freshness window, and `fetchTopicRows` shares `rowsCache`
 
444
  }
445
  const list = ((rowsPayload?.fields?.length ? rowsPayload.fields : ws?.fields) ?? []) as Field[];
446
  const rows: Row[] = rowsPayload?.rows ?? [];
 
 
 
 
 
 
 
 
 
 
 
 
447
  setWorkspace(ws);
448
  setFields(list);
449
  setRawRows(rows);
 
450
  setToday(rowsPayload?.today);
451
  setRowsResolved(true);
452
  })();
 
491
  pendingCellFilterRef.current = null;
492
  }, []);
493
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
494
  /**
495
  * ⭐⭐ WHERE THE KEYSTROKE ACTUALLY ARRIVES, WHICH IS NOT WHERE THE SHEET'S UNDO LIVES.
496
  *
 
519
  */
520
  const undoRef = useRef<() => void>(() => {});
521
  undoRef.current = () => {
522
+ if (!undoTree) return;
523
  setUndoTree(null);
524
  void applyTree(undoTree);
525
  };
 
554
  : savedView
555
  ? { conj: savedView.config.filterConj, nodes: savedView.config.filters }
556
  : null;
557
+ const forcedFieldKeys = cellForcedFieldKeys(
558
+ fieldFilter, shown?.aggregateField, shown?.stepField,
559
+ );
560
  const defaultFieldKeys = fields
561
+ .filter((field) => field.default !== false
562
+ && (field.custom !== true || Boolean(field.measure))
563
+ && field.shared !== true)
564
  .map((field) => field.key);
565
  const visibleKeys = cellViewVisibleKeys(
566
  defaultFieldKeys,
 
614
  const bandText = !shown
615
  ? ""
616
  : shown.kind === "view"
617
+ // ⛔⛔ W57-T21 - THE BAND CARRIES THE EDITING LIMIT NOW, because the control that used to
618
+ // carry it is gone. The deleted Edit filter button was DISABLED on this branch with a title
619
+ // saying where the filter is changed instead; without a replacement the grid's own Filter
620
+ // control would sit there looking editable and quietly write nothing back, which is standing
621
+ // rule 1's second sentence exactly: a limit that cannot be removed is REPORTED, never
622
+ // silently enforced.
623
+ ? (shown.name
624
+ ? `Rows come from the saved view ${shown.name}, so this cell's filter is changed in Data`
625
+ : "Rows come from a saved view, so this cell's filter is changed in Data")
626
  // ⛔ THE FALLBACK IS THE COUNT, NOT A SECOND SENTENCE. `filterSentence` answers "" when the
627
  // filter narrows nothing, which covers both an empty tree and one whose conditions are all
628
+ // still half typed; `conditionCountLabel` keeps the wording shared with the filter kit.
 
629
  : said ? `Rows where ${said}` : conditionCountLabel(shown.tree);
630
 
631
  if (error) {
 
670
  // now would blink the screen back to empty at the last moment, which is the defect this ticket
671
  // exists to remove, arriving one step later.
672
  /**
673
+ * ⭐⭐ ONE `OverlayProvider` OVER EVERY LAYER THIS CARD OPENS, AND IT IS STILL LOAD-BEARING
674
+ * AFTER W57-T21 DELETED THE EDIT DOOR. `useOverlayLayer` defers to a higher layer only when it
675
+ * can SEE one: `if (!dismissOnOutside || (stack && !stack.isTop(id))) return;`, where `stack`
676
+ * is `useContext(OverlayStackContext)`. The Sheet route mounts no provider of its own, so
677
+ * `LinkGridModal` would run with `stack === null` and read a pointerdown ANYWHERE outside its
678
+ * own card as a dismissal, including one inside a layer opened on top of it. The Export menu
679
+ * below is exactly such a layer, and so is every filter, field and sort popover the grid's own
680
+ * chrome opens now that the chrome is the only filter door. Both register here instead, the
681
+ * later one is topmost, and the card stands down while it is up. `filter-kit/SheetFilterPopup.tsx`
682
+ * documents the same trap one layer further out.
683
  *
684
  * ⛔ ESCAPE IS UNAFFECTED AND STILL RESOLVES TO EXACTLY ONE SURFACE. That is the module-level
685
+ * stack in `ui/useEscapeClose`, not this one: the card claims when it mounts, a popover claims
686
+ * when it opens and is therefore topmost, so one press closes the popover and the next closes
687
+ * the drill. The band claims nothing: it is a statement inside the card, not an overlay.
 
688
  */
689
  <OverlayProvider>
690
  <Suspense fallback={<DrillSkeleton label={label} nodeRef={skeletonRef} />}>
 
694
  recordIds={drill.record_ids}
695
  editable={false}
696
  cellView
697
+ cellFields={visibleKeys}
698
  // A view-bound cell passes neither prop: its rows remain the saved view's business.
699
  cellFilter={shownTree ?? undefined}
700
  onCellFilterChange={shownKind === "filter" ? settleCellFilter : undefined}
701
  headerActions={(
702
  <div className="sheet-cell-view-toolbar" role="toolbar" aria-label="Cell View controls">
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
703
  {canEditRows && (
704
  <button type="button" className="sheet-cell-view-action" onClick={editInData}>
705
  <svg viewBox="0 0 16 16" aria-hidden="true">
 
754
  ))}
755
  </AnchoredOverlay>
756
  )}
 
 
 
 
 
 
 
 
 
 
757
  </OverlayProvider>
758
  );
759
  }
web/src/sheet/KeyTips.tsx CHANGED
@@ -1,4 +1,4 @@
1
- // sheet/KeyTips.tsx — Excel-style Alt key tips over the Home ribbon (wave 52, W52-T17, owner
2
  // instruction 20, ruling R7; AutoWiki/waves/wave52/proto/excel-behaviour-spec.md Part B,
3
  // rules KT-1 through KT-21 and D-1/D-2/D-3/D-6/D-7).
4
  //
@@ -17,11 +17,11 @@
17
  // not active), this file swallows NOTHING — a bare keystroke reaches the grid exactly as before.
18
  //
19
  // ⛔ D-2/D-3 — BARE ALT, KEYDOWN-THEN-KEYUP, NOTHING ELSE PRESSED, UNDER 800ms, WINDOW FOCUSED.
20
- // This is NOT `Alt+letter` held as a chord (that belongs to the browser/OS — Alt+F/Alt+D/Alt+Tab
21
- // are never intercepted here). Every key that resolves a key-tip sequence once the layer is
22
- // active is a PLAIN unmodified keypress, typed one after another with Alt already released. The
23
- // pending-Alt state is cleared on `blur` and `visibilitychange` so an Alt-tab away and back never
24
- // leaves a stray toggle armed.
25
  //
26
  // ⭐ KT-10/11/12 — TWO CASES, TOLD APART BY `data-kt-opens`, NEVER GUESSED FROM STRING LENGTH. A
27
  // badge with no `data-kt-opens` is PREFIX-MATCHED (`FS` fires only once both `F` and `S` land;
@@ -30,9 +30,9 @@
30
  // fresh badge set from whatever `.sheet-ribbon-pop` is now open (KT-11).
31
  //
32
  // ⚠ SCOPE, STATED HONESTLY (the ticket's own "best effort" clause for the third level). The first
33
- // two levels — Alt -> Home tab badge, H -> every Home control badge, prefix match, Left/Right and
34
- // Enter nav, Escape/Alt exit — are built to the full spec. Wave 55 gives Up/Down back to the grid
35
- // immediately. The THIRD level (inside an opened gallery) is
36
  // exercised to full fidelity for Borders only (`Ribbon.tsx`'s `BORDERS` array now carries its own
37
  // one-letter `data-kt` per entry, plus "No border"). Every OTHER gallery (Insert, Delete, Format,
38
  // Clear, Fill/Text colour, Font size, Number format) still gets Escape-to-close and generic
@@ -80,8 +80,8 @@ function isTextChar(key: string): boolean {
80
  * old code marked the press a chord, refused to activate, and the whole sequence died: measured
81
  * 0 of 5 held runs against 5 of 5 sequential runs, headless Chromium, 2026-09-06.
82
  * This predicate is what keeps the fix narrow. A held Alt plus a letter only becomes a key-tip
83
- * activation when that letter names a live FIRST-LEVEL badge (today: H for Home), so every other
84
- * Alt chord the browser owns (Alt+D, Alt+F, Alt+Left) is never touched. */
85
  function isFirstLevelCode(container: HTMLElement | null, ch: string): boolean {
86
  return getTargets(container, "tabs").some((t) => t.code.startsWith(ch));
87
  }
@@ -111,11 +111,17 @@ function pressFeedback(el: HTMLElement): void {
111
  }, PRESS_MS);
112
  }
113
 
114
- /** Every `[data-kt]` element visible AT THIS DEPTH, with its badge code. */
 
 
 
 
 
 
115
  function getTargets(container: HTMLElement | null, depth: Depth): Target[] {
116
  if (!container) return [];
117
  if (depth === "tabs") {
118
- return collect(container.querySelectorAll<HTMLButtonElement>('[data-ribbon="tab-home"][data-kt]'));
119
  }
120
  if (depth === "gallery") {
121
  const openPop = (container.querySelector<HTMLElement>(".sheet-ribbon-pop")
@@ -129,7 +135,7 @@ function getTargets(container: HTMLElement | null, depth: Depth): Target[] {
129
  ?? document.querySelector<HTMLElement>(".sheet-ribbon-pop"));
130
  return openPop ? collect(openPop.querySelectorAll<HTMLButtonElement>("[data-kt]")) : [];
131
  }
132
- return collect(container.querySelectorAll<HTMLButtonElement>('[data-kt]:not([data-ribbon="tab-home"])'));
133
  }
134
 
135
  function collect(list: NodeListOf<HTMLButtonElement>): Target[] {
@@ -214,8 +220,10 @@ export default function KeyTips({ containerRef }: KeyTipsProps) {
214
  const opener = containerRef.current?.querySelector<HTMLButtonElement>(
215
  '[data-kt-opens="gallery"][aria-expanded="true"]',
216
  );
 
 
217
  opener?.click();
218
- setKt({ depth: "home", prefix: "", focusedIdx: 0 });
219
  requestAnimationFrame(() => opener?.focus());
220
  return;
221
  }
@@ -233,16 +241,20 @@ export default function KeyTips({ containerRef }: KeyTipsProps) {
233
  deactivateAll();
234
  }, [containerRef, deactivateAll, setKt]);
235
 
236
- /** Fires (or opens) the matched control. `depth === "tabs"` is the ONE case that transitions
237
- * rather than exits: pressing H never fires an act, it reveals the Home controls (KT-8/KT-9).
238
  */
239
  const activate = useCallback((el: HTMLButtonElement) => {
240
  const st = stateRef.current;
241
  pressFeedback(el); // W54-T24: the pressed look lands on the same tick as the command
242
- if (st.depth === "tabs") {
243
  el.click();
244
  setKt({ depth: "home", prefix: "", focusedIdx: 0 });
245
- requestAnimationFrame(() => navElements(containerRef.current, "home", "")[0]?.focus());
 
 
 
 
246
  return;
247
  }
248
  if (el.dataset.ktOpens === "gallery") {
@@ -255,7 +267,7 @@ export default function KeyTips({ containerRef }: KeyTipsProps) {
255
  // and the keyboard returns to wherever it was before Alt was first pressed.
256
  el.click();
257
  deactivateAll();
258
- }, [containerRef, deactivateAll, setKt]);
259
 
260
  const handleCharacter = useCallback((ch: string) => {
261
  const st = stateRef.current;
 
1
+ // sheet/KeyTips.tsx - Excel-style Alt key tips over the sheet ribbon (wave 52, W52-T17, owner
2
  // instruction 20, ruling R7; AutoWiki/waves/wave52/proto/excel-behaviour-spec.md Part B,
3
  // rules KT-1 through KT-21 and D-1/D-2/D-3/D-6/D-7).
4
  //
 
17
  // not active), this file swallows NOTHING — a bare keystroke reaches the grid exactly as before.
18
  //
19
  // ⛔ D-2/D-3 — BARE ALT, KEYDOWN-THEN-KEYUP, NOTHING ELSE PRESSED, UNDER 800ms, WINDOW FOCUSED.
20
+ // A bare press toggles the layer; held Alt plus a live first-level letter also enters its path
21
+ // (W54-T24). Other Alt chords belong to the browser/OS; Alt+F/Alt+D/Alt+Tab are never intercepted
22
+ // while idle. Once active, letters resolve the key-tip sequence in order. The pending-Alt state
23
+ // is cleared on `blur` and `visibilitychange` so an Alt-tab away and back never leaves a stray
24
+ // toggle armed.
25
  //
26
  // ⭐ KT-10/11/12 — TWO CASES, TOLD APART BY `data-kt-opens`, NEVER GUESSED FROM STRING LENGTH. A
27
  // badge with no `data-kt-opens` is PREFIX-MATCHED (`FS` fires only once both `F` and `S` land;
 
30
  // fresh badge set from whatever `.sheet-ribbon-pop` is now open (KT-11).
31
  //
32
  // ⚠ SCOPE, STATED HONESTLY (the ticket's own "best effort" clause for the third level). The first
33
+ // two levels show the tab strip's badges, then ONLY the chosen tab's group controls, with prefix
34
+ // match, Left/Right and Enter nav, and Escape/Alt exit. Strip actions use their own gallery/leaf
35
+ // path. Wave 55 gives Up/Down back to the grid immediately. The gallery level is
36
  // exercised to full fidelity for Borders only (`Ribbon.tsx`'s `BORDERS` array now carries its own
37
  // one-letter `data-kt` per entry, plus "No border"). Every OTHER gallery (Insert, Delete, Format,
38
  // Clear, Fill/Text colour, Font size, Number format) still gets Escape-to-close and generic
 
80
  * old code marked the press a chord, refused to activate, and the whole sequence died: measured
81
  * 0 of 5 held runs against 5 of 5 sequential runs, headless Chromium, 2026-09-06.
82
  * This predicate is what keeps the fix narrow. A held Alt plus a letter only becomes a key-tip
83
+ * activation when that letter names a live FIRST-LEVEL badge in the tab strip (tabs and actions),
84
+ * so every other Alt chord the browser owns (Alt+D, Alt+F, Alt+Left) is never touched. */
85
  function isFirstLevelCode(container: HTMLElement | null, ch: string): boolean {
86
  return getTargets(container, "tabs").some((t) => t.code.startsWith(ch));
87
  }
 
111
  }, PRESS_MS);
112
  }
113
 
114
+ /** Every `[data-kt]` element visible AT THIS DEPTH, with its badge code. Each depth is
115
+ * scoped to the DOM region that owns it: the tab strip, the active tab's group row, or
116
+ * the open gallery.
117
+ * ⚠ `verify_grid_ux.py::w54_t24_speed_shape` slices this file from `pressFeedback` up to
118
+ * the words "Every `[data-kt]` element", so this comment is a GATE ANCHOR: reword the rest
119
+ * of the sentence freely, never that phrase. Measured W57-T08: rewriting the whole line
120
+ * raised `ValueError: substring not found` and the gate died mid-run. */
121
  function getTargets(container: HTMLElement | null, depth: Depth): Target[] {
122
  if (!container) return [];
123
  if (depth === "tabs") {
124
+ return collect(container.querySelectorAll<HTMLButtonElement>(".sheet-ribbon-tabs [data-kt]"));
125
  }
126
  if (depth === "gallery") {
127
  const openPop = (container.querySelector<HTMLElement>(".sheet-ribbon-pop")
 
135
  ?? document.querySelector<HTMLElement>(".sheet-ribbon-pop"));
136
  return openPop ? collect(openPop.querySelectorAll<HTMLButtonElement>("[data-kt]")) : [];
137
  }
138
+ return collect(container.querySelectorAll<HTMLButtonElement>(".sheet-ribbon-scroll [data-kt]"));
139
  }
140
 
141
  function collect(list: NodeListOf<HTMLButtonElement>): Target[] {
 
220
  const opener = containerRef.current?.querySelector<HTMLButtonElement>(
221
  '[data-kt-opens="gallery"][aria-expanded="true"]',
222
  );
223
+ // Galleries can open from either level, so the opener's DOM location determines where Escape returns.
224
+ const depth = opener?.closest(".sheet-ribbon-tabs") ? "tabs" : "home";
225
  opener?.click();
226
+ setKt({ depth, prefix: "", focusedIdx: 0 });
227
  requestAnimationFrame(() => opener?.focus());
228
  return;
229
  }
 
241
  deactivateAll();
242
  }, [containerRef, deactivateAll, setKt]);
243
 
244
+ /** A first-level tab reveals its own group controls (KT-8/KT-9); strip actions follow the
245
+ * same gallery/leaf handling as group controls.
246
  */
247
  const activate = useCallback((el: HTMLButtonElement) => {
248
  const st = stateRef.current;
249
  pressFeedback(el); // W54-T24: the pressed look lands on the same tick as the command
250
+ if (st.depth === "tabs" && el.dataset.ribbon?.startsWith("tab-")) {
251
  el.click();
252
  setKt({ depth: "home", prefix: "", focusedIdx: 0 });
253
+ requestAnimationFrame(() => {
254
+ navElements(containerRef.current, "home", "")[0]?.focus();
255
+ // Re-read badge targets after React replaces the active tab's group row.
256
+ bump();
257
+ });
258
  return;
259
  }
260
  if (el.dataset.ktOpens === "gallery") {
 
267
  // and the keyboard returns to wherever it was before Alt was first pressed.
268
  el.click();
269
  deactivateAll();
270
+ }, [bump, containerRef, deactivateAll, setKt]);
271
 
272
  const handleCharacter = useCallback((ch: string) => {
273
  const st = stateRef.current;
web/src/sheet/Ribbon.tsx CHANGED
@@ -64,6 +64,9 @@ import {
64
  // own `import "./filters.css"`. See the stylesheet's own header for why this is not an
65
  // `index.css` `@import` line.
66
  import "../styles/wave52/ribbon.css";
 
 
 
67
  // ⭐⭐ W54 base kit 2a — THE REGISTERED TABS. Each module exports its own descriptor and its own
68
  // control keys; this file imports them and nothing else from either.
69
  import { HOME_TAB } from "./ribbonHome";
@@ -87,6 +90,9 @@ import KeyTips from "./KeyTips";
87
  // import stays here where both tabs inherit it.
88
  import "../styles/wave53/ribbon-pop.css";
89
 
 
 
 
90
  /**
91
  * ⭐⭐ THE ACT VOCABULARY, CLOSED. W51-T16 builds against this union and nothing else; adding a
92
  * control means adding its name here first, which is exactly the review moment that was missing
@@ -272,6 +278,9 @@ export interface RibbonTabContext {
272
  /** View-only state owned by the ribbon shell, with no new document or SheetGrid action. */
273
  fullscreen: boolean;
274
  toggleFullscreen: () => void;
 
 
 
275
  formulaBarVisible: boolean;
276
  toggleFormulaBar: () => void;
277
  openPop: (which: Popover) => (event: ReactMouseEvent<HTMLButtonElement>) => void;
@@ -375,11 +384,12 @@ function IconFullScreen() {
375
  );
376
  }
377
 
378
- /** The collapse chevron. It points UP while the row is showing, because that is where it goes. */
379
- function IconChevron({ up }: { up: boolean }) {
 
380
  return (
381
  <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon">
382
- <path d={up ? "M4.5 9.5L8 6l3.5 3.5" : "M4.5 6.5L8 10l3.5 -3.5"} />
383
  </svg>
384
  );
385
  }
@@ -414,6 +424,9 @@ export default function Ribbon({
414
  const [collapsed, setCollapsed] = useState<boolean>(readCollapsed);
415
  const [formulaBarVisible, setFormulaBarVisible] = useState<boolean>(readFormulaBar);
416
  const rootRef = useRef<HTMLDivElement | null>(null);
 
 
 
417
 
418
  useEffect(() => {
419
  const wrap = rootRef.current?.closest<HTMLElement>(".sheet-grid-wrap");
@@ -433,6 +446,48 @@ export default function Ribbon({
433
  const [active, setActive] = useState<TabId>(TABS[0].id);
434
  const activeTab = TABS.find((tab) => tab.id === active) ?? TABS[0];
435
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
436
  /**
437
  * The keys the arrows may reach right now. Collapsed, that is the strip and nothing else — and
438
  * the strip now carries Import, Refresh, Export and Full screen too.
@@ -500,6 +555,27 @@ export default function Ribbon({
500
  });
501
  }, []);
502
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
503
  // ⭐⭐ W53-T07 — THE HAND-ROLLED OUTSIDE-PRESS LISTENER IS GONE, AND ITS REASON SURVIVED THE
504
  // DELETION. It read: *"a popover closes on an outside press, and on `mousedown` rather than
505
  // `click`, because a click listener fires after the grid canvas has already taken focus and
@@ -720,6 +796,7 @@ export default function Ribbon({
720
  const tabContext: RibbonTabContext = {
721
  style, frozen, open, anchorEl, onApply, apply, act,
722
  fullscreen, toggleFullscreen, formulaBarVisible, toggleFormulaBar,
 
723
  openPop, closePop, control, group, word, unavailable, item, insert,
724
  };
725
 
@@ -771,11 +848,11 @@ export default function Ribbon({
771
  ariaLabel="Export workbook"
772
  dataKind="sheet-export"
773
  >
774
- <span className="sheet-ribbon-label">
775
  {`Ready to export ${exportRangeName}, ${exportRowCount} ${exportRowCount === 1 ? "row" : "rows"}`}
776
  </span>
777
  {exportRange.truncated && (
778
- <span className="sheet-ribbon-label">
779
  {`Only the first ${SHEET_EXPORT_SCAN_LIMIT.cols} columns and `}
780
  {`${SHEET_EXPORT_SCAN_LIMIT.rows.toLocaleString()} rows were scanned, so a `}
781
  {"larger sheet may hold cells this file does not include."}
@@ -787,6 +864,7 @@ export default function Ribbon({
787
  exportScope === "sheet", "menuitemradio", "W")}
788
  {item("Selection", () => setExportScope("selection"),
789
  exportScope === "selection", "menuitemradio", "S")}
 
790
  </>
791
  )}
792
  {EXPORT_FORMATS.map(({ format, label }) => item(label, () => {
@@ -816,7 +894,7 @@ export default function Ribbon({
816
  onMouseDown={(e) => e.preventDefault()}
817
  onClick={toggleCollapsed}
818
  >
819
- <IconChevron up={!collapsed} />
820
  </button>
821
  </div>
822
 
@@ -826,15 +904,42 @@ export default function Ribbon({
826
  role="toolbar"
827
  aria-label={activeTab.toolbarLabel}
828
  >
 
 
 
 
 
 
 
 
 
 
 
 
 
 
829
  {/* ⛔ `min-width: 0` ON THE SCROLLER IS LOAD BEARING. A flex child will not scroll
830
  without it. Import, Refresh, Export and Full screen do not live in this row
831
  (W52-T15 moved them to the tab strip above), so the only thing that can walk off
832
  the right edge at a narrow window now is a group itself, which scrolling permits. */}
833
- <div className="sheet-ribbon-scroll">
834
  {/* ⭐⭐ THE ACTIVE TAB'S OWN GROUPS. `ribbonHome.tsx` holds every one of them, in R8's
835
  order, and this is the whole of the shell's knowledge of what they are. */}
836
  {activeTab.groups(tabContext)}
837
  </div>
 
 
 
 
 
 
 
 
 
 
 
 
 
838
  </div>
839
  )}
840
  {/* ⭐⭐ W52-T17 (instruction 20, ruling R7) — mounted ONCE, absolutely positioned via its own
 
64
  // own `import "./filters.css"`. See the stylesheet's own header for why this is not an
65
  // `index.css` `@import` line.
66
  import "../styles/wave52/ribbon.css";
67
+ import "../styles/wave57/sheet-fullscreen.css";
68
+ import "../styles/wave57/ribbon-view.css";
69
+ import "../styles/wave57/ribbon-export.css";
70
  // ⭐⭐ W54 base kit 2a — THE REGISTERED TABS. Each module exports its own descriptor and its own
71
  // control keys; this file imports them and nothing else from either.
72
  import { HOME_TAB } from "./ribbonHome";
 
90
  // import stays here where both tabs inherit it.
91
  import "../styles/wave53/ribbon-pop.css";
92
 
93
+ /** Opens the active cell's binding editor through SheetPage's document listener. */
94
+ export const OPEN_CELL_DATA_EVENT = "aios:sheet-open-cell-data";
95
+
96
  /**
97
  * ⭐⭐ THE ACT VOCABULARY, CLOSED. W51-T16 builds against this union and nothing else; adding a
98
  * control means adding its name here first, which is exactly the review moment that was missing
 
278
  /** View-only state owned by the ribbon shell, with no new document or SheetGrid action. */
279
  fullscreen: boolean;
280
  toggleFullscreen: () => void;
281
+ newWindowBlocked: boolean;
282
+ openNewWindow: () => void;
283
+ openCellData: () => void;
284
  formulaBarVisible: boolean;
285
  toggleFormulaBar: () => void;
286
  openPop: (which: Popover) => (event: ReactMouseEvent<HTMLButtonElement>) => void;
 
384
  );
385
  }
386
 
387
+ /** One chevron drawing serves collapse and horizontal scrolling through rotation. */
388
+ function IconChevron({ direction }: { direction: "up" | "down" | "left" | "right" }) {
389
+ const rotation = { up: 0, down: 180, left: -90, right: 90 }[direction];
390
  return (
391
  <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon">
392
+ <path d="M4.5 9.5L8 6l3.5 3.5" transform={`rotate(${rotation} 8 8)`} />
393
  </svg>
394
  );
395
  }
 
424
  const [collapsed, setCollapsed] = useState<boolean>(readCollapsed);
425
  const [formulaBarVisible, setFormulaBarVisible] = useState<boolean>(readFormulaBar);
426
  const rootRef = useRef<HTMLDivElement | null>(null);
427
+ const scrollRef = useRef<HTMLDivElement | null>(null);
428
+ const [canScrollLeft, setCanScrollLeft] = useState(false);
429
+ const [canScrollRight, setCanScrollRight] = useState(false);
430
 
431
  useEffect(() => {
432
  const wrap = rootRef.current?.closest<HTMLElement>(".sheet-grid-wrap");
 
446
  const [active, setActive] = useState<TabId>(TABS[0].id);
447
  const activeTab = TABS.find((tab) => tab.id === active) ?? TABS[0];
448
 
449
+ useEffect(() => {
450
+ const scroller = scrollRef.current;
451
+ if (!scroller) {
452
+ setCanScrollLeft(false);
453
+ setCanScrollRight(false);
454
+ return;
455
+ }
456
+ const updateScrollAvailability = () => {
457
+ const toolbar = scroller.parentElement;
458
+ const toolbarStyle = toolbar ? window.getComputedStyle(toolbar) : null;
459
+ // Measure the full row so the chevrons cannot keep a fitting tab overflowing by themselves.
460
+ const fullWidth = toolbar && toolbarStyle
461
+ ? toolbar.clientWidth - parseFloat(toolbarStyle.paddingLeft)
462
+ - parseFloat(toolbarStyle.paddingRight)
463
+ : scroller.clientWidth;
464
+ const overflows = scroller.scrollWidth > fullWidth + 1;
465
+ setCanScrollLeft(overflows && scroller.scrollLeft > 1);
466
+ setCanScrollRight(overflows
467
+ && scroller.scrollLeft + scroller.clientWidth < scroller.scrollWidth - 1);
468
+ };
469
+ updateScrollAvailability();
470
+ scroller.addEventListener("scroll", updateScrollAvailability, { passive: true });
471
+ window.addEventListener("resize", updateScrollAvailability);
472
+ const observer = typeof ResizeObserver === "undefined"
473
+ ? null : new ResizeObserver(updateScrollAvailability);
474
+ observer?.observe(scroller);
475
+ return () => {
476
+ scroller.removeEventListener("scroll", updateScrollAvailability);
477
+ window.removeEventListener("resize", updateScrollAvailability);
478
+ observer?.disconnect();
479
+ };
480
+ }, [active, collapsed]);
481
+
482
+ const scrollGroups = (direction: -1 | 1) => {
483
+ const scroller = scrollRef.current;
484
+ if (!scroller) return;
485
+ scroller.scrollBy({
486
+ left: direction * scroller.clientWidth * 0.8,
487
+ behavior: window.matchMedia("(prefers-reduced-motion: reduce)").matches ? "auto" : "smooth",
488
+ });
489
+ };
490
+
491
  /**
492
  * The keys the arrows may reach right now. Collapsed, that is the strip and nothing else — and
493
  * the strip now carries Import, Refresh, Export and Full screen too.
 
555
  });
556
  }, []);
557
 
558
+ const [newWindowBlocked, setNewWindowBlocked] = useState(false);
559
+ const openNewWindow = useCallback(() => {
560
+ // The noopener feature also returns null on success. Open a blank window to detect a
561
+ // real refusal, then detach its opener before any workbook code can load.
562
+ const nextWindow = window.open("about:blank", "_blank", "popup");
563
+ if (!nextWindow) {
564
+ setNewWindowBlocked(true);
565
+ return;
566
+ }
567
+ nextWindow.opener = null;
568
+ nextWindow.location.replace(window.location.href);
569
+ setNewWindowBlocked(false);
570
+ }, []);
571
+
572
+ const openCellData = useCallback(() => {
573
+ // The ribbon lives in SheetGrid's DOM, so a bubbling event on the shared document reaches
574
+ // SheetPage's listener. RibbonInsertDoor cannot carry this callback: its constructor is in
575
+ // another lane's SheetGrid.tsx, which this ticket cannot edit.
576
+ document.dispatchEvent(new CustomEvent(OPEN_CELL_DATA_EVENT, { bubbles: true }));
577
+ }, []);
578
+
579
  // ⭐⭐ W53-T07 — THE HAND-ROLLED OUTSIDE-PRESS LISTENER IS GONE, AND ITS REASON SURVIVED THE
580
  // DELETION. It read: *"a popover closes on an outside press, and on `mousedown` rather than
581
  // `click`, because a click listener fires after the grid canvas has already taken focus and
 
796
  const tabContext: RibbonTabContext = {
797
  style, frozen, open, anchorEl, onApply, apply, act,
798
  fullscreen, toggleFullscreen, formulaBarVisible, toggleFormulaBar,
799
+ newWindowBlocked, openNewWindow, openCellData,
800
  openPop, closePop, control, group, word, unavailable, item, insert,
801
  };
802
 
 
848
  ariaLabel="Export workbook"
849
  dataKind="sheet-export"
850
  >
851
+ <span className="sheet-ribbon-export-caption">
852
  {`Ready to export ${exportRangeName}, ${exportRowCount} ${exportRowCount === 1 ? "row" : "rows"}`}
853
  </span>
854
  {exportRange.truncated && (
855
+ <span className="sheet-ribbon-export-caption">
856
  {`Only the first ${SHEET_EXPORT_SCAN_LIMIT.cols} columns and `}
857
  {`${SHEET_EXPORT_SCAN_LIMIT.rows.toLocaleString()} rows were scanned, so a `}
858
  {"larger sheet may hold cells this file does not include."}
 
864
  exportScope === "sheet", "menuitemradio", "W")}
865
  {item("Selection", () => setExportScope("selection"),
866
  exportScope === "selection", "menuitemradio", "S")}
867
+ <span className="sheet-ribbon-export-separator" role="separator" />
868
  </>
869
  )}
870
  {EXPORT_FORMATS.map(({ format, label }) => item(label, () => {
 
894
  onMouseDown={(e) => e.preventDefault()}
895
  onClick={toggleCollapsed}
896
  >
897
+ <IconChevron direction={collapsed ? "down" : "up"} />
898
  </button>
899
  </div>
900
 
 
904
  role="toolbar"
905
  aria-label={activeTab.toolbarLabel}
906
  >
907
+ {/* Scroll buttons stay outside the roving order because keyboard focus already scrolls controls into view. */}
908
+ {canScrollLeft && (
909
+ <button
910
+ type="button"
911
+ className="sheet-ribbon-scroll-button"
912
+ aria-label="Scroll ribbon left"
913
+ title="Scroll ribbon left"
914
+ tabIndex={-1}
915
+ onMouseDown={(e) => e.preventDefault()}
916
+ onClick={() => scrollGroups(-1)}
917
+ >
918
+ <IconChevron direction="left" />
919
+ </button>
920
+ )}
921
  {/* ⛔ `min-width: 0` ON THE SCROLLER IS LOAD BEARING. A flex child will not scroll
922
  without it. Import, Refresh, Export and Full screen do not live in this row
923
  (W52-T15 moved them to the tab strip above), so the only thing that can walk off
924
  the right edge at a narrow window now is a group itself, which scrolling permits. */}
925
+ <div className="sheet-ribbon-scroll" ref={scrollRef}>
926
  {/* ⭐⭐ THE ACTIVE TAB'S OWN GROUPS. `ribbonHome.tsx` holds every one of them, in R8's
927
  order, and this is the whole of the shell's knowledge of what they are. */}
928
  {activeTab.groups(tabContext)}
929
  </div>
930
+ {canScrollRight && (
931
+ <button
932
+ type="button"
933
+ className="sheet-ribbon-scroll-button"
934
+ aria-label="Scroll ribbon right"
935
+ title="Scroll ribbon right"
936
+ tabIndex={-1}
937
+ onMouseDown={(e) => e.preventDefault()}
938
+ onClick={() => scrollGroups(1)}
939
+ >
940
+ <IconChevron direction="right" />
941
+ </button>
942
+ )}
943
  </div>
944
  )}
945
  {/* ⭐⭐ W52-T17 (instruction 20, ruling R7) — mounted ONCE, absolutely positioned via its own
web/src/sheet/SheetGrid.tsx CHANGED
@@ -142,7 +142,7 @@ import { RulesDialog, ValidationDialog } from "./RulesDialog";
142
  import ChartDialog from "./ChartDialog";
143
  import SheetChartLayer from "./SheetChartLayer";
144
  import ShortcutsPanel from "./ShortcutsPanel";
145
- import { colToIndex, indexToCol } from "./a1";
146
  // ⛔⛔ W51-T18 — THE RULE ENGINE AND THE VALIDATION CHECKER ARE PURE AND SHEET LOCAL, and that is
147
  // what lets `verify_api.py` compile them beside `sheetState.js` and EXECUTE the ten operators
148
  // rather than grep for their names. This component is the only place their answers meet a canvas.
@@ -196,7 +196,7 @@ import type { SavedViewShadow } from "./bindingRefs";
196
  // ⛔⛔ W51-T17 — ONE TABLE, TWO CONSUMERS. `shortcuts.ts` is the key map AND the panel's rows, and
197
  // it imports NOTHING: see its head note on tsc's emitted root. This file matches against it and
198
  // `ShortcutsPanel.tsx` renders it, so the two cannot advertise different keys.
199
- import { arrowStep, columnBand, commitDirection, commitTarget, edgeIndex, edgeStart,
200
  extendEdgeRect, isArrowKey, KEY_TIP_GRID_ARROW_EVENT, keyTipGridArrow, matchShortcut,
201
  rowBand, shortcutOwner, structureAxis, tabRunOrigin } from "./shortcuts";
202
  import type { SelectionAxis, SelectionRect, ShortcutId } from "./shortcuts";
@@ -541,6 +541,23 @@ function pointRangeText(a: { col: number; row: number }, b: { col: number; row:
541
  return `${pointAddr({ col: col0, row: row0 })}:${pointAddr({ col: col1, row: row1 })}`;
542
  }
543
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
544
  /** What the right-click menu is open ON: a whole column, or the row and column of one cell. */
545
  interface SheetMenu {
546
  anchor: ReturnType<typeof rectAnchor>;
@@ -608,12 +625,17 @@ interface FormulaEditState {
608
  /** FA-23 #1: the dropdown is closed without touching `draft` (see `FormulaAssist`'s own note). */
609
  dismissed: boolean;
610
  mode: "enter" | "point";
 
 
611
  /** PM-4's anchor: the EDITING cell, real 1-based coordinates. Never the selection. */
612
  anchor: RealCell;
613
  /** Where in `draft` the live point-mode reference text starts, for PM-5's replace-not-append. */
614
  insertStart: number | null;
615
  /** The single proposed cell while no Shift range is open. */
616
  pointCell: RealCell | null;
 
 
 
617
  /** PM-7's range anchor once Shift extends the proposal; null outside a range. */
618
  rangeAnchor: RealCell | null;
619
  }
@@ -1503,8 +1525,8 @@ export default function SheetGrid({
1503
  setMenu(null);
1504
  setDropdown(null);
1505
  setFormulaEdit({
1506
- addr, inBand, viewCell, draft, caret, dropdownIndex: 0, dismissed: false, mode: "enter",
1507
- anchor, insertStart: null, pointCell: null, rangeAnchor: null,
1508
  });
1509
  }, []);
1510
 
@@ -1588,21 +1610,40 @@ export default function SheetGrid({
1588
  * PM-4/PM-5/PM-7/PM-8: every point-mode proposal, arrived at from either the anchor (a fresh
1589
  * arrow press) or the previous proposal (a continued one), goes through this ONE splice so
1590
  * "insert" and "replace the last insert" are the same code path rather than two that can drift.
 
 
1591
  */
1592
- const proposeCell = useCallback((target: RealCell, shift: boolean) => {
 
 
 
 
 
 
 
 
 
 
1593
  if (!formulaEdit) return;
1594
  const insertStart = formulaEdit.mode === "point" && formulaEdit.insertStart !== null
1595
  ? formulaEdit.insertStart : formulaEdit.caret;
1596
  const oldLen = formulaEdit.mode === "point" ? formulaEdit.caret - insertStart : 0;
 
 
 
1597
  const rangeAnchor = shift
1598
- ? (formulaEdit.rangeAnchor ?? (formulaEdit.mode === "point" ? formulaEdit.pointCell : target))
 
1599
  : null;
1600
- const text = rangeAnchor ? pointRangeText(rangeAnchor, target) : pointAddr(target);
 
 
1601
  const draft = formulaEdit.draft.slice(0, insertStart) + text
1602
  + formulaEdit.draft.slice(insertStart + oldLen);
1603
  const caret = insertStart + text.length;
1604
  setFormulaEdit({
1605
  ...formulaEdit, draft, caret, insertStart, mode: "point", pointCell: target, rangeAnchor,
 
1606
  });
1607
  // PM-6: the grid scrolls to keep the proposal visible. Best effort on the MAIN grid only --
1608
  // a proposal inside the frozen band is permanently on screen by construction (R17).
@@ -1610,7 +1651,7 @@ export default function SheetGrid({
1610
  const viewRow = viewRowOf(target.row - 1);
1611
  if (viewRow >= 0) gridRef.current?.scrollTo(viewIndexOf(visCols, target.col - 1), viewRow);
1612
  }
1613
- }, [formulaEdit, viewRowOf, visCols]);
1614
 
1615
  /** PM-9/PM-10/PM-11: `,`/`(`/`)` commit the live reference as literal text and leave point mode. */
1616
  const commitPointReference = useCallback((trailer: string) => {
@@ -1619,7 +1660,7 @@ export default function SheetGrid({
1619
  + formulaEdit.draft.slice(formulaEdit.caret);
1620
  setFormulaEdit({
1621
  ...formulaEdit, draft, caret: formulaEdit.caret + trailer.length,
1622
- mode: "enter", pointCell: null, rangeAnchor: null, insertStart: null,
1623
  });
1624
  }, [formulaEdit]);
1625
 
@@ -1693,17 +1734,80 @@ export default function SheetGrid({
1693
 
1694
  const onFormulaKeyDown = useCallback((e: ReactKeyboardEvent<HTMLInputElement>) => {
1695
  if (!formulaEdit) return;
1696
- const { draft, caret, mode } = formulaEdit;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1697
 
1698
  if (formulaDropdownOpen) {
1699
- if (e.key === "ArrowDown") {
1700
  e.preventDefault();
1701
  setFormulaEdit({
1702
  ...formulaEdit, dropdownIndex: (formulaEdit.dropdownIndex + 1) % formulaSuggestions.length,
1703
  });
1704
  return;
1705
  }
1706
- if (e.key === "ArrowUp") {
1707
  e.preventDefault();
1708
  setFormulaEdit({
1709
  ...formulaEdit,
@@ -1747,8 +1851,29 @@ export default function SheetGrid({
1747
  return;
1748
  }
1749
 
 
 
 
 
 
 
 
 
 
 
 
 
1750
  if (mode === "point") {
1751
  if (ARROW_DELTA[e.key]) {
 
 
 
 
 
 
 
 
 
1752
  e.preventDefault();
1753
  const dir = ARROW_DELTA[e.key];
1754
  const from = formulaEdit.pointCell ?? formulaEdit.anchor;
@@ -1772,13 +1897,18 @@ export default function SheetGrid({
1772
  // PM-14: any other typed character leaves point mode and is inserted literally. No
1773
  // `preventDefault` -- the browser's own keystroke does the inserting.
1774
  setFormulaEdit({
1775
- ...formulaEdit, mode: "enter", pointCell: null, rangeAnchor: null, insertStart: null,
1776
  });
1777
  return;
1778
  }
1779
- if (e.key === "Backspace" || e.key === "Delete") {
 
 
 
 
 
1780
  setFormulaEdit({
1781
- ...formulaEdit, mode: "enter", pointCell: null, rangeAnchor: null, insertStart: null,
1782
  });
1783
  }
1784
  return;
@@ -1786,7 +1916,7 @@ export default function SheetGrid({
1786
 
1787
  // PM-4: an arrow key at a legal reference position starts point mode, anchored on the
1788
  // EDITING cell (never the grid's own selection).
1789
- if (ARROW_DELTA[e.key] && isRefPosition(draft, caret)) {
1790
  e.preventDefault();
1791
  const dir = ARROW_DELTA[e.key];
1792
  proposeCell(
@@ -1802,8 +1932,9 @@ export default function SheetGrid({
1802
  // is capture phase on the document and stops propagation, so a branch here could never fire
1803
  // anyway - it would be dead code that a later reader would trust.
1804
  }, [
1805
- acceptFormulaSuggestion, clampCol, clampRow, commitFormulaEditor,
1806
- commitPointReference, formulaDropdownOpen, formulaEdit, formulaSuggestions, proposeCell,
 
1807
  ]);
1808
 
1809
  // The caret has to land where `formulaEdit.caret` says on every mutation, which React does not
@@ -1844,11 +1975,18 @@ export default function SheetGrid({
1844
  : (selected?.cell?.kind === "formula" ? (selected.cell.formula ?? "") : "");
1845
  if (!source) return out;
1846
  for (const ref of refsIn(source)) {
1847
- const c0 = colToIndex(ref.start.col);
1848
- const c1 = colToIndex(ref.end.col);
1849
- const r0 = ref.start.row;
1850
- const r1 = ref.end.row;
1851
- // A pathological typed range (a whole-column reference, say) must not stall a paint.
 
 
 
 
 
 
 
1852
  if ((Math.abs(c1 - c0) + 1) * (Math.abs(r1 - r0) + 1) > 4000) continue;
1853
  const color = colorForSlot(ref.colorIndex, "light");
1854
  for (let c = Math.min(c0, c1); c <= Math.max(c0, c1); c += 1) {
@@ -1880,11 +2018,20 @@ export default function SheetGrid({
1880
  * cannot say WHICH of its references is the live one: `=F6+F6` has two occurrences of the same
1881
  * text and only one of them is under the arrow keys.
1882
  */
 
 
1883
  const formulaPointCells = useMemo(() => {
1884
  const out = new Set<string>();
1885
  if (!formulaEdit || formulaEdit.mode !== "point" || !formulaEdit.pointCell) return out;
1886
- const a = formulaEdit.rangeAnchor ?? formulaEdit.pointCell;
1887
- const b = formulaEdit.pointCell;
 
 
 
 
 
 
 
1888
  // The same cap `formulaRefCells` uses: a pathological proposal must not stall a paint.
1889
  if ((Math.abs(b.col - a.col) + 1) * (Math.abs(b.row - a.row) + 1) > 4000) return out;
1890
  for (let c = Math.min(a.col, b.col); c <= Math.max(a.col, b.col); c += 1) {
@@ -2233,6 +2380,10 @@ export default function SheetGrid({
2233
  // feature. The block is screened against the validation the TARGET already carries, the
2234
  // allowed cells land, and every refusal is named in one sentence rather than forty.
2235
  landFill(out, true);
 
 
 
 
2236
  // ⭐ W52-T07: the WHOLE destination range, not just the anchor `target` glide handed over —
2237
  // `values`' own shape (rows outer, cols inner) IS that range's size.
2238
  setPasteHighlight({ col: realCol(target[0]), row: realRow(target[1]),
@@ -2274,6 +2425,10 @@ export default function SheetGrid({
2274
  // ⛔ W51-T18 / C2 — AND THE FILL IS THE SECOND DOOR. Dragging a value down a column lands
2275
  // it on every cell it passes, list or no list, so it is screened exactly as the paste is.
2276
  landFill(out, true);
 
 
 
 
2277
  },
2278
  [cellValueGetter, landFill, options, realCol, realRow, tab, viewShadows],
2279
  );
@@ -2852,6 +3007,10 @@ export default function SheetGrid({
2852
  return;
2853
  }
2854
  landFill(out, mode === "values");
 
 
 
 
2855
  // ⭐ W52-T07: same highlight the glide door sets, from the ribbon's own paste path.
2856
  setPasteHighlight({ col: realCol(range.col0), row: realRow(range.row0),
2857
  cols: values[0]?.length ?? 0, rows: values.length });
@@ -3727,6 +3886,16 @@ export default function SheetGrid({
3727
  if (!cur) return;
3728
  applySelection(rowBand(cur.cell[1], visCols.length), cur.cell);
3729
  return;
 
 
 
 
 
 
 
 
 
 
3730
 
3731
  // -- entering and filling. Each one reaches the RIBBON's act, never a second copy. -----
3732
  case "fill-down": onRibbonAction({ kind: "fill-down" }); return;
@@ -3759,6 +3928,10 @@ export default function SheetGrid({
3759
  return;
3760
  }
3761
  landFill(out, false);
 
 
 
 
3762
  return;
3763
  }
3764
  case "line-break": {
 
142
  import ChartDialog from "./ChartDialog";
143
  import SheetChartLayer from "./SheetChartLayer";
144
  import ShortcutsPanel from "./ShortcutsPanel";
145
+ import { colToIndex, columnRangeA1, indexToCol, rowRangeA1 } from "./a1";
146
  // ⛔⛔ W51-T18 — THE RULE ENGINE AND THE VALIDATION CHECKER ARE PURE AND SHEET LOCAL, and that is
147
  // what lets `verify_api.py` compile them beside `sheetState.js` and EXECUTE the ten operators
148
  // rather than grep for their names. This component is the only place their answers meet a canvas.
 
196
  // ⛔⛔ W51-T17 — ONE TABLE, TWO CONSUMERS. `shortcuts.ts` is the key map AND the panel's rows, and
197
  // it imports NOTHING: see its head note on tsc's emitted root. This file matches against it and
198
  // `ShortcutsPanel.tsx` renders it, so the two cannot advertise different keys.
199
+ import { arrowStep, columnBand, commitDirection, commitTarget, currentRegion, edgeIndex, edgeStart,
200
  extendEdgeRect, isArrowKey, KEY_TIP_GRID_ARROW_EVENT, keyTipGridArrow, matchShortcut,
201
  rowBand, shortcutOwner, structureAxis, tabRunOrigin } from "./shortcuts";
202
  import type { SelectionAxis, SelectionRect, ShortcutId } from "./shortcuts";
 
541
  return `${pointAddr({ col: col0, row: row0 })}:${pointAddr({ col: col1, row: row1 })}`;
542
  }
543
 
544
+ /**
545
+ * W57-T01: how far a whole-column or whole-row reference highlight paints, in one-based inclusive
546
+ * coordinates on both axes.
547
+ *
548
+ * ⛔ A CONSTANT RATHER THAN THE SHEET'S OWN EXTENT, AND THAT IS A DELIBERATE TRADE. The two memos
549
+ * that paint this band are pinned by `verify_formula_engine.py`'s RO-3 and RO-4 to close over the
550
+ * edit state and the selection and nothing else, so a bound read off `tab` would add a third input
551
+ * to both and cost the guarantee those legs exist to hold: that no outline can outlive the
552
+ * reference or the editor that made it. A fixed span costs nothing anybody can see instead. It is
553
+ * past `MAX_SHEET_COLS` (702), so a whole-ROW band is always complete; a whole-COLUMN band paints
554
+ * its first thousand rows, which is roughly thirty screenfuls at the contract 1440x900 viewport, so
555
+ * the column reads as highlighted at every scroll position a person reaches while editing one
556
+ * formula. And it stays under the 4000-cell paint cap below, so the band always paints rather than
557
+ * being skipped as pathological.
558
+ */
559
+ const BAND_HIGHLIGHT_SPAN = 1000;
560
+
561
  /** What the right-click menu is open ON: a whole column, or the row and column of one cell. */
562
  interface SheetMenu {
563
  anchor: ReturnType<typeof rectAnchor>;
 
625
  /** FA-23 #1: the dropdown is closed without touching `draft` (see `FormulaAssist`'s own note). */
626
  dismissed: boolean;
627
  mode: "enter" | "point";
628
+ /** W57-T04: F2 toggles native caret arrows; explicit Ctrl reference gestures still work. */
629
+ caretOnly: boolean;
630
  /** PM-4's anchor: the EDITING cell, real 1-based coordinates. Never the selection. */
631
  anchor: RealCell;
632
  /** Where in `draft` the live point-mode reference text starts, for PM-5's replace-not-append. */
633
  insertStart: number | null;
634
  /** The single proposed cell while no Shift range is open. */
635
  pointCell: RealCell | null;
636
+ /** W57-T01: set when the live proposal is a whole column or row rather than a cell or
637
+ * rectangle, so the dashed overlay can cover the band the same way the colour map does. */
638
+ pointBand: "column" | "row" | null;
639
  /** PM-7's range anchor once Shift extends the proposal; null outside a range. */
640
  rangeAnchor: RealCell | null;
641
  }
 
1525
  setMenu(null);
1526
  setDropdown(null);
1527
  setFormulaEdit({
1528
+ addr, inBand, viewCell, draft, caret, dropdownIndex: 0, dismissed: false, mode: "enter", caretOnly: false,
1529
+ anchor, insertStart: null, pointCell: null, pointBand: null, rangeAnchor: null,
1530
  });
1531
  }, []);
1532
 
 
1610
  * PM-4/PM-5/PM-7/PM-8: every point-mode proposal, arrived at from either the anchor (a fresh
1611
  * arrow press) or the previous proposal (a continued one), goes through this ONE splice so
1612
  * "insert" and "replace the last insert" are the same code path rather than two that can drift.
1613
+ * W57-T01: a whole-column or whole-row proposal changes only the emitted text; it shares the
1614
+ * same insertStart, replacement length and caret rule as a cell or rectangular range.
1615
  */
1616
+ const proposeCell = useCallback((
1617
+ target: RealCell,
1618
+ shift: boolean,
1619
+ wholeAxis?: "column" | "row",
1620
+ /** W57-T02: where a NEW range starts, for a Shift-extended press made before point mode
1621
+ * exists. Without it the anchor would default to `target` and a Ctrl+Shift+Arrow pressed as
1622
+ * the first key after `=SUM(` would emit one cell instead of the run it selected. T02 only
1623
+ * supplies this in enter mode; repeat presses keep the existing range anchor. W57-T04
1624
+ * also uses it to explicitly name a region's top-left corner while already pointing. */
1625
+ rangeFrom?: RealCell,
1626
+ ) => {
1627
  if (!formulaEdit) return;
1628
  const insertStart = formulaEdit.mode === "point" && formulaEdit.insertStart !== null
1629
  ? formulaEdit.insertStart : formulaEdit.caret;
1630
  const oldLen = formulaEdit.mode === "point" ? formulaEdit.caret - insertStart : 0;
1631
+ // W57-T04: an explicit rangeFrom wins so a region can name its anchor outright. This
1632
+ // preserves T02: it only supplies rangeFrom in enter mode, where rangeAnchor is null by
1633
+ // construction, so both orders answer identically for every existing T02 press.
1634
  const rangeAnchor = shift
1635
+ ? (rangeFrom ?? formulaEdit.rangeAnchor
1636
+ ?? (formulaEdit.mode === "point" ? formulaEdit.pointCell : target))
1637
  : null;
1638
+ const text = wholeAxis === "column" ? columnRangeA1(target.col)
1639
+ : wholeAxis === "row" ? rowRangeA1(target.row)
1640
+ : rangeAnchor ? pointRangeText(rangeAnchor, target) : pointAddr(target);
1641
  const draft = formulaEdit.draft.slice(0, insertStart) + text
1642
  + formulaEdit.draft.slice(insertStart + oldLen);
1643
  const caret = insertStart + text.length;
1644
  setFormulaEdit({
1645
  ...formulaEdit, draft, caret, insertStart, mode: "point", pointCell: target, rangeAnchor,
1646
+ pointBand: wholeAxis ?? null,
1647
  });
1648
  // PM-6: the grid scrolls to keep the proposal visible. Best effort on the MAIN grid only --
1649
  // a proposal inside the frozen band is permanently on screen by construction (R17).
 
1651
  const viewRow = viewRowOf(target.row - 1);
1652
  if (viewRow >= 0) gridRef.current?.scrollTo(viewIndexOf(visCols, target.col - 1), viewRow);
1653
  }
1654
+ }, [columnRangeA1, formulaEdit, rowRangeA1, viewRowOf, visCols]);
1655
 
1656
  /** PM-9/PM-10/PM-11: `,`/`(`/`)` commit the live reference as literal text and leave point mode. */
1657
  const commitPointReference = useCallback((trailer: string) => {
 
1660
  + formulaEdit.draft.slice(formulaEdit.caret);
1661
  setFormulaEdit({
1662
  ...formulaEdit, draft, caret: formulaEdit.caret + trailer.length,
1663
+ mode: "enter", pointCell: null, pointBand: null, rangeAnchor: null, insertStart: null,
1664
  });
1665
  }, [formulaEdit]);
1666
 
 
1734
 
1735
  const onFormulaKeyDown = useCallback((e: ReactKeyboardEvent<HTMLInputElement>) => {
1736
  if (!formulaEdit) return;
1737
+ const { draft, caret, mode, caretOnly } = formulaEdit;
1738
+ const caretArrow = caretOnly && !e.ctrlKey && !e.metaKey && !e.altKey;
1739
+
1740
+ // W57-T01 / C1: the formula input owns focus, so these keys cannot reach the grid handler.
1741
+ // Use its SAME matcher and action names above point mode's early returns: both entry modes
1742
+ // widen the pointed cell (or the editing anchor) through the ONE proposal splice. Passing
1743
+ // false clears any rectangular range anchor; a repeated press replaces that live proposal,
1744
+ // and the existing caret effect keeps focus just after the reference inside the formula.
1745
+ // W57-T02: dispatch BEFORE the dropdown because it consumes Up/Down without checking Ctrl.
1746
+ // Plain arrows and Tab do not match these actions; F2 can reserve the arrows for the caret
1747
+ // below while the dropdown keeps its existing Tab behavior.
1748
+ const hit: ShortcutId | null = matchShortcut(e);
1749
+ if (hit === "select-column" || hit === "select-row") {
1750
+ e.preventDefault();
1751
+ const target = mode === "point" ? (formulaEdit.pointCell ?? formulaEdit.anchor)
1752
+ : formulaEdit.anchor;
1753
+ proposeCell(target, false, hit === "select-column" ? "column" : "row");
1754
+ return;
1755
+ }
1756
+
1757
+ // W57-T04 / C1: the grid and formula editor share the same region in real coordinates.
1758
+ // Only this boundary converts the zero-based rectangle to the one-based proposal splice.
1759
+ if (hit === "select-region") {
1760
+ e.preventDefault();
1761
+ const from = formulaEdit.pointCell ?? formulaEdit.anchor;
1762
+ const region = currentRegion({ col: from.col - 1, row: from.row - 1 }, extent,
1763
+ (c, r) => isFilled(tab, c, r));
1764
+ const topLeft: RealCell = { col: region.col0 + 1, row: region.row0 + 1 };
1765
+ const bottomRight: RealCell = { col: region.col1 + 1, row: region.row1 + 1 };
1766
+ proposeCell(bottomRight, true, undefined, topLeft);
1767
+ return;
1768
+ }
1769
+
1770
+ // W57-T02 / C1: share the grid's edgeIndex walk and keep all A1 edits in proposeCell.
1771
+ // RealCell is 1-based; edgeIndex and isFilled are 0-based. Convert once on entry and once
1772
+ // on exit, or every reference silently lands one cell off. Point mode walks its active end;
1773
+ // a NEW extended range starts at the clamped plain-arrow neighbour and walks from there.
1774
+ // Enter mode only claims reference positions, preserving text navigation elsewhere. A jump
1775
+ // clears rangeAnchor, while an extension keeps the existing anchor across repeat presses.
1776
+ if (hit === "jump-edge" || hit === "extend-edge") {
1777
+ const step = arrowStep(e.key);
1778
+ if (step && (mode === "point" || isRefPosition(draft, caret))) {
1779
+ e.preventDefault();
1780
+ const extending = hit === "extend-edge";
1781
+ const rangeFrom: RealCell | undefined = mode === "enter" && extending
1782
+ ? { col: clampCol(formulaEdit.anchor.col + step.dCol),
1783
+ row: clampRow(formulaEdit.anchor.row + step.dRow) }
1784
+ : undefined;
1785
+ const from = mode === "point" ? (formulaEdit.pointCell ?? formulaEdit.anchor)
1786
+ : (rangeFrom ?? formulaEdit.anchor);
1787
+ const fromColZero = from.col - 1;
1788
+ const fromRowZero = from.row - 1;
1789
+ const edgeZero = step.dRow !== 0
1790
+ ? { col: fromColZero,
1791
+ row: edgeIndex(fromRowZero, extent.rows, step.dRow,
1792
+ (i) => isFilled(tab, fromColZero, i)) }
1793
+ : { col: edgeIndex(fromColZero, extent.cols, step.dCol,
1794
+ (i) => isFilled(tab, i, fromRowZero)),
1795
+ row: fromRowZero };
1796
+ const edgeCell: RealCell = { col: edgeZero.col + 1, row: edgeZero.row + 1 };
1797
+ proposeCell(edgeCell, extending, undefined, rangeFrom);
1798
+ return;
1799
+ }
1800
+ }
1801
 
1802
  if (formulaDropdownOpen) {
1803
+ if (e.key === "ArrowDown" && !caretArrow) {
1804
  e.preventDefault();
1805
  setFormulaEdit({
1806
  ...formulaEdit, dropdownIndex: (formulaEdit.dropdownIndex + 1) % formulaSuggestions.length,
1807
  });
1808
  return;
1809
  }
1810
+ if (e.key === "ArrowUp" && !caretArrow) {
1811
  e.preventDefault();
1812
  setFormulaEdit({
1813
  ...formulaEdit,
 
1851
  return;
1852
  }
1853
 
1854
+ // W57-T04: F2 switches Excel's Enter/Edit arrow behavior without changing the draft.
1855
+ // Retire any live proposal before allowing native caret movement; its old insertStart
1856
+ // must never be reused after the caret moves. Explicit Ctrl gestures are dispatched above.
1857
+ if (e.key === "F2") {
1858
+ e.preventDefault();
1859
+ setFormulaEdit({
1860
+ ...formulaEdit, caretOnly: !caretOnly, mode: "enter", pointCell: null, pointBand: null,
1861
+ rangeAnchor: null, insertStart: null,
1862
+ });
1863
+ return;
1864
+ }
1865
+
1866
  if (mode === "point") {
1867
  if (ARROW_DELTA[e.key]) {
1868
+ if (caretArrow) {
1869
+ // A Ctrl gesture can propose while F2's caret mode is active. The next plain arrow
1870
+ // retires that proposal, then the browser moves the caret without preventDefault.
1871
+ setFormulaEdit({
1872
+ ...formulaEdit, mode: "enter", pointCell: null, pointBand: null,
1873
+ rangeAnchor: null, insertStart: null,
1874
+ });
1875
+ return;
1876
+ }
1877
  e.preventDefault();
1878
  const dir = ARROW_DELTA[e.key];
1879
  const from = formulaEdit.pointCell ?? formulaEdit.anchor;
 
1897
  // PM-14: any other typed character leaves point mode and is inserted literally. No
1898
  // `preventDefault` -- the browser's own keystroke does the inserting.
1899
  setFormulaEdit({
1900
+ ...formulaEdit, mode: "enter", pointCell: null, pointBand: null, rangeAnchor: null, insertStart: null,
1901
  });
1902
  return;
1903
  }
1904
+ // W57-T04 - MOVING THE CARET BY HAND LEAVES POINT MODE. insertStart records where the
1905
+ // live proposal begins; after the reader moves elsewhere, reusing it would splice over
1906
+ // unrelated characters. No preventDefault: the browser still moves or deletes, just as
1907
+ // PM-14's sibling branch relies on the browser to insert the typed character.
1908
+ if (e.key === "Backspace" || e.key === "Delete"
1909
+ || e.key === "Home" || e.key === "End") {
1910
  setFormulaEdit({
1911
+ ...formulaEdit, mode: "enter", pointCell: null, pointBand: null, rangeAnchor: null, insertStart: null,
1912
  });
1913
  }
1914
  return;
 
1916
 
1917
  // PM-4: an arrow key at a legal reference position starts point mode, anchored on the
1918
  // EDITING cell (never the grid's own selection).
1919
+ if (!caretArrow && ARROW_DELTA[e.key] && isRefPosition(draft, caret)) {
1920
  e.preventDefault();
1921
  const dir = ARROW_DELTA[e.key];
1922
  proposeCell(
 
1932
  // is capture phase on the document and stops propagation, so a branch here could never fire
1933
  // anyway - it would be dead code that a later reader would trust.
1934
  }, [
1935
+ acceptFormulaSuggestion, arrowStep, clampCol, clampRow, commitFormulaEditor,
1936
+ commitPointReference, currentRegion, edgeIndex, extent.cols, extent.rows, formulaDropdownOpen, formulaEdit,
1937
+ formulaSuggestions, isFilled, matchShortcut, proposeCell, tab,
1938
  ]);
1939
 
1940
  // The caret has to land where `formulaEdit.caret` says on every mutation, which React does not
 
1975
  : (selected?.cell?.kind === "formula" ? (selected.cell.formula ?? "") : "");
1976
  if (!source) return out;
1977
  for (const ref of refsIn(source)) {
1978
+ let c0 = colToIndex(ref.start.col);
1979
+ let c1 = colToIndex(ref.end.col);
1980
+ let r0 = ref.start.row;
1981
+ let r1 = ref.end.row;
1982
+ if (ref.band === "column") {
1983
+ r0 = 1;
1984
+ r1 = BAND_HIGHLIGHT_SPAN;
1985
+ } else if (ref.band === "row") {
1986
+ c0 = 1;
1987
+ c1 = BAND_HIGHLIGHT_SPAN;
1988
+ }
1989
+ // A pathological typed range or a band with a huge used extent must not stall a paint.
1990
  if ((Math.abs(c1 - c0) + 1) * (Math.abs(r1 - r0) + 1) > 4000) continue;
1991
  const color = colorForSlot(ref.colorIndex, "light");
1992
  for (let c = Math.min(c0, c1); c <= Math.max(c0, c1); c += 1) {
 
2018
  * cannot say WHICH of its references is the live one: `=F6+F6` has two occurrences of the same
2019
  * text and only one of them is under the arrow keys.
2020
  */
2021
+ // W57-T01: a band inserted in point mode is still the live proposal; the next arrow replaces
2022
+ // it with a cell reference. Dash the whole bounded band until it settles, then leave it solid.
2023
  const formulaPointCells = useMemo(() => {
2024
  const out = new Set<string>();
2025
  if (!formulaEdit || formulaEdit.mode !== "point" || !formulaEdit.pointCell) return out;
2026
+ let a = formulaEdit.rangeAnchor ?? formulaEdit.pointCell;
2027
+ let b = formulaEdit.pointCell;
2028
+ if (formulaEdit.pointBand === "column") {
2029
+ a = { col: b.col, row: 1 };
2030
+ b = { col: b.col, row: BAND_HIGHLIGHT_SPAN };
2031
+ } else if (formulaEdit.pointBand === "row") {
2032
+ a = { col: 1, row: b.row };
2033
+ b = { col: BAND_HIGHLIGHT_SPAN, row: b.row };
2034
+ }
2035
  // The same cap `formulaRefCells` uses: a pathological proposal must not stall a paint.
2036
  if ((Math.abs(b.col - a.col) + 1) * (Math.abs(b.row - a.row) + 1) > 4000) return out;
2037
  for (let c = Math.min(a.col, b.col); c <= Math.max(a.col, b.col); c += 1) {
 
2380
  // feature. The block is screened against the validation the TARGET already carries, the
2381
  // allowed cells land, and every refusal is named in one sentence rather than forty.
2382
  landFill(out, true);
2383
+ if (out.tab) {
2384
+ if (out.tab.charts !== tab.charts) writeCharts(out.tab.charts ?? []);
2385
+ if (out.tab.rules !== tab.rules) saveRules(out.tab.rules ?? []);
2386
+ }
2387
  // ⭐ W52-T07: the WHOLE destination range, not just the anchor `target` glide handed over —
2388
  // `values`' own shape (rows outer, cols inner) IS that range's size.
2389
  setPasteHighlight({ col: realCol(target[0]), row: realRow(target[1]),
 
2425
  // ⛔ W51-T18 / C2 — AND THE FILL IS THE SECOND DOOR. Dragging a value down a column lands
2426
  // it on every cell it passes, list or no list, so it is screened exactly as the paste is.
2427
  landFill(out, true);
2428
+ if (out.tab) {
2429
+ if (out.tab.charts !== tab.charts) writeCharts(out.tab.charts ?? []);
2430
+ if (out.tab.rules !== tab.rules) saveRules(out.tab.rules ?? []);
2431
+ }
2432
  },
2433
  [cellValueGetter, landFill, options, realCol, realRow, tab, viewShadows],
2434
  );
 
3007
  return;
3008
  }
3009
  landFill(out, mode === "values");
3010
+ if (out.tab) {
3011
+ if (out.tab.charts !== tab.charts) writeCharts(out.tab.charts ?? []);
3012
+ if (out.tab.rules !== tab.rules) saveRules(out.tab.rules ?? []);
3013
+ }
3014
  // ⭐ W52-T07: same highlight the glide door sets, from the ribbon's own paste path.
3015
  setPasteHighlight({ col: realCol(range.col0), row: realRow(range.row0),
3016
  cols: values[0]?.length ?? 0, rows: values.length });
 
3886
  if (!cur) return;
3887
  applySelection(rowBand(cur.cell[1], visCols.length), cur.cell);
3888
  return;
3889
+ case "select-region": {
3890
+ if (!cur) return;
3891
+ const region = currentRegion({ col: realCol(cur.cell[0]), row: realRow(cur.cell[1]) },
3892
+ extent, (c, r) => isFilled(tab, c, r));
3893
+ applySelection({
3894
+ col0: viewIndexOf(visCols, region.col0), row0: viewRowOf(region.row0),
3895
+ col1: viewIndexOf(visCols, region.col1), row1: viewRowOf(region.row1),
3896
+ }, cur.cell);
3897
+ return;
3898
+ }
3899
 
3900
  // -- entering and filling. Each one reaches the RIBBON's act, never a second copy. -----
3901
  case "fill-down": onRibbonAction({ kind: "fill-down" }); return;
 
3928
  return;
3929
  }
3930
  landFill(out, false);
3931
+ if (out.tab) {
3932
+ if (out.tab.charts !== tab.charts) writeCharts(out.tab.charts ?? []);
3933
+ if (out.tab.rules !== tab.rules) saveRules(out.tab.rules ?? []);
3934
+ }
3935
  return;
3936
  }
3937
  case "line-break": {
web/src/sheet/SheetPage.tsx CHANGED
@@ -40,6 +40,7 @@ import type { PointerEvent as ReactPointerEvent, ReactNode } from "react";
40
  import "../styles/wave49/sheet.css";
41
  import "../styles/wave50/sheet.css";
42
  import "../styles/wave55/sheet.css";
 
43
  // ⛔⛔ W51-T09 — THE LAUNCHER'S OWN STYLESHEET, AND IT IS NOT OPTIONAL. `.cg-chat-toggle` and
44
  // `.cg-chat-dock` live in `customer-grid/chatDock.css`, which until this ticket ONLY
45
  // `CustomerGrid.tsx` imported. On a direct load of `#/sheet` that chunk is never fetched, so the
@@ -54,6 +55,7 @@ import BindingEditor from "./BindingEditor";
54
  import DrillModal from "./DrillModal";
55
  import type { DrillCellScope } from "./DrillModal";
56
  import FormulaBar from "./FormulaBar";
 
57
  import SheetGridBase from "./SheetGrid";
58
  import type { BoundEvaluationRequest, SheetGridProps } from "./SheetGrid";
59
  import SheetRail from "./SheetRail";
@@ -89,6 +91,13 @@ import type { SheetHistory, StructureOp } from "./sheetState";
89
  import { emptyIndex } from "./types";
90
  import type { Cell, IndexRepair, SheetChartSpec, SheetRule, SheetTab, Workbook } from "./types";
91
 
 
 
 
 
 
 
 
92
  /**
93
  * ⭐⭐ W51-T08 / CONTRACT C1 — THE FOUR SEAM PROPS, TYPED HERE BECAUSE `SheetGrid.tsx` IS LANE E'S.
94
  *
@@ -506,6 +515,119 @@ export default function SheetPage() {
506
  /** The current drain, so the unmount flush can call it without re-arming its own effect. */
507
  const drainRef = useRef<() => void>(() => {});
508
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
509
  /** Write the ref and the state together. Nothing in this file calls `setBook` on its own. */
510
  const applyLocal = useCallback((next: Workbook) => {
511
  bookRef.current = next;
@@ -764,6 +886,16 @@ export default function SheetPage() {
764
  setEditAt(addr);
765
  }, []);
766
 
 
 
 
 
 
 
 
 
 
 
767
  /**
768
  * A 409 on one tab: re-read THAT TAB and say so, naming it.
769
  *
@@ -2164,17 +2296,25 @@ export default function SheetPage() {
2164
  const drillBindingScope = (drillBinding?.scope ?? null) as Record<string, unknown> | null;
2165
  const drillViewId = typeof drillBindingScope?.view_id === "string"
2166
  ? drillBindingScope.view_id.trim() : "";
 
 
 
 
2167
  const drillScope: DrillCellScope | null = !drillBindingScope
2168
  ? null
2169
  : drillViewId
2170
  ? {
2171
  kind: "view",
2172
  name: typeof drillBindingScope.view_name === "string" ? drillBindingScope.view_name : "",
 
 
2173
  }
2174
  : {
2175
  kind: "filter",
2176
  tree: (drillBindingScope.filter as FilterTree | null | undefined)
2177
  ?? { conj: "and", nodes: [] },
 
 
2178
  };
2179
 
2180
  return (
@@ -2247,26 +2387,24 @@ export default function SheetPage() {
2247
  </div>
2248
  ) : (
2249
  <div className="sheet-body">
2250
- {/* ⭐⭐ W51-T08 (owner instructions 8 and 10) — THE PAGE TOOLBAR IS GONE, TITLE AND ALL.
2251
- The owner's ask is that the Sheet carries no page title and that exactly ONE ribbon
2252
- sits above exactly ONE formula bar above the canvas. A `.sheet-toolbar` row holding an
2253
- `<h1>` and a second Refresh button is a THIRD band of chrome above the ribbon, and the
2254
- workbook's name is already the selected row in the rail beside it, so the heading was
2255
- naming the page to a reader who had just clicked it.
2256
-
2257
- ⭐ REFRESH DID NOT DISAPPEAR, IT MOVED. R8 puts it on the ribbon's own row, so it is
2258
- handed down as `onRefresh` (C1) rather than drawn here. Wave-49 R12's reasoning still
2259
- holds and is why it is a ROW-level control rather than a cell one: a sheet is a
2260
- snapshot, so the one act that changes every number on screen is a page-level act.
2261
-
2262
- ⚠ `.sheet-notice` DELIBERATELY STAYS. It is a transient sentence about a refusal, not
2263
- chrome, and instructions 8 and 10 name a title and a duplicated bar. Deleting it would
2264
- take the only place a save conflict or a failed refresh is ever said out loud. */}
2265
- {notice && <p className="sheet-notice">{notice}</p>}
2266
-
2267
- {/* ⭐⭐ W53-T08 — THE `.sheet-status` LINE THAT SAT HERE IS DELETED (instruction 14). Its
2268
- hook class went with it; `.sheet-notice` directly above is a DIFFERENT element and
2269
- survives deliberately. */}
2270
 
2271
  {/* ⭐ THREE OUTCOMES, IN THE ORDER THEY CAN HAPPEN. A workbook is switching, so the
2272
  spinner again; a workbook is open, so the grid; nothing opened and `loading` is over,
@@ -2279,6 +2417,8 @@ export default function SheetPage() {
2279
  <SheetGrid
2280
  workbook={book}
2281
  tab={tab}
 
 
2282
  // ⭐ W54-T34: a drill in flight is a round trip like a refresh, and the cell action bar
2283
  // reads exactly one prop for "a round trip is in flight". The page root's `data-drill`
2284
  // is what tells the two apart in the stylesheet.
@@ -2342,6 +2482,13 @@ export default function SheetPage() {
2342
  </div>
2343
  )}
2344
 
 
 
 
 
 
 
 
2345
  {/* ⭐⭐ THE TAB BAR (wave-49 R7), AND IT SITS AT THE BOTTOM OF THE WORKBOOK.
2346
  R7 says one rail entry is a WORKBOOK WITH TABS, so the tabs belong INSIDE the workbook
2347
  and never on the rail, which lists workbooks. The bottom is also Excel's own place for
@@ -2396,10 +2543,22 @@ export default function SheetPage() {
2396
  <span className="sheet-ribbon-sep" aria-hidden />
2397
  <button
2398
  type="button"
2399
- className="sheet-ribbon-btn"
2400
  onClick={onAddTab}
2401
  title="Add a sheet to this workbook"
2402
  >
 
 
 
 
 
 
 
 
 
 
 
 
2403
  <span className="sheet-ribbon-label">Add sheet</span>
2404
  </button>
2405
  </div>
 
40
  import "../styles/wave49/sheet.css";
41
  import "../styles/wave50/sheet.css";
42
  import "../styles/wave55/sheet.css";
43
+ import "../styles/wave57/sheet-tabs.css";
44
  // ⛔⛔ W51-T09 — THE LAUNCHER'S OWN STYLESHEET, AND IT IS NOT OPTIONAL. `.cg-chat-toggle` and
45
  // `.cg-chat-dock` live in `customer-grid/chatDock.css`, which until this ticket ONLY
46
  // `CustomerGrid.tsx` imported. On a direct load of `#/sheet` that chunk is never fetched, so the
 
55
  import DrillModal from "./DrillModal";
56
  import type { DrillCellScope } from "./DrillModal";
57
  import FormulaBar from "./FormulaBar";
58
+ import { OPEN_CELL_DATA_EVENT } from "./Ribbon";
59
  import SheetGridBase from "./SheetGrid";
60
  import type { BoundEvaluationRequest, SheetGridProps } from "./SheetGrid";
61
  import SheetRail from "./SheetRail";
 
91
  import { emptyIndex } from "./types";
92
  import type { Cell, IndexRepair, SheetChartSpec, SheetRule, SheetTab, Workbook } from "./types";
93
 
94
+ // W57-T19: the page supplies the ordered options and saved-view filters used by every copy door.
95
+ import { choiceVocabulary, topicForScope } from "../customer-grid/types";
96
+ import { bindingOptionKey } from "./sheetState";
97
+ import type { OptionCatalogue } from "./sheetState";
98
+ import { bindingOnDrag } from "./types";
99
+ import type { SavedViewShadow } from "./bindingRefs";
100
+
101
  /**
102
  * ⭐⭐ W51-T08 / CONTRACT C1 — THE FOUR SEAM PROPS, TYPED HERE BECAUSE `SheetGrid.tsx` IS LANE E'S.
103
  *
 
515
  /** The current drain, so the unmount flush can call it without re-arming its own effect. */
516
  const drainRef = useRef<() => void>(() => {});
517
 
518
+ // W57-T19: stable pair keys keep these background reads out of ordinary edits and paints.
519
+ const copyPairs = useMemo(() => {
520
+ const fields = new Set<string>();
521
+ const views = new Set<string>();
522
+ for (const sheet of book?.sheets ?? []) {
523
+ // ⛔⛔ W57-T19 - `cells` IS OPTIONAL ON A STORED TAB AND `Object.values(undefined)`
524
+ // THROWS. Measured: without this guard the whole Sheet route rendered its failure
525
+ // card on tenant #0's own workbook, and tsc, the gates and the production build were
526
+ // all green, because the shape is only wrong at RUNTIME on a tab saved without a
527
+ // cells map. A background read must never be able to take the page down with it.
528
+ for (const cell of Object.values(sheet?.cells ?? {})) {
529
+ if (cell?.kind !== "bound" || !cell.binding) continue;
530
+ const binding = cell.binding;
531
+ const database = typeof binding.database === "string" ? binding.database.trim() : "";
532
+ if (!database) continue;
533
+ const down = bindingOnDrag(binding).down;
534
+ if (down !== "none") fields.add(bindingOptionKey(database, down.field));
535
+ const scope = binding.scope as { view_id?: unknown } | undefined;
536
+ const viewId = typeof scope?.view_id === "string" ? scope.view_id.trim() : "";
537
+ if (viewId) views.add(JSON.stringify([database, viewId]));
538
+ }
539
+ }
540
+ return { fields: JSON.stringify([...fields].sort()), views: JSON.stringify([...views].sort()) };
541
+ }, [book?.sheets]);
542
+ const optionRequestKey = JSON.stringify([book?.id ?? "", copyPairs.fields]);
543
+ const shadowRequestKey = JSON.stringify([book?.id ?? "", copyPairs.views]);
544
+ const [copyOptions, setCopyOptions] = useState<{ key: string; value: OptionCatalogue }>(
545
+ { key: "", value: {} },
546
+ );
547
+ const [copyShadows, setCopyShadows] = useState<{ key: string; value: SavedViewShadow[] }>(
548
+ { key: "", value: [] },
549
+ );
550
+ const optionCatalogue = copyOptions.key === optionRequestKey ? copyOptions.value : undefined;
551
+ const viewShadows = copyShadows.key === shadowRequestKey ? copyShadows.value : undefined;
552
+
553
+ useEffect(() => {
554
+ const [, pairsKey] = JSON.parse(optionRequestKey) as [string, string];
555
+ const databases = new Map<string, Set<string>>();
556
+ for (const pair of JSON.parse(pairsKey) as string[]) {
557
+ const [database, field] = JSON.parse(pair) as [string, string];
558
+ const fields = databases.get(database) ?? new Set<string>();
559
+ fields.add(field);
560
+ databases.set(database, fields);
561
+ }
562
+ if (!databases.size) return;
563
+ let live = true;
564
+ const scopeOf = (database: string): SurfaceScope | null => {
565
+ if (database === "customer_data") return "customer";
566
+ if (database === "product_data") return "product";
567
+ return database.startsWith("ut_") ? (database as SurfaceScope) : null;
568
+ };
569
+ void Promise.allSettled([...databases].map(async ([database, wanted]) => {
570
+ const scope = scopeOf(database);
571
+ if (!scope) return;
572
+ const workspace = await fetchWorkspace(scope);
573
+ if (!live || !workspace) return;
574
+ const fields = (workspace.fields ?? []).filter((field) => wanted.has(field.key));
575
+ const needsRows = fields.some((field) => choiceVocabulary(field, []).length === 0);
576
+ const rows = needsRows ? (await fetchTopicRows(topicForScope(scope)))?.rows ?? [] : [];
577
+ if (!live) return;
578
+ const catalogue: OptionCatalogue = {};
579
+ for (const field of fields) {
580
+ catalogue[bindingOptionKey(database, field.key)] = choiceVocabulary(field, rows);
581
+ }
582
+ setCopyOptions((current) => ({
583
+ key: optionRequestKey,
584
+ value: { ...(current.key === optionRequestKey ? current.value : {}), ...catalogue },
585
+ }));
586
+ }));
587
+ return () => { live = false; };
588
+ }, [optionRequestKey]);
589
+
590
+ useEffect(() => {
591
+ const [workbookId, pairsKey] = JSON.parse(shadowRequestKey) as [string, string];
592
+ const wanted = new Set(JSON.parse(pairsKey) as string[]);
593
+ if (!workbookId || !wanted.size) return;
594
+ const bindings = new Map<string, Record<string, unknown>>();
595
+ for (const sheet of bookRef.current?.sheets ?? []) {
596
+ // ⛔⛔ W57-T19 - `cells` IS OPTIONAL ON A STORED TAB AND `Object.values(undefined)`
597
+ // THROWS. Measured: without this guard the whole Sheet route rendered its failure
598
+ // card on tenant #0's own workbook, and tsc, the gates and the production build were
599
+ // all green, because the shape is only wrong at RUNTIME on a tab saved without a
600
+ // cells map. A background read must never be able to take the page down with it.
601
+ for (const cell of Object.values(sheet?.cells ?? {})) {
602
+ if (cell?.kind !== "bound" || !cell.binding) continue;
603
+ const binding = cell.binding;
604
+ const scope = binding.scope as { view_id?: unknown } | undefined;
605
+ const pair = JSON.stringify([String(binding.database ?? "").trim(),
606
+ String(scope?.view_id ?? "").trim()]);
607
+ if (wanted.has(pair) && !bindings.has(pair)) bindings.set(pair, binding);
608
+ }
609
+ }
610
+ const controller = new AbortController();
611
+ void (async () => {
612
+ try {
613
+ const response = await fetch(
614
+ `/api/v1/sheets/${encodeURIComponent(workbookId)}/binding-shadows`,
615
+ { method: "POST", credentials: "same-origin", signal: controller.signal,
616
+ headers: { "Content-Type": "application/json" },
617
+ body: JSON.stringify({ bindings: [...bindings.values()] }) },
618
+ );
619
+ if (!response.ok) return;
620
+ const payload = await response.json() as { shadows?: SavedViewShadow[] };
621
+ if (!controller.signal.aborted && Array.isArray(payload.shadows)) {
622
+ setCopyShadows({ key: shadowRequestKey, value: payload.shadows });
623
+ }
624
+ } catch {
625
+ // An unavailable snapshot keeps the grid's existing missing-view copy notice.
626
+ }
627
+ })();
628
+ return () => controller.abort();
629
+ }, [shadowRequestKey]);
630
+
631
  /** Write the ref and the state together. Nothing in this file calls `setBook` on its own. */
632
  const applyLocal = useCallback((next: Workbook) => {
633
  bookRef.current = next;
 
886
  setEditAt(addr);
887
  }, []);
888
 
889
+ useEffect(() => {
890
+ const openCellData = () => {
891
+ if (!barAddr) return;
892
+ setNotice("");
893
+ setEditAt(barAddr);
894
+ };
895
+ document.addEventListener(OPEN_CELL_DATA_EVENT, openCellData);
896
+ return () => document.removeEventListener(OPEN_CELL_DATA_EVENT, openCellData);
897
+ }, [barAddr]);
898
+
899
  /**
900
  * A 409 on one tab: re-read THAT TAB and say so, naming it.
901
  *
 
2296
  const drillBindingScope = (drillBinding?.scope ?? null) as Record<string, unknown> | null;
2297
  const drillViewId = typeof drillBindingScope?.view_id === "string"
2298
  ? drillBindingScope.view_id.trim() : "";
2299
+ const drillAggregate = drillBinding?.aggregate as Record<string, unknown> | undefined;
2300
+ const drillAggregateField = typeof drillAggregate?.field === "string"
2301
+ ? drillAggregate.field.trim() : "";
2302
+ const drillStep = bindingOnDrag(drillBinding).down;
2303
  const drillScope: DrillCellScope | null = !drillBindingScope
2304
  ? null
2305
  : drillViewId
2306
  ? {
2307
  kind: "view",
2308
  name: typeof drillBindingScope.view_name === "string" ? drillBindingScope.view_name : "",
2309
+ ...(drillAggregateField ? { aggregateField: drillAggregateField } : {}),
2310
+ ...(drillStep !== "none" ? { stepField: drillStep.field } : {}),
2311
  }
2312
  : {
2313
  kind: "filter",
2314
  tree: (drillBindingScope.filter as FilterTree | null | undefined)
2315
  ?? { conj: "and", nodes: [] },
2316
+ ...(drillAggregateField ? { aggregateField: drillAggregateField } : {}),
2317
+ ...(drillStep !== "none" ? { stepField: drillStep.field } : {}),
2318
  };
2319
 
2320
  return (
 
2387
  </div>
2388
  ) : (
2389
  <div className="sheet-body">
2390
+ {/* ⭐⭐ W51-T08 (owner instructions 8 and 10) — THERE IS NO PAGE TOOLBAR AND NO TITLE HERE,
2391
+ AND THAT IS THE RULE, NOT AN OMISSION. Exactly ONE ribbon sits above exactly ONE formula
2392
+ bar above the canvas; a `.sheet-toolbar` row holding an `<h1>` and a second Refresh
2393
+ button would be a THIRD band of chrome, and the workbook's name is already the selected
2394
+ row in the rail beside it. Refresh did not disappear, it MOVED: R8 puts it on the
2395
+ ribbon's own row, handed down as `onRefresh` (C1) rather than drawn here, because a
2396
+ sheet is a snapshot and the one act that changes every number on screen is a page-level
2397
+ act.
2398
+
2399
+ ⭐⭐ W57-T15 (owner instructions 6 and 12) — AND THE NOTICE NO LONGER SITS HERE EITHER.
2400
+ It used to render at the top of this column, so every refusal pushed the ribbon and the
2401
+ whole grid down under the reader's cursor. It now renders just above the tab strip; see
2402
+ `.sheet-tab-notices` below.
2403
+
2404
+ ⭐⭐ W53-T08 — THE `.sheet-status` LINE THAT SAT HERE IS DELETED (instruction 14). Its
2405
+ hook class went with it. ⚠ `verify_wiring.py:4124` still asserts that line's JSX is
2406
+ present in this file and has therefore been RED since W53-T08 landed; the gate is what
2407
+ is stale, not the code. */}
 
 
2408
 
2409
  {/* ⭐ THREE OUTCOMES, IN THE ORDER THEY CAN HAPPEN. A workbook is switching, so the
2410
  spinner again; a workbook is open, so the grid; nothing opened and `loading` is over,
 
2417
  <SheetGrid
2418
  workbook={book}
2419
  tab={tab}
2420
+ options={optionCatalogue}
2421
+ viewShadows={viewShadows}
2422
  // ⭐ W54-T34: a drill in flight is a round trip like a refresh, and the cell action bar
2423
  // reads exactly one prop for "a round trip is in flight". The page root's `data-drill`
2424
  // is what tells the two apart in the stylesheet.
 
2482
  </div>
2483
  )}
2484
 
2485
+ {/* `.sheet-notice` is a transient sentence about a refusal, not chrome.
2486
+ Keep messages above the tab strip so they cannot move the ribbon or the grid's
2487
+ origin (owner instructions 6 and 12). */}
2488
+ <div className="sheet-tab-notices">
2489
+ {notice && <p className="sheet-notice">{notice}</p>}
2490
+ </div>
2491
+
2492
  {/* ⭐⭐ THE TAB BAR (wave-49 R7), AND IT SITS AT THE BOTTOM OF THE WORKBOOK.
2493
  R7 says one rail entry is a WORKBOOK WITH TABS, so the tabs belong INSIDE the workbook
2494
  and never on the rail, which lists workbooks. The bottom is also Excel's own place for
 
2543
  <span className="sheet-ribbon-sep" aria-hidden />
2544
  <button
2545
  type="button"
2546
+ className="sheet-ribbon-btn sheet-tab-add"
2547
  onClick={onAddTab}
2548
  title="Add a sheet to this workbook"
2549
  >
2550
+ <svg
2551
+ width="16"
2552
+ height="16"
2553
+ viewBox="0 0 16 16"
2554
+ fill="none"
2555
+ stroke="currentColor"
2556
+ strokeWidth="1.4"
2557
+ strokeLinecap="round"
2558
+ aria-hidden="true"
2559
+ >
2560
+ <path d="M8 3v10M3 8h10" />
2561
+ </svg>
2562
  <span className="sheet-ribbon-label">Add sheet</span>
2563
  </button>
2564
  </div>
web/src/sheet/a1.ts CHANGED
@@ -29,6 +29,15 @@ export const indexToCol = (index: number): string => {
29
  return out;
30
  };
31
 
 
 
 
 
 
 
 
 
 
32
  export interface CellRef {
33
  sheet: string;
34
  colAbs: boolean;
 
29
  return out;
30
  };
31
 
32
+ /** W57-T01: a whole column from its 1-based index, e.g. 1 -> "A:A". */
33
+ export const columnRangeA1 = (col: number): string => {
34
+ const column = indexToCol(col);
35
+ return `${column}:${column}`;
36
+ };
37
+
38
+ /** W57-T01: a whole row from its 1-based index, e.g. 1 -> "1:1". */
39
+ export const rowRangeA1 = (row: number): string => `${row}:${row}`;
40
+
41
  export interface CellRef {
42
  sheet: string;
43
  colAbs: boolean;
web/src/sheet/bindingRefs.ts CHANGED
@@ -107,6 +107,84 @@ const asRecord = (value: unknown): Record<string, unknown> | null =>
107
  ? (value as Record<string, unknown>)
108
  : null;
109
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
110
  /** Read the string at a path, trimmed. Empty when any step of the path is missing. */
111
  const readAt = (root: Record<string, unknown>, path: readonly string[]): string => {
112
  let node: Record<string, unknown> | null = root;
@@ -295,6 +373,20 @@ export const filterFieldKeys = (tree: unknown): string[] => {
295
  return [...seen];
296
  };
297
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
298
  /**
299
  * C6's visible-field law: a person's ordered choice (or the database defaults) UNION every
300
  * field the filter needs. Invalid/stale field keys are removed, and the identity key stays first.
 
107
  ? (value as Record<string, unknown>)
108
  : null;
109
 
110
+ export type CopyAxis = "right" | "down" | "left" | "up";
111
+
112
+ export interface FilterStep {
113
+ binding: Record<string, unknown>;
114
+ changed: boolean;
115
+ /** No leaf in the tree names that field. */
116
+ noField: boolean;
117
+ /** The walk stopped at an option boundary rather than wrapping. */
118
+ atEnd: boolean;
119
+ }
120
+
121
+ const optionIndex = (options: readonly string[], value: string): number =>
122
+ options.findIndex((option) => String(option) === value);
123
+
124
+ /** An unknown value starts before the first option; walking past either end clamps. */
125
+ const walkOption = (
126
+ options: readonly string[], value: string, steps: number,
127
+ ): { value: string; atEnd: boolean } => {
128
+ if (options.length === 0 || steps === 0) return { value, atEnd: false };
129
+ const wanted = optionIndex(options, value) + steps;
130
+ const landed = Math.max(0, Math.min(options.length - 1, wanted));
131
+ return { value: String(options[landed]), atEnd: landed !== wanted };
132
+ };
133
+
134
+ /** Copy only changed paths through nested groups; unrelated clauses keep their exact records. */
135
+ const walkFilterNodes = (
136
+ nodes: readonly unknown[], field: string, next: (value: string) => string,
137
+ ): { nodes: readonly unknown[]; found: boolean; changed: boolean } => {
138
+ let found = false;
139
+ let changed = false;
140
+ const out = nodes.map((node) => {
141
+ const record = asRecord(node);
142
+ if (!record) return node;
143
+ if (Array.isArray(record.children)) {
144
+ const inner = walkFilterNodes(record.children, field, next);
145
+ found = found || inner.found;
146
+ if (!inner.changed) return node;
147
+ changed = true;
148
+ return { ...record, children: inner.nodes };
149
+ }
150
+ if (String(record.colId ?? "") !== field) return node;
151
+ found = true;
152
+ const value = String(record.value ?? "");
153
+ const walked = next(value);
154
+ if (walked === value) return node;
155
+ changed = true;
156
+ return { ...record, value: walked };
157
+ });
158
+ return { nodes: changed ? out : nodes, found, changed };
159
+ };
160
+
161
+ /** C4 / R8: right and down advance by n; left and up reverse that distance. */
162
+ export const stepBindingFilter = (
163
+ binding: Record<string, unknown>, field: string, options: readonly string[],
164
+ axis: CopyAxis, n: number,
165
+ ): FilterStep => {
166
+ const steps = n * (axis === "left" || axis === "up" ? -1 : 1);
167
+ const scope = asRecord(binding.scope);
168
+ const tree = asRecord(scope?.filter);
169
+ if (!tree || !Array.isArray(tree.nodes)) {
170
+ return { binding, changed: false, noField: true, atEnd: false };
171
+ }
172
+ let atEnd = false;
173
+ const walked = walkFilterNodes(tree.nodes, field, (value) => {
174
+ const option = walkOption(options, value, steps);
175
+ atEnd = atEnd || option.atEnd;
176
+ return option.value;
177
+ });
178
+ return {
179
+ binding: walked.changed
180
+ ? { ...binding, scope: { ...scope, filter: { ...tree, nodes: walked.nodes } } }
181
+ : binding,
182
+ changed: walked.changed,
183
+ noField: !walked.found,
184
+ atEnd,
185
+ };
186
+ };
187
+
188
  /** Read the string at a path, trimmed. Empty when any step of the path is missing. */
189
  const readAt = (root: Record<string, unknown>, path: readonly string[]): string => {
190
  let node: Record<string, unknown> | null = root;
 
373
  return [...seen];
374
  };
375
 
376
+ /** Fields that explain a cell's rows and value, regardless of the database's default columns. */
377
+ export const cellForcedFieldKeys = (
378
+ filterTree: unknown,
379
+ aggregateField?: string,
380
+ stepField?: string,
381
+ ): string[] => {
382
+ const keys = new Set(filterFieldKeys(filterTree));
383
+ for (const field of [aggregateField, stepField]) {
384
+ const key = field?.trim();
385
+ if (key && !key.startsWith("__")) keys.add(key);
386
+ }
387
+ return [...keys];
388
+ };
389
+
390
  /**
391
  * C6's visible-field law: a person's ordered choice (or the database defaults) UNION every
392
  * field the filter needs. Invalid/stale field keys are removed, and the identity key stays first.
web/src/sheet/formulaAssist.ts CHANGED
@@ -198,12 +198,22 @@ export interface CellReference {
198
  end: CellRef;
199
  /** 0-5, a slot into the fixed six colour rotation in refColors.ts (CR-4). */
200
  colorIndex: number;
 
 
 
201
  }
202
 
203
  /** One reference candidate, matched but not yet range-joined. */
204
  const REF_TOKEN =
205
  "(?:(?:'([^']{1,64})'|([A-Za-z_][A-Za-z0-9_]{0,63}))!)?(\\$?)([A-Za-z]{1,3})(\\$?)([1-9][0-9]{0,6})";
206
 
 
 
 
 
 
 
 
207
  /**
208
  * CR-1..CR-5, CR-9: every distinct cell or range reference in `text`, in order of FIRST
209
  * appearance, each carrying a colour slot from the fixed six colour rotation (CR-4) -- the same
@@ -222,6 +232,7 @@ const REF_TOKEN =
222
  export function refsIn(text: string): CellReference[] {
223
  const src = String(text || "");
224
  const scan = new RegExp(REF_TOKEN, "gy");
 
225
  const out: CellReference[] = [];
226
  const slotByKey = new Map<string, number>();
227
  let nextSlot = 0;
@@ -239,6 +250,36 @@ export function refsIn(text: string): CellReference[] {
239
  return { token: m[0], ref };
240
  };
241
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
242
  while (i < src.length) {
243
  const c = src[i];
244
  if (quote) {
@@ -262,13 +303,14 @@ export function refsIn(text: string): CellReference[] {
262
  }
263
  const prev = i ? src[i - 1] : "";
264
  const boundary = !/[A-Za-z0-9_$]/.test(prev);
265
- if (boundary && /[A-Za-z$']/.test(c)) {
266
- const first = matchAt(i);
 
267
  if (first) {
268
  let fullText = first.token;
269
- let end = first.ref;
270
  let cursor = i + first.token.length;
271
- if (src[cursor] === ":") {
272
  const second = matchAt(cursor + 1);
273
  if (second) {
274
  fullText = `${first.token}:${second.token}`;
@@ -289,6 +331,7 @@ export function refsIn(text: string): CellReference[] {
289
  start: first.ref,
290
  end,
291
  colorIndex: slot,
 
292
  });
293
  i = cursor;
294
  continue;
 
198
  end: CellRef;
199
  /** 0-5, a slot into the fixed six colour rotation in refColors.ts (CR-4). */
200
  colorIndex: number;
201
+ /** W57-T01: a whole column or row. Endpoints carry only its axis position; a painter
202
+ * must bound the other axis against the sheet it is painting on. */
203
+ band?: "column" | "row";
204
  }
205
 
206
  /** One reference candidate, matched but not yet range-joined. */
207
  const REF_TOKEN =
208
  "(?:(?:'([^']{1,64})'|([A-Za-z_][A-Za-z0-9_]{0,63}))!)?(\\$?)([A-Za-z]{1,3})(\\$?)([1-9][0-9]{0,6})";
209
 
210
+ // W57-T01: only identical axes form a band; matchBandAt checks equality after matching.
211
+ // The trailing boundary prevents A:A1 or 1:10 from being accepted as a shorter band.
212
+ const BAND_TOKEN =
213
+ "(?:(?:'([^']{1,64})'|([A-Za-z_][A-Za-z0-9_]{0,63}))!)?(\\$?)"
214
+ + "([A-Za-z]{1,3}|[1-9][0-9]{0,6}):(\\$?)([A-Za-z]{1,3}|[1-9][0-9]{0,6})"
215
+ + "(?![A-Za-z0-9_$!])";
216
+
217
  /**
218
  * CR-1..CR-5, CR-9: every distinct cell or range reference in `text`, in order of FIRST
219
  * appearance, each carrying a colour slot from the fixed six colour rotation (CR-4) -- the same
 
232
  export function refsIn(text: string): CellReference[] {
233
  const src = String(text || "");
234
  const scan = new RegExp(REF_TOKEN, "gy");
235
+ const bandScan = new RegExp(BAND_TOKEN, "gy");
236
  const out: CellReference[] = [];
237
  const slotByKey = new Map<string, number>();
238
  let nextSlot = 0;
 
250
  return { token: m[0], ref };
251
  };
252
 
253
+ const matchBandAt = (pos: number): {
254
+ token: string; ref: CellRef; end: CellRef; band: "column" | "row";
255
+ } | null => {
256
+ bandScan.lastIndex = pos;
257
+ const m = bandScan.exec(src);
258
+ if (!m || m.index !== pos) return null;
259
+ if (m[4].toUpperCase() !== m[6].toUpperCase()) return null;
260
+ const after = src.slice(pos + m[0].length);
261
+ if (/^\s*\(/.test(after)) return null;
262
+ const isColumn = /^[A-Za-z]/.test(m[4]);
263
+ // parseRef stays cell-only: widening it would also change fill and structural rewrites.
264
+ const ref: CellRef = {
265
+ sheet: m[1] || m[2] || "",
266
+ colAbs: isColumn && m[3] === "$",
267
+ col: isColumn ? m[4].toUpperCase() : "A",
268
+ rowAbs: !isColumn && m[3] === "$",
269
+ row: isColumn ? 1 : Number(m[4]),
270
+ };
271
+ return {
272
+ token: m[0],
273
+ ref,
274
+ end: {
275
+ ...ref,
276
+ colAbs: isColumn && m[5] === "$",
277
+ rowAbs: !isColumn && m[5] === "$",
278
+ },
279
+ band: isColumn ? "column" : "row",
280
+ };
281
+ };
282
+
283
  while (i < src.length) {
284
  const c = src[i];
285
  if (quote) {
 
303
  }
304
  const prev = i ? src[i - 1] : "";
305
  const boundary = !/[A-Za-z0-9_$]/.test(prev);
306
+ if (boundary && /[A-Za-z0-9$']/.test(c)) {
307
+ const band = matchBandAt(i);
308
+ const first = matchAt(i) ?? band;
309
  if (first) {
310
  let fullText = first.token;
311
+ let end = band?.end ?? first.ref;
312
  let cursor = i + first.token.length;
313
+ if (!band && src[cursor] === ":") {
314
  const second = matchAt(cursor + 1);
315
  if (second) {
316
  fullText = `${first.token}:${second.token}`;
 
331
  start: first.ref,
332
  end,
333
  colorIndex: slot,
334
+ ...(band ? { band: band.band } : {}),
335
  });
336
  i = cursor;
337
  continue;
web/src/sheet/formulaEval.ts CHANGED
@@ -2,13 +2,13 @@
2
  //
3
  // ⭐⭐ RULING R2: a formula that references only OTHER CELLS evaluates HERE, the instant it is
4
  // committed, and never touches the network. `evaluateFormula` is the whole of that: a small,
5
- // self-contained engine over numeric literals, A1 cell references (with Excel's `$` tolerated),
6
  // the four operators, parentheses, and C1's five aggregate functions (SUM/COUNT/AVG/MIN/MAX) plus
7
  // COUNTA (W54-T27), each run over one simple range. It is NOT a reimplementation of the server's
8
- // full grammar
9
- // (`api/formula_runtime.py::evaluate_sheet`) — cross-sheet references are admitted only through
10
- // an explicitly workbook-aware getter, and there is no function catalogue beyond the five
11
- // aggregates.
12
  //
13
  // ⛔⛔ AND WHAT IT CANNOT ANSWER IS `unsupported`, NEVER AN ERROR. That distinction is the whole
14
  // safety of shipping a second, smaller engine beside the server's: `=IF(...)` and a qualified
@@ -207,9 +207,9 @@ type Token =
207
  | { t: "fn"; v: string }
208
  | { t: "str"; v: string }
209
  | { t: "err"; v: FormulaErrorCode }
210
- | { t: "op"; v: "+" | "-" | "*" | "/" | "(" | ")" | ":" };
211
 
212
- const OPS = "+-*/():";
213
 
214
  /**
215
  * ⚠ A LETTER RUN IS A CELL REFERENCE ONLY WHEN DIGITS FOLLOW IT WITH NO GAP. `SUM` ahead of `(`
@@ -227,7 +227,7 @@ const tokenize = (src: string, qualified = false): Token[] => {
227
  const ch = text[i];
228
  if (/\s/.test(ch)) { i += 1; continue; }
229
  if (OPS.includes(ch)) {
230
- tokens.push({ t: "op", v: ch as "+" | "-" | "*" | "/" | "(" | ")" | ":" });
231
  i += 1;
232
  continue;
233
  }
@@ -282,8 +282,8 @@ const tokenize = (src: string, qualified = false): Token[] => {
282
  continue;
283
  }
284
  // ⭐ W54-T26: A QUOTED RUN IS A TEXT LITERAL, so `=1+"x"` can say `#VALUE!` about the thing
285
- // that is actually wrong with it. It is still only a literal: a comma, a `&` and a comparison
286
- // all remain unreadable here, so every function call carrying one is still the server's.
287
  if (ch === '"' || ch === "'") {
288
  const close = text.indexOf(ch, i + 1);
289
  if (close < 0) throw new Unsupported("token");
@@ -291,7 +291,7 @@ const tokenize = (src: string, qualified = false): Token[] => {
291
  i = close + 1;
292
  continue;
293
  }
294
- // A comma, an unrecognised `!`, a `%`, a `^`: every one of them is a formula the SERVER can read
295
  // and this file cannot. See the header: that is `unsupported`, never an error.
296
  throw new Unsupported("token");
297
  }
@@ -856,6 +856,14 @@ export const qualifiedRecalcOrder = (
856
  /** A number in progress, carrying whether any input it used was `pending` (last known, not fresh). */
857
  interface Num { n: number; pending: boolean }
858
 
 
 
 
 
 
 
 
 
859
  const toNum = (cv: CellValue): Num => {
860
  if (cv.kind === "number") return { n: cv.value, pending: cv.pending === true };
861
  if (cv.kind === "text") {
@@ -980,23 +988,401 @@ const rangeEndpoint = (tok: Token, name: string): string => {
980
  return tok.v;
981
  };
982
 
983
- const parseAtom = (c: Cursor, get: Getter): Num => {
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
984
  const tk = take(c);
985
  if (tk.t === "num") return { n: tk.v, pending: false };
986
- if (tk.t === "ref") return toNum(get(tk.v));
987
  // ⭐⭐ W54-T26: AN ERROR PROPAGATES THROUGH ARITHMETIC, EXACTLY AS EXCEL DOES. Reading one is
988
  // the same as reading a cell that holds one, so it takes the same road out: a thrown
989
  // `FormulaError` whose message already states the code, which `errorValue` passes through.
990
  if (tk.t === "err") throw new FormulaError(tk.v);
991
  // ⭐ W54-T26: a text literal coerces the way a text CELL does, so `=1+"1"` is 2 and `=1+"x"`
992
  // is `#VALUE!`, which is Excel's own answer to both.
993
- if (tk.t === "str") return toNum({ kind: "text", value: tk.v });
994
  if (tk.t === "fn") {
995
  const name = tk.v;
996
  // ⭐⭐ W54-T26: A BARE NAME IS NOT A CALL AND NOTHING CAN RESOLVE IT. `=FOO` names a thing,
997
  // and NEITHER engine has named ranges, so no round trip to the server can turn it into a
998
  // value. That makes it the one name this file may refuse on its own: `#NAME?`.
999
  if (!isOp(peekTok(c), "(")) throw new FormulaError(NAME_NOT_FOUND);
 
1000
  // ⭐ EVERY OTHER FUNCTION IN THE CATALOGUE IS THE SERVER'S. `IF`, `ROUND`, `TEXT` and the
1001
  // rest are real formulas this file does not speak, so they take the `unsupported` road home
1002
  // and keep working exactly as they did before this ticket (see the header).
@@ -1005,6 +1391,13 @@ const parseAtom = (c: Cursor, get: Getter): Num => {
1005
  if (!AGGREGATE_SET.has(name)) throw new Unsupported(name);
1006
  take(c);
1007
  const from = rangeEndpoint(take(c), name);
 
 
 
 
 
 
 
1008
  if (!isOp(peekTok(c), ":")) throw new Unsupported(name);
1009
  take(c);
1010
  const to = rangeEndpoint(take(c), name);
@@ -1021,45 +1414,47 @@ const parseAtom = (c: Cursor, get: Getter): Num => {
1021
  throw new Unsupported("token");
1022
  };
1023
 
1024
- const parseUnary = (c: Cursor, get: Getter): Num => {
1025
  if (isOp(peekTok(c), "-")) {
1026
  take(c);
1027
- const inner = parseUnary(c, get);
1028
  return { n: -inner.n, pending: inner.pending };
1029
  }
1030
- if (isOp(peekTok(c), "+")) { take(c); return parseUnary(c, get); }
1031
  return parseAtom(c, get);
1032
  };
1033
 
1034
- const parseTerm = (c: Cursor, get: Getter): Num => {
1035
- let left = parseUnary(c, get);
1036
  while (isOp(peekTok(c), "*") || isOp(peekTok(c), "/")) {
1037
  const op = take(c);
1038
- const right = parseUnary(c, get);
 
1039
  if (op.t === "op" && op.v === "/") {
1040
  // ⛔ A DIVISOR THAT IS ONLY ZERO BECAUSE IT HAS NOT LOADED IS NOT A DIVISION BY ZERO. It is
1041
  // a value nobody has yet, so the whole formula waits rather than accusing the reader of
1042
  // dividing by something they never wrote.
1043
  if (right.n === 0 && right.pending) throw new PendingInput("divisor");
1044
  if (right.n === 0) throw new FormulaError("This formula divides by zero.");
1045
- left = { n: left.n / right.n, pending: left.pending || right.pending };
1046
  } else {
1047
- left = { n: left.n * right.n, pending: left.pending || right.pending };
1048
  }
1049
  }
1050
- return left;
1051
  };
1052
 
1053
- const parseExpr = (c: Cursor, get: Getter): Num => {
1054
- let left = parseTerm(c, get);
1055
  while (isOp(peekTok(c), "+") || isOp(peekTok(c), "-")) {
1056
  const op = take(c);
1057
- const right = parseTerm(c, get);
 
1058
  const plus = op.t === "op" && op.v === "+";
1059
- left = { n: plus ? left.n + right.n : left.n - right.n,
1060
  pending: left.pending || right.pending };
1061
  }
1062
- return left;
1063
  };
1064
 
1065
  /**
@@ -1078,8 +1473,8 @@ const cleanNumber = (n: number): number => {
1078
  * accepted so a caller can hand this either the raw stored formula or its own trimmed draft.
1079
  *
1080
  * ⭐ A BARE SINGLE REFERENCE PASSES THROUGH UNCOERCED. `=F6` of a text cell is F6's text, not a
1081
- * refusal: only once an operator or a function is involved does this coerce through arithmetic,
1082
- * exactly as Excel's own distinction between "reads a cell" and "computes with a cell" works.
1083
  *
1084
  * ⛔ NEVER THROWS. Every outcome — a token this engine does not speak, a function that belongs to
1085
  * the server, a division by zero, a reference to a cell held in a genuine error state — comes
@@ -1100,8 +1495,13 @@ export const evaluateFormula = (src: string, get: Getter): CellValue => {
1100
  return one.t === "ref" ? get(one.v) : { kind: "empty" };
1101
  }
1102
  const cursor: Cursor = { tokens, i: 0 };
1103
- const result = parseExpr(cursor, get);
1104
  if (!atEnd(cursor)) throw new Unsupported("trailing tokens");
 
 
 
 
 
1105
  if (!Number.isFinite(result.n)) {
1106
  return { kind: "error", message: "This formula could not be calculated." };
1107
  }
 
2
  //
3
  // ⭐⭐ RULING R2: a formula that references only OTHER CELLS evaluates HERE, the instant it is
4
  // committed, and never touches the network. `evaluateFormula` is the whole of that: a small,
5
+ // self-contained engine over literals, A1 cell references (with Excel's `$` tolerated),
6
  // the four operators, parentheses, and C1's five aggregate functions (SUM/COUNT/AVG/MIN/MAX) plus
7
  // COUNTA (W54-T27), each run over one simple range. It is NOT a reimplementation of the server's
8
+ // full grammar (`api/formula_runtime.py::evaluate_sheet`). W57-T06 adds scalar lookup results
9
+ // and comma-separated lookup arguments. Cross-sheet references are admitted only through
10
+ // an explicitly workbook-aware getter. W57-T07 adds five server-backed text/date functions
11
+ // through the same argument parser; unsupported forms still belong to Refresh.
12
  //
13
  // ⛔⛔ AND WHAT IT CANNOT ANSWER IS `unsupported`, NEVER AN ERROR. That distinction is the whole
14
  // safety of shipping a second, smaller engine beside the server's: `=IF(...)` and a qualified
 
207
  | { t: "fn"; v: string }
208
  | { t: "str"; v: string }
209
  | { t: "err"; v: FormulaErrorCode }
210
+ | { t: "op"; v: "+" | "-" | "*" | "/" | "(" | ")" | ":" | "," };
211
 
212
+ const OPS = "+-*/():,";
213
 
214
  /**
215
  * ⚠ A LETTER RUN IS A CELL REFERENCE ONLY WHEN DIGITS FOLLOW IT WITH NO GAP. `SUM` ahead of `(`
 
227
  const ch = text[i];
228
  if (/\s/.test(ch)) { i += 1; continue; }
229
  if (OPS.includes(ch)) {
230
+ tokens.push({ t: "op", v: ch as "+" | "-" | "*" | "/" | "(" | ")" | ":" | "," });
231
  i += 1;
232
  continue;
233
  }
 
282
  continue;
283
  }
284
  // ⭐ W54-T26: A QUOTED RUN IS A TEXT LITERAL, so `=1+"x"` can say `#VALUE!` about the thing
285
+ // that is actually wrong with it. W57-T06 also preserves literals as lookup arguments;
286
+ // concatenation and comparisons still belong to the server.
287
  if (ch === '"' || ch === "'") {
288
  const close = text.indexOf(ch, i + 1);
289
  if (close < 0) throw new Unsupported("token");
 
291
  i = close + 1;
292
  continue;
293
  }
294
+ // An unrecognised `!`, a `%`, a `^`: every one of them is a formula the SERVER can read
295
  // and this file cannot. See the header: that is `unsupported`, never an error.
296
  throw new Unsupported("token");
297
  }
 
856
  /** A number in progress, carrying whether any input it used was `pending` (last known, not fresh). */
857
  interface Num { n: number; pending: boolean }
858
 
859
+ // W57-T06: scalar lookup answers keep their text until an operator asks for a number.
860
+ // Num and the aggregate arithmetic stay intact, including the gate's mutation anchors.
861
+ type ExpressionValue = Num | CellValue;
862
+ const expressionNumber = (value: ExpressionValue): Num =>
863
+ "kind" in value ? toNum(value) : value;
864
+ const expressionCell = (value: ExpressionValue): CellValue =>
865
+ "kind" in value ? value : { kind: "number", value: value.n, pending: value.pending };
866
+
867
  const toNum = (cv: CellValue): Num => {
868
  if (cv.kind === "number") return { n: cv.value, pending: cv.pending === true };
869
  if (cv.kind === "text") {
 
988
  return tok.v;
989
  };
990
 
991
+ // W57-T06: retain a rectangle's shape beside the shared row-major address expansion.
992
+ // Whole bands, named ranges and array-producing expressions still belong to Refresh.
993
+ interface LookupRange { kind: "range"; addrs: string[]; rows: number; cols: number; explicit: boolean }
994
+ interface LookupBoolean { kind: "boolean"; literal: "TRUE" | "FALSE" }
995
+ type LookupArgument = CellValue | LookupRange | LookupBoolean;
996
+ // W57-T07: one dispatch table and argument loop for lookups, text and dates. TEXTJOIN's
997
+ // variadic cap is formula_runtime.py's MANY (30); larger calls defer to its arity refusal.
998
+ const CALL_ARITY: Readonly<Record<string, readonly [number, number]>> = {
999
+ XLOOKUP: [3, 5], VLOOKUP: [3, 4], INDEX: [2, 3], MATCH: [2, 3], CHOOSE: [2, 255],
1000
+ TEXTJOIN: [3, 30], SUBSTITUTE: [3, 4], EOMONTH: [2, 2], WORKDAY: [2, 3], NETWORKDAYS: [2, 3],
1001
+ };
1002
+
1003
+ const parseLookupArgument = (
1004
+ c: Cursor, get: Getter, booleanFlag: string | undefined, booleanLiterals = false,
1005
+ ): LookupArgument => {
1006
+ const first = peekTok(c);
1007
+ const next = c.tokens[c.i + 1];
1008
+ // W57-T07: reuse W57-T06's real-boolean flag for TEXTJOIN. Text arguments may also spell
1009
+ // TRUE/FALSE for the server's _text conversion; a bare name outside these calls is unchanged.
1010
+ if (booleanFlag || booleanLiterals) {
1011
+ if (first?.t === "fn" && (first.v === "FALSE" || first.v === "TRUE")
1012
+ && (isOp(next, ",") || isOp(next, ")"))) {
1013
+ take(c);
1014
+ return { kind: "boolean", literal: first.v };
1015
+ }
1016
+ // W57-T06: the server takes a boolean and refuses a number. Numeric flags and
1017
+ // expressions must reach the server, even when they would evaluate to zero here.
1018
+ if (booleanFlag) throw new Unsupported(booleanFlag);
1019
+ }
1020
+ if (first?.t === "ref" && (isOp(next, ":") || isOp(next, ",") || isOp(next, ")"))) {
1021
+ take(c);
1022
+ let last = first.v;
1023
+ if (isOp(peekTok(c), ":")) {
1024
+ take(c);
1025
+ last = rangeEndpoint(take(c), "lookup range");
1026
+ }
1027
+ const a = splitRef(first.v);
1028
+ const b = splitRef(last);
1029
+ return { kind: "range", addrs: rangeAddresses(first.v, last), explicit: isOp(next, ":"),
1030
+ rows: Math.abs(a.row - b.row) + 1, cols: Math.abs(a.col - b.col) + 1 };
1031
+ }
1032
+ // W57-T06: recurse through the expression grammar; nested calls and 1+2 keep precedence.
1033
+ return expressionCell(parseExpr(c, get));
1034
+ };
1035
+
1036
+ // W57-T06: match the server's _values_equal (numeric strings, then case-insensitive text).
1037
+ // Do not use arithmetic's comma-stripping coercion for lookup keys: "1,000" is text there.
1038
+ const lookupKey = (value: CellValue): number | string => {
1039
+ if (value.kind === "number") {
1040
+ if (!Number.isFinite(value.value)) throw new Unsupported("lookup number");
1041
+ return value.value;
1042
+ }
1043
+ if (value.kind === "empty") return "";
1044
+ if (value.kind === "pending") throw new PendingInput("lookup key");
1045
+ if (value.kind !== "text") { toNum(value); throw new Unsupported("lookup key"); }
1046
+ const trimmed = value.value.trim();
1047
+ if (/^[+-]?(?:\d(?:_?\d)*(?:\.(?:\d(?:_?\d)*)?)?|\.\d(?:_?\d)*)(?:[eE][+-]?\d(?:_?\d)*)?$/.test(trimmed)) {
1048
+ const n = Number(trimmed.replace(/_/g, ""));
1049
+ if (Number.isFinite(n)) return n;
1050
+ }
1051
+ // Python casefold and JavaScript lowercase differ for some Unicode text. Defer those
1052
+ // comparisons instead of presenting an answer that can change at Refresh.
1053
+ if (/[^\x00-\x7f]/.test(value.value)) throw new Unsupported("lookup Unicode comparison");
1054
+ return value.value.toLowerCase();
1055
+ };
1056
+
1057
+ // W57-T07: mirror _text without arithmetic coercion. Python's float spelling differs for
1058
+ // tiny fractions and large integers; defer those instead of changing text after Refresh.
1059
+ const functionText = (value: CellValue): string => {
1060
+ if (value.kind === "text") return value.value;
1061
+ if (value.kind === "empty") return "";
1062
+ if (value.kind === "pending") throw new PendingInput("text argument");
1063
+ if (value.kind === "number") {
1064
+ const n = value.value;
1065
+ if (!Number.isFinite(n) || (Number.isInteger(n) && !Number.isSafeInteger(n))
1066
+ || (n !== 0 && Math.abs(n) < 0.0001)) throw new Unsupported("text number spelling");
1067
+ return String(n);
1068
+ }
1069
+ toNum(value);
1070
+ throw new Unsupported("text argument");
1071
+ };
1072
+
1073
+ // W57-T07: _num accepts decimal numeric text, including exponents and underscores, but
1074
+ // never arithmetic's comma stripping, hex or blank-as-zero. Unicode numerals defer because
1075
+ // Python float accepts spellings JavaScript Number does not. Null mirrors _num's no-number.
1076
+ const functionNumber = (value: CellValue): number | null => {
1077
+ if (value.kind === "pending") throw new PendingInput("numeric argument");
1078
+ if (value.kind === "empty") return null;
1079
+ if (value.kind === "number") return Number.isFinite(value.value) ? value.value : null;
1080
+ if (value.kind !== "text") { toNum(value); throw new Unsupported("numeric argument"); }
1081
+ if (/[^\x00-\x7f]/.test(value.value)) throw new Unsupported("numeric Unicode argument");
1082
+ const trimmed = value.value.trim();
1083
+ if (!/^[+-]?(?:\d(?:_?\d)*(?:\.(?:\d(?:_?\d)*)?)?|\.\d(?:_?\d)*)(?:[eE][+-]?\d(?:_?\d)*)?$/.test(trimmed)) return null;
1084
+ const n = Number(trimmed.replace(/_/g, ""));
1085
+ return Number.isFinite(n) ? n : null;
1086
+ };
1087
+
1088
+ const MAX_DAY_SPAN = 20_000;
1089
+ const CALENDAR_DAY_MS = 86_400_000;
1090
+
1091
+ // W57-T07: dates are ISO strings, never serials or local time. Use UTC for every calendar
1092
+ // operation so a reader west of Greenwich cannot see the previous date. setUTCFullYear also
1093
+ // avoids Date.UTC's special 1900 offset for years 0 through 99.
1094
+ const utcCalendarDate = (year: number, month: number, day: number): Date => {
1095
+ const date = new Date(0);
1096
+ date.setUTCFullYear(year, month - 1, day);
1097
+ return date;
1098
+ };
1099
+
1100
+ const functionDate = (value: CellValue): Date | null => {
1101
+ if (value.kind === "pending") throw new PendingInput("date argument");
1102
+ if (value.kind === "error" || value.kind === "unsupported") toNum(value);
1103
+ if (value.kind !== "text") return null;
1104
+ // W57-T07: _date reads only the first ten characters, accepting timestamp suffixes.
1105
+ // Other ISO spellings remain server-owned rather than using JavaScript's loose parser.
1106
+ const prefix = value.value.slice(0, 10);
1107
+ if (!/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/.test(prefix)) return null;
1108
+ const year = Number(prefix.slice(0, 4));
1109
+ const month = Number(prefix.slice(5, 7));
1110
+ const day = Number(prefix.slice(8, 10));
1111
+ if (year < 1 || month < 1 || month > 12 || day < 1 || day > 31) return null;
1112
+ const date = utcCalendarDate(year, month, day);
1113
+ return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1
1114
+ && date.getUTCDate() === day ? date : null;
1115
+ };
1116
+
1117
+ const functionDateText = (date: Date): string => {
1118
+ // W57-T07: Python dates stop at years 1..9999; its overflow outcome belongs to Refresh.
1119
+ const year = date.getUTCFullYear();
1120
+ if (!Number.isFinite(year) || year < 1 || year > 9999) throw new Unsupported("date overflow");
1121
+ return date.toISOString().slice(0, 10);
1122
+ };
1123
+
1124
+ const parseLookup = (name: string, c: Cursor, get: Getter): CellValue => {
1125
+ const textOrDate = name === "TEXTJOIN" || name === "SUBSTITUTE" || name === "EOMONTH"
1126
+ || name === "WORKDAY" || name === "NETWORKDAYS";
1127
+ let pending = false;
1128
+ const observe = (value: CellValue): CellValue => {
1129
+ if (value.kind === "pending"
1130
+ || ((value.kind === "number" || value.kind === "text") && value.pending)) pending = true;
1131
+ return value;
1132
+ };
1133
+ // W57-T06: every actual read, including a preceding non-match or an argument expression,
1134
+ // contributes its pending flag. Preserve workbook qualification on the wrapped getter.
1135
+ const read: Getter = (addr) => observe(get(addr));
1136
+ if (get.workbookReferences) read.workbookReferences = true;
1137
+ const args: LookupArgument[] = [];
1138
+ take(c); // Opening parenthesis already checked by parseAtom.
1139
+ if (isOp(peekTok(c), ")")) throw new Unsupported(name + " arguments");
1140
+ while (true) {
1141
+ const booleanFlag = name === "VLOOKUP" && args.length === 3 ? "VLOOKUP approximate match"
1142
+ : name === "TEXTJOIN" && args.length === 1 ? "TEXTJOIN ignore_empty" : undefined;
1143
+ args.push(parseLookupArgument(c, read, booleanFlag, textOrDate));
1144
+ if (isOp(peekTok(c), ")")) { take(c); break; }
1145
+ if (!isOp(peekTok(c), ",")) throw new Unsupported(name + " arguments");
1146
+ take(c);
1147
+ }
1148
+ const [min, max] = CALL_ARITY[name];
1149
+ if (args.length < min || args.length > max) throw new Unsupported(name + " arguments");
1150
+ const scalar = (index: number): CellValue => {
1151
+ const arg = args[index];
1152
+ if (arg.kind === "boolean") throw new Unsupported(name + " scalar argument");
1153
+ if (arg.kind !== "range") return observe(arg);
1154
+ // W57-T07: A1 is a scalar read, but even A1:A1 is explicit range syntax. Defer ranges
1155
+ // at new scalar positions instead of flattening them and shifting argument meanings.
1156
+ if (textOrDate && arg.explicit) throw new Unsupported(name + " scalar argument");
1157
+ if (arg.addrs.length !== 1) throw new Unsupported(name + " scalar argument");
1158
+ return read(arg.addrs[0]);
1159
+ };
1160
+ const number = (index: number): number => {
1161
+ const value = scalar(index);
1162
+ if (value.kind === "pending") throw new PendingInput("lookup argument");
1163
+ const numeric = toNum(value);
1164
+ pending = pending || numeric.pending;
1165
+ if (!Number.isFinite(numeric.n)) throw new Unsupported(name + " numeric argument");
1166
+ return numeric.n;
1167
+ };
1168
+ const range = (index: number): LookupRange => {
1169
+ const arg = args[index];
1170
+ if (arg.kind !== "range") throw new Unsupported(name + " range argument");
1171
+ return arg;
1172
+ };
1173
+ const finish = (value: CellValue): CellValue => {
1174
+ observe(value);
1175
+ // W57-T06: propagate a selected error here, after a nested aggregate has had its own
1176
+ // chance to ignore error cells for COUNT/COUNTA. The tracking getter must not throw.
1177
+ if (value.kind === "error" || value.kind === "unsupported") toNum(value);
1178
+ if (pending && (value.kind === "number" || value.kind === "text")) {
1179
+ return { ...value, pending: true };
1180
+ }
1181
+ return pending && value.kind === "empty" ? { kind: "pending" } : value;
1182
+ };
1183
+ const noMatch = (): never => {
1184
+ if (pending) throw new PendingInput("lookup match");
1185
+ // W57-T06: Excel's #N/A is outside the shared four-code vocabulary. This deliberate
1186
+ // deferral lets the server report no_match without inventing a fifth client error code.
1187
+ throw new Unsupported(name + " no match (#N/A)");
1188
+ };
1189
+
1190
+ if (name === "TEXTJOIN" || name === "SUBSTITUTE") {
1191
+ const text = (index: number): string => {
1192
+ const arg = args[index];
1193
+ return arg.kind === "boolean" ? arg.literal : functionText(scalar(index));
1194
+ };
1195
+ if (name === "TEXTJOIN") {
1196
+ const delimiter = text(0);
1197
+ const flag = args[1];
1198
+ if (flag.kind !== "boolean") throw new Unsupported("TEXTJOIN ignore_empty");
1199
+ const parts: string[] = [];
1200
+ for (let i = 2; i < args.length; i += 1) {
1201
+ const part = text(i);
1202
+ if (flag.literal === "FALSE" || part !== "") parts.push(part);
1203
+ }
1204
+ return finish({ kind: "text", value: parts.join(delimiter) });
1205
+ }
1206
+ const source = text(0);
1207
+ const old = text(1);
1208
+ const replacement = text(2);
1209
+ // W57-T07: Python inserts around characters for replace("", ...), but split("") raises
1210
+ // for an instance request. Defer both empty separators rather than inventing that result.
1211
+ if (old === "") throw new Unsupported("SUBSTITUTE empty old_text");
1212
+ const parts = source.split(old);
1213
+ if (args.length === 3) return finish({ kind: "text", value: parts.join(replacement) });
1214
+ const instance = args[3].kind === "boolean" ? null : functionNumber(scalar(3));
1215
+ const occurrence = Math.trunc(instance ?? 0);
1216
+ // W57-T07: reproduce the server's Python slices even for zero/negative occurrences;
1217
+ // Excel's invalid-instance rules would give a different answer on the next Refresh.
1218
+ const value = parts.slice(0, occurrence).join(old)
1219
+ + (occurrence > 0 && occurrence < parts.length
1220
+ ? replacement + parts.slice(occurrence).join(old) : "");
1221
+ return finish({ kind: "text", value });
1222
+ }
1223
+
1224
+ if (name === "EOMONTH" || name === "WORKDAY" || name === "NETWORKDAYS") {
1225
+ const date = (index: number): Date => {
1226
+ const parsed = functionDate(scalar(index));
1227
+ // W57-T07: _date returns None without bad_value. Refresh owns the resulting blank or
1228
+ // refusal; do not label an unparseable date #VALUE! just because JavaScript rejected it.
1229
+ if (!parsed) throw new Unsupported(name + " date argument");
1230
+ return parsed;
1231
+ };
1232
+ const strictNumber = (index: number): number => {
1233
+ const n = functionNumber(scalar(index));
1234
+ // W57-T07: _strict_num distinguishes blank from bad_value. Defer either no-number
1235
+ // case so arithmetic's zero coercion cannot turn a missing offset into a real date.
1236
+ if (n === null) throw new Unsupported(name + " numeric argument");
1237
+ return Math.trunc(n);
1238
+ };
1239
+ const start = date(0);
1240
+ if (name === "EOMONTH") {
1241
+ const months = strictNumber(1);
1242
+ const index = start.getUTCMonth() + months;
1243
+ const year = start.getUTCFullYear() + Math.floor(index / 12);
1244
+ const month = ((index % 12) + 12) % 12 + 1;
1245
+ // W57-T07: _month_shift clamps the original day, then EOMONTH discards it. Day zero
1246
+ // of the following month gives that same last day, including leap years and negatives.
1247
+ if (!Number.isSafeInteger(months) || year < 1 || year > 9999) {
1248
+ throw new Unsupported("EOMONTH date overflow");
1249
+ }
1250
+ return finish({ kind: "text", value: functionDateText(utcCalendarDate(year, month + 1, 0)) });
1251
+ }
1252
+ const end = name === "NETWORKDAYS" ? date(1) : null;
1253
+ const days = end ? (end.getTime() - start.getTime()) / CALENDAR_DAY_MS : strictNumber(1);
1254
+ if (Math.abs(days) > MAX_DAY_SPAN) {
1255
+ throw new FormulaError(ERROR_VALUE + " Working day span exceeds 20000 days.");
1256
+ }
1257
+ const holidays = new Set<number>();
1258
+ if (args.length > 2) {
1259
+ const arg = args[2];
1260
+ // W57-T07: the server accepts a holiday range or scalar and ignores invalid entries.
1261
+ // Read every range member through read so even a pending holiday marks the answer.
1262
+ if (arg.kind !== "boolean") {
1263
+ const values = arg.kind === "range" ? arg.addrs.map(read) : [scalar(2)];
1264
+ for (const value of values) {
1265
+ const parsed = functionDate(value);
1266
+ // W57-T07: a non-ISO holiday (including an integer YYYYMMDD) might be a spelling
1267
+ // Python accepts. Defer nonblank invalid entries instead of dropping a holiday.
1268
+ if (!parsed && value.kind !== "empty" && !(value.kind === "text" && value.value === "")) {
1269
+ throw new Unsupported(name + " holiday date");
1270
+ }
1271
+ if (parsed) holidays.add(parsed.getTime());
1272
+ }
1273
+ }
1274
+ }
1275
+ const working = (cursor: Date): boolean => cursor.getUTCDay() !== 0
1276
+ && cursor.getUTCDay() !== 6 && !holidays.has(cursor.getTime());
1277
+ const step = days >= 0 ? 1 : -1;
1278
+ const cursor = new Date(start.getTime());
1279
+ if (end) {
1280
+ let counted = 0;
1281
+ // W57-T07: both ends count, including the start when dates run backwards.
1282
+ while (true) {
1283
+ if (working(cursor)) counted += 1;
1284
+ if (cursor.getTime() === end.getTime()) break;
1285
+ cursor.setUTCDate(cursor.getUTCDate() + step);
1286
+ }
1287
+ return finish({ kind: "number", value: counted === 0 ? 0 : step * counted });
1288
+ }
1289
+ // W57-T07: WORKDAY steps before testing; zero days returns the start even on a weekend.
1290
+ let remaining = Math.abs(days);
1291
+ while (remaining > 0) {
1292
+ cursor.setUTCDate(cursor.getUTCDate() + step);
1293
+ if (cursor.getUTCFullYear() < 1 || cursor.getUTCFullYear() > 9999) {
1294
+ throw new Unsupported("WORKDAY date overflow");
1295
+ }
1296
+ if (working(cursor)) remaining -= 1;
1297
+ }
1298
+ return finish({ kind: "text", value: functionDateText(cursor) });
1299
+ }
1300
+
1301
+ if (name === "CHOOSE") {
1302
+ const index = Math.trunc(number(0));
1303
+ if (index < 1 || index >= args.length) {
1304
+ throw new FormulaError(ERROR_VALUE + " CHOOSE index is outside its list.");
1305
+ }
1306
+ return finish(scalar(index));
1307
+ }
1308
+ if (name === "INDEX") {
1309
+ const array = range(0);
1310
+ let row = Math.trunc(number(1));
1311
+ let col = args.length > 2 ? Math.trunc(number(2)) : 1;
1312
+ if (args.length === 2) {
1313
+ if (array.rows === 1) { col = row; row = 1; }
1314
+ else if (array.cols !== 1) throw new Unsupported("INDEX array result");
1315
+ }
1316
+ if (row < 1 || row > array.rows || col < 1 || col > array.cols) {
1317
+ // W57-T06: `#VALUE!` rather than Excel's `#REF!`, on purpose. `formula_runtime.py` answers
1318
+ // `bad_value` for a position outside the range and `types.ts` maps that to `#VALUE!`, and the
1319
+ // server recomputes every formula at Refresh. Matching Excel here would make the token change
1320
+ // under the reader a moment later. Excel parity is the SERVER's to fix, in one place, later.
1321
+ throw new FormulaError(ERROR_VALUE + " INDEX position is outside its range.");
1322
+ }
1323
+ return finish(read(array.addrs[(row - 1) * array.cols + col - 1]));
1324
+ }
1325
+
1326
+ const wanted = lookupKey(scalar(0));
1327
+ const array = range(1);
1328
+ let resultRange: LookupRange | undefined;
1329
+ let col = 1;
1330
+ // W57-T06: approximate modes require sorted-list and ordering parity beyond the worked
1331
+ // cases. Keep VLOOKUP's TRUE/default, MATCH's +/-1/default and nonzero XLOOKUP modes on
1332
+ // the server instead of silently treating an approximate request as an exact request.
1333
+ if (name === "VLOOKUP") {
1334
+ const flag = args[3];
1335
+ if (flag?.kind !== "boolean" || flag.literal !== "FALSE") throw new Unsupported("VLOOKUP approximate match");
1336
+ col = Math.trunc(number(2));
1337
+ if (col < 1) throw new FormulaError(ERROR_VALUE + " VLOOKUP column must be at least one.");
1338
+ // W57-T06: the same server bad_value bounds mapping as INDEX above.
1339
+ if (col > array.cols) throw new FormulaError(ERROR_VALUE + " VLOOKUP column is outside its table.");
1340
+ } else {
1341
+ if (array.rows !== 1 && array.cols !== 1) throw new Unsupported(name + " lookup vector");
1342
+ if (name === "MATCH") {
1343
+ if (args.length < 3 || number(2) !== 0) throw new Unsupported("MATCH approximate match");
1344
+ } else {
1345
+ resultRange = range(2);
1346
+ if (resultRange.rows !== 1 && resultRange.cols !== 1) throw new Unsupported("XLOOKUP array result");
1347
+ if (array.addrs.length !== resultRange.addrs.length) {
1348
+ throw new FormulaError(ERROR_VALUE + " XLOOKUP ranges must have the same size.");
1349
+ }
1350
+ if (args.length > 4 && number(4) !== 0) throw new Unsupported("XLOOKUP match mode");
1351
+ }
1352
+ }
1353
+ const count = name === "VLOOKUP" ? array.rows : array.addrs.length;
1354
+ for (let i = 0; i < count; i += 1) {
1355
+ const offset = name === "VLOOKUP" ? i * array.cols : i;
1356
+ if (lookupKey(read(array.addrs[offset])) !== wanted) continue;
1357
+ if (name === "MATCH") return finish({ kind: "number", value: i + 1 });
1358
+ const address = resultRange ? resultRange.addrs[i] : array.addrs[offset + col - 1];
1359
+ return finish(read(address));
1360
+ }
1361
+ if (name === "XLOOKUP" && args.length > 3) {
1362
+ const fallback = scalar(3);
1363
+ if (fallback.kind !== "empty") return finish(fallback);
1364
+ }
1365
+ return noMatch();
1366
+ };
1367
+
1368
+ const parseAtom = (c: Cursor, get: Getter): ExpressionValue => {
1369
  const tk = take(c);
1370
  if (tk.t === "num") return { n: tk.v, pending: false };
1371
+ if (tk.t === "ref") return get(tk.v);
1372
  // ⭐⭐ W54-T26: AN ERROR PROPAGATES THROUGH ARITHMETIC, EXACTLY AS EXCEL DOES. Reading one is
1373
  // the same as reading a cell that holds one, so it takes the same road out: a thrown
1374
  // `FormulaError` whose message already states the code, which `errorValue` passes through.
1375
  if (tk.t === "err") throw new FormulaError(tk.v);
1376
  // ⭐ W54-T26: a text literal coerces the way a text CELL does, so `=1+"1"` is 2 and `=1+"x"`
1377
  // is `#VALUE!`, which is Excel's own answer to both.
1378
+ if (tk.t === "str") return { kind: "text", value: tk.v };
1379
  if (tk.t === "fn") {
1380
  const name = tk.v;
1381
  // ⭐⭐ W54-T26: A BARE NAME IS NOT A CALL AND NOTHING CAN RESOLVE IT. `=FOO` names a thing,
1382
  // and NEITHER engine has named ranges, so no round trip to the server can turn it into a
1383
  // value. That makes it the one name this file may refuse on its own: `#NAME?`.
1384
  if (!isOp(peekTok(c), "(")) throw new FormulaError(NAME_NOT_FOUND);
1385
+ if (Object.prototype.hasOwnProperty.call(CALL_ARITY, name)) return parseLookup(name, c, get);
1386
  // ⭐ EVERY OTHER FUNCTION IN THE CATALOGUE IS THE SERVER'S. `IF`, `ROUND`, `TEXT` and the
1387
  // rest are real formulas this file does not speak, so they take the `unsupported` road home
1388
  // and keep working exactly as they did before this ticket (see the header).
 
1391
  if (!AGGREGATE_SET.has(name)) throw new Unsupported(name);
1392
  take(c);
1393
  const from = rangeEndpoint(take(c), name);
1394
+ // W57-T03 / P1 F2: one cell is a legal aggregate input in Excel and on the server.
1395
+ // COUNT(A6) and SUM(A6) can compute here without waiting for Refresh. Only one cell or
1396
+ // the existing range is admitted; argument lists and whole-band references stay unsupported.
1397
+ if (isOp(peekTok(c), ")")) {
1398
+ take(c);
1399
+ return evalAggregate(name, [from], get);
1400
+ }
1401
  if (!isOp(peekTok(c), ":")) throw new Unsupported(name);
1402
  take(c);
1403
  const to = rangeEndpoint(take(c), name);
 
1414
  throw new Unsupported("token");
1415
  };
1416
 
1417
+ const parseUnary = (c: Cursor, get: Getter): ExpressionValue => {
1418
  if (isOp(peekTok(c), "-")) {
1419
  take(c);
1420
+ const inner = expressionNumber(parseUnary(c, get));
1421
  return { n: -inner.n, pending: inner.pending };
1422
  }
1423
+ if (isOp(peekTok(c), "+")) { take(c); return expressionNumber(parseUnary(c, get)); }
1424
  return parseAtom(c, get);
1425
  };
1426
 
1427
+ const parseTerm = (c: Cursor, get: Getter): ExpressionValue => {
1428
+ let value = parseUnary(c, get);
1429
  while (isOp(peekTok(c), "*") || isOp(peekTok(c), "/")) {
1430
  const op = take(c);
1431
+ const left = expressionNumber(value);
1432
+ const right = expressionNumber(parseUnary(c, get));
1433
  if (op.t === "op" && op.v === "/") {
1434
  // ⛔ A DIVISOR THAT IS ONLY ZERO BECAUSE IT HAS NOT LOADED IS NOT A DIVISION BY ZERO. It is
1435
  // a value nobody has yet, so the whole formula waits rather than accusing the reader of
1436
  // dividing by something they never wrote.
1437
  if (right.n === 0 && right.pending) throw new PendingInput("divisor");
1438
  if (right.n === 0) throw new FormulaError("This formula divides by zero.");
1439
+ value = { n: left.n / right.n, pending: left.pending || right.pending };
1440
  } else {
1441
+ value = { n: left.n * right.n, pending: left.pending || right.pending };
1442
  }
1443
  }
1444
+ return value;
1445
  };
1446
 
1447
+ const parseExpr = (c: Cursor, get: Getter): ExpressionValue => {
1448
+ let value = parseTerm(c, get);
1449
  while (isOp(peekTok(c), "+") || isOp(peekTok(c), "-")) {
1450
  const op = take(c);
1451
+ const left = expressionNumber(value);
1452
+ const right = expressionNumber(parseTerm(c, get));
1453
  const plus = op.t === "op" && op.v === "+";
1454
+ value = { n: plus ? left.n + right.n : left.n - right.n,
1455
  pending: left.pending || right.pending };
1456
  }
1457
+ return value;
1458
  };
1459
 
1460
  /**
 
1473
  * accepted so a caller can hand this either the raw stored formula or its own trimmed draft.
1474
  *
1475
  * ⭐ A BARE SINGLE REFERENCE PASSES THROUGH UNCOERCED. `=F6` of a text cell is F6's text, not a
1476
+ * refusal. W57-T06 also passes scalar lookup text through; only numeric arguments and
1477
+ * arithmetic operators request coercion.
1478
  *
1479
  * ⛔ NEVER THROWS. Every outcome — a token this engine does not speak, a function that belongs to
1480
  * the server, a division by zero, a reference to a cell held in a genuine error state — comes
 
1495
  return one.t === "ref" ? get(one.v) : { kind: "empty" };
1496
  }
1497
  const cursor: Cursor = { tokens, i: 0 };
1498
+ const expression = parseExpr(cursor, get);
1499
  if (!atEnd(cursor)) throw new Unsupported("trailing tokens");
1500
+ // W57-T06: a lookup's text or empty result reaches the cell without numeric coercion.
1501
+ // Arithmetic has already called expressionNumber, which reuses the existing toNum rules.
1502
+ if ("kind" in expression && (expression.kind === "text" || expression.kind === "empty"
1503
+ || expression.kind === "pending")) return expression;
1504
+ const result = expressionNumber(expression);
1505
  if (!Number.isFinite(result.n)) {
1506
  return { kind: "error", message: "This formula could not be calculated." };
1507
  }
web/src/sheet/functionCatalog.ts CHANGED
@@ -168,6 +168,18 @@ const FUNCTION_DEFS: FunctionDef[] = [
168
  args: [{ name: "value" }, { name: "value_if_error" }],
169
  summary: "Returns a fallback value when the first argument is an error.",
170
  },
 
 
 
 
 
 
 
 
 
 
 
 
171
  {
172
  name: "VLOOKUP",
173
  category: "Lookup",
@@ -189,6 +201,13 @@ const FUNCTION_DEFS: FunctionDef[] = [
189
  ],
190
  summary: "Returns a value at a given position in a range.",
191
  },
 
 
 
 
 
 
 
192
  {
193
  name: "CONCATENATE",
194
  category: "Text",
@@ -196,6 +215,30 @@ const FUNCTION_DEFS: FunctionDef[] = [
196
  repeats: true,
197
  summary: "Joins several text values into one text value.",
198
  },
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
199
  {
200
  name: "ROUND",
201
  category: "Math",
@@ -232,6 +275,25 @@ const FUNCTION_DEFS: FunctionDef[] = [
232
  args: [{ name: "text" }, { name: "num_chars", optional: true }],
233
  summary: "Returns the rightmost characters from a text value.",
234
  },
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
235
  {
236
  name: "TODAY",
237
  category: "Date",
 
168
  args: [{ name: "value" }, { name: "value_if_error" }],
169
  summary: "Returns a fallback value when the first argument is an error.",
170
  },
171
+ {
172
+ name: "XLOOKUP",
173
+ category: "Lookup",
174
+ args: [
175
+ { name: "lookup_value" },
176
+ { name: "lookup_array" },
177
+ { name: "return_array" },
178
+ { name: "if_not_found", optional: true },
179
+ { name: "match_mode", optional: true },
180
+ ],
181
+ summary: "Finds a value in one range and returns the matching value from another, with an answer of your own when nothing matches.",
182
+ },
183
  {
184
  name: "VLOOKUP",
185
  category: "Lookup",
 
201
  ],
202
  summary: "Returns a value at a given position in a range.",
203
  },
204
+ {
205
+ name: "CHOOSE",
206
+ category: "Lookup",
207
+ args: [{ name: "index_num" }, { name: "value1" }, { name: "value2", optional: true }],
208
+ repeats: true,
209
+ summary: "Returns the value at the position you name in a list.",
210
+ },
211
  {
212
  name: "CONCATENATE",
213
  category: "Text",
 
215
  repeats: true,
216
  summary: "Joins several text values into one text value.",
217
  },
218
+ // W57-T07: offer only server-backed text functions, with hints built by buildSignature.
219
+ {
220
+ name: "TEXTJOIN",
221
+ category: "Text",
222
+ args: [
223
+ { name: "delimiter" },
224
+ { name: "ignore_empty" },
225
+ { name: "text1" },
226
+ { name: "text2", optional: true },
227
+ ],
228
+ repeats: true,
229
+ summary: "Joins text values with a delimiter between them, optionally skipping the empty ones.",
230
+ },
231
+ {
232
+ name: "SUBSTITUTE",
233
+ category: "Text",
234
+ args: [
235
+ { name: "text" },
236
+ { name: "old_text" },
237
+ { name: "new_text" },
238
+ { name: "instance_num", optional: true },
239
+ ],
240
+ summary: "Replaces old text with new text in a text value.",
241
+ },
242
  {
243
  name: "ROUND",
244
  category: "Math",
 
275
  args: [{ name: "text" }, { name: "num_chars", optional: true }],
276
  summary: "Returns the rightmost characters from a text value.",
277
  },
278
+ // W57-T07: these date functions return ISO dates or counts on both sides of Refresh.
279
+ {
280
+ name: "EOMONTH",
281
+ category: "Date",
282
+ args: [{ name: "date" }, { name: "months" }],
283
+ summary: "Returns the last day of the month a number of months away from a date.",
284
+ },
285
+ {
286
+ name: "WORKDAY",
287
+ category: "Date",
288
+ args: [{ name: "start_date" }, { name: "days" }, { name: "holidays", optional: true }],
289
+ summary: "Returns the date a number of working days away from a date, skipping weekends and any holidays you name.",
290
+ },
291
+ {
292
+ name: "NETWORKDAYS",
293
+ category: "Date",
294
+ args: [{ name: "start_date" }, { name: "end_date" }, { name: "holidays", optional: true }],
295
+ summary: "Counts the working days between two dates, skipping weekends and any holidays you name.",
296
+ },
297
  {
298
  name: "TODAY",
299
  category: "Date",
web/src/sheet/ribbonData.tsx CHANGED
@@ -2,13 +2,280 @@
2
  // stay within Sheet's existing executable actions; unavailable audit commands remain visible and
3
  // honest rather than becoming no-op affordances.
4
 
5
- import type { RibbonTabContext } from "./Ribbon";
 
 
 
 
 
 
 
6
 
7
- const DATA = ["data-refresh"] as const;
8
  const OUTLINE = ["data-hide-rows", "data-hide-columns", "data-unhide"] as const;
9
 
10
  export const DATA_KEYS = [...DATA, ...OUTLINE] as const;
11
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
12
  function IconRefresh() {
13
  return (
14
  <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon">
@@ -27,8 +294,319 @@ function IconBand({ column = false }: { column?: boolean }) {
27
  );
28
  }
29
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
30
  export const dataGroups = (ctx: RibbonTabContext) => {
31
- const { act, control, group, unavailable, word } = ctx;
 
32
  return (
33
  <>
34
  {group("Data", (
@@ -37,22 +615,30 @@ export const dataGroups = (ctx: RibbonTabContext) => {
37
  "data-refresh", "Refresh all", <><IconRefresh />{word("Refresh all")}</>,
38
  () => act("refresh"), false, undefined, "R",
39
  )}
40
- {unavailable("Queries and connections", word("Queries and connections"))}
41
  </>
42
  ))}
43
  {group("Sort", (
44
  <>
45
- {unavailable("Sort ascending", word("Sort ascending"))}
46
- {unavailable("Sort descending", word("Sort descending"))}
 
 
 
 
 
 
 
 
47
  </>
48
  ))}
49
  {group("Auto filter", unavailable("Filter", word("Filter")))}
50
- {group("Data validation", unavailable("Data validation", word("Data validation")))}
51
  {group("Data tools", (
52
  <>
53
- {unavailable("Split text to columns", word("Text to columns"))}
54
- {unavailable("Flash fill", word("Flash fill"))}
55
- {unavailable("Remove duplicates", word("Remove duplicates"))}
56
  </>
57
  ))}
58
  {group("Outline", (
 
2
  // stay within Sheet's existing executable actions; unavailable audit commands remain visible and
3
  // honest rather than becoming no-op affordances.
4
 
5
+ import { useState } from "react";
6
+ import { AnchoredOverlay } from "../customer-grid/OverlaySurface";
7
+ import type { RibbonInsertDoor, RibbonTabContext } from "./Ribbon";
8
+ import { usedRange } from "./sheetExport";
9
+ import { addressOf, setLiteral } from "./sheetState";
10
+ import { asNumber, MAX_SHEET_COLS } from "./types";
11
+ import type { Cell, CellBinding } from "./types";
12
+ import { listText, parseList, validationOf } from "./validation";
13
 
14
+ const DATA = ["data-refresh", "data-queries-connections", "data-sort-asc", "data-sort-desc", "data-validation", "data-text-to-columns", "data-flash-fill", "data-remove-duplicates"] as const;
15
  const OUTLINE = ["data-hide-rows", "data-hide-columns", "data-unhide"] as const;
16
 
17
  export const DATA_KEYS = [...DATA, ...OUTLINE] as const;
18
 
19
+ type DataRows = (Cell | null)[][];
20
+ type DataKey = number | string | null;
21
+
22
+ const hasDataRange = (selection: RibbonInsertDoor["selection"] | undefined): boolean =>
23
+ !!selection && (selection.col0 !== selection.col1 || selection.row0 !== selection.row1);
24
+
25
+ /**
26
+ * Snapshot before writing, so moving a row cannot overwrite a later row's source. The door is
27
+ * already in sheet coordinates, including hidden rows and columns; no view-index conversion here.
28
+ * Excel would offer to widen the selection. Sort exactly the selected rectangle: silently widening
29
+ * it is the dangerous half of that dialog, because it moves cells the person did not select.
30
+ */
31
+ function transformSelectionRows(
32
+ door: RibbonInsertDoor | undefined,
33
+ transform: (rows: DataRows) => DataRows,
34
+ ): { before: number; after: number } | null {
35
+ const selection = door?.selection;
36
+ if (!door || !selection || !hasDataRange(selection)) return null;
37
+ const col0 = Math.min(selection.col0, selection.col1);
38
+ const row0 = Math.min(selection.row0, selection.row1);
39
+ const width = Math.abs(selection.col1 - selection.col0) + 1;
40
+ const height = Math.abs(selection.row1 - selection.row0) + 1;
41
+ const rows: DataRows = Array.from({ length: height }, (_, row) =>
42
+ Array.from({ length: width }, (_, col) => door.cellAt(col0 + col, row0 + row)));
43
+ const next = transform(rows);
44
+ const edits: Record<string, Cell | null> = {};
45
+ for (let row = 0; row < height; row += 1) {
46
+ for (let col = 0; col < width; col += 1) {
47
+ // Include every address, especially the shortened tail: omitted edits leave stale cells.
48
+ edits[addressOf(col0 + col, row0 + row)] = next[row]?.[col] ?? null;
49
+ }
50
+ }
51
+ // The same batch door as paste makes the whole action one history step and one save.
52
+ door.onCells(edits);
53
+ return { before: height, after: next.length };
54
+ }
55
+
56
+ /** Sort and dedupe agree on values, never formula source, formatting, or binding definitions. */
57
+ function dataKey(cell: Cell | null): DataKey {
58
+ if (!cell || cell.kind === "empty") return null;
59
+ // Bound cells use their last computed result, even when stale, then their displayed text.
60
+ // A missing value is not zero; an empty computed string also wins over old source text.
61
+ const value = cell.value ?? (cell.kind === "bound"
62
+ ? cell.display ?? cell.text
63
+ : cell.text ?? cell.display) ?? "";
64
+ if (value === "") return null;
65
+ // Typed numbers are stored as strings in Sheet, so use the same numeric reader as its cells.
66
+ const number = asNumber(value);
67
+ return number === null ? String(value).toLowerCase() : number;
68
+ }
69
+
70
+ /** dataKey normalizes comparisons; text operations need the same value precedence verbatim. */
71
+ function dataText(cell: Cell | null): string {
72
+ if (!cell || cell.kind === "empty") return "";
73
+ const value = cell.value ?? (cell.kind === "bound"
74
+ ? cell.display ?? cell.text
75
+ : cell.text ?? cell.display) ?? "";
76
+ return String(value);
77
+ }
78
+
79
+ function compareDataKeys(left: DataKey, right: DataKey, direction: 1 | -1): number {
80
+ // Blanks stay last in BOTH directions; only the nonblank ordering may be reversed.
81
+ if (left === null) return right === null ? 0 : 1;
82
+ if (right === null) return -1;
83
+ const order = typeof left === "number"
84
+ ? typeof right === "number" ? left - right : -1
85
+ : typeof right === "number" ? 1 : left.localeCompare(right);
86
+ return direction * order;
87
+ }
88
+
89
+ function sortRows(rows: DataRows, direction: 1 | -1): DataRows {
90
+ return rows.map((cells, index) => ({ cells, index, key: dataKey(cells[0] ?? null) }))
91
+ // Original indices break ties outside the direction multiplier, preserving equal-key order.
92
+ .sort((left, right) => compareDataKeys(left.key, right.key, direction) || left.index - right.index)
93
+ .map(({ cells }) => cells);
94
+ }
95
+
96
+ function uniqueRows(rows: DataRows): DataRows {
97
+ const seen = new Set<string>();
98
+ return rows.filter((cells) => {
99
+ // JSON escapes every embedded NUL, so this separator cannot occur in an encoded cell key.
100
+ // It also keeps numeric and text keys distinct without mistaking column boundaries for data.
101
+ const key = cells.map((cell) => JSON.stringify(dataKey(cell))).join("\u0000");
102
+ if (seen.has(key)) return false;
103
+ seen.add(key);
104
+ // Filtering in source order retains the first entire cell row, including its styles/bindings.
105
+ return true;
106
+ });
107
+ }
108
+
109
+ function splitTextToColumns(door: RibbonInsertDoor | undefined, delimiter: string): string {
110
+ const selection = door?.selection;
111
+ if (!door || !selection || !hasDataRange(selection)) return "Nothing was split; select a range of cells.";
112
+ const col0 = Math.min(selection.col0, selection.col1);
113
+ const row0 = Math.min(selection.row0, selection.row1);
114
+ const row1 = Math.max(selection.row0, selection.row1);
115
+ const splitRows = Array.from({ length: row1 - row0 + 1 }, (_, row) => {
116
+ const cell = door.cellAt(col0, row0 + row);
117
+ if (!cell || dataKey(cell) === null) return null;
118
+ const pieces = dataText(cell).split(delimiter);
119
+ return pieces.length > 1 ? pieces : null;
120
+ });
121
+ const count = splitRows.filter((pieces) => pieces !== null).length;
122
+ if (count === 0) return "0 rows were split because no values contained the chosen delimiter.";
123
+ const width = splitRows.reduce((widest, pieces) => Math.max(widest, pieces?.length ?? 1), 1);
124
+ if (col0 + width > MAX_SHEET_COLS) return "Nothing was split because the result would exceed the sheet's column limit.";
125
+
126
+ // Check the entire output rectangle before any write, including cells outside the selection.
127
+ for (let row = row0; row <= row1; row += 1) {
128
+ for (let col = col0 + 1; col < col0 + width; col += 1) {
129
+ const cell = door.cellAt(col, row);
130
+ // A blank formula or binding still owns content, even when its current result is empty.
131
+ if (cell && (dataKey(cell) !== null || cell.kind === "formula" || cell.kind === "bound" || cell.sparkline)) {
132
+ return `Nothing was split because ${addressOf(col, row)} already contains data.`;
133
+ }
134
+ }
135
+ }
136
+
137
+ // Reuse the existing snapshot and batch writer with the checked output range in sheet coordinates.
138
+ transformSelectionRows({ ...door, selection: { col0, row0, col1: col0 + width - 1, row1 } }, (rows) =>
139
+ rows.map((cells, row) => {
140
+ const pieces = splitRows[row];
141
+ if (!pieces) return cells;
142
+ return cells.map((cell, col) => {
143
+ const piece = pieces[col];
144
+ return piece === undefined ? cell : setLiteral(cell, piece);
145
+ });
146
+ }));
147
+ return `${count} ${count === 1 ? "row was" : "rows were"} split into columns.`;
148
+ }
149
+
150
+ type FlashFillExample = { sources: readonly string[]; target: string };
151
+ type FlashFillTransform = (sources: readonly string[]) => string | null;
152
+
153
+ /** Include overlapping occurrences and empty text, but stop at the end even for an empty match. */
154
+ function* textPositions(text: string, value: string, from = 0): Generator<number> {
155
+ let position = text.indexOf(value, from);
156
+ while (position !== -1 && position <= text.length) {
157
+ yield position;
158
+ if (position === text.length) return;
159
+ position = text.indexOf(value, position + 1);
160
+ }
161
+ }
162
+
163
+ function fitFlashFillAffixes(
164
+ examples: readonly FlashFillExample[],
165
+ read: FlashFillTransform,
166
+ ): FlashFillTransform | null {
167
+ const first = examples[0];
168
+ if (!first) return null;
169
+ const value = read(first.sources);
170
+ if (value === null) return null;
171
+ // A repeated source can occur in an affix too; try every placement before refusing this rule.
172
+ for (const position of textPositions(first.target, value)) {
173
+ const prefix = first.target.slice(0, position);
174
+ const suffix = first.target.slice(position + value.length);
175
+ const transform: FlashFillTransform = (sources) => {
176
+ const part = read(sources);
177
+ return part === null ? null : prefix + part + suffix;
178
+ };
179
+ if (examples.every((example) => transform(example.sources) === example.target)) return transform;
180
+ }
181
+ return null;
182
+ }
183
+
184
+ function inferFlashFill(examples: readonly FlashFillExample[]): FlashFillTransform | null {
185
+ const first = examples[0];
186
+ if (!first) return null;
187
+ const width = first.sources.length;
188
+
189
+ // Family order is intentional: take the first rule that explains EVERY example exactly.
190
+ for (let col = 0; col < width; col += 1) {
191
+ const transform = fitFlashFillAffixes(examples, (sources) => sources[col] ?? null);
192
+ if (transform) return transform;
193
+ }
194
+ const delimiters = [" ", ",", ";", "\t", "-", "@", "/", "."] as const;
195
+ for (let col = 0; col < width; col += 1) {
196
+ for (const delimiter of delimiters) {
197
+ const pieces = first.sources[col]?.split(delimiter) ?? [];
198
+ for (let piece = 0; piece < pieces.length; piece += 1) {
199
+ const transform = fitFlashFillAffixes(examples, (sources) =>
200
+ sources[col]?.split(delimiter)[piece] ?? null);
201
+ if (transform) return transform;
202
+ }
203
+ }
204
+ }
205
+ // Ordered pairs also permit a person to type the right source before the left source.
206
+ for (let left = 0; left < width; left += 1) {
207
+ const leftValue = first.sources[left];
208
+ if (leftValue === undefined) continue;
209
+ for (let right = 0; right < width; right += 1) {
210
+ const rightValue = first.sources[right];
211
+ if (left === right || rightValue === undefined) continue;
212
+ for (const start of textPositions(first.target, leftValue)) {
213
+ const end = start + leftValue.length;
214
+ for (const next of textPositions(first.target, rightValue, end)) {
215
+ const prefix = first.target.slice(0, start);
216
+ const separator = first.target.slice(end, next);
217
+ const suffix = first.target.slice(next + rightValue.length);
218
+ const transform: FlashFillTransform = (sources) => {
219
+ const leftPart = sources[left];
220
+ const rightPart = sources[right];
221
+ return leftPart === undefined || rightPart === undefined
222
+ ? null : prefix + leftPart + separator + rightPart + suffix;
223
+ };
224
+ if (examples.every((example) => transform(example.sources) === example.target)) return transform;
225
+ }
226
+ }
227
+ }
228
+ }
229
+ return null;
230
+ }
231
+
232
+ function flashFillSelection(door: RibbonInsertDoor | undefined): string {
233
+ const selection = door?.selection;
234
+ if (!door || !selection || !hasDataRange(selection)) return "Nothing was filled; select a range of cells.";
235
+ const col0 = Math.min(selection.col0, selection.col1);
236
+ const row0 = Math.min(selection.row0, selection.row1);
237
+ const row1 = Math.max(selection.row0, selection.row1);
238
+ if (col0 === 0) return "Nothing was filled because there is no source column to the left; select a target column to the right of your source data.";
239
+
240
+ // Source columns can be outside the selection; snapshot them before inferring or writing.
241
+ const rows = Array.from({ length: row1 - row0 + 1 }, (_, index) => {
242
+ const cell = door.cellAt(col0, row0 + index);
243
+ return {
244
+ cell,
245
+ target: dataText(cell),
246
+ sources: Array.from({ length: col0 }, (_, col) => dataText(door.cellAt(col, row0 + index))),
247
+ };
248
+ });
249
+ const examples = rows.filter((row) => row.target !== "");
250
+ if (examples.length === 0) return "Nothing was filled because there is no example; type an example in the target column within your selection.";
251
+ const pending = rows.filter((row) => row.target === "");
252
+ if (pending.length === 0) return "Nothing was filled because there are no empty target cells left; include empty rows in your selection.";
253
+ // As with Text to columns, a blank computed result does not make a formula or binding disposable.
254
+ if (pending.some(({ cell }) => cell && (cell.kind === "formula" || cell.kind === "bound" || cell.sparkline))) {
255
+ return "Nothing was filled because an empty-looking target contains a formula, binding or sparkline; select empty target cells or clear their contents first.";
256
+ }
257
+ const transform = inferFlashFill(examples);
258
+ if (!transform) return "The examples do not agree on one rule, so nothing was changed; correct the examples or select a smaller range with a consistent pattern.";
259
+
260
+ // Precompute ALL outputs: a missing piece in even one fill row must never cause a partial write.
261
+ const fills = new Map<number, string>();
262
+ for (const [index, row] of rows.entries()) {
263
+ if (row.target !== "") continue;
264
+ const value = transform(row.sources);
265
+ if (value === null || value === "") {
266
+ return "Nothing was filled because some rows lack the source text needed by the examples; complete those source cells or select a smaller range.";
267
+ }
268
+ fills.set(index, value);
269
+ }
270
+ // Only the target column is written; the shared batch helper preserves one history/save step.
271
+ transformSelectionRows({ ...door, selection: { col0, row0, col1: col0, row1 } }, (cells) =>
272
+ cells.map((row, index) => {
273
+ const value = fills.get(index);
274
+ return value === undefined ? row : [setLiteral(row[0], value)];
275
+ }));
276
+ return `${fills.size} ${fills.size === 1 ? "row was" : "rows were"} filled.`;
277
+ }
278
+
279
  function IconRefresh() {
280
  return (
281
  <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon">
 
294
  );
295
  }
296
 
297
+ function IconSort({ descending = false }: { descending?: boolean }) {
298
+ return (
299
+ <svg viewBox="0 0 16 16" stroke="currentColor" fill="none" aria-hidden="true" className="sheet-ribbon-icon">
300
+ <path d={descending ? "M3.5 2.5v11m-2-2 2 2 2-2" : "M3.5 13.5v-11m-2 2 2-2 2 2"} />
301
+ <path d="M8 3.5h2M8 8h4M8 12.5h6" />
302
+ </svg>
303
+ );
304
+ }
305
+
306
+ function IconRemoveDuplicates() {
307
+ return (
308
+ <svg viewBox="0 0 16 16" stroke="currentColor" fill="none" aria-hidden="true" className="sheet-ribbon-icon">
309
+ <rect x="2" y="2" width="8" height="8" rx="1" />
310
+ <path d="M6 10v3a1 1 0 0 0 1 1h6a1 1 0 0 0 1-1V7a1 1 0 0 0-1-1h-3M8.5 10h3" />
311
+ </svg>
312
+ );
313
+ }
314
+
315
+ function IconTextToColumns() {
316
+ return (
317
+ <svg viewBox="0 0 16 16" stroke="currentColor" fill="none" aria-hidden="true" className="sheet-ribbon-icon">
318
+ <path d="M2 3h12M2 6h4M2 9h4M8 5v9M10 6h4M10 9h4M2 12h4M10 12h4" />
319
+ </svg>
320
+ );
321
+ }
322
+
323
+ function IconFlashFill() {
324
+ return (
325
+ <svg viewBox="0 0 16 16" stroke="currentColor" fill="none" aria-hidden="true" className="sheet-ribbon-icon">
326
+ <path d="M2 3h4M2 8h3M2 13h4M11 1 7 8h3l-1 7 5-9h-4l1-5Z" />
327
+ </svg>
328
+ );
329
+ }
330
+
331
+ function IconDataValidation() {
332
+ return (
333
+ <svg viewBox="0 0 16 16" stroke="currentColor" fill="none" aria-hidden="true" className="sheet-ribbon-icon">
334
+ <rect x="1.5" y="2.5" width="13" height="11" rx="1" />
335
+ <path d="m3.5 8 2 2 3.5-4M11 6h1M11 9h1" />
336
+ </svg>
337
+ );
338
+ }
339
+
340
+ function IconQueriesConnections() {
341
+ return (
342
+ <svg viewBox="0 0 16 16" stroke="currentColor" fill="none" aria-hidden="true" className="sheet-ribbon-icon">
343
+ <ellipse cx="6" cy="3.5" rx="4" ry="2" />
344
+ <path d="M2 3.5v7c0 1.1 1.8 2 4 2M10 3.5v3M2 7c0 1.1 1.8 2 4 2M8 11h6m-2-2 2 2-2 2" />
345
+ </svg>
346
+ );
347
+ }
348
+
349
+ function DataValidationControl({ ctx }: { ctx: RibbonTabContext }) {
350
+ const { insert, control, word, open, anchorEl, openPop, closePop } = ctx;
351
+ const [text, setText] = useState("");
352
+ const [result, setResult] = useState<string | null>(null);
353
+ const submit = () => {
354
+ const selection = insert?.selection;
355
+ if (!insert || !selection) { setResult("Select a cell to change its validation list."); return; }
356
+ const parsed = parseList(text);
357
+ if (parsed.refusal) { setResult(parsed.refusal); return; }
358
+ const col0 = Math.min(selection.col0, selection.col1);
359
+ const col1 = Math.max(selection.col0, selection.col1);
360
+ const row0 = Math.min(selection.row0, selection.row1);
361
+ const row1 = Math.max(selection.row0, selection.row1);
362
+ const edits: Record<string, Cell | null> = {};
363
+ let boundSkipped = 0;
364
+ for (let row = row0; row <= row1; row += 1) {
365
+ for (let col = col0; col <= col1; col += 1) {
366
+ const cell = insert.cellAt(col, row);
367
+ const addr = addressOf(col, row);
368
+ // Mirror validation.ts::validationEdits, including its bound-cell skip and empty-cell
369
+ // rules; change this with it. The ribbon door has no SheetTab to pass to that helper.
370
+ if (cell?.kind === "bound") { boundSkipped += 1; continue; }
371
+ if (!cell) {
372
+ if (parsed.list.length > 0) {
373
+ edits[addr] = { kind: "empty", state: "fresh", validation: { list: [...parsed.list] } };
374
+ }
375
+ continue;
376
+ }
377
+ if (parsed.list.length === 0) {
378
+ if (cell.kind === "empty" && !cell.style) { edits[addr] = null; continue; }
379
+ const cleared: Cell = { ...cell };
380
+ delete cleared.validation;
381
+ edits[addr] = cleared;
382
+ continue;
383
+ }
384
+ edits[addr] = { ...cell, validation: { list: [...parsed.list] } };
385
+ }
386
+ }
387
+ const count = Object.keys(edits).length;
388
+ if (count > 0) insert.onCells(edits);
389
+ const skipped = boundSkipped > 0
390
+ ? `; ${boundSkipped} bound ${boundSkipped === 1 ? "cell was" : "cells were"} skipped because their values are computed from a database`
391
+ : "";
392
+ setResult(`${parsed.list.length > 0 ? "Validation list applied to" : "Validation cleared from"} ${count} ${count === 1 ? "cell" : "cells"}${skipped}.`);
393
+ };
394
+ return (
395
+ <span className="sheet-ribbon-slot">
396
+ {control(
397
+ "data-validation", "Data validation", <><IconDataValidation />{word("Data validation")}</>,
398
+ (event) => {
399
+ if (open === "data-validation") { closePop(); return; }
400
+ const selection = insert?.selection;
401
+ if (!insert || !selection) return;
402
+ const anchor = insert.cellAt(Math.min(selection.col0, selection.col1), Math.min(selection.row0, selection.row1));
403
+ setText(listText(validationOf(anchor)?.list));
404
+ setResult(null);
405
+ openPop("data-validation")(event);
406
+ },
407
+ false, open === "data-validation", "V", "gallery", !insert?.selection,
408
+ )}
409
+ {open === "data-validation" && (
410
+ <AnchoredOverlay
411
+ anchor={anchorEl}
412
+ className="sheet-ribbon-pop sheet-ribbon-pop-portal sheet-ribbon-insert-form"
413
+ onDismiss={closePop}
414
+ role="dialog"
415
+ ariaLabel="Data validation"
416
+ >
417
+ <form className="sheet-ribbon-insert-fields" onSubmit={(event) => { event.preventDefault(); submit(); }}>
418
+ <label className="sheet-ribbon-insert-caption" htmlFor="sheet-data-validation-list">
419
+ Allowed values, one per line
420
+ </label>
421
+ <textarea
422
+ id="sheet-data-validation-list"
423
+ name="validation"
424
+ className="sheet-ribbon-insert-area"
425
+ rows={6}
426
+ value={text}
427
+ onChange={(event) => { setText(event.target.value); setResult(null); }}
428
+ />
429
+ <p className="sheet-ribbon-insert-hint">Leave empty to clear validation.</p>
430
+ <button type="submit" className="sheet-ribbon-item" disabled={!insert?.selection}>Apply</button>
431
+ {result !== null && <p className="sheet-ribbon-insert-hint" role="status">{result}</p>}
432
+ </form>
433
+ </AnchoredOverlay>
434
+ )}
435
+ </span>
436
+ );
437
+ }
438
+
439
+ function connectionDescription(binding: CellBinding): string {
440
+ // CellBinding is a Record<string, unknown>. Narrow the fields BindingEditor actually writes.
441
+ const parts = [typeof binding.database === "string" ? binding.database.trim() : ""];
442
+ const aggregate = binding.aggregate;
443
+ if (aggregate && typeof aggregate === "object" && !Array.isArray(aggregate)) {
444
+ const fn = "fn" in aggregate && typeof aggregate.fn === "string" ? aggregate.fn.trim() : "";
445
+ const field = "field" in aggregate && typeof aggregate.field === "string" ? aggregate.field.trim() : "";
446
+ parts.push([fn, field].filter(Boolean).join(" "));
447
+ }
448
+ const scope = binding.scope;
449
+ if (scope && typeof scope === "object" && !Array.isArray(scope)) {
450
+ const name = "view_name" in scope && typeof scope.view_name === "string" ? scope.view_name.trim() : "";
451
+ const id = "view_id" in scope && typeof scope.view_id === "string" ? scope.view_id.trim() : "";
452
+ parts.push(name || id);
453
+ }
454
+ return parts.filter(Boolean).join(", ");
455
+ }
456
+
457
+ function QueriesConnectionsControl({ ctx }: { ctx: RibbonTabContext }) {
458
+ const { insert, control, word, act, open, anchorEl, openPop, closePop } = ctx;
459
+ const [connections, setConnections] = useState<{ address: string; description: string }[]>([]);
460
+ return (
461
+ <span className="sheet-ribbon-slot">
462
+ {control(
463
+ "data-queries-connections", "Queries and connections", <><IconQueriesConnections />{word("Queries and connections")}</>,
464
+ (event) => {
465
+ if (open === "data-queries-connections") { closePop(); return; }
466
+ const found: { address: string; description: string }[] = [];
467
+ // Inspect on open, not on every Ribbon render. The existing usedRange owns the scan.
468
+ const range = insert ? usedRange(insert.cellAt) : null;
469
+ if (insert && range) {
470
+ for (let row = range.row0; row <= range.row1; row += 1) {
471
+ for (let col = range.col0; col <= range.col1; col += 1) {
472
+ const cell = insert.cellAt(col, row);
473
+ if (cell?.kind !== "bound" || !cell.binding) continue;
474
+ found.push({ address: addressOf(col, row), description: connectionDescription(cell.binding) });
475
+ }
476
+ }
477
+ }
478
+ setConnections(found);
479
+ openPop("data-queries-connections")(event);
480
+ },
481
+ false, open === "data-queries-connections", "Q", "gallery", false,
482
+ )}
483
+ {open === "data-queries-connections" && (
484
+ <AnchoredOverlay
485
+ anchor={anchorEl}
486
+ className="sheet-ribbon-pop sheet-ribbon-pop-portal"
487
+ onDismiss={closePop}
488
+ role="dialog"
489
+ ariaLabel="Queries and connections"
490
+ >
491
+ {connections.length === 0 ? (
492
+ <p className="sheet-ribbon-insert-hint">This workbook has no connected cells.</p>
493
+ ) : (
494
+ <ul aria-label="Connected cells">
495
+ {connections.map(({ address, description }) => (
496
+ <li key={address} className="sheet-ribbon-insert-hint">
497
+ {address}{description ? `: ${description}` : ""}
498
+ </li>
499
+ ))}
500
+ </ul>
501
+ )}
502
+ <button type="button" className="sheet-ribbon-item" onClick={() => act("refresh")}>Refresh all</button>
503
+ </AnchoredOverlay>
504
+ )}
505
+ </span>
506
+ );
507
+ }
508
+
509
+ function TextToColumnsControl({ ctx }: { ctx: RibbonTabContext }) {
510
+ const { insert, control, word, item, open, anchorEl, openPop, closePop } = ctx;
511
+ const [result, setResult] = useState<string | null>(null);
512
+ const split = (delimiter: string) => setResult(splitTextToColumns(insert, delimiter));
513
+ return (
514
+ <span className="sheet-ribbon-slot">
515
+ {control(
516
+ "data-text-to-columns", "Split text to columns", <><IconTextToColumns />{word("Text to columns")}</>,
517
+ (event) => { setResult(null); openPop("data-text-to-columns")(event); },
518
+ false, open === "data-text-to-columns", "T", "gallery", !hasDataRange(insert?.selection),
519
+ )}
520
+ {open === "data-text-to-columns" && (
521
+ <AnchoredOverlay
522
+ anchor={anchorEl}
523
+ className="sheet-ribbon-pop sheet-ribbon-pop-portal"
524
+ onDismiss={closePop}
525
+ role="menu"
526
+ ariaLabel="Split text to columns delimiter"
527
+ >
528
+ {item("Comma", () => split(","), false, "menuitem", "C")}
529
+ {item("Semicolon", () => split(";"), false, "menuitem", "M")}
530
+ {item("Tab", () => split("\t"), false, "menuitem", "T")}
531
+ {item("Space", () => split(" "), false, "menuitem", "S")}
532
+ {result !== null && <p className="sheet-ribbon-insert-hint" role="status">{result}</p>}
533
+ </AnchoredOverlay>
534
+ )}
535
+ </span>
536
+ );
537
+ }
538
+
539
+ /**
540
+ * groups(ctx) is called inside Ribbon's render, so hooks there would change order on a tab switch.
541
+ * A real child component owns this result because the tab context has no notice callback.
542
+ */
543
+ function RemoveDuplicatesControl({ ctx }: { ctx: RibbonTabContext }) {
544
+ const { insert, control, word, open, anchorEl, openPop, closePop } = ctx;
545
+ const [result, setResult] = useState<string | null>(null);
546
+ return (
547
+ <span className="sheet-ribbon-slot">
548
+ {control(
549
+ "data-remove-duplicates", "Remove duplicates", <><IconRemoveDuplicates />{word("Remove duplicates")}</>,
550
+ (event) => {
551
+ // Pressing an open result closes it without deduping the already-cleared tail again.
552
+ if (open === "data-remove-duplicates") { closePop(); return; }
553
+ const count = transformSelectionRows(insert, uniqueRows);
554
+ if (!count) return;
555
+ setResult(`${count.before - count.after} duplicate values found and removed; ${count.after} unique values remain.`);
556
+ openPop("data-remove-duplicates")(event);
557
+ },
558
+ // This is a completed action with status feedback, so it has no menu/gallery semantics.
559
+ false, undefined, "D", undefined, !hasDataRange(insert?.selection),
560
+ )}
561
+ {open === "data-remove-duplicates" && result !== null && (
562
+ <AnchoredOverlay
563
+ anchor={anchorEl}
564
+ className="sheet-ribbon-pop sheet-ribbon-pop-portal"
565
+ onDismiss={closePop}
566
+ role="status"
567
+ ariaLabel="Remove duplicates result"
568
+ initialFocus="none"
569
+ >
570
+ <p className="sheet-ribbon-insert-hint">{result}</p>
571
+ </AnchoredOverlay>
572
+ )}
573
+ </span>
574
+ );
575
+ }
576
+
577
+ function FlashFillControl({ ctx }: { ctx: RibbonTabContext }) {
578
+ const { insert, control, word, open, anchorEl, openPop, closePop } = ctx;
579
+ const [result, setResult] = useState<string | null>(null);
580
+ return (
581
+ <span className="sheet-ribbon-slot">
582
+ {control(
583
+ "data-flash-fill", "Flash fill", <><IconFlashFill />{word("Flash fill")}</>,
584
+ (event) => {
585
+ if (open === "data-flash-fill") { closePop(); return; }
586
+ setResult(flashFillSelection(insert));
587
+ openPop("data-flash-fill")(event);
588
+ },
589
+ false, undefined, "F", undefined, !hasDataRange(insert?.selection),
590
+ )}
591
+ {open === "data-flash-fill" && result !== null && (
592
+ <AnchoredOverlay
593
+ anchor={anchorEl}
594
+ className="sheet-ribbon-pop sheet-ribbon-pop-portal"
595
+ onDismiss={closePop}
596
+ role="status"
597
+ ariaLabel="Flash fill result"
598
+ initialFocus="none"
599
+ >
600
+ <p className="sheet-ribbon-insert-hint">{result}</p>
601
+ </AnchoredOverlay>
602
+ )}
603
+ </span>
604
+ );
605
+ }
606
+
607
  export const dataGroups = (ctx: RibbonTabContext) => {
608
+ const { act, control, group, unavailable, word, insert, closePop } = ctx;
609
+ const dataDisabled = !hasDataRange(insert?.selection);
610
  return (
611
  <>
612
  {group("Data", (
 
615
  "data-refresh", "Refresh all", <><IconRefresh />{word("Refresh all")}</>,
616
  () => act("refresh"), false, undefined, "R",
617
  )}
618
+ <QueriesConnectionsControl ctx={ctx} />
619
  </>
620
  ))}
621
  {group("Sort", (
622
  <>
623
+ {control(
624
+ "data-sort-asc", "Sort ascending", <><IconSort />{word("Sort ascending")}</>,
625
+ () => { transformSelectionRows(insert, (rows) => sortRows(rows, 1)); closePop(); },
626
+ false, undefined, "SA", undefined, dataDisabled,
627
+ )}
628
+ {control(
629
+ "data-sort-desc", "Sort descending", <><IconSort descending />{word("Sort descending")}</>,
630
+ () => { transformSelectionRows(insert, (rows) => sortRows(rows, -1)); closePop(); },
631
+ false, undefined, "SD", undefined, dataDisabled,
632
+ )}
633
  </>
634
  ))}
635
  {group("Auto filter", unavailable("Filter", word("Filter")))}
636
+ {group("Data validation", <DataValidationControl ctx={ctx} />)}
637
  {group("Data tools", (
638
  <>
639
+ <TextToColumnsControl ctx={ctx} />
640
+ <FlashFillControl ctx={ctx} />
641
+ <RemoveDuplicatesControl ctx={ctx} />
642
  </>
643
  ))}
644
  {group("Outline", (
web/src/sheet/ribbonInsert.tsx CHANGED
@@ -94,6 +94,7 @@ const CHARTS = ["chart"] as const;
94
  const SPARKLINES = ["sparkline-line", "sparkline-column", "sparkline-winloss"] as const;
95
  const LINKS = ["link"] as const;
96
  const COMMENTS = ["comment"] as const;
 
97
 
98
  /**
99
  * ⭐⭐ THE INSERT TAB'S ROVING ORDER, WHICH IS ALSO ITS TYPE. The shell spreads this into the union
@@ -103,7 +104,7 @@ const COMMENTS = ["comment"] as const;
103
  * call rendering it makes ArrowRight land on nothing, with every gate still green, so the two are
104
  * changed together or not at all.
105
  */
106
- export const INSERT_KEYS = [...CHARTS, ...SPARKLINES, ...LINKS, ...COMMENTS] as const;
107
 
108
  /**
109
  * ⭐ THE EIGHT KINDS AND THE FALLBACK RECTANGLE BOTH MOVED TO `ChartDialog.tsx` (W54-T11), which
@@ -384,7 +385,7 @@ export const insertGroups = (ctx: RibbonTabContext) => {
384
  // ⚠ `item` IS NO LONGER TAKEN OFF THE CONTEXT, and that is W54-T11's doing rather than an
385
  // oversight: the only menu this tab ever painted was the chart gallery, and the eight kinds are
386
  // buttons inside `ChartDialog` now. The shell still offers the helper to every tab.
387
- const { open, anchorEl, openPop, closePop, control, group, word, insert, act } = ctx;
388
 
389
  /**
390
  * ⭐ THE ANCHOR CELL, IN SHEET COORDINATES. The door hands the selection over already translated
@@ -627,6 +628,13 @@ export const insertGroups = (ctx: RibbonTabContext) => {
627
  )}
628
  </span>
629
  ))}
 
 
 
 
 
 
 
630
  </fieldset>
631
  );
632
  };
 
94
  const SPARKLINES = ["sparkline-line", "sparkline-column", "sparkline-winloss"] as const;
95
  const LINKS = ["link"] as const;
96
  const COMMENTS = ["comment"] as const;
97
+ const CELL_DATA = ["cell-data"] as const;
98
 
99
  /**
100
  * ⭐⭐ THE INSERT TAB'S ROVING ORDER, WHICH IS ALSO ITS TYPE. The shell spreads this into the union
 
104
  * call rendering it makes ArrowRight land on nothing, with every gate still green, so the two are
105
  * changed together or not at all.
106
  */
107
+ export const INSERT_KEYS = [...CHARTS, ...SPARKLINES, ...LINKS, ...COMMENTS, ...CELL_DATA] as const;
108
 
109
  /**
110
  * ⭐ THE EIGHT KINDS AND THE FALLBACK RECTANGLE BOTH MOVED TO `ChartDialog.tsx` (W54-T11), which
 
385
  // ⚠ `item` IS NO LONGER TAKEN OFF THE CONTEXT, and that is W54-T11's doing rather than an
386
  // oversight: the only menu this tab ever painted was the chart gallery, and the eight kinds are
387
  // buttons inside `ChartDialog` now. The shell still offers the helper to every tab.
388
+ const { open, anchorEl, openPop, closePop, control, group, word, insert, act, openCellData } = ctx;
389
 
390
  /**
391
  * ⭐ THE ANCHOR CELL, IN SHEET COORDINATES. The door hands the selection over already translated
 
628
  )}
629
  </span>
630
  ))}
631
+ {group("Cell data", control("cell-data", "Cell database", <>
632
+ <svg viewBox="0 0 16 16" stroke="currentColor" fill="none" aria-hidden="true" className="sheet-ribbon-icon">
633
+ <ellipse cx="8" cy="3.5" rx="5" ry="2" />
634
+ <path d="M3 3.5v9c0 1.1 2.2 2 5 2s5-.9 5-2v-9M3 8c0 1.1 2.2 2 5 2s5-.9 5-2" />
635
+ </svg>
636
+ {word("Cell database")}
637
+ </>, openCellData, undefined, undefined, "D"))}
638
  </fieldset>
639
  );
640
  };
web/src/sheet/ribbonView.tsx CHANGED
@@ -1,11 +1,11 @@
1
  // Sheet View ribbon, adapted from the behavior and grouping in the Wave 55 public Excel audit.
2
- // Freeze, Formula bar, Full screen, and Go to use existing executable doors. Canvas gridline
3
  // visibility and the other unsupported commands are deliberately labelled unavailable.
4
 
5
  import type { RibbonTabContext } from "./Ribbon";
6
 
7
  const SHOW = ["view-formula-bar"] as const;
8
- const WINDOW = ["view-freeze", "view-fullscreen"] as const;
9
  const NAVIGATION = ["view-go-to"] as const;
10
 
11
  export const VIEW_KEYS = [...SHOW, ...WINDOW, ...NAVIGATION] as const;
@@ -28,6 +28,15 @@ function IconFreeze() {
28
  );
29
  }
30
 
 
 
 
 
 
 
 
 
 
31
  function IconFullScreen() {
32
  return (
33
  <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon">
@@ -47,13 +56,25 @@ function IconGoTo() {
47
 
48
  export const viewGroups = (ctx: RibbonTabContext) => {
49
  const {
50
- act, control, formulaBarVisible, frozen, fullscreen, group,
51
  toggleFormulaBar, toggleFullscreen, unavailable, word,
52
  } = ctx;
53
  const fullscreenLabel = fullscreen ? "Exit full screen" : "Full screen";
54
  return (
55
  <>
56
- {group("Workbook views", unavailable("New window", word("New window")))}
 
 
 
 
 
 
 
 
 
 
 
 
57
  {group("Show", (
58
  <>
59
  {control(
 
1
  // Sheet View ribbon, adapted from the behavior and grouping in the Wave 55 public Excel audit.
2
+ // New window, Freeze, Formula bar, Full screen, and Go to use executable doors. Canvas gridline
3
  // visibility and the other unsupported commands are deliberately labelled unavailable.
4
 
5
  import type { RibbonTabContext } from "./Ribbon";
6
 
7
  const SHOW = ["view-formula-bar"] as const;
8
+ const WINDOW = ["view-freeze", "view-new-window", "view-fullscreen"] as const;
9
  const NAVIGATION = ["view-go-to"] as const;
10
 
11
  export const VIEW_KEYS = [...SHOW, ...WINDOW, ...NAVIGATION] as const;
 
28
  );
29
  }
30
 
31
+ function IconNewWindow() {
32
+ return (
33
+ <svg viewBox="0 0 16 16" stroke="currentColor" aria-hidden="true" className="sheet-ribbon-icon">
34
+ <rect x="5.5" y="5.5" width="8" height="8" rx="1" />
35
+ <path d="M10.5 5.5v-2a1 1 0 0 0-1-1h-6a1 1 0 0 0-1 1v6a1 1 0 0 0 1 1h2" />
36
+ </svg>
37
+ );
38
+ }
39
+
40
  function IconFullScreen() {
41
  return (
42
  <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon">
 
56
 
57
  export const viewGroups = (ctx: RibbonTabContext) => {
58
  const {
59
+ act, control, formulaBarVisible, frozen, fullscreen, group, newWindowBlocked, openNewWindow,
60
  toggleFormulaBar, toggleFullscreen, unavailable, word,
61
  } = ctx;
62
  const fullscreenLabel = fullscreen ? "Exit full screen" : "Full screen";
63
  return (
64
  <>
65
+ {group("Workbook views", (
66
+ <>
67
+ {control(
68
+ "view-new-window", "New window", <><IconNewWindow />{word("New window")}</>,
69
+ openNewWindow, undefined, undefined, "W",
70
+ )}
71
+ {newWindowBlocked && (
72
+ <span className="sheet-ribbon-state sheet-ribbon-window-message" role="status">
73
+ The browser blocked the new window. Allow popups for this site.
74
+ </span>
75
+ )}
76
+ </>
77
+ ))}
78
  {group("Show", (
79
  <>
80
  {control(
web/src/sheet/rules.ts CHANGED
@@ -344,6 +344,19 @@ export const rangeText = (range: string | SheetRuleRect): string => {
344
  return first === last ? first : `${first}:${last}`;
345
  };
346
 
 
 
 
 
 
 
 
 
 
 
 
 
 
347
  /** Does a rule's range cover this zero-based cell? `false` for a range that does not parse. */
348
  export const rangeCovers = (range: string | SheetRuleRect, col: number, row: number): boolean => {
349
  const rect = parseRange(range);
 
344
  return first === last ? first : `${first}:${last}`;
345
  };
346
 
347
+ /** Replace a parsed range without changing its stored shape or losing unparseable source text. */
348
+ export const withRuleRange = (rule: SheetRule, rect: RuleRect | null): SheetRule => {
349
+ const previous = parseRange(rule.range);
350
+ if (!previous || !rect || (previous.col0 === rect.col0 && previous.row0 === rect.row0
351
+ && previous.col1 === rect.col1 && previous.row1 === rect.row1)) return rule;
352
+ return {
353
+ ...rule,
354
+ range: typeof rule.range === "string"
355
+ ? rangeText(rect)
356
+ : { ...rule.range, ...rect },
357
+ };
358
+ };
359
+
360
  /** Does a rule's range cover this zero-based cell? `false` for a range that does not parse. */
361
  export const rangeCovers = (range: string | SheetRuleRect, col: number, row: number): boolean => {
362
  const rect = parseRange(range);
web/src/sheet/sheetState.ts CHANGED
@@ -31,7 +31,9 @@ import type { StructuralShift } from "./a1";
31
  // (its registry) and HOW one moves (delegated straight to `a1.ts`, never re-derived). This file
32
  // used to answer the first half inline, in two branches of `dragBoundCell`, which meant C3's
33
  // second reference slot would have had to be added here as well as wherever it was declared.
34
- import { materializeLocalViewBinding, shiftBindingRefs, shiftRefText } from "./bindingRefs";
 
 
35
  import type { SavedViewShadow } from "./bindingRefs";
36
  // ⭐⭐ W53-T01 / CONTRACT C1 — THE ONE IMPORT THAT MAKES A COMMITTED FORMULA COMPUTE LOCALLY.
37
  // `formulaEval.ts` imports nothing back from this file (see its own header): it takes a plain
@@ -45,6 +47,7 @@ import {
45
  import type { CellValue, QualifiedFormula } from "./formulaEval";
46
  import { replaceCellStyle } from "./cellStyleOps";
47
  import type { PasteMode } from "./clipboardOps";
 
48
 
49
  /** R19's three MARKS. `refused` is a fourth state and not one of the three: it replaces the value
50
  * rather than qualifying it, so it gets its own treatment in the renderer. */
@@ -661,6 +664,20 @@ export const displayText = (cell: Cell | null | undefined): string => {
661
  );
662
  };
663
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
664
  /**
665
  * Replace or REMOVE several cells at once, returning a NEW workbook. `null` removes.
666
  *
@@ -674,15 +691,7 @@ export const withCells = (
674
  edits: Record<string, Cell | null>,
675
  ): Workbook => ({
676
  ...book,
677
- sheets: book.sheets.map((tab) => {
678
- if (tab.id !== tabId) return tab;
679
- const cells: Record<string, Cell> = { ...(tab.cells ?? {}) };
680
- for (const [addr, cell] of Object.entries(edits)) {
681
- if (cell === null) delete cells[addr];
682
- else cells[addr] = cell;
683
- }
684
- return { ...tab, cells };
685
- }),
686
  });
687
 
688
  // ── undo and redo ────────────────────────────────────────────────────────────────────────────
@@ -768,6 +777,83 @@ export interface BulkEdit {
768
  edits: Record<string, Cell | null>;
769
  }
770
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
771
  // ═════════════════════════════════════════════════════════════════════════════════════════════
772
  // ⭐⭐ W51-T19 — DRAG RULES ON A BOUND CELL (rulings R9 and R10, contract C2).
773
  //
@@ -837,7 +923,12 @@ export interface BoundDragTally {
837
  }
838
 
839
  /** A bulk edit that also carries what the drag rules did. Every existing consumer still reads it. */
840
- export interface FillEdit extends BulkEdit, BoundDragTally {}
 
 
 
 
 
841
 
842
  /**
843
  * A PASTE, which is a fill that can also refuse for a reason no other bulk door has.
@@ -916,52 +1007,6 @@ export const signedCopyStep = (dCol: number, dRow: number): number => dCol || dR
916
  export const shiftPeriodRef = (ref: string, dRow: number, dCol: number): string =>
917
  shiftRefText(ref, dRow, dCol);
918
 
919
- /** Where a value sits in an option order, or -1. An unset value walks into the FIRST option. */
920
- const optionIndex = (options: readonly string[], value: string): number =>
921
- options.findIndex((option) => String(option) === value);
922
-
923
- /**
924
- * Walk one value `steps` places through an option order. NO WRAP: running off either end clamps
925
- * and says so, because a filter that silently returned to the first option would show the same
926
- * forty numbers twice with nothing on screen to explain it.
927
- */
928
- const walkOption = (
929
- options: readonly string[], value: string, steps: number,
930
- ): { value: string; atEnd: boolean } => {
931
- if (options.length === 0) return { value, atEnd: false };
932
- const at = optionIndex(options, value);
933
- const wanted = at + steps;
934
- const landed = Math.max(0, Math.min(options.length - 1, wanted));
935
- return { value: String(options[landed]), atEnd: landed !== wanted };
936
- };
937
-
938
- /**
939
- * Rewrite the value of the leaf whose `colId` is `field`, anywhere in a filter tree.
940
- *
941
- * ⛔ IT RECURSES INTO A GROUP'S `children`. `FilterBuilderPanel` emits nested groups, so matching
942
- * only the root's leaves is a walk that silently does nothing on any grouped filter, which is
943
- * the sort of filter a person builds when the cell matters enough to drag it forty times.
944
- */
945
- const walkFilterNodes = (
946
- nodes: readonly unknown[], field: string, next: (value: string) => string,
947
- ): { nodes: unknown[]; found: boolean } => {
948
- let found = false;
949
- const out = nodes.map((node) => {
950
- if (!node || typeof node !== "object") return node;
951
- const record = node as Record<string, unknown>;
952
- if (Array.isArray(record.children)) {
953
- const inner = walkFilterNodes(record.children as unknown[], field, next);
954
- if (!inner.found) return node;
955
- found = true;
956
- return { ...record, children: inner.nodes };
957
- }
958
- if (String(record.colId ?? "") !== field) return node;
959
- found = true;
960
- return { ...record, value: next(String(record.value ?? "")) };
961
- });
962
- return { nodes: out, found };
963
- };
964
-
965
  /** What one bound cell becomes when it is dragged, and what has to be SAID about it. */
966
  export interface BoundDrag {
967
  cell: Cell;
@@ -1058,28 +1103,12 @@ export const dragBoundCell = (
1058
  if (!options || options.length === 0) {
1059
  noCatalogue = true;
1060
  } else {
1061
- const scope = (next.scope ?? null) as Record<string, unknown> | null;
1062
- const tree = scope && typeof scope.filter === "object" && scope.filter
1063
- ? (scope.filter as Record<string, unknown>)
1064
- : null;
1065
- const nodes = tree && Array.isArray(tree.nodes) ? (tree.nodes as unknown[]) : null;
1066
- if (!nodes) {
1067
- noField = true;
1068
- } else {
1069
- const walked = walkFilterNodes(nodes, field, (value) => {
1070
- const walkedOption = walkOption(options, value, step);
1071
- atEnd = atEnd || walkedOption.atEnd;
1072
- return walkedOption.value;
1073
- });
1074
- if (!walked.found) noField = true;
1075
- else {
1076
- next = {
1077
- ...next,
1078
- scope: { ...(scope ?? {}), filter: { ...tree, nodes: walked.nodes } },
1079
- };
1080
- changed = true;
1081
- }
1082
- }
1083
  }
1084
  }
1085
 
@@ -1456,6 +1485,7 @@ export const pasteCells = (
1456
  // ⛔⛔ W54-T16 — A CUT IS A MOVE, AND A MOVE SHIFTS NOTHING. Answered ONCE, before any cell is
1457
  // built, because every landing cell in the block has to agree about it.
1458
  const moving = mode === "normal" && completesCut(pastedText);
 
1459
  const recalled = drag?.cells
1460
  ? null
1461
  : recallCopy(pastedText);
@@ -1573,29 +1603,38 @@ export const pasteCells = (
1573
  const srcRows = source.length;
1574
  let srcCols = 0;
1575
  for (const row of source) srcCols = Math.max(srcCols, row.length);
1576
- if (!rect || srcRows === 0 || srcCols === 0 || (wide === 1 && tall === 1)) {
 
1577
  // No drag, or one target cell: the block lands anchored where it was dropped, as it always has.
1578
  writeBlock(targetCol, targetRow);
1579
- // ⛔ W54-T16: AFTER the paste's own writes, so an overlapping cut keeps what just landed.
1580
- if (mode === "normal") clearCutSource(tab, edits, pastedText);
1581
- return { edits, ...tally };
1582
- }
1583
- if (wide % srcCols !== 0 || tall % srcRows !== 0) {
1584
  // ⛔ NOTHING IS WRITTEN ON A REFUSAL. Half a tile would leave the selection holding half a
1585
  // paste, which is the one outcome nobody can see well enough to put back by hand.
1586
  return { edits: {}, ...emptyTally(),
1587
  sizeRefusal: "The copy area and the paste area are not the same size." };
1588
- }
1589
- for (let ty = 0; ty < tall / srcRows; ty += 1) {
1590
- for (let tx = 0; tx < wide / srcCols; tx += 1) {
1591
- writeBlock(rect.col0 + tx * srcCols, rect.row0 + ty * srcRows);
 
1592
  }
1593
  }
 
 
 
 
 
 
 
 
 
 
 
1594
  // ⛔ W54-T16: same rule on the tiled path, and after every tile - a cut tiled back over its own
1595
  // rectangle keeps the copies that landed there. A SIZE REFUSAL above wrote nothing and returned
1596
  // before this line, so a refused paste also leaves the cut armed for the paste that works.
1597
  if (mode === "normal") clearCutSource(tab, edits, pastedText);
1598
- return { edits, ...tally };
1599
  };
1600
 
1601
  /**
@@ -1615,6 +1654,8 @@ export const fillCells = (
1615
  destination: { col0: number; row0: number; col1: number; row1: number },
1616
  drag?: DragContext,
1617
  get?: (addr: string) => CellValue,
 
 
1618
  ): FillEdit => {
1619
  const sc0 = Math.min(source.col0, source.col1);
1620
  const sr0 = Math.min(source.row0, source.row1);
@@ -1622,6 +1663,39 @@ export const fillCells = (
1622
  const sh = Math.abs(source.row1 - source.row0) + 1;
1623
  const edits: Record<string, Cell | null> = {};
1624
  const tally = emptyTally();
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1625
  // ⭐ W53-T01 / R2: a formula DRAGGED down shows its own number rather than its text, and it
1626
  // reads through the same overlay a paste does — a fill walks top to bottom, so the third cell
1627
  // of a running total must see the second cell this very fill just wrote.
@@ -1687,7 +1761,7 @@ export const fillCells = (
1687
  edits[addr] = withSourceStyle(commitTyped(target, editableText(pattern)), pattern);
1688
  }
1689
  }
1690
- return { edits, ...tally };
1691
  };
1692
 
1693
  // ═════════════════════════════════════════════════════════════════════════════════════════════
 
31
  // (its registry) and HOW one moves (delegated straight to `a1.ts`, never re-derived). This file
32
  // used to answer the first half inline, in two branches of `dragBoundCell`, which meant C3's
33
  // second reference slot would have had to be added here as well as wherever it was declared.
34
+ import {
35
+ materializeLocalViewBinding, shiftBindingRefs, shiftRefText, stepBindingFilter,
36
+ } from "./bindingRefs";
37
  import type { SavedViewShadow } from "./bindingRefs";
38
  // ⭐⭐ W53-T01 / CONTRACT C1 — THE ONE IMPORT THAT MAKES A COMMITTED FORMULA COMPUTE LOCALLY.
39
  // `formulaEval.ts` imports nothing back from this file (see its own header): it takes a plain
 
47
  import type { CellValue, QualifiedFormula } from "./formulaEval";
48
  import { replaceCellStyle } from "./cellStyleOps";
49
  import type { PasteMode } from "./clipboardOps";
50
+ import { parseRange, withRuleRange } from "./rules";
51
 
52
  /** R19's three MARKS. `refused` is a fourth state and not one of the three: it replaces the value
53
  * rather than qualifying it, so it gets its own treatment in the renderer. */
 
664
  );
665
  };
666
 
667
+ /** Apply a batch without losing tab-level fields, including the ranges returned by a move. */
668
+ const tabWithEdits = (
669
+ tab: SheetTab,
670
+ edits: Record<string, Cell | null>,
671
+ ): SheetTab => {
672
+ if (Object.keys(edits).length === 0) return tab;
673
+ const cells: Record<string, Cell> = { ...(tab.cells ?? {}) };
674
+ for (const [addr, cell] of Object.entries(edits)) {
675
+ if (cell === null) delete cells[addr];
676
+ else cells[addr] = cell;
677
+ }
678
+ return { ...tab, cells };
679
+ };
680
+
681
  /**
682
  * Replace or REMOVE several cells at once, returning a NEW workbook. `null` removes.
683
  *
 
691
  edits: Record<string, Cell | null>,
692
  ): Workbook => ({
693
  ...book,
694
+ sheets: book.sheets.map((tab) => tab.id === tabId ? tabWithEdits(tab, edits) : tab),
 
 
 
 
 
 
 
 
695
  });
696
 
697
  // ── undo and redo ────────────────────────────────────────────────────────────────────────────
 
777
  edits: Record<string, Cell | null>;
778
  }
779
 
780
+ /** Everything on a tab that stores a range of cells and must follow them when they move. */
781
+ export interface RangeConsumer {
782
+ name: string;
783
+ read: (tab: SheetTab) => readonly (CellRange | null)[];
784
+ write: (tab: SheetTab, ranges: readonly (CellRange | null)[]) => SheetTab;
785
+ }
786
+
787
+ /** C2: new tab-level range consumers register their read and write here, never at a move door. */
788
+ export const RANGE_CONSUMERS = [
789
+ {
790
+ name: "charts",
791
+ read: (tab) => (tab.charts ?? []).map((chart) => chart.range),
792
+ write: (tab, ranges) => ({
793
+ ...tab,
794
+ charts: (tab.charts ?? []).map((chart, index) => {
795
+ const range = ranges[index];
796
+ return !range || range === chart.range
797
+ ? chart : { ...chart, range: { ...chart.range, ...range } };
798
+ }),
799
+ }),
800
+ },
801
+ {
802
+ name: "rules",
803
+ read: (tab) => (tab.rules ?? []).map((rule) => parseRange(rule.range)),
804
+ write: (tab, ranges) => ({
805
+ ...tab,
806
+ rules: (tab.rules ?? []).map((rule, index) => withRuleRange(rule, ranges[index] ?? null)),
807
+ }),
808
+ },
809
+ ] as const satisfies readonly RangeConsumer[];
810
+
811
+ /**
812
+ * C2: translate the WHOLE stored range when it intersects the source rectangle, including an
813
+ * edge or corner cell. Disjoint ranges stay put. This is a move, never copy or structure math.
814
+ * The caller saves the returned tab; unchanged ranges keep their objects and nothing is mutated.
815
+ */
816
+ export const rewriteRangesOnMove = (
817
+ tab: SheetTab,
818
+ delta: { dCol: number; dRow: number },
819
+ movedRect: CellRange,
820
+ ): SheetTab => {
821
+ if ((!delta.dCol && !delta.dRow) || ![
822
+ delta.dCol, delta.dRow, movedRect.col0, movedRect.row0, movedRect.col1, movedRect.row1,
823
+ ].every(Number.isFinite)) return tab;
824
+ const source = normalised(movedRect);
825
+ const extent = sheetExtent(tab);
826
+ // Match the chart-axis clamp precedent: normalized, nonnegative, bounded by rendered extent.
827
+ const shiftedAxis = (a: number, b: number, step: number, limit: number): [number, number] => {
828
+ const ceiling = Math.max(0, limit - 1);
829
+ let lo = Math.max(0, Math.min(a, b) + step);
830
+ let hi = Math.max(lo, Math.max(a, b) + step);
831
+ if (hi > ceiling) {
832
+ lo = Math.max(0, lo - (hi - ceiling));
833
+ hi = ceiling;
834
+ }
835
+ return [Math.min(lo, ceiling), Math.min(Math.max(lo, hi), ceiling)];
836
+ };
837
+ let next = tab;
838
+ for (const consumer of RANGE_CONSUMERS) {
839
+ let changed = false;
840
+ const ranges = consumer.read(next).map((range) => {
841
+ if (!range) return range;
842
+ const rect = normalised(range);
843
+ if (rect.col1 < source.col0 || rect.col0 > source.col1
844
+ || rect.row1 < source.row0 || rect.row0 > source.row1) return range;
845
+ const [col0, col1] = shiftedAxis(rect.col0, rect.col1, delta.dCol, extent.cols);
846
+ const [row0, row1] = shiftedAxis(rect.row0, rect.row1, delta.dRow, extent.rows);
847
+ if (col0 === range.col0 && col1 === range.col1
848
+ && row0 === range.row0 && row1 === range.row1) return range;
849
+ changed = true;
850
+ return { ...range, col0, row0, col1, row1 };
851
+ });
852
+ if (changed) next = consumer.write(next, ranges);
853
+ }
854
+ return next;
855
+ };
856
+
857
  // ═════════════════════════════════════════════════════════════════════════════════════════════
858
  // ⭐⭐ W51-T19 — DRAG RULES ON A BOUND CELL (rulings R9 and R10, contract C2).
859
  //
 
923
  }
924
 
925
  /** A bulk edit that also carries what the drag rules did. Every existing consumer still reads it. */
926
+ export interface FillEdit extends BulkEdit, BoundDragTally {
927
+ /** The complete document result. Save this tab, not only its cell edits, to retain moved ranges. */
928
+ tab?: SheetTab;
929
+ /** A move needs one destination rectangle of the same size as its source. */
930
+ sizeRefusal?: string;
931
+ }
932
 
933
  /**
934
  * A PASTE, which is a fill that can also refuse for a reason no other bulk door has.
 
1007
  export const shiftPeriodRef = (ref: string, dRow: number, dCol: number): string =>
1008
  shiftRefText(ref, dRow, dCol);
1009
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1010
  /** What one bound cell becomes when it is dragged, and what has to be SAID about it. */
1011
  export interface BoundDrag {
1012
  cell: Cell;
 
1103
  if (!options || options.length === 0) {
1104
  noCatalogue = true;
1105
  } else {
1106
+ const axis = dCol ? (dCol < 0 ? "left" : "right") : (dRow < 0 ? "up" : "down");
1107
+ const walked = stepBindingFilter(next, field, options, axis, Math.abs(step));
1108
+ next = walked.binding;
1109
+ changed = changed || walked.changed;
1110
+ noField = walked.noField;
1111
+ atEnd = walked.atEnd;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1112
  }
1113
  }
1114
 
 
1485
  // ⛔⛔ W54-T16 — A CUT IS A MOVE, AND A MOVE SHIFTS NOTHING. Answered ONCE, before any cell is
1486
  // built, because every landing cell in the block has to agree about it.
1487
  const moving = mode === "normal" && completesCut(pastedText);
1488
+ const cut = moving ? pendingCut : null;
1489
  const recalled = drag?.cells
1490
  ? null
1491
  : recallCopy(pastedText);
 
1603
  const srcRows = source.length;
1604
  let srcCols = 0;
1605
  for (const row of source) srcCols = Math.max(srcCols, row.length);
1606
+ const anchored = !rect || srcRows === 0 || srcCols === 0 || (wide === 1 && tall === 1);
1607
+ if (anchored) {
1608
  // No drag, or one target cell: the block lands anchored where it was dropped, as it always has.
1609
  writeBlock(targetCol, targetRow);
1610
+ } else if (wide % srcCols !== 0 || tall % srcRows !== 0) {
 
 
 
 
1611
  // ⛔ NOTHING IS WRITTEN ON A REFUSAL. Half a tile would leave the selection holding half a
1612
  // paste, which is the one outcome nobody can see well enough to put back by hand.
1613
  return { edits: {}, ...emptyTally(),
1614
  sizeRefusal: "The copy area and the paste area are not the same size." };
1615
+ } else {
1616
+ for (let ty = 0; ty < tall / srcRows; ty += 1) {
1617
+ for (let tx = 0; tx < wide / srcCols; tx += 1) {
1618
+ writeBlock(rect.col0 + tx * srcCols, rect.row0 + ty * srcRows);
1619
+ }
1620
  }
1621
  }
1622
+ // C2: a cut follows the FIRST landing block if the selection tiles it. Use its actual offset,
1623
+ // not the zero delta that deliberately keeps moved formulas and bindings verbatim above.
1624
+ const movedTab = tab && cut && Object.keys(edits).length > 0
1625
+ ? rewriteRangesOnMove(tab, {
1626
+ dCol: (anchored ? targetCol : rect.col0) - cut.col,
1627
+ dRow: (anchored ? targetRow : rect.row0) - cut.row,
1628
+ }, {
1629
+ col0: cut.col, row0: cut.row,
1630
+ col1: cut.col + srcCols - 1, row1: cut.row + srcRows - 1,
1631
+ })
1632
+ : tab;
1633
  // ⛔ W54-T16: same rule on the tiled path, and after every tile - a cut tiled back over its own
1634
  // rectangle keeps the copies that landed there. A SIZE REFUSAL above wrote nothing and returned
1635
  // before this line, so a refused paste also leaves the cut armed for the paste that works.
1636
  if (mode === "normal") clearCutSource(tab, edits, pastedText);
1637
+ return { edits, ...tally, ...(movedTab ? { tab: tabWithEdits(movedTab, edits) } : {}) };
1638
  };
1639
 
1640
  /**
 
1654
  destination: { col0: number; row0: number; col1: number; row1: number },
1655
  drag?: DragContext,
1656
  get?: (addr: string) => CellValue,
1657
+ /** Ordinary fills copy. An explicit move relocates one equally sized source block verbatim. */
1658
+ mode: "copy" | "move" = "copy",
1659
  ): FillEdit => {
1660
  const sc0 = Math.min(source.col0, source.col1);
1661
  const sr0 = Math.min(source.row0, source.row1);
 
1663
  const sh = Math.abs(source.row1 - source.row0) + 1;
1664
  const edits: Record<string, Cell | null> = {};
1665
  const tally = emptyTally();
1666
+ if (mode === "move") {
1667
+ if (!tab) return { edits, ...tally };
1668
+ const target = normalised(destination);
1669
+ const extent = sheetExtent(tab);
1670
+ if (target.col1 - target.col0 + 1 !== sw || target.row1 - target.row0 + 1 !== sh) {
1671
+ return { edits, ...tally, sizeRefusal: "The source and move area must be the same size." };
1672
+ }
1673
+ if (sc0 < 0 || sr0 < 0 || sc0 + sw > extent.cols || sr0 + sh > extent.rows
1674
+ || target.col0 < 0 || target.row0 < 0
1675
+ || target.col1 >= extent.cols || target.row1 >= extent.rows) {
1676
+ return { edits, ...tally, sizeRefusal: "The move area must be inside this sheet." };
1677
+ }
1678
+ const delta = { dCol: target.col0 - sc0, dRow: target.row0 - sr0 };
1679
+ if (!delta.dCol && !delta.dRow) return { edits, ...tally, tab };
1680
+ // Clear first and land from the original tab, so overlapping moves retain every source cell.
1681
+ for (const addr of addressesIn(sc0, sr0, sc0 + sw - 1, sr0 + sh - 1)) edits[addr] = null;
1682
+ for (let r = 0; r < sh; r += 1) {
1683
+ for (let c = 0; c < sw; c += 1) {
1684
+ const pattern = cellAt(tab, addressOf(sc0 + c, sr0 + r));
1685
+ const addr = addressOf(target.col0 + c, target.row0 + r);
1686
+ if (pattern?.kind === "bound") {
1687
+ edits[addr] = dragBoundCell(pattern, 0, 0, drag?.catalogue, drag?.shadows).cell;
1688
+ tally.dragged += 1;
1689
+ } else {
1690
+ edits[addr] = pattern ? { ...pattern } : null;
1691
+ }
1692
+ }
1693
+ }
1694
+ const movedTab = rewriteRangesOnMove(tab, delta, {
1695
+ col0: sc0, row0: sr0, col1: sc0 + sw - 1, row1: sr0 + sh - 1,
1696
+ });
1697
+ return { edits, ...tally, tab: tabWithEdits(movedTab, edits) };
1698
+ }
1699
  // ⭐ W53-T01 / R2: a formula DRAGGED down shows its own number rather than its text, and it
1700
  // reads through the same overlay a paste does — a fill walks top to bottom, so the third cell
1701
  // of a running total must see the second cell this very fill just wrote.
 
1761
  edits[addr] = withSourceStyle(commitTyped(target, editableText(pattern)), pattern);
1762
  }
1763
  }
1764
+ return { edits, ...tally, ...(tab ? { tab: tabWithEdits(tab, edits) } : {}) };
1765
  };
1766
 
1767
  // ═════════════════════════════════════════════════════════════════════════════════════════════
web/src/sheet/shortcuts.ts CHANGED
@@ -35,7 +35,7 @@ export type ShortcutId =
35
  | "jump-edge" | "extend-edge" | "extend-cell"
36
  | "go-home" | "go-end" | "page-up" | "page-down"
37
  | "prev-sheet" | "next-sheet"
38
- | "select-all" | "select-column" | "select-row"
39
  // Entering and filling
40
  | "fill-down" | "fill-right" | "fill-selection" | "line-break" | "today" | "autosum"
41
  // Undo, redo and the workbook's own doors
@@ -172,6 +172,15 @@ export const SHORTCUTS: readonly Shortcut[] = [
172
  when: "A cell is selected",
173
  owner: "sheet",
174
  },
 
 
 
 
 
 
 
 
 
175
  {
176
  id: "fill-down",
177
  keys: "Ctrl+D",
@@ -676,6 +685,7 @@ const rawMatchShortcut = (chord: KeyChord): ShortcutId | null => {
676
 
677
  if (shift) {
678
  if (ARROWS[key] === true) return "extend-edge";
 
679
  if (letter === "z") return "redo-alt";
680
  if (key === "$") return "format-currency";
681
  if (key === "%") return "format-percent";
@@ -791,6 +801,34 @@ export const edgeIndex = (
791
  return at;
792
  };
793
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
794
  /** The rectangle Ctrl+Space means: one whole column, in whatever coordinates it was handed. */
795
  export const columnBand = (col: number, rows: number) => ({
796
  col0: col, col1: col, row0: 0, row1: Math.max(0, rows - 1),
 
35
  | "jump-edge" | "extend-edge" | "extend-cell"
36
  | "go-home" | "go-end" | "page-up" | "page-down"
37
  | "prev-sheet" | "next-sheet"
38
+ | "select-all" | "select-column" | "select-row" | "select-region"
39
  // Entering and filling
40
  | "fill-down" | "fill-right" | "fill-selection" | "line-break" | "today" | "autosum"
41
  // Undo, redo and the workbook's own doors
 
172
  when: "A cell is selected",
173
  owner: "sheet",
174
  },
175
+ // W57-T04: instruction 1's "figure out other things like this too" authorizes this addition
176
+ // to R7's list. No existing row or chord is dropped or renamed.
177
+ {
178
+ id: "select-region",
179
+ keys: "Ctrl+Shift+Space",
180
+ action: "Select the block of data around the cell",
181
+ when: "A cell is selected",
182
+ owner: "sheet",
183
+ },
184
  {
185
  id: "fill-down",
186
  keys: "Ctrl+D",
 
685
 
686
  if (shift) {
687
  if (ARROWS[key] === true) return "extend-edge";
688
+ if (key === " ") return "select-region";
689
  if (letter === "z") return "redo-alt";
690
  if (key === "$") return "format-currency";
691
  if (key === "%") return "format-percent";
 
801
  return at;
802
  };
803
 
804
+ /**
805
+ * W57-T04 - EXCEL'S CURRENT REGION: the block of filled cells around one anchor, bounded by
806
+ * the first empty row and column in each of the four directions.
807
+ *
808
+ * Built from {@link edgeIndex}, not a second walk: each bound follows the same contiguous
809
+ * run as Ctrl+Arrow, with the perpendicular index held at the anchor. An isolated empty cell
810
+ * is its own one-cell region. Every index is zero based, like {@link edgeIndex}'s.
811
+ */
812
+ export const currentRegion = (
813
+ anchor: { col: number; row: number },
814
+ extent: { cols: number; rows: number },
815
+ filled: (col: number, row: number) => boolean,
816
+ ): SelectionRect => {
817
+ const { col, row } = anchor;
818
+ const left = edgeIndex(col, extent.cols, -1, (c) => filled(c, row));
819
+ const right = edgeIndex(col, extent.cols, 1, (c) => filled(c, row));
820
+ const up = edgeIndex(row, extent.rows, -1, (r) => filled(col, r));
821
+ const down = edgeIndex(row, extent.rows, 1, (r) => filled(col, r));
822
+ // edgeIndex deliberately moves through gaps or to the boundary. A region must stop at a
823
+ // blank immediate neighbour instead, or an isolated anchor would select the whole sheet.
824
+ return {
825
+ col0: col > 0 && filled(col - 1, row) ? left : col,
826
+ col1: col + 1 < extent.cols && filled(col + 1, row) ? right : col,
827
+ row0: row > 0 && filled(col, row - 1) ? up : row,
828
+ row1: row + 1 < extent.rows && filled(col, row + 1) ? down : row,
829
+ };
830
+ };
831
+
832
  /** The rectangle Ctrl+Space means: one whole column, in whatever coordinates it was handed. */
833
  export const columnBand = (col: number, rows: number) => ({
834
  col0: col, col1: col, row0: 0, row1: Math.max(0, rows - 1),
web/src/sheet/types.ts CHANGED
@@ -1233,6 +1233,13 @@ export const asNumber = (value: unknown): number | null => {
1233
  export const FORMULA_ERROR_CODES = ["#DIV/0!", "#REF!", "#NAME?", "#VALUE!"] as const;
1234
  export type FormulaErrorCode = (typeof FORMULA_ERROR_CODES)[number];
1235
 
 
 
 
 
 
 
 
1236
  /**
1237
  * ⭐ THE SERVER'S REFUSAL CODES, TRANSLATED. These names are `routes_sheet.py`'s own
1238
  * (`div_zero`, `unknown_ref`, `unknown_sheet`, `bad_formula`, `bad_value`), and the server owns
@@ -1280,7 +1287,7 @@ export const cellErrorCode = (
1280
  };
1281
 
1282
  /**
1283
- * How a formatted cell READS: on the canvas, in glide's clipboard, and therefore in an export.
1284
  *
1285
  * ⛔⛔ R10 IS NOT BENT BY THIS AND THE DISTINCTION MATTERS. A format PRESENTS the value the cell
1286
  * already holds; it never asks the server for a new one and never recomputes anything. A sheet
@@ -1301,6 +1308,15 @@ export const formatCellText = (
1301
  const errorCode = cellErrorCode(cell);
1302
  if (errorCode) return errorCode;
1303
 
 
 
 
 
 
 
 
 
 
1304
  const format = cell?.style?.format;
1305
  if (!cell || !format) return fallback;
1306
  if (cell.state === "refused") return fallback;
 
1233
  export const FORMULA_ERROR_CODES = ["#DIV/0!", "#REF!", "#NAME?", "#VALUE!"] as const;
1234
  export type FormulaErrorCode = (typeof FORMULA_ERROR_CODES)[number];
1235
 
1236
+ /**
1237
+ * W57-T03 / instruction 2: a formula that has never computed reads as pending, not its source.
1238
+ * `sheetState.ts::cellFromFormulaResult` falls back to `display: formula` when no value exists.
1239
+ * Keep this distinct from blank: an `empty` result computed to nothing; this formula awaits a value.
1240
+ */
1241
+ export const FORMULA_PENDING_DISPLAY = "...";
1242
+
1243
  /**
1244
  * ⭐ THE SERVER'S REFUSAL CODES, TRANSLATED. These names are `routes_sheet.py`'s own
1245
  * (`div_zero`, `unknown_ref`, `unknown_sheet`, `bad_formula`, `bad_value`), and the server owns
 
1287
  };
1288
 
1289
  /**
1290
+ * How a formatted cell reads on the canvas and in glide's clipboard.
1291
  *
1292
  * ⛔⛔ R10 IS NOT BENT BY THIS AND THE DISTINCTION MATTERS. A format PRESENTS the value the cell
1293
  * already holds; it never asks the server for a new one and never recomputes anything. A sheet
 
1308
  const errorCode = cellErrorCode(cell);
1309
  if (errorCode) return errorCode;
1310
 
1311
+ // W57-T03 / instruction 2: a cell never reads as its own uncomputed formula.
1312
+ // Check the value too: ="=hello" is a valid computed string and must keep its leading "=".
1313
+ // Refused cells keep their error token above or refusal text; this guards waiting formulas
1314
+ // before the optional format so unformatted cells, canvas and clipboard all use the rule.
1315
+ if (cell?.kind === "formula" && cell.value == null && cell.state !== "refused"
1316
+ && String(fallback ?? "").startsWith("=")) {
1317
+ return FORMULA_PENDING_DISPLAY;
1318
+ }
1319
+
1320
  const format = cell?.style?.format;
1321
  if (!cell || !format) return fallback;
1322
  if (cell.state === "refused") return fallback;
web/src/shell/LoginPage.tsx CHANGED
@@ -19,11 +19,74 @@
19
  // double-click protection, not rate limiting.
20
  // ---------------------------------------------------------------------------
21
 
22
- import { useState } from "react";
23
  import type { FormEvent } from "react";
24
  import { Brand } from "./Brand";
25
- import { login } from "./session";
26
- import type { SessionUser } from "./session";
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
27
 
28
  /** The reveal toggle the host's password field ships natively (BaseWeb's eye).
29
  * Two doors, one affordance. */
@@ -43,23 +106,141 @@ export default function LoginPage({ onSignedIn }: { onSignedIn: (user: SessionUs
43
  const [error, setError] = useState("");
44
  const [busy, setBusy] = useState(false);
45
  const [reveal, setReveal] = useState(false);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
46
 
47
  async function submit(e: FormEvent) {
48
  e.preventDefault();
49
- if (busy) return;
 
50
  setBusy(true);
51
  setError("");
52
- const result = await login(username, password);
53
- if (result.ok) {
54
- // No setBusy(false): the parent unmounts this tree on success, and
55
- // flipping state on the way out is how "update on an unmounted
56
- // component" warnings are born.
57
- onSignedIn(result.user);
58
- return;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
59
  }
60
- setBusy(false);
61
- setError(result.message);
 
 
 
62
  setPassword("");
 
 
 
 
 
 
 
63
  }
64
 
65
  // An error that survives the correction is an error that reads as sticky.
@@ -91,68 +272,156 @@ export default function LoginPage({ onSignedIn }: { onSignedIn: (user: SessionUs
91
  ⚠ No dash of any kind (R6). A slogan is exactly where an em dash wants to appear. */}
92
  <p className="login-tagline">Every workflow, automated.</p>
93
 
 
 
 
 
 
 
 
 
94
  <form className="login-form" onSubmit={submit} noValidate>
95
- {/* Labels are present and hidden, not absent. `gate()` collapses them
96
- because Streamlit gives no other way to get a placeholder-only
97
- field; here the label exists for assistive tech and the visual is
98
- identical. */}
99
- {/* No autoFocus: the other door cannot autofocus (Streamlit), and the
100
- focus ring it would paint on load reads as a highlighted error on
101
- an untouched form. */}
102
- <label className="lp-sr-only" htmlFor="login-username">Username</label>
103
- <input
104
- id="login-username"
105
- className="login-input"
106
- name="username"
107
- type="text"
108
- autoComplete="username"
109
- placeholder="Username"
110
- value={username}
111
- onChange={edit(setUsername)}
112
- disabled={busy}
113
- aria-invalid={error ? true : undefined}
114
- />
115
-
116
- <label className="lp-sr-only" htmlFor="login-password">Password</label>
117
- <div className="login-field">
118
- <input
119
- id="login-password"
120
- className="login-input"
121
- name="password"
122
- type={reveal ? "text" : "password"}
123
- autoComplete="current-password"
124
- placeholder="Password"
125
- value={password}
126
- onChange={edit(setPassword)}
127
- disabled={busy}
128
- aria-invalid={error ? true : undefined}
129
- />
130
- {/* tabIndex −1: Tab goes Username → Password → Log in; the reveal is
131
- a mouse affordance, same as the host's. */}
132
- <button
133
- type="button"
134
- className="login-eye"
135
- aria-label={reveal ? "Hide password" : "Show password"}
136
- onClick={() => setReveal((v) => !v)}
137
- disabled={busy}
138
- tabIndex={-1}
139
- >
140
- <EyeIcon off={reveal} />
141
- </button>
142
- </div>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
143
 
144
  {/* Disabled through THREE channels (the real attribute, the cursor and
145
  the opacity), never opacity alone — a control that only looks dead
146
  is a control that still takes the click. */}
147
- <button className="login-submit" type="submit" disabled={busy}>
148
- {busy ? "Signing in…" : "Log in"}
149
- </button>
 
 
 
 
 
 
 
 
 
150
  </form>
151
 
152
  {/* The message line is ALWAYS in the layout (min-height: 1lh) so an
153
  arriving error does not shove the card. `role="status"` rather than
154
  "alert": polite announcement, no interruption. */}
155
- <p className="login-msg" role="status" aria-live="polite">
156
  {error}
157
  </p>
158
  </div>
 
19
  // double-click protection, not rate limiting.
20
  // ---------------------------------------------------------------------------
21
 
22
+ import { useEffect, useRef, useState } from "react";
23
  import type { FormEvent } from "react";
24
  import { Brand } from "./Brand";
25
+ import { changePassword, login, mfaEnrollConfirm, mfaEnrollStart, passwordPolicy } from "./session";
26
+ import type { LoginOutcome, MFASetup, PasswordPolicy, SessionUser } from "./session";
27
+ import { useEscapeClose } from "../ui/useEscapeClose";
28
+ import "../styles/wave57/login-mfa.css";
29
+
30
+ type Step = "credentials" | "expired" | "mfa" | "enrol" | "codes";
31
+ type IssuedCodes = { user: SessionUser; recoveryCodes: string[] };
32
+
33
+ /** W57-T36 / C12: one show-once treatment in both doors. Copy is a quiet,
34
+ * explicit export to the person's clipboard, never persistence on their behalf.
35
+ * Only the acknowledgement can dismiss this surface; Escape names what remains.
36
+ * Browser reload/close can only be warned about, never made impossible by a page. */
37
+ export function RecoveryCodes({ codes, onSaved, onError }: {
38
+ codes: string[];
39
+ onSaved: () => void;
40
+ onError: (message: string) => void;
41
+ }) {
42
+ const [copied, setCopied] = useState<boolean>(false);
43
+ const [copying, setCopying] = useState<boolean>(false);
44
+ useEscapeClose(true, () => onError("Save your recovery codes before continuing."));
45
+ useEffect(() => {
46
+ const warn = (event: BeforeUnloadEvent) => {
47
+ event.preventDefault();
48
+ event.returnValue = "";
49
+ };
50
+ window.addEventListener("beforeunload", warn);
51
+ return () => window.removeEventListener("beforeunload", warn);
52
+ }, []);
53
+
54
+ async function copy() {
55
+ if (copying) return;
56
+ setCopying(true);
57
+ try {
58
+ await navigator.clipboard.writeText(codes.join("\n"));
59
+ setCopied(true);
60
+ onError("");
61
+ } catch {
62
+ setCopied(false);
63
+ onError("Copy did not work. Select the codes and copy them manually.");
64
+ } finally {
65
+ setCopying(false);
66
+ }
67
+ }
68
+
69
+ return (
70
+ <>
71
+ <p className="login-mfa-help">This screen is the only place these recovery codes will ever be shown.</p>
72
+ <p className="login-mfa-help">Save them somewhere safe; each code works once if you lose your authenticator.</p>
73
+ <ul className="login-mfa-codes" aria-label="Recovery codes">
74
+ {codes.map((code) => <li key={code}><code>{code}</code></li>)}
75
+ </ul>
76
+ <div className="login-mfa-copy-row">
77
+ <button type="button" className="login-mfa-quiet" onClick={() => void copy()} disabled={copying}>
78
+ {copying ? "Copying…" : "Copy codes"}
79
+ </button>
80
+ <span className="login-mfa-copy-status" role="status">{copied ? "Copied" : ""}</span>
81
+ </div>
82
+ {/* A type=button acknowledgement cannot be submitted by Enter left over
83
+ from the previous code field. There is no Back or secondary exit. */}
84
+ <button type="button" className="login-submit" onClick={onSaved} disabled={copying}>
85
+ I have saved these codes
86
+ </button>
87
+ </>
88
+ );
89
+ }
90
 
91
  /** The reveal toggle the host's password field ships natively (BaseWeb's eye).
92
  * Two doors, one affordance. */
 
106
  const [error, setError] = useState("");
107
  const [busy, setBusy] = useState(false);
108
  const [reveal, setReveal] = useState(false);
109
+ const [step, setStep] = useState<Step>("credentials");
110
+ const [newPassword, setNewPassword] = useState<string>("");
111
+ const [confirmPassword, setConfirmPassword] = useState<string>("");
112
+ const [code, setCode] = useState<string>("");
113
+ const [setup, setSetup] = useState<MFASetup | null>(null);
114
+ const [issued, setIssued] = useState<IssuedCodes | null>(null);
115
+ const [policy, setPolicy] = useState<PasswordPolicy | null>(null);
116
+ const [policyLoading, setPolicyLoading] = useState<boolean>(false);
117
+ const flight = useRef<boolean>(false);
118
+ const stepHeading = useRef<HTMLHeadingElement>(null);
119
+
120
+ // The password rules belong to the server, including history. Show its
121
+ // checklist without inventing a second policy or claiming a local green pass.
122
+ useEffect(() => {
123
+ if (step !== "expired") return;
124
+ let current = true;
125
+ setPolicy(null);
126
+ setPolicyLoading(true);
127
+ void passwordPolicy().then((next) => {
128
+ if (!current) return;
129
+ setPolicy(next);
130
+ setPolicyLoading(false);
131
+ });
132
+ return () => { current = false; };
133
+ }, [step]);
134
+
135
+ // Initial credentials keep the original no-autofocus rule. Later steps name
136
+ // the new task to assistive tech, and focus the heading rather than a submit.
137
+ useEffect(() => { stepHeading.current?.focus(); }, [step]);
138
+
139
+ async function startEnrolment(currentPassword: string) {
140
+ setSetup(null);
141
+ setCode("");
142
+ const result = await mfaEnrollStart(username, currentPassword);
143
+ if (result.ok === false) setError(result.message);
144
+ else setSetup({ secret: result.secret, otpauthUri: result.otpauthUri, issuer: result.issuer });
145
+ }
146
+
147
+ /** Correct credentials must survive a challenge. Clearing the password on
148
+ * every 401 would make the second-factor POST an invalid-credentials loop.
149
+ * It stays only in this mounted tree, and leaves with success or Back. */
150
+ async function accept(result: LoginOutcome, currentPassword: string) {
151
+ if (result.ok === true) {
152
+ setPassword("");
153
+ setSetup(null);
154
+ setCode("");
155
+ onSignedIn(result.user);
156
+ return;
157
+ }
158
+ setError(result.message);
159
+ switch (result.reason) {
160
+ case "password_expired":
161
+ setPolicyLoading(true);
162
+ setStep("expired");
163
+ setSetup(null);
164
+ setCode("");
165
+ break;
166
+ case "mfa_required":
167
+ case "mfa_invalid":
168
+ setStep("mfa");
169
+ setSetup(null);
170
+ setCode("");
171
+ break;
172
+ case "mfa_enrolment_required":
173
+ setStep("enrol");
174
+ await startEnrolment(currentPassword);
175
+ break;
176
+ default:
177
+ // Keep the current challenge on network/backoff errors so retry uses
178
+ // the proved password. A wrong initial credential is cleared as before.
179
+ if (step === "credentials" && result.reason === "credentials") setPassword("");
180
+ }
181
+ }
182
 
183
  async function submit(e: FormEvent) {
184
  e.preventDefault();
185
+ if (flight.current || step === "codes") return;
186
+ flight.current = true;
187
  setBusy(true);
188
  setError("");
189
+ try {
190
+ if (step === "expired") {
191
+ if (newPassword !== confirmPassword) {
192
+ setError("The new passwords do not match.");
193
+ return;
194
+ }
195
+ const changed = await changePassword(username, password, newPassword);
196
+ if (changed.ok === false) {
197
+ setError(changed.message);
198
+ return;
199
+ }
200
+ // Rotation invalidates the old credential. Reuse the new one right
201
+ // away, with a retryable credentials step if the next request is lost.
202
+ setPassword(newPassword);
203
+ setNewPassword("");
204
+ setConfirmPassword("");
205
+ setStep("credentials");
206
+ await accept(await login(username, newPassword), newPassword);
207
+ } else if (step === "enrol") {
208
+ if (!setup) {
209
+ await startEnrolment(password);
210
+ return;
211
+ }
212
+ const confirmed = await mfaEnrollConfirm(username, password, setup.secret, code);
213
+ if (confirmed.ok === false) {
214
+ setError(confirmed.message);
215
+ return;
216
+ }
217
+ // The server has minted a cookie, but this component does NOT open the
218
+ // frame yet. C12 requires the person to save this one clear response.
219
+ setIssued({ user: confirmed.user, recoveryCodes: confirmed.recoveryCodes });
220
+ setSetup(null);
221
+ setPassword("");
222
+ setCode("");
223
+ setStep("codes");
224
+ } else {
225
+ await accept(await login(username, password, step === "mfa" ? code : undefined), password);
226
+ }
227
+ } finally {
228
+ flight.current = false;
229
+ setBusy(false);
230
  }
231
+ }
232
+
233
+ function back() {
234
+ if (flight.current || step === "codes") return;
235
+ setStep("credentials");
236
  setPassword("");
237
+ setNewPassword("");
238
+ setConfirmPassword("");
239
+ setCode("");
240
+ setSetup(null);
241
+ setIssued(null);
242
+ setReveal(false);
243
+ setError("");
244
  }
245
 
246
  // An error that survives the correction is an error that reads as sticky.
 
272
  ⚠ No dash of any kind (R6). A slogan is exactly where an em dash wants to appear. */}
273
  <p className="login-tagline">Every workflow, automated.</p>
274
 
275
+ {/* One card and one anchor across all five steps. The extra content
276
+ grows downward; no alternate width, position or brand lockup. */}
277
+ {step !== "credentials" ? (
278
+ <h2 className="login-mfa-heading" ref={stepHeading} tabIndex={-1}>
279
+ {step === "expired" ? "New password" : step === "mfa" ? "Two step sign in"
280
+ : step === "enrol" ? "Authenticator setup" : "Recovery codes"}
281
+ </h2>
282
+ ) : null}
283
  <form className="login-form" onSubmit={submit} noValidate>
284
+ {step === "credentials" ? (
285
+ <>
286
+ {/* Labels are present and hidden, not absent. `gate()` collapses them
287
+ because Streamlit gives no other way to get a placeholder-only
288
+ field; here the label exists for assistive tech and the visual is
289
+ identical. */}
290
+ {/* No autoFocus: the other door cannot autofocus (Streamlit), and the
291
+ focus ring it would paint on load reads as a highlighted error on
292
+ an untouched form. */}
293
+ <label className="lp-sr-only" htmlFor="login-username">Username</label>
294
+ <input
295
+ id="login-username"
296
+ className="login-input"
297
+ name="username"
298
+ type="text"
299
+ autoComplete="username"
300
+ placeholder="Username"
301
+ value={username}
302
+ onChange={edit(setUsername)}
303
+ disabled={busy}
304
+ aria-invalid={error ? true : undefined}
305
+ />
306
+
307
+ <label className="lp-sr-only" htmlFor="login-password">Password</label>
308
+ <div className="login-field">
309
+ <input
310
+ id="login-password"
311
+ className="login-input"
312
+ name="password"
313
+ type={reveal ? "text" : "password"}
314
+ autoComplete="current-password"
315
+ placeholder="Password"
316
+ value={password}
317
+ onChange={edit(setPassword)}
318
+ disabled={busy}
319
+ aria-invalid={error ? true : undefined}
320
+ />
321
+ {/* tabIndex -1: Tab goes Username to Password to Log in; the reveal is
322
+ a mouse affordance, same as the host's. */}
323
+ <button
324
+ type="button"
325
+ className="login-eye"
326
+ aria-label={reveal ? "Hide password" : "Show password"}
327
+ onClick={() => setReveal((v) => !v)}
328
+ disabled={busy}
329
+ tabIndex={-1}
330
+ >
331
+ <EyeIcon off={reveal} />
332
+ </button>
333
+ </div>
334
+ </>
335
+ ) : null}
336
+
337
+ {step === "expired" ? (
338
+ <>
339
+ {policy ? (
340
+ <ul className="login-mfa-policy" aria-label="Password requirements">
341
+ {policy.rules.map((rule) => <li key={rule.rule}>{rule.message}</li>)}
342
+ </ul>
343
+ ) : (
344
+ <p className="login-mfa-help" role="status">
345
+ {policyLoading ? "Loading password requirements…"
346
+ : "Password requirements could not be loaded. Submit a new password to check it."}
347
+ </p>
348
+ )}
349
+ <label className="login-mfa-label" htmlFor="login-new-password">New password</label>
350
+ <input id="login-new-password" className="login-input" type="password" autoComplete="new-password"
351
+ value={newPassword} onChange={edit(setNewPassword)} disabled={busy}
352
+ aria-invalid={error ? true : undefined} aria-describedby="login-message" />
353
+ <label className="login-mfa-label" htmlFor="login-confirm-password">Confirm new password</label>
354
+ <input id="login-confirm-password" className="login-input" type="password" autoComplete="new-password"
355
+ value={confirmPassword} onChange={edit(setConfirmPassword)} disabled={busy}
356
+ aria-invalid={error ? true : undefined} aria-describedby="login-message" />
357
+ </>
358
+ ) : null}
359
+
360
+ {step === "mfa" ? (
361
+ <>
362
+ <label className="login-mfa-label" htmlFor="login-mfa-code">Authenticator code</label>
363
+ {/* No digits-only pattern: the SAME door consumes a formatted
364
+ recovery code. users.new_recovery_codes issues five hex digits,
365
+ a hyphen and five more: 11 characters, not the brief's nine. */}
366
+ <input id="login-mfa-code" className="login-input" type="text" inputMode="numeric"
367
+ autoComplete="one-time-code" maxLength={11} value={code} onChange={edit(setCode)}
368
+ disabled={busy} aria-invalid={error ? true : undefined} aria-describedby="login-mfa-help login-message" />
369
+ <p className="login-mfa-help" id="login-mfa-help">
370
+ Enter the 6 digit code from your authenticator app. A recovery code works here too.
371
+ </p>
372
+ <p className="login-mfa-help">If you have lost both, ask an administrator to reset two step sign in.</p>
373
+ </>
374
+ ) : null}
375
+
376
+ {step === "enrol" ? (
377
+ <>
378
+ {/* Manual setup is deliberate: the pinned dependency set has no
379
+ QR encoder, and T36 adds no dependency or external QR service. */}
380
+ <p className="login-mfa-help">Type this setup code into any authenticator app.</p>
381
+ {setup ? (
382
+ <>
383
+ <span className="login-mfa-label">{setup.issuer} setup code</span>
384
+ <code className="login-mfa-secret">{setup.secret.match(/.{1,4}/g)?.join(" ")}</code>
385
+ <span className="login-mfa-label">Authenticator setup link</span>
386
+ <code className="login-mfa-uri">{setup.otpauthUri}</code>
387
+ <label className="login-mfa-label" htmlFor="login-enrol-code">First authenticator code</label>
388
+ <input id="login-enrol-code" className="login-input" type="text" inputMode="numeric"
389
+ autoComplete="one-time-code" maxLength={6} value={code} onChange={edit(setCode)}
390
+ disabled={busy} aria-invalid={error ? true : undefined} aria-describedby="login-message" />
391
+ </>
392
+ ) : <p className="login-mfa-help">{busy ? "Preparing your setup code…" : "Try setup again to get a code."}</p>}
393
+ </>
394
+ ) : null}
395
+
396
+ {step === "codes" && issued ? (
397
+ <RecoveryCodes codes={issued.recoveryCodes} onError={setError} onSaved={() => {
398
+ const user = issued.user;
399
+ setIssued(null);
400
+ onSignedIn(user);
401
+ }} />
402
+ ) : null}
403
 
404
  {/* Disabled through THREE channels (the real attribute, the cursor and
405
  the opacity), never opacity alone — a control that only looks dead
406
  is a control that still takes the click. */}
407
+ {step !== "codes" ? (
408
+ <button className="login-submit" type="submit" disabled={busy}>
409
+ {busy ? (step === "expired" ? "Updating password…" : step === "enrol" ? "Setting up…" : "Signing in…")
410
+ : step === "expired" ? "Set new password" : step === "enrol" ? (setup ? "Confirm setup" : "Try setup again")
411
+ : step === "mfa" ? "Verify and sign in" : "Log in"}
412
+ </button>
413
+ ) : null}
414
+ {step !== "credentials" && step !== "codes" ? (
415
+ <button type="button" className="login-mfa-quiet login-mfa-back" disabled={busy} onClick={back}>
416
+ Back to sign in
417
+ </button>
418
+ ) : null}
419
  </form>
420
 
421
  {/* The message line is ALWAYS in the layout (min-height: 1lh) so an
422
  arriving error does not shove the card. `role="status"` rather than
423
  "alert": polite announcement, no interruption. */}
424
+ <p className="login-msg" id="login-message" role="status" aria-live="polite">
425
  {error}
426
  </p>
427
  </div>