fsanyoto commited on
Commit
dcd43e2
·
verified ·
1 Parent(s): e58541f

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 -435
  2. VERSION +1 -1
  3. api/automation_engine.py +68 -0
  4. api/connectors_amazon.py +132 -1
  5. api/main.py +161 -1
  6. api/routes_connectors.py +47 -5
  7. api/routes_customers.py +20 -4
  8. api/routes_dependents.py +19 -0
  9. api/routes_grid.py +197 -22
  10. api/routes_keychain.py +8 -0
  11. api/routes_nav.py +67 -7
  12. api/routes_odoo_tables.py +247 -292
  13. api/routes_products.py +19 -2
  14. api/routes_sheet.py +421 -60
  15. api/routes_starred.py +11 -9
  16. api/routes_tables.py +96 -56
  17. platform/core/connector_sync.py +74 -0
  18. platform/core/dependents.py +233 -40
  19. platform/core/measure_resolve.py +4 -2
  20. platform/core/perm_scope.py +17 -4
  21. platform/core/relations.py +19 -0
  22. platform/core/sheet_templates.py +164 -2
  23. platform/core/sheets.py +173 -24
  24. platform/core/user_tables.py +8 -5
  25. platform/harness/amazon_client.py +73 -1
  26. platform/harness/amazon_store.py +430 -21
  27. platform/harness/measure_filter.py +7 -2
  28. platform/harness/runtime.py +2 -0
  29. platform/harness/semantic.py +32 -8
  30. platform/harness/windows.py +87 -0
  31. platform/modules/product_data.py +63 -0
  32. platform/modules/sheet.py +350 -39
  33. web/src/automation/AutomationSurface.tsx +24 -23
  34. web/src/automation/automationApi.ts +23 -0
  35. web/src/connectors/ConnectorModal.tsx +24 -11
  36. web/src/connectors/DatabasesTab.tsx +392 -24
  37. web/src/customer-grid/ColumnMenu.tsx +80 -9
  38. web/src/customer-grid/CustomerGrid.tsx +177 -59
  39. web/src/customer-grid/MapView.tsx +13 -0
  40. web/src/customer-grid/RecordDetail.tsx +87 -138
  41. web/src/customer-grid/ViewSidebar.tsx +17 -11
  42. web/src/customer-grid/apiBridge.ts +181 -20
  43. web/src/customer-grid/hostBridge.ts +10 -3
  44. web/src/customer-grid/useCustomerData.ts +34 -29
  45. web/src/customer-grid/windows.ts +70 -0
  46. web/src/home/HomePage.tsx +259 -12
  47. web/src/sheet/BindingEditor.tsx +377 -141
  48. web/src/sheet/ChartDialog.tsx +199 -51
  49. web/src/sheet/DrillModal.tsx +44 -5
  50. web/src/sheet/Ribbon.tsx +8 -2
RELEASES.json CHANGED
@@ -1,437 +1,4 @@
1
  {
2
- "current": "40dceba",
3
- "releases": [
4
- {
5
- "version": "v73",
6
- "sha": "bb94de5",
7
- "date": "2026-09-13",
8
- "subject": "release v73"
9
- },
10
- {
11
- "version": "v71",
12
- "sha": "96143dc",
13
- "date": "2026-09-04",
14
- "subject": "release v71 - wave 51, QA'd 24 PASS / 6 FAIL / 5 UNPROVEN"
15
- },
16
- {
17
- "version": "v70",
18
- "sha": "eedfb6a",
19
- "date": "2026-09-03",
20
- "subject": "release v70 - wave 50 (grid analytics, the Sheet as a spreadsheet, view trash and audit)"
21
- },
22
- {
23
- "version": "v69",
24
- "sha": "8598f56",
25
- "date": "2026-09-02",
26
- "subject": "release v69: wave48-continuation validated + hotfixes v67/v68/d4e3e31 + go-live QA repairs (Supplier option limit, optio"
27
- },
28
- {
29
- "version": "v68",
30
- "sha": "62b065a",
31
- "date": "2026-09-01",
32
- "subject": "release v68: unified holiday date offsets"
33
- },
34
- {
35
- "version": "v67",
36
- "sha": "3b22419",
37
- "date": "2026-09-01",
38
- "subject": "release v67"
39
- },
40
- {
41
- "version": "v66",
42
- "sha": "73c94f0",
43
- "date": "2026-08-31",
44
- "subject": "release v66"
45
- },
46
- {
47
- "version": "v65",
48
- "sha": "9f6cfed",
49
- "date": "2026-08-31",
50
- "subject": "release v65"
51
- },
52
- {
53
- "version": "v64",
54
- "sha": "bb8985c",
55
- "date": "2026-08-31",
56
- "subject": "release v64"
57
- },
58
- {
59
- "version": "v63",
60
- "sha": "ec75cb8",
61
- "date": "2026-08-31",
62
- "subject": "release v63"
63
- },
64
- {
65
- "version": "v62",
66
- "sha": "2c8f702",
67
- "date": "2026-08-31",
68
- "subject": "release v62"
69
- },
70
- {
71
- "version": "v61",
72
- "sha": "bbc4c07",
73
- "date": "2026-08-30",
74
- "subject": "v61 - wave 46 hotfix: D-590 schema overlay reaches the grid read (all three assemblies), D-599 route to zone association"
75
- },
76
- {
77
- "version": "v60",
78
- "sha": "dd1b062",
79
- "date": "2026-08-30",
80
- "subject": "v60 - wave 46"
81
- },
82
- {
83
- "version": "v59",
84
- "sha": "3cb73ce",
85
- "date": "2026-08-29",
86
- "subject": "release v59"
87
- },
88
- {
89
- "version": "v58",
90
- "sha": "c526ced",
91
- "date": "2026-08-29",
92
- "subject": "release v58"
93
- },
94
- {
95
- "version": "v57",
96
- "sha": "4859c03",
97
- "date": "2026-08-29",
98
- "subject": "release v57"
99
- },
100
- {
101
- "version": "v56",
102
- "sha": "2970b72",
103
- "date": "2026-08-28",
104
- "subject": "release v56"
105
- },
106
- {
107
- "version": "v55",
108
- "sha": "b766b90",
109
- "date": "2026-08-28",
110
- "subject": "release v55"
111
- },
112
- {
113
- "version": "v54",
114
- "sha": "6a8e99a",
115
- "date": "2026-08-27",
116
- "subject": "release v54"
117
- },
118
- {
119
- "version": "v53",
120
- "sha": "89ed2cb",
121
- "date": "2026-08-24",
122
- "subject": "release v53"
123
- },
124
- {
125
- "version": "v52",
126
- "sha": "8263493",
127
- "date": "2026-08-23",
128
- "subject": "release v52"
129
- },
130
- {
131
- "version": "v51",
132
- "sha": "5740d20",
133
- "date": "2026-08-23",
134
- "subject": "release v51"
135
- },
136
- {
137
- "version": "v50",
138
- "sha": "8027c83",
139
- "date": "2026-08-23",
140
- "subject": "release v50"
141
- },
142
- {
143
- "version": "v49",
144
- "sha": "9a14c01",
145
- "date": "2026-08-23",
146
- "subject": "release v49"
147
- },
148
- {
149
- "version": "v48",
150
- "sha": "3c69fd9",
151
- "date": "2026-08-23",
152
- "subject": "release v48"
153
- },
154
- {
155
- "version": "v47",
156
- "sha": "917f9a0",
157
- "date": "2026-08-23",
158
- "subject": "release v47"
159
- },
160
- {
161
- "version": "v46",
162
- "sha": "a8dc531",
163
- "date": "2026-08-23",
164
- "subject": "release v46"
165
- },
166
- {
167
- "version": "v45",
168
- "sha": "0b2b501",
169
- "date": "2026-08-23",
170
- "subject": "release v45"
171
- },
172
- {
173
- "version": "v44",
174
- "sha": "a7877aa",
175
- "date": "2026-08-23",
176
- "subject": "Hotfix: allow renaming the active Map view"
177
- },
178
- {
179
- "version": "v43",
180
- "sha": "e2ba461",
181
- "date": "2026-08-23",
182
- "subject": "release v43"
183
- },
184
- {
185
- "version": "v42",
186
- "sha": "25b885e",
187
- "date": "2026-08-23",
188
- "subject": "release v42"
189
- },
190
- {
191
- "version": "v41",
192
- "sha": "1d6adcc",
193
- "date": "2026-08-22",
194
- "subject": "v41 vertical route navigation"
195
- },
196
- {
197
- "version": "v40",
198
- "sha": "1451837",
199
- "date": "2026-08-22",
200
- "subject": "release v40 route UI correction"
201
- },
202
- {
203
- "version": "v39",
204
- "sha": "a78bdf0",
205
- "date": "2026-08-21",
206
- "subject": "W39 clean stale migration targets"
207
- },
208
- {
209
- "version": "v38",
210
- "sha": "a556631",
211
- "date": "2026-08-21",
212
- "subject": "W39 reversible Live store cutover"
213
- },
214
- {
215
- "version": "v37",
216
- "sha": "1ddd8cf",
217
- "date": "2026-08-21",
218
- "subject": "W39: coalesce derived workspace reads"
219
- },
220
- {
221
- "version": "v36",
222
- "sha": "51db3b7",
223
- "date": "2026-08-21",
224
- "subject": "W39 share-field oid repair"
225
- },
226
- {
227
- "version": "v35",
228
- "sha": "0f64212",
229
- "date": "2026-08-21",
230
- "subject": "W39 visual QA fixture"
231
- },
232
- {
233
- "version": "v34",
234
- "sha": "cb4caa1",
235
- "date": "2026-08-21",
236
- "subject": "W39 Staging PostgreSQL egress controls"
237
- },
238
- {
239
- "version": "v33",
240
- "sha": "2b115e5",
241
- "date": "2026-08-21",
242
- "subject": "W39: stop nonproduction Postgres background egress"
243
- },
244
- {
245
- "version": "v32",
246
- "sha": "b47b27c",
247
- "date": "2026-08-21",
248
- "subject": "W39: repair Staging Postgres projection"
249
- },
250
- {
251
- "version": "v31",
252
- "sha": "8880a49",
253
- "date": "2026-08-21",
254
- "subject": "v31: Wave 39 staging candidate"
255
- },
256
- {
257
- "version": "v30",
258
- "sha": "71776ca",
259
- "date": "2026-08-20",
260
- "subject": "v30: W39-T29 Member-owned View first-share hotfix"
261
- },
262
- {
263
- "version": "v29",
264
- "sha": "55ced50",
265
- "date": "2026-08-18",
266
- "subject": "v29: the build staging has been running since 2026-08-18 (55ced50)."
267
- },
268
- {
269
- "version": "v28",
270
- "sha": "2793e4b",
271
- "date": "2026-08-18",
272
- "subject": "release v28"
273
- },
274
- {
275
- "version": "v27",
276
- "sha": "c05a794",
277
- "date": "2026-08-18",
278
- "subject": "release v27"
279
- },
280
- {
281
- "version": "v25",
282
- "sha": "bc24829",
283
- "date": "2026-08-14",
284
- "subject": "v25 - wave 32's LIVE build (deployed 2026-08-13, bc24829)"
285
- },
286
- {
287
- "version": "v26",
288
- "sha": "6a642e1",
289
- "date": "2026-08-14",
290
- "subject": "v26 - wave 33's build (deployed 2026-08-14, 6a642e1)"
291
- },
292
- {
293
- "version": "v24",
294
- "sha": "514d829",
295
- "date": "2026-08-09",
296
- "subject": "release v24"
297
- },
298
- {
299
- "version": "v23",
300
- "sha": "44cc283",
301
- "date": "2026-08-09",
302
- "subject": "release v23"
303
- },
304
- {
305
- "version": "v22",
306
- "sha": "f14e199",
307
- "date": "2026-08-09",
308
- "subject": "release v22"
309
- },
310
- {
311
- "version": "v21",
312
- "sha": "5fdffce",
313
- "date": "2026-08-09",
314
- "subject": "release v21"
315
- },
316
- {
317
- "version": "v20",
318
- "sha": "442e4a1",
319
- "date": "2026-08-09",
320
- "subject": "release v20"
321
- },
322
- {
323
- "version": "v19",
324
- "sha": "94cb4a4",
325
- "date": "2026-08-09",
326
- "subject": "release v19"
327
- },
328
- {
329
- "version": "v18",
330
- "sha": "0106ef9",
331
- "date": "2026-08-09",
332
- "subject": "release v18"
333
- },
334
- {
335
- "version": "v17",
336
- "sha": "308240c",
337
- "date": "2026-08-09",
338
- "subject": "release v17"
339
- },
340
- {
341
- "version": "v16",
342
- "sha": "a804df5",
343
- "date": "2026-08-09",
344
- "subject": "release v16"
345
- },
346
- {
347
- "version": "v15",
348
- "sha": "6b84d72",
349
- "date": "2026-08-09",
350
- "subject": "release v15"
351
- },
352
- {
353
- "version": "v14",
354
- "sha": "bee5eaf",
355
- "date": "2026-08-07",
356
- "subject": "release v14"
357
- },
358
- {
359
- "version": "v13",
360
- "sha": "314c0e3",
361
- "date": "2026-08-06",
362
- "subject": "release v13"
363
- },
364
- {
365
- "version": "v12",
366
- "sha": "4908f39",
367
- "date": "2026-08-06",
368
- "subject": "release v12"
369
- },
370
- {
371
- "version": "v11",
372
- "sha": "3126617",
373
- "date": "2026-08-05",
374
- "subject": "release v11"
375
- },
376
- {
377
- "version": "v10",
378
- "sha": "43f8042",
379
- "date": "2026-08-05",
380
- "subject": "release v10"
381
- },
382
- {
383
- "version": "v9",
384
- "sha": "2e26f57",
385
- "date": "2026-08-05",
386
- "subject": "release v9"
387
- },
388
- {
389
- "version": "v8",
390
- "sha": "8073b3e",
391
- "date": "2026-08-05",
392
- "subject": "release v8"
393
- },
394
- {
395
- "version": "v7",
396
- "sha": "b1c5a7e",
397
- "date": "2026-08-05",
398
- "subject": "release v7"
399
- },
400
- {
401
- "version": "v6",
402
- "sha": "a344020",
403
- "date": "2026-08-05",
404
- "subject": "release v6"
405
- },
406
- {
407
- "version": "v5",
408
- "sha": "c0b0fbb",
409
- "date": "2026-08-05",
410
- "subject": "release v5"
411
- },
412
- {
413
- "version": "v4",
414
- "sha": "de5037f",
415
- "date": "2026-08-05",
416
- "subject": "release v4"
417
- },
418
- {
419
- "version": "v3",
420
- "sha": "6b9fa62",
421
- "date": "2026-08-05",
422
- "subject": "release v3"
423
- },
424
- {
425
- "version": "v2",
426
- "sha": "fd05861",
427
- "date": "2026-08-04",
428
- "subject": "release v2"
429
- },
430
- {
431
- "version": "v1",
432
- "sha": "5b4e2c4",
433
- "date": "2026-08-04",
434
- "subject": "release v1"
435
- }
436
- ]
437
  }
 
1
  {
2
+ "current": "0eda914",
3
+ "releases": []
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4
  }
VERSION CHANGED
@@ -1 +1 @@
1
- 40dceba
 
1
+ 0eda914
api/automation_engine.py CHANGED
@@ -14553,6 +14553,74 @@ def relation_cells(rt, table_key, tables=None):
14553
  return changes, limits
14554
 
14555
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
14556
  def related_product_metric_values(rt, customer_id, products, fields, offer, *,
14557
  team_id=None, agent=None, today=None):
14558
  """Read-only customer × real product metrics; the caller supplies walled server rows.
 
14553
  return changes, limits
14554
 
14555
 
14556
+ def related_metric_values(rt, table_key, rows, fields, offer, related, *, team_id=None,
14557
+ today=None):
14558
+ """Read-only linked cells at customer, product or declared entity grain.
14559
+
14560
+ The host supplies the same resolved membership as its rows door and its walled catalogue.
14561
+ A request-local memo never survives a parent, account, permission or tenant change.
14562
+ """
14563
+ from core import measure_resolve, relations
14564
+ from harness import semantic as sem, windows
14565
+ import time
14566
+
14567
+ rt.assert_datastore_matches()
14568
+ today = today or time.strftime('%Y-%m-%d')
14569
+ by_key = {m['key']: m for m in offer}
14570
+ out = relations.MeasureAnswer({r['pid']: {f['key']: None for f in fields} for r in rows})
14571
+ memo = {}
14572
+ for field in fields:
14573
+ spec = field.get('measure') or {}
14574
+ key = spec.get('key')
14575
+ if key not in by_key:
14576
+ continue # The host removes unavailable catalogue entries before serialization.
14577
+ try:
14578
+ bounds = windows.resolve(spec.get('window'), today)
14579
+ if bounds is None:
14580
+ raise ValueError('The metric date window cannot be resolved. Choose a valid period.')
14581
+ if table_key == 'customer_data':
14582
+ errors = []
14583
+ values = measure_resolve.column_values(
14584
+ [field], team_id, [r['pid'] for r in rows], today, today, memo,
14585
+ on_error=lambda _where, exc: errors.append(exc), related=related)
14586
+ if errors:
14587
+ raise ValueError('This metric could not be read for the linked record. Try again after the database is ready.')
14588
+ out.refusals.extend(getattr(values, 'refusals', ()))
14589
+ for pid, cells in values.items():
14590
+ out[pid].update(cells)
14591
+ continue
14592
+ topic = sem.topic_for_grid(table_key)
14593
+ cache_key = (topic, key, bounds, team_id)
14594
+ if cache_key not in memo:
14595
+ memo[cache_key] = sem.entity_measure_values(
14596
+ topic, [key], date_from=bounds[0], date_to=bounds[1], team_id=team_id,
14597
+ offer=offer, related=related)
14598
+ values = memo[cache_key]
14599
+ markers = getattr(values, 'refusals', ())
14600
+ if markers:
14601
+ out.refusals.extend(dict(marker, field=field['key']) for marker in markers)
14602
+ continue # Never zero-fill a refused answer or expose its unscoped values.
14603
+ for row in rows:
14604
+ identity = row.get('code') if table_key == 'product_data' else row['pid']
14605
+ if identity in (None, ''):
14606
+ raise ValueError('The metric identity cannot be read for this record.')
14607
+ cell = sem.entity_zero_fill(values.get(identity), [key], offer)
14608
+ out[row['pid']][field['key']] = cell.get(key)
14609
+ except Exception as exc:
14610
+ message = (str(exc) if isinstance(exc, (relations.PinRefusal, sem._EntityMeasureError)) else
14611
+ 'This metric cannot be read for the linked record. Check its period and source binding, then try again.')
14612
+ out.refusals.append(dict(code='metric_scope_unavailable', message=message,
14613
+ path=related.path, field=field['key'], scoped=False))
14614
+ # Customer resolvers deliberately retain diagnostics even when their low-level pin refuses.
14615
+ for marker in out.refusals:
14616
+ marker['message'] = marker['message'].replace('Values are unscoped.', 'Values are unavailable.').replace(
14617
+ 'Metric values are unscoped.', 'Metric values are unavailable.')
14618
+ for cells in out.values():
14619
+ if marker.get('field') in cells:
14620
+ cells[marker['field']] = None
14621
+ return out
14622
+
14623
+
14624
  def related_product_metric_values(rt, customer_id, products, fields, offer, *,
14625
  team_id=None, agent=None, today=None):
14626
  """Read-only customer × real product metrics; the caller supplies walled server rows.
api/connectors_amazon.py CHANGED
@@ -94,6 +94,137 @@ def assert_safe_status(payload):
94
  return payload
95
 
96
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
97
  #: W55-T19 / R7 / C10 — AMAZON'S OWN ENABLEMENT DOCUMENT. This is deliberately not Odoo's
98
  #: model catalogue or connector config: Amazon publishes report schemas, not ``fields_get``, and
99
  #: its seven databases are enabled at the provider boundary rather than masquerading as Odoo
@@ -340,7 +471,7 @@ def main(argv):
340
  return 1
341
  print("\nreport types this connector will pull (owner ruling R4):")
342
  for table, spec in REPORT_TYPES.items():
343
- rep = spec.get("report") or "NO CONFIRMED REPORT FLAVOR (see O5)"
344
  print(f" {table:<16} {rep}")
345
 
346
  if "--probe-report" in argv:
 
94
  return payload
95
 
96
 
97
+ def first_load_status(tenant_key, rt=None):
98
+ """Writer-side progress helper; request status uses sync_state's read-only cursor."""
99
+ from harness import amazon_store
100
+ return assert_safe_status(amazon_store.first_load_status(tenant_key, rt=rt))
101
+
102
+
103
+ def sync_state(rt, tenant_key, *, cadence_seconds=None, now=None):
104
+ """Each Amazon table's sync state, or None when this mirror cannot be read.
105
+
106
+ Read only: never _connect_tenant_mirror or first_load_status, which issue DDL.
107
+ Missing bookkeeping is unknown, not a measured zero. First-load numbers describe the
108
+ whole connection, because that is the scope of the producer's durable progress marker.
109
+ """
110
+ import json
111
+ from datetime import datetime, timezone
112
+ import duckdb
113
+ from harness import amazon_store as az
114
+ from routes_odoo_tables import _sync_entities, stuck_verdict
115
+
116
+ def stamp(value):
117
+ if not value:
118
+ return None
119
+ try:
120
+ parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
121
+ return (parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)).astimezone(timezone.utc)
122
+ except (ValueError, TypeError, OverflowError):
123
+ return None
124
+
125
+ def iso(value):
126
+ return value.isoformat().replace("+00:00", "Z") if value else None
127
+
128
+ cadence = cadence_seconds if cadence_seconds is not None else 1800
129
+ try:
130
+ path = az._tenant_mirror_path(tenant_key, rt=rt)
131
+ if not path.is_file():
132
+ return assert_safe_status(None)
133
+ # ⛔⛔ A SECOND `duckdb.connect(read_only=True)` ON A FILE THIS PROCESS ALREADY HOLDS RAISES
134
+ # `ConnectionException: Can't open a connection to same database file with a different
135
+ # configuration`. On the DEFAULT tenant layout the Amazon mirror IS the process-global
136
+ # analytical mirror (`datastore.DB_PATH`), so the swallowed refusal below turned this whole
137
+ # screen into a permanent "sync status is unknown" on exactly the deployment the ticket is
138
+ # for. Measured on staging 2026-09-14, W60-T35. `datastore.ro_con()` is the shipped
139
+ # per-thread READ cursor on that same instance, and it takes no lock against the writer.
140
+ from harness import datastore as _ds
141
+ if path.resolve() == _ds.DB_PATH.resolve():
142
+ # `ro_cursor()` is a cursor on the instance this process ALREADY holds: no second
143
+ # connection, no lock contention with the writer, and no DDL. Deliberately NOT
144
+ # `ro_con()`, which refuses until `ready()` and would report the whole screen as
145
+ # unknown whenever the Odoo backfill is mid-flight, and NOT `datastore.connect()`,
146
+ # which issues `CREATE TABLE IF NOT EXISTS`.
147
+ entities = _sync_entities(_ds.ro_cursor(), cadence)
148
+ else:
149
+ with duckdb.connect(str(path), read_only=True) as cur:
150
+ entities = _sync_entities(cur, cadence)
151
+ except Exception: # noqa: BLE001
152
+ # No exception text: paths, provider payloads and credentials never become status copy.
153
+ return assert_safe_status(None)
154
+ if entities is None:
155
+ return assert_safe_status(None)
156
+
157
+ clock = stamp(now) if now is not None else datetime.now(timezone.utc)
158
+ states, bad_ticks = {}, set()
159
+ for table in az.TABLES:
160
+ tick = entities.get(az.entity_key("sync_tick_" + table))
161
+ if tick:
162
+ updated = stamp(tick.get("updatedAt"))
163
+ if updated is None or tick.get("phase") not in ("attempted", "done", "running"):
164
+ bad_ticks.add(table)
165
+ else:
166
+ states[table] = {"state": tick["phase"], "updated_at": iso(updated)}
167
+ # An unreadable input cannot support a cadence promise for any table in the rotation.
168
+ plan = az.sync_plan(states, now=clock) if not bad_ticks and clock is not None else None
169
+ first_load, load_unknown = None, ""
170
+ load = entities.get(az.entity_key(az.FIRST_LOAD_STATUS_KEY))
171
+ if load:
172
+ try:
173
+ progress = json.loads(load.get("cursor") or "")
174
+ remaining, eta = progress["remaining"], progress["etaSeconds"]
175
+ if (type(remaining) is not int or not 0 <= remaining <= 2**53 - 1
176
+ or type(eta) is not int or not 0 <= eta <= 2**53 - 1
177
+ or (load.get("phase") == "done" and remaining > 0)):
178
+ raise ValueError("Invalid first-load progress")
179
+ if remaining > 0:
180
+ first_load = {"remaining": remaining, "etaSeconds": eta,
181
+ "cause": az.first_load_eta_cause(remaining),
182
+ "needsAttention": load.get("phase") == "failed"}
183
+ except (ValueError, TypeError, KeyError, OverflowError, RecursionError):
184
+ load_unknown = "First-load progress is unknown because its saved marker could not be read. Retry sync to refresh it."
185
+ elif (entities.get(az.entity_key(az.FIRST_LOAD_END_KEY)) or {}).get("phase") not in (None, "done"):
186
+ load_unknown = "First-load progress is not available yet. Keep the connection enabled and check again after this pass."
187
+
188
+ answer = {}
189
+ for table in az.TABLES:
190
+ landed = entities.get(az.entity_key(table)) or {}
191
+ tick = entities.get(az.entity_key("sync_tick_" + table)) or {}
192
+ watermark = entities.get(az.entity_key(az.WATERMARK_PREFIX + table)) or {}
193
+ rows = landed.get("rows")
194
+ if type(rows) is not int or rows < 0:
195
+ rows = None
196
+ successes = [when for marker in (landed, tick, watermark)
197
+ if marker.get("phase") == "done"
198
+ and (when := stamp(marker.get("updatedAt"))) is not None]
199
+ stuck, stuck_cause = tick.get("stuck"), tick.get("stuckCause") or ""
200
+ if tick.get("phase") == "attempted":
201
+ # The shared stall helper calls an active phase 'running'; Amazon calls it 'attempted'.
202
+ updated = stamp(tick.get("updatedAt"))
203
+ stuck, stuck_cause = stuck_verdict(
204
+ "running", iso(updated), cadence,
205
+ now=clock.replace(tzinfo=None) if clock else None)
206
+ reason = plan["deferred"].get(table) if plan else None
207
+ # Only the planner's explicit due stamp is a due date. Minimum stagger spacing is not
208
+ # a promise about when a later resident tick will select this table.
209
+ next_due = stamp(reason.partition("next due ")[2]) if reason else None
210
+ unknown = [load_unknown] if load_unknown else []
211
+ if rows is None:
212
+ unknown.append("This container has no readable row count for this table.")
213
+ if plan is None:
214
+ unknown.append("The sync schedule is unknown because a saved timestamp could not be read. Retry sync to refresh it.")
215
+ answer[table] = {
216
+ "rowsLoaded": rows,
217
+ "lastSuccess": iso(max(successes)) if successes else None,
218
+ "inProgress": tick.get("phase") == "attempted" and stuck is False,
219
+ "deferred": {"reason": reason} if reason else None,
220
+ "nextDue": iso(next_due),
221
+ "firstLoad": first_load,
222
+ "stuck": stuck, "stuckCause": stuck_cause,
223
+ "unknownCause": " ".join(unknown),
224
+ }
225
+ return assert_safe_status(answer)
226
+
227
+
228
  #: W55-T19 / R7 / C10 — AMAZON'S OWN ENABLEMENT DOCUMENT. This is deliberately not Odoo's
229
  #: model catalogue or connector config: Amazon publishes report schemas, not ``fields_get``, and
230
  #: its seven databases are enabled at the provider boundary rather than masquerading as Odoo
 
471
  return 1
472
  print("\nreport types this connector will pull (owner ruling R4):")
473
  for table, spec in REPORT_TYPES.items():
474
+ rep = spec.get("report") or spec.get("report_discover") or "NO CONFIRMED REPORT FLAVOR (see O5)"
475
  print(f" {table:<16} {rep}")
476
 
477
  if "--probe-report" in argv:
api/main.py CHANGED
@@ -766,6 +766,158 @@ def _pull_amazon(why):
766
  return False
767
 
768
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
769
  def _rebuild_meta_relational(why, rt, previous_fingerprint=None, force_relations=False):
770
  """Spawn/refresh the `ut_meta_*` locked databases off the SAME mirror the Odoo half just used.
771
 
@@ -1320,6 +1472,7 @@ def _store_resync_loop():
1320
  Streamlit app piggybacks on page renders. Measure memos key on the pool stamp, so a
1321
  refreshed pool re-reads the freshly synced store."""
1322
  import time as _t
 
1323
  passes = 0
1324
  last_relational_success_at = None
1325
  last_meta_fingerprint = None
@@ -1388,10 +1541,13 @@ def _store_resync_loop():
1388
  # stored fields such as customer_rank can change without partner write_date advancing,
1389
  # so staging served a provably stale customer population for its first hour. Subsequent
1390
  # passes still sleep at the freshly resolved cadence, and manual still skips only Odoo.
 
1391
  if passes:
1392
- _t.sleep(_every)
 
1393
  passes += 1
1394
  RESYNC_STATE["passes"] = passes
 
1395
  sync_report, delete_report, _err = _resync_mirror_pass(_manual, passes)
1396
  RESYNC_STATE["lastPassAt"] = _t.strftime("%Y-%m-%dT%H:%M:%SZ", _t.gmtime())
1397
  RESYNC_STATE["lastPassOk"] = _err is None
@@ -1444,6 +1600,10 @@ def _store_resync_loop():
1444
  _amzn_previous = last_amzn_fingerprint if _meta_reason is None else None
1445
  _reason = _resync_rebuild_reason(sync_report, delete_report,
1446
  last_relational_success_at, _meta_now)
 
 
 
 
1447
  _meta_state = {}
1448
  if _reason is not None:
1449
  print(f"[aios-api] odoo relational rebuild required ({_reason})")
 
766
  return False
767
 
768
 
769
+ class _SyncNowRefused(Exception):
770
+ """An application-authored, credential-free sentence for a Sync now receipt."""
771
+
772
+
773
+ def _sync_now_failure(cause):
774
+ """Classify actual provider failures without returning vendor text or exception reprs."""
775
+ import re
776
+ text = str(cause).lower()
777
+ causes = (
778
+ (("reduce the amount of data", "response too large"),
779
+ "The provider refused the pull because the response contains too much data."),
780
+ (("no ad accounts",), "The Meta token cannot access any ad accounts."),
781
+ (("max_pages", "page cap"), "The pull stopped at the provider page limit."),
782
+ (("sandbox",), "Amazon sync requires a production credential; this credential is for the sandbox."),
783
+ (("deletion", "retention"), "Amazon sync is blocked by an outstanding data deletion requirement."),
784
+ (("no stored", "no odoo credentials", "access_token is not set"),
785
+ "This tenant has no usable credential for the connector."),
786
+ (("enablement document", "capability unavailable"),
787
+ "The connector database settings could not be read."),
788
+ (("throttl", "rate limit", "too many requests"),
789
+ "The provider rate limit stopped the sync. Retry after the provider delay."),
790
+ (("timed out", "timeout"), "The sync failed because the provider request timed out."),
791
+ (("permission", "access denied", "unauthorized", "invalid oauth", "invalid token",
792
+ "expired", "authentication"), "The provider refused the connector credential or its permissions."),
793
+ (("duplicate key", "primary key", "constraint"),
794
+ "The mirror rejected rows because they violate a database constraint."),
795
+ (("connection", "network", "name resolution"),
796
+ "The sync could not connect to the provider or tenant database."),
797
+ # A-META / D-201: a Meta pull on a container whose mirror never held `meta_*` raises
798
+ # DuckDB's CatalogException. Standing rule 1 wants the CAUSE, not "unexpected error":
799
+ # "the loader is broken" and "this server has never held these tables" are different
800
+ # operator actions, and only the second one is true here.
801
+ (("does not exist", "no such table", "catalog error"),
802
+ "This server's mirror does not hold this connector's tables yet, so there was nothing "
803
+ "to update. Run the connector's first load on the server that owns this tenant."),
804
+ )
805
+ for needles, sentence in causes:
806
+ if any(needle in text for needle in needles):
807
+ return sentence
808
+ status = re.search(r"\bhttp\s+(\d{3})\b", text)
809
+ if status:
810
+ return f"The provider refused the sync request with HTTP status {status.group(1)}."
811
+ if isinstance(cause, TypeError):
812
+ return "The connector failed because its provider call used incompatible arguments."
813
+ if isinstance(cause, (KeyError, ValueError)):
814
+ return "The connector could not read an expected value in the sync response."
815
+ return "The connector encountered an unexpected error while processing the sync response."
816
+
817
+
818
+ def _run_sync_requests():
819
+ """Drain Sync now intents on the resident resync thread, the mirror's single writer.
820
+
821
+ D-29 / intake F6: HTTP handlers only queue intents. Provider calls stay here, before the
822
+ resident projection pass. A failed request cannot discard another tenant's queued work.
823
+ """
824
+ from core import connector_sync
825
+ odoo_requested = False
826
+ for receipt in connector_sync.take_sync_requests():
827
+ provider, tenant = receipt["provider"], receipt["tenant"]
828
+ ok, detail = False, ""
829
+ first_load_progress, continuing = None, False
830
+ try:
831
+ from harness import runtime, datastore
832
+ rt = runtime.get_runtime(tenant)
833
+ if rt.key != tenant:
834
+ raise _SyncNowRefused("The sync runtime does not match the requesting tenant.")
835
+ # These two loaders use a process-global mirror. Never repoint it under readers.
836
+ # Amazon's writer opens an explicit tenant file and does not need this restriction.
837
+ if provider in ("odoo", "meta_ads") and (
838
+ rt.datastore_path.resolve() != datastore.DB_PATH.resolve() or
839
+ datastore.path_for(tenant).resolve() != datastore.DB_PATH.resolve()):
840
+ raise _SyncNowRefused(
841
+ "This tenant's mirror is not resident on this server. Sync requires its tenant worker.")
842
+ if provider == "odoo":
843
+ import core.odoo as odoo
844
+ import odoo_relational as rel
845
+ if rt.odoo_paused() or rel.frozen(rt):
846
+ raise _SyncNowRefused("Odoo is paused or disconnected. Resume the connection before syncing.")
847
+ source = rt.odoo_source()
848
+ if source is None:
849
+ raise _SyncNowRefused("This tenant has no Odoo credential. Connect Odoo before syncing.")
850
+ odoo_requested = True
851
+ previous_client = getattr(odoo._tlocal, "client", None)
852
+ previous_context = getattr(odoo._tlocal, "tenant_ctx", None)
853
+ try:
854
+ # Raw mirror pulls use the resolved tenant credential and a dedicated
855
+ # transport. Do not borrow a request's cached XML-RPC client.
856
+ odoo._tlocal.client = odoo.OdooClient(creds=source._creds)
857
+ odoo._tlocal.tenant_ctx = None
858
+ report = datastore.sync_all(log=lambda *a, **k: None)
859
+ finally:
860
+ odoo._tlocal.client = previous_client
861
+ odoo._tlocal.tenant_ctx = previous_context
862
+ if not report:
863
+ raise _SyncNowRefused("Odoo did not run a sync. Check whether the connection is paused.")
864
+ if any(row.get("phase") != "live" for row in report.values()):
865
+ raise _SyncNowRefused("Odoo backfill is incomplete. Run Sync now again to continue it.")
866
+ problems = []
867
+ elif provider == "amazon_sp":
868
+ from harness import amazon_store as amazon
869
+ if not amazon.credential(tenant, rt=rt):
870
+ raise _SyncNowRefused("This tenant has no stored Amazon credential. Connect Amazon before syncing.")
871
+ first_load = amazon.needs_first_load(tenant, rt=rt)
872
+ options = {"first_load": True, "report_budget": amazon.FIRST_LOAD_REPORTS_PER_PASS} if first_load else {}
873
+ report = amazon.sync(tenant, rt=rt, scheduled=False, **options, log=lambda *a, **k: None)
874
+ from connectors_amazon import assert_safe_status
875
+ first_load_progress = assert_safe_status(report.get("firstLoad"))
876
+ continuing = report.get("state") == "partial"
877
+ problems = list(report.get("problems") or []) + list(report.get("audit_problems") or [])
878
+ tables = report.get("tables") or {}
879
+ if not problems and not tables and not continuing:
880
+ raise _SyncNowRefused("Amazon returned no table results, so the sync could not be confirmed.")
881
+ if not problems and not continuing and all(row.get("state") == "disabled" for row in tables.values()):
882
+ raise _SyncNowRefused("All Amazon databases are disabled. Enable a database before syncing.")
883
+ elif provider == "meta_ads":
884
+ from harness import meta_store as meta
885
+ if not meta.token(rt):
886
+ raise _SyncNowRefused("Meta Ads has no access token. Connect Meta Ads before syncing.")
887
+ report = meta.sync(tenant, log=lambda *a, **k: None, insights_days=7)
888
+ problems = list(report.get("problems") or [])
889
+ if any(row.get("capped") for row in (report.get("tables") or {}).values()):
890
+ problems.append("The pull hit the page cap.")
891
+ if not problems and not report.get("tables"):
892
+ raise _SyncNowRefused("Meta Ads returned no table results, so the sync could not be confirmed.")
893
+ else:
894
+ raise _SyncNowRefused("This connector has no Sync now runner.")
895
+ if continuing:
896
+ ok = True
897
+ detail = (f"The first load is continuing. {int(report['remaining'])} windows remain; "
898
+ f"Amazon report pacing needs at least {int(report['etaSeconds'])} seconds.")
899
+ if problems:
900
+ detail += " " + _sync_now_failure(problems[0])
901
+ elif problems:
902
+ detail = _sync_now_failure(problems[0])
903
+ else:
904
+ ok, detail = True, "Sync finished."
905
+ except _SyncNowRefused as exc:
906
+ detail = str(exc)
907
+ except Exception as exc: # noqa: BLE001
908
+ detail = _sync_now_failure(exc)
909
+ if first_load_progress is not None:
910
+ connector_sync.finish_sync_request(provider, tenant, ok=ok, detail=detail,
911
+ first_load=first_load_progress)
912
+ else:
913
+ connector_sync.finish_sync_request(provider, tenant, ok=ok, detail=detail)
914
+ if continuing and ok:
915
+ # Finish first: the desk refuses a second in-flight intent. Return to the resident
916
+ # loop so its Odoo mirror pass runs before this continuation is claimed.
917
+ connector_sync.request_sync("amazon_sp", tenant, requested_by="first load")
918
+ return odoo_requested
919
+
920
+
921
  def _rebuild_meta_relational(why, rt, previous_fingerprint=None, force_relations=False):
922
  """Spawn/refresh the `ut_meta_*` locked databases off the SAME mirror the Odoo half just used.
923
 
 
1472
  Streamlit app piggybacks on page renders. Measure memos key on the pool stamp, so a
1473
  refreshed pool re-reads the freshly synced store."""
1474
  import time as _t
1475
+ from core import connector_sync
1476
  passes = 0
1477
  last_relational_success_at = None
1478
  last_meta_fingerprint = None
 
1541
  # stored fields such as customer_rank can change without partner write_date advancing,
1542
  # so staging served a provably stale customer population for its first hour. Subsequent
1543
  # passes still sleep at the freshly resolved cadence, and manual still skips only Odoo.
1544
+ # The wait is now interruptible so an administrator's Sync now wakes this writer.
1545
  if passes:
1546
+ connector_sync.sync_wake_event().wait(_every)
1547
+ connector_sync.sync_wake_event().clear()
1548
  passes += 1
1549
  RESYNC_STATE["passes"] = passes
1550
+ _odoo_requested = _run_sync_requests()
1551
  sync_report, delete_report, _err = _resync_mirror_pass(_manual, passes)
1552
  RESYNC_STATE["lastPassAt"] = _t.strftime("%Y-%m-%dT%H:%M:%SZ", _t.gmtime())
1553
  RESYNC_STATE["lastPassOk"] = _err is None
 
1600
  _amzn_previous = last_amzn_fingerprint if _meta_reason is None else None
1601
  _reason = _resync_rebuild_reason(sync_report, delete_report,
1602
  last_relational_success_at, _meta_now)
1603
+ # The scheduled pass may now be quiet because Sync now just advanced this mirror.
1604
+ # Its zero-change report cannot suppress projection of the explicit Odoo pull.
1605
+ if _odoo_requested:
1606
+ _reason = "sync now"
1607
  _meta_state = {}
1608
  if _reason is not None:
1609
  print(f"[aios-api] odoo relational rebuild required ({_reason})")
api/routes_connectors.py CHANGED
@@ -1575,6 +1575,30 @@ def connector_sync_status(connector_key: str, connection_id: str = None,
1575
  return _sync_payload(connector_key, connection_id, row)
1576
 
1577
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1578
  @router.post("/connectors/{connector_key}/sync/retry")
1579
  def connector_sync_retry(connector_key: str, connection_id: str = None,
1580
  session: Session = Depends(require_session), database_key: str = None):
@@ -2578,11 +2602,25 @@ def _detail_databases(rt, is_admin, connector_key, uname="", connection_id=None)
2578
  return _named_databases(rt, is_admin, uname, out)
2579
 
2580
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2581
  def _amazon_databases(rt, is_admin, spec=None):
2582
  """⭐⭐ W52 · R6 — THE SEVEN AMAZON DATABASES, DISCLOSED WITH WHERE EACH COLUMN CAME FROM.
2583
 
2584
- Fills the SAME `ConnectorDatabase` shape Odoo does, so the Databases tab needs no client
2585
- change: `key`, `label`, `enabled`, `fields`, `excluded`, `sharesFieldsWith`.
2586
 
2587
  ⛔⛔ **`excluded` CARRIES THE PROVENANCE, AND THAT IS THE WHOLE POINT OF THE SCREEN HERE.** Five
2588
  of the seven tables have NO published schema, because Amazon publishes artifacts only for its
@@ -2611,12 +2649,13 @@ def _amazon_databases(rt, is_admin, spec=None):
2611
  enabled = enablement.get("databases") or {}
2612
  cat = amazon_schema.catalogue()
2613
  tables = cat.get("tables") or {}
 
2614
 
2615
  # Which OTHER declared tables are filled from the SAME report document. Derived from the
2616
  # report map so a table added to `REPORT_TYPES` gets this disclosure for free.
2617
  by_report = {}
2618
  for name in amazon_schema.PROVENANCE:
2619
- rep = str((cx.REPORT_TYPES.get(name) or {}).get("report") or "")
2620
  if rep:
2621
  by_report.setdefault(rep, []).append("ut_amzn_" + name)
2622
 
@@ -2625,7 +2664,7 @@ def _amazon_databases(rt, is_admin, spec=None):
2625
  key = "ut_amzn_" + name
2626
  spec = tables.get(name) or {}
2627
  cols = spec.get("columns") or []
2628
- rep = str((cx.REPORT_TYPES.get(name) or {}).get("report") or "")
2629
  fields = [{"key": str(c.get("name") or ""),
2630
  "label": str(c.get("name") or "").replace("_", " ").capitalize(),
2631
  "type": "text" if str(c.get("type")) == "VARCHAR" else "number",
@@ -2656,6 +2695,7 @@ def _amazon_databases(rt, is_admin, spec=None):
2656
  # read from Odoo's grid config, and disabling it leaves every stored row and
2657
  # definition untouched: only this provider config document changes.
2658
  "enabled": enabled.get(key) is True,
 
2659
  "fields": fields,
2660
  "excluded": excluded,
2661
  "sharesFieldsWith": [k for k in by_report.get(rep, ()) if k != key]})
@@ -2876,9 +2916,11 @@ def connector_detail(rt, user, uname, is_admin, connector_key):
2876
  return _safe_connector_status(key, {"overview": overview,
2877
  "keychain": keychain,
2878
  "databases": databases,
 
 
2879
  "materialization": ({"provider": key, "statusPath": f"/connectors/{key}/jobs",
2880
  "retryPath": f"/connectors/{key}/sync/retry"}
2881
- if is_admin and key in connector_sync.providers() else None),
2882
  # W55-T19 / R7 / C10 — a provider-specific capability. The client neither infers it
2883
  # from ``introspectable`` nor sends Amazon through Odoo's schema/config endpoints.
2884
  "enablement": enablement,
 
1575
  return _sync_payload(connector_key, connection_id, row)
1576
 
1577
 
1578
+ @router.post("/connectors/{connector_key}/sync/now")
1579
+ def connector_sync_now(connector_key: str, session: Session = Depends(require_session)):
1580
+ _sync_admin(session)
1581
+ if connector_key not in connector_sync.providers():
1582
+ raise err(404, "sync_provider_unknown", "This connector is not registered for sync.")
1583
+ try:
1584
+ return connector_sync.request_sync(connector_key, session.runtime.key,
1585
+ requested_by=session.uname)
1586
+ except ValueError:
1587
+ raise err(404, "sync_provider_unknown", "This connector is not registered for sync.") from None
1588
+
1589
+
1590
+ @router.get("/connectors/{connector_key}/sync/now")
1591
+ def connector_sync_now_status(connector_key: str, session: Session = Depends(require_session)):
1592
+ _sync_admin(session)
1593
+ if connector_key not in connector_sync.providers():
1594
+ raise err(404, "sync_provider_unknown", "This connector is not registered for sync.")
1595
+ return connector_sync.sync_request(connector_key, session.runtime.key) or {
1596
+ "provider": connector_key, "tenant": session.runtime.key, "state": "idle",
1597
+ "requestedAt": None, "startedAt": None, "finishedAt": None,
1598
+ "requestedBy": "", "detail": "", "accepted": False,
1599
+ }
1600
+
1601
+
1602
  @router.post("/connectors/{connector_key}/sync/retry")
1603
  def connector_sync_retry(connector_key: str, connection_id: str = None,
1604
  session: Session = Depends(require_session), database_key: str = None):
 
2602
  return _named_databases(rt, is_admin, uname, out)
2603
 
2604
 
2605
+ def _amazon_report_name(table):
2606
+ """The report type this Amazon table reads, whichever key declares it.
2607
+
2608
+ ⛔ SETTLEMENTS DECLARE `report_discover`, NOT `report` (W60-T36), because Amazon issues them on
2609
+ its own schedule and refuses a createReport for that type: it is a getReports DISCOVERY filter
2610
+ and is deliberately absent from `_APPROVED_REPORT_TYPES`. Reading only `report` here printed an
2611
+ empty Source name for settlements on the connector screen, which reads as "this table has no
2612
+ report" when the truth is "this table is not requested, it is listed".
2613
+ """
2614
+ import connectors_amazon as cx # noqa: PLC0415 - provider owns state
2615
+ spec = cx.REPORT_TYPES.get(table) or {}
2616
+ return str(spec.get("report") or spec.get("report_discover") or "")
2617
+
2618
+
2619
  def _amazon_databases(rt, is_admin, spec=None):
2620
  """⭐⭐ W52 · R6 — THE SEVEN AMAZON DATABASES, DISCLOSED WITH WHERE EACH COLUMN CAME FROM.
2621
 
2622
+ Fills the shared `ConnectorDatabase` shape and adds an administrator-only Amazon `sync`
2623
+ block. Members retain the shared shape without the field catalogue or sync bookkeeping.
2624
 
2625
  ⛔⛔ **`excluded` CARRIES THE PROVENANCE, AND THAT IS THE WHOLE POINT OF THE SCREEN HERE.** Five
2626
  of the seven tables have NO published schema, because Amazon publishes artifacts only for its
 
2649
  enabled = enablement.get("databases") or {}
2650
  cat = amazon_schema.catalogue()
2651
  tables = cat.get("tables") or {}
2652
+ states = cx.sync_state(rt, getattr(rt, "key", "")) if is_admin else None
2653
 
2654
  # Which OTHER declared tables are filled from the SAME report document. Derived from the
2655
  # report map so a table added to `REPORT_TYPES` gets this disclosure for free.
2656
  by_report = {}
2657
  for name in amazon_schema.PROVENANCE:
2658
+ rep = _amazon_report_name(name)
2659
  if rep:
2660
  by_report.setdefault(rep, []).append("ut_amzn_" + name)
2661
 
 
2664
  key = "ut_amzn_" + name
2665
  spec = tables.get(name) or {}
2666
  cols = spec.get("columns") or []
2667
+ rep = _amazon_report_name(name)
2668
  fields = [{"key": str(c.get("name") or ""),
2669
  "label": str(c.get("name") or "").replace("_", " ").capitalize(),
2670
  "type": "text" if str(c.get("type")) == "VARCHAR" else "number",
 
2695
  # read from Odoo's grid config, and disabling it leaves every stored row and
2696
  # definition untouched: only this provider config document changes.
2697
  "enabled": enabled.get(key) is True,
2698
+ **({"sync": (states or {}).get(name)} if is_admin else {}),
2699
  "fields": fields,
2700
  "excluded": excluded,
2701
  "sharesFieldsWith": [k for k in by_report.get(rep, ()) if k != key]})
 
2916
  return _safe_connector_status(key, {"overview": overview,
2917
  "keychain": keychain,
2918
  "databases": databases,
2919
+ "syncNow": ({"provider": key, "path": f"/connectors/{key}/sync/now"}
2920
+ if is_admin and key in connector_sync.providers() else None),
2921
  "materialization": ({"provider": key, "statusPath": f"/connectors/{key}/jobs",
2922
  "retryPath": f"/connectors/{key}/sync/retry"}
2923
+ if is_admin and key == "odoo" else None),
2924
  # W55-T19 / R7 / C10 — a provider-specific capability. The client neither infers it
2925
  # from ``introspectable`` nor sends Amazon through Odoo's schema/config endpoints.
2926
  "enablement": enablement,
api/routes_customers.py CHANGED
@@ -603,7 +603,7 @@ def grid_assembly(session: Session, scope: str = "customer", storage_key: str =
603
  "team_id": team_id, "routes": normalized_routes, "zones": normalized_zones}
604
 
605
 
606
- def _payload(session: Session):
607
  """`{fields, rows, today, docs, pulled_at}` — X2's shape, which `verify_fields_contract.py`
608
  referees. Rows are now built by `aios_grid.rows_from_pool` (embed == standalone by
609
  construction); see `grid_assembly` for what that fixed.
@@ -617,11 +617,18 @@ def _payload(session: Session):
617
  """
618
  import aios_grid
619
 
620
- g = grid_assembly(session)
621
  rows = aios_grid.rows_from_pool(
622
  g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"])
623
  from core import route_system
624
  rows = route_system.apply_customer_projections(rows, g["routes"], g["zones"])
 
 
 
 
 
 
 
625
  # ⭐ C4 / D-138 (W30-T37) — THE DOCUMENTS PRODUCER FOR THE CUSTOMER SCOPE. The write door
626
  # (`doc_add`/`doc_fetch`/`doc_delete`) never stopped working and every client half is
627
  # complete; what vanished with `app.py` at EXIT-6 was the only thing that ever set this key.
@@ -636,6 +643,8 @@ def _payload(session: Session):
636
  # "every document in the tenant" mode to reach for, deliberately.
637
  from core import grid_events as _ge
638
  return {"fields": g["fields"], "rows": rows,
 
 
639
  # `today` rides the payload because every relative date condition must resolve against
640
  # the TENANT's day, never the browser's — a client that falls back to its own clock
641
  # disagrees with the server for everyone west of it.
@@ -718,8 +727,15 @@ def allowed_pids(session: Session):
718
 
719
 
720
  @router.get("/customers")
721
- def customers(session: Session = Depends(module_gate(MODULE))):
722
- return _payload(session)
 
 
 
 
 
 
 
723
 
724
 
725
  @router.get("/customers/assigned/{view_id}/rows")
 
603
  "team_id": team_id, "routes": normalized_routes, "zones": normalized_zones}
604
 
605
 
606
+ def _payload(session: Session, related=None):
607
  """`{fields, rows, today, docs, pulled_at}` — X2's shape, which `verify_fields_contract.py`
608
  referees. Rows are now built by `aios_grid.rows_from_pool` (embed == standalone by
609
  construction); see `grid_assembly` for what that fixed.
 
617
  """
618
  import aios_grid
619
 
620
+ g = grid_assembly(session, consume_corrections=not bool(related))
621
  rows = aios_grid.rows_from_pool(
622
  g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"])
623
  from core import route_system
624
  rows = route_system.apply_customer_projections(rows, g["routes"], g["zones"])
625
+ from routes_odoo_tables import narrow_related_rows
626
+ rows = narrow_related_rows(session, MODULE, rows, related)
627
+ from routes_tables import scope_linked_metrics, linked_metric_limits
628
+ rows, g['fields'], metric_refusals = scope_linked_metrics(
629
+ session, MODULE, rows, g['fields'], g['measures'], related)
630
+ if related:
631
+ g["pids"] = frozenset(row["pid"] for row in rows)
632
  # ⭐ C4 / D-138 (W30-T37) — THE DOCUMENTS PRODUCER FOR THE CUSTOMER SCOPE. The write door
633
  # (`doc_add`/`doc_fetch`/`doc_delete`) never stopped working and every client half is
634
  # complete; what vanished with `app.py` at EXIT-6 was the only thing that ever set this key.
 
643
  # "every document in the tenant" mode to reach for, deliberately.
644
  from core import grid_events as _ge
645
  return {"fields": g["fields"], "rows": rows,
646
+ "refusals": metric_refusals,
647
+ "limits": linked_metric_limits(metric_refusals),
648
  # `today` rides the payload because every relative date condition must resolve against
649
  # the TENANT's day, never the browser's — a client that falls back to its own clock
650
  # disagrees with the server for everyone west of it.
 
727
 
728
 
729
  @router.get("/customers")
730
+ def customers(session: Session = Depends(module_gate(MODULE)), related: str = None):
731
+ return _payload(session, related=related)
732
+
733
+
734
+ @router.post("/customers/aggregates")
735
+ def customer_aggregates(body: dict = Body(default=None),
736
+ session: Session = Depends(module_gate(MODULE))):
737
+ from routes_odoo_tables import odoo_table_aggregates
738
+ return odoo_table_aggregates(MODULE, body=body, session=session)
739
 
740
 
741
  @router.get("/customers/assigned/{view_id}/rows")
api/routes_dependents.py CHANGED
@@ -42,6 +42,8 @@ docstring names the cost of publishing it. This door returns names and a count,
42
  "Shared with Anna and 2 others" consumes.
43
  """
44
 
 
 
45
  from fastapi import APIRouter, Depends, Query
46
 
47
  import core.dependents as dependents_registry
@@ -148,6 +150,23 @@ def read_dependents(kind: str = Query(...), key: str = Query(...),
148
 
149
  target = {"kind": target_kind, "key": target_key, "database": resolved}
150
  report = dependents_registry.dependents_report(session.runtime, target)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
151
  label = _label_for(session, resolved, target_kind, target_key)
152
  body = {
153
  "target": target,
 
42
  "Shared with Anna and 2 others" consumes.
43
  """
44
 
45
+ from urllib.parse import parse_qs
46
+
47
  from fastapi import APIRouter, Depends, Query
48
 
49
  import core.dependents as dependents_registry
 
150
 
151
  target = {"kind": target_kind, "key": target_key, "database": resolved}
152
  report = dependents_registry.dependents_report(session.runtime, target)
153
+ seen = {resolved: True}
154
+ for dependent in report['dependents']:
155
+ # An address is not an authorisation. Inbound fields can live on a different
156
+ # database, so reuse the same wall before offering either C3 address shape.
157
+ for item in [dependent, *dependent.get('items', [])]:
158
+ href = item.get('href')
159
+ if not isinstance(href, str):
160
+ continue
161
+ if not href.startswith(('#/data?', '#/sheet?')):
162
+ item['href'] = None
163
+ item['reason'] = 'This dependent has no supported address available.'
164
+ continue
165
+ destinations = parse_qs(href.partition('?')[2]).get('database', [])
166
+ if (href.startswith('#/data?') and not destinations) or any(
167
+ not _may_open(session, destination, seen) for destination in destinations):
168
+ item['href'] = None
169
+ item['reason'] = 'You do not have access to open this dependent\'s database.'
170
  label = _label_for(session, resolved, target_kind, target_key)
171
  body = {
172
  "target": target,
api/routes_grid.py CHANGED
@@ -2491,9 +2491,11 @@ def _topic_rt(st, module):
2491
  return st
2492
 
2493
 
2494
- def _customer_rows(table_key, user, st):
2495
  """`(fields, rows)` for the customer topic — the SAME derivation `_team_agent` uses."""
2496
  import aios_grid
 
 
2497
  import core.perm_scope as perm_scope
2498
  from routes_customers import _pool_for
2499
 
@@ -2502,15 +2504,16 @@ def _customer_rows(table_key, user, st):
2502
  return list(aios_grid.FIELDS), _pool_for(rt, team_id, agent)
2503
 
2504
 
2505
- def _product_rows(table_key, user, st):
2506
  """`(fields, rows)` for the product topic. `consolidated=` follows the derived scope, so a
2507
  BU-pinned reader gets that BU's field contract rather than the consolidated one."""
2508
  import core.perm_scope as perm_scope
2509
  from routes_products import _pool_for, pd_fields
2510
 
2511
- rt = _topic_rt(st, table_key)
2512
  team_id, _agent = perm_scope.derive_pool_scope(user, table_key)
2513
- return pd_fields(consolidated=team_id is None, st=st), _pool_for(rt, team_id)
 
2514
 
2515
 
2516
  def _register_topic_rows():
@@ -2747,7 +2750,8 @@ def _may_open(session: Session, key: str, st=None, memo: dict = None):
2747
  return _walled_fields(session, key, st=st, memo=memo) is not None
2748
 
2749
 
2750
- def _source_fields(session: Session, table: str, st=None, memo: dict = None):
 
2751
  """The link-bearing field list for `table`, under this session's field wall.
2752
 
2753
  ⛔⛔ THE PRE-SET COLUMNS ARE NOT IN `scoped_fields` AND THAT IS THE TRAP THIS FUNCTION EXISTS
@@ -2769,7 +2773,8 @@ def _source_fields(session: Session, table: str, st=None, memo: dict = None):
2769
  import odoo_relational
2770
  fields = fields + list(odoo_relational.module_link_fields(table) or ())
2771
  except Exception: # noqa: BLE001
2772
- pass
 
2773
  return fields
2774
 
2775
 
@@ -2826,7 +2831,7 @@ def _ensure_odoo_spec():
2826
  return False
2827
 
2828
 
2829
- def _unwalled_fields(defs: dict, key: str):
2830
  """`key`'s field list WITHOUT this session's FIELD wall, for the W53-T18 diff pass only.
2831
 
2832
  ⛔⛔ IT IS NEVER SERVED AND NEVER WIDENS A TAB. Its ONE consumer is the unfiltered half of
@@ -2849,7 +2854,8 @@ def _unwalled_fields(defs: dict, key: str):
2849
  import odoo_relational
2850
  fields = fields + list(odoo_relational.module_link_fields(key) or ())
2851
  except Exception: # noqa: BLE001
2852
- pass
 
2853
  return fields
2854
 
2855
 
@@ -2884,7 +2890,7 @@ def _relation_context(session: Session, table: str, memo: dict = None):
2884
  than a silently empty grid — and `scoped_fields` is a `want_rows=False` door by construction.
2885
  Nothing here is handed to a mutation; `grid_related` is a GET.
2886
  ⛔ IT CANNOT WIDEN A WALL, and that was checked rather than assumed: the lent handle serves
2887
- only `user_tables` and (lazily, once) `object_shares`, every other store key falls through to
2888
  the real runtime, and `session.require` is not given it at all. MEASURED 2026-09-06 across all
2889
  ten of tenant #0's databases: `scoped_fields` under the lent handle returned a field list
2890
  EQUAL, key for key and value for value, to the one it returned under the bare runtime.
@@ -2895,16 +2901,19 @@ def _relation_context(session: Session, table: str, memo: dict = None):
2895
  """
2896
  import core.user_tables as user_tables
2897
 
 
2898
  try:
2899
  defs = dict(user_tables.all_defs(st=session.runtime) or {})
2900
  except Exception: # noqa: BLE001
2901
  defs = {}
 
2902
  try:
2903
  lent = user_tables.lend(session.runtime, **{user_tables.STORE_KEY: defs})
2904
  except Exception: # noqa: BLE001
2905
  # A store handle too old to lend is CORRECT-but-slow, exactly as `all_defs`' own fallback
2906
  # is: the pass simply goes back to paying a round trip per wall resolution.
2907
  lent = session.runtime
 
2908
 
2909
  # ⭐ ONE WALL RESOLUTION PER TABLE, SHARED BY BOTH CALLBACKS. `open_memo` and `field_memo`
2910
  # below still memoise their own composition (the grant gate, the pre-set link append); this is
@@ -2919,24 +2928,30 @@ def _relation_context(session: Session, table: str, memo: dict = None):
2919
  def may_open(key):
2920
  if key not in open_memo:
2921
  open_memo[key] = _may_open(session, key, st=lent, memo=wall_memo)
 
 
2922
  return open_memo[key]
2923
 
2924
  def fields_for(key):
2925
  if key not in field_memo:
2926
- field_memo[key] = _source_fields(session, key, st=lent, memo=wall_memo)
 
 
 
2927
  return field_memo[key]
2928
 
2929
  def open_fields_for(key):
2930
  if key not in wide_memo:
2931
  walled = list(fields_for(key) or ())
2932
  seen = {str(f.get("key")) for f in walled if isinstance(f, dict)}
2933
- extra = [f for f in _unwalled_fields(defs, key)
2934
  if isinstance(f, dict) and str(f.get("key")) not in seen]
2935
  wide_memo[key] = walled + extra
2936
  return wide_memo[key]
2937
 
2938
- return {"defs": defs, "may_open": may_open, "fields_for": fields_for,
2939
- "open_fields_for": open_fields_for}
 
2940
 
2941
 
2942
  def related_path_entries(session: Session, table: str, depth: int, ctx: dict = None):
@@ -2952,14 +2967,120 @@ def related_path_entries(session: Session, table: str, depth: int, ctx: dict = N
2952
  """
2953
  import core.relations as relations
2954
 
2955
- _ensure_odoo_spec()
2956
  table = str(table or "")
2957
  ctx = ctx or _relation_context(session, table)
 
 
2958
  return relations.related_paths(table, fields=ctx["fields_for"](table), defs=ctx["defs"],
2959
  depth=depth, may_open=ctx["may_open"],
2960
  fields_for=ctx["fields_for"])
2961
 
2962
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2963
  def related_refusals(session: Session, table: str, depth: int, entries: list, ctx: dict = None):
2964
  """W53-T18 / R13 / C3 — WHAT THE WALL REMOVED from `entries`, by name. The SIBLING of `related`.
2965
 
@@ -3031,6 +3152,33 @@ def _refusal_error(diag: dict):
3031
  return exc
3032
 
3033
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3034
  @router.get("/grid/{table}/related")
3035
  def grid_related(table: str,
3036
  depth: int = Query(default=2),
@@ -3102,12 +3250,27 @@ def grid_related(table: str,
3102
  f"{relations.MAX_DEPTH} (those plus everything one further named hop away), and "
3103
  f"this request asked for {depth}. Ask for 1 or {relations.MAX_DEPTH}")
3104
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3105
  ctx = _relation_context(session, table, memo=wall_memo)
3106
  entries = related_path_entries(session, table, depth, ctx)
3107
- if via:
3108
- wanted = [str(v) for v in via if str(v or "").strip()]
3109
- if len(wanted) > relations.MAX_DEPTH:
3110
- raise err(400, "over_depth", relations.over_depth_refusal(table, wanted))
3111
  hit = relations.pick_path(entries, wanted)
3112
  if hit is None:
3113
  # ⭐⭐ W53-T18 / R13 / C3 — THE ONE GENERIC `unknown_via` IS NOW ONE OF FOUR NAMED
@@ -3127,7 +3290,19 @@ def grid_related(table: str,
3127
  # ⚠ A RESOLVED PIN REPORTS NO REFUSALS. The caller named one path and got it; the other
3128
  # tabs the wall removed are the LISTING's answer, not this one, and repeating them here
3129
  # would attach an unasked-for permission report to every successful read.
3130
- return {"ok": True, "table": table, "depth": depth, "related": [hit], "refusals": []}
3131
- return {"ok": True, "table": table, "depth": depth, "related": entries,
3132
- "refusals": related_refusals(session, table, depth, entries, ctx)}
3133
-
 
 
 
 
 
 
 
 
 
 
 
 
 
2491
  return st
2492
 
2493
 
2494
+ def _customer_rows(table_key, user, st, want_rows=True):
2495
  """`(fields, rows)` for the customer topic — the SAME derivation `_team_agent` uses."""
2496
  import aios_grid
2497
+ if not want_rows:
2498
+ return list(aios_grid.FIELDS), []
2499
  import core.perm_scope as perm_scope
2500
  from routes_customers import _pool_for
2501
 
 
2504
  return list(aios_grid.FIELDS), _pool_for(rt, team_id, agent)
2505
 
2506
 
2507
+ def _product_rows(table_key, user, st, want_rows=True):
2508
  """`(fields, rows)` for the product topic. `consolidated=` follows the derived scope, so a
2509
  BU-pinned reader gets that BU's field contract rather than the consolidated one."""
2510
  import core.perm_scope as perm_scope
2511
  from routes_products import _pool_for, pd_fields
2512
 
2513
+ rt = _topic_rt(st, table_key) if want_rows else None
2514
  team_id, _agent = perm_scope.derive_pool_scope(user, table_key)
2515
+ return pd_fields(consolidated=team_id is None, st=st), (
2516
+ _pool_for(rt, team_id) if want_rows else [])
2517
 
2518
 
2519
  def _register_topic_rows():
 
2750
  return _walled_fields(session, key, st=st, memo=memo) is not None
2751
 
2752
 
2753
+ def _source_fields(session: Session, table: str, st=None, memo: dict = None,
2754
+ read_status: dict = None):
2755
  """The link-bearing field list for `table`, under this session's field wall.
2756
 
2757
  ⛔⛔ THE PRE-SET COLUMNS ARE NOT IN `scoped_fields` AND THAT IS THE TRAP THIS FUNCTION EXISTS
 
2773
  import odoo_relational
2774
  fields = fields + list(odoo_relational.module_link_fields(table) or ())
2775
  except Exception: # noqa: BLE001
2776
+ if read_status is not None:
2777
+ read_status["cacheable"] = False
2778
  return fields
2779
 
2780
 
 
2831
  return False
2832
 
2833
 
2834
+ def _unwalled_fields(defs: dict, key: str, read_status: dict = None):
2835
  """`key`'s field list WITHOUT this session's FIELD wall, for the W53-T18 diff pass only.
2836
 
2837
  ⛔⛔ IT IS NEVER SERVED AND NEVER WIDENS A TAB. Its ONE consumer is the unfiltered half of
 
2854
  import odoo_relational
2855
  fields = fields + list(odoo_relational.module_link_fields(key) or ())
2856
  except Exception: # noqa: BLE001
2857
+ if read_status is not None:
2858
+ read_status["cacheable"] = False
2859
  return fields
2860
 
2861
 
 
2890
  than a silently empty grid — and `scoped_fields` is a `want_rows=False` door by construction.
2891
  Nothing here is handed to a mutation; `grid_related` is a GET.
2892
  ⛔ IT CANNOT WIDEN A WALL, and that was checked rather than assumed: the lent handle serves
2893
+ `user_tables`, (lazily, once) `object_shares` and read-only `__shared` overlays; other keys fall through to
2894
  the real runtime, and `session.require` is not given it at all. MEASURED 2026-09-06 across all
2895
  ten of tenant #0's databases: `scoped_fields` under the lent handle returned a field list
2896
  EQUAL, key for key and value for value, to the one it returned under the bare runtime.
 
2901
  """
2902
  import core.user_tables as user_tables
2903
 
2904
+ read_status = {"cacheable": True}
2905
  try:
2906
  defs = dict(user_tables.all_defs(st=session.runtime) or {})
2907
  except Exception: # noqa: BLE001
2908
  defs = {}
2909
+ read_status["cacheable"] = False
2910
  try:
2911
  lent = user_tables.lend(session.runtime, **{user_tables.STORE_KEY: defs})
2912
  except Exception: # noqa: BLE001
2913
  # A store handle too old to lend is CORRECT-but-slow, exactly as `all_defs`' own fallback
2914
  # is: the pass simply goes back to paying a round trip per wall resolution.
2915
  lent = session.runtime
2916
+ read_status["cacheable"] = False
2917
 
2918
  # ⭐ ONE WALL RESOLUTION PER TABLE, SHARED BY BOTH CALLBACKS. `open_memo` and `field_memo`
2919
  # below still memoise their own composition (the grant gate, the pre-set link append); this is
 
2928
  def may_open(key):
2929
  if key not in open_memo:
2930
  open_memo[key] = _may_open(session, key, st=lent, memo=wall_memo)
2931
+ if not open_memo[key]:
2932
+ read_status["cacheable"] = False
2933
  return open_memo[key]
2934
 
2935
  def fields_for(key):
2936
  if key not in field_memo:
2937
+ field_memo[key] = _source_fields(session, key, st=lent, memo=wall_memo,
2938
+ read_status=read_status)
2939
+ if wall_memo.get(key) is None:
2940
+ read_status["cacheable"] = False
2941
  return field_memo[key]
2942
 
2943
  def open_fields_for(key):
2944
  if key not in wide_memo:
2945
  walled = list(fields_for(key) or ())
2946
  seen = {str(f.get("key")) for f in walled if isinstance(f, dict)}
2947
+ extra = [f for f in _unwalled_fields(defs, key, read_status=read_status)
2948
  if isinstance(f, dict) and str(f.get("key")) not in seen]
2949
  wide_memo[key] = walled + extra
2950
  return wide_memo[key]
2951
 
2952
+ read_status.update(defs=defs, may_open=may_open, fields_for=fields_for,
2953
+ open_fields_for=open_fields_for)
2954
+ return read_status
2955
 
2956
 
2957
  def related_path_entries(session: Session, table: str, depth: int, ctx: dict = None):
 
2967
  """
2968
  import core.relations as relations
2969
 
2970
+ spec_ready = _ensure_odoo_spec()
2971
  table = str(table or "")
2972
  ctx = ctx or _relation_context(session, table)
2973
+ if not spec_ready:
2974
+ ctx["cacheable"] = False
2975
  return relations.related_paths(table, fields=ctx["fields_for"](table), defs=ctx["defs"],
2976
  depth=depth, may_open=ctx["may_open"],
2977
  fields_for=ctx["fields_for"])
2978
 
2979
 
2980
+ def related_measure_pin(session, target, related, requested):
2981
+ """Compile metric membership with the rows door's exact path and leg resolvers.
2982
+
2983
+ SQL bindings are host declarations. No SQL, callbacks or row identities are trusted from
2984
+ the client beyond the origin id, named edge and requested subset of resolved target ids.
2985
+ Retain through rows as well as explicit hops so a metric cannot expand behind a row wall.
2986
+ """
2987
+ from core import perm_scope, relations
2988
+ import routes_odoo_tables as door
2989
+
2990
+ if isinstance(related, str):
2991
+ related = door._json_arg(related, 'related')
2992
+ allowed = door._relation_target_ids(session, target, related)
2993
+ if set(requested) - allowed:
2994
+ raise err(403, 'metric_record_refused', 'A requested record is outside this linked grid.')
2995
+ source, via = str(related['table']), related.get('via')
2996
+ path = door._via_path(via)
2997
+ entries = related_path_entries(session, source, len(path) if path else 1)
2998
+ entry = relations.pick_path(entries, path) if path else relations.pick(entries, via)
2999
+ legs = [(source, entry)]
3000
+ if len(entry.get('path') or ()) > 1:
3001
+ first, middle, last = door._related_path_legs(session, source, entry, entries)
3002
+ legs = [(source, first), (middle, last)]
3003
+
3004
+ bindings = {
3005
+ 'sale_order_line': [
3006
+ dict(table='customer_data', column='pid', sql='{alias}.order_partner_id'),
3007
+ dict(table='product_data', column='product_id', sql='{alias}.product_id'),
3008
+ dict(table='ut_odoo_orders', column='pid', sql='{alias}.order_id'),
3009
+ dict(table='ut_odoo_order_lines', column='pid', sql='{alias}.id'),
3010
+ dict(table='ut_odoo_agents', column='pid', sql='rp.agent_id'),
3011
+ ],
3012
+ 'sale_order': [
3013
+ dict(table='customer_data', column='pid', sql='{alias}.partner_id'),
3014
+ dict(table='ut_odoo_orders', column='pid', sql='{alias}.id'),
3015
+ dict(table='ut_odoo_agents', column='pid', sql='rp.agent_id'),
3016
+ dict(table='ut_odoo_order_lines', column='order_id', sql='{alias}.id'),
3017
+ ],
3018
+ }
3019
+ members = {}
3020
+ def read(table, column, values, where):
3021
+ columns = {'pid', column}
3022
+ if table == 'product_data':
3023
+ columns.add('product_id')
3024
+ if table == 'ut_odoo_order_lines':
3025
+ columns.add('order_id')
3026
+ return door._relation_rows(session, table, columns, match=(column, values), where=where)
3027
+
3028
+ def retain(table, ids):
3029
+ rows = read(table, 'pid', ids, None)
3030
+ if table in members:
3031
+ existing = {r['pid'] for r in members[table]}
3032
+ if {r['pid'] for r in rows} != existing:
3033
+ raise err(409, 'metric_scope_unsupported',
3034
+ 'This metric cannot distinguish repeated databases in the record path. '
3035
+ 'Use a direct relation or add a metric binding for these separate roles.')
3036
+ rows = [r for r in rows if r['pid'] in existing]
3037
+ members[table] = rows
3038
+
3039
+ with relations.measure_pin_context(read=read, bindings=bindings,
3040
+ may_open=lambda key: _may_open(session, key)):
3041
+ ids = {int(related['record'])}
3042
+ retain(source, ids)
3043
+ if not members[source]:
3044
+ raise err(403, 'metric_record_refused', 'The origin record is unavailable to this account.')
3045
+ for table, leg in legs:
3046
+ link, via = leg.get('link') or {}, leg.get('via') or {}
3047
+ through = link.get('through')
3048
+ if through and link.get('selectionMode') != 'manual':
3049
+ reverse = via.get('direction') == 'reverse'
3050
+ left = str(link['throughTo'] if reverse else link['throughOn'])
3051
+ frm = str(via.get('from') or 'pid')
3052
+ origins = door._relation_rows(session, table, [frm], ids=ids)
3053
+ bridge = read(str(through), left,
3054
+ [r[frm] for r in origins if r.get(frm) is not None], None)
3055
+ retain(str(through), {r['pid'] for r in bridge})
3056
+ ids = door._relation_leg_ids(session, table, ids, leg)
3057
+ retain(str(leg['target']), ids)
3058
+ required = tuple(members)
3059
+ # A manual link need not name the sales bridge. Its metrics still obey that
3060
+ # database's row wall, intersected with the already resolved record membership.
3061
+ if 'ut_odoo_order_lines' not in members:
3062
+ for table, column, join in [('customer_data', 'pid', 'partner_id'),
3063
+ ('product_data', 'product_id', 'product_id'),
3064
+ ('ut_odoo_orders', 'pid', 'order_id')]:
3065
+ if table in members:
3066
+ bridge = read('ut_odoo_order_lines', join,
3067
+ [r[column] for r in members[table]], None)
3068
+ # This extra wall belongs to line metrics. Header metrics use their own
3069
+ # traversed order membership, including legitimate orders with no lines.
3070
+ retain('ut_odoo_order_lines', {r['pid'] for r in bridge})
3071
+ bindings['sale_order'] = [binding for binding in bindings['sale_order']
3072
+ if binding['table'] != 'ut_odoo_order_lines']
3073
+ break
3074
+ # Required path tables must all bind. Binding only the destination would return globals.
3075
+ pin = relations.MeasurePin(entry['path'], members, bindings,
3076
+ required=required)
3077
+ scopes = [perm_scope.derive_pool_scope(session.user, table) for table in required]
3078
+ teams = {team for team, _agent in scopes if team is not None}
3079
+ if len(teams) > 1:
3080
+ raise err(403, 'metric_scope_conflict', 'The linked databases have incompatible business unit scopes.')
3081
+ return pin, next(iter(teams), None)
3082
+
3083
+
3084
  def related_refusals(session: Session, table: str, depth: int, entries: list, ctx: dict = None):
3085
  """W53-T18 / R13 / C3 — WHAT THE WALL REMOVED from `entries`, by name. The SIBLING of `related`.
3086
 
 
3152
  return exc
3153
 
3154
 
3155
+ _RELATED_CACHE_LIMIT = 128
3156
+
3157
+
3158
+ def _related_cache_key(session: Session, table: str, depth: int, via):
3159
+ """Names-only answers follow this user's schema, grant, sync and registrar revisions.
3160
+
3161
+ Tokens are read-through dict lookups, not document downloads. A runtime without revision
3162
+ support can still serve an uncached answer. Never reuse an answer with unknown revisions.
3163
+ """
3164
+ import core.store as store
3165
+ import core.shares as shares
3166
+ import core.user_tables as user_tables
3167
+ import odoo_relational
3168
+
3169
+ try:
3170
+ if not session.uname:
3171
+ return None
3172
+ return (session.uname, table, depth, via,
3173
+ session.runtime.revision(user_tables.STORE_KEY)["token"],
3174
+ session.runtime.revision(shares.SHARES_KEY)["token"],
3175
+ store.revision("users")["token"],
3176
+ session.runtime.revision(odoo_relational.CONFIG_KEY)["token"],
3177
+ user_tables.register_read_through(), user_tables.register_connected_prefix())
3178
+ except Exception: # noqa: BLE001
3179
+ return None
3180
+
3181
+
3182
  @router.get("/grid/{table}/related")
3183
  def grid_related(table: str,
3184
  depth: int = Query(default=2),
 
3250
  f"{relations.MAX_DEPTH} (those plus everything one further named hop away), and "
3251
  f"this request asked for {depth}. Ask for 1 or {relations.MAX_DEPTH}")
3252
 
3253
+ wanted = tuple(str(v).strip() for v in via if str(v or "").strip()) if via else None
3254
+ if wanted is not None and len(wanted) > relations.MAX_DEPTH:
3255
+ raise err(400, "over_depth", relations.over_depth_refusal(table, list(wanted)))
3256
+
3257
+ # This registration must run even on a hit; an import order repair cannot be skipped by
3258
+ # memoisation. Failed registration or reads are served as before, but never remembered.
3259
+ spec_ready = _ensure_odoo_spec()
3260
+ cache = getattr(session.runtime, "related_cache", None)
3261
+ cache_key = (_related_cache_key(session, table, depth, wanted)
3262
+ if spec_ready and cache is not None else None)
3263
+ if spec_ready and cache_key is not None:
3264
+ from copy import deepcopy
3265
+ with session.runtime._lock:
3266
+ cached = cache.get(cache_key)
3267
+ if cached is not None:
3268
+ return deepcopy(cached)
3269
+
3270
  ctx = _relation_context(session, table, memo=wall_memo)
3271
  entries = related_path_entries(session, table, depth, ctx)
3272
+ if wanted is not None:
3273
+ wanted = list(wanted)
 
 
3274
  hit = relations.pick_path(entries, wanted)
3275
  if hit is None:
3276
  # ⭐⭐ W53-T18 / R13 / C3 — THE ONE GENERIC `unknown_via` IS NOW ONE OF FOUR NAMED
 
3290
  # ⚠ A RESOLVED PIN REPORTS NO REFUSALS. The caller named one path and got it; the other
3291
  # tabs the wall removed are the LISTING's answer, not this one, and repeating them here
3292
  # would attach an unasked-for permission report to every successful read.
3293
+ answer = {"ok": True, "table": table, "depth": depth, "related": [hit], "refusals": []}
3294
+ else:
3295
+ answer = {"ok": True, "table": table, "depth": depth, "related": entries,
3296
+ "refusals": related_refusals(session, table, depth, entries, ctx)}
3297
+ if (spec_ready and cache_key is not None and ctx.get("cacheable", False) and ctx["defs"]
3298
+ and not answer["refusals"]
3299
+ and cache_key == _related_cache_key(session, table, depth, cache_key[3])):
3300
+ from copy import deepcopy
3301
+ # The Amazon purge's pool-cache tuple does not include this memo. That is safe because
3302
+ # every lookup checks the current tokens; old entries cannot match changed metadata.
3303
+ # Limit memory, not the number of related databases: eviction just rebuilds next open.
3304
+ with session.runtime._lock:
3305
+ if len(cache) >= _RELATED_CACHE_LIMIT:
3306
+ cache.clear()
3307
+ cache[cache_key] = deepcopy(answer)
3308
+ return answer
api/routes_keychain.py CHANGED
@@ -920,6 +920,14 @@ def add_key(body: dict = Body(default=None), session: Session = Depends(require_
920
  _rel_reconnect(session.runtime)
921
  except Exception: # noqa: BLE001
922
  pass
 
 
 
 
 
 
 
 
923
  if scope != DEFAULT_SCOPE:
924
  try:
925
  _write_scope(session.runtime, row["id"], scope, session.uname)
 
920
  _rel_reconnect(session.runtime)
921
  except Exception: # noqa: BLE001
922
  pass
923
+ elif etype == "amazon_sp":
924
+ # D-29 / intake F6: the HTTP thread only records intent. The resident resync thread
925
+ # remains the mirror's single writer. A queue failure must not undo a stored credential.
926
+ try:
927
+ from core import connector_sync
928
+ connector_sync.request_sync("amazon_sp", session.runtime.key, requested_by=session.uname)
929
+ except Exception: # noqa: BLE001
930
+ pass
931
  if scope != DEFAULT_SCOPE:
932
  try:
933
  _write_scope(session.runtime, row["id"], scope, session.uname)
api/routes_nav.py CHANGED
@@ -81,6 +81,36 @@ def _now() -> int:
81
  return int(time.time())
82
 
83
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
84
  def _clean_nav_prefs(raw, page_keys, *, keep_unknown_ut=False):
85
  """Validated wholesale replacement, the `clean_folders` posture: prune, never invent.
86
 
@@ -118,7 +148,35 @@ def _clean_nav_prefs(raw, page_keys, *, keep_unknown_ut=False):
118
  placement[k] = v
119
  elif keep_unknown_ut and k.startswith("ut_"):
120
  placement[k] = v
121
- return {"folders": folders, "placement": placement}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
122
 
123
 
124
  def _placeable_top_keys(session):
@@ -959,7 +1017,7 @@ def nav_prefs(session: Session = Depends(require_session)):
959
  try:
960
  stored = (session.runtime.get(_NAV_PREFS_KEY) or {}).get(session.uname) or {}
961
  except Exception:
962
- stored = {}
963
  keys, enumerated = _placeable_top_keys(session)
964
  return {"prefs": _clean_nav_prefs(stored, keys, keep_unknown_ut=not enumerated)}
965
 
@@ -967,17 +1025,19 @@ def nav_prefs(session: Session = Depends(require_session)):
967
  @router.post("/nav/prefs")
968
  def save_nav_prefs(body: dict = Body(default=None),
969
  session: Session = Depends(require_session)):
970
- """Wholesale replace, like the table folder stratum — the client sent its complete
971
- picture, validated here; a partial merge would resurrect deleted folders forever."""
972
  keys, enumerated = _placeable_top_keys(session)
973
- clean = _clean_nav_prefs(body or {}, keys, keep_unknown_ut=not enumerated)
974
  if not session.runtime.available():
975
  raise err(503, "store_unavailable",
976
  "the tenant store is unavailable. Nothing was saved.")
977
 
978
  def _up(data):
 
979
  data = data if isinstance(data, dict) else {}
980
- if clean["folders"] or clean["placement"]:
 
 
981
  data[session.uname] = clean
982
  else:
983
  data.pop(session.uname, None)
@@ -987,7 +1047,7 @@ def save_nav_prefs(body: dict = Body(default=None),
987
  session.runtime.update(_NAV_PREFS_KEY, _up)
988
  except Exception:
989
  raise err(503, "store_unavailable",
990
- "the folder change was not saved: the store refused the write.")
991
  return {"prefs": clean}
992
 
993
 
 
81
  return int(time.time())
82
 
83
 
84
+ def _clean_linked_layouts(raw):
85
+ """R8 personal presentation only. Never accept a SavedView or a field definition."""
86
+ if not isinstance(raw, dict):
87
+ return {}
88
+ layouts = {}
89
+ for key, value in raw.items():
90
+ if not isinstance(key, str) or not key or not isinstance(value, dict):
91
+ continue
92
+ layout = {}
93
+ for name in ("order", "visible"):
94
+ if isinstance(value.get(name), list):
95
+ layout[name] = list(dict.fromkeys(k for k in value[name] if isinstance(k, str)))
96
+ if isinstance(value.get("widths"), dict):
97
+ layout["widths"] = {k: w for k, w in value["widths"].items()
98
+ if isinstance(k, str) and type(w) in (int, float) and w > 0}
99
+ if isinstance(value.get("sorts"), list):
100
+ layout["sorts"] = [{"colId": s["colId"], "dir": s["dir"]}
101
+ for s in value["sorts"] if isinstance(s, dict)
102
+ and isinstance(s.get("colId"), str) and s.get("dir") in ("asc", "desc")]
103
+ if isinstance(value.get("filters"), list):
104
+ layout["filters"] = [n for n in value["filters"] if isinstance(n, dict)]
105
+ if value.get("filterConj") in ("and", "or"):
106
+ layout["filterConj"] = value["filterConj"]
107
+ if "groupBy" in value and (value["groupBy"] is None or isinstance(value["groupBy"], str)):
108
+ layout["groupBy"] = value["groupBy"]
109
+ if layout:
110
+ layouts[key] = layout
111
+ return layouts
112
+
113
+
114
  def _clean_nav_prefs(raw, page_keys, *, keep_unknown_ut=False):
115
  """Validated wholesale replacement, the `clean_folders` posture: prune, never invent.
116
 
 
148
  placement[k] = v
149
  elif keep_unknown_ut and k.startswith("ut_"):
150
  placement[k] = v
151
+ clean = {"folders": folders, "placement": placement}
152
+ layouts = _clean_linked_layouts(raw.get("linkedLayouts"))
153
+ if layouts:
154
+ clean["linkedLayouts"] = layouts
155
+ return clean
156
+
157
+
158
+ def _merge_nav_prefs(stored, body, page_keys, *, keep_unknown_ut=False):
159
+ """Replace navigation only when supplied; patch each personal link independently.
160
+
161
+ Called inside runtime.update so concurrent link and folder writes see the latest entry.
162
+ Folder clients may echo a stale linkedLayouts from GET; only a layout-only request owns it.
163
+ """
164
+ stored = stored if isinstance(stored, dict) else {}
165
+ body = body if isinstance(body, dict) else {}
166
+ navigation = "folders" in body or "placement" in body
167
+ merged = {**stored}
168
+ if navigation:
169
+ merged.update(folders=body.get("folders", []), placement=body.get("placement", {}))
170
+ else:
171
+ layouts = _clean_linked_layouts(stored.get("linkedLayouts"))
172
+ layouts.update(_clean_linked_layouts(body.get("linkedLayouts")))
173
+ merged["linkedLayouts"] = layouts
174
+ # A layout write does not own navigation pruning either.
175
+ clean = _clean_nav_prefs(merged, page_keys, keep_unknown_ut=keep_unknown_ut)
176
+ if not navigation:
177
+ for name, default in (("folders", []), ("placement", {})):
178
+ clean[name] = stored.get(name, default)
179
+ return clean
180
 
181
 
182
  def _placeable_top_keys(session):
 
1017
  try:
1018
  stored = (session.runtime.get(_NAV_PREFS_KEY) or {}).get(session.uname) or {}
1019
  except Exception:
1020
+ raise err(503, "store_unavailable", "Your saved preferences could not be loaded.")
1021
  keys, enumerated = _placeable_top_keys(session)
1022
  return {"prefs": _clean_nav_prefs(stored, keys, keep_unknown_ut=not enumerated)}
1023
 
 
1025
  @router.post("/nav/prefs")
1026
  def save_nav_prefs(body: dict = Body(default=None),
1027
  session: Session = Depends(require_session)):
1028
+ """Replace the supplied navigation picture or patch personal linked-grid layouts."""
 
1029
  keys, enumerated = _placeable_top_keys(session)
1030
+ clean = {}
1031
  if not session.runtime.available():
1032
  raise err(503, "store_unavailable",
1033
  "the tenant store is unavailable. Nothing was saved.")
1034
 
1035
  def _up(data):
1036
+ nonlocal clean
1037
  data = data if isinstance(data, dict) else {}
1038
+ clean = _merge_nav_prefs(data.get(session.uname), body, keys,
1039
+ keep_unknown_ut=not enumerated)
1040
+ if clean["folders"] or clean["placement"] or clean.get("linkedLayouts"):
1041
  data[session.uname] = clean
1042
  else:
1043
  data.pop(session.uname, None)
 
1047
  session.runtime.update(_NAV_PREFS_KEY, _up)
1048
  except Exception:
1049
  raise err(503, "store_unavailable",
1050
+ "the preference change was not saved: the store refused the write.")
1051
  return {"prefs": clean}
1052
 
1053
 
api/routes_odoo_tables.py CHANGED
@@ -23,6 +23,7 @@ import hashlib
23
  import hmac
24
  import json
25
  import time
 
26
 
27
  from fastapi import Body, Depends, HTTPException
28
  from fastapi import APIRouter, Query
@@ -1516,6 +1517,148 @@ def _related_source_value(session, entry, record):
1516
  return None
1517
 
1518
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1519
  def _cache_relation_plan(session, source, via, target):
1520
  """The offered module link and its explicit bridge, or a cause-specific refusal.
1521
 
@@ -1601,7 +1744,10 @@ def _cache_relation_source_value(session, entry, record):
1601
 
1602
 
1603
  def _cache_relation_target_ids(session, source, record, via, target):
1604
- """Resolve one explicit source -> mirror bridge -> module-cache path to target row pids."""
 
 
 
1605
  entry, _link, through, through_on, through_to, on = _cache_relation_plan(
1606
  session, source, via, target)
1607
  source_value = _cache_relation_source_value(session, entry, record)
@@ -1658,7 +1804,8 @@ def odoo_relation_targets(source: str = Query(...), record: int = Query(..., ge=
1658
  via: str = Query(...), target: str = Query(...),
1659
  session: Session = Depends(require_session)):
1660
  """Target pids for a declared relation whose destination is a runtime-cache database."""
1661
- return _cache_relation_target_ids(session, source, record, via, target)
 
1662
 
1663
 
1664
  def _via_path(via):
@@ -1721,308 +1868,24 @@ def _related_path_legs(session, source, entry, entries):
1721
  return dict(first, __source__=source), mid_key, dict(last, __source__=mid_key)
1722
 
1723
 
1724
- def _related_hop_values(session, source, record, first, mid_key, last, notes):
1725
- """The values hop 2 joins on, resolved from the INTERMEDIATE database's own rows.
1726
-
1727
- ⭐⭐ W54-T40 — THIS IS THE HALF THAT MAKES A TWO-HOP TAB ANSWER ROWS INSTEAD OF A SENTENCE.
1728
- Hop 1 turns the source record into a set of intermediate rows; this returns the value each of
1729
- those rows carries in the column hop 2 is keyed on, and the caller pins THIS database by them.
1730
-
1731
- ⛔⛔ THE INTERMEDIATE IS READ THROUGH `_compiled_read`, WHICH IS THE SAME COMPILER THIS DOOR
1732
- USES FOR AN ORDINARY WINDOW, AND THAT IS THE WHOLE PERMISSION ARGUMENT. Its grant gate, its
1733
- administrator row wall and its hidden-field closure all run before a single id is produced, so
1734
- a traversal cannot be used to learn about rows of the middle database a reader may not see. A
1735
- second, lighter read here would be a second permission wall, and this file already carries the
1736
- rule that a second copy of that block does not drift towards refusing.
1737
- ⛔ AND AN INTERMEDIATE THIS DOOR CANNOT READ REFUSES BY NAME. `product_data` is a compiled
1738
- registry module with no read-through binding, so the one enumerated path that passes through it
1739
- answers a sentence carrying the cause and a way round it, rather than an empty grid.
1740
-
1741
- ⚠ NO CAP, AND THE COST IS REPORTED INSTEAD (standing rule 1). Every distinct value comes back,
1742
- however many there are, and the reader is told through `limits` that this tab resolves a second
1743
- database on every page.
1744
- """
1745
- import core.relations as relations
1746
- from fastapi import HTTPException # noqa: PLC0415
1747
-
1748
- value = _related_source_value(session, first, record)
1749
- if value in (None, ""):
1750
- raise err(400, "unknown_relation",
1751
- relations.unresolvable_source_refusal(source, first))
1752
- try:
1753
- mid = _compiled_read(mid_key, session)
1754
- except HTTPException as exc:
1755
- why = ""
1756
- if isinstance(getattr(exc, "detail", None), dict):
1757
- why = str((exc.detail.get("error") or {}).get("message") or "")
1758
- raise err(409, "relation_not_served",
1759
- f"this relation reaches '{last.get('target')}' through '{mid_key}', and that "
1760
- f"database could not be read here to follow it"
1761
- + (f" ({why})" if why else "")
1762
- + f". Open '{mid_key}' on its own, find the records this one is linked to, and "
1763
- f"follow the next relation from there")
1764
- mid_spec = mid["spec"]
1765
- on1 = str((first.get("via") or {}).get("on") or "")
1766
- step = (mid_spec.get("cols") or {}).get(on1)
1767
- if not step:
1768
- raise err(409, "relation_not_served",
1769
- f"'{mid_key}' has no live expression for '{on1}', which is the column the first "
1770
- f"hop of this relation joins on, so the traversal cannot be resolved. Open "
1771
- f"'{mid_key}' on its own, or ask for '{on1}' to be added to its live connection")
1772
- # ⭐ THE COLUMN HOP 2 IS KEYED ON, READ OFF THE INTERMEDIATE. `pid` is the row IDENTITY and is
1773
- # not a column of the mirror spec, so it resolves to the spec's own identity expression, which
1774
- # is the same one this route trusts everywhere else and is per table rather than a bare `id`.
1775
- frm2 = str((last.get("via") or {}).get("from") or relations.IDENTITY_COL)
1776
- take = (mid_spec["id"] if frm2 == relations.IDENTITY_COL
1777
- else ((mid_spec.get("cols") or {}).get(frm2) or (None,))[0])
1778
- if not take:
1779
- raise err(409, "relation_not_served",
1780
- f"'{mid_key}' has no live expression for '{frm2}', which is the value the second "
1781
- f"hop of this relation is keyed on, so the traversal cannot be resolved. Open "
1782
- f"'{mid_key}' on its own, or ask for '{frm2}' to be added to its live connection")
1783
- try:
1784
- value = step[1](value)
1785
- except Exception: # noqa: BLE001
1786
- value = str(value)
1787
- mid_from = mid_spec["from_sql"] if mid_spec.get("from_sql") else mid_spec["table"]
1788
- parts = [p for p in (mid["base_where"], first.get("where")) if p]
1789
- parts.append(f"{step[0]} = ?")
1790
- pred = " AND ".join(f"({p})" for p in parts)
1791
- rows = mid["cur"].execute(
1792
- f"SELECT DISTINCT {take} FROM {mid_from} WHERE {pred}",
1793
- list(mid["wall_params"]) + [value]).fetchall()
1794
- values = [r[0] for r in rows if r and r[0] is not None]
1795
- # ⭐⭐ STANDING RULE 1'S SECOND SENTENCE, AND `effect` IS CHOSEN SO THE READER GETS **THIS**
1796
- # SENTENCE RATHER THAN A NEIGHBOUR'S. `counts.ts::plainLimit` maps a known `effect` to one
1797
- # fixed client phrase and falls through to the SERVER's own first sentence for an effect it has
1798
- # not learned; `slow` maps to *"Rows this far down load slowly, each page is reached by walking
1799
- # every row above it"*, which is a true statement about a deep page and a FALSE one about a
1800
- # seven-row traversal. `traversal` is deliberately not in that table, so the strip prints the
1801
- # cause below, which is what actually happened.
1802
- # ⚠ THE FIRST CLAUSE IS THE ONE THAT REACHES THE STRIP: `firstSentence` cuts at the first full
1803
- # stop and truncates past 120 characters, so the mechanism is stated before the count.
1804
- notes.append({
1805
- "subject": "related", "effect": "traversal",
1806
- "cause": f"these rows are reached through '{mid_key}', so every page resolves that "
1807
- f"database first. This record matched {len(values):,} of its records, and this "
1808
- f"database is then narrowed to the rows those reach",
1809
- "recommendation": f"open '{mid_key}' on its own if you are paging through a large set, or "
1810
- f"filter this database beside the relation to ask a smaller question"})
1811
- return values
1812
 
1813
 
1814
  def _related_pin(table_key, session, spec, base_where, wall_params, cur, related):
1815
- """`(sql, params, notes)` for C6's pinned read, or `(None, [], [])` when nothing is pinned.
1816
-
1817
- ⛔⛔ WHY THIS DOES NOT CALL `compile_filter_tree(member_ids=)`, WHICH IS WHAT C6'S SENTENCE
1818
- SAYS. Measured against `platform/harness/filter_sql.py` on 2026-09-03, that call cannot express
1819
- a pinned read and the failure is silent in the widening direction, twice over:
1820
-
1821
- 1. `:583` returns None the moment the tree is INACTIVE, and the `member_ids` branch is BELOW
1822
- that return. A pin with no client filter is exactly the inactive case, so the ids would be
1823
- dropped and the whole table served.
1824
- 2. `:588` emits `(tree OR id_sql IN (...))`. Its own docstring: *"`member_ids` reproduces
1825
- `members.has(r.pid) || matchFilterTree(...)`"*. That is a UNION. ORing a pin onto a
1826
- filter WIDENS; a pinned read needs an INTERSECTION.
1827
-
1828
- So the tail is compiled by `core.relations.pin_sql`, in `filter_sql`'s OWN spelling (proven
1829
- byte for byte by `verify_pivot.py`, not by this comment), and ANDed in. `filter_sql.py` is lane
1830
- B's file this wave; a narrowing member mode there is an AMENDMENT and is booked in the handoff,
1831
- not edited in from here.
1832
-
1833
- ⭐ `id_sql` IS PASSED EXPLICITLY, AS `spec["id"]`, AND IS NEVER DEFAULTED. `harness/semantic.py`
1834
- defaults it to `f"{alias}.id"` inside its OWN compile calls; a call from the route layer never
1835
- reaches that line, and `filter_sql:586` RAISES without it. It matters that it is per table
1836
- rather than a literal `id`: `ut_odoo_order_lines` is join-shaped and its identity is `sol.id`,
1837
- so a bare `id` would be ambiguous across `sale_order_line` and `sale_order`. It is the same
1838
- expression this route already trusts as `tiebreak_sql` and as the fallback ORDER BY.
1839
-
1840
- ⭐⭐ W54-T40 / INSTRUCTION 22 / R12 — **A `via` MAY NOW BE A PATH, AND THE PATH IS SERVED.**
1841
- The owner's second quoted error was this function's own `bad_relation` sentence, and it fired
1842
- on 18 of the 25 rail tabs of `customer_data`: R12 says the client pins a traversal by naming
1843
- each edge, so a two-hop tab sends `via` as the ARRAY `["invoices","order_link"]`, and the
1844
- guard below accepted only the one-hop bag. MEASURED 2026-09-06, 6 of 25 tabs answered 200 and
1845
- 18 answered 400 on the first click.
1846
-
1847
- ⛔⛔ ACCEPTING THE ARRAY IS HALF A FIX AND WOULD HAVE MOVED THE ERROR RATHER THAN CLOSED IT.
1848
- `relations.pick` matches `via.direction` against `DIRECTIONS`, and a two-hop entry's direction
1849
- is the literal `path`, deliberately outside that tuple so nothing serves half a traversal. So
1850
- a path resolves through `relations.pick_path` against the DEPTH-AWARE listing, and the read is
1851
- then answered in TWO steps: hop 1 resolves the intermediate database's own rows to the values
1852
- hop 2 joins on, and hop 2 pins this database by them. Sending the object form alone answered
1853
- `400 unknown_relation` and changed nothing the reader could see.
1854
-
1855
- ⭐ EVERY HOP IS STILL PERMISSION CHECKED, AND AT PIN TIME, NOT ONLY AT LISTING TIME (R13). The
1856
- intermediate is resolved through `_compiled_read`, i.e. THE SAME compiler this door uses for
1857
- an ordinary read, so its grant, its row wall and its hidden-field closure all apply before a
1858
- single id crosses into this table's predicate. A second, laxer read of the intermediate would
1859
- be exactly the permission wall with a hole in it that `related_entries` exists to prevent.
1860
- ⛔ AND AN INTERMEDIATE THIS DOOR CANNOT READ IS A **REPORTED LIMIT**, never a silent empty:
1861
- `product_data` is a registry module with no read-through binding, so the one enumerated path
1862
- that passes through it refuses by name with a cause and a recommendation.
1863
- """
1864
  import core.relations as relations
1865
 
1866
  if isinstance(related, str):
1867
  related = _json_arg(related, "related")
1868
  if related in (None, "", {}):
1869
  return None, [], []
1870
- if not isinstance(related, dict):
1871
- raise err(400, "bad_relation",
1872
- "`related` must be an object naming the record to pin these rows to: "
1873
- "{table, record, via}")
1874
-
1875
- source = str(related.get("table") or "")
1876
- record = related.get("record")
1877
- via = related.get("via")
1878
- # ⭐⭐ W54-T40 — `via` IS EITHER ONE EDGE'S BAG OR A PATH OF EDGE KEYS, and `_via_path` is the
1879
- # one place that decides which. It answers None for the bag, which is what keeps the guard
1880
- # below spelling the SAME refusal for a genuinely incomplete pin.
1881
- path = _via_path(via)
1882
- if not source or record in (None, "") or (path is None and not isinstance(via, dict)):
1883
- raise err(400, "bad_relation",
1884
- "a pinned read needs the record's database, the record id and the relation to "
1885
- "follow, as {table, record, via}, where `via` is one relation or the array of "
1886
- "edge keys naming each hop. Ask GET /api/v1/grid/" + (source or "{table}")
1887
- + "/related for the relations this account may follow")
1888
-
1889
- from routes_grid import _may_open, related_entries, related_path_entries
1890
-
1891
- if not _may_open(session, source):
1892
- # ⚠ THE CAUSE IS NAMED AS A PAIR, ON PURPOSE. `_may_open` is fail-closed and answers False
1893
- # both for a genuine permission refusal and for a database it could not read at all, so a
1894
- # sentence claiming only the first would tell a reader their access was revoked when the
1895
- # store had merely hiccupped. Naming both is honest and still refuses.
1896
- raise err(403, "not_permitted",
1897
- f"'{source}' could not be opened for your account, either because it is not "
1898
- f"granted to you or because it could not be read just now, so rows here cannot "
1899
- f"be pinned to one of its records. Ask an administrator for access to that "
1900
- f"database, or try again")
1901
-
1902
- # ⛔ RESOLVED AGAINST THE **SCOPED** LISTING, which is what makes "an edge you cannot be
1903
- # offered is an edge you cannot pin" structural rather than remembered. `related_entries` is
1904
- # the same function `GET /grid/{table}/related` answers with; there is no second resolution.
1905
- # ⭐ W54-T40 — AND A PATH RESOLVES AGAINST THE DEPTH-AWARE LISTING, WHICH IS THE SAME RULE ONE
1906
- # LEVEL DEEPER: `related_path_entries` is what `GET /grid/{table}/related?depth=2` answers
1907
- # with, so a traversal this account is not offered is a traversal it cannot pin either.
1908
- # ⚠ THE DEPTH ASKED FOR IS THE LENGTH OF THE PATH, never a flat 2. A one-element path costs
1909
- # the depth-1 enumeration it needs and not the depth-2 one, which on `customer_data` is the
1910
- # difference between roughly half a second and roughly two.
1911
- if path is None:
1912
- entries = related_entries(session, source)
1913
- entry = relations.pick(entries, via)
1914
- else:
1915
- if len(path) > relations.MAX_DEPTH:
1916
- raise err(400, "over_depth", relations.over_depth_refusal(source, path))
1917
- entries = related_path_entries(session, source, len(path))
1918
- entry = relations.pick_path(entries, path)
1919
- if entry is None:
1920
- raise err(400, "unknown_relation", relations.unknown_via_refusal(source, via))
1921
- entry = dict(entry, __source__=source)
1922
-
1923
- if str(entry.get("target") or "") != str(table_key):
1924
- raise err(400, "unknown_relation",
1925
- f"the relation '{entry.get('key')}' on '{source}' points at "
1926
- f"'{entry.get('target')}', not at '{table_key}', so it cannot narrow this "
1927
- f"database. Read the database the relation names, or ask for the relation that "
1928
- f"reaches this one")
1929
- if not entry.get("served", True):
1930
- raise err(409, "relation_not_served", relations.unserved_target_refusal(entry))
1931
-
1932
- # ⭐⭐ W54-T40 — THE **LAST** HOP IS WHAT JOINS THIS DATABASE, and on a two-hop entry that is
1933
- # not `entry`. A composite carries `via = {direction: 'path', key, path}` and NO `on`, no
1934
- # `from` and no `where`: `relations._two_hop_entry` refuses to flatten the two hops' predicates
1935
- # onto the pair, because one of them may carry a predicate the other does not (the open-invoice
1936
- # bridge is exactly that edge). So the legs are resolved, each from its OWN table's scoped
1937
- # listing, and the last one is what this block below reads.
1938
  notes = []
1939
- first, mid_key, last = entry, "", entry
1940
- if len(entry.get("path") or ()) > 1:
1941
- first, mid_key, last = _related_path_legs(session, source, entry, entries)
1942
-
1943
- on = str((last.get("via") or {}).get("on") or "")
1944
- # ⚠ `spec["cols"]`, NOT the caller's narrowed `cols`. The join column is a JOIN, not a value
1945
- # this response returns: a relation must keep working when an administrator has hidden the id
1946
- # column it runs over, and no cell of it is ever projected. The hidden-field closure still
1947
- # governs everything that reaches the wire, one layer up.
1948
- # ⭐⭐ W54-T40 — AND THE ROW IDENTITY IS NOT ONE OF THOSE COLUMNS. `relations` defaults an edge
1949
- # with no declared `on` to `pid`, which is the wire's name for the row identity and is never a
1950
- # key of a mirror spec's `cols` (measured across all eight bound grains on 2026-09-06: not one
1951
- # carries it). Every such edge therefore refused with "has no live expression for 'pid'" while
1952
- # the expression was in hand the whole time, as `spec["id"]` - the same per-table identity this
1953
- # route already uses for the pin itself, for the tiebreak and for the fallback ORDER BY, and
1954
- # deliberately not a bare `id`, which is ambiguous on a join-shaped grain.
1955
- if on == relations.IDENTITY_COL:
1956
- binding = (spec["id"], int)
1957
- else:
1958
- binding = (spec.get("cols") or {}).get(on)
1959
- if not binding:
1960
- raise err(409, "relation_not_served",
1961
- f"'{table_key}' has no live expression for '{on}', which is the column this "
1962
- f"relation joins on, so the rows cannot be narrowed to one record here. Open "
1963
- f"this database directly, or ask for '{on}' to be added to its live connection")
1964
- on_expr, on_cast = binding[0], binding[1]
1965
-
1966
- if mid_key:
1967
- # ⭐ HOP 1, ANSWERED BY THE INTERMEDIATE DATABASE ITSELF, UNDER ITS OWN WALL. See
1968
- # `_related_hop_values`. An empty answer is an ANSWER (this record reaches nothing through
1969
- # that database) and compiles to `1=0` two blocks down, never to "no pin".
1970
- values = _related_hop_values(session, source, record, first, mid_key, last, notes)
1971
- else:
1972
- value = _related_source_value(session, entry, record)
1973
- if value in (None, ""):
1974
- raise err(400, "unknown_relation",
1975
- relations.unresolvable_source_refusal(source, entry))
1976
- values = [value]
1977
- cast = []
1978
- for one in values:
1979
- try:
1980
- cast.append(on_cast(one))
1981
- except Exception: # noqa: BLE001
1982
- cast.append(str(one))
1983
-
1984
- # ── the member ids, in ONE SQL over the bridge column (the ticket's `how:`) ────────────────
1985
- # ⛔ NOT THROUGH `datastore.window`: that clamps at `WINDOW_MAX` (5,000) rows, so a customer
1986
- # with more order lines than that would be pinned to the first 5,000 of them and the tab would
1987
- # show a smaller, entirely plausible number with nothing red anywhere. Standing rule 1: no cap
1988
- # on data from a connected source.
1989
- # ⚠ THE WALL RIDES ALONG. Resolving ids under `base_where` means the id SET a scoped reader can
1990
- # produce is already narrowed to rows they may see, so the pin cannot be used to learn how many
1991
- # rows exist beyond their boundary.
1992
- # ⭐ W54-T40 — `= ?` FOR ONE VALUE AND `IN (...)` FOR MANY, and the one-value spelling is kept
1993
- # BYTE FOR BYTE so a one-hop pin compiles exactly the SQL it compiled before this ticket. The
1994
- # many-value arm is only ever reached by the second hop of a traversal.
1995
- frm_body = spec["from_sql"] if spec.get("from_sql") else spec["table"]
1996
- ids = []
1997
- if cast:
1998
- parts = [p for p in (base_where, last.get("where")) if p]
1999
- parts.append(f"{on_expr} = ?" if len(cast) == 1
2000
- else f"{on_expr} IN ({','.join('?' for _ in cast)})")
2001
- pred = " AND ".join(f"({p})" for p in parts)
2002
- ids = [int(r[0]) for r in cur.execute(
2003
- f'SELECT DISTINCT {spec["id"]} FROM {frm_body} WHERE {pred}',
2004
- list(wall_params) + list(cast)).fetchall() if r and r[0] is not None]
2005
-
2006
- # ⭐ STANDING RULE 1'S SECOND SENTENCE, ON A COST RATHER THAN ON A CAP. Nothing is limited
2007
- # here; the reader is told that this particular relation is answered by reading the source
2008
- # database once per page, because it is keyed on a column rather than on the record id.
2009
- if str((first.get("via") or {}).get("from") or "") != relations.IDENTITY_COL:
2010
- notes.append({
2011
- "subject": "related", "effect": "slow",
2012
- "cause": f"this relation is keyed on the '{first['via']['from']}' column of "
2013
- f"'{source}' rather than on its record id, so every page of these rows is "
2014
- f"resolved by reading that database first",
2015
- "recommendation": "read this database on its own and filter it on "
2016
- f"'{on}' if you are paging through a large set"})
2017
- if len(ids) >= _PIN_REPORT_AT:
2018
  notes.append({
2019
  "subject": "related", "effect": "slow",
2020
- "cause": f"this record is linked to {len(ids):,} rows, and each page names every one "
2021
- f"of them in the query that narrows this database to them",
2022
- "recommendation": "add a filter beside the relation to ask a smaller question, or "
2023
- "read this database on its own"})
2024
-
2025
- sql, params = relations.pin_sql(spec["id"], ids)
2026
  return sql, params, notes
2027
 
2028
 
@@ -2615,6 +2478,87 @@ def _compiled_read(table_key, session, *, filters=None, filterConj="and", sorts=
2615
  "pred": pred}
2616
 
2617
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2618
  @router.get("/odoo-tables/{table_key}/rows")
2619
  def odoo_table_rows(table_key: str,
2620
  offset: int = Query(default=0, ge=0),
@@ -2652,6 +2596,10 @@ def odoo_table_rows(table_key: str,
2652
  import core.perm_scope as perm_scope
2653
  from harness import datastore
2654
 
 
 
 
 
2655
  # ⛔⛔ ONE COMPILER, AND THE AGGREGATES DOOR CALLS THE SAME ONE. The permission wall, the
2656
  # hidden-field closure, the user predicate and the search all live in `_compiled_read` above,
2657
  # because C1 promises that `/aggregates` answers over *the same compiled predicate this window
@@ -3041,6 +2989,13 @@ def odoo_table_aggregates(table_key: str, body: dict = Body(default=None),
3041
  if group_by is not None and not isinstance(group_by, str):
3042
  raise err(400, "bad_selection", "groupBy must be a column id")
3043
 
 
 
 
 
 
 
 
3044
  # ⛔⛔ THE PIN RIDES THE **SAME** COMPILER, AND THIS ONE LINE IS THE WHOLE OF CORRECTION (3).
3045
  # `/rows` takes `related` as a JSON query STRING and this door takes it as a BODY KEY; a worker
3046
  # who assumed both were bodies would have wired the rows and left the summaries answering over
 
23
  import hmac
24
  import json
25
  import time
26
+ from contextlib import contextmanager
27
 
28
  from fastapi import Body, Depends, HTTPException
29
  from fastapi import APIRouter, Query
 
1517
  return None
1518
 
1519
 
1520
+ def _materialised_table(table_key):
1521
+ """Storage dispatch, independent of the browser's fallible status roster."""
1522
+ return module_cache_source(table_key) is not None or table_key not in _sources()
1523
+
1524
+
1525
+ def _relation_rows(session, table, columns, *, ids=None, match=None, where=None):
1526
+ """Internal join values, after the ordinary row wall, with no row-count ceiling.
1527
+
1528
+ Join columns may be hidden on the wire. Only identities leave the resolver; the native
1529
+ payload builders still apply their complete hidden-field closure before returning cells.
1530
+ """
1531
+ import core.perm_scope as perm_scope
1532
+ import core.relations as relations
1533
+
1534
+ columns = set(columns) | {relations.IDENTITY_COL}
1535
+ if not _materialised_table(table):
1536
+ read = _compiled_read(table, session)
1537
+ spec = read["spec"]
1538
+ bindings = dict(spec["cols"], pid=(spec["id"], int))
1539
+ if columns - set(bindings):
1540
+ raise err(409, "relation_target_unavailable", "A required relation column is unavailable.")
1541
+ parts = [p for p in (read["where"], where) if p]
1542
+ params = list(read["params"])
1543
+ for key, values in (("pid", ids), match or ("pid", None)):
1544
+ if values is None:
1545
+ continue
1546
+ expr, cast = bindings[key]
1547
+ values = list(values)
1548
+ parts.append(f"{expr} IN ({','.join('?' for _ in values)})" if values else "1=0")
1549
+ params.extend(cast(value) for value in values)
1550
+ names = sorted(columns)
1551
+ projection = ", ".join(bindings[key][0] for key in names)
1552
+ source = spec.get("from_sql") or spec["table"]
1553
+ predicate = " AND ".join(f"({part})" for part in parts) or "1=1"
1554
+ return [dict(zip(names, row)) for row in read["cur"].execute(
1555
+ f"SELECT {projection} FROM {source} WHERE {predicate}", params).fetchall()]
1556
+
1557
+ # This is an internal join, never a cell response. Apply the same permanent wall on the
1558
+ # complete contract before taking any join value, including a join on a hidden column.
1559
+ if not perm_scope.may_read(session.user, table, st=session.runtime):
1560
+ raise err(403, "forbidden_table", "This account cannot open the linked database.")
1561
+ if module_cache_source(table) is not None:
1562
+ session.require(table)
1563
+ fields, rows = perm_scope._read(table, session.user, session.runtime)
1564
+ rows = perm_scope.apply_row_scope(rows, session.user, table, fields, st=session.runtime)
1565
+ if where:
1566
+ raise err(409, "relation_target_unavailable", "This relation needs a connected database predicate.")
1567
+ if ids is not None:
1568
+ wanted = {str(value) for value in ids}
1569
+ rows = [row for row in rows if str(row.get("pid")) in wanted]
1570
+ if match is not None:
1571
+ key, values = match
1572
+ wanted = {str(value) for value in values}
1573
+ rows = [row for row in rows if str(row.get(key)) in wanted]
1574
+ return [{key: row.get(key) for key in columns} for row in rows]
1575
+
1576
+
1577
+ def _relation_cell_ids(value):
1578
+ """Stored link cells contain comma-separated identities, not a scalar join value."""
1579
+ parts = value if isinstance(value, (list, tuple, set)) else str(value or "").split(",")
1580
+ return {str(int(part)) for part in parts if str(part).strip().isdigit() and int(part) > 0}
1581
+
1582
+
1583
+ def _relation_leg_ids(session, source, source_ids, entry):
1584
+ """Follow one declared leg, including manual, inverse and through links."""
1585
+ target = str(entry["target"])
1586
+ via = entry.get("via") or {}
1587
+ link = entry.get("link") or {}
1588
+ reverse = via.get("direction") == "reverse"
1589
+ frm, on = str(via.get("from") or "pid"), str(via.get("on") or "pid")
1590
+ field = str(via.get("field") or "")
1591
+ manual = bool(field and link and not link.get("inverse")
1592
+ and (link.get("selectionMode") == "manual" or not link.get("on")))
1593
+ inverse = str(link.get("inverse") or "")
1594
+ source_col, target_col = frm, on
1595
+ if manual:
1596
+ source_col, target_col = ("pid", field) if reverse else (field, "pid")
1597
+ elif inverse:
1598
+ source_col, target_col = (inverse, "pid") if reverse else ("pid", inverse)
1599
+ source_rows = _relation_rows(session, source, [source_col], ids=source_ids)
1600
+ values = {str(row[source_col]) for row in source_rows if row.get(source_col) not in (None, "")}
1601
+ if (manual and not reverse) or (inverse and reverse):
1602
+ values = set().union(*(_relation_cell_ids(row.get(source_col)) for row in source_rows))
1603
+ target_col = "pid"
1604
+ through = link.get("through") if not manual else None
1605
+ if through:
1606
+ left = str(link["throughTo"] if reverse else link["throughOn"])
1607
+ right = str(link["throughOn"] if reverse else link["throughTo"])
1608
+ middle = _relation_rows(session, str(through), [left, right], match=(left, values))
1609
+ values = {str(row[right]) for row in middle if row.get(right) not in (None, "")}
1610
+ if (manual and reverse) or (inverse and not reverse):
1611
+ rows = _relation_rows(session, target, [target_col])
1612
+ rows = [row for row in rows if _relation_cell_ids(row.get(target_col)) & values]
1613
+ else:
1614
+ rows = _relation_rows(session, target, [target_col], match=(target_col, values),
1615
+ where=entry.get("where"))
1616
+ return {int(row["pid"]) for row in rows}
1617
+
1618
+
1619
+ def _relation_target_ids(session, target, related):
1620
+ """One pin resolver for SQL, pool and tenant rows, selected from the scoped path list."""
1621
+ import core.relations as relations
1622
+ from routes_grid import _may_open, related_path_entries
1623
+
1624
+ if isinstance(related, str):
1625
+ related = _json_arg(related, "related")
1626
+ if not isinstance(related, dict) or not related.get("table") or related.get("record") in (None, ""):
1627
+ raise err(400, "bad_relation", "A pinned read needs {table, record, via}.")
1628
+ source = str(related["table"])
1629
+ via = related.get("via")
1630
+ path = _via_path(via)
1631
+ if path and len(path) > relations.MAX_DEPTH:
1632
+ raise err(400, "over_depth", relations.over_depth_refusal(source, path))
1633
+ if not _may_open(session, source):
1634
+ raise err(403, "forbidden_table", "This account cannot open the source database.")
1635
+ entries = related_path_entries(session, source, len(path) if path else 1)
1636
+ entry = relations.pick_path(entries, path) if path else relations.pick(entries, via)
1637
+ if entry is None or str(entry.get("target")) != str(target):
1638
+ raise err(400, "unknown_relation", relations.unknown_via_refusal(source, via))
1639
+ try:
1640
+ ids = {int(related["record"])}
1641
+ except (TypeError, ValueError):
1642
+ raise err(400, "bad_relation", "The source record must have an integer identity.")
1643
+ legs = [(source, entry)]
1644
+ if len(entry.get("path") or ()) > 1:
1645
+ first, middle, last = _related_path_legs(session, source, entry, entries)
1646
+ legs = [(source, first), (middle, last)]
1647
+ for table, leg in legs:
1648
+ if not _may_open(session, leg["target"]):
1649
+ raise err(403, "forbidden_table", "This account cannot open the linked database.")
1650
+ ids = _relation_leg_ids(session, table, ids, leg)
1651
+ return ids
1652
+
1653
+
1654
+ def narrow_related_rows(session, table_key, rows, related):
1655
+ """Intersect an already walled and stripped payload with one resolved identity set."""
1656
+ if related in (None, "", {}):
1657
+ return rows
1658
+ ids = _relation_target_ids(session, table_key, related)
1659
+ return [row for row in rows if int(row["pid"]) in ids]
1660
+
1661
+
1662
  def _cache_relation_plan(session, source, via, target):
1663
  """The offered module link and its explicit bridge, or a cause-specific refusal.
1664
 
 
1744
 
1745
 
1746
  def _cache_relation_target_ids(session, source, record, via, target):
1747
+ """Resolve any offered path; retain the legacy Products ordered string transport."""
1748
+ if not (source == "customer_data" and target == "product_data" and via == "products_ordered"):
1749
+ ids = _relation_target_ids(session, target, {"table": source, "record": record, "via": via})
1750
+ return {"ok": True, "target": str(target), "ids": sorted(ids)}
1751
  entry, _link, through, through_on, through_to, on = _cache_relation_plan(
1752
  session, source, via, target)
1753
  source_value = _cache_relation_source_value(session, entry, record)
 
1804
  via: str = Query(...), target: str = Query(...),
1805
  session: Session = Depends(require_session)):
1806
  """Target pids for a declared relation whose destination is a runtime-cache database."""
1807
+ parsed_via = _json_arg(via, "via") if via.startswith(("[", "{")) else via
1808
+ return _cache_relation_target_ids(session, source, record, parsed_via, target)
1809
 
1810
 
1811
  def _via_path(via):
 
1868
  return dict(first, __source__=source), mid_key, dict(last, __source__=mid_key)
1869
 
1870
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1871
 
1872
 
1873
  def _related_pin(table_key, session, spec, base_where, wall_params, cur, related):
1874
+ """Compile the same resolved identity set on both mirror transports, as an intersection."""
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1875
  import core.relations as relations
1876
 
1877
  if isinstance(related, str):
1878
  related = _json_arg(related, "related")
1879
  if related in (None, "", {}):
1880
  return None, [], []
1881
+ ids = _relation_target_ids(session, table_key, related)
1882
+ sql, params = relations.pin_sql(spec["id"], sorted(ids))
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1883
  notes = []
1884
+ if len(ids) > _PIN_REPORT_AT:
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1885
  notes.append({
1886
  "subject": "related", "effect": "slow",
1887
+ "cause": f"This relation matched {len(ids):,} records, all of which are included.",
1888
+ "recommendation": "Add a filter to reduce the result while continuing to page through every match."})
 
 
 
 
1889
  return sql, params, notes
1890
 
1891
 
 
2478
  "pred": pred}
2479
 
2480
 
2481
+ @contextmanager
2482
+ def _materialised_read(table_key, session, query, related):
2483
+ """One compiler for native rows and their aggregate sibling, over the walled payload.
2484
+
2485
+ The temporary connection contains only this request's already stripped, pinned rows and is
2486
+ closed before returning. It never registers data on the tenant's shared mirror connection.
2487
+ """
2488
+ import duckdb
2489
+
2490
+ if table_key == "customer_data":
2491
+ from routes_customers import _payload
2492
+ session.require(table_key)
2493
+ payload = _payload(session, related=related)
2494
+ elif table_key == "product_data":
2495
+ from routes_products import products
2496
+ session.require(table_key)
2497
+ payload = products(session=session, related=related)
2498
+ else:
2499
+ from routes_tables import table_rows
2500
+ payload = table_rows(table_key, session=session, related=related)
2501
+ fields = payload["fields"]
2502
+ with duckdb.connect(":memory:") as cur:
2503
+ cur.execute("CREATE TABLE pinned_rows AS SELECT value AS payload FROM json_each(?)",
2504
+ [json.dumps(payload["rows"], default=str)])
2505
+ bindings = {}
2506
+ for field in fields:
2507
+ key = str(field["key"])
2508
+ pointer = ("/" + key.replace("~", "~0").replace("/", "~1")).replace("'", "''")
2509
+ expr = f"json_extract_string(payload, '{pointer}')"
2510
+ numeric = field.get("type") in ("int", "currency", "pct", "float", "number")
2511
+ bindings[key] = (f"TRY_CAST({expr} AS DOUBLE)" if numeric else expr,
2512
+ float if numeric else str)
2513
+ spec = {"table": "pinned_rows", "id": "CAST(json_extract_string(payload, '/pid') AS BIGINT)",
2514
+ "cols": bindings, "where": None}
2515
+ cols = _filter_columns(spec, fields)
2516
+ limits = list(payload.get("limits") or [])
2517
+ tree, cohorts = _views_as_cohorts(query["filters"], table_key, session, spec, cols,
2518
+ None, [], cur, limits)
2519
+ missing = _leaf_cols(tree) - _PSEUDO_COLS - set(cols)
2520
+ if missing:
2521
+ raise err(400, "filter_unsupported", "A filter names a column unavailable to this account.")
2522
+ try:
2523
+ pred = _fs().compile_filter_tree(tree, conj=query["filterConj"], columns=cols,
2524
+ id_sql=spec["id"], today=payload.get("today") or _today(),
2525
+ cohort_sets=cohorts)
2526
+ except ValueError as exc:
2527
+ raise err(400, "filter_unsupported", str(exc))
2528
+ if pred is not None and pred.uses_aggregate:
2529
+ raise err(400, "filter_unsupported", "This condition cannot be evaluated for individual rows.")
2530
+ where, params = (pred.sql, list(pred.params)) if pred is not None else (None, [])
2531
+ search = _fs().compile_search(query["search"], cols) if query["search"] else None
2532
+ if search is not None:
2533
+ where = f"({where}) AND {search.sql}" if where else search.sql
2534
+ params.extend(search.params)
2535
+ yield {"cur": cur, "spec": spec, "cols": cols, "where": where, "params": params,
2536
+ "frm": {"table": "pinned_rows"}, "limits": limits, "payload": payload}
2537
+
2538
+
2539
+ def _materialised_window(table_key, session, offset, limit, filters, filterConj, sorts, search, related):
2540
+ from harness import datastore
2541
+
2542
+ query = _selection_query({"filters": _json_arg(filters, "filters"), "filterConj": filterConj,
2543
+ "sorts": _json_arg(sorts, "sorts"), "search": search})
2544
+ with _materialised_read(table_key, session, query, related) as read:
2545
+ spec = read["spec"]
2546
+ order = _fs().compile_order_by(query["sorts"], read["cols"], tiebreak_sql=spec["id"])
2547
+ win = datastore.window(select=f'{spec["id"]} AS pid', where=read["where"],
2548
+ params=tuple(read["params"]), order_by=order or spec["id"],
2549
+ offset=offset, limit=limit or None, cur=read["cur"], **read["frm"])
2550
+ payload = read["payload"]
2551
+ by_id = {int(row["pid"]): row for row in payload["rows"]}
2552
+ rows = [by_id[int(row[0])] for row in win["rows"]]
2553
+ if win["clamped"]:
2554
+ read["limits"].append({"subject": "limit", "effect": "window_clamped",
2555
+ "cause": f"One response carries at most {datastore.WINDOW_MAX} rows to bound response memory.",
2556
+ "recommendation": "Continue paging with offset. Every matching row remains available."})
2557
+ return {**payload, "ok": True, "rows": rows, "total": win["total"],
2558
+ "totalUnfiltered": len(by_id), "offset": win["offset"], "limit": win["limit"],
2559
+ "limits": read["limits"], "scope": {"table": table_key, "readThrough": True}}
2560
+
2561
+
2562
  @router.get("/odoo-tables/{table_key}/rows")
2563
  def odoo_table_rows(table_key: str,
2564
  offset: int = Query(default=0, ge=0),
 
2596
  import core.perm_scope as perm_scope
2597
  from harness import datastore
2598
 
2599
+ if _materialised_table(table_key):
2600
+ return _materialised_window(table_key, session, offset, limit, filters, filterConj,
2601
+ sorts, search, related)
2602
+
2603
  # ⛔⛔ ONE COMPILER, AND THE AGGREGATES DOOR CALLS THE SAME ONE. The permission wall, the
2604
  # hidden-field closure, the user predicate and the search all live in `_compiled_read` above,
2605
  # because C1 promises that `/aggregates` answers over *the same compiled predicate this window
 
2989
  if group_by is not None and not isinstance(group_by, str):
2990
  raise err(400, "bad_selection", "groupBy must be a column id")
2991
 
2992
+ if _materialised_table(table_key):
2993
+ with _materialised_read(table_key, session, query, payload.get("related")) as read:
2994
+ out = _aggregate_over(read["cur"], read["spec"], read["cols"], read["where"],
2995
+ read["params"], read["frm"], aggs, group_by=group_by,
2996
+ limits=read["limits"])
2997
+ return {"ok": True, **out, "scope": {"table": table_key, "readThrough": True}}
2998
+
2999
  # ⛔⛔ THE PIN RIDES THE **SAME** COMPILER, AND THIS ONE LINE IS THE WHOLE OF CORRECTION (3).
3000
  # `/rows` takes `related` as a JSON query STRING and this door takes it as a BODY KEY; a worker
3001
  # who assumed both were bodies would have wired the rows and left the summaries answering over
api/routes_products.py CHANGED
@@ -561,7 +561,7 @@ def product_assembly(session: Session, scope: str = "product", storage_key: str
561
 
562
 
563
  @router.get("/products")
564
- def products(session: Session = Depends(module_gate(MODULE))):
565
  """The product table for this session's scope — the /customers envelope byte-for-byte
566
  (`{fields, rows, today, pulled_at}`) plus two additive keys (`identity`, `scope`).
567
 
@@ -573,13 +573,21 @@ def products(session: Session = Depends(module_gate(MODULE))):
573
  import aios_grid
574
  import modules.product_data as pd
575
 
576
- g = product_assembly(session)
577
  rows = aios_grid.rows_from_pool(
578
  g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"])
579
  rows = _seed_image(_seed_shared(rows, g["rows_src"], g["fields"]), g["fields"])
580
  from core import user_tables as _zones
581
  rows = _zones.zone_cells("product_data", rows, allowed_row_ids=g["pids"],
582
  st=session.runtime)
 
 
 
 
 
 
 
 
583
  # ⭐⭐ W41-T17 (owner instruction 25) — THE IDENTITY REPORT RIDES THE ENVELOPE, because a
584
  # report nothing reads is not a report. `product_data.identity_report` is standing rule 1's
585
  # second sentence as data for this grid's two identity columns: `product_id` (the Odoo
@@ -599,12 +607,21 @@ def products(session: Session = Depends(module_gate(MODULE))):
599
  # The envelope check beside it filters to the four `/customers` keys, so an additive key is
600
  # the shape this route already established with `identity` and `scope`.
601
  return {"fields": g["fields"], "rows": rows,
 
 
602
  "today": g["today"], "pulled_at": time.strftime("%Y-%m-%d %H:%M"),
603
  "identity": {"pid": "pid", "businessKey": "code"},
604
  "identity_report": pd.identity_report(g["rows_src"]),
605
  "scope": {"team_id": g["team_id"], "consolidated": g["team_id"] is None}}
606
 
607
 
 
 
 
 
 
 
 
608
  @router.patch("/products/{pid}")
609
  def patch_product(pid: int, body: dict = Body(default=None),
610
  session: Session = Depends(module_gate(MODULE))):
 
561
 
562
 
563
  @router.get("/products")
564
+ def products(session: Session = Depends(module_gate(MODULE)), related: str = None):
565
  """The product table for this session's scope — the /customers envelope byte-for-byte
566
  (`{fields, rows, today, pulled_at}`) plus two additive keys (`identity`, `scope`).
567
 
 
573
  import aios_grid
574
  import modules.product_data as pd
575
 
576
+ g = product_assembly(session, consume_corrections=not bool(related))
577
  rows = aios_grid.rows_from_pool(
578
  g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"])
579
  rows = _seed_image(_seed_shared(rows, g["rows_src"], g["fields"]), g["fields"])
580
  from core import user_tables as _zones
581
  rows = _zones.zone_cells("product_data", rows, allowed_row_ids=g["pids"],
582
  st=session.runtime)
583
+ from routes_odoo_tables import narrow_related_rows
584
+ rows = narrow_related_rows(session, MODULE, rows, related)
585
+ from routes_tables import scope_linked_metrics, linked_metric_limits
586
+ rows, g['fields'], metric_refusals = scope_linked_metrics(
587
+ session, MODULE, rows, g['fields'], g['measures'], related)
588
+ if related:
589
+ pinned = {row["pid"] for row in rows}
590
+ g["rows_src"] = [row for row in g["rows_src"] if row["pid"] in pinned]
591
  # ⭐⭐ W41-T17 (owner instruction 25) — THE IDENTITY REPORT RIDES THE ENVELOPE, because a
592
  # report nothing reads is not a report. `product_data.identity_report` is standing rule 1's
593
  # second sentence as data for this grid's two identity columns: `product_id` (the Odoo
 
607
  # The envelope check beside it filters to the four `/customers` keys, so an additive key is
608
  # the shape this route already established with `identity` and `scope`.
609
  return {"fields": g["fields"], "rows": rows,
610
+ "refusals": metric_refusals,
611
+ "limits": linked_metric_limits(metric_refusals),
612
  "today": g["today"], "pulled_at": time.strftime("%Y-%m-%d %H:%M"),
613
  "identity": {"pid": "pid", "businessKey": "code"},
614
  "identity_report": pd.identity_report(g["rows_src"]),
615
  "scope": {"team_id": g["team_id"], "consolidated": g["team_id"] is None}}
616
 
617
 
618
+ @router.post("/products/aggregates")
619
+ def product_aggregates(body: dict = Body(default=None),
620
+ session: Session = Depends(module_gate(MODULE))):
621
+ from routes_odoo_tables import odoo_table_aggregates
622
+ return odoo_table_aggregates(MODULE, body=body, session=session)
623
+
624
+
625
  @router.patch("/products/{pid}")
626
  def patch_product(pid: int, body: dict = Body(default=None),
627
  session: Session = Depends(module_gate(MODULE))):
api/routes_sheet.py CHANGED
@@ -248,6 +248,159 @@ def _registry_assembly(session: Session, table_key: str):
248
  "shown rather than shown from an older set of columns. Try again in a moment.")
249
 
250
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
251
  def _registry_mirror(session: Session, cur, table_key: str, metric_window, needed=None):
252
  """`(cursor, spec, columns)` for one compiled registry grid, at the cell's own period.
253
 
@@ -642,10 +795,8 @@ def _refuse(exc):
642
  nothing else, so the 409 and the 413 are raised here directly rather than by bending `err`,
643
  which would change the error shape of every route in the app.
644
 
645
- ⚠ `workbook_revision_stale` (the PUT door's code) ALSO ENDS `_stale` and still lands here. It
646
- carries no `rev_current`, so its body is unchanged and the client's existing PUT branch keeps
647
- working. ⭐ D-639's `index_revision_stale` lands here too and DOES carry one, so the rail's
648
- new guard needed no branch of its own: matching the family's spelling was the whole cost.
649
  """
650
  if exc.code in _CAP_CODES:
651
  return HTTPException(status_code=413,
@@ -739,13 +890,22 @@ def _role_on_workbook(session: Session, book):
739
  round because a workbook that has never been shared has no registry record at all. Asking
740
  `shares.role_for` alone would answer `None` for the person who created it.
741
  """
742
- from core import shares
743
- if session.admin:
744
- return "owner"
745
- me = str(session.uname or "").strip().lower()
746
- if me and _workbook_owner(book) == me:
747
- return "owner"
748
- return shares.role_for("workbook", book.get("id"), me, st=_store(session))
 
 
 
 
 
 
 
 
 
749
 
750
 
751
  def _require_editor(session: Session, book):
@@ -778,6 +938,8 @@ def _wire_shares(rows):
778
  out = []
779
  for row in rows or ():
780
  row = dict(row)
 
 
781
  row["shares"] = [{"who": s.get("who"), "role": wire_role(s.get("role"))}
782
  for s in (row.get("shares") or [])
783
  if wire_role(s.get("role"))]
@@ -809,7 +971,24 @@ def _binding_scope_key(session: Session, database: str, binding: dict) -> str:
809
  return sheets.scope_hash(database, wall_tree, (binding or {}).get("scope") or {})
810
 
811
 
812
- def _reresolved_for_reader(session: Session, book):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
813
  """A COPY of `book` whose every bound cell was recomputed under THIS reader's scope (C5).
814
 
815
  ⛔⛔ IN MEMORY, AND IT MUST NEVER PERSIST. `refresh_sheet` runs the same loop and ends with
@@ -850,6 +1029,8 @@ def _reresolved_for_reader(session: Session, book):
850
  for addr, cell in (tab.get("cells") or {}).items():
851
  if not isinstance(cell, dict) or cell.get("kind") != "bound":
852
  continue
 
 
853
  touched += 1
854
  binding = cell.get("binding") or {}
855
  db = str(binding.get("database") or "")
@@ -872,7 +1053,7 @@ def _reresolved_for_reader(session: Session, book):
872
  cell_key = tab_ref + "!" + addr
873
  scope_key = _binding_scope_key(session, db, binding)
874
  hit = None
875
- if wid and scope_key:
876
  try:
877
  hit = sheets.cached_scope_value(store, wid, cell_key, scope_key)
878
  except Exception: # noqa: BLE001
@@ -890,7 +1071,7 @@ def _reresolved_for_reader(session: Session, book):
890
  continue
891
 
892
  try:
893
- out = _resolve_binding(session, binding, view_memo=view_memo)
894
  except HTTPException as exc:
895
  detail = getattr(exc, "detail", None) or {}
896
  info = detail.get("error") if isinstance(detail, dict) else None
@@ -901,6 +1082,7 @@ def _reresolved_for_reader(session: Session, book):
901
  "code": (info or {}).get("code", "sheet_unresolved"),
902
  "message": (info or {}).get("message", "This cell could not be refreshed."),
903
  }
 
904
  continue
905
  cell["state"] = "fresh"
906
  cell["value"] = out["value"]
@@ -932,15 +1114,24 @@ def _reresolved_for_reader(session: Session, book):
932
  return fresh
933
 
934
 
 
 
 
 
 
 
 
935
  def _read_for(session: Session, book):
936
  """The workbook this session is entitled to see: stored for the owner, re-resolved otherwise.
937
 
938
- ⚠ A STRANGER IS A NON-OWNER AND TAKES THE SAME PATH, deliberately. Nothing in this file
939
- refuses a stranger's READ today (see the module note the measurement is booked under), so the
940
- fail-closed answer to "what should they be shown" is: whatever THEIR OWN scope computes,
941
- never the owner's cached numbers.
942
  """
 
943
  if _role_on_workbook(session, book) == "owner":
 
 
 
944
  return book
945
  return _reresolved_for_reader(session, book)
946
 
@@ -951,8 +1142,7 @@ def list_sheets(session: Session = Depends(require_session)):
951
 
952
  ⚠ C5's `shares` rides here as well as on `/sheets/index`, because the client reads both.
953
  """
954
- from core import sheets
955
- rows = sheets.project_shares(_store(session), sheets.list_workbooks(_store(session)))
956
  return {"workbooks": _wire_shares(rows)}
957
 
958
 
@@ -967,7 +1157,7 @@ def create_sheet(body: dict = Body(default=None), session: Session = Depends(req
967
  created_by=session.uname)
968
  except sheets.SheetRefusal as exc:
969
  raise _refuse(exc)
970
- return {"workbook": book}
971
 
972
 
973
  # ── the rail's own document (wave 50, W50-T17) ───────────────────────────────────────────────
@@ -982,17 +1172,10 @@ def create_sheet(body: dict = Body(default=None), session: Session = Depends(req
982
  # ⚠ `Depends(require_session)` ONLY, like every other door in this file, and that is correct: the
983
  # Sheet is granted to everyone, and the rail's folders name no database.
984
  #
985
- # ⛔⛔ MEASURED IN W51-T25 AND BOOKED, NOT FIXED: THAT SENTENCE MEANS EVERY SIGNED IN ACCOUNT CAN
986
- # ALREADY READ EVERY WORKBOOK. Nothing in `core.sheets.list_workbooks` or `::read_index` filters by
987
- # owner, and `GET /sheets/{id}` walls on the session alone, so an account holding NO share reads a
988
- # stranger's workbook with **200**. Driven in `verify_sheet.py` section 5c with a third identity.
989
- # ⇒ `sharedWithMe` is therefore a PARTITION of a list everyone can already see, and C5's
990
- # viewer/editor wall guards the WRITE doors rather than closing a read that was never shut.
991
- # Refusing a stranger's read is not in W51-T25's `done-when` and widening it here would change the
992
- # behaviour of a door six other tickets are built on, so it is an amendment finding for the root.
993
- # ⚠ WHAT THIS TICKET DOES GUARANTEE MEANWHILE is the half that leaks data rather than existence:
994
- # a non-owner never receives the owner's stored numbers, because every cell-bearing read
995
- # re-resolves under the caller's own scope first.
996
 
997
 
998
  @router.get("/sheets/index")
@@ -1007,8 +1190,7 @@ def read_sheet_index(session: Session = Depends(require_session)):
1007
  can reach: a client cannot send a revision it was never given, and a server that never checks
1008
  one is a client stamping a number nobody reads.
1009
  """
1010
- from core import sheets
1011
- return {"index": _wire_index(sheets.read_index(_store(session), viewer=session.uname))}
1012
 
1013
 
1014
  @router.put("/sheets/index")
@@ -1035,7 +1217,7 @@ def write_sheet_index(body: dict = Body(default=None),
1035
  expect_rev=raw.get("rev"))
1036
  except sheets.SheetRefusal as exc:
1037
  raise _refuse(exc)
1038
- return {"index": _wire_index(out)}
1039
 
1040
 
1041
  # ── C4: the .xlsx IMPORT, which is a JOB and not a request (wave 51, W51-T24) ────────────────
@@ -1133,7 +1315,7 @@ def _run_import(job_id, path, filename, runtime, uname):
1133
  stamp = _now_iso()
1134
  made = sheets.create_workbook(runtime, name=book.get("name") or "", created_by=uname)
1135
  saved = sheets.put_workbook(runtime, made["id"],
1136
- dict(book, refreshed_at=stamp, rev=made["rev"]))
1137
  _job_set(job_id, state="done", progress=1.0, workbook_id=saved["id"],
1138
  sentence=_import_sentence(report))
1139
  except sheet_import.ImportRefusal as exc:
@@ -1258,6 +1440,7 @@ def read_sheet(workbook_id: str, tabs: str = "",
1258
  from core import sheets
1259
  try:
1260
  book = sheets.get_workbook(_store(session), workbook_id)
 
1261
  except sheets.SheetRefusal as exc:
1262
  raise _refuse(exc)
1263
  if str(tabs or "").strip().lower() == "meta":
@@ -1294,6 +1477,7 @@ def read_sheet_tab(workbook_id: str, tab: str,
1294
  from core import sheets
1295
  try:
1296
  book = sheets.get_workbook(_store(session), workbook_id)
 
1297
  served = _read_for(session, book)
1298
  found = sheets.find_tab(served, tab)
1299
  except sheets.SheetRefusal as exc:
@@ -1319,9 +1503,8 @@ def patch_sheet_cells(workbook_id: str, tab: str, body: dict = Body(default=None
1319
  same patch has landed. A CAP breach is the opposite: it is a whole request 413, because the
1320
  document as a whole cannot be stored and there is no partial version of that.
1321
 
1322
- ⚠ `rev` IN THE BODY MAKES THE WRITE CONDITIONAL, exactly as it does on the PUT door. Omit it
1323
- and the last writer wins; send the `rev` the tab read and a concurrent change answers 409
1324
- `sheet_revision_stale` carrying `rev_current`, which is the revision to refetch.
1325
 
1326
  ⛔⛔ C5's READ-ONLY CHECK RUNS BEFORE THAT COMPARISON AND THE ORDER IS THE CONTRACT. A viewer
1327
  is refused 403 `workbook_read_only`; a viewer holding a stale rev is ALSO refused
@@ -1347,7 +1530,8 @@ def patch_sheet_cells(workbook_id: str, tab: str, body: dict = Body(default=None
1347
  expect = raw.get("rev")
1348
  try:
1349
  out = sheets.patch_cells(_store(session), workbook_id, tab, raw.get("cells"),
1350
- expect_rev=expect)
 
1351
  except sheets.SheetRefusal as exc:
1352
  raise _refuse(exc)
1353
  accepted = out.pop("accepted", [])
@@ -1396,11 +1580,31 @@ def _recomputed_tab_cells(session: Session, workbook_id: str, tab_ref: str, *, c
1396
  (found.get("cells") or {}).get(str(addr).strip().upper()) for addr in changes}
1397
  _recompute_formulas(book, fr, sheet_mod,
1398
  cache_key=(session.tenant, session.uname, workbook_id), changes=edits)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1399
  found = sheets.find_tab(book, tab_ref)
1400
  out = {}
1401
  for addr, cell in (found.get("cells") or {}).items():
1402
  if not isinstance(cell, dict) or (cell.get("kind") != "formula"
1403
- and "spill" not in cell and "spillParent" not in cell):
 
1404
  continue
1405
  row = {"value": cell.get("value"),
1406
  "display": "" if cell.get("value") is None else str(cell.get("display") or ""),
@@ -1435,10 +1639,12 @@ def write_sheet(workbook_id: str, body: dict = Body(default=None),
1435
  # `rev` inside the body IS the expectation; `core.sheets.put_workbook` reads it. This door
1436
  # does not translate it into a second argument, because two ways to say the same thing is
1437
  # how one of them ends up ignored.
1438
- book = sheets.put_workbook(_store(session), workbook_id, raw)
 
 
1439
  except sheets.SheetRefusal as exc:
1440
  raise _refuse(exc)
1441
- return {"workbook": book}
1442
 
1443
 
1444
  @router.delete("/sheets/{workbook_id}")
@@ -1509,6 +1715,14 @@ def share_sheet(workbook_id: str, body: dict = Body(default=None),
1509
  rec = shares.set_grants("workbook", book["id"], entries,
1510
  owner=(None if held.get("owner") else _workbook_owner(book)),
1511
  granter=session.uname, st=_store(session), expect=prior)
 
 
 
 
 
 
 
 
1512
  except shares.GrantsChanged as exc:
1513
  # ⚠ `grants_changed`, THE SAME CODE `routes_shares.py` ALREADY ANSWERS, and a plain 409
1514
  # rather than the `_stale` shape: there is no revision to hand back here, and a
@@ -1613,20 +1827,24 @@ def refresh_sheet(workbook_id: str, session: Session = Depends(require_session))
1613
  if failure is not None:
1614
  cell["state"] = "refused"
1615
  cell["value"] = None
 
1616
  cell["refusal"] = {"code": "database_unreadable",
1617
  "message": f"You cannot read {db}."}
 
1618
  continue
1619
  try:
1620
- out = _resolve_binding(session, binding, view_memo=view_memo)
1621
  except HTTPException as exc:
1622
  detail = getattr(exc, "detail", None) or {}
1623
  info = detail.get("error") if isinstance(detail, dict) else None
1624
  cell["state"] = "refused"
1625
  cell["value"] = None
 
1626
  cell["refusal"] = {
1627
  "code": (info or {}).get("code", "sheet_unresolved"),
1628
  "message": (info or {}).get("message", "This cell could not be refreshed."),
1629
  }
 
1630
  continue
1631
  cell["state"] = "fresh"
1632
  cell["value"] = out["value"]
@@ -1654,14 +1872,16 @@ def refresh_sheet(workbook_id: str, session: Session = Depends(require_session))
1654
  try:
1655
  saved = sheets.put_workbook(_store(session), workbook_id,
1656
  {"name": book.get("name"), "sheets": book.get("sheets"),
1657
- "refreshed_at": stamp, "rev": book.get("rev")})
 
 
1658
  except sheets.SheetRefusal as exc:
1659
  raise _refuse(exc)
1660
  # ⭐⭐ R3 / W52-T12: REFRESH IS THE ONE EVENT ALLOWED TO INVALIDATE A READER'S CACHED SCOPE
1661
  # VALUE, so it is the one door that clears the whole per-scope cache. Every reader's next GET
1662
  # recomputes once, under their own scope, and fills its own slot again from there.
1663
  sheets.clear_scope_cache(_store(session), workbook_id)
1664
- return {"workbook": saved, "recalc_ms": recalc_ms}
1665
 
1666
 
1667
  def _now_iso():
@@ -1916,7 +2136,120 @@ def _metric_column_aggregate(session, database, aggregate, window):
1916
  return column(raw)
1917
 
1918
 
1919
- def _resolve_binding(session: Session, raw_binding, *, today=None, view_memo=None):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1920
  """Evaluate ONE C2 binding and return `{value, limits, sql_columns}`.
1921
 
1922
  The order below is the contract, not a preference:
@@ -1944,7 +2277,10 @@ def _resolve_binding(session: Session, raw_binding, *, today=None, view_memo=Non
1944
  raise err(400, exc.code, exc.message)
1945
 
1946
  database = _require_database(session, binding["database"])
1947
- window = sheet_mod.period_window(binding.get("period"))
 
 
 
1948
  # W59-T14 / R10: the per-database wall is contract step 1. A metric key must not be looked
1949
  # up or acted on before the caller passes it; the ordinary column guards below still apply.
1950
  if binding["aggregate"].get("metric_key"):
@@ -1966,12 +2302,16 @@ def _resolve_binding(session: Session, raw_binding, *, today=None, view_memo=Non
1966
  scope.get("view_name", ""), memo=view_memo)
1967
  else:
1968
  scope_nodes, scope_conj = _fe_parts(scope.get("filter"))
 
 
1969
  needed = (sheet_mod.filter_columns_named(scope_nodes)
1970
  | sheet_mod.filter_columns_named(wall_nodes))
1971
  if binding["aggregate"].get("field"):
1972
  needed.add(str(binding["aggregate"]["field"]))
1973
 
1974
  cur, spec, cols = _mirror(session)(database, metric_window=window, needed=needed)
 
 
1975
 
1976
  # ⛔ THE COLUMN IS CHECKED BEFORE THE SQL IS BUILT (W53-T13). Now that every tenant column is a
1977
  # real column of the materialised table, a `sum` over a text column reaches DuckDB as a binder
@@ -2069,7 +2409,15 @@ def preview_cell(workbook_id: str, addr: str, body: dict = Body(default=None),
2069
  field through the database's ordinary field writer; reusing a column needs no field write.
2070
  """
2071
  raw = dict(body or {})
2072
- out = _resolve_binding(session, raw.get("binding"))
 
 
 
 
 
 
 
 
2073
  return {"value": out["value"], "display": "" if out["value"] is None else str(out["value"]),
2074
  "limits": out["limits"]}
2075
 
@@ -2203,7 +2551,7 @@ def compute_cell(workbook_id: str, addr: str, body: dict = Body(default=None),
2203
  saved = dict(cell)
2204
  limits, resolved = [], None
2205
  try:
2206
- resolved = _resolve_binding(session, binding)
2207
  except HTTPException as exc:
2208
  #: The same per-cell refusal shape `refresh_sheet` writes, so a cell refused by this door
2209
  #: and a cell refused by that one read identically. It is PERSISTED rather than raised:
@@ -2226,7 +2574,9 @@ def compute_cell(workbook_id: str, addr: str, body: dict = Body(default=None),
2226
  saved.pop("refusal", None)
2227
 
2228
  try:
2229
- landed = sheets.patch_cells(_store(session), workbook_id, tab_ref, {key: saved})
 
 
2230
  except sheets.SheetRefusal as exc:
2231
  raise _refuse(exc)
2232
 
@@ -2317,14 +2667,24 @@ def drill_cell(workbook_id: str, addr: str, session: Session = Depends(require_s
2317
  # `_metric_derived` at a month window is 27 ms of an 8,437 ms drill on `customer_data`. So the
2318
  # window is kept UNCONDITIONALLY, exactly as W53-T13 wrote it, and the saving is taken from
2319
  # the column set instead, where the time actually is.
 
 
 
 
 
2320
  cur, spec, cols = _mirror(session)(
2321
- database, metric_window=sheet_mod.period_window(binding.get("period")),
2322
  needed=(sheet_mod.filter_columns_named(scope_nodes)
2323
  | sheet_mod.filter_columns_named(wall_nodes)))
 
 
2324
 
2325
- count_sql, count_params, limits = sheet_mod.build_aggregate_query(
2326
- spec, {"aggregate": {"fn": "count"}}, cols, scope_nodes=scope_nodes,
2327
- scope_conj=scope_conj, wall_nodes=wall_nodes, wall_conj=wall_conj)
 
 
 
2328
  total = (cur.execute(count_sql, count_params).fetchone() or [0])[0]
2329
 
2330
  ids_sql, ids_params, _ = sheet_mod.build_ids_query(
@@ -2411,8 +2771,8 @@ def resolve_bindings(workbook_id: str, body: dict = Body(default=None),
2411
 
2412
  ⛔⛔ AND HERE IS WHAT THE SHAPE CANNOT CARRY, STATED RATHER THAN HIDDEN: a bound cell whose
2413
  binding was REFUSED just now (a database wall, a row wall, a scope condition this database
2414
- cannot compile) comes back as `null`, which is the same thing an aggregate over zero matching
2415
- rows returns. The cause is real and this door knows it; `{addr: value}` has nowhere to put it.
2416
  `POST /sheets/{id}/refresh` and `GET /sheets/{id}` both still carry the full
2417
  `{code, message}` refusal on the cell, so nothing is lost from the document - what is lost is
2418
  the client's ability to paint THIS cell's refusal at commit time. Raised as a dated PRD
@@ -2479,11 +2839,12 @@ def resolve_bindings(workbook_id: str, body: dict = Body(default=None),
2479
  if cell is None:
2480
  continue
2481
  binding = cell.get("binding") or {}
2482
- slot = json.dumps(binding, sort_keys=True, default=str)
 
2483
  if slot not in by_binding:
2484
  try:
2485
- by_binding[slot] = _resolve_binding(session, binding,
2486
- view_memo=view_memo)["value"]
2487
  except HTTPException:
2488
  # ⛔ SWALLOWED HERE AND NOWHERE ELSE. See the docstring: the flat body has no
2489
  # room for a cause, and failing the whole batch on one walled cell would take
 
248
  "shown rather than shown from an older set of columns. Try again in a moment.")
249
 
250
 
251
+ def _linked_customer_bridges(database):
252
+ """Only declared reverse customer edges with an unconditional, served relation."""
253
+ from core.relations import BRIDGES
254
+ return [bridge for bridge in BRIDGES if bridge.get("target") == database
255
+ and bridge.get("source") == "customer_data" and bridge.get("served")
256
+ and bridge.get("cardinality") == "one_to_many" and not bridge.get("where")]
257
+
258
+
259
+ def _linked_customer_fields(session, bridge):
260
+ from core import perm_scope
261
+ _require_database(session, bridge["source"])
262
+ g = _registry_assembly(session, bridge["source"])
263
+ fields = list(g.get("fields") or [])
264
+ hidden = perm_scope.hidden_keys(session.user, bridge["source"], fields, st=session.runtime)
265
+ # Only values the server can read per record. A browser formula or linked rollup needs
266
+ # another evaluator; offering it here would make a missing value look like a blank value.
267
+ fields = [f for f in fields if f.get("key") not in hidden
268
+ and f.get("type") not in {"formula", "link", "lookup", "rollup", "metric"}
269
+ and not f.get("measure")]
270
+ return g, fields
271
+
272
+
273
+ def _linked_relation_column(session, bridge, cur, spec, columns):
274
+ from core import perm_scope
275
+ from modules import sheet as sheet_mod
276
+ key = str(bridge.get("target_col") or "")
277
+ subject = bridge["key"] + ":" + (key or "(missing column)")
278
+ hidden = perm_scope.hidden_keys(session.user, bridge["target"], spec.get("fields") or [],
279
+ st=session.runtime)
280
+ if key in hidden:
281
+ raise sheet_mod.SheetRefusal("linked_filter_unreadable", subject,
282
+ "the relation column is hidden from this account.")
283
+ # The catalogue owns expressions such as sol.order_partner_id and aml.partner_id.
284
+ # The declaration supplies the key, and is a fallback only when the catalogue has none.
285
+ if (columns.get(key) or {}).get("sql"):
286
+ return key
287
+ if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", key):
288
+ raise sheet_mod.SheetRefusal("linked_filter_unreadable", subject,
289
+ "the link does not declare a readable relation column.")
290
+ source = spec.get("from_sql") or spec.get("table")
291
+ try:
292
+ cur.execute(f'SELECT {key} FROM {source} LIMIT 0')
293
+ except Exception:
294
+ raise sheet_mod.SheetRefusal("linked_filter_unreadable", subject,
295
+ "the declared relation column is unavailable on this database.")
296
+ columns[key] = {"sql": key, "type": "int", "aggregate": False}
297
+ return key
298
+
299
+
300
+ @router.get("/sheets/filter-fields/{database}")
301
+ def linked_filter_fields(database: str, session: Session = Depends(require_session)):
302
+ """The linked Filter offer, through the same field wall as the related grid."""
303
+ from modules import sheet as sheet_mod
304
+ database = _require_database(session, database)
305
+ bridges = _linked_customer_bridges(database)
306
+ if not bridges:
307
+ return {"fields": []}
308
+ cur, spec, columns = _mirror(session)(database)
309
+ columns = dict(columns)
310
+ offered = []
311
+ for bridge in bridges:
312
+ try:
313
+ _linked_relation_column(session, bridge, cur, spec, columns)
314
+ _g, fields = _linked_customer_fields(session, bridge)
315
+ except HTTPException as exc:
316
+ if exc.status_code == 403:
317
+ continue
318
+ raise
319
+ except sheet_mod.SheetRefusal:
320
+ continue
321
+ link_label = f'{bridge.get("source_label") or bridge["source"]} via {bridge.get("label") or bridge["key"]}'
322
+ for field in fields:
323
+ # Copy the existing field vocabulary, including options. No customer values or
324
+ # hidden definitions travel on the picker wire.
325
+ offered.append({**field,
326
+ "key": f'{sheet_mod.LINKED_FILTER_PREFIX}{bridge["key"]}:{field["key"]}',
327
+ "label": f'{link_label}: {field.get("label") or field["key"]}'})
328
+ return {"fields": offered}
329
+
330
+
331
+ def _linked_filter_scope(session, database, nodes, cur, spec, columns, *, today=None):
332
+ """Read linked values in Python, then give the relation-blind compiler flat predicates."""
333
+ from modules import sheet as sheet_mod
334
+ if not sheet_mod.linked_filter_ids(nodes):
335
+ return nodes
336
+ import aios_grid
337
+ from core import perm_scope, shared_overlay, view_templates
338
+ from harness import filter_eval, filter_sql
339
+
340
+ bridges = {b["key"]: b for b in _linked_customer_bridges(database)}
341
+ related = {}
342
+
343
+ def resolve(leaf):
344
+ subject = leaf["colId"]
345
+ bridge_key, field_key = sheet_mod.linked_field_parts(subject)
346
+ bridge = bridges.get(bridge_key)
347
+ if bridge is None:
348
+ raise sheet_mod.SheetRefusal("linked_filter_unreadable", subject,
349
+ "this database no longer has that available customer link.")
350
+ try:
351
+ relation_column = _linked_relation_column(session, bridge, cur, spec, columns)
352
+ if bridge_key not in related:
353
+ g, fields = _linked_customer_fields(session, bridge)
354
+ # Use the rows door's wall, including its shared-field enrichment. The pool's
355
+ # identity is pid; it must never be confused with the orders' partner_id.
356
+ rows = perm_scope.apply_row_scope(g["rows_src"], session.user, bridge["source"],
357
+ aios_grid.FIELDS, st=session.runtime)
358
+ related[bridge_key] = (g, fields, rows)
359
+ g, fields, source_rows = related[bridge_key]
360
+ except HTTPException as exc:
361
+ if exc.status_code != 403:
362
+ raise
363
+ raise sheet_mod.SheetRefusal("linked_filter_unreadable", subject,
364
+ "this account cannot read the linked customer database.")
365
+ field = next((f for f in fields if f.get("key") == field_key), None)
366
+ if field is None:
367
+ raise sheet_mod.SheetRefusal("linked_filter_unreadable", subject,
368
+ "the field is hidden, removed, or has no readable per-record value.")
369
+ local = {**leaf, "colId": field_key}
370
+ # Validate before evaluating even an empty pool, so malformed/stale leaves refuse
371
+ # rather than looking like a genuine zero. Cell slots were resolved by W60-T06 above.
372
+ probe_columns = {field_key: {"sql": "linked_value", "type": sheet_mod.mirror_field_type(field)}}
373
+ try:
374
+ compiled = sheet_mod.compile_scope([local], "and", probe_columns, today=today)
375
+ if (local.get("op") not in filter_sql.FILTER_OPS or compiled is None
376
+ or field_key not in compiled.columns_used):
377
+ raise ValueError("unusable linked condition")
378
+ except (ValueError, sheet_mod.SheetRefusal):
379
+ raise sheet_mod.SheetRefusal("linked_filter_unreadable", subject,
380
+ "its value or operator cannot be applied to this field.")
381
+ storage_key = view_templates.workspace_key(bridge["source"])
382
+ try:
383
+ definitions = shared_overlay.fields(storage_key, st=session.runtime)
384
+ rows = aios_grid.rows_from_pool(source_rows, fields, (g.get("ws") or {}).get("overlays"),
385
+ derived=g.get("derived"))
386
+ if field_key in definitions:
387
+ cells = shared_overlay.cells(storage_key, [r["pid"] for r in source_rows], st=session.runtime)
388
+ rows = [{**row, field_key: (cells.get(str(int(row["pid"]))) or {}).get(field_key, "")}
389
+ for row in rows]
390
+ ctx = filter_eval.EvalCtx(today=today)
391
+ ids = [row[bridge["source_col"]] for row in rows
392
+ if filter_eval.permits({"conj": "and", "nodes": [local]}, row, fields, ctx)]
393
+ return sheet_mod.linked_id_predicate(relation_column, ids)
394
+ except Exception:
395
+ raise sheet_mod.SheetRefusal("linked_filter_unreadable", subject,
396
+ "the linked customer values could not be read. Retry after the data is available.")
397
+
398
+ try:
399
+ return sheet_mod.rewrite_linked_filters(nodes, resolve)
400
+ except sheet_mod.SheetRefusal as exc:
401
+ raise err(409, exc.code, exc.message)
402
+
403
+
404
  def _registry_mirror(session: Session, cur, table_key: str, metric_window, needed=None):
405
  """`(cursor, spec, columns)` for one compiled registry grid, at the cell's own period.
406
 
 
795
  nothing else, so the 409 and the 413 are raised here directly rather than by bending `err`,
796
  which would change the error shape of every route in the app.
797
 
798
+ Workbook, retained cell history and folder index refusals all carry the current revision
799
+ through the same existing envelope.
 
 
800
  """
801
  if exc.code in _CAP_CODES:
802
  return HTTPException(status_code=413,
 
890
  round because a workbook that has never been shared has no registry record at all. Asking
891
  `shares.role_for` alone would answer `None` for the person who created it.
892
  """
893
+ from core import sheets
894
+ return sheets.workbook_role(_store(session), book, session.uname, is_admin=session.admin)
895
+
896
+
897
+ def _require_reader(session: Session, book):
898
+ """R28: use the same predicate as the index; hidden and missing ids answer identically."""
899
+ from core import sheets
900
+ if not sheets.may_read_workbook(book, _role_on_workbook(session, book)):
901
+ raise _refuse(sheets.SheetRefusal("workbook_missing", "That workbook no longer exists."))
902
+
903
+
904
+ def _index_for(session: Session):
905
+ """C2: every list response uses the index's sole visibility filter and role helper."""
906
+ from core import sheets
907
+ return sheets.read_index(_store(session), viewer=session.uname,
908
+ role_on_workbook=lambda book: _role_on_workbook(session, book))
909
 
910
 
911
  def _require_editor(session: Session, book):
 
938
  out = []
939
  for row in rows or ():
940
  row = dict(row)
941
+ if "role" in row:
942
+ row["role"] = "owner" if row["role"] == "owner" else wire_role(row["role"])
943
  row["shares"] = [{"who": s.get("who"), "role": wire_role(s.get("role"))}
944
  for s in (row.get("shares") or [])
945
  if wire_role(s.get("role"))]
 
971
  return sheets.scope_hash(database, wall_tree, (binding or {}).get("scope") or {})
972
 
973
 
974
+ def _has_ending(binding):
975
+ return (isinstance(binding, dict) and isinstance(binding.get("period"), dict)
976
+ and "ending" in binding["period"])
977
+
978
+
979
+ def _has_cell_inputs(binding):
980
+ from modules import sheet as sheet_mod
981
+ if _has_ending(binding):
982
+ return True
983
+ scope = binding.get("scope") if isinstance(binding, dict) else None
984
+ nodes, _ = _fe_parts(scope.get("filter") if isinstance(scope, dict) else None)
985
+ # Linked values and related-table grants can change independently of the orders' cache key.
986
+ if sheet_mod.linked_filter_ids(nodes):
987
+ return True
988
+ return any(sheet_mod.filter_cell_nodes(nodes))
989
+
990
+
991
+ def _reresolved_for_reader(session: Session, book, *, endings_only=False):
992
  """A COPY of `book` whose every bound cell was recomputed under THIS reader's scope (C5).
993
 
994
  ⛔⛔ IN MEMORY, AND IT MUST NEVER PERSIST. `refresh_sheet` runs the same loop and ends with
 
1029
  for addr, cell in (tab.get("cells") or {}).items():
1030
  if not isinstance(cell, dict) or cell.get("kind") != "bound":
1031
  continue
1032
+ if endings_only and not _has_cell_inputs(cell.get("binding")):
1033
+ continue
1034
  touched += 1
1035
  binding = cell.get("binding") or {}
1036
  db = str(binding.get("database") or "")
 
1053
  cell_key = tab_ref + "!" + addr
1054
  scope_key = _binding_scope_key(session, db, binding)
1055
  hit = None
1056
+ if wid and scope_key and not _has_cell_inputs(binding):
1057
  try:
1058
  hit = sheets.cached_scope_value(store, wid, cell_key, scope_key)
1059
  except Exception: # noqa: BLE001
 
1071
  continue
1072
 
1073
  try:
1074
+ out = _resolve_cell_binding(session, binding, fresh, tab_ref, view_memo=view_memo)
1075
  except HTTPException as exc:
1076
  detail = getattr(exc, "detail", None) or {}
1077
  info = detail.get("error") if isinstance(detail, dict) else None
 
1082
  "code": (info or {}).get("code", "sheet_unresolved"),
1083
  "message": (info or {}).get("message", "This cell could not be refreshed."),
1084
  }
1085
+ cell.pop("limits", None)
1086
  continue
1087
  cell["state"] = "fresh"
1088
  cell["value"] = out["value"]
 
1114
  return fresh
1115
 
1116
 
1117
+ def _response_workbook(book):
1118
+ """Omit private write history from response tabs without changing the stored document."""
1119
+ return {**book, "sheets": [{key: value for key, value in tab.items()
1120
+ if key not in ("writes", "writesFrom")}
1121
+ for tab in book.get("sheets") or []]}
1122
+
1123
+
1124
  def _read_for(session: Session, book):
1125
  """The workbook this session is entitled to see: stored for the owner, re-resolved otherwise.
1126
 
1127
+ W60-T09, 2026-09-14: R28 checks visibility before this projection. Admitted legacy readers
1128
+ and grantees still receive their own scoped numbers, never the owner's cached numbers.
 
 
1129
  """
1130
+ book = _response_workbook(book)
1131
  if _role_on_workbook(session, book) == "owner":
1132
+ if any(_has_cell_inputs(cell.get("binding"))
1133
+ for tab in book.get("sheets") or [] for cell in (tab.get("cells") or {}).values()):
1134
+ return _reresolved_for_reader(session, book, endings_only=True)
1135
  return book
1136
  return _reresolved_for_reader(session, book)
1137
 
 
1142
 
1143
  ⚠ C5's `shares` rides here as well as on `/sheets/index`, because the client reads both.
1144
  """
1145
+ rows = _index_for(session)["workbooks"]
 
1146
  return {"workbooks": _wire_shares(rows)}
1147
 
1148
 
 
1157
  created_by=session.uname)
1158
  except sheets.SheetRefusal as exc:
1159
  raise _refuse(exc)
1160
+ return {"workbook": _response_workbook(book)}
1161
 
1162
 
1163
  # ── the rail's own document (wave 50, W50-T17) ───────────────────────────────────────────────
 
1172
  # ⚠ `Depends(require_session)` ONLY, like every other door in this file, and that is correct: the
1173
  # Sheet is granted to everyone, and the rail's folders name no database.
1174
  #
1175
+ # W60-T09, 2026-09-14: R28 supersedes the W51-T25 amendment finding. Both lists and all three
1176
+ # workbook read shapes use core.sheets.may_read_workbook with _role_on_workbook. New workbooks
1177
+ # are private to their creator and grantees; administrators see all. Unmarked or creatorless
1178
+ # documents retain legacy visibility. Admitted non-owners still re-resolve under their own scope.
 
 
 
 
 
 
 
1179
 
1180
 
1181
  @router.get("/sheets/index")
 
1190
  can reach: a client cannot send a revision it was never given, and a server that never checks
1191
  one is a client stamping a number nobody reads.
1192
  """
1193
+ return {"index": _wire_index(_index_for(session))}
 
1194
 
1195
 
1196
  @router.put("/sheets/index")
 
1217
  expect_rev=raw.get("rev"))
1218
  except sheets.SheetRefusal as exc:
1219
  raise _refuse(exc)
1220
+ return {"index": _wire_index({**_index_for(session), "repairs": out.get("repairs", [])})}
1221
 
1222
 
1223
  # ── C4: the .xlsx IMPORT, which is a JOB and not a request (wave 51, W51-T24) ────────────────
 
1315
  stamp = _now_iso()
1316
  made = sheets.create_workbook(runtime, name=book.get("name") or "", created_by=uname)
1317
  saved = sheets.put_workbook(runtime, made["id"],
1318
+ dict(book, refreshed_at=stamp, rev=made["rev"]), actor=uname)
1319
  _job_set(job_id, state="done", progress=1.0, workbook_id=saved["id"],
1320
  sentence=_import_sentence(report))
1321
  except sheet_import.ImportRefusal as exc:
 
1440
  from core import sheets
1441
  try:
1442
  book = sheets.get_workbook(_store(session), workbook_id)
1443
+ _require_reader(session, book)
1444
  except sheets.SheetRefusal as exc:
1445
  raise _refuse(exc)
1446
  if str(tabs or "").strip().lower() == "meta":
 
1477
  from core import sheets
1478
  try:
1479
  book = sheets.get_workbook(_store(session), workbook_id)
1480
+ _require_reader(session, book)
1481
  served = _read_for(session, book)
1482
  found = sheets.find_tab(served, tab)
1483
  except sheets.SheetRefusal as exc:
 
1503
  same patch has landed. A CAP breach is the opposite: it is a whole request 413, because the
1504
  document as a whole cannot be stored and there is no partial version of that.
1505
 
1506
+ With retained history, a stale revision merges by address and the later value wins;
1507
+ `conflicts` names other people's overlapping writes, and only missing history refuses.
 
1508
 
1509
  ⛔⛔ C5's READ-ONLY CHECK RUNS BEFORE THAT COMPARISON AND THE ORDER IS THE CONTRACT. A viewer
1510
  is refused 403 `workbook_read_only`; a viewer holding a stale rev is ALSO refused
 
1530
  expect = raw.get("rev")
1531
  try:
1532
  out = sheets.patch_cells(_store(session), workbook_id, tab, raw.get("cells"),
1533
+ expect_rev=expect, actor=session.uname,
1534
+ actor_name=session.user.get("name") or session.uname)
1535
  except sheets.SheetRefusal as exc:
1536
  raise _refuse(exc)
1537
  accepted = out.pop("accepted", [])
 
1580
  (found.get("cells") or {}).get(str(addr).strip().upper()) for addr in changes}
1581
  _recompute_formulas(book, fr, sheet_mod,
1582
  cache_key=(session.tenant, session.uname, workbook_id), changes=edits)
1583
+ # Date and filter-cell edits also change database totals. Recompute all readers, then formulas.
1584
+ ending_cells = set()
1585
+ for source in book.get("sheets") or []:
1586
+ for addr, cell in (source.get("cells") or {}).items():
1587
+ binding = cell.get("binding") or {}
1588
+ if cell.get("kind") != "bound" or not _has_cell_inputs(binding):
1589
+ continue
1590
+ try:
1591
+ result = _resolve_cell_binding(session, binding, book, source.get("id"))
1592
+ cell.update(value=result["value"], display="" if result["value"] is None else str(result["value"]), state="fresh")
1593
+ cell.pop("refusal", None)
1594
+ except HTTPException as exc:
1595
+ info = ((exc.detail or {}).get("error") or {})
1596
+ cell.update(value=None, display="", state="refused", refusal={
1597
+ "code": info.get("code", "ending_cell_unreadable"),
1598
+ "message": info.get("message", "The Ending date could not be read. Choose a valid date.")})
1599
+ ending_cells.add((source.get("id"), addr))
1600
+ if ending_cells:
1601
+ _recompute_formulas(book, fr, sheet_mod)
1602
  found = sheets.find_tab(book, tab_ref)
1603
  out = {}
1604
  for addr, cell in (found.get("cells") or {}).items():
1605
  if not isinstance(cell, dict) or (cell.get("kind") != "formula"
1606
+ and "spill" not in cell and "spillParent" not in cell
1607
+ and (found.get("id"), addr) not in ending_cells):
1608
  continue
1609
  row = {"value": cell.get("value"),
1610
  "display": "" if cell.get("value") is None else str(cell.get("display") or ""),
 
1639
  # `rev` inside the body IS the expectation; `core.sheets.put_workbook` reads it. This door
1640
  # does not translate it into a second argument, because two ways to say the same thing is
1641
  # how one of them ends up ignored.
1642
+ book = sheets.put_workbook(_store(session), workbook_id, raw,
1643
+ actor=session.uname,
1644
+ actor_name=session.user.get("name") or session.uname)
1645
  except sheets.SheetRefusal as exc:
1646
  raise _refuse(exc)
1647
+ return {"workbook": _response_workbook(book)}
1648
 
1649
 
1650
  @router.delete("/sheets/{workbook_id}")
 
1715
  rec = shares.set_grants("workbook", book["id"], entries,
1716
  owner=(None if held.get("owner") else _workbook_owner(book)),
1717
  granter=session.uname, st=_store(session), expect=prior)
1718
+ # A successful explicit share narrows legacy visibility; ordinary saves never do.
1719
+ if "access" not in book:
1720
+ # W60-T09, 2026-09-14: the first share decides VISIBILITY, making the owner gate load bearing.
1721
+ # A non-owner must not reach this narrowing on an ownerless legacy workbook
1722
+ # and lock themselves out by sharing it.
1723
+ sheets.narrow_workbook(_store(session), book["id"])
1724
+ except sheets.SheetRefusal as exc:
1725
+ raise _refuse(exc)
1726
  except shares.GrantsChanged as exc:
1727
  # ⚠ `grants_changed`, THE SAME CODE `routes_shares.py` ALREADY ANSWERS, and a plain 409
1728
  # rather than the `_stale` shape: there is no revision to hand back here, and a
 
1827
  if failure is not None:
1828
  cell["state"] = "refused"
1829
  cell["value"] = None
1830
+ cell["display"] = ""
1831
  cell["refusal"] = {"code": "database_unreadable",
1832
  "message": f"You cannot read {db}."}
1833
+ cell.pop("limits", None)
1834
  continue
1835
  try:
1836
+ out = _resolve_cell_binding(session, binding, book, tab.get("id"), view_memo=view_memo)
1837
  except HTTPException as exc:
1838
  detail = getattr(exc, "detail", None) or {}
1839
  info = detail.get("error") if isinstance(detail, dict) else None
1840
  cell["state"] = "refused"
1841
  cell["value"] = None
1842
+ cell["display"] = ""
1843
  cell["refusal"] = {
1844
  "code": (info or {}).get("code", "sheet_unresolved"),
1845
  "message": (info or {}).get("message", "This cell could not be refreshed."),
1846
  }
1847
+ cell.pop("limits", None)
1848
  continue
1849
  cell["state"] = "fresh"
1850
  cell["value"] = out["value"]
 
1872
  try:
1873
  saved = sheets.put_workbook(_store(session), workbook_id,
1874
  {"name": book.get("name"), "sheets": book.get("sheets"),
1875
+ "refreshed_at": stamp, "rev": book.get("rev")},
1876
+ actor=session.uname,
1877
+ actor_name=session.user.get("name") or session.uname)
1878
  except sheets.SheetRefusal as exc:
1879
  raise _refuse(exc)
1880
  # ⭐⭐ R3 / W52-T12: REFRESH IS THE ONE EVENT ALLOWED TO INVALIDATE A READER'S CACHED SCOPE
1881
  # VALUE, so it is the one door that clears the whole per-scope cache. Every reader's next GET
1882
  # recomputes once, under their own scope, and fills its own slot again from there.
1883
  sheets.clear_scope_cache(_store(session), workbook_id)
1884
+ return {"workbook": _response_workbook(saved), "recalc_ms": recalc_ms}
1885
 
1886
 
1887
  def _now_iso():
 
2136
  return column(raw)
2137
 
2138
 
2139
+ def _ending_window(session, binding, *, book=None, tab=None, today=None, seen=()):
2140
+ """Resolve a period from authored cells. Submitted ending.date is never trusted for a ref."""
2141
+ from modules import sheet as sheet_mod
2142
+ from harness import windows as W
2143
+ period = binding.get("period")
2144
+ if not isinstance(period, dict) or (period.get("ending") or {}).get("kind") != "cell":
2145
+ return sheet_mod.period_window(period, today)
2146
+ ref = period.get("ref") or "(blank)"
2147
+ value = _read_binding_cell(session, ref, book=book, tab=tab, today=today, seen=seen)
2148
+ date = W.ending_cell_date(value, book.get("dateSystem", "1900"))
2149
+ if date is None:
2150
+ raise sheet_mod.SheetRefusal("ending_cell_unreadable", ref, "its value is not a real date.")
2151
+ return sheet_mod.period_window(period, today, cell_date=date)
2152
+
2153
+
2154
+ def _read_binding_cell(session, ref, *, book=None, tab=None, today=None, seen=(),
2155
+ code="ending_cell_unreadable"):
2156
+ """Shared cell read for Ending and Filter, including scoped bound and formula inputs."""
2157
+ from modules import sheet as sheet_mod
2158
+ import formula_runtime as fr
2159
+
2160
+ def refuse(reason):
2161
+ raise sheet_mod.SheetRefusal(code, ref or "(blank)", reason)
2162
+
2163
+ if not re.fullmatch(r"(?:(?:'([^']|'')+'|[^'!]+)!)?\$?[A-Za-z]{1,3}\$?[1-9][0-9]{0,6}", ref):
2164
+ refuse("its reference is invalid.")
2165
+ if book is None:
2166
+ refuse("the source workbook is unavailable.")
2167
+ tabs = book.get("sheets") or []
2168
+ names = _tab_scope_names(tabs)
2169
+ home = _resolve_home_tab(book, tabs, names, tab)
2170
+ key = _asked_key(ref, home, fr)
2171
+ if key in seen:
2172
+ refuse("the reference is circular.")
2173
+ cells = {fr.a1_key(addr, name): cell for source, name in zip(tabs, names)
2174
+ for addr, cell in (source.get("cells") or {}).items()}
2175
+ cell = cells.get(key)
2176
+ if not isinstance(cell, dict) or cell.get("kind") == "empty":
2177
+ refuse("the cell or its sheet is missing or blank.")
2178
+ if cell.get("kind") == "bound":
2179
+ try:
2180
+ value = _resolve_binding(session, cell.get("binding"), today=today,
2181
+ book=book, tab=key.rpartition("!")[0], ending_seen=(*seen, key))["value"]
2182
+ except HTTPException as exc:
2183
+ reason = ((exc.detail or {}).get("error") or {}).get("message", "its source is refused.")
2184
+ refuse(reason)
2185
+ elif cell.get("kind") == "formula":
2186
+ # The existing formula graph discovers actual inputs, including dynamic references.
2187
+ # A database input starts refused, so a cached value can never bypass this reader's wall.
2188
+ bound = {k: c for k, c in cells.items() if c.get("kind") == "bound"}
2189
+ specs = {k: ({"refused": "ending_input_pending"} if k in bound
2190
+ else fr._document_spec(c, k.rpartition("!")[0])) for k, c in cells.items()}
2191
+ engine = fr.SheetCalculation(specs, sheets=names, today=today,
2192
+ named_ranges=book.get("namedRanges"), date_system=book.get("dateSystem", "1900"))
2193
+ attempted, failures = set(), {}
2194
+ while True:
2195
+ dependencies, pending = set(), [key]
2196
+ while pending:
2197
+ dependency = pending.pop()
2198
+ if dependency in dependencies:
2199
+ continue
2200
+ dependencies.add(dependency)
2201
+ pending.extend(engine.consumed.get(dependency, ()))
2202
+ needed = (dependencies & set(bound)) - attempted
2203
+ if not needed:
2204
+ break
2205
+ changes = {}
2206
+ for dependency in needed:
2207
+ attempted.add(dependency)
2208
+ try:
2209
+ result = _resolve_binding(session, bound[dependency].get("binding"), today=today,
2210
+ book=book, tab=dependency.rpartition("!")[0], ending_seen=(*seen, key, dependency))
2211
+ changes[dependency] = {"value": result["value"]}
2212
+ except HTTPException as exc:
2213
+ info = ((exc.detail or {}).get("error") or {})
2214
+ failures[dependency] = info.get("message", "a database input is refused.")
2215
+ changes[dependency] = {"refused": info.get("code", "ending_cell_unreadable")}
2216
+ # Each pass resolves previously unread database cells, so the workbook bounds the loop.
2217
+ engine.update(changes, revision=engine.revision + 1, today=today)
2218
+ if engine.errors.get(key):
2219
+ error_code = engine.errors[key]
2220
+ reason = next((failures[k] for k in dependencies if k in failures), None)
2221
+ if not reason:
2222
+ reason = (sheet_mod.SheetRefusal(error_code, ref, "a formula input is refused.").message
2223
+ if error_code in sheet_mod.REFUSALS else fr._sheet_error_message(error_code))
2224
+ refuse(reason)
2225
+ value = engine.values.get(key)
2226
+ else:
2227
+ if cell.get("state") == "refused":
2228
+ refuse((cell.get("refusal") or {}).get("message") or "the cell is refused.")
2229
+ if cell.get("state") == "stale":
2230
+ refuse("the cell needs to be refreshed.")
2231
+ value = cell.get("value", cell.get("text"))
2232
+ return value
2233
+
2234
+
2235
+ def _filter_cell_values(session, nodes, *, book=None, tab=None, today=None, seen=()):
2236
+ from modules import sheet as sheet_mod
2237
+ try:
2238
+ return sheet_mod.resolve_filter_cells(nodes, lambda ref: _read_binding_cell(
2239
+ session, ref, book=book, tab=tab, today=today, seen=seen, code="filter_cell_unreadable"))
2240
+ except sheet_mod.SheetRefusal as exc:
2241
+ raise err(400, exc.code, exc.message)
2242
+
2243
+
2244
+ def _resolve_cell_binding(session, binding, book, tab, **kwargs):
2245
+ """Keep the legacy resolver calling convention for bindings without workbook inputs."""
2246
+ if _has_cell_inputs(binding):
2247
+ return _resolve_binding(session, binding, book=book, tab=tab, **kwargs)
2248
+ return _resolve_binding(session, binding, **kwargs)
2249
+
2250
+
2251
+ def _resolve_binding(session: Session, raw_binding, *, today=None, view_memo=None,
2252
+ book=None, tab=None, ending_seen=()):
2253
  """Evaluate ONE C2 binding and return `{value, limits, sql_columns}`.
2254
 
2255
  The order below is the contract, not a preference:
 
2277
  raise err(400, exc.code, exc.message)
2278
 
2279
  database = _require_database(session, binding["database"])
2280
+ try:
2281
+ window = _ending_window(session, binding, book=book, tab=tab, today=today, seen=ending_seen)
2282
+ except sheet_mod.SheetRefusal as exc:
2283
+ raise err(400, exc.code, exc.message)
2284
  # W59-T14 / R10: the per-database wall is contract step 1. A metric key must not be looked
2285
  # up or acted on before the caller passes it; the ordinary column guards below still apply.
2286
  if binding["aggregate"].get("metric_key"):
 
2302
  scope.get("view_name", ""), memo=view_memo)
2303
  else:
2304
  scope_nodes, scope_conj = _fe_parts(scope.get("filter"))
2305
+ scope_nodes = _filter_cell_values(session, scope_nodes, book=book, tab=tab,
2306
+ today=today, seen=ending_seen)
2307
  needed = (sheet_mod.filter_columns_named(scope_nodes)
2308
  | sheet_mod.filter_columns_named(wall_nodes))
2309
  if binding["aggregate"].get("field"):
2310
  needed.add(str(binding["aggregate"]["field"]))
2311
 
2312
  cur, spec, cols = _mirror(session)(database, metric_window=window, needed=needed)
2313
+ cols = dict(cols)
2314
+ scope_nodes = _linked_filter_scope(session, database, scope_nodes, cur, spec, cols, today=today)
2315
 
2316
  # ⛔ THE COLUMN IS CHECKED BEFORE THE SQL IS BUILT (W53-T13). Now that every tenant column is a
2317
  # real column of the materialised table, a `sum` over a text column reaches DuckDB as a binder
 
2409
  field through the database's ordinary field writer; reusing a column needs no field write.
2410
  """
2411
  raw = dict(body or {})
2412
+ binding = raw.get("binding") or {}
2413
+ book = None
2414
+ if _has_cell_inputs(binding):
2415
+ from core import sheets
2416
+ try:
2417
+ book = sheets.get_workbook(_store(session), workbook_id)
2418
+ except sheets.SheetRefusal as exc:
2419
+ raise _refuse(exc)
2420
+ out = _resolve_cell_binding(session, binding, book, raw.get("tab"))
2421
  return {"value": out["value"], "display": "" if out["value"] is None else str(out["value"]),
2422
  "limits": out["limits"]}
2423
 
 
2551
  saved = dict(cell)
2552
  limits, resolved = [], None
2553
  try:
2554
+ resolved = _resolve_cell_binding(session, binding, book, tab_ref)
2555
  except HTTPException as exc:
2556
  #: The same per-cell refusal shape `refresh_sheet` writes, so a cell refused by this door
2557
  #: and a cell refused by that one read identically. It is PERSISTED rather than raised:
 
2574
  saved.pop("refusal", None)
2575
 
2576
  try:
2577
+ landed = sheets.patch_cells(_store(session), workbook_id, tab_ref, {key: saved},
2578
+ actor=session.uname,
2579
+ actor_name=session.user.get("name") or session.uname)
2580
  except sheets.SheetRefusal as exc:
2581
  raise _refuse(exc)
2582
 
 
2667
  # `_metric_derived` at a month window is 27 ms of an 8,437 ms drill on `customer_data`. So the
2668
  # window is kept UNCONDITIONALLY, exactly as W53-T13 wrote it, and the saving is taken from
2669
  # the column set instead, where the time actually is.
2670
+ try:
2671
+ scope_nodes = _filter_cell_values(session, scope_nodes, book=book, tab=tab.get("id"))
2672
+ window = _ending_window(session, binding, book=book, tab=tab.get("id"))
2673
+ except sheet_mod.SheetRefusal as exc:
2674
+ raise err(400, exc.code, exc.message)
2675
  cur, spec, cols = _mirror(session)(
2676
+ database, metric_window=window,
2677
  needed=(sheet_mod.filter_columns_named(scope_nodes)
2678
  | sheet_mod.filter_columns_named(wall_nodes)))
2679
+ cols = dict(cols)
2680
+ scope_nodes = _linked_filter_scope(session, database, scope_nodes, cur, spec, cols)
2681
 
2682
+ try:
2683
+ count_sql, count_params, limits = sheet_mod.build_aggregate_query(
2684
+ spec, {"aggregate": {"fn": "count"}}, cols, scope_nodes=scope_nodes,
2685
+ scope_conj=scope_conj, wall_nodes=wall_nodes, wall_conj=wall_conj)
2686
+ except sheet_mod.SheetRefusal as exc:
2687
+ raise err(400, exc.code, exc.message)
2688
  total = (cur.execute(count_sql, count_params).fetchone() or [0])[0]
2689
 
2690
  ids_sql, ids_params, _ = sheet_mod.build_ids_query(
 
2771
 
2772
  ⛔⛔ AND HERE IS WHAT THE SHAPE CANNOT CARRY, STATED RATHER THAN HIDDEN: a bound cell whose
2773
  binding was REFUSED just now (a database wall, a row wall, a scope condition this database
2774
+ cannot compile) comes back as `null`, which is also an empty AVG/MIN/MAX result. An empty
2775
+ SUM returns zero. The cause is real and this door knows it; `{addr: value}` has nowhere to put it.
2776
  `POST /sheets/{id}/refresh` and `GET /sheets/{id}` both still carry the full
2777
  `{code, message}` refusal on the cell, so nothing is lost from the document - what is lost is
2778
  the client's ability to paint THIS cell's refusal at commit time. Raised as a dated PRD
 
2839
  if cell is None:
2840
  continue
2841
  binding = cell.get("binding") or {}
2842
+ own_tab = _asked_key(label, home, fr).rpartition("!")[0]
2843
+ slot = json.dumps([own_tab, binding], sort_keys=True, default=str)
2844
  if slot not in by_binding:
2845
  try:
2846
+ by_binding[slot] = _resolve_cell_binding(session, binding, book, own_tab,
2847
+ view_memo=view_memo)["value"]
2848
  except HTTPException:
2849
  # ⛔ SWALLOWED HERE AND NOWHERE ELSE. See the docstring: the flat body has no
2850
  # room for a cause, and failing the whole batch on one walled cell would take
api/routes_starred.py CHANGED
@@ -39,17 +39,17 @@ from deps import Session, err, require_session
39
 
40
  router = APIRouter(prefix="/api/v1")
41
 
42
- #: The per-user bucket holding the three ID-LIST kinds. `{username: {databases, agents, queries}}`
43
  #:
44
  #: ⚠ PER USER (R6), like `nav_recents` and unlike `nav_meta`: what I care about is not a fact about
45
  #: the object, so a tenant-wide star would put one person's shortlist on everybody's Home.
46
  _STARRED_KEY = "starred"
47
 
48
- #: The four kinds C2 declares. `view` is the odd one out — see the header.
49
- KINDS = ("database", "agent", "query", "view", "application")
50
 
51
- #: The three kinds this file's own bucket holds, and the payload key each answers under.
52
- _LIST_KINDS = {"database": "databases", "agent": "agents", "query": "queries"}
53
 
54
  #: A bound on each id list. ⛔ REPORTED, NEVER SILENT: a POST that would cross it is refused with
55
  #: the cause and the action (unstar something), rather than being accepted and truncated. A star
@@ -90,7 +90,7 @@ def _clean_list(raw):
90
 
91
 
92
  def _read_lists(session):
93
- """This caller's three id lists. A store blip answers empty rather than taking the page down."""
94
  try:
95
  mine = (session.runtime.get(_STARRED_KEY) or {}).get(session.uname) or {}
96
  except Exception:
@@ -289,7 +289,7 @@ def _query_names(session, qids):
289
 
290
 
291
  def _payload(session, keys=None, cache=None):
292
- """The C2 answer: the three id lists, the starred views, and what could not be read.
293
 
294
  ⚠ `degraded` SHIPS AS `[]` RATHER THAN BEING OMITTED WHEN EMPTY — the same rule `/nav`'s
295
  `omitted`/`degraded` follow, for the same reason: a key a consumer has to test for is a key a
@@ -307,6 +307,8 @@ def _payload(session, keys=None, cache=None):
307
  # validate, and pruning them here buys nothing: this list is the CALLER'S OWN writes, so it can
308
  # disclose nothing they did not already know, and B/C render only objects they can already see
309
  # (the way `groupRecents` drops an unreachable recent). Said out loud rather than left as a gap.
 
 
310
  lists["databases"] = [k for k in lists["databases"] if k in keys]
311
  # ⭐ ASK B-1 (2): the names, and — because the read that answers "what is it called" also answers
312
  # "does it still exist" — the same prune the databases get. ⛔ ONLY WHEN THE READ SUCCEEDED: a
@@ -327,7 +329,7 @@ def _payload(session, keys=None, cache=None):
327
  except Exception:
328
  application_rows = []
329
  out = {"databases": lists["databases"], "agents": lists["agents"],
330
- "queries": lists["queries"], "queryNames": qnames,
331
  "views": views, "applications": application_rows, "degraded": unread}
332
  if unread:
333
  # R6's second sentence, in the payload: the CAUSE and what it means, not a bare list.
@@ -503,7 +505,7 @@ def set_starred(body: dict = Body(default=None),
503
  session: Session = Depends(require_session)):
504
  """C2 — star or unstar ONE object, and answer with the caller's whole new list.
505
 
506
- Body: `{"kind": "database"|"agent"|"query"|"view", "id": str, "on": bool}`, plus an OPTIONAL
507
  `"database"` when `kind` is `view` (the fast path — see `_find_view`).
508
 
509
  ⚠ THE WHOLE LIST COMES BACK, not an ack, because the client is optimistic-then-reconciled
 
39
 
40
  router = APIRouter(prefix="/api/v1")
41
 
42
+ #: The per-user bucket holding ID-LIST kinds. `{username: {databases, agents, queries, sheets}}`
43
  #:
44
  #: ⚠ PER USER (R6), like `nav_recents` and unlike `nav_meta`: what I care about is not a fact about
45
  #: the object, so a tenant-wide star would put one person's shortlist on everybody's Home.
46
  _STARRED_KEY = "starred"
47
 
48
+ #: Accepted star kinds. Views and applications keep their own record-backed write paths.
49
+ KINDS = ("database", "agent", "query", "view", "application", "sheet")
50
 
51
+ #: The kinds this file's own bucket holds, and the payload key each answers under.
52
+ _LIST_KINDS = {"database": "databases", "agent": "agents", "query": "queries", "sheet": "sheets"}
53
 
54
  #: A bound on each id list. ⛔ REPORTED, NEVER SILENT: a POST that would cross it is refused with
55
  #: the cause and the action (unstar something), rather than being accepted and truncated. A star
 
90
 
91
 
92
  def _read_lists(session):
93
+ """This caller's id lists. A store blip answers empty rather than taking the page down."""
94
  try:
95
  mine = (session.runtime.get(_STARRED_KEY) or {}).get(session.uname) or {}
96
  except Exception:
 
289
 
290
 
291
  def _payload(session, keys=None, cache=None):
292
+ """The star answer: the caller's id lists, starred records, and what could not be read.
293
 
294
  ⚠ `degraded` SHIPS AS `[]` RATHER THAN BEING OMITTED WHEN EMPTY — the same rule `/nav`'s
295
  `omitted`/`degraded` follow, for the same reason: a key a consumer has to test for is a key a
 
307
  # validate, and pruning them here buys nothing: this list is the CALLER'S OWN writes, so it can
308
  # disclose nothing they did not already know, and B/C render only objects they can already see
309
  # (the way `groupRecents` drops an unreachable recent). Said out loud rather than left as a gap.
310
+ # Sheets are also the CALLER'S OWN writes. R28 filters the sheet index; C2 forbids a second
311
+ # access check here, so sheet ids pass through unchanged.
312
  lists["databases"] = [k for k in lists["databases"] if k in keys]
313
  # ⭐ ASK B-1 (2): the names, and — because the read that answers "what is it called" also answers
314
  # "does it still exist" — the same prune the databases get. ⛔ ONLY WHEN THE READ SUCCEEDED: a
 
329
  except Exception:
330
  application_rows = []
331
  out = {"databases": lists["databases"], "agents": lists["agents"],
332
+ "queries": lists["queries"], "sheets": lists["sheets"], "queryNames": qnames,
333
  "views": views, "applications": application_rows, "degraded": unread}
334
  if unread:
335
  # R6's second sentence, in the payload: the CAUSE and what it means, not a bare list.
 
505
  session: Session = Depends(require_session)):
506
  """C2 — star or unstar ONE object, and answer with the caller's whole new list.
507
 
508
+ Body: `{"kind": "database"|"agent"|"query"|"view"|"application"|"sheet", "id": str, "on": bool}`, plus an OPTIONAL
509
  `"database"` when `kind` is `view` (the fast path — see `_find_view`).
510
 
511
  ⚠ THE WHOLE LIST COMES BACK, not an ack, because the client is optimistic-then-reconciled
api/routes_tables.py CHANGED
@@ -68,33 +68,45 @@ class _MetricReadRuntime:
68
  raise AttributeError(name)
69
 
70
 
71
- def _related_product_fields(session, rows):
72
  """Resolve authored Metric definitions through the existing workspace and field wall."""
73
  import aios_grid
74
  from core import grid_events, perm_scope, shared_overlay
75
  from modules import product_data as pd
 
 
 
 
 
 
 
 
 
 
 
 
 
76
 
77
  pids = frozenset(r["pid"] for r in rows)
78
  ctx = grid_events.EventCtx(uname=session.uname, allowed_pids=pids, fields=[],
79
  hidden_keys=set(), admin=session.admin, fallback_ws=None,
80
- seen_ids={}, st=session.runtime, scope_key="product",
81
- table=pd.table_ops(session.runtime))
82
  ws = grid_events.table_workspace(ctx, allowed_pids=pids, consume_corrections=False)
83
  _, fields, _, _ = aios_grid.workspace_wire(
84
- ws, session.uname, set(pids), defs={}, scope_key="product", with_cohorts=False,
85
- fields_base=aios_grid.product_fields(), st=session.runtime)
86
  have = {f["key"] for f in fields}
87
  fields = list(fields) + [dict(f, source="overlay", shared=True)
88
- for key, f in shared_overlay.fields(pd.TABLE_KEY, st=session.runtime).items()
89
  if key not in have]
90
- hidden = perm_scope.hidden_keys(session.user, "product_data", fields, st=session.runtime)
91
  return [f for f in fields if f.get("measure") and f["key"] not in hidden]
92
 
93
 
94
  @router.post("/tables/{table_key}/related-metrics")
95
  def related_metrics(table_key: str, body: dict = Body(default=None),
96
  session: Session = Depends(require_session)):
97
- """C6: a visible Products ordered edge, origin customer and real destination ids.
98
 
99
  The request supplies only grid identities and a named relation. Fields, periods, source
100
  identities and values are read from this tenant; nothing is authored by this endpoint.
@@ -106,66 +118,79 @@ def related_metrics(table_key: str, body: dict = Body(default=None),
106
  import automation_engine
107
 
108
  body = body if isinstance(body, dict) else {}
109
- pin = body.get("related") or {}
110
  pids = body.get("pids")
111
- if (table_key != "product_data" or not isinstance(pin, dict)
112
- or pin.get("table") != "customer_data"
113
- or type(pin.get("record")) is not int or pin["record"] <= 0
114
- or not isinstance(pids, list) or not pids
115
  or any(type(pid) is not int or pid <= 0 for pid in pids)):
116
- raise err(400, "bad_metric_scope", "Name the origin customer and related product records.")
117
  viewer = copy.copy(session)
118
  viewer.runtime = _MetricReadRuntime(session.runtime)
119
  try:
120
- # Both endpoints and the actual bridge are permission-bearing databases.
121
- for key in ("customer_data", "product_data", "ut_odoo_order_lines"):
122
- viewer.require(key)
123
- entries = routes_grid.related_path_entries(viewer, "customer_data", 1)
124
- via = pin.get("via")
125
- edge = relations.pick_path(entries, via) if isinstance(via, list) else relations.pick(entries, via)
126
- if (edge is None or edge.get("target") != "product_data"
127
- or edge.get("via", {}).get("field") != "products_ordered"):
128
- raise err(403, "metric_relation_refused", "This Products ordered relation is unavailable.")
129
- source_fields = routes_grid._source_fields(viewer, "customer_data")
130
- hidden = perm_scope.hidden_keys(viewer.user, "customer_data", source_fields, st=viewer.runtime)
131
- if "products_ordered" in hidden:
132
- raise err(403, "metric_relation_refused", "This Products ordered relation is unavailable.")
133
- customers = perm_scope.scoped_table(viewer.user, "customer_data", st=viewer.runtime)
134
- if not any(r.get("pid") == pin["record"] for r in customers):
135
- raise err(403, "metric_record_refused", "The origin record is not available to this account.")
136
- products = perm_scope.scoped_table(viewer.user, "product_data", st=viewer.runtime)
137
  requested = set(pids)
138
  selected = [r for r in products if r.get("pid") in requested]
139
- if (len(selected) != len(requested)
140
- or any(type(r.get("product_id")) is not int or r["product_id"] <= 0 for r in selected)):
141
  raise err(403, "metric_record_refused", "The destination records cannot be scoped for this account.")
142
- # A bridge restriction that cannot be translated must never be silently dropped.
143
- bridge_fields = perm_scope.scoped_fields(viewer.user, "ut_odoo_order_lines", st=viewer.runtime)
144
- declared = perm_scope.entry(viewer.user, "ut_odoo_order_lines") or {}
145
- if (perm_scope.row_scope_applies(viewer.user, "ut_odoo_order_lines")
146
- or (not viewer.admin and declared.get("hiddenFields"))
147
- or not {"partner_id", "product_id"}.issubset({f["key"] for f in bridge_fields})):
148
- raise err(409, "metric_scope_unsupported", "Order-line permission restrictions cannot be applied to these Metrics yet.")
149
- scopes = [perm_scope.derive_pool_scope(viewer.user, key)
150
- for key in ("customer_data", "product_data", "ut_odoo_order_lines")]
151
- teams = {team for team, _ in scopes if team is not None}
152
- agents = {agent for _, agent in scopes if agent is not None}
153
- if len(teams) > 1 or len(agents) > 1:
154
- raise err(403, "metric_scope_conflict", "The related databases have incompatible permission scopes.")
155
- fields = _related_product_fields(viewer, products)
156
- values, reasons = automation_engine.related_product_metric_values(
157
- viewer.runtime, pin["record"], selected, fields, routes_products.product_measures(viewer),
158
- team_id=next(iter(teams), None), agent=next(iter(agents), None))
159
  return {"ok": True, "values": values, "fields": [f["key"] for f in fields],
160
- "scope": {"customer": pin["record"],
161
- "products": {r["pid"]: r["product_id"] for r in selected}},
162
- "reason": " ".join(reasons)}
 
 
163
  except (perm_scope.Denied, perm_scope.UnknownTable):
164
  raise err(403, "metric_record_refused", "The related records are not available to this account.")
165
  except (perm_scope.Unresolvable, RuntimeError, ValueError):
166
  raise err(409, "metric_scope_unavailable", "Scoped Metrics could not be read. Reopen the related records after the database is ready.")
167
 
168
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
169
  def _ut():
170
  import core.user_tables as user_tables
171
  return user_tables
@@ -2277,7 +2302,8 @@ def _thin_json(fields, merged, table_key=""):
2277
 
2278
 
2279
  @router.get("/tables/{table_key}/rows")
2280
- def table_rows(table_key: str, session: Session = Depends(require_session)):
 
2281
  """The `/customers`-shaped envelope for one user table: `{fields, rows, today, pulled_at,
2282
  identity}` — so the client's generic topic fetch consumes it with zero new parsing.
2283
 
@@ -2299,7 +2325,7 @@ def table_rows(table_key: str, session: Session = Depends(require_session)):
2299
  # PRE-WRITE snapshot, and handing one to a path that writes and then reads back would report the
2300
  # value it replaced (contract C5).
2301
  _lent = _ut().lend(session.runtime)
2302
- g = ut_assembly(session, table_key, st=_lent)
2303
  # ⛔ THE OVERLAY WAS NEVER ACTUALLY MERGED, and the docstring above has described the merge
2304
  # this line does not perform since the route was written (owner item 3, 2026-08-09:
2305
  # *"Using the swipe, fast doesn't register the CHANGE. I went back and it all got reseted"*).
@@ -2361,6 +2387,12 @@ def table_rows(table_key: str, session: Session = Depends(require_session)):
2361
  # ⭐⭐ WAVE-34 (R13) — the per-cell enrichment STATE rides the row, beside `_created`/`lat`/
2362
  # `lon`. See `_stamp_ai_states` for why it is a row key rather than a map beside `rows`.
2363
  _stamp_ai_states(table_key, g["fields"], rows, st=_lent)
 
 
 
 
 
 
2364
  # ⭐ R6's SECOND SENTENCE, ON THE WIRE (W30-T29). *"if there is lag or it can't be done, you
2365
  # need to explicitly tell me why and recommend a fix."* A ceiling that still applies to this
2366
  # database says so here, with its cause and the recommendation, rather than waiting to be
@@ -2382,16 +2414,24 @@ def table_rows(table_key: str, session: Session = Depends(require_session)):
2382
  if str(pid) in _zone_pids])
2383
  for zone in _ut().zones(table_key, st=_lent)]
2384
  return {"fields": _field_axes(g["fields"]), "rows": rows, "today": g["today"],
 
2385
  "zones": _zones,
2386
  "docs": _ge.docs_for(g["pids"], scope_key=table_key, uname=session.uname,
2387
  admin=session.admin, st=session.runtime),
2388
  "pulled_at": time.strftime("%Y-%m-%d %H:%M"),
2389
  "identity": {"pid": "pid"},
2390
  "scope": {"table": table_key, "rowCount": len(rows)},
2391
- "limits": [_report] if _report else [],
2392
  "recordsMutable": _ut().records_mutable(table_key, st=_lent)}
2393
 
2394
 
 
 
 
 
 
 
 
2395
  #: The per-cell provenance a row carries on the wire, one key per enrichment column.
2396
  #: ⛔ A ROW KEY RATHER THAN A SIBLING MAP, and the choice is load-bearing rather than cosmetic.
2397
  #: A `{colId: {pid: state}}` map beside `rows` would need a new PROP on `RecordDetail` and a new
 
68
  raise AttributeError(name)
69
 
70
 
71
+ def _related_product_fields(session, rows, table_key='product_data'):
72
  """Resolve authored Metric definitions through the existing workspace and field wall."""
73
  import aios_grid
74
  from core import grid_events, perm_scope, shared_overlay
75
  from modules import product_data as pd
76
+ import routes_customers
77
+
78
+ scope = {'product_data': 'product', 'customer_data': 'customer'}.get(table_key, table_key)
79
+ if table_key == 'product_data':
80
+ table, base = pd.table_ops(session.runtime), aios_grid.product_fields()
81
+ shared_key = pd.TABLE_KEY
82
+ elif table_key == 'customer_data':
83
+ table, base = routes_customers._customer_table(session), aios_grid.FIELDS
84
+ shared_key = routes_customers._shared_key()
85
+ else:
86
+ table = _ops(session, table_key)
87
+ base = perm_scope.scoped_fields(session.user, table_key, st=session.runtime)
88
+ shared_key = table_key
89
 
90
  pids = frozenset(r["pid"] for r in rows)
91
  ctx = grid_events.EventCtx(uname=session.uname, allowed_pids=pids, fields=[],
92
  hidden_keys=set(), admin=session.admin, fallback_ws=None,
93
+ seen_ids={}, st=session.runtime, scope_key=scope, table=table)
 
94
  ws = grid_events.table_workspace(ctx, allowed_pids=pids, consume_corrections=False)
95
  _, fields, _, _ = aios_grid.workspace_wire(
96
+ ws, session.uname, set(pids), defs={}, scope_key=scope, with_cohorts=False,
97
+ fields_base=base, st=session.runtime)
98
  have = {f["key"] for f in fields}
99
  fields = list(fields) + [dict(f, source="overlay", shared=True)
100
+ for key, f in shared_overlay.fields(shared_key, st=session.runtime).items()
101
  if key not in have]
102
+ hidden = perm_scope.hidden_keys(session.user, table_key, fields, st=session.runtime)
103
  return [f for f in fields if f.get("measure") and f["key"] not in hidden]
104
 
105
 
106
  @router.post("/tables/{table_key}/related-metrics")
107
  def related_metrics(table_key: str, body: dict = Body(default=None),
108
  session: Session = Depends(require_session)):
109
+ """R5: any offered relation, with the rows door's exact walled membership.
110
 
111
  The request supplies only grid identities and a named relation. Fields, periods, source
112
  identities and values are read from this tenant; nothing is authored by this endpoint.
 
118
  import automation_engine
119
 
120
  body = body if isinstance(body, dict) else {}
121
+ pin = body.get("related")
122
  pids = body.get("pids")
123
+ if (not isinstance(pin, dict) or not isinstance(pids, list)
 
 
 
124
  or any(type(pid) is not int or pid <= 0 for pid in pids)):
125
+ raise err(400, "bad_metric_scope", "Name the origin record, relation and linked records.")
126
  viewer = copy.copy(session)
127
  viewer.runtime = _MetricReadRuntime(session.runtime)
128
  try:
129
+ compiled, team_id = routes_grid.related_measure_pin(viewer, table_key, pin, pids)
130
+ # Read actual rows, not the fields-only door introduced by T24.
131
+ products = perm_scope.scoped_table(viewer.user, table_key, st=viewer.runtime)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
132
  requested = set(pids)
133
  selected = [r for r in products if r.get("pid") in requested]
134
+ if len(selected) != len(requested):
 
135
  raise err(403, "metric_record_refused", "The destination records cannot be scoped for this account.")
136
+ fields = _related_product_fields(viewer, products, table_key)
137
+ from core import measure_resolve
138
+ if not perm_scope.may_metrics(viewer.user, table_key):
139
+ offer = []
140
+ elif table_key == 'customer_data':
141
+ offer = measure_resolve.offer(team_id)
142
+ elif table_key == 'product_data':
143
+ offer = routes_products.product_measures(viewer)
144
+ else:
145
+ offer = ut_measures(table_key, viewer)
146
+ admitted = {m['key'] for m in offer}
147
+ fields = [f for f in fields if f['measure'].get('key') in admitted]
148
+ values = automation_engine.related_metric_values(
149
+ viewer.runtime, table_key, selected, fields, offer, compiled, team_id=team_id)
 
 
 
150
  return {"ok": True, "values": values, "fields": [f["key"] for f in fields],
151
+ "refusals": values.refusals,
152
+ "scope": {"table": table_key, "related": pin, "pids": sorted(requested),
153
+ "customer": pin.get('record'),
154
+ "products": {r['pid']: r.get('product_id') for r in selected}},
155
+ "reason": ' '.join(dict.fromkeys(r['message'] for r in values.refusals))}
156
  except (perm_scope.Denied, perm_scope.UnknownTable):
157
  raise err(403, "metric_record_refused", "The related records are not available to this account.")
158
  except (perm_scope.Unresolvable, RuntimeError, ValueError):
159
  raise err(409, "metric_scope_unavailable", "Scoped Metrics could not be read. Reopen the related records after the database is ready.")
160
 
161
 
162
+ def scope_linked_metrics(session, table_key, rows, fields, offer, related):
163
+ """Replace metric cells before a pinned payload can be filtered or aggregated."""
164
+ if not related or not any(f.get('measure') for f in fields):
165
+ return rows, fields, []
166
+ from core import perm_scope
167
+ import routes_grid
168
+ import automation_engine
169
+
170
+ admitted = {m['key'] for m in offer} if perm_scope.may_metrics(session.user, table_key) else set()
171
+ hidden = {f['key'] for f in fields if f.get('measure')
172
+ and f['measure'].get('key') not in admitted}
173
+ fields = [f for f in fields if f['key'] not in hidden]
174
+ rows = [{k: v for k, v in row.items() if k not in hidden} for row in rows]
175
+ metrics = [f for f in fields if f.get('measure')]
176
+ if not metrics:
177
+ return rows, fields, []
178
+ pin, team_id = routes_grid.related_measure_pin(session, table_key, related,
179
+ [row['pid'] for row in rows])
180
+ answer = automation_engine.related_metric_values(session.runtime, table_key, rows, metrics,
181
+ offer, pin, team_id=team_id)
182
+ return [{**row, **answer[row['pid']]} for row in rows], fields, answer.refusals
183
+
184
+
185
+ def linked_metric_limits(refusals):
186
+ """The same refusal accompanies rows, filters and aggregate siblings."""
187
+ if not refusals:
188
+ return []
189
+ return [dict(subject='Linked metrics',
190
+ cause=' '.join(dict.fromkeys(marker['message'] for marker in refusals)),
191
+ recommendation='Check the metric source binding and period, then reopen this tab.')]
192
+
193
+
194
  def _ut():
195
  import core.user_tables as user_tables
196
  return user_tables
 
2302
 
2303
 
2304
  @router.get("/tables/{table_key}/rows")
2305
+ def table_rows(table_key: str, session: Session = Depends(require_session),
2306
+ related: str = None):
2307
  """The `/customers`-shaped envelope for one user table: `{fields, rows, today, pulled_at,
2308
  identity}` — so the client's generic topic fetch consumes it with zero new parsing.
2309
 
 
2325
  # PRE-WRITE snapshot, and handing one to a path that writes and then reads back would report the
2326
  # value it replaced (contract C5).
2327
  _lent = _ut().lend(session.runtime)
2328
+ g = ut_assembly(session, table_key, st=_lent, consume_corrections=not bool(related))
2329
  # ⛔ THE OVERLAY WAS NEVER ACTUALLY MERGED, and the docstring above has described the merge
2330
  # this line does not perform since the route was written (owner item 3, 2026-08-09:
2331
  # *"Using the swipe, fast doesn't register the CHANGE. I went back and it all got reseted"*).
 
2387
  # ⭐⭐ WAVE-34 (R13) — the per-cell enrichment STATE rides the row, beside `_created`/`lat`/
2388
  # `lon`. See `_stamp_ai_states` for why it is a row key rather than a map beside `rows`.
2389
  _stamp_ai_states(table_key, g["fields"], rows, st=_lent)
2390
+ from routes_odoo_tables import narrow_related_rows
2391
+ rows = narrow_related_rows(session, table_key, rows, related)
2392
+ rows, g['fields'], metric_refusals = scope_linked_metrics(
2393
+ session, table_key, rows, g['fields'], g['measures'], related)
2394
+ if related:
2395
+ g["pids"] = frozenset(row["pid"] for row in rows)
2396
  # ⭐ R6's SECOND SENTENCE, ON THE WIRE (W30-T29). *"if there is lag or it can't be done, you
2397
  # need to explicitly tell me why and recommend a fix."* A ceiling that still applies to this
2398
  # database says so here, with its cause and the recommendation, rather than waiting to be
 
2414
  if str(pid) in _zone_pids])
2415
  for zone in _ut().zones(table_key, st=_lent)]
2416
  return {"fields": _field_axes(g["fields"]), "rows": rows, "today": g["today"],
2417
+ "refusals": metric_refusals,
2418
  "zones": _zones,
2419
  "docs": _ge.docs_for(g["pids"], scope_key=table_key, uname=session.uname,
2420
  admin=session.admin, st=session.runtime),
2421
  "pulled_at": time.strftime("%Y-%m-%d %H:%M"),
2422
  "identity": {"pid": "pid"},
2423
  "scope": {"table": table_key, "rowCount": len(rows)},
2424
+ "limits": ([_report] if _report else []) + linked_metric_limits(metric_refusals),
2425
  "recordsMutable": _ut().records_mutable(table_key, st=_lent)}
2426
 
2427
 
2428
+ @router.post("/tables/{table_key}/aggregates")
2429
+ def table_aggregates(table_key: str, body: dict = Body(default=None),
2430
+ session: Session = Depends(require_session)):
2431
+ from routes_odoo_tables import odoo_table_aggregates
2432
+ return odoo_table_aggregates(table_key, body=body, session=session)
2433
+
2434
+
2435
  #: The per-cell provenance a row carries on the wire, one key per enrichment column.
2436
  #: ⛔ A ROW KEY RATHER THAN A SIBLING MAP, and the choice is load-bearing rather than cosmetic.
2437
  #: A `{colId: {pid: state}}` map beside `rows` would need a new PROP on `RecordDetail` and a new
platform/core/connector_sync.py CHANGED
@@ -8,6 +8,7 @@ from __future__ import annotations
8
  import datetime as _dt
9
  import hashlib
10
  import json
 
11
  import time
12
  import uuid
13
 
@@ -20,6 +21,77 @@ _ERROR_LIMIT = 50
20
  _DEFAULT_CONNECTION = "default"
21
  _PROVIDERS = {}
22
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
23
  # One receipt per immutable database identity. No credentials, session, or source values.
24
  JOBS_KEY = "connector_materialization_jobs"
25
  MAX_ATTEMPTS = 3
@@ -363,3 +435,5 @@ register_provider(
363
  label="Amazon",
364
  retry_hint="No sync runner is wired for this connector yet.",
365
  )
 
 
 
8
  import datetime as _dt
9
  import hashlib
10
  import json
11
+ import threading
12
  import time
13
  import uuid
14
 
 
21
  _DEFAULT_CONNECTION = "default"
22
  _PROVIDERS = {}
23
 
24
+ # One in-flight Sync now per (provider, tenant). Only the resident resync thread drains this
25
+ # intent desk. Nothing here imports a provider, calls a runner, or writes to the mirror/store.
26
+ _SYNC_REQUESTS = {}
27
+ _SYNC_REQUEST_LOCK = threading.Lock()
28
+ _SYNC_WAKE = threading.Event()
29
+
30
+
31
+ def request_sync(provider, tenant, *, requested_by="", now=None):
32
+ """Queue an intent. A duplicate queued/running request returns accepted=False."""
33
+ if provider not in _PROVIDERS:
34
+ raise ValueError("This connector is not registered for sync.")
35
+ tenant = str(tenant or "").strip()
36
+ if not tenant:
37
+ raise ValueError("A tenant is required for sync.")
38
+ with _SYNC_REQUEST_LOCK:
39
+ previous = _SYNC_REQUESTS.get((provider, tenant))
40
+ if previous and previous["state"] in ("queued", "running"):
41
+ return {**previous, "accepted": False}
42
+ receipt = {"provider": provider, "tenant": tenant, "state": "queued",
43
+ "requestedAt": time.time() if now is None else now,
44
+ "startedAt": None, "finishedAt": None, "detail": "",
45
+ "requestedBy": str(requested_by or ""), "accepted": True}
46
+ if requested_by == "first load" and previous and previous.get("firstLoad"):
47
+ # A continuation keeps the safe numeric progress visible while waiting for the writer.
48
+ receipt.update(detail=previous["detail"], firstLoad=dict(previous["firstLoad"]))
49
+ _SYNC_REQUESTS[(provider, tenant)] = receipt
50
+ _SYNC_WAKE.set()
51
+ return dict(receipt)
52
+
53
+
54
+ def sync_request(provider, tenant):
55
+ """Return a detached current receipt, or None."""
56
+ with _SYNC_REQUEST_LOCK:
57
+ receipt = _SYNC_REQUESTS.get((provider, tenant))
58
+ if receipt is None:
59
+ return None
60
+ result = {**receipt, "accepted": False}
61
+ if "firstLoad" in result:
62
+ result["firstLoad"] = dict(result["firstLoad"])
63
+ return result
64
+
65
+
66
+ def take_sync_requests():
67
+ """Claim every queued intent atomically, on the resident resync thread."""
68
+ with _SYNC_REQUEST_LOCK:
69
+ _SYNC_WAKE.clear()
70
+ claimed = []
71
+ for receipt in _SYNC_REQUESTS.values():
72
+ if receipt["state"] == "queued":
73
+ receipt.update(state="running", startedAt=time.time(), accepted=False)
74
+ claimed.append(dict(receipt))
75
+ return claimed
76
+
77
+
78
+ def finish_sync_request(provider, tenant, *, ok, detail="", now=None, first_load=None):
79
+ """Finish a claimed intent. The API runner supplies a safe cause sentence, never raw errors."""
80
+ with _SYNC_REQUEST_LOCK:
81
+ receipt = _SYNC_REQUESTS.get((provider, tenant))
82
+ if receipt is None or receipt["state"] != "running":
83
+ return None
84
+ receipt.update(state="done" if ok else "failed", detail=str(detail or "")[:300],
85
+ finishedAt=time.time() if now is None else now, accepted=False)
86
+ if first_load is not None:
87
+ receipt["firstLoad"] = dict(first_load)
88
+ return dict(receipt)
89
+
90
+
91
+ def sync_wake_event():
92
+ """The event the resident thread waits on between passes."""
93
+ return _SYNC_WAKE
94
+
95
  # One receipt per immutable database identity. No credentials, session, or source values.
96
  JOBS_KEY = "connector_materialization_jobs"
97
  MAX_ATTEMPTS = 3
 
435
  label="Amazon",
436
  retry_hint="No sync runner is wired for this connector yet.",
437
  )
438
+ register_provider("meta_ads", label="Meta Ads",
439
+ retry_hint="Use Sync now to retry the Meta Ads pull.")
platform/core/dependents.py CHANGED
@@ -47,7 +47,13 @@ walked directly instead, exactly as the shape allows.
47
  FIELD KEY (a string) of the link the rollup traverses. A rollup may also carry no `link` at all
48
  (the `{'source': {...}}` shape, which joins through a topic dim). Every walker below branches on
49
  `field['type']` first and on which key is present second.
 
 
 
 
50
  """
 
 
51
  import core.chart_system as chart_system
52
  import core.route_system as route_system
53
  import core.shares as shares
@@ -60,6 +66,13 @@ from core.table_store import ASSIGNED_KEY, SHARED_KEY
60
  #: happened to register first (W49-T11 registers `sheet_cell` after the merge).
61
  KIND_ORDER = ('view', 'route', 'link', 'rollup', 'grant', 'chart', 'sheet_cell')
62
 
 
 
 
 
 
 
 
63
  #: Singular / plural noun phrase per kind. ⛔ THE CASING IS R23's OWN — lowercase `views`, capital
64
  #: `Route`, capital `Sheet cells` — because the ruling quotes the sentence the user reads.
65
  _NOUNS = {
@@ -75,6 +88,36 @@ _NOUNS = {
75
  _PROVIDERS = {}
76
 
77
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
78
  def noun(kind, count):
79
  """The noun phrase for `count` of `kind`, agreeing in number."""
80
  pair = _NOUNS.get(str(kind or ''))
@@ -120,7 +163,7 @@ def clean_target(target):
120
  return {'kind': kind, 'key': key, 'database': database}
121
 
122
 
123
- def _dependent(kind, ids):
124
  """A Dependent, or None when nothing depends. ⛔ NONE IS THE ZERO CASE — never `count: 0`."""
125
  seen, out = set(), []
126
  for raw in ids or ():
@@ -130,7 +173,13 @@ def _dependent(kind, ids):
130
  out.append(value)
131
  if not out:
132
  return None
133
- return {'kind': kind, 'label': noun(kind, len(out)), 'count': len(out), 'ids': out}
 
 
 
 
 
 
134
 
135
 
136
  def dependents(st, target):
@@ -162,10 +211,36 @@ def dependents_report(st, target):
162
  count = int(item.get('count') or len(ids) or 0)
163
  if count <= 0:
164
  continue
165
- found.append({'kind': str(item.get('kind') or kind),
166
  'label': str(item.get('label') or noun(kind, count)),
167
  'count': count,
168
- 'ids': [str(i) for i in ids]})
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
169
  order = {kind: index for index, kind in enumerate(KIND_ORDER)}
170
  found.sort(key=lambda item: (order.get(item['kind'], len(order)), item['kind']))
171
  return {'dependents': found, 'errors': errors}
@@ -334,16 +409,27 @@ def view_dependents(st, target):
334
  """
335
  kind, key, database = target['kind'], target['key'], target['database']
336
  if kind == 'table':
337
- return _dependent('view', [vid for _owner, vid, _v in walk_views(st, key)])
 
 
338
  if kind == 'view':
339
  if not database:
340
  return None
341
- return _dependent('view', _assigned_ids(st, database, key))
342
- hits = []
 
 
 
 
 
 
 
 
343
  for _owner, view_id, view in walk_views(st, database):
344
- if _view_names_field(view, key):
345
- hits.append(view_id)
346
- return _dependent('view', hits)
 
347
 
348
 
349
  def _view_names_field(view, field_key):
@@ -383,21 +469,31 @@ def route_dependents(st, target):
383
  a `geographicField`, which is what makes them a FIELD dependent too.
384
  """
385
  kind, key, database = target['kind'], target['key'], target['database']
386
- routes, hits = _routes(st), []
387
  if kind == 'view':
388
- hits += [str(r.get('id')) for r in routes if str(r.get('sourceViewId') or '') == key]
389
- hits += [str(z.get('id')) for z in _zones(st, database or None)
390
- if str(z.get('sourceViewId') or '') == key]
391
- return _dependent('route', hits)
392
- if kind == 'table':
393
- view_ids = {vid for _owner, vid, _v in walk_views(st, key)}
394
- hits += [str(r.get('id')) for r in routes
395
- if str(r.get('sourceViewId') or '') in view_ids]
396
- hits += [str(z.get('id')) for z in _zones(st, key)]
397
- return _dependent('route', hits)
398
- hits += [str(z.get('id')) for z in _zones(st, database)
399
- if str(z.get('geographicField') or '') == key]
400
- return _dependent('route', hits)
 
 
 
 
 
 
 
 
 
 
401
 
402
 
403
  def link_dependents(st, target):
@@ -410,18 +506,18 @@ def link_dependents(st, target):
410
  kind, key = target['kind'], target['key']
411
  if kind == 'view':
412
  return None
413
- hits = []
414
  for table_key, definition in _defs(st).items():
415
  for field in _fields(definition):
416
  bag = _link_bag(field)
417
  if bag is None:
418
  continue
419
  if kind == 'table' and str(bag.get('table') or '') == key and str(table_key) != key:
420
- hits.append(f'{table_key}:{field.get("key")}')
421
  elif kind == 'field' and str(bag.get('inverse') or '') == key \
422
  and str(bag.get('table') or '') == str(target['database']):
423
- hits.append(f'{table_key}:{field.get("key")}')
424
- return _dependent('link', hits)
425
 
426
 
427
  def rollup_dependents(st, target):
@@ -435,7 +531,7 @@ def rollup_dependents(st, target):
435
  kind, key = target['kind'], target['key']
436
  if kind == 'view':
437
  return None
438
- hits = []
439
  for table_key, definition in _defs(st).items():
440
  fields = _fields(definition)
441
  by_key = {str(f.get('key') or ''): f for f in fields}
@@ -449,18 +545,18 @@ def rollup_dependents(st, target):
449
  hop_bag = _link_bag(hop_field) if hop_field else None
450
  if kind == 'table':
451
  if source and str(source.get('topic') or '') == key:
452
- hits.append(f'{table_key}:{field.get("key")}')
453
  elif hop_bag is not None and str(hop_bag.get('table') or '') == key:
454
- hits.append(f'{table_key}:{field.get("key")}')
455
  continue
456
  if str(target['database']) and str(table_key) != str(target['database']):
457
  continue
458
  if hop == key or str(bag.get('field') or '') == key:
459
- hits.append(f'{table_key}:{field.get("key")}')
460
  elif source and key in (str(source.get('on') or ''), str(source.get('groupBy') or ''),
461
  str(source.get('measure') or '')):
462
- hits.append(f'{table_key}:{field.get("key")}')
463
- return _dependent('rollup', hits)
464
 
465
 
466
  def grant_dependents(st, target):
@@ -471,13 +567,21 @@ def grant_dependents(st, target):
471
  * field -> the `field` grant on `<database>:<key>`
472
  """
473
  kind, key, database = target['kind'], target['key'], target['database']
 
 
 
 
 
 
 
 
474
  if kind == 'view':
475
- return _dependent('grant', share_audience(st, key)['names'])
476
  if kind == 'field':
477
  if not database:
478
  return None
479
  record = shares.grants('field', shares.field_oid(database, key), st=st)
480
- return _dependent('grant', [str(e.get('user') or '') for e in (record.get('entries') or ())])
481
  holders = [str(e.get('user') or '')
482
  for e in (shares.grants('database', key, st=st).get('entries') or ())]
483
  try:
@@ -490,21 +594,110 @@ def grant_dependents(st, target):
490
  continue
491
  for entry in (shares.grants('field', oid, st=st).get('entries') or ()):
492
  holders.append(str(entry.get('user') or ''))
493
- return _dependent('grant', holders)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
494
 
495
 
496
  def chart_dependents(st, target):
497
- """Saved charts filed against the target DATABASE.
498
 
499
  ⛔ A CHART NEVER DEPENDS ON A VIEW, and that is `chart_system`'s stated contract rather than an
500
  omission here: a chart's `config` is OPAQUE and this file must not start reading keys out of
501
  it to guess at a reference. Deleting a view cannot delete a chart, so it must not disclose one.
 
 
 
 
 
502
  """
503
  kind, key = target['kind'], target['key']
504
  if kind != 'table':
505
  return None
506
- return _dependent('chart', [str(c.get('id')) for c in _charts(st)
507
- if str(c.get('database') or '') == key])
 
 
 
 
 
 
 
 
 
 
 
 
508
 
509
 
510
  register('view', view_dependents)
 
47
  FIELD KEY (a string) of the link the rollup traverses. A rollup may also carry no `link` at all
48
  (the `{'source': {...}}` shape, which joins through a topic dim). Every walker below branches on
49
  `field['type']` first and on which key is present second.
50
+
51
+ W60-T31 / C3: grouped kind/label/count/ids retain their meanings. Additive `items` names each
52
+ id in order and gives its address or a reason it cannot be opened. Data addresses use only
53
+ the existing #/data? prefix; workbook addresses belong to the Sheet provider (C2).
54
  """
55
+ from urllib.parse import parse_qs, urlencode
56
+
57
  import core.chart_system as chart_system
58
  import core.route_system as route_system
59
  import core.shares as shares
 
66
  #: happened to register first (W49-T11 registers `sheet_cell` after the merge).
67
  KIND_ORDER = ('view', 'route', 'link', 'rollup', 'grant', 'chart', 'sheet_cell')
68
 
69
+ #: Built-in Default views are not dependents, including their saved owner copies. Their ids are
70
+ #: shared by EVERY database, so counting them charges one database's Default view to another.
71
+ #: `aios_grid.py` mints `all-customers` on every topic; its `IG_OVERVIEW_ID` is `tpl_overview`.
72
+ #: Hardcoded here because `core/` may not reach UP into `aios_grid`; `verify_shared_views.py`
73
+ #: pins this pair against that module so the declarations cannot drift.
74
+ PINNED_VIEW_IDS = frozenset({'all-customers', 'tpl_overview'})
75
+
76
  #: Singular / plural noun phrase per kind. ⛔ THE CASING IS R23's OWN — lowercase `views`, capital
77
  #: `Route`, capital `Sheet cells` — because the ruling quotes the sentence the user reads.
78
  _NOUNS = {
 
88
  _PROVIDERS = {}
89
 
90
 
91
+ DATA_HASH_PREFIX = '#/data?'
92
+
93
+
94
+ def data_hash(database, **params):
95
+ """Build a #/data?database=... address. The only hash builder in this module."""
96
+ database = str(database or '').strip()
97
+ if not database:
98
+ return None
99
+ query = {'database': database}
100
+ query.update({key: str(value) for key, value in params.items()
101
+ if key != 'database' and value is not None and str(value) != ''})
102
+ return DATA_HASH_PREFIX + urlencode(query)
103
+
104
+
105
+ def _dependent_item(item_id, label, href=None, reason=''):
106
+ """A named thing with an existing hash address or an explicit explanation."""
107
+ item_id = str(item_id or '')
108
+ label = str(label or item_id)
109
+ href = href if isinstance(href, str) and href.startswith((DATA_HASH_PREFIX, '#/sheet?')) else None
110
+ return {'id': item_id, 'label': label, 'href': href,
111
+ 'reason': str(reason or '') if href else
112
+ str(reason or f'{label} has no direct address available.')}
113
+
114
+
115
+ def _field_item(table_key, field):
116
+ key = str(field.get('key') or '')
117
+ return _dependent_item(f'{table_key}:{key}', field.get('label') or key,
118
+ data_hash(table_key, field=key) if key else None)
119
+
120
+
121
  def noun(kind, count):
122
  """The noun phrase for `count` of `kind`, agreeing in number."""
123
  pair = _NOUNS.get(str(kind or ''))
 
163
  return {'kind': kind, 'key': key, 'database': database}
164
 
165
 
166
+ def _dependent(kind, ids, items=None):
167
  """A Dependent, or None when nothing depends. ⛔ NONE IS THE ZERO CASE — never `count: 0`."""
168
  seen, out = set(), []
169
  for raw in ids or ():
 
173
  out.append(value)
174
  if not out:
175
  return None
176
+ result = {'kind': kind, 'label': noun(kind, len(out)), 'count': len(out), 'ids': out}
177
+ if items is not None:
178
+ by_id = {}
179
+ for item in items:
180
+ by_id.setdefault(str(item.get('id') or ''), item)
181
+ result['items'] = [by_id.get(value) or _dependent_item(value, value) for value in out]
182
+ return result
183
 
184
 
185
  def dependents(st, target):
 
211
  count = int(item.get('count') or len(ids) or 0)
212
  if count <= 0:
213
  continue
214
+ normalized = {'kind': str(item.get('kind') or kind),
215
  'label': str(item.get('label') or noun(kind, count)),
216
  'count': count,
217
+ 'ids': [str(i) for i in ids]}
218
+ # Lane A may supply a single Sheet address on the dependent itself. Preserve
219
+ # both that shape and per-id items; neither changes the legacy count or label.
220
+ if 'href' in item:
221
+ normalized['href'] = item['href'] if isinstance(item['href'], str) else None
222
+ if 'reason' in item:
223
+ normalized['reason'] = str(item.get('reason') or '')
224
+ # W60-T12 (combine-owned), 2026-09-14: `refusal` is the OTHER half of the same fact
225
+ # and was being dropped at this seam. A provider says "no address" with `href: None`
226
+ # AND says WHY in `refusal`; carrying the null while dropping the cause turns an
227
+ # explained dead end into an unexplained one, which is the defect R23's sentence
228
+ # exists to prevent. Both keys are optional and neither changes count or label.
229
+ if 'refusal' in item:
230
+ normalized['refusal'] = str(item.get('refusal') or '')
231
+ if isinstance(item.get('items'), list):
232
+ normalized['items'] = []
233
+ for entry in item['items']:
234
+ entry = entry if isinstance(entry, dict) else {'id': entry}
235
+ href = entry.get('href') if isinstance(entry.get('href'), str) else None
236
+ normalized['items'].append({
237
+ 'id': str(entry.get('id') or ''),
238
+ 'label': str(entry.get('label') or entry.get('id') or ''),
239
+ 'href': href,
240
+ 'reason': str(entry.get('reason') or ('' if href else
241
+ 'This dependent has no direct address available.')),
242
+ })
243
+ found.append(normalized)
244
  order = {kind: index for index, kind in enumerate(KIND_ORDER)}
245
  found.sort(key=lambda item: (order.get(item['kind'], len(order)), item['kind']))
246
  return {'dependents': found, 'errors': errors}
 
409
  """
410
  kind, key, database = target['kind'], target['key'], target['database']
411
  if kind == 'table':
412
+ items = [_dependent_item(vid, view.get('name') or vid, data_hash(key, view=vid))
413
+ for _owner, vid, view in walk_views(st, key) if vid not in PINNED_VIEW_IDS]
414
+ return _dependent('view', [item['id'] for item in items], items=items)
415
  if kind == 'view':
416
  if not database:
417
  return None
418
+ ids = _assigned_ids(st, database, key)
419
+ assignments = _table_doc(st, database).get(ASSIGNED_KEY) or {}
420
+ items = []
421
+ for item_id in ids:
422
+ recipient, _, view_id = item_id.partition(':')
423
+ view = assignments[recipient]['views'][view_id]
424
+ label = f'{recipient}: {view.get("name") or view_id}'
425
+ items.append(_dependent_item(item_id, label, data_hash(database, view=view_id)))
426
+ return _dependent('view', ids, items=items)
427
+ items = []
428
  for _owner, view_id, view in walk_views(st, database):
429
+ if view_id not in PINNED_VIEW_IDS and _view_names_field(view, key):
430
+ items.append(_dependent_item(view_id, view.get('name') or view_id,
431
+ data_hash(database, view=view_id)))
432
+ return _dependent('view', [item['id'] for item in items], items=items)
433
 
434
 
435
  def _view_names_field(view, field_key):
 
469
  a `geographicField`, which is what makes them a FIELD dependent too.
470
  """
471
  kind, key, database = target['kind'], target['key'], target['database']
472
+ routes, matched_routes, matched_zones = _routes(st), [], []
473
  if kind == 'view':
474
+ matched_routes = [r for r in routes if str(r.get('sourceViewId') or '') == key]
475
+ matched_zones = [z for z in _zones(st, database or None)
476
+ if str(z.get('sourceViewId') or '') == key]
477
+ elif kind == 'table':
478
+ view_ids = {vid for _owner, vid, _v in walk_views(st, key)
479
+ if vid not in PINNED_VIEW_IDS}
480
+ # A-QI7: Routes store no source database and are created only from customer_data.
481
+ # The database test must therefore use the target table key, not the tenant-wide Route
482
+ # list or a shared view id. Zones already carry their own table scope.
483
+ if str(key) == route_system.DEFAULT_ZONE_TABLE:
484
+ matched_routes = [r for r in routes if str(r.get('sourceViewId') or '') in view_ids]
485
+ matched_zones = _zones(st, key)
486
+ else:
487
+ matched_zones = [z for z in _zones(st, database)
488
+ if str(z.get('geographicField') or '') == key]
489
+ items = [_dependent_item(str(r.get('id')), r.get('name') or r.get('id'),
490
+ data_hash(route_system.DEFAULT_ZONE_TABLE, route=r.get('id')))
491
+ for r in matched_routes]
492
+ for zone in matched_zones:
493
+ name = zone.get('name') or zone.get('id')
494
+ items.append(_dependent_item(str(zone.get('id')), name, reason=
495
+ f'{name} has no direct address. Edit this zone in the Map view Zones menu.'))
496
+ return _dependent('route', [item['id'] for item in items], items=items)
497
 
498
 
499
  def link_dependents(st, target):
 
506
  kind, key = target['kind'], target['key']
507
  if kind == 'view':
508
  return None
509
+ items = []
510
  for table_key, definition in _defs(st).items():
511
  for field in _fields(definition):
512
  bag = _link_bag(field)
513
  if bag is None:
514
  continue
515
  if kind == 'table' and str(bag.get('table') or '') == key and str(table_key) != key:
516
+ items.append(_field_item(table_key, field))
517
  elif kind == 'field' and str(bag.get('inverse') or '') == key \
518
  and str(bag.get('table') or '') == str(target['database']):
519
+ items.append(_field_item(table_key, field))
520
+ return _dependent('link', [item['id'] for item in items], items=items)
521
 
522
 
523
  def rollup_dependents(st, target):
 
531
  kind, key = target['kind'], target['key']
532
  if kind == 'view':
533
  return None
534
+ items = []
535
  for table_key, definition in _defs(st).items():
536
  fields = _fields(definition)
537
  by_key = {str(f.get('key') or ''): f for f in fields}
 
545
  hop_bag = _link_bag(hop_field) if hop_field else None
546
  if kind == 'table':
547
  if source and str(source.get('topic') or '') == key:
548
+ items.append(_field_item(table_key, field))
549
  elif hop_bag is not None and str(hop_bag.get('table') or '') == key:
550
+ items.append(_field_item(table_key, field))
551
  continue
552
  if str(target['database']) and str(table_key) != str(target['database']):
553
  continue
554
  if hop == key or str(bag.get('field') or '') == key:
555
+ items.append(_field_item(table_key, field))
556
  elif source and key in (str(source.get('on') or ''), str(source.get('groupBy') or ''),
557
  str(source.get('measure') or '')):
558
+ items.append(_field_item(table_key, field))
559
+ return _dependent('rollup', [item['id'] for item in items], items=items)
560
 
561
 
562
  def grant_dependents(st, target):
 
567
  * field -> the `field` grant on `<database>:<key>`
568
  """
569
  kind, key, database = target['kind'], target['key'], target['database']
570
+
571
+ def named_grants(names):
572
+ subject = {'view': 'view', 'table': 'database', 'field': 'field'}[kind]
573
+ items = [_dependent_item(name, name, reason=
574
+ f'{name} has no direct access address. Change their access from this '
575
+ f'{subject}\'s share dialog.') for name in names]
576
+ return _dependent('grant', names, items=items)
577
+
578
  if kind == 'view':
579
+ return named_grants(share_audience(st, key)['names'])
580
  if kind == 'field':
581
  if not database:
582
  return None
583
  record = shares.grants('field', shares.field_oid(database, key), st=st)
584
+ return named_grants([str(e.get('user') or '') for e in (record.get('entries') or ())])
585
  holders = [str(e.get('user') or '')
586
  for e in (shares.grants('database', key, st=st).get('entries') or ())]
587
  try:
 
594
  continue
595
  for entry in (shares.grants('field', oid, st=st).get('entries') or ()):
596
  holders.append(str(entry.get('user') or ''))
597
+ return named_grants(holders)
598
+
599
+
600
+ def _sheet_chart_items(st, target):
601
+ """Sheet charts drawn over a cell that depends on `target` (W60-T12, contract C2).
602
+
603
+ ⛔⛔ THE DEPENDENCY DECISION IS NOT REMADE HERE, AND THAT IS THE WHOLE DESIGN. Whether a CELL
604
+ depends on the target is `modules/sheet.py`'s answer, and `core/` may not reach UP into
605
+ `modules/` to ask it directly -- the same layering rule `PINNED_VIEW_IDS` is hardcoded for. So
606
+ this reads the ALREADY-REGISTERED `sheet_cell` provider's own rows and takes the cells it
607
+ named. One source of truth for the predicate, so a chart can never disagree with the cell it
608
+ is drawn over; and if nothing registered `sheet_cell` there are no sheet charts to report and
609
+ this is silent, exactly as an absent provider is everywhere else in this file.
610
+
611
+ ⚠ A CELL WITH NO ADDRESS CONTRIBUTES NO CHART ADDRESS. `sheet_cell` answers `href: None` plus a
612
+ cause when the destination is hidden or unreadable, and a link built anyway would open some
613
+ OTHER cell -- which is the defect W60-T12 exists to close, not one to reintroduce one layer up.
614
+ """
615
+ provider = _PROVIDERS.get('sheet_cell')
616
+ if provider is None:
617
+ return []
618
+ try:
619
+ rows = provider(st, dict(target))
620
+ except Exception:
621
+ return [] # a provider that raises omits its kind; so does this
622
+ wanted = {}
623
+ for row in rows if isinstance(rows, (list, tuple)) else ():
624
+ if not isinstance(row, dict) or row.get('kind') != 'sheet_cell':
625
+ continue
626
+ href = row.get('href')
627
+ if not isinstance(href, str) or not href.startswith('#/sheet?'):
628
+ continue
629
+ params = parse_qs(href.split('?', 1)[1])
630
+ workbook_id = (params.get('wb') or [''])[0]
631
+ tab_id = (params.get('tab') or [''])[0]
632
+ addr = (params.get('cell') or [''])[0]
633
+ if workbook_id and tab_id and addr:
634
+ wanted.setdefault((workbook_id, tab_id), []).append(addr)
635
+ if not wanted:
636
+ return []
637
+
638
+ from core import sheets as sheet_store
639
+ items, seen = [], set()
640
+ for workbook_id in dict.fromkeys(book for book, _ in wanted):
641
+ try:
642
+ book = sheet_store.get_workbook(st, workbook_id)
643
+ except Exception:
644
+ continue # an unreadable workbook is `sheet_cell`'s to report
645
+ for tab in book.get('sheets') or ():
646
+ tab_id = str(tab.get('id') or '')
647
+ addrs = wanted.get((workbook_id, tab_id)) or []
648
+ if not addrs:
649
+ continue
650
+ # ⚠ THE ADDRESS MATHS IS `core/sheets.py`'s, not a second copy. `_clean_range` accepts
651
+ # both `"B4"` and the chart's `{col0,row0,col1,row1}` and answers the same zero-based
652
+ # rectangle for each, so a cell and the chart over it cannot drift apart.
653
+ cells = [rect for rect in (sheet_store._clean_range(a) for a in addrs) if rect]
654
+ for chart in tab.get('charts') or ():
655
+ if not isinstance(chart, dict):
656
+ continue
657
+ chart_id = str(chart.get('id') or '')
658
+ rect = sheet_store._clean_range(chart.get('range'))
659
+ if not chart_id or chart_id in seen or not rect:
660
+ continue
661
+ if not any(rect['col0'] <= c['col0'] <= rect['col1']
662
+ and rect['row0'] <= c['row0'] <= rect['row1'] for c in cells):
663
+ continue
664
+ seen.add(chart_id)
665
+ label = str(chart.get('name') or chart.get('title') or '').strip() or (
666
+ f"Chart in {book.get('name') or workbook_id} / {tab.get('name') or tab_id}")
667
+ items.append(_dependent_item(chart_id, label, '#/sheet?' + urlencode(
668
+ {'wb': workbook_id, 'tab': tab_id, 'chart': chart_id})))
669
+ return items
670
 
671
 
672
  def chart_dependents(st, target):
673
+ """Saved charts filed against the target DATABASE, and Sheet charts drawn over its cells.
674
 
675
  ⛔ A CHART NEVER DEPENDS ON A VIEW, and that is `chart_system`'s stated contract rather than an
676
  omission here: a chart's `config` is OPAQUE and this file must not start reading keys out of
677
  it to guess at a reference. Deleting a view cannot delete a chart, so it must not disclose one.
678
+
679
+ ⭐ W60-T12 (combine-owned) ADDED THE SECOND SOURCE. A Sheet chart is not reachable from
680
+ `sheet_dependents` at all -- it is a sibling of the cells, not one of them -- so before this a
681
+ database could be switched off while a chart still drew from it, and R23's refusal would not
682
+ have said so. Charts are not read from the sheet document here; see `_sheet_chart_items`.
683
  """
684
  kind, key = target['kind'], target['key']
685
  if kind != 'table':
686
  return None
687
+ items = [_dependent_item(str(c.get('id')), c.get('name') or c.get('id'), c.get('href'),
688
+ '' if c.get('href') else
689
+ 'This chart has no direct address. Open it from Charts.')
690
+ for c in _charts(st) if str(c.get('database') or '') == key]
691
+ items += _sheet_chart_items(st, target)
692
+ row = _dependent('chart', [item['id'] for item in items], items=items)
693
+ # ⭐ WHEN EXACTLY ONE CHART DEPENDS ON THE TARGET, THE ROW ADDRESSES ONE THING, so it carries
694
+ # that address itself -- the single-address-on-the-dependent shape `dependents_report` already
695
+ # preserves. ⛔ With several it carries none: a row-level link would have to pick one chart and
696
+ # would silently mean the others, which is the naming-by-display defect W60-T12 closed.
697
+ if row and len(items) == 1:
698
+ row['href'] = items[0]['href']
699
+ row['reason'] = items[0]['reason']
700
+ return row
701
 
702
 
703
  register('view', view_dependents)
platform/core/measure_resolve.py CHANGED
@@ -152,8 +152,8 @@ def column_values(fields, team_id, allowed_pids, today, stamp, memo, on_error=No
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:
@@ -197,6 +197,8 @@ def column_values(fields, team_id, allowed_pids, today, stamp, memo, on_error=No
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:
 
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 publishes a per-field marker and no values, on memo hits too.
156
+ 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:
 
197
  if related is not None:
198
  out.refusals.extend(dict(marker, field=fkey)
199
  for marker in getattr(vals, 'refusals', ()))
200
+ if getattr(vals, 'refusals', ()):
201
+ continue
202
  for pid, v in vals.items():
203
  out.setdefault(pid, {})[fkey] = v
204
  if len(memo) > 100:
platform/core/perm_scope.py CHANGED
@@ -40,6 +40,7 @@ twice in this codebase (`modules: []` and `bus: [<unknown id>]` both read as UNR
40
  perms block; without this clause an explicit-marker scheme locks the owner out of their own
41
  product at exactly the moment the store is broken.
42
  """
 
43
  import re
44
 
45
  import core.perms as perms
@@ -1400,7 +1401,7 @@ class Unresolvable(RuntimeError):
1400
 
1401
 
1402
  #: Row readers DECLARED by the app layer, keyed by EXACT database key.
1403
- #: `reader(table_key, user, st) -> (fields, rows)`.
1404
  #:
1405
  #: ⛔ WHY A REGISTRY AND NOT AN IMPORT. `core` never imports up (`platform/ARCHITECTURE.md`), and
1406
  #: a registry TOPIC's rows are built by `modules/` + `aios_grid` behind an API-layer pool cache
@@ -1409,6 +1410,7 @@ class Unresolvable(RuntimeError):
1409
  #: `ROW_HOOKS`: *"`core` never imports up, so the app tells this layer rather than being
1410
  #: interrogated by it."*
1411
  _ROW_SOURCES = {}
 
1412
 
1413
  #: THE reader for a read-through `ut_*` grid — one reader, because there is one mirror.
1414
  #: `reader(table_key, field_keys, st) -> rows`.
@@ -1423,10 +1425,18 @@ def register_rows(reader, *table_keys):
1423
  says so ([[reachable-is-not-the-same-as-built]]). Routing the read door through the write
1424
  door's return keeps one construction site of the set instead of two.
1425
  """
 
 
 
 
 
 
 
1426
  for key in table_keys:
1427
  k = str(key or '').strip()
1428
  if k:
1429
  _ROW_SOURCES[k] = reader
 
1430
  return frozenset(_ROW_SOURCES)
1431
 
1432
 
@@ -1568,8 +1578,8 @@ def scoped_fields(user, table_key, st=None):
1568
  second path to the store (W1). So both come from here, off one wall.
1569
 
1570
  ⚠ On a `ut_*` database this reads the DEFINITION only — the projection, no rows (D-213). On a
1571
- registry topic it goes through the registered reader, which builds that topic's pool; the
1572
- pool is cached per scope on the tenant runtime, so it is a cache hit next to `scoped_table`.
1573
  """
1574
  fields, _rows = _scoped(user, table_key, st=st, ctx=None, want_rows=False)
1575
  return fields
@@ -1613,7 +1623,10 @@ def _read(table_key, user, st, want_rows=True):
1613
  """`(fields, rows)` BEFORE the wall — the app layer's reader, or core's own for a `ut_*`."""
1614
  reader = _ROW_SOURCES.get(table_key)
1615
  if reader is not None:
1616
- fields, rows = reader(table_key, user, st)
 
 
 
1617
  return list(fields or ()), list(rows or ())
1618
  ut = _ut()
1619
  if not table_key.startswith(ut.KEY_PREFIX):
 
40
  perms block; without this clause an explicit-marker scheme locks the owner out of their own
41
  product at exactly the moment the store is broken.
42
  """
43
+ import inspect
44
  import re
45
 
46
  import core.perms as perms
 
1401
 
1402
 
1403
  #: Row readers DECLARED by the app layer, keyed by EXACT database key.
1404
+ #: `reader(table_key, user, st[, want_rows=True]) -> (fields, rows)`.
1405
  #:
1406
  #: ⛔ WHY A REGISTRY AND NOT AN IMPORT. `core` never imports up (`platform/ARCHITECTURE.md`), and
1407
  #: a registry TOPIC's rows are built by `modules/` + `aios_grid` behind an API-layer pool cache
 
1410
  #: `ROW_HOOKS`: *"`core` never imports up, so the app tells this layer rather than being
1411
  #: interrogated by it."*
1412
  _ROW_SOURCES = {}
1413
+ _ROW_SOURCE_WANT_ROWS = {}
1414
 
1415
  #: THE reader for a read-through `ut_*` grid — one reader, because there is one mirror.
1416
  #: `reader(table_key, field_keys, st) -> rows`.
 
1425
  says so ([[reachable-is-not-the-same-as-built]]). Routing the read door through the write
1426
  door's return keeps one construction site of the set instead of two.
1427
  """
1428
+ # Decide the calling convention once. Never retry a reader's own TypeError as an old
1429
+ # signature: doing so can silently replace a failed read with a different answer.
1430
+ parameters = inspect.signature(reader).parameters
1431
+ accepts_want_rows = any(p.kind == inspect.Parameter.VAR_KEYWORD
1432
+ for p in parameters.values()) or (
1433
+ 'want_rows' in parameters and parameters['want_rows'].kind in (
1434
+ inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY))
1435
  for key in table_keys:
1436
  k = str(key or '').strip()
1437
  if k:
1438
  _ROW_SOURCES[k] = reader
1439
+ _ROW_SOURCE_WANT_ROWS[k] = accepts_want_rows
1440
  return frozenset(_ROW_SOURCES)
1441
 
1442
 
 
1578
  second path to the store (W1). So both come from here, off one wall.
1579
 
1580
  ⚠ On a `ut_*` database this reads the DEFINITION only — the projection, no rows (D-213). On a
1581
+ registry topic it asks the registered reader for fields only when supported. Legacy
1582
+ three-argument readers retain their existing call contract.
1583
  """
1584
  fields, _rows = _scoped(user, table_key, st=st, ctx=None, want_rows=False)
1585
  return fields
 
1623
  """`(fields, rows)` BEFORE the wall — the app layer's reader, or core's own for a `ut_*`."""
1624
  reader = _ROW_SOURCES.get(table_key)
1625
  if reader is not None:
1626
+ if _ROW_SOURCE_WANT_ROWS.get(table_key, False):
1627
+ fields, rows = reader(table_key, user, st, want_rows=want_rows)
1628
+ else:
1629
+ fields, rows = reader(table_key, user, st)
1630
  return list(fields or ()), list(rows or ())
1631
  ut = _ut()
1632
  if not table_key.startswith(ut.KEY_PREFIX):
platform/core/relations.py CHANGED
@@ -745,6 +745,10 @@ def measure_pin_key(related):
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
 
@@ -754,11 +758,17 @@ class MeasurePin:
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']
@@ -1126,6 +1136,15 @@ def one_hop(table, fields=None, defs=None, include_retired=False):
1126
  out = []
1127
  for entry in base:
1128
  entry = dict(entry)
 
 
 
 
 
 
 
 
 
1129
  got = cards.get(entry['key']) or bridge_cards.get(entry['key'])
1130
  entry['cardinality'] = str(got or 'many_to_many')
1131
  out.append(entry)
 
745
  if related is None:
746
  return None
747
  ctx = _MEASURE_PIN_CONTEXT.get() or {}
748
+ if isinstance(related, MeasurePin):
749
+ # Compiled pins contain the server's walled membership, not just a wire path.
750
+ related = dict(path=related.path, rows=related.rows, bindings=related.bindings,
751
+ refusal=related.refusal, required=related.required)
752
  return json.dumps(related, sort_keys=True, separators=(',', ':')), ctx.get('cache_key')
753
 
754
 
 
758
  rows: dict
759
  bindings: dict
760
  refusal: dict = None
761
+ required: tuple = ()
762
 
763
  def predicate(self, store):
764
  """AND every declared, traversed member set into this metric's raw rows."""
765
  if self.refusal is not None:
766
  return None, []
767
+ bound = {b['table'] for b in self.bindings.get(store['table'], ())}
768
+ if set(self.required) - bound:
769
+ raise PinRefusal('relation_binding_unavailable',
770
+ 'This metric cannot be restricted to every database in this record path. '
771
+ 'Ask an administrator to add the missing metric binding.', self.path)
772
  parts, params = [], []
773
  for binding in self.bindings.get(store['table'], ()):
774
  table, column = binding['table'], binding['column']
 
1136
  out = []
1137
  for entry in base:
1138
  entry = dict(entry)
1139
+ # Keep related()'s legacy shape. Depth-aware pins also need the declared manual,
1140
+ # inverse or through configuration, which remains schema-only cache input.
1141
+ via = entry.get('via') or {}
1142
+ owner_fields = (((defs or {}).get(entry['target']) or {}).get('fields') or []
1143
+ if via.get('direction') == 'reverse' else fields or [])
1144
+ declared = next((field for field in owner_fields
1145
+ if field.get('key') == via.get('field')), None)
1146
+ if declared and _link_bag(declared):
1147
+ entry['link'] = dict(_link_bag(declared))
1148
  got = cards.get(entry['key']) or bridge_cards.get(entry['key'])
1149
  entry['cardinality'] = str(got or 'many_to_many')
1150
  out.append(entry)
platform/core/sheet_templates.py CHANGED
@@ -43,6 +43,118 @@ def _scope(*conditions):
43
  for field, op, value in conditions]}
44
 
45
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
46
  # C4 has exactly two additions: answers supplies the gallery's short question
47
  # summary; semantic_fields lets bindings name concepts such as "revenue" rather
48
  # than tenant column ids. Tenants can map that concept to different source keys.
@@ -50,6 +162,7 @@ def _scope(*conditions):
50
  # an applied workbook never silently moves a labelled period to another month.
51
  _AS_OF = date.today()
52
  TEMPLATES = [
 
53
  {
54
  "key": "odoo_monthly_sales", "title": "Monthly sales", "source": "odoo",
55
  "database_hint": "ut_odoo_orders",
@@ -205,8 +318,15 @@ def build_cells(template, resolved, database_key):
205
 
206
  for entry in template["bindings"]:
207
  cells, addr = target(entry)
 
 
 
 
 
 
 
208
  binding = {"database": database_key,
209
- "aggregate": {"fn": entry["fn"], "field": resolved[entry["field"]]},
210
  "scope": _resolved_scope(entry.get("scope", {"filter": []}), resolved)}
211
  if "period" in entry:
212
  binding["period"] = deepcopy(entry["period"])
@@ -224,6 +344,40 @@ def build_cells(template, resolved, database_key):
224
  return tabs
225
 
226
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
227
  def apply_template(st, key, database_key, *, name="", created_by=""):
228
  descriptor = template(key)
229
  if descriptor is None:
@@ -233,11 +387,19 @@ def apply_template(st, key, database_key, *, name="", created_by=""):
233
  raise TemplateRefusal("unknown_database", detail="That database does not exist.")
234
  if source_of_database(database_key) != descriptor["source"]:
235
  raise TemplateRefusal("template_source_mismatch", detail="That database uses a different connector from this template.")
236
- resolved = resolve_fields(descriptor, (field["key"] for field in definition.get("fields", [])))
 
 
 
 
237
  prepared = build_cells(descriptor, resolved, database_key)
238
  # Validate tab names, extents and every cell before the first store write.
239
  checked = sheets.migrate_workbook({"sheets": [
240
  {"name": tab_name, "cells": cells} for _, tab_name, cells in prepared]})
 
 
 
 
241
  book = sheets.create_workbook(st, name=name or descriptor["title"], created_by=created_by)
242
  try:
243
  tabs = [{**tab, "cells": {}} for tab in checked["sheets"]]
 
43
  for field, op, value in conditions]}
44
 
45
 
46
+ def _sales_summary():
47
+ """W60-T08: Field aggregates need date predicates, not a Metric-only period.
48
+
49
+ The existing T06 valueRef reader resolves these formula dates and dropdowns;
50
+ T40 resolves the shared customer field. No raw records enter the workbook.
51
+ """
52
+ tabs, bindings, formats = [], [], []
53
+ for index, name in enumerate(("Summary (All)", "Summary (SR)")):
54
+ cells = {
55
+ "A1": _literal("Daily sales performance"),
56
+ "A2": _literal("Ending date"), "B2": _literal(date.today().isoformat()),
57
+ "A3": _literal("Business unit"),
58
+ "B3": {**_literal("Royal"), "validation": {"list": ["Fisch", "Royal"]}},
59
+ "A4": _literal("Assigned agent" if index else "Scope"),
60
+ "B4": ({**_literal("Choose an assigned agent"),
61
+ "validation": {"list": ["Choose an assigned agent"]}} if index else
62
+ _literal("Confirmed wholesale orders, untaxed, by order date")),
63
+ "A6": _literal("Week starting"), "A7": _literal("Before"),
64
+ "A8": _literal("Sales, fully invoiced"), "A9": _literal("Confirmed sales orders"),
65
+ "A10": _literal("Order count"), "A11": _literal("Average order value"),
66
+ "A14": _literal("Year to date"), "B14": _literal("Current year"),
67
+ "C14": _literal("Previous year"),
68
+ "A15": _literal("From"), "A16": _literal("Before"),
69
+ "B15": _formula("=DATE(YEAR(B2),1,1)"),
70
+ "C15": _formula("=DATE(YEAR(B2)-1,1,1)"),
71
+ "B16": _formula('=DATEADD(B2,1,"days")'),
72
+ "C16": _formula('=DATEADD(EDATE(B2,-12),1,"days")'),
73
+ "A17": _literal("Sales, fully invoiced"), "A18": _literal("Confirmed sales orders"),
74
+ "A19": _literal("Order count"), "A20": _literal("Average order value"),
75
+ "A23": _literal("Sales basis"),
76
+ "B23": _literal("Fully invoiced means invoice_status = invoiced, by order date. "
77
+ "Partial invoices and invoice-date totals are not included."),
78
+ "A24": _literal("Workbook difference"),
79
+ "B24": _literal("Uses confirmed orders and order date. The Excel workbook uses "
80
+ "creation dates and all states, so its totals differ by design."),
81
+ "A25": _literal("Assigned agent setup"),
82
+ "B25": _literal("Create Assigned agent on Customers using the column menu, add "
83
+ "agent choices, then share the field. It starts empty; no Odoo "
84
+ "salesperson or commission-agent values are copied."),
85
+ "A27": _literal("Workbook exclusions"),
86
+ "B27": _literal("HubSpot activities and companies need a connector. Delivery time "
87
+ "needs a validated delivery-completion measure. Raw tabs, Backend, "
88
+ "Mastersheet and the other customer worklists are outside this summary template."),
89
+ "A28": _literal("Import limits"),
90
+ "B28": _literal("The source is a 39 MB .xlsm; import accepts .xlsx up to 25 MB. "
91
+ "Use this Cell database summary or export smaller .xlsx reports. "
92
+ "Excel macros and print automation are not imported."),
93
+ "A29": _literal("Formula limits"),
94
+ "B29": _literal("Ranges above 5,000 cells and tabs above 100,000 cells are refused. "
95
+ "Eight source tabs exceed the tab cap. Use Cell database aggregates "
96
+ "instead of raw dumps and whole-column formulas."),
97
+ "A30": _literal("Long formulas"),
98
+ "B30": _literal("26,934 source Mastersheet formulas exceed 500 characters. "
99
+ "Move those calculations to database fields or split them into smaller formulas."),
100
+ "A31": _literal("Workbook size"),
101
+ "B31": _literal("Saved workbooks are limited to 64 MiB. The expanded raw workbook "
102
+ "has not been measured; keep data in databases and aggregate it into cells."),
103
+ }
104
+ if index:
105
+ cells["B2"] = _formula("='Summary (All)'!B2")
106
+ cells["B3"] = _formula("='Summary (All)'!B3")
107
+ for offset, col in enumerate("BCDEFGHIJKLMN"):
108
+ cells[f"{col}6"] = _formula(
109
+ f'=DATEADD($B$2,1-WEEKDAY($B$2,2)-{(12-offset)*7},"days")')
110
+ cells[f"{col}7"] = _formula(f'=DATEADD({col}6,7,"days")')
111
+
112
+ for col, start, end, first in [*( (c, f"{c}6", f"{c}7", 8) for c in "BCDEFGHIJKLMN"),
113
+ ("B", "B15", "B16", 17), ("C", "C15", "C16", 17)]:
114
+ filters = [
115
+ {"colId": "order_date", "op": "gte", "valueRef": {"ref": start}},
116
+ {"colId": "order_date", "op": "lt", "valueRef": {"ref": end}},
117
+ {"colId": "business_unit", "op": "eq", "valueRef": {"ref": "'Summary (All)'!$B$3"}},
118
+ {"colId": "wholesale", "op": "eq", "value": "1"},
119
+ {"colId": "state", "op": "isAnyOf", "values": ["sale", "done"]},
120
+ ]
121
+ if index:
122
+ filters.append({"colId": "assigned_agent", "op": "eq",
123
+ "valueRef": {"ref": "$B$4"}})
124
+ for row, fn, field in ((first, "sum", "revenue"),
125
+ (first+1, "sum", "revenue"), (first+2, "count", "order")):
126
+ nodes = deepcopy(filters)
127
+ if row == first:
128
+ nodes.append({"colId": "invoice_status", "op": "eq", "value": "invoiced"})
129
+ bindings.append({"sheet": index, "addr": f"{col}{row}", "field": field,
130
+ "fn": fn, "scope": {"filter": nodes}})
131
+ cells[f"{col}{first+3}"] = _formula(
132
+ f'=IF({col}{first+2}=0,0,{col}{first+1}/{col}{first+2})')
133
+ formats.extend({"sheet": index, "addr": f"{col}{row}", "kind": kind}
134
+ for row, kind in ((first, "currency"), (first+1, "currency"),
135
+ (first+2, "number"), (first+3, "currency")))
136
+ formats.extend({"sheet": index, "addr": addr, "kind": "date"}
137
+ for addr in ["B2", "B15", "C15", "B16", "C16",
138
+ *(f"{col}{row}" for col in "BCDEFGHIJKLMN" for row in (6, 7))])
139
+ for addr, cell in cells.items():
140
+ if addr.startswith("A") or addr in ("B14", "C14"):
141
+ cell["style"] = {"bold": True}
142
+ tabs.append({"name": name, "cells": cells})
143
+ return {
144
+ "key": "odoo_daily_sales_performance", "title": "Daily sales performance",
145
+ "source": "odoo", "database_hint": "ut_odoo_orders",
146
+ "answers": "How do thirteen weeks and year-to-date sales compare by business unit "
147
+ "and the customer's shared Assigned agent? Uses confirmed, untaxed orders "
148
+ "by order date, so totals differ from the Excel workbook.",
149
+ "semantic_fields": {"order_date": ("order_date",), "revenue": ("amount_untaxed",),
150
+ "order": ("odoo_id",), "business_unit": ("team",),
151
+ "wholesale": ("wholesale_scope",), "state": ("state",),
152
+ "invoice_status": ("invoice_status",),
153
+ "assigned_agent": ("linked:bridge_customer_orders:custom_assigned_agent",)},
154
+ "sheets": tabs, "bindings": bindings, "formats": formats,
155
+ }
156
+
157
+
158
  # C4 has exactly two additions: answers supplies the gallery's short question
159
  # summary; semantic_fields lets bindings name concepts such as "revenue" rather
160
  # than tenant column ids. Tenants can map that concept to different source keys.
 
162
  # an applied workbook never silently moves a labelled period to another month.
163
  _AS_OF = date.today()
164
  TEMPLATES = [
165
+ _sales_summary(),
166
  {
167
  "key": "odoo_monthly_sales", "title": "Monthly sales", "source": "odoo",
168
  "database_hint": "ut_odoo_orders",
 
318
 
319
  for entry in template["bindings"]:
320
  cells, addr = target(entry)
321
+ if set(entry) - {"sheet", "addr", "fn", "field", "metric_key", "scope", "period"}:
322
+ raise TemplateRefusal("template_invalid", detail="The template binding has an unknown setting.")
323
+ aggregate = ({"metric_key": entry["metric_key"]} if "metric_key" in entry else
324
+ {"fn": entry["fn"], "field": resolved[entry["field"]]})
325
+ if "metric_key" in entry and (not entry["metric_key"] or "field" in entry or "fn" in entry
326
+ or not entry.get("period")):
327
+ raise TemplateRefusal("template_invalid", detail="A template metric needs a period and no field aggregate.")
328
  binding = {"database": database_key,
329
+ "aggregate": aggregate,
330
  "scope": _resolved_scope(entry.get("scope", {"filter": []}), resolved)}
331
  if "period" in entry:
332
  binding["period"] = deepcopy(entry["period"])
 
344
  return tabs
345
 
346
 
347
+ def _sales_summary_inputs(st, descriptor, created_by):
348
+ """Read existing shared field metadata only; creation and promotion stay in the column menu."""
349
+ from core import perm_scope, shared_overlay, users, view_templates
350
+ user = {**(st.get("users").get(created_by) or {}), "username": created_by}
351
+ if not perm_scope.may_access(user, "customer_data"):
352
+ raise TemplateRefusal("template_fields_missing", missing=("a readable shared Assigned agent field",))
353
+ shared = shared_overlay.fields(view_templates.workspace_key("customer_data"), st=st)
354
+ visible = perm_scope.visible_fields(list(shared.values()), user, "customer_data", st=st)
355
+ candidates = [f for f in visible if f.get("label", "").casefold() in
356
+ ("assigned agent", "w60-t08 assigned agent") and f.get("type") in ("text", "select", "user")]
357
+ if len(candidates) != 1:
358
+ raise TemplateRefusal("template_fields_missing", missing=(
359
+ "one shared Assigned agent field on Customers (create it with the column menu and share it)",))
360
+ field = candidates[0]
361
+ descriptor = deepcopy(descriptor)
362
+ key = "linked:bridge_customer_orders:" + field["key"]
363
+ descriptor["semantic_fields"]["assigned_agent"] = (key,)
364
+ # BU choice metadata follows the same permission helper as the rest of the product.
365
+ bus = [label for label in users.allowed_bus_labels(user) if label != "All"]
366
+ all_cells, sr_cells = (tab["cells"] for tab in descriptor["sheets"])
367
+ all_cells["B2"] = _literal(date.today().isoformat())
368
+ all_cells["B3"] = {**_literal(bus[0]), "validation": {"list": bus}}
369
+ choices = [str(option.get("value") or option.get("label") or "") if isinstance(option, dict)
370
+ else str(option) for option in field.get("options", [])]
371
+ choices = list(dict.fromkeys(choice for choice in choices if choice.strip()))
372
+ if choices:
373
+ sr_cells["B4"] = {**_literal(choices[0]), "validation": {"list": choices[:200]}}
374
+ if len(choices) > 200:
375
+ sr_cells["A26"] = _literal("Agent choices")
376
+ sr_cells["B26"] = _literal(f"Showing 200 of {len(choices)} choices. The dropdown holds at most "
377
+ "200; type another agent value or reduce the field's choices.")
378
+ return descriptor, key
379
+
380
+
381
  def apply_template(st, key, database_key, *, name="", created_by=""):
382
  descriptor = template(key)
383
  if descriptor is None:
 
387
  raise TemplateRefusal("unknown_database", detail="That database does not exist.")
388
  if source_of_database(database_key) != descriptor["source"]:
389
  raise TemplateRefusal("template_source_mismatch", detail="That database uses a different connector from this template.")
390
+ field_keys = [field["key"] for field in definition.get("fields", [])]
391
+ if key == "odoo_daily_sales_performance":
392
+ descriptor, linked_key = _sales_summary_inputs(st, descriptor, created_by)
393
+ field_keys.append(linked_key)
394
+ resolved = resolve_fields(descriptor, field_keys)
395
  prepared = build_cells(descriptor, resolved, database_key)
396
  # Validate tab names, extents and every cell before the first store write.
397
  checked = sheets.migrate_workbook({"sheets": [
398
  {"name": tab_name, "cells": cells} for _, tab_name, cells in prepared]})
399
+ if key == "odoo_daily_sales_performance":
400
+ for tab in checked["sheets"]:
401
+ tab["colWidths"] = {"A": 230, **{col: 125 for col in "BCDEFGHIJKLMN"}}
402
+ tab["freeze"] = {"rows": 7, "cols": 1}
403
  book = sheets.create_workbook(st, name=name or descriptor["title"], created_by=created_by)
404
  try:
405
  tabs = [{**tab, "cells": {}} for tab in checked["sheets"]]
platform/core/sheets.py CHANGED
@@ -81,6 +81,7 @@ AMAZON_DATA_ORIGIN_NAME = "Amazon Services API"
81
  SHEET_SCHEMA_VERSION = 1
82
  DOCUMENT_MAX_COLS = 16384
83
  DOCUMENT_MAX_ROWS = 1048576
 
84
 
85
  #: ⛔ THE FROZEN VOCABULARY (contract C1, amended by C2). `verify_api.py` and `verify_sheet.py`
86
  #: assert `web/src/sheet/types.ts` carries exactly these, name for name.
@@ -230,7 +231,7 @@ SHEET_CHART_KINDS = ("bar", "line", "area", "donut", "column", "pie", "scatter",
230
  #: The order is the order a cleaned tab reads in: identity, then A2's geometry, then C2's strata.
231
  SHEET_TAB_KEYS = ("id", "name", "cols", "rows", "cells", "usedExtent", "colWidths", "freeze",
232
  "rules", "hiddenRows", "hiddenCols", "charts", "imported", "rowHeight", "rowHeights",
233
- "visibility", "print", "excel")
234
 
235
  #: The keys above that `_clean_sheet` writes UNCONDITIONALLY. Every other member of
236
  #: `SHEET_TAB_KEYS` is written only when it holds something, for `_clean_style`'s reason: a tab
@@ -1197,6 +1198,38 @@ def _clean_print(raw):
1197
  return out
1198
 
1199
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1200
  def _clean_imported(raw):
1201
  """C4's import record: when, from what, and WHAT DID NOT SURVIVE.
1202
 
@@ -1269,6 +1302,7 @@ def _clean_sheet(raw, index=0, *, lossless=False):
1269
  "rowHeight": _clean_base_row_height(raw.get("rowHeight")),
1270
  "rowHeights": _clean_row_heights(raw.get("rowHeights")),
1271
  "visibility": visibility,
 
1272
  "print": _clean_print(raw.get("print")),
1273
  "excel": excel,
1274
  }
@@ -1287,7 +1321,7 @@ def _clean_sheet(raw, index=0, *, lossless=False):
1287
  if value:
1288
  sheet[key] = value
1289
  extensions = {key: copy.deepcopy(value) for key, value in raw.items()
1290
- if key not in set(optional) | set(SHEET_TAB_ALWAYS_KEYS) | {"cellCount"}}
1291
  sheet.update(_json_safe(extensions, "sheet extensions"))
1292
  if lossless:
1293
  sheet["cols"] = max(cols, (sheet.get("freeze") or {}).get("cols", 0))
@@ -1346,10 +1380,11 @@ def new_workbook(name="", created_by="", workbook_id=""):
1346
  "name": _text(name, _MAX_NAME) or "Untitled workbook",
1347
  "sheets": [{"id": uuid.uuid4().hex[:12], "name": "Sheet1",
1348
  "cols": DEFAULT_SHEET_COLS, "rows": DEFAULT_SHEET_ROWS, "cells": {},
1349
- "usedExtent": None}],
1350
  "rev": 1,
1351
  "refreshed_at": None,
1352
  "created_by": _text(created_by, _MAX_ID),
 
1353
  "created_at": stamp,
1354
  "updated_at": stamp,
1355
  }
@@ -1429,6 +1464,30 @@ def create_workbook(st, name="", created_by=""):
1429
  return book
1430
 
1431
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1432
  def get_workbook(st, workbook_id):
1433
  """One workbook, or a named refusal when the document is not there."""
1434
  wid = _slug_id(workbook_id)
@@ -1436,13 +1495,13 @@ def get_workbook(st, workbook_id):
1436
  if not doc or not doc.get("id"):
1437
  raise SheetRefusal("workbook_missing",
1438
  "That workbook no longer exists.")
1439
- return migrate_workbook(doc)
1440
 
1441
 
1442
- def put_workbook(st, workbook_id, raw, expect_rev=None):
1443
  """Replace a workbook's name and sheets, bumping `rev`.
1444
 
1445
- ⛔ `id`, `created_by` and `created_at` are PRIOR-WINS: a client may not reassign a workbook by
1446
  sending a different id, and a client that never read the document cannot blank its provenance.
1447
 
1448
  ⚠ `expect_rev` makes the write CONDITIONAL, and when it is not passed explicitly the `rev`
@@ -1472,9 +1531,10 @@ def put_workbook(st, workbook_id, raw, expect_rev=None):
1472
  if prior is None:
1473
  raise SheetRefusal("workbook_missing", "That workbook no longer exists.")
1474
  if expect_rev is not None and int(prior.get("rev") or 0) != int(expect_rev):
1475
- raise SheetRefusal(
1476
  "workbook_revision_stale",
1477
- "That workbook changed somewhere else, so this save was not applied.")
 
1478
  book = migrate_workbook(prior)
1479
  # Immutable ownership and server read projections cannot be reassigned by a PUT.
1480
  # ``dataOrigins`` is SERVER-MAINTAINED (DPP 1.8) and therefore protected: a PUT body may
@@ -1483,16 +1543,24 @@ def put_workbook(st, workbook_id, raw, expect_rev=None):
1483
  # ``[]`` erases a genuine Amazon origin, and sending a well-formed tag plants one on an
1484
  # unrelated workbook. The origin list is rebuilt from the PRIOR document plus the cleaned
1485
  # cells by ``_merge_data_origins`` immediately below.
1486
- protected = {"id", "created_by", "created_at", "updated_at", "rev", "refreshed_at",
1487
  "sheets", "name", "refreshedFor", "shares", "role", "permissions",
1488
  "dataOrigins"}
1489
  book.update({key: value for key, value in incoming.items() if key not in protected})
1490
  book["name"] = name or _text(prior.get("name"), _MAX_NAME) or "Untitled workbook"
1491
- book["sheets"] = sheets
 
1492
  # DPP 1.8: merge from the PRIOR document and the cleaned cells. ``raw.dataOrigins`` is
1493
  # ignored, so a client cannot erase or replace the server-maintained attribution list.
1494
  _merge_data_origins(book, sheets=sheets)
1495
  book["rev"] = int(prior.get("rev") or 0) + 1
 
 
 
 
 
 
 
1496
  if refreshed_at is not None:
1497
  book["refreshed_at"] = _text(refreshed_at, 120) or None
1498
  book["updated_at"] = _now()
@@ -1574,7 +1642,7 @@ def workbook_meta(book):
1574
  return meta
1575
 
1576
 
1577
- def patch_cells(st, workbook_id, tab_ref, raw_cells, expect_rev=None):
1578
  """Merge a RANGE of cells into ONE tab. Returns `{rev, tab, refused}` (contract C3).
1579
 
1580
  ⭐⭐ ONE BAD CELL DOES NOT THROW THE COMMIT AWAY. Every address is cleaned on its own and a
@@ -1640,13 +1708,7 @@ def patch_cells(st, workbook_id, tab_ref, raw_cells, expect_rev=None):
1640
  if prior is None:
1641
  raise SheetRefusal("workbook_missing", "That workbook no longer exists.")
1642
  current = int(prior.get("rev") or 0)
1643
- if expect_rev is not None and current != int(expect_rev):
1644
- raise SheetStaleRefusal(
1645
- "sheet_revision_stale",
1646
- "This sheet changed somewhere else while you had it open, so this save was not "
1647
- "applied. Reload the tab and try again.",
1648
- rev_current=current)
1649
- book = migrate_workbook(prior)
1650
  tabs = book.get("sheets") or []
1651
  at = _tab_index(tabs, tab_ref)
1652
  if at is None:
@@ -1654,6 +1716,21 @@ def patch_cells(st, workbook_id, tab_ref, raw_cells, expect_rev=None):
1654
  "tab_missing",
1655
  "Tab " + (str(tab_ref) or "(unnamed)") + " is not in this workbook.")
1656
  tab = tabs[at]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1657
  cells = dict(tab.get("cells") or {})
1658
  for key in deleted:
1659
  cells.pop(key, None)
@@ -1670,6 +1747,7 @@ def patch_cells(st, workbook_id, tab_ref, raw_cells, expect_rev=None):
1670
  book["sheets"] = tabs
1671
  _merge_data_origins(book, sheets=tabs)
1672
  book["rev"] = current + 1
 
1673
  book["updated_at"] = _now()
1674
  _json_safe(book, "workbook")
1675
  out["rev"] = book["rev"]
@@ -1677,6 +1755,7 @@ def patch_cells(st, workbook_id, tab_ref, raw_cells, expect_rev=None):
1677
  out["cells"] = len(cells)
1678
  out["schemaVersion"] = SHEET_SCHEMA_VERSION
1679
  out["usedExtent"] = tab["usedExtent"]
 
1680
  # Server-cleaned keys only. The route consumes this delta for calculation context.
1681
  out["accepted"] = list(dict.fromkeys([*merged, *deleted]))
1682
  saved.update(book)
@@ -1883,6 +1962,19 @@ def _index_upsert(st, book):
1883
  #: registry's words, so a second spelling cannot be introduced here by accident.
1884
 
1885
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1886
  def workbook_shares(st, workbook_id):
1887
  """C5's `shares` list for ONE workbook, computed from `core.shares` and never stored.
1888
 
@@ -1904,11 +1996,31 @@ def workbook_shares(st, workbook_id):
1904
  return [{"who": e["user"], "role": e["role"]} for e in (rec.get("entries") or [])]
1905
 
1906
 
1907
- def project_shares(st, rows):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1908
  """Join `shares` onto a list of index rows. Returns NEW rows; the stored ones are untouched.
1909
 
1910
- ⚠ Called by `read_index`, `save_folders` and `routes_sheet.list_sheets` — the three doors a
1911
- client reads the rail through. `list_workbooks` itself stays a bare pointer list on purpose:
 
1912
  `iter_workbooks` walks it to answer W49-T10's dependents question, and paying a grant-registry
1913
  read per workbook there would put a permission lookup inside a scan that asks no permission
1914
  question at all.
@@ -1918,6 +2030,15 @@ def project_shares(st, rows):
1918
  if not isinstance(row, dict) or not row.get("id"):
1919
  continue
1920
  joined = dict(row)
 
 
 
 
 
 
 
 
 
1921
  joined["shares"] = workbook_shares(st, row["id"])
1922
  out.append(joined)
1923
  return out
@@ -2374,7 +2495,31 @@ def _index_rev(doc):
2374
  return 0
2375
 
2376
 
2377
- def read_index(st, viewer=None):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2378
  """The whole rail document: `{workbooks, folders, itemFolders, starred, rev}`, plus
2379
  `sharedWithMe` when a `viewer` is named.
2380
 
@@ -2399,6 +2544,7 @@ def read_index(st, viewer=None):
2399
  doc = _read(st, INDEX_KEY)
2400
  rows = [dict(r) for r in (doc.get("workbooks") or [])
2401
  if isinstance(r, dict) and r.get("id")]
 
2402
  ids = {r["id"] for r in rows}
2403
  placements = doc.get("itemFolders")
2404
  try:
@@ -2407,11 +2553,14 @@ def read_index(st, viewer=None):
2407
  flat = [dict(f, parent=None) for f in (doc.get("folders") or [])
2408
  if isinstance(f, dict) and f.get("id")]
2409
  folders, placed, _repairs = validate_folder_tree(flat, placements)
 
 
 
2410
  out = {
2411
- "workbooks": project_shares(st, rows),
2412
  "folders": folders,
2413
  "itemFolders": {k: v for k, v in placed.items() if k in ids},
2414
- "starred": _clean_starred(doc.get("starred"), ids, []),
2415
  "rev": _index_rev(doc),
2416
  }
2417
  if viewer:
 
81
  SHEET_SCHEMA_VERSION = 1
82
  DOCUMENT_MAX_COLS = 16384
83
  DOCUMENT_MAX_ROWS = 1048576
84
+ WRITE_LOG_REVS = 200
85
 
86
  #: ⛔ THE FROZEN VOCABULARY (contract C1, amended by C2). `verify_api.py` and `verify_sheet.py`
87
  #: assert `web/src/sheet/types.ts` carries exactly these, name for name.
 
231
  #: The order is the order a cleaned tab reads in: identity, then A2's geometry, then C2's strata.
232
  SHEET_TAB_KEYS = ("id", "name", "cols", "rows", "cells", "usedExtent", "colWidths", "freeze",
233
  "rules", "hiddenRows", "hiddenCols", "charts", "imported", "rowHeight", "rowHeights",
234
+ "visibility", "view", "print", "excel")
235
 
236
  #: The keys above that `_clean_sheet` writes UNCONDITIONALLY. Every other member of
237
  #: `SHEET_TAB_KEYS` is written only when it holds something, for `_clean_style`'s reason: a tab
 
1198
  return out
1199
 
1200
 
1201
+ #: Wave 60 base kit: `SheetTabView` in `sheet/types.ts`. Display settings, so a bad value is
1202
+ #: DROPPED rather than refused: a sheet must never fail to save over a zoom level.
1203
+ _VIEW_ZOOM_MIN, _VIEW_ZOOM_MAX = 10, 400
1204
+ _VIEW_PAGE_VIEWS = ("normal", "pageBreak", "pageLayout")
1205
+
1206
+
1207
+ def _clean_view(raw):
1208
+ """A tab's display settings: gridlines, headings, zoom, pageView and split, nothing else.
1209
+
1210
+ Booleans stay booleans, zoom clamps to 10..400 (a non-number is dropped), pageView keeps only
1211
+ the three words, split keeps non-negative integer rows and cols or is dropped. An empty
1212
+ result is None, so the tab stores no empty stratum.
1213
+ """
1214
+ if not isinstance(raw, dict):
1215
+ return None
1216
+ out = {}
1217
+ for key in ("gridlines", "headings"):
1218
+ if isinstance(raw.get(key), bool):
1219
+ out[key] = raw[key]
1220
+ zoom = raw.get("zoom")
1221
+ if not isinstance(zoom, bool) and isinstance(zoom, (int, float)) and math.isfinite(zoom):
1222
+ out["zoom"] = max(_VIEW_ZOOM_MIN, min(_VIEW_ZOOM_MAX, zoom))
1223
+ if raw.get("pageView") in _VIEW_PAGE_VIEWS:
1224
+ out["pageView"] = raw["pageView"]
1225
+ split = raw.get("split")
1226
+ if isinstance(split, dict):
1227
+ parts = [split.get("rows"), split.get("cols")]
1228
+ if all(isinstance(n, int) and not isinstance(n, bool) and n >= 0 for n in parts):
1229
+ out["split"] = {"rows": parts[0], "cols": parts[1]}
1230
+ return out or None
1231
+
1232
+
1233
  def _clean_imported(raw):
1234
  """C4's import record: when, from what, and WHAT DID NOT SURVIVE.
1235
 
 
1302
  "rowHeight": _clean_base_row_height(raw.get("rowHeight")),
1303
  "rowHeights": _clean_row_heights(raw.get("rowHeights")),
1304
  "visibility": visibility,
1305
+ "view": _clean_view(raw.get("view")),
1306
  "print": _clean_print(raw.get("print")),
1307
  "excel": excel,
1308
  }
 
1321
  if value:
1322
  sheet[key] = value
1323
  extensions = {key: copy.deepcopy(value) for key, value in raw.items()
1324
+ if key not in set(optional) | set(SHEET_TAB_ALWAYS_KEYS) | {"cellCount", "writes", "writesFrom"}}
1325
  sheet.update(_json_safe(extensions, "sheet extensions"))
1326
  if lossless:
1327
  sheet["cols"] = max(cols, (sheet.get("freeze") or {}).get("cols", 0))
 
1380
  "name": _text(name, _MAX_NAME) or "Untitled workbook",
1381
  "sheets": [{"id": uuid.uuid4().hex[:12], "name": "Sheet1",
1382
  "cols": DEFAULT_SHEET_COLS, "rows": DEFAULT_SHEET_ROWS, "cells": {},
1383
+ "usedExtent": None, "writesFrom": 0}],
1384
  "rev": 1,
1385
  "refreshed_at": None,
1386
  "created_by": _text(created_by, _MAX_ID),
1387
+ "access": "private",
1388
  "created_at": stamp,
1389
  "updated_at": stamp,
1390
  }
 
1464
  return book
1465
 
1466
 
1467
+ def _carry_write_logs(book, prior):
1468
+ """Only stored tabs may supply write history; client metadata never owns it."""
1469
+ held = {tab.get("id"): tab for tab in prior.get("sheets") or []}
1470
+ for tab in book.get("sheets") or []:
1471
+ source = held.get(tab.get("id")) or {}
1472
+ tab.pop("writes", None)
1473
+ tab["writesFrom"] = int(source.get("writesFrom") or 0)
1474
+ if "writes" in source:
1475
+ tab["writes"] = copy.deepcopy(source["writes"])
1476
+ return book
1477
+
1478
+
1479
+ def _append_write_log(tab, rev, addrs, *, actor="", actor_name=""):
1480
+ """Record accepted addresses and the oldest revision with complete retained history."""
1481
+ if not addrs:
1482
+ return
1483
+ writes = [*(tab.get("writes") or []), {"rev": rev, "by": actor,
1484
+ "byName": actor_name or actor, "addrs": list(addrs)}]
1485
+ dropped = writes[:-WRITE_LOG_REVS]
1486
+ if dropped:
1487
+ tab["writesFrom"] = max(int(tab.get("writesFrom") or 0), int(dropped[-1]["rev"]))
1488
+ tab["writes"] = writes[-WRITE_LOG_REVS:]
1489
+
1490
+
1491
  def get_workbook(st, workbook_id):
1492
  """One workbook, or a named refusal when the document is not there."""
1493
  wid = _slug_id(workbook_id)
 
1495
  if not doc or not doc.get("id"):
1496
  raise SheetRefusal("workbook_missing",
1497
  "That workbook no longer exists.")
1498
+ return _carry_write_logs(migrate_workbook(doc), doc)
1499
 
1500
 
1501
+ def put_workbook(st, workbook_id, raw, expect_rev=None, *, actor="", actor_name=""):
1502
  """Replace a workbook's name and sheets, bumping `rev`.
1503
 
1504
+ ⛔ `id`, `created_by`, `access` and `created_at` are PRIOR-WINS: a client may not reassign a workbook by
1505
  sending a different id, and a client that never read the document cannot blank its provenance.
1506
 
1507
  ⚠ `expect_rev` makes the write CONDITIONAL, and when it is not passed explicitly the `rev`
 
1531
  if prior is None:
1532
  raise SheetRefusal("workbook_missing", "That workbook no longer exists.")
1533
  if expect_rev is not None and int(prior.get("rev") or 0) != int(expect_rev):
1534
+ raise SheetStaleRefusal(
1535
  "workbook_revision_stale",
1536
+ "That workbook changed somewhere else, so this save was not applied.",
1537
+ rev_current=int(prior.get("rev") or 0))
1538
  book = migrate_workbook(prior)
1539
  # Immutable ownership and server read projections cannot be reassigned by a PUT.
1540
  # ``dataOrigins`` is SERVER-MAINTAINED (DPP 1.8) and therefore protected: a PUT body may
 
1543
  # ``[]`` erases a genuine Amazon origin, and sending a well-formed tag plants one on an
1544
  # unrelated workbook. The origin list is rebuilt from the PRIOR document plus the cleaned
1545
  # cells by ``_merge_data_origins`` immediately below.
1546
+ protected = {"id", "created_by", "access", "created_at", "updated_at", "rev", "refreshed_at",
1547
  "sheets", "name", "refreshedFor", "shares", "role", "permissions",
1548
  "dataOrigins"}
1549
  book.update({key: value for key, value in incoming.items() if key not in protected})
1550
  book["name"] = name or _text(prior.get("name"), _MAX_NAME) or "Untitled workbook"
1551
+ book["sheets"] = copy.deepcopy(sheets)
1552
+ _carry_write_logs(book, prior)
1553
  # DPP 1.8: merge from the PRIOR document and the cleaned cells. ``raw.dataOrigins`` is
1554
  # ignored, so a client cannot erase or replace the server-maintained attribution list.
1555
  _merge_data_origins(book, sheets=sheets)
1556
  book["rev"] = int(prior.get("rev") or 0) + 1
1557
+ prior_tabs = {tab.get("id"): tab for tab in prior.get("sheets") or []}
1558
+ for tab in book["sheets"]:
1559
+ before = (prior_tabs.get(tab.get("id")) or {}).get("cells") or {}
1560
+ after = tab.get("cells") or {}
1561
+ changed = sorted(addr for addr in before.keys() | after.keys()
1562
+ if before.get(addr) != after.get(addr))
1563
+ _append_write_log(tab, book["rev"], changed, actor=actor, actor_name=actor_name)
1564
  if refreshed_at is not None:
1565
  book["refreshed_at"] = _text(refreshed_at, 120) or None
1566
  book["updated_at"] = _now()
 
1642
  return meta
1643
 
1644
 
1645
+ def patch_cells(st, workbook_id, tab_ref, raw_cells, expect_rev=None, *, actor="", actor_name=""):
1646
  """Merge a RANGE of cells into ONE tab. Returns `{rev, tab, refused}` (contract C3).
1647
 
1648
  ⭐⭐ ONE BAD CELL DOES NOT THROW THE COMMIT AWAY. Every address is cleaned on its own and a
 
1708
  if prior is None:
1709
  raise SheetRefusal("workbook_missing", "That workbook no longer exists.")
1710
  current = int(prior.get("rev") or 0)
1711
+ book = _carry_write_logs(migrate_workbook(prior), prior)
 
 
 
 
 
 
1712
  tabs = book.get("sheets") or []
1713
  at = _tab_index(tabs, tab_ref)
1714
  if at is None:
 
1716
  "tab_missing",
1717
  "Tab " + (str(tab_ref) or "(unnamed)") + " is not in this workbook.")
1718
  tab = tabs[at]
1719
+ writes = tab.get("writes") or []
1720
+ touched = list(dict.fromkeys([*merged, *deleted]))
1721
+ conflicts = {}
1722
+ if touched and expect_rev is not None and int(expect_rev) < current:
1723
+ revision = int(expect_rev)
1724
+ if revision < int(tab.get("writesFrom") or 0):
1725
+ raise SheetStaleRefusal(
1726
+ "sheet_revision_stale",
1727
+ "This tab's retained change history was truncated after your revision. Reload the tab and try again.",
1728
+ rev_current=current)
1729
+ for write in writes:
1730
+ if int(write["rev"]) > revision and write["by"] != actor:
1731
+ for addr in sorted(set(touched).intersection(write["addrs"])):
1732
+ conflicts[addr] = {"addr": addr, "by": write["by"],
1733
+ "byName": write.get("byName") or write["by"]}
1734
  cells = dict(tab.get("cells") or {})
1735
  for key in deleted:
1736
  cells.pop(key, None)
 
1747
  book["sheets"] = tabs
1748
  _merge_data_origins(book, sheets=tabs)
1749
  book["rev"] = current + 1
1750
+ _append_write_log(tab, book["rev"], touched, actor=actor, actor_name=actor_name)
1751
  book["updated_at"] = _now()
1752
  _json_safe(book, "workbook")
1753
  out["rev"] = book["rev"]
 
1755
  out["cells"] = len(cells)
1756
  out["schemaVersion"] = SHEET_SCHEMA_VERSION
1757
  out["usedExtent"] = tab["usedExtent"]
1758
+ out["conflicts"] = list(conflicts.values())
1759
  # Server-cleaned keys only. The route consumes this delta for calculation context.
1760
  out["accepted"] = list(dict.fromkeys([*merged, *deleted]))
1761
  saved.update(book)
 
1962
  #: registry's words, so a second spelling cannot be introduced here by accident.
1963
 
1964
 
1965
+ def narrow_workbook(st, workbook_id):
1966
+ """Persist explicit sharing's one way visibility decision on the latest document."""
1967
+ wid = _slug_id(workbook_id)
1968
+
1969
+ def _apply(state):
1970
+ if not state.get("id"):
1971
+ raise SheetRefusal("workbook_missing", "That workbook no longer exists.")
1972
+ state.setdefault("access", "private")
1973
+ return state, None
1974
+
1975
+ _persist(st, workbook_key(wid), _apply)
1976
+
1977
+
1978
  def workbook_shares(st, workbook_id):
1979
  """C5's `shares` list for ONE workbook, computed from `core.shares` and never stored.
1980
 
 
1996
  return [{"who": e["user"], "role": e["role"]} for e in (rec.get("entries") or [])]
1997
 
1998
 
1999
+ def workbook_role(st, book, viewer, *, is_admin=False):
2000
+ """Document ownership plus the existing grant reader, shared with the route's role helper."""
2001
+ from core import shares
2002
+ me = str(viewer or "").strip().lower()
2003
+ if me and str(book.get("created_by") or "").strip().lower() == me:
2004
+ return "owner"
2005
+ return shares.role_for("workbook", book.get("id"), me, is_admin=is_admin, st=st)
2006
+
2007
+
2008
+ def may_read_workbook(book, role):
2009
+ """R28: a role admits a reader; unmarked or creatorless documents remain legacy-visible.
2010
+
2011
+ Creation and explicit sharing stamp access. Read the document every time:
2012
+ _index_upsert rebuilds its row after every save, and PUT must preserve marker absence too.
2013
+ Legacy visibility grants no ownership or editing role.
2014
+ """
2015
+ return bool(role) or "access" not in book or not book.get("created_by")
2016
+
2017
+
2018
+ def project_shares(st, rows, viewer=None, *, is_admin=False, role_on_workbook=None):
2019
  """Join `shares` onto a list of index rows. Returns NEW rows; the stored ones are untouched.
2020
 
2021
+ A named viewer filters rows against each live workbook document and receives their role.
2022
+ The route supplies its existing role helper; core callers use workbook_role directly.
2023
+ `list_workbooks` itself stays a bare pointer list on purpose:
2024
  `iter_workbooks` walks it to answer W49-T10's dependents question, and paying a grant-registry
2025
  read per workbook there would put a permission lookup inside a scan that asks no permission
2026
  question at all.
 
2030
  if not isinstance(row, dict) or not row.get("id"):
2031
  continue
2032
  joined = dict(row)
2033
+ if viewer:
2034
+ book = _read(st, workbook_key(row["id"]))
2035
+ if not book or not book.get("id"):
2036
+ continue
2037
+ role = (role_on_workbook(book) if role_on_workbook is not None
2038
+ else workbook_role(st, book, viewer, is_admin=is_admin))
2039
+ if not may_read_workbook(book, role):
2040
+ continue
2041
+ joined["role"] = role or "view"
2042
  joined["shares"] = workbook_shares(st, row["id"])
2043
  out.append(joined)
2044
  return out
 
2495
  return 0
2496
 
2497
 
2498
+ def _visible_rail(folders, placed, starred, ids):
2499
+ """Prune hidden placements, stars and folders occupied only by hidden workbooks.
2500
+
2501
+ Keep visible folders' ancestors and intentionally empty folders. Otherwise creating an
2502
+ empty folder would immediately hide it from the person who needs to put a workbook in it.
2503
+ """
2504
+ parents = {f["id"]: f.get("parent") for f in folders}
2505
+
2506
+ def ancestors(folder_ids):
2507
+ found = set()
2508
+ for fid in folder_ids:
2509
+ while fid in parents and fid not in found:
2510
+ found.add(fid)
2511
+ fid = parents[fid]
2512
+ return found
2513
+
2514
+ visible = {wid: fid for wid, fid in placed.items() if wid in ids}
2515
+ occupied = ancestors(placed.values())
2516
+ needed = ancestors(set(visible.values()) | (parents.keys() - occupied))
2517
+ hidden_only = occupied - needed
2518
+ return ([f for f in folders if f["id"] not in hidden_only], visible,
2519
+ _clean_starred(starred, ids, []))
2520
+
2521
+
2522
+ def read_index(st, viewer=None, *, is_admin=False, role_on_workbook=None):
2523
  """The whole rail document: `{workbooks, folders, itemFolders, starred, rev}`, plus
2524
  `sharedWithMe` when a `viewer` is named.
2525
 
 
2544
  doc = _read(st, INDEX_KEY)
2545
  rows = [dict(r) for r in (doc.get("workbooks") or [])
2546
  if isinstance(r, dict) and r.get("id")]
2547
+ rows = project_shares(st, rows, viewer, is_admin=is_admin, role_on_workbook=role_on_workbook)
2548
  ids = {r["id"] for r in rows}
2549
  placements = doc.get("itemFolders")
2550
  try:
 
2553
  flat = [dict(f, parent=None) for f in (doc.get("folders") or [])
2554
  if isinstance(f, dict) and f.get("id")]
2555
  folders, placed, _repairs = validate_folder_tree(flat, placements)
2556
+ starred = _clean_starred(doc.get("starred"), ids, [])
2557
+ if viewer:
2558
+ folders, placed, starred = _visible_rail(folders, placed, doc.get("starred"), ids)
2559
  out = {
2560
+ "workbooks": rows,
2561
  "folders": folders,
2562
  "itemFolders": {k: v for k, v in placed.items() if k in ids},
2563
+ "starred": starred,
2564
  "rev": _index_rev(doc),
2565
  }
2566
  if viewer:
platform/core/user_tables.py CHANGED
@@ -4473,10 +4473,13 @@ def may_edit_database(table_key, viewer, is_admin=False, st=None):
4473
  #:
4474
  #: ⚠ THE ALLOW-LIST IS THE SAFETY ARGUMENT, not the read-only-ness. Any other key passes through
4475
  #: to the real runtime uncached, `fresh=True` always bypasses, and every WRITE verb reaches the
4476
- #: runtime through `__getattr__` — so this can serve a stale value for exactly two keys, for
 
4477
  #: exactly one pass, to code proven not to mutate them (`all_tables` shallow-copies the top level
4478
  #: before anybody touches it; `grants`/`_clean_entries` build new objects; `may_open` only READS
4479
- #: `createdBy`).
 
 
4480
  _LENDABLE = (STORE_KEY, 'object_shares')
4481
 
4482
 
@@ -4487,7 +4490,7 @@ class _Lent:
4487
  self._runtime, self._docs = runtime, dict(docs or {})
4488
 
4489
  def get(self, name, fresh=False):
4490
- if fresh or name not in _LENDABLE:
4491
  return self._runtime.get(name, fresh) if fresh else self._runtime.get(name)
4492
  if name not in self._docs:
4493
  self._docs[name] = self._runtime.get(name) # lazily, once, for this pass
@@ -4507,7 +4510,7 @@ class _Lent:
4507
  A re-projection would cost a second copy to convert the first case and change nothing
4508
  about the second.
4509
  """
4510
- if name not in _LENDABLE:
4511
  return self._runtime.get_projection(name, drop=drop)
4512
  if name not in self._docs:
4513
  self._docs[name] = self._runtime.get_projection(name, drop=drop)
@@ -4518,7 +4521,7 @@ class _Lent:
4518
 
4519
 
4520
  def lend(st=None, **docs):
4521
- """A handle that serves `docs` for `_LENDABLE` keys and defers everything else to `st`.
4522
 
4523
  `lend(rt, user_tables=doc)` — keyword names are STORE KEYS. Call it once per read pass and
4524
  hand the result to every predicate in that pass; see the note above for what makes it safe.
 
4473
  #:
4474
  #: ⚠ THE ALLOW-LIST IS THE SAFETY ARGUMENT, not the read-only-ness. Any other key passes through
4475
  #: to the real runtime uncached, `fresh=True` always bypasses, and every WRITE verb reaches the
4476
+ #: runtime through `__getattr__` — so this can serve a stale value for the two named keys and
4477
+ #: dynamically named `<key>__shared` overlay buckets, for
4478
  #: exactly one pass, to code proven not to mutate them (`all_tables` shallow-copies the top level
4479
  #: before anybody touches it; `grants`/`_clean_entries` build new objects; `may_open` only READS
4480
+ #: `createdBy`). Shared overlays are also read-only on this path: `_shared_value_keys` only
4481
+ #: reads their field keys, never mutates the document. Their first read is lent for one pass;
4482
+ #: `fresh=True` and write verbs still reach the runtime, never the snapshot.
4483
  _LENDABLE = (STORE_KEY, 'object_shares')
4484
 
4485
 
 
4490
  self._runtime, self._docs = runtime, dict(docs or {})
4491
 
4492
  def get(self, name, fresh=False):
4493
+ if fresh or (name not in _LENDABLE and not str(name).endswith('__shared')):
4494
  return self._runtime.get(name, fresh) if fresh else self._runtime.get(name)
4495
  if name not in self._docs:
4496
  self._docs[name] = self._runtime.get(name) # lazily, once, for this pass
 
4510
  A re-projection would cost a second copy to convert the first case and change nothing
4511
  about the second.
4512
  """
4513
+ if name not in _LENDABLE and not str(name).endswith('__shared'):
4514
  return self._runtime.get_projection(name, drop=drop)
4515
  if name not in self._docs:
4516
  self._docs[name] = self._runtime.get_projection(name, drop=drop)
 
4521
 
4522
 
4523
  def lend(st=None, **docs):
4524
+ """Lend `_LENDABLE` keys and `__shared` suffix buckets; defer other keys to `st`.
4525
 
4526
  `lend(rt, user_tables=doc)` — keyword names are STORE KEYS. Call it once per read pass and
4527
  hand the result to every predicate in that pass; see the note above for what makes it safe.
platform/harness/amazon_client.py CHANGED
@@ -245,8 +245,10 @@ REPORT_TYPES = {
245
  # reads whatever V2 actually sends and nothing here needs to know the column list -- which is
246
  # exactly the property that makes swapping the report type a one-line change.
247
  # · https://developer-docs.amazon.com/sp-api/docs/report-type-values-settlement
 
 
248
  "settlements": {
249
- "report": "GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE_V2",
250
  "validates_against": "settlement summary vs settlement lines",
251
  "role": "Finance and Accounting",
252
  },
@@ -324,6 +326,13 @@ OPERATIONS = {
324
  "name": "createReport", "roles": _BULK_REPORT_ROLES, "method": "POST",
325
  "path": "reports/2021-06-30/reports", "report_types": _APPROVED_REPORT_TYPES,
326
  },
 
 
 
 
 
 
 
327
  "getReport": {
328
  "name": "getReport", "roles": _BULK_REPORT_ROLES, "method": "GET",
329
  "path": "reports/2021-06-30/reports/{reportId}",
@@ -967,6 +976,69 @@ def report_document(fields, report_type, start=None, end=None, options=None,
967
  "compression": meta.get("compressionAlgorithm")}
968
 
969
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
970
  def _download_document(url, compression="", timeout=120):
971
  """Fetch one presigned report document and decode it. -> text.
972
 
 
245
  # reads whatever V2 actually sends and nothing here needs to know the column list -- which is
246
  # exactly the property that makes swapping the report type a one-line change.
247
  # · https://developer-docs.amazon.com/sp-api/docs/report-type-values-settlement
248
+ # Amazon creates settlements on its own schedule and refuses createReport for them.
249
+ # This type is a getReports discovery filter, never a requestable report flavor.
250
  "settlements": {
251
+ "report_discover": "GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE_V2",
252
  "validates_against": "settlement summary vs settlement lines",
253
  "role": "Finance and Accounting",
254
  },
 
326
  "name": "createReport", "roles": _BULK_REPORT_ROLES, "method": "POST",
327
  "path": "reports/2021-06-30/reports", "report_types": _APPROVED_REPORT_TYPES,
328
  },
329
+ # Discovery is approved only for Amazon-issued settlements and their finance role.
330
+ # Sharing the Reports path grants neither the other bulk types nor their roles.
331
+ "getReports": {
332
+ "name": "getReports", "roles": ("Finance and Accounting",), "method": "GET",
333
+ "path": "reports/2021-06-30/reports",
334
+ "report_types": (REPORT_TYPES["settlements"]["report_discover"],),
335
+ },
336
  "getReport": {
337
  "name": "getReport", "roles": _BULK_REPORT_ROLES, "method": "GET",
338
  "path": "reports/2021-06-30/reports/{reportId}",
 
976
  "compression": meta.get("compressionAlgorithm")}
977
 
978
 
979
+ SETTLEMENT_REPORT_PAGE_CAP = 1000
980
+
981
+
982
+ def settlement_reports(fields, *, since=None, timeout=_TIMEOUT, log=None):
983
+ """List settlements Amazon has already created, oldest first.
984
+
985
+ Amazon issues these on its own fortnightly cycle, so this lists rather than requests.
986
+ Only safe, named metadata leaves this function; vendor extras and tokens stay here.
987
+ """
988
+ require_operation("GET", _REPORTS_CREATE_PATH,
989
+ report_type=REPORT_TYPES["settlements"]["report_discover"])
990
+ import re
991
+
992
+ rtype = REPORT_TYPES["settlements"]["report_discover"]
993
+ token = access_token(fields, timeout=timeout)
994
+ region = str((fields or {}).get("region") or DEFAULT_REGION)
995
+ params = {"reportTypes": rtype, "processingStatuses": "DONE", "pageSize": 100}
996
+ if since is not None:
997
+ params["createdSince"] = str(since)
998
+ reports = []
999
+ for _page in range(SETTLEMENT_REPORT_PAGE_CAP):
1000
+ # _request owns the same _retry policy as the existing report/document reads.
1001
+ got = _request(_REPORTS_CREATE_PATH, token, region=region, timeout=timeout,
1002
+ sandbox=is_sandbox(fields), **params)
1003
+ for raw in got.get("reports") or ():
1004
+ row = {key: str(raw[key]) if raw.get(key) is not None else "" for key in (
1005
+ "reportId", "reportDocumentId", "reportType", "dataStartTime",
1006
+ "dataEndTime", "createdTime")}
1007
+ # Match the API status door without importing upward into the API layer.
1008
+ # Refuse unsafe values with a fixed sentence that cannot echo the credential.
1009
+ if any(len(value) > 512 or "Atzr|" in value
1010
+ or re.search(r"\bbearer\s+\S+", value, flags=re.IGNORECASE)
1011
+ or any(ch in value for ch in ("\u2014", "\u2013"))
1012
+ for value in row.values()):
1013
+ raise AmazonError("Settlement discovery returned unsafe metadata; no status was emitted.")
1014
+ if row["reportType"] != rtype or not row["reportDocumentId"]:
1015
+ raise AmazonError("Settlement discovery returned an unexpected type or no document ID.")
1016
+ reports.append(row)
1017
+ next_token = got.get("nextToken")
1018
+ if not next_token:
1019
+ if log:
1020
+ log(f"getReports discovered {len(reports)} settlement reports")
1021
+ return sorted(reports, key=lambda row: (row["createdTime"], row["reportId"]))
1022
+ # Amazon continuation tokens replace the original filters, which the token carries.
1023
+ params = {"nextToken": str(next_token)}
1024
+ raise AmazonError(
1025
+ f"Settlement discovery hit the {SETTLEMENT_REPORT_PAGE_CAP}-page cap because Amazon kept "
1026
+ "returning nextToken; retry with a narrower createdSince window.")
1027
+
1028
+
1029
+ def settlement_document(fields, document_id, *, timeout=_TIMEOUT):
1030
+ """One settlement document's text through getReportDocument and the presigned URL."""
1031
+ require_operation("GET", f"reports/2021-06-30/documents/{document_id}")
1032
+ token = access_token(fields, timeout=timeout)
1033
+ region = str((fields or {}).get("region") or DEFAULT_REGION)
1034
+ meta = _request(f"reports/2021-06-30/documents/{document_id}", token, region=region,
1035
+ timeout=timeout, sandbox=is_sandbox(fields))
1036
+ url = str(meta.get("url") or "")
1037
+ if not url:
1038
+ raise AmazonError("The settlement document carried no download URL.")
1039
+ return _download_document(url, str(meta.get("compressionAlgorithm") or ""))
1040
+
1041
+
1042
  def _download_document(url, compression="", timeout=120):
1043
  """Fetch one presigned report document and decode it. -> text.
1044
 
platform/harness/amazon_store.py CHANGED
@@ -70,6 +70,9 @@ PREFIX = "amzn_"
70
  TABLES = ("orders", "order_items", "listings", "settlements", "inventory",
71
  "pricing", "brand_analytics")
72
 
 
 
 
73
  # C1 is a tenant-store document, not an API dependency. verify_amazon gates reader parity.
74
  ENABLEMENT_KEY = "amazon_connector_enablement"
75
  # Settlements are issued roughly fortnightly; spending a report on every hourly tick adds nothing.
@@ -149,8 +152,20 @@ def entity_key(table):
149
  #: How far back a first sync reaches when the caller names no window. Amazon's flat-file order
150
  #: reports accept at most ~31 days per request, so a backfill is sliced (`_windows`).
151
  DEFAULT_BACKFILL_DAYS = int(os.environ.get("AMAZON_BACKFILL_DAYS") or 730)
 
 
152
  #: ⚠ AMAZON'S OWN CEILING, NOT OURS, and it is why a backfill is many reports rather than one.
153
  MAX_WINDOW_DAYS = 30
 
 
 
 
 
 
 
 
 
 
154
 
155
  # Connector metadata, NOT measured Amazon fields. TSV normalization strips leading underscores;
156
  # JSON flattening rejects these exact reserved keys. Neither path can overwrite metadata.
@@ -447,7 +462,7 @@ def _cell(value, kind):
447
  return None
448
 
449
 
450
- def _ensure(con, table, cols, rows=None, declared=None):
451
  """Create or widen the mirror table. A column whose type is now wrong is REBUILT, not patched.
452
 
453
  ⚠ Same ruling as `meta_store._ensure`: DuckDB cannot retype in place, and this is derived data
@@ -479,7 +494,15 @@ def _ensure(con, table, cols, rows=None, declared=None):
479
  clash = [c for c, ty in want.items()
480
  if c in have and have[c] != ty
481
  and not (have[c].startswith("VARCHAR") and ty == "VARCHAR")]
482
- if clash:
 
 
 
 
 
 
 
 
483
  con.execute(f"DROP TABLE {table}")
484
  have = {}
485
  if not have:
@@ -508,6 +531,47 @@ def _replace(con, table, cols, types, rows):
508
  return len(rows)
509
 
510
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
511
  def _windows(start, end, size=MAX_WINDOW_DAYS):
512
  """Slice a backfill into report-sized windows. Amazon's ceiling, reported not hidden."""
513
  out, cur = [], start
@@ -518,6 +582,49 @@ def _windows(start, end, size=MAX_WINDOW_DAYS):
518
  return out
519
 
520
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
521
  def _iso(dt):
522
  return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
523
 
@@ -1071,6 +1178,94 @@ def _read_state(con, key):
1071
  return {"state": row[0], "rows": row[1], "updated_at": row[2], "detail": row[3]}
1072
 
1073
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1074
  def _sync_event(kind, tenant, table, detail, rt, report, log):
1075
  """Sync is nondestructive: preserve C2's loud failure, but continue the data pull."""
1076
  try:
@@ -1108,7 +1303,7 @@ def _sync_problem(exc, table, operation, tenant, rt, report, log):
1108
 
1109
 
1110
  def sync(tenant_key="royal-imports", tables=None, since=None, log=print, rt=None,
1111
- max_wait=900, *, scheduled=False):
1112
  """Pull every declared table into the tenant's mirror. -> a report dict.
1113
 
1114
  Idempotent: a re-sync replaces each window rather than appending. Refuses, loudly and with the
@@ -1142,7 +1337,6 @@ def sync(tenant_key="royal-imports", tables=None, since=None, log=print, rt=None
1142
 
1143
  want = [t for t in (TABLES if tables is None else tables) if t in TABLES]
1144
  end = datetime.now(timezone.utc)
1145
- start = since or (end - timedelta(days=DEFAULT_BACKFILL_DAYS))
1146
  report = {"tenant": tenant_key, "tables": {}, "started": _iso(end),
1147
  "problems": [], "audit_problems": []}
1148
  enablement = read_database_enablement(rt)
@@ -1171,6 +1365,16 @@ def sync(tenant_key="royal-imports", tables=None, since=None, log=print, rt=None
1171
  if obligation["earliestTriggerAt"]:
1172
  con.close()
1173
  raise RuntimeError("Amazon deletion is outstanding; sync cannot repopulate purged data")
 
 
 
 
 
 
 
 
 
 
1174
  if scheduled:
1175
  plan = sync_plan({table: _read_state(con, entity_key("sync_tick_" + table))
1176
  for table in TABLES}, want, now=end)
@@ -1179,9 +1383,60 @@ def sync(tenant_key="royal-imports", tables=None, since=None, log=print, rt=None
1179
  report["tables"][table] = {"state": "deferred", "reason": reason}
1180
  log(f"{table}: DEFERRED: {reason}")
1181
 
1182
- for table in want:
1183
- spec = cx.REPORT_TYPES.get(table) or {}
1184
- rtype = spec.get("report")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1185
  key, mirror = entity_key(table), table_name(table)
1186
  if not rtype:
1187
  report["tables"][table] = {"rows": 0, "state": "no confirmed bulk report"}
@@ -1189,15 +1444,89 @@ def sync(tenant_key="royal-imports", tables=None, since=None, log=print, rt=None
1189
  continue
1190
  prov = amazon_schema.PROVENANCE.get(table, "measured_at_sync")
1191
  root = (amazon_schema.ARTIFACTS.get(table) or (None, None))[1]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1192
  try:
1193
  # Attempt first, so a refusal or process interruption cannot starve the other tables.
1194
- _record_state(con, entity_key("sync_tick_" + table), "attempted")
 
 
 
 
1195
  written, cols, cleared = 0, [], False
1196
  pricing_asins = []
1197
- for w0, w1 in _windows(start, end):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1198
  # W59-T43 / C2 has no amazon.access kind. Record each credential-backed
1199
  # vendor attempt as a sync ACCESS phase, distinct from the completion event.
1200
  # Lane F/combine own the vocabulary decision; no credential or row enters C2.
 
1201
  _sync_event("amazon.sync", tenant_key, table,
1202
  {"state": "access", "operation": "report_document"}, rt, report, log)
1203
  text, meta = cx.report_document(
@@ -1237,7 +1566,25 @@ def sync(tenant_key="royal-imports", tables=None, since=None, log=print, rt=None
1237
  text, document_id=meta.get("reportDocumentId"), report_type=rtype)
1238
  declared = {}
1239
  if not cols:
1240
- continue
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1241
  if table == "orders":
1242
  rows = _dedupe_orders(rows)
1243
  if table == "inventory":
@@ -1246,16 +1593,32 @@ def sync(tenant_key="royal-imports", tables=None, since=None, log=print, rt=None
1246
  cols.append("inventory_source")
1247
  if table == "pricing":
1248
  pricing_asins.extend(_pricing_asins(rows))
1249
- types = _ensure(con, mirror, cols, rows, declared=declared)
1250
- # Clear once, after the table exists. The old multi-window branch deleted nothing,
1251
- # so every backfill appended a second copy of every historical row.
1252
- if not cleared:
1253
  con.execute(f"DELETE FROM {mirror} WHERE 1=1")
1254
  cleared = True
1255
- written += _replace(con, mirror, cols, types, rows)
 
 
 
 
 
 
 
 
 
 
 
1256
 
1257
- operations = {}
1258
  if table == "pricing":
 
 
 
 
 
 
1259
  state_key = ENTITY_STATE_KEYS[table]
1260
  if not pricing_asins:
1261
  _record_state(con, state_key, "unproven", 0,
@@ -1291,11 +1654,11 @@ def sync(tenant_key="royal-imports", tables=None, since=None, log=print, rt=None
1291
  awd_rows = _awd_rows(inventory)
1292
  if awd_rows:
1293
  awd_cols = sorted({c for row in awd_rows for c in row})
1294
- awd_types = _ensure(con, mirror, awd_cols, awd_rows)
1295
- if not cleared:
1296
  con.execute(f"DELETE FROM {mirror} WHERE 1=1")
1297
  cleared = True
1298
- written += _replace(con, mirror, awd_cols, awd_types, awd_rows)
1299
  _record_state(con, state_key, "done", len(awd_rows))
1300
  operations["listInventory"] = {
1301
  "state": "done", "rows": len(awd_rows)}
@@ -1312,21 +1675,67 @@ def sync(tenant_key="royal-imports", tables=None, since=None, log=print, rt=None
1312
  column_count, total_rows = len(cols), written
1313
  report["tables"][table] = {
1314
  "rows": total_rows, "columns": column_count, "provenance": prov,
1315
- "report": rtype, "operations": operations}
 
1316
  _record_state(con, key, "done", total_rows)
1317
  _record_state(con, entity_key("sync_tick_" + table), "done", total_rows)
 
 
1318
  _sync_event("amazon.sync", tenant_key, table,
1319
  {"state": "done", "rows": total_rows,
1320
  "operations_ok": all(v["state"] == "done" for v in operations.values())},
1321
  rt, report, log)
1322
  log(f" {table:<16} {total_rows:>7,} rows {column_count:>3} cols {prov}")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1323
  except Exception as e: # noqa: BLE001
 
1324
  # ⚠ ONE TABLE'S REFUSAL IS NOT THE SYNC'S. A 403 on brand_analytics is R5's UNPROVEN
1325
  # ticket answering itself, and it must not cost the six tables that did work.
1326
- problem = _sync_problem(e, table, "report_document", tenant_key, rt, report, log)
 
1327
  report["tables"][table] = {"rows": 0, **problem}
1328
  _sync_event("amazon.sync", tenant_key, table,
1329
  {"state": problem["state"], "rows": 0}, rt, report, log)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1330
  report["finished"] = _iso(datetime.now(timezone.utc))
1331
  con.close()
1332
  return report
 
70
  TABLES = ("orders", "order_items", "listings", "settlements", "inventory",
71
  "pricing", "brand_analytics")
72
 
73
+ #: Head -> lines: both tables read the same document; a second report buys no new rows.
74
+ SHARED_REPORT_SIBLINGS = {"orders": "order_items"}
75
+
76
  # C1 is a tenant-store document, not an API dependency. verify_amazon gates reader parity.
77
  ENABLEMENT_KEY = "amazon_connector_enablement"
78
  # Settlements are issued roughly fortnightly; spending a report on every hourly tick adds nothing.
 
152
  #: How far back a first sync reaches when the caller names no window. Amazon's flat-file order
153
  #: reports accept at most ~31 days per request, so a backfill is sliced (`_windows`).
154
  DEFAULT_BACKFILL_DAYS = int(os.environ.get("AMAZON_BACKFILL_DAYS") or 730)
155
+ #: Per-table marker whose detail is the ISO UTC end of the last successfully landed window.
156
+ WATERMARK_PREFIX = "sync_mark_"
157
  #: ⚠ AMAZON'S OWN CEILING, NOT OURS, and it is why a backfill is many reports rather than one.
158
  MAX_WINDOW_DAYS = 30
159
+ #: R18: the most recent month lands before any history, so a newly connected account has usable
160
+ #: rows in minutes instead of hours. One window, because Amazon's own ceiling is 30 days.
161
+ FIRST_LOAD_RECENT_DAYS = MAX_WINDOW_DAYS
162
+ #: F4: Amazon paces createReport (burst 15, one per 60 s, 5 s gap), so 7 tables x 25 windows is
163
+ #: about 2.7 h. A first load therefore runs in BOUNDED passes, or it would hold the resident
164
+ #: thread for hours and the Odoo resync behind it would never run.
165
+ FIRST_LOAD_REPORTS_PER_PASS = 15
166
+ BACKFILL_FLOOR_PREFIX = "sync_floor_"
167
+ FIRST_LOAD_END_KEY = "sync_first_load_end"
168
+ FIRST_LOAD_STATUS_KEY = "sync_first_load_status"
169
 
170
  # Connector metadata, NOT measured Amazon fields. TSV normalization strips leading underscores;
171
  # JSON flattening rejects these exact reserved keys. Neither path can overwrite metadata.
 
462
  return None
463
 
464
 
465
+ def _ensure(con, table, cols, rows=None, declared=None, *, preserve_rows=False):
466
  """Create or widen the mirror table. A column whose type is now wrong is REBUILT, not patched.
467
 
468
  ⚠ Same ruling as `meta_store._ensure`: DuckDB cannot retype in place, and this is derived data
 
494
  clash = [c for c, ty in want.items()
495
  if c in have and have[c] != ty
496
  and not (have[c].startswith("VARCHAR") and ty == "VARCHAR")]
497
+ if clash and preserve_rows:
498
+ # Settlement document markers preclude replay: widening must retain prior lines.
499
+ # The measured types are VARCHAR, BIGINT and DOUBLE; never narrow historical data.
500
+ for c in clash:
501
+ widened = "VARCHAR" if "VARCHAR" in (have[c], want[c]) else "DOUBLE"
502
+ if have[c] != widened:
503
+ con.execute(f'ALTER TABLE "{table}" ALTER COLUMN "{c}" TYPE {widened}')
504
+ have[c] = want[c] = widened
505
+ elif clash:
506
  con.execute(f"DROP TABLE {table}")
507
  have = {}
508
  if not have:
 
531
  return len(rows)
532
 
533
 
534
+ def replace_keys_for(table):
535
+ """Replace on declared identity excluding lineage, which changes on every fetch."""
536
+ return tuple(c for c in (amazon_schema.TABLE_SPECS.get(table) or {}).get("row_identity", ())
537
+ if c not in _ORIGIN_TYPES)
538
+
539
+
540
+ def replace_window(con, table, cols, types, rows, keys):
541
+ """Replace incoming key groups atomically, or report why only insertion is possible."""
542
+ missing = [c for c in keys if c not in cols]
543
+ if missing:
544
+ note = (f"{table}: window replacement unavailable; missing identity columns: "
545
+ f"{', '.join(missing)}; rows inserted; use a report carrying these columns")
546
+ return _replace(con, table, cols, types, rows), note
547
+ if not keys or not rows:
548
+ return _replace(con, table, cols, types, rows), None
549
+ quote = lambda name: '"' + str(name).replace('"', '""') + '"'
550
+ target = quote(table)
551
+ temporary = quote("amazon_window_keys_" + uuid.uuid4().hex)
552
+ columns = ", ".join(quote(c) for c in keys)
553
+ # Use the mirror's types and the insert's cell conversion so NULL and numeric keys agree.
554
+ incoming = list(dict.fromkeys(tuple(_cell(row.get(c), types.get(c, "VARCHAR"))
555
+ for c in keys) for row in rows))
556
+ con.execute(f"CREATE TEMP TABLE {temporary} AS SELECT {columns} FROM {target} WHERE FALSE")
557
+ try:
558
+ con.executemany(f"INSERT INTO {temporary} VALUES ({', '.join('?' for _ in keys)})",
559
+ incoming)
560
+ predicate = " AND ".join(
561
+ f'{target}.{quote(c)} IS NOT DISTINCT FROM "k".{quote(c)}' for c in keys)
562
+ con.execute("BEGIN TRANSACTION")
563
+ try:
564
+ con.execute(f'DELETE FROM {target} WHERE EXISTS (SELECT 1 FROM {temporary} AS "k" WHERE {predicate})')
565
+ count = _replace(con, table, cols, types, rows)
566
+ con.execute("COMMIT")
567
+ except Exception:
568
+ con.execute("ROLLBACK")
569
+ raise
570
+ return count, None
571
+ finally:
572
+ con.execute(f"DROP TABLE {temporary}")
573
+
574
+
575
  def _windows(start, end, size=MAX_WINDOW_DAYS):
576
  """Slice a backfill into report-sized windows. Amazon's ceiling, reported not hidden."""
577
  out, cur = [], start
 
582
  return out
583
 
584
 
585
+ def first_load_plan(tables, start, end, *, recent_days=None, size=MAX_WINDOW_DAYS):
586
+ """R18's request order: every recent month, then each table's history, oldest last.
587
+
588
+ Settlements have one discovery slot (None, None), never a createReport window.
589
+ This planner is pure; durable floors filter its fixed windows when a pass resumes.
590
+ """
591
+ start, end = _utc(start), _utc(end)
592
+ if start >= end:
593
+ return []
594
+ size = min(float(size), MAX_WINDOW_DAYS)
595
+ recent_days = FIRST_LOAD_RECENT_DAYS if recent_days is None else recent_days
596
+ recent_days = min(float(recent_days), size)
597
+ if size <= 0 or recent_days <= 0:
598
+ raise ValueError("Amazon report windows must have a positive size.")
599
+ recent_start = max(start, end - timedelta(days=recent_days))
600
+ tables = list(dict.fromkeys(tables))
601
+ recent = [(table, None, None) if table == "settlements" else (table, recent_start, end)
602
+ for table in tables]
603
+ history = [(table, w0, w1) for table in tables if table != "settlements"
604
+ for w0, w1 in reversed(_windows(start, recent_start, size))]
605
+ return recent + history
606
+
607
+
608
+ def first_load_eta(report_count, *, stagger_seconds=None, burst=None, per_minute=None):
609
+ """Amazon createReport pacing floor in seconds; polling and other work can add time."""
610
+ from harness.amazon_client import REPORT_STAGGER_SECONDS, REPORT_BURST, REPORT_SUSTAINED_SECONDS
611
+ if report_count <= 0:
612
+ return 0
613
+ stagger = REPORT_STAGGER_SECONDS if stagger_seconds is None else stagger_seconds
614
+ tokens = REPORT_BURST if burst is None else burst
615
+ rate = 60 / REPORT_SUSTAINED_SECONDS if per_minute is None else per_minute
616
+ seconds = max(0, (report_count - 1) * stagger, (report_count - tokens) * 60 / rate)
617
+ return int(seconds) + (seconds > int(seconds))
618
+
619
+
620
+ def first_load_eta_cause(report_count):
621
+ """Screen-safe explanation of the vendor ceiling and the automatic continuation."""
622
+ from harness.amazon_client import REPORT_BURST, REPORT_SUSTAINED_SECONDS
623
+ return (f"Amazon's report rate allows a burst of {REPORT_BURST}, then one report every "
624
+ f"{REPORT_SUSTAINED_SECONDS:g} seconds. Keep the connection enabled while history "
625
+ "loads automatically. Report processing and other syncs can add time.")
626
+
627
+
628
  def _iso(dt):
629
  return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
630
 
 
1178
  return {"state": row[0], "rows": row[1], "updated_at": row[2], "detail": row[3]}
1179
 
1180
 
1181
+ def settlement_is_new(con, document_id):
1182
+ """A completed document is durable even when it contained no mirror lines."""
1183
+ state = _read_state(con, entity_key("settlement_doc_" + str(document_id)))
1184
+ return not state or state["state"] != "done"
1185
+
1186
+
1187
+ def read_watermark(con, table):
1188
+ """Missing or malformed detail means no successful window, never the current time."""
1189
+ state = _read_state(con, entity_key(WATERMARK_PREFIX + table))
1190
+ detail = (state or {}).get("detail")
1191
+ if not detail:
1192
+ return None
1193
+ try:
1194
+ return _utc(detail)
1195
+ except (ValueError, TypeError, AttributeError, OverflowError):
1196
+ return None
1197
+
1198
+
1199
+ def record_watermark(con, table, when, rows=0):
1200
+ """Persist only after this table's pass succeeds."""
1201
+ _record_state(con, entity_key(WATERMARK_PREFIX + table), "done", rows, _iso(_utc(when)))
1202
+
1203
+
1204
+ def read_backfill_floor(con, table):
1205
+ """Oldest contiguous landed window; missing or corrupt markers restart safely."""
1206
+ state = _read_state(con, entity_key(BACKFILL_FLOOR_PREFIX + table))
1207
+ try:
1208
+ return _utc(state["detail"]) if state and state.get("detail") else None
1209
+ except (ValueError, TypeError, AttributeError, OverflowError):
1210
+ return None
1211
+
1212
+
1213
+ def record_backfill_floor(con, table, when):
1214
+ _record_state(con, entity_key(BACKFILL_FLOOR_PREFIX + table), "done", detail=_iso(_utc(when)))
1215
+
1216
+
1217
+ def needs_first_load(tenant_key, rt=None):
1218
+ """A fresh account or an unfinished durable load uses bounded passes, even after one table finishes."""
1219
+ con, _path = _connect_tenant_mirror(tenant_key, rt)
1220
+ try:
1221
+ load = _read_state(con, entity_key(FIRST_LOAD_END_KEY))
1222
+ return bool(load and load["state"] != "done") or not any(
1223
+ read_watermark(con, table) for table in TABLES)
1224
+ finally:
1225
+ con.close()
1226
+
1227
+
1228
+ def first_load_status(tenant_key, rt=None):
1229
+ """Durable numeric progress for the API's safe-status projection; no vendor payloads."""
1230
+ con, _path = _connect_tenant_mirror(tenant_key, rt)
1231
+ try:
1232
+ state = _read_state(con, entity_key(FIRST_LOAD_STATUS_KEY))
1233
+ if not state:
1234
+ return None
1235
+ values = json.loads(state["detail"])
1236
+ return {"state": state["state"], "remaining": int(values["remaining"]),
1237
+ "etaSeconds": int(values["etaSeconds"]), "backfillDays": DEFAULT_BACKFILL_DAYS,
1238
+ "cause": first_load_eta_cause(values["remaining"])}
1239
+ finally:
1240
+ con.close()
1241
+
1242
+
1243
+ def sync_window(table, mark, *, now, since=None, backfill_days=None):
1244
+ """Pure request decision for one table: start, end, report, incremental and cause."""
1245
+ end = _utc(now)
1246
+ days = DEFAULT_BACKFILL_DAYS if backfill_days is None else backfill_days
1247
+ try:
1248
+ mark = _utc(mark) if mark else None
1249
+ except (ValueError, TypeError, AttributeError, OverflowError):
1250
+ mark = None
1251
+ if since is not None:
1252
+ start, incremental = _utc(since), False
1253
+ cause = f"caller named the window starting {_iso(start)}"
1254
+ elif mark is not None:
1255
+ start, incremental = mark, True
1256
+ cause = f"incremental window since watermark {_iso(mark)}"
1257
+ else:
1258
+ start, incremental = end - timedelta(days=days), False
1259
+ cause = f"first full load: {days} days of backfill"
1260
+ spec = _client().REPORT_TYPES.get(table) or {}
1261
+ rtype = spec.get("report_incremental") if incremental and spec.get("report_incremental") else spec.get("report")
1262
+ if table == "settlements":
1263
+ # The watermark filters issued reports by creation time; it never requests one.
1264
+ rtype = spec.get("report_discover")
1265
+ return {"start": start, "end": end, "report": rtype,
1266
+ "incremental": incremental, "cause": cause}
1267
+
1268
+
1269
  def _sync_event(kind, tenant, table, detail, rt, report, log):
1270
  """Sync is nondestructive: preserve C2's loud failure, but continue the data pull."""
1271
  try:
 
1303
 
1304
 
1305
  def sync(tenant_key="royal-imports", tables=None, since=None, log=print, rt=None,
1306
+ max_wait=900, *, scheduled=False, first_load=False, report_budget=None):
1307
  """Pull every declared table into the tenant's mirror. -> a report dict.
1308
 
1309
  Idempotent: a re-sync replaces each window rather than appending. Refuses, loudly and with the
 
1337
 
1338
  want = [t for t in (TABLES if tables is None else tables) if t in TABLES]
1339
  end = datetime.now(timezone.utc)
 
1340
  report = {"tenant": tenant_key, "tables": {}, "started": _iso(end),
1341
  "problems": [], "audit_problems": []}
1342
  enablement = read_database_enablement(rt)
 
1365
  if obligation["earliestTriggerAt"]:
1366
  con.close()
1367
  raise RuntimeError("Amazon deletion is outstanding; sync cannot repopulate purged data")
1368
+ load = _read_state(con, entity_key(FIRST_LOAD_END_KEY))
1369
+ if scheduled and load and load["state"] != "done":
1370
+ # The pinned inline producer still calls sync(scheduled=True). Do not let it start an
1371
+ # unbounded history pull between the resident writer's bounded first-load passes.
1372
+ for table in want:
1373
+ report["tables"][table] = {"state": "deferred", "reason":
1374
+ "The first load is continuing in bounded passes on the resident sync thread."}
1375
+ report["finished"] = _iso(datetime.now(timezone.utc))
1376
+ con.close()
1377
+ return report
1378
  if scheduled:
1379
  plan = sync_plan({table: _read_state(con, entity_key("sync_tick_" + table))
1380
  for table in TABLES}, want, now=end)
 
1383
  report["tables"][table] = {"state": "deferred", "reason": reason}
1384
  log(f"{table}: DEFERRED: {reason}")
1385
 
1386
+ # Heads go first even when the caller listed lines first. Scheduled plans still select one.
1387
+ pending = list(dict.fromkeys([head for head, sibling in SHARED_REPORT_SIBLINGS.items()
1388
+ if head in want and sibling in want] + want))
1389
+ handled, noted = set(), set()
1390
+
1391
+ def write_window(table, cols, types, rows):
1392
+ count, note = replace_window(con, table_name(table), cols, types, rows,
1393
+ replace_keys_for(table))
1394
+ if note and table not in noted:
1395
+ noted.add(table)
1396
+ report["problems"].append(note)
1397
+ log(note)
1398
+ return count
1399
+
1400
+ work, plans, paired, contexts = [], {}, {}, {}
1401
+ documents, settlement_remaining = 0, 0
1402
+ failed, landed = set(), set()
1403
+ if first_load:
1404
+ # Freeze the cohort end across passes. Recomputing it would move every window boundary.
1405
+ end = _utc(load["detail"]) if load else _utc(_iso(end))
1406
+ _record_state(con, entity_key(FIRST_LOAD_END_KEY), "running", detail=_iso(end))
1407
+ plans = {table: sync_window(table, None, now=end) for table in pending}
1408
+ floors = {table: read_backfill_floor(con, table) for table in pending}
1409
+ wanted = [table for table in pending if not read_watermark(con, table)
1410
+ or read_watermark(con, table) < end]
1411
+ for task in first_load_plan(wanted, end - timedelta(days=DEFAULT_BACKFILL_DAYS), end):
1412
+ table, w0, w1 = task
1413
+ if w1 is None or floors[table] is None or w1 <= floors[table]:
1414
+ work.append(task)
1415
+ # A failed enrichment after the final report retries completion without fetching again.
1416
+ for table in wanted:
1417
+ if not any(task[0] == table for task in work):
1418
+ work.append((table, None, None))
1419
+ # Reuse a document for head and lines only when BOTH durable cursors agree.
1420
+ for head, sibling in SHARED_REPORT_SIBLINGS.items():
1421
+ head_tasks = [(w0, w1) for table, w0, w1 in work if table == head]
1422
+ line_tasks = [(w0, w1) for table, w0, w1 in work if table == sibling]
1423
+ if head_tasks and head_tasks == line_tasks:
1424
+ paired[head] = sibling
1425
+ work = [task for task in work if task[0] != sibling]
1426
+ else:
1427
+ work = [(table, None, None) for table in pending]
1428
+
1429
+ for index, (table, task_start, task_end) in enumerate(work):
1430
+ if first_load and table in failed:
1431
+ continue
1432
+ if (first_load and isinstance(report_budget, int) and documents >= max(0, report_budget)
1433
+ and (task_end is not None or table == "settlements")):
1434
+ break
1435
+ if table in handled:
1436
+ continue
1437
+ plan = plans[table] if first_load else sync_window(
1438
+ table, read_watermark(con, table), now=end, since=since)
1439
+ rtype = plan["report"]
1440
  key, mirror = entity_key(table), table_name(table)
1441
  if not rtype:
1442
  report["tables"][table] = {"rows": 0, "state": "no confirmed bulk report"}
 
1444
  continue
1445
  prov = amazon_schema.PROVENANCE.get(table, "measured_at_sync")
1446
  root = (amazon_schema.ARTIFACTS.get(table) or (None, None))[1]
1447
+ log(f"{table}: {plan['cause']}")
1448
+ sibling = SHARED_REPORT_SIBLINGS.get(table)
1449
+ sibling_plan = None
1450
+ if first_load:
1451
+ sibling = paired.get(table)
1452
+ sibling_plan = plans.get(sibling)
1453
+ elif sibling in want and sibling not in handled:
1454
+ sibling_plan = sync_window(sibling, read_watermark(con, sibling), now=end, since=since)
1455
+ differs = [part for part in ("start", "end", "report")
1456
+ if plan[part] != sibling_plan[part]]
1457
+ if differs:
1458
+ log(f"{table} and {sibling}: cannot share this pass; differing {', '.join(differs)}")
1459
+ sibling = None
1460
+ else:
1461
+ handled.add(sibling)
1462
+ log(f"{sibling}: {sibling_plan['cause']}")
1463
+ else:
1464
+ sibling = None
1465
+ operation = "report_document"
1466
  try:
1467
  # Attempt first, so a refusal or process interruption cannot starve the other tables.
1468
+ if not first_load:
1469
+ _record_state(con, entity_key("sync_tick_" + table), "attempted")
1470
+ if sibling and not first_load:
1471
+ _record_state(con, entity_key("sync_tick_" + sibling), "attempted")
1472
+ sibling_written, sibling_cleared = 0, False
1473
  written, cols, cleared = 0, [], False
1474
  pricing_asins = []
1475
+ operations = {}
1476
+ if first_load:
1477
+ cleared = floors[table] is not None
1478
+ sibling_cleared = bool(sibling and floors[sibling] is not None)
1479
+ pricing_asins = contexts.setdefault(table, [])
1480
+ if table == "settlements":
1481
+ operation = "getReports"
1482
+ _sync_event("amazon.sync", tenant_key, table,
1483
+ {"state": "access", "operation": operation}, rt, report, log)
1484
+ discovered = cx.settlement_reports(
1485
+ fields, since=_iso(plan["start"]) if plan["incremental"] else None,
1486
+ log=lambda message: log(f"settlements: {message}"))
1487
+ downloaded, skipped = 0, 0
1488
+ for issued_index, issued in enumerate(discovered):
1489
+ document_id = str(issued.get("reportDocumentId") or "")
1490
+ if not document_id:
1491
+ raise cx.AmazonError("Settlement discovery returned no document ID.")
1492
+ if not settlement_is_new(con, document_id):
1493
+ skipped += 1
1494
+ continue
1495
+ if first_load and isinstance(report_budget, int) and documents >= max(0, report_budget):
1496
+ settlement_remaining = sum(settlement_is_new(con, str(item.get("reportDocumentId") or ""))
1497
+ for item in discovered[issued_index:])
1498
+ break
1499
+ operation = "getReportDocument"
1500
+ documents += 1
1501
+ _sync_event("amazon.sync", tenant_key, table,
1502
+ {"state": "access", "operation": operation}, rt, report, log)
1503
+ text = cx.settlement_document(fields, document_id)
1504
+ cols, rows = parse_flat_file(text, document_id=document_id, report_type=rtype)
1505
+ count = 0
1506
+ if cols and rows:
1507
+ types = _ensure(con, mirror, cols, rows, preserve_rows=True)
1508
+ # Never clear settlement history: durable markers prevent its replay.
1509
+ # A newly issued document still replaces its own settlement's lines.
1510
+ count = write_window(table, cols, types, rows)
1511
+ written += count
1512
+ # Record completion after the write, including header-only and blank files.
1513
+ _record_state(con, entity_key("settlement_doc_" + document_id), "done",
1514
+ count, issued.get("dataEndTime"))
1515
+ downloaded += 1
1516
+ operations["getReports"] = {
1517
+ "state": "done", "reports": len(discovered),
1518
+ "downloaded": downloaded, "skipped": skipped}
1519
+ if first_load and settlement_remaining:
1520
+ break
1521
+ windows = ()
1522
+ if table != "settlements":
1523
+ windows = (([(task_start, task_end)] if task_end is not None else []) if first_load
1524
+ else _windows(plan["start"], plan["end"]))
1525
+ for w0, w1 in (() if table == "settlements" else windows):
1526
  # W59-T43 / C2 has no amazon.access kind. Record each credential-backed
1527
  # vendor attempt as a sync ACCESS phase, distinct from the completion event.
1528
  # Lane F/combine own the vocabulary decision; no credential or row enters C2.
1529
+ documents += 1
1530
  _sync_event("amazon.sync", tenant_key, table,
1531
  {"state": "access", "operation": "report_document"}, rt, report, log)
1532
  text, meta = cx.report_document(
 
1566
  text, document_id=meta.get("reportDocumentId"), report_type=rtype)
1567
  declared = {}
1568
  if not cols:
1569
+ if first_load:
1570
+ # Even an empty recent window clears old rows exactly once.
1571
+ for empty_table in (table, sibling):
1572
+ if empty_table and floors[empty_table] is None:
1573
+ if con.execute("SELECT 1 FROM information_schema.tables WHERE table_name=?",
1574
+ [table_name(empty_table)]).fetchone():
1575
+ con.execute(f"DELETE FROM {table_name(empty_table)} WHERE 1=1")
1576
+ cleared = True
1577
+ else:
1578
+ continue
1579
+ if sibling:
1580
+ sibling_mirror = table_name(sibling)
1581
+ sibling_types = _ensure(con, sibling_mirror, cols, rows, declared=declared,
1582
+ preserve_rows=first_load) if cols else {}
1583
+ if cols and not sibling_cleared and not sibling_plan["incremental"]:
1584
+ con.execute(f"DELETE FROM {sibling_mirror} WHERE 1=1")
1585
+ sibling_cleared = True
1586
+ if cols:
1587
+ sibling_written += write_window(sibling, cols, sibling_types, rows)
1588
  if table == "orders":
1589
  rows = _dedupe_orders(rows)
1590
  if table == "inventory":
 
1593
  cols.append("inventory_source")
1594
  if table == "pricing":
1595
  pricing_asins.extend(_pricing_asins(rows))
1596
+ types = _ensure(con, mirror, cols, rows, declared=declared,
1597
+ preserve_rows=first_load) if cols else {}
1598
+ # Explicit windows and first loads replace the mirror; incremental passes keep history.
1599
+ if not cleared and not plan["incremental"]:
1600
  con.execute(f"DELETE FROM {mirror} WHERE 1=1")
1601
  cleared = True
1602
+ if cols:
1603
+ written += write_window(table, cols, types, rows)
1604
+ if first_load:
1605
+ for reached in (table, sibling):
1606
+ if reached:
1607
+ record_backfill_floor(con, reached, w0)
1608
+ floors[reached] = w0
1609
+
1610
+ if first_load:
1611
+ landed.add((table, task_start, task_end))
1612
+ if any(next_table == table for next_table, _w0, _w1 in work[index + 1:]):
1613
+ continue
1614
 
 
1615
  if table == "pricing":
1616
+ if first_load:
1617
+ # Completion can be in another process/pass than the recent ASIN report.
1618
+ available = {row[1] for row in con.execute(f"PRAGMA table_info('{mirror}')").fetchall()}
1619
+ pricing_asins = list(dict.fromkeys(pricing_asins + [str(row[0])
1620
+ for col in ("child_asin", "parent_asin") if col in available
1621
+ for row in con.execute(f'SELECT DISTINCT "{col}" FROM {mirror} WHERE "{col}" IS NOT NULL').fetchall()]))
1622
  state_key = ENTITY_STATE_KEYS[table]
1623
  if not pricing_asins:
1624
  _record_state(con, state_key, "unproven", 0,
 
1654
  awd_rows = _awd_rows(inventory)
1655
  if awd_rows:
1656
  awd_cols = sorted({c for row in awd_rows for c in row})
1657
+ awd_types = _ensure(con, mirror, awd_cols, awd_rows, preserve_rows=first_load)
1658
+ if not cleared and not plan["incremental"]:
1659
  con.execute(f"DELETE FROM {mirror} WHERE 1=1")
1660
  cleared = True
1661
+ written += write_window(table, awd_cols, awd_types, awd_rows)
1662
  _record_state(con, state_key, "done", len(awd_rows))
1663
  operations["listInventory"] = {
1664
  "state": "done", "rows": len(awd_rows)}
 
1675
  column_count, total_rows = len(cols), written
1676
  report["tables"][table] = {
1677
  "rows": total_rows, "columns": column_count, "provenance": prov,
1678
+ "report": rtype, "window": plan["cause"], "incremental": plan["incremental"],
1679
+ "operations": operations}
1680
  _record_state(con, key, "done", total_rows)
1681
  _record_state(con, entity_key("sync_tick_" + table), "done", total_rows)
1682
+ if not any(v["state"] in ("refused", "throttled") for v in operations.values()):
1683
+ record_watermark(con, table, plan["end"], total_rows)
1684
  _sync_event("amazon.sync", tenant_key, table,
1685
  {"state": "done", "rows": total_rows,
1686
  "operations_ok": all(v["state"] == "done" for v in operations.values())},
1687
  rt, report, log)
1688
  log(f" {table:<16} {total_rows:>7,} rows {column_count:>3} cols {prov}")
1689
+ if sibling:
1690
+ sibling_mirror = table_name(sibling)
1691
+ try:
1692
+ sibling_columns = len(con.execute(f"PRAGMA table_info('{sibling_mirror}')").fetchall())
1693
+ sibling_total = int(con.execute(f"SELECT COUNT(*) FROM {sibling_mirror}").fetchone()[0])
1694
+ except Exception:
1695
+ sibling_columns, sibling_total = len(cols), sibling_written
1696
+ sibling_prov = amazon_schema.PROVENANCE.get(sibling, "measured_at_sync")
1697
+ report["tables"][sibling] = {
1698
+ "rows": sibling_total, "columns": sibling_columns, "provenance": sibling_prov,
1699
+ "report": rtype, "window": sibling_plan["cause"],
1700
+ "incremental": sibling_plan["incremental"], "operations": {}}
1701
+ _record_state(con, entity_key(sibling), "done", sibling_total)
1702
+ _record_state(con, entity_key("sync_tick_" + sibling), "done", sibling_total)
1703
+ record_watermark(con, sibling, sibling_plan["end"], sibling_total)
1704
+ _sync_event("amazon.sync", tenant_key, sibling,
1705
+ {"state": "done", "rows": sibling_total, "operations_ok": True},
1706
+ rt, report, log)
1707
+ log(f" {sibling:<16} {sibling_total:>7,} rows {sibling_columns:>3} cols {sibling_prov}")
1708
  except Exception as e: # noqa: BLE001
1709
+ # A failed pass retains its previous watermark so its window will be retried.
1710
  # ⚠ ONE TABLE'S REFUSAL IS NOT THE SYNC'S. A 403 on brand_analytics is R5's UNPROVEN
1711
  # ticket answering itself, and it must not cost the six tables that did work.
1712
+ problem = _sync_problem(e, table, operation, tenant_key, rt, report, log)
1713
+ failed.add(table)
1714
  report["tables"][table] = {"rows": 0, **problem}
1715
  _sync_event("amazon.sync", tenant_key, table,
1716
  {"state": problem["state"], "rows": 0}, rt, report, log)
1717
+ if sibling:
1718
+ problem = _sync_problem(e, sibling, "report_document", tenant_key, rt, report, log)
1719
+ report["tables"][sibling] = {"rows": 0, **problem}
1720
+ _sync_event("amazon.sync", tenant_key, sibling,
1721
+ {"state": problem["state"], "rows": 0}, rt, report, log)
1722
+ if first_load:
1723
+ remaining = sum(task not in landed for task in work)
1724
+ if settlement_remaining:
1725
+ remaining += settlement_remaining - 1 # Replace the discovery slot with known documents.
1726
+ # Keep healthy tables moving after an isolated refusal. Once only failed work remains,
1727
+ # stop automatic continuation instead of endlessly retrying the same vendor refusal.
1728
+ continuable = any(task not in landed and task[0] not in failed for task in work)
1729
+ state = ("partial" if remaining and continuable else
1730
+ "failed" if remaining or report["problems"] or report["audit_problems"] else "done")
1731
+ progress = {"state": state, "remaining": remaining,
1732
+ "etaSeconds": first_load_eta(remaining, burst=0),
1733
+ "cause": first_load_eta_cause(remaining), "backfillDays": DEFAULT_BACKFILL_DAYS}
1734
+ report.update(progress)
1735
+ report["firstLoad"] = dict(progress)
1736
+ _record_state(con, entity_key(FIRST_LOAD_END_KEY), state, detail=_iso(end))
1737
+ _record_state(con, entity_key(FIRST_LOAD_STATUS_KEY), state,
1738
+ detail=json.dumps({key: progress[key] for key in ("remaining", "etaSeconds")}))
1739
  report["finished"] = _iso(datetime.now(timezone.utc))
1740
  con.close()
1741
  return report
platform/harness/measure_filter.py CHANGED
@@ -302,7 +302,7 @@ def _base_topic(key):
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)
@@ -673,6 +673,10 @@ def resolve_values(key, window, today, team_id=None, allowed_pids=None, related=
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
@@ -682,7 +686,8 @@ def resolve_values(key, window, today, team_id=None, allowed_pids=None, related=
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
 
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) and related.refusal):
306
  return related
307
  try:
308
  pin = _relations.measure_pin(related)
 
673
  con = _sem._store_con()
674
  try:
675
  totals = _totals(con, key, window, today, team_id, related)
676
+ guard = None
677
+ metric = _sem.metrics().get(key, {})
678
+ if related is not None and not related.refusal and metric.get('agg') == 'ratio':
679
+ guard = _totals(con, metric['denominator'], window, today, team_id, related)
680
  finally:
681
  con.close()
682
  scale = ADMITTED.get(key, {}).get('input_scale') or 1.0
 
686
  # round(x, None) returns an int — exactly the pool's `_round` convention for money/counts.
687
  # The pin narrows SQL input only. Keep the caller's entire pool for zero reconstruction.
688
  return _related_answer(
689
+ {int(p): round(float(totals.get(p, 0.0)) * scale, nd) for p in universe
690
+ if guard is None or guard.get(p)}, related)
691
 
692
 
693
  #: The series channel's calendar buckets. `date_trunc` names in DuckDB; 'week' truncates to
platform/harness/runtime.py CHANGED
@@ -126,6 +126,8 @@ class TenantRuntime:
126
  tenant: object # harness.base.Tenant
127
  store_namespace: str = ""
128
  pool_cache: dict = field(default_factory=dict)
 
 
129
  #: EXIT-5 — the API adapter's memos for `core.measure_resolve` (the Streamlit adapter keeps
130
  #: its own in st.session_state). Bounded by the module's own clear-past-cap rule; keyed on
131
  #: (stamp, scope, pool identity, question) so nothing user-shaped lives in them.
 
126
  tenant: object # harness.base.Tenant
127
  store_namespace: str = ""
128
  pool_cache: dict = field(default_factory=dict)
129
+ # Names/edges only, bounded and revision-keyed by routes_grid; no row pools live here.
130
+ related_cache: dict = field(default_factory=dict)
131
  #: EXIT-5 — the API adapter's memos for `core.measure_resolve` (the Streamlit adapter keeps
132
  #: its own in st.session_state). Bounded by the module's own clear-past-cap rule; keyed on
133
  #: (stamp, scope, pool identity, question) so nothing user-shaped lives in them.
platform/harness/semantic.py CHANGED
@@ -827,13 +827,24 @@ def _scope_for_binding(store, scope_variant=None):
827
 
828
  def store_query(topic, measures, group_by=None, grain=None, date_from=None, date_to=None,
829
  team_id=None, filters=None, sort=None, limit=1000, exclude_services=False,
830
- filter_tree=None, filter_conj="and", today=None, scope_variant=None):
831
  """The semantic query over the tenant store — the engine behind the Analyst's
832
  run_semantic_query tool and the saved-view re-runner. All keys whitelisted against the model."""
833
  t = _model()["topics"].get(topic)
834
  if not t or "store" not in t:
835
  raise ModelError(f"topic {topic!r} has no store binding")
836
  s = t["store"]
 
 
 
 
 
 
 
 
 
 
 
837
  alias = s["alias"]
838
  dims = s.get("dims") or {}
839
  # ⭐ A GROUPED QUERY IS BOUNDED BY GROUPS, NOT BY ROWS — and the 5,000 row ceiling applied to
@@ -869,7 +880,9 @@ def store_query(topic, measures, group_by=None, grain=None, date_from=None, date
869
  foreign_vals = {}
870
  for k in foreign:
871
  sub = store_query(_model()["metrics"][k]["topic"], [k], date_from=date_from,
872
- date_to=date_to, team_id=team_id)
 
 
873
  foreign_vals[k] = sub["rows"][0][k] if sub["rows"] else 0
874
  if not base_keys: # purely foreign scalar request
875
  return {"topic": topic, "rows": [foreign_vals], "row_count": 1, "sql": "(nested)",
@@ -895,6 +908,9 @@ def store_query(topic, measures, group_by=None, grain=None, date_from=None, date
895
  select.append(f"{_measure_sql(_model()['metrics'][k], alias)} AS {k}")
896
 
897
  where = [_scope_for_binding(s, scope_variant)]
 
 
 
898
  # TYPE-CORRECT date bounds (the 2025-07-01 lesson): columns hold ISO strings in TWO shapes —
899
  # datetimes ('YYYY-MM-DD HH:MM:SS', sale date_order) and bare dates ('YYYY-MM-DD', GL date).
900
  # Lexical string comparison EXCLUDES the window's first day for bare dates ('2025-07-01' <
@@ -911,7 +927,7 @@ def store_query(topic, measures, group_by=None, grain=None, date_from=None, date
911
  # intersecting either with a `team_id` restates the same dimension a second time and the two
912
  # statements can disagree. Concretely, `channel_amazon` AND `team_id = 5` returns an empty
913
  # cell that reads as "this SKU sold nothing on Amazon" — a FALSE number, not a narrower one.
914
- if team_id and scope_variant is None:
915
  if not s.get("team_col"):
916
  raise ModelError(f"topic {topic!r} is company-level: it has no business-unit filter")
917
  where.append(f"{s['team_col']} = ?"); params.append(int(team_id))
@@ -1505,7 +1521,7 @@ def _one_binding_offer(topic, b, strict=False, ready=None):
1505
 
1506
 
1507
  def entity_measure_values(topic, keys, date_from=None, date_to=None, team_id=None,
1508
- exclude_services=False, offer=None):
1509
  """`{group key: {measure key: value}}` for an entity topic's lookback columns.
1510
 
1511
  ONE grouped query for all `keys` together — they share a topic, a scope and a window, so
@@ -1548,11 +1564,15 @@ def entity_measure_values(topic, keys, date_from=None, date_to=None, team_id=Non
1548
  groups.setdefault((by_key[k]["topic"], by_key[k]["dim"],
1549
  by_key[k].get("scope_variant")), []).append(k)
1550
  if len(groups) > 1:
1551
- merged = {}
 
1552
  for (_src, _dim, _variant), ks in groups.items():
1553
- for gk, cell in entity_measure_values(
1554
  topic, ks, date_from=date_from, date_to=date_to, team_id=team_id,
1555
- exclude_services=exclude_services, offer=offer).items():
 
 
 
1556
  merged.setdefault(gk, {}).update(cell)
1557
  return merged
1558
  (src, dim, scope_variant), want = next(iter(groups.items()))
@@ -1568,7 +1588,11 @@ def entity_measure_values(topic, keys, date_from=None, date_to=None, team_id=Non
1568
  base_of = {k: (by_key[k].get("base_key") or k) for k in want}
1569
  res = store_query(src, [base_of[k] for k in want], group_by=[dim], date_from=date_from,
1570
  date_to=date_to, team_id=team_id, exclude_services=exclude_services,
1571
- limit=MAX_GROUPS, scope_variant=scope_variant)
 
 
 
 
1572
  # ⛔ A TRUNCATED GROUP SET IS A WRONG ANSWER PER ROW, not a short list — the same refusal
1573
  # `rollup_sql.group_values` makes, for the same reason. Never write cells from one.
1574
  if res.get("truncated"):
 
827
 
828
  def store_query(topic, measures, group_by=None, grain=None, date_from=None, date_to=None,
829
  team_id=None, filters=None, sort=None, limit=1000, exclude_services=False,
830
+ filter_tree=None, filter_conj="and", today=None, scope_variant=None, related=None):
831
  """The semantic query over the tenant store — the engine behind the Analyst's
832
  run_semantic_query tool and the saved-view re-runner. All keys whitelisted against the model."""
833
  t = _model()["topics"].get(topic)
834
  if not t or "store" not in t:
835
  raise ModelError(f"topic {topic!r} has no store binding")
836
  s = t["store"]
837
+ pin_predicate, pin_params = None, []
838
+ if related is not None:
839
+ from core import relations
840
+ try:
841
+ pin = relations.measure_pin(related)
842
+ if pin.refusal:
843
+ raise relations.PinRefusal(pin.refusal['code'], pin.refusal['message'], pin.path)
844
+ pin_predicate, pin_params = pin.predicate(s)
845
+ except relations.PinRefusal as exc:
846
+ return {"topic": topic, "rows": [], "row_count": 0, "truncated": False,
847
+ "refusals": [exc.marker]}
848
  alias = s["alias"]
849
  dims = s.get("dims") or {}
850
  # ⭐ A GROUPED QUERY IS BOUNDED BY GROUPS, NOT BY ROWS — and the 5,000 row ceiling applied to
 
880
  foreign_vals = {}
881
  for k in foreign:
882
  sub = store_query(_model()["metrics"][k]["topic"], [k], date_from=date_from,
883
+ date_to=date_to, team_id=team_id, related=related)
884
+ if sub.get("refusals"):
885
+ return sub
886
  foreign_vals[k] = sub["rows"][0][k] if sub["rows"] else 0
887
  if not base_keys: # purely foreign scalar request
888
  return {"topic": topic, "rows": [foreign_vals], "row_count": 1, "sql": "(nested)",
 
908
  select.append(f"{_measure_sql(_model()['metrics'][k], alias)} AS {k}")
909
 
910
  where = [_scope_for_binding(s, scope_variant)]
911
+ if pin_predicate is not None:
912
+ where.append(f'({pin_predicate})')
913
+ params.extend(pin_params)
914
  # TYPE-CORRECT date bounds (the 2025-07-01 lesson): columns hold ISO strings in TWO shapes —
915
  # datetimes ('YYYY-MM-DD HH:MM:SS', sale date_order) and bare dates ('YYYY-MM-DD', GL date).
916
  # Lexical string comparison EXCLUDES the window's first day for bare dates ('2025-07-01' <
 
927
  # intersecting either with a `team_id` restates the same dimension a second time and the two
928
  # statements can disagree. Concretely, `channel_amazon` AND `team_id = 5` returns an empty
929
  # cell that reads as "this SKU sold nothing on Amazon" — a FALSE number, not a narrower one.
930
+ if team_id and (scope_variant is None or related is not None):
931
  if not s.get("team_col"):
932
  raise ModelError(f"topic {topic!r} is company-level: it has no business-unit filter")
933
  where.append(f"{s['team_col']} = ?"); params.append(int(team_id))
 
1521
 
1522
 
1523
  def entity_measure_values(topic, keys, date_from=None, date_to=None, team_id=None,
1524
+ exclude_services=False, offer=None, related=None):
1525
  """`{group key: {measure key: value}}` for an entity topic's lookback columns.
1526
 
1527
  ONE grouped query for all `keys` together — they share a topic, a scope and a window, so
 
1564
  groups.setdefault((by_key[k]["topic"], by_key[k]["dim"],
1565
  by_key[k].get("scope_variant")), []).append(k)
1566
  if len(groups) > 1:
1567
+ from core import relations
1568
+ merged = relations.MeasureAnswer() if related is not None else {}
1569
  for (_src, _dim, _variant), ks in groups.items():
1570
+ answer = entity_measure_values(
1571
  topic, ks, date_from=date_from, date_to=date_to, team_id=team_id,
1572
+ exclude_services=exclude_services, offer=offer, related=related)
1573
+ if related is not None:
1574
+ merged.refusals.extend(getattr(answer, 'refusals', ()))
1575
+ for gk, cell in answer.items():
1576
  merged.setdefault(gk, {}).update(cell)
1577
  return merged
1578
  (src, dim, scope_variant), want = next(iter(groups.items()))
 
1588
  base_of = {k: (by_key[k].get("base_key") or k) for k in want}
1589
  res = store_query(src, [base_of[k] for k in want], group_by=[dim], date_from=date_from,
1590
  date_to=date_to, team_id=team_id, exclude_services=exclude_services,
1591
+ limit=MAX_GROUPS, scope_variant=scope_variant, related=related)
1592
+ if res.get("refusals"):
1593
+ from core import relations
1594
+ return relations.MeasureAnswer(refusals=[dict(marker, measure=k)
1595
+ for marker in res['refusals'] for k in want])
1596
  # ⛔ A TRUNCATED GROUP SET IS A WRONG ANSWER PER ROW, not a short list — the same refusal
1597
  # `rollup_sql.group_values` makes, for the same reason. Never write cells from one.
1598
  if res.get("truncated"):
platform/harness/windows.py CHANGED
@@ -40,6 +40,8 @@ DESIGN NOTES THAT ARE EASY TO GET WRONG
40
  "all time" would widen a filter while still reporting an authoritative count.
41
  """
42
  import datetime as _dt
 
 
43
 
44
  #: Every window kind the UI may offer. Mirrors WINDOW_KINDS in customer-grid/windows.ts;
45
  #: verify_windows.py asserts the two lists are identical, because a kind the client can emit and
@@ -191,6 +193,91 @@ def _parse_date(v):
191
  return None
192
 
193
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
194
  def normalize(spec):
195
  """Coerce an untrusted window spec to `{kind, n?, from?, to?}` or None.
196
 
 
40
  "all time" would widen a filter while still reporting an authoritative count.
41
  """
42
  import datetime as _dt
43
+ import re
44
+ import math
45
 
46
  #: Every window kind the UI may offer. Mirrors WINDOW_KINDS in customer-grid/windows.ts;
47
  #: verify_windows.py asserts the two lists are identical, because a kind the client can emit and
 
193
  return None
194
 
195
 
196
+ # Sheet Ending metadata belongs to the binding period, never to a window spec.
197
+ ENDING_KINDS = ("today", "yesterday", "last_week", "last_month", "last_quarter",
198
+ "last_year", "fixed", "cell")
199
+ ENDING_LABELS = dict(zip(ENDING_KINDS, ("Today (live)", "Yesterday", "End of last week",
200
+ "End of last month", "End of last quarter", "End of last year", "A fixed date", "From a cell")))
201
+ TO_DATE_KINDS = ("ytd", "ytd_last_year", "this_month", "this_quarter")
202
+ ENDING_STEPS = ("day", "week", "month", "quarter", "year")
203
+
204
+
205
+ def ending_step_default(kind):
206
+ return "quarter" if kind == "this_quarter" else "month"
207
+
208
+
209
+ def ending_date(value):
210
+ """A real ISO day only. No truncation, calendar rollover, or blank fallback."""
211
+ if not isinstance(value, str) or not re.fullmatch(r"[0-9]{4}-[0-9]{2}-[0-9]{2}", value.strip()):
212
+ return None
213
+ d = _parse_date(value)
214
+ return _iso(d) if d else None
215
+
216
+
217
+ def resolve_ending(mode, value, today, step="month", offset=0):
218
+ """Inclusive ending date; cell values are supplied by the caller's trusted read."""
219
+ d = _parse_date(today)
220
+ if d is None:
221
+ raise ValueError("Ending needs a valid today date")
222
+ if mode not in ENDING_KINDS or step not in ENDING_STEPS:
223
+ return None
224
+ if isinstance(offset, bool) or not isinstance(offset, int) or offset < 0:
225
+ return None
226
+ if mode in ("fixed", "cell"):
227
+ parsed = ending_date(value)
228
+ if parsed is None:
229
+ return None
230
+ end = _parse_date(parsed)
231
+ elif mode == "today":
232
+ end = d
233
+ elif mode == "yesterday":
234
+ end = d - _dt.timedelta(days=1)
235
+ elif mode == "last_week":
236
+ end = d - _dt.timedelta(days=d.weekday() + 1)
237
+ elif mode == "last_month":
238
+ end = _month_start(d) - _dt.timedelta(days=1)
239
+ elif mode == "last_quarter":
240
+ end = _quarter_start(d) - _dt.timedelta(days=1)
241
+ else:
242
+ end = _dt.date(d.year - 1, 12, 31)
243
+ try:
244
+ if step in ("day", "week"):
245
+ end += _dt.timedelta(days=offset * (7 if step == "week" else 1))
246
+ else:
247
+ end = _shift_months(end, offset * {"month": 1, "quarter": 3, "year": 12}[step])
248
+ return _iso(end)
249
+ except (ValueError, OverflowError):
250
+ return None
251
+
252
+
253
+ def ending_cell_date(value, date_system="1900"):
254
+ """Sheet dates may be ISO days or Excel serials in the workbook's declared epoch."""
255
+ if not isinstance(value, (int, float)) or isinstance(value, bool):
256
+ return ending_date(value)
257
+ if not math.isfinite(value) or value < (0 if date_system == "1904" else 1):
258
+ return None
259
+ days = math.floor(value)
260
+ if date_system != "1904" and days == 60:
261
+ return None # Excel's fictional February 29, 1900 is not a calendar date.
262
+ epoch = (_dt.date(1904, 1, 1) if date_system == "1904" else
263
+ _dt.date(1899, 12, 31) if days < 60 else _dt.date(1899, 12, 30))
264
+ try:
265
+ return _iso(epoch + _dt.timedelta(days=days))
266
+ except (ValueError, OverflowError):
267
+ return None
268
+
269
+
270
+ def ending_bounds(kind, mode, value, today, step="month", offset=0):
271
+ """Keep the kind's own start. An ending before it refuses instead of reversing bounds."""
272
+ if kind not in TO_DATE_KINDS:
273
+ return None
274
+ end = resolve_ending(mode, value, today, step, offset)
275
+ if end is None:
276
+ return None
277
+ start = resolve({"kind": kind}, today)[0]
278
+ return (start, end) if start <= end else None
279
+
280
+
281
  def normalize(spec):
282
  """Coerce an untrusted window spec to `{kind, n?, from?, to?}` or None.
283
 
platform/modules/product_data.py CHANGED
@@ -1431,9 +1431,72 @@ def validate(team_id=None, t=None):
1431
  checks.extend(validate_price_and_unit_cells(rows))
1432
  checks.extend(validate_stock_measures(t=t))
1433
  checks.extend(validate_fba(rows))
 
1434
  return checks
1435
 
1436
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1437
  def fba_quant_oracle():
1438
  """`(warehouse | None, {product_id: units}, detail)` — the FBA column's INDEPENDENT oracle.
1439
 
 
1431
  checks.extend(validate_price_and_unit_cells(rows))
1432
  checks.extend(validate_stock_measures(t=t))
1433
  checks.extend(validate_fba(rows))
1434
+ checks.extend(validate_linked_metric(team_id=team_id))
1435
  return checks
1436
 
1437
 
1438
+ def validate_linked_metric(customer_id=None, product_id=None, team_id=None,
1439
+ date_from=None, date_to=None):
1440
+ """Reconcile one customer/product revenue cell to an independent live Odoo aggregate.
1441
+
1442
+ The semantic result uses the shipping pin predicate and entity measure resolver. The
1443
+ oracle uses Odoo's real partner/product ids and read_group, never the mirror's totals.
1444
+ A live/mirror gap is reported exactly and fails; sync and rerun to distinguish lag.
1445
+ Explicit ids/window make the leg reproducible without rebuilding the product pool.
1446
+ """
1447
+ from core import relations
1448
+ from harness import semantic as sem, datastore as ds
1449
+
1450
+ name = 'linked customer/product revenue reconciles to independent Odoo'
1451
+ try:
1452
+ con = ds.ro_cursor()
1453
+ try:
1454
+ parts, params = ["o.state IN ('sale','done')"], []
1455
+ for expression, value in [('l.order_partner_id', customer_id),
1456
+ ('l.product_id', product_id), ('o.team_id', team_id)]:
1457
+ if value is not None:
1458
+ parts.append(f'{expression} = ?')
1459
+ params.append(int(value))
1460
+ sample = con.execute(
1461
+ "SELECT l.order_partner_id, l.product_id, "
1462
+ "COALESCE(NULLIF(p.default_code, ''), 'pid:' || CAST(p.id AS VARCHAR)), "
1463
+ "CAST(o.date_order AS DATE) FROM sale_order_line l "
1464
+ "JOIN sale_order o ON o.id=l.order_id JOIN product_product p ON p.id=l.product_id "
1465
+ f"WHERE {' AND '.join(parts)} ORDER BY o.date_order DESC, l.id LIMIT 1", params).fetchone()
1466
+ finally:
1467
+ con.close()
1468
+ if not sample:
1469
+ return [dict(check=name, ours=None, theirs=None, ok=False,
1470
+ detail='No confirmed customer/product sample is available. Sync the sales source and rerun.')]
1471
+ customer_id, product_id, code, day = sample
1472
+ date_from, date_to = date_from or str(day), date_to or str(day)
1473
+ pin = relations.MeasurePin(['validation'],
1474
+ {'customer_data': [{'pid': customer_id}],
1475
+ 'product_data': [{'product_id': product_id}]},
1476
+ {'sale_order_line': [
1477
+ dict(table='customer_data', column='pid', sql='{alias}.order_partner_id'),
1478
+ dict(table='product_data', column='product_id', sql='{alias}.product_id')]},
1479
+ required=('customer_data', 'product_data'))
1480
+ answer = sem.entity_measure_values('odoo_products', ['revenue'], date_from=date_from,
1481
+ date_to=date_to, team_id=team_id, related=pin)
1482
+ if getattr(answer, 'refusals', ()):
1483
+ return [dict(check=name, ours=None, theirs=None, ok=False, detail=answer.refusals)]
1484
+ ours = answer.get(code, {}).get('revenue', 0)
1485
+ domain = O.sale_line_domain(date_from, date_to, team_id=team_id, all_channels=True,
1486
+ extra=[('order_partner_id', '=', customer_id), ('product_id', '=', product_id)])
1487
+ aggregate = O.get_odoo().read_group('sale.order.line', domain,
1488
+ ['price_subtotal:sum'], [], lazy=False)
1489
+ theirs = sum(r.get('price_subtotal') or 0 for r in aggregate)
1490
+ delta = round(ours - theirs, 2)
1491
+ return [dict(check=name, ours=ours, theirs=theirs, ok=abs(delta) < 0.005,
1492
+ detail=dict(customer=customer_id, product=product_id, team_id=team_id,
1493
+ date_from=date_from, date_to=date_to, difference=delta,
1494
+ recommendation='If different, sync sales and rerun this exact sample; investigate any remaining difference.'))]
1495
+ except Exception as exc:
1496
+ return [dict(check=name, ours=None, theirs=None, ok=False,
1497
+ detail=f'Validation could not read both sources ({type(exc).__name__}). Check source readiness and rerun.')]
1498
+
1499
+
1500
  def fba_quant_oracle():
1501
  """`(warehouse | None, {product_id: units}, detail)` — the FBA column's INDEPENDENT oracle.
1502
 
platform/modules/sheet.py CHANGED
@@ -33,20 +33,21 @@ from __future__ import annotations
33
 
34
  import datetime
35
  import re
 
 
 
36
 
37
  #: C2's aggregate vocabulary. W59-T14 resolves the `metric_key` arm through a Metric column,
38
  #: using only the catalogue's declared fold: see `metric_key_fold` and its additivity guard.
39
  AGGREGATE_FNS = ("sum", "count", "avg", "min", "max")
40
 
41
- #: ⭐ R9's PERIOD (wave 51, W51-T21). The three units a bound cell can be pinned to, and the month
42
- #: its window starts in. `web/src/sheet/types.ts` carries the same three names.
43
- PERIOD_UNITS = ("month", "quarter", "year")
44
 
45
- #: `YYYY-MM`. A period starts in a MONTH whatever its unit, because a quarter and a year are both
46
- #: named by the month they open on, and one spelling means a copied cell cannot mean two things.
47
  _PERIOD_START = re.compile(r"^\d{4}-(0[1-9]|1[0-2])$")
48
 
49
- #: Literal inclusive endpoints of a frozen calendar period, spelled `YYYY-MM-DD`.
50
  _PERIOD_DAY = re.compile(r"^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$")
51
 
52
  #: A `period.ref` points at a cell that holds the period, so it is a plain A1 address with no `$`,
@@ -72,7 +73,17 @@ REFUSALS = {
72
  "binding_invalid": "That cell's source is not set up correctly.",
73
  "aggregate_unknown": "{subject} is not an aggregate this cell can compute.",
74
  "field_unknown": "{subject} is not a column on this database.",
75
- "period_invalid": "{subject} is not a period this cell can use.",
 
 
 
 
 
 
 
 
 
 
76
  # ── W53-T13's two refusals, and the reason each of them is NOT `field_unknown` ────────────
77
  #
78
  # ⛔⛔ `field_unknown`'s sentence is "{subject} is not a column on this database", and for a
@@ -140,6 +151,10 @@ class SheetRefusal(Exception):
140
  self.detail = str(detail or "")
141
  self.message = template.format(subject=self.subject or "this database",
142
  detail=self.detail)
 
 
 
 
143
  super().__init__(self.message)
144
 
145
 
@@ -150,7 +165,7 @@ def clean_period(raw):
150
  True so freezing and unfreezing returns to the identical rolling period already stored.
151
 
152
  ⛔ AN UNKNOWN UNIT OR A MALFORMED START IS REFUSED BY NAME, and that is not the same call as
153
- the cosmetic keys next door. A period decides WHICH ROWS ARE COUNTED. Dropping `unit: "week"`
154
  would answer for every row the binding can see and hand back a bigger number with nobody told,
155
  which is standing rule 1's second sentence turned into a defect.
156
 
@@ -174,6 +189,39 @@ def clean_period(raw):
174
  return None
175
  out = {}
176
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
177
  unit = str(raw.get("unit") or "").strip().lower()
178
  if unit:
179
  if unit not in PERIOD_UNITS:
@@ -182,8 +230,16 @@ def clean_period(raw):
182
 
183
  start = str(raw.get("start") or "").strip()
184
  if start:
185
- if not _PERIOD_START.match(start):
 
186
  raise SheetRefusal("period_invalid", start)
 
 
 
 
 
 
 
187
  out["start"] = start
188
 
189
  if raw.get("frozen") is True:
@@ -226,13 +282,11 @@ def clean_period(raw):
226
  return out
227
 
228
 
229
- #: ⭐ R7's PERIOD ARITHMETIC, spelled once. How many months each unit spans, which is the whole
230
- #: difference between the three: a period is always named by the month it OPENS on (`clean_period`
231
- #: enforces the `YYYY-MM` spelling for that reason), so the unit only decides where it closes.
232
  PERIOD_MONTHS = {"month": 1, "quarter": 3, "year": 12}
233
 
234
 
235
- def period_window(period):
236
  """⭐⭐ R7 — a bound cell's PERIOD as a `harness.windows` CUSTOM window, or None.
237
 
238
  OWNER, R7: *"must also be bounded by date time lookup"*. A Metric column carries its OWN
@@ -270,14 +324,36 @@ def period_window(period):
270
  """
271
  if not isinstance(period, dict):
272
  return None
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
273
  if period.get("frozen") is True and period.get("from") and period.get("to"):
274
  return {"kind": "custom", "from": period["from"], "to": period["to"]}
275
  if period.get("window") is not None:
276
  return period["window"]
277
  start = str(period.get("start") or "").strip()
 
 
 
 
 
 
 
 
278
  if not _PERIOD_START.match(start):
279
  return None
280
- unit = str(period.get("unit") or "month").strip().lower()
281
  months = PERIOD_MONTHS.get(unit)
282
  if not months:
283
  return None
@@ -289,10 +365,8 @@ def period_window(period):
289
  return {"kind": "custom", "from": f"{start}-01", "to": last.isoformat()}
290
 
291
 
292
- #: The column types `harness/filter_sql.py::NUMERIC_TYPES` compiles as numbers AND
293
- #: `odoo_relational._REGISTRY_COL_TYPE` materialises as a number. The two lists have to agree or a
294
- #: column is stored as one thing and compared as another.
295
- MIRROR_NUMERIC_TYPES = ("currency", "int", "pct")
296
 
297
  #: ⭐ THE COMPUTED KINDS THE MIRROR HAS TO BE TOLD ABOUT. `_REGISTRY_COL_TYPE` maps the ordinary
298
  #: field types and falls back to VARCHAR for everything else, so a `metric` or `rating` column
@@ -504,8 +578,34 @@ def clean_on_drag(raw):
504
  down = raw.get("down")
505
  if isinstance(down, dict) and str(down.get("field") or "").strip():
506
  out_down = {"field": str(down["field"]).strip()}
 
 
507
  else:
508
  out_down = DRAG_DOWN_NONE
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
509
  return {"across": across, "down": out_down}
510
 
511
 
@@ -527,6 +627,66 @@ def clean_adopted_from(raw):
527
  return out or None
528
 
529
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
530
  def clean_binding(raw):
531
  """Normalize a C2 `Binding`, or raise `SheetRefusal`.
532
 
@@ -595,6 +755,106 @@ def clean_binding(raw):
595
  return out
596
 
597
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
598
  def filter_columns_named(nodes):
599
  """Every `colId` a filter tree names, at any depth, including a right-hand column reference.
600
 
@@ -682,6 +942,27 @@ def compile_scope(nodes, conj, columns, *, today=None, cohort_sets=None):
682
  is what a relative date condition needs, and it is exactly the value R14's `period.ref` feeds.
683
  """
684
  from harness.filter_sql import compile_filter_tree
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
685
  return compile_filter_tree(list(nodes or ()), conj=conj or "and", columns=columns or {},
686
  today=today, cohort_sets=cohort_sets)
687
 
@@ -714,6 +995,9 @@ def aggregate_sql(spec, aggregate, columns):
714
  col = (columns or {}).get(key)
715
  if not col or not col.get("sql"):
716
  raise SheetRefusal("field_unknown", key or "That column")
 
 
 
717
  return f"{fn.upper()}({col['sql']})", key
718
 
719
 
@@ -800,6 +1084,31 @@ def build_ids_query(spec, columns, *, scope_nodes, scope_conj, wall_nodes=None,
800
 
801
  # ── W49-T10: the dependents provider (contract C3) ───────────────────────────────────────────
802
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
803
  def sheet_dependents(st, target):
804
  """Which Sheet cells depend on `target`, as C3 `Dependent` rows.
805
 
@@ -823,35 +1132,37 @@ def sheet_dependents(st, target):
823
  if not kind or not key:
824
  return []
825
 
826
- hits, unreadable = [], 0
827
  for row in sheet_store.list_workbooks(st):
828
  try:
829
  book = sheet_store.get_workbook(st, row["id"])
830
  except sheet_store.SheetRefusal:
831
- unreadable += 1
 
 
 
 
 
 
 
832
  continue
833
  for tab in book.get("sheets") or ():
834
  for addr, cell in (tab.get("cells") or {}).items():
835
  if _cell_depends_on(cell, kind, key, database):
836
- hits.append(f"{book.get('name') or book.get('id')} / "
837
- f"{tab.get('name') or tab.get('id')}!{addr}")
838
-
839
- out = []
840
- if hits:
841
- # ⛔ NO `label` KEY, DELIBERATELY. `dependents.dependents_report` defaults it to
842
- # `noun("sheet_cell", count)`, which AGREES IN NUMBER; a static "Sheet cells" renders
843
- # the user-facing refusal "Leads is used by 1 Sheet cells". Enforced, not merely
844
- # written down: `verify_shared_views.py`'s `(W49-T11b)` leg reds on a static label.
845
- out.append({"kind": "sheet_cell", "count": len(hits), "ids": hits})
846
- if unreadable:
847
- # ⚠ REPORTED, never folded into the count above. "3 cells depend on this" and "3 cells
848
- # depend on this and 2 workbooks could not be read" are different answers, and only the
849
- # second one lets a person decide whether to proceed.
850
- out.append({"kind": "sheet_unreadable",
851
- "label": ("Workbook that could not be read" if unreadable == 1
852
- else "Workbooks that could not be read"),
853
- "count": unreadable, "ids": []})
854
- return out
855
 
856
 
857
  # ── W49-T11 (combine-owned): register the provider with the dependents registry ────────────
 
33
 
34
  import datetime
35
  import re
36
+ from urllib.parse import urlencode
37
+
38
+ from harness.filter_sql import NUMERIC_TYPES as MIRROR_NUMERIC_TYPES
39
 
40
  #: C2's aggregate vocabulary. W59-T14 resolves the `metric_key` arm through a Metric column,
41
  #: using only the catalogue's declared fold: see `metric_key_fold` and its additivity guard.
42
  AGGREGATE_FNS = ("sum", "count", "avg", "min", "max")
43
 
44
+ #: Calendar units shared with `web/src/sheet/types.ts`; W60-T06 adds daily and weekly summaries.
45
+ PERIOD_UNITS = ("day", "week", "month", "quarter", "year")
 
46
 
47
+ #: Month, Quarter and Year keep their opening-month encoding unchanged.
 
48
  _PERIOD_START = re.compile(r"^\d{4}-(0[1-9]|1[0-2])$")
49
 
50
+ #: Day/Week starts and inclusive endpoints of a frozen period, spelled `YYYY-MM-DD`.
51
  _PERIOD_DAY = re.compile(r"^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$")
52
 
53
  #: A `period.ref` points at a cell that holds the period, so it is a plain A1 address with no `$`,
 
73
  "binding_invalid": "That cell's source is not set up correctly.",
74
  "aggregate_unknown": "{subject} is not an aggregate this cell can compute.",
75
  "field_unknown": "{subject} is not a column on this database.",
76
+ "period_invalid": "{subject} is not a period this cell can use. "
77
+ "Choose a valid start for the selected period unit.",
78
+ "ending_invalid": "Ending {subject} cannot be used. Choose a valid ending date.",
79
+ "ending_not_supported": "{subject} does not support an Ending. Choose year to date, last year "
80
+ "to date, this month or this quarter.",
81
+ "ending_cell_unreadable": "Ending from cell {subject} cannot be read. "
82
+ "Use a cell containing a date in YYYY-MM-DD format.",
83
+ "filter_cell_unreadable": "Filter value from cell {subject} cannot be read. "
84
+ "Choose a readable cell containing one nonblank value, or type the filter value.",
85
+ "linked_filter_unreadable": "Linked field {subject} cannot be filtered because {detail} "
86
+ "Choose a readable field through an available link, or ask an administrator to restore access.",
87
  # ── W53-T13's two refusals, and the reason each of them is NOT `field_unknown` ────────────
88
  #
89
  # ⛔⛔ `field_unknown`'s sentence is "{subject} is not a column on this database", and for a
 
151
  self.detail = str(detail or "")
152
  self.message = template.format(subject=self.subject or "this database",
153
  detail=self.detail)
154
+ if code in ("ending_invalid", "ending_cell_unreadable", "filter_cell_unreadable") and self.detail:
155
+ verb = "used" if code == "ending_invalid" else "read"
156
+ self.message = self.message.replace(f"cannot be {verb}.",
157
+ f"cannot be {verb} because {self.detail}")
158
  super().__init__(self.message)
159
 
160
 
 
165
  True so freezing and unfreezing returns to the identical rolling period already stored.
166
 
167
  ⛔ AN UNKNOWN UNIT OR A MALFORMED START IS REFUSED BY NAME, and that is not the same call as
168
+ the cosmetic keys next door. A period decides WHICH ROWS ARE COUNTED. Dropping `unit: "fortnight"`
169
  would answer for every row the binding can see and hand back a bigger number with nobody told,
170
  which is standing rule 1's second sentence turned into a defect.
171
 
 
189
  return None
190
  out = {}
191
 
192
+ # An Ending is a period modifier. Validate before the legacy dialect can discard it.
193
+ if "ending" in raw:
194
+ from harness import windows as W
195
+ window = W.normalize(raw.get("window"))
196
+ kind = (window or {}).get("kind")
197
+ if kind not in W.TO_DATE_KINDS:
198
+ raise SheetRefusal("ending_not_supported", kind or "This period")
199
+ ending = raw["ending"]
200
+ mode = ending.get("kind") if isinstance(ending, dict) else None
201
+ if mode not in W.ENDING_KINDS:
202
+ raise SheetRefusal("ending_invalid", str(mode or "selection"), "the choice is unknown.")
203
+ step = raw.get("endingStep", W.ending_step_default(kind))
204
+ offset = raw.get("endingOffset", 0)
205
+ if step not in W.ENDING_STEPS or isinstance(offset, bool) or not isinstance(offset, int) or offset < 0:
206
+ raise SheetRefusal("ending_invalid", "step", "its size or copy offset is invalid.")
207
+ out = {"window": window, "ending": {"kind": mode}, "endingStep": step}
208
+ if offset:
209
+ out["endingOffset"] = offset
210
+ if raw.get("locked") is True:
211
+ out["locked"] = True
212
+ if mode == "fixed":
213
+ day = W.ending_date(ending.get("date"))
214
+ if day is None:
215
+ raise SheetRefusal("ending_invalid", "fixed date", "it is not a real ISO date.")
216
+ out["ending"]["date"] = day
217
+ if mode == "cell":
218
+ ref = str(raw.get("ref") or "").strip()
219
+ # Preserve sheet names and dollar anchors. The read layer validates the target.
220
+ if not re.fullmatch(r"(?:(?:'([^']|'')+'|[^'!]+)!)?\$?[A-Za-z]{1,3}\$?[1-9][0-9]{0,6}", ref):
221
+ raise SheetRefusal("ending_cell_unreadable", ref or "(blank)", "its reference is invalid.")
222
+ out["ref"] = ref
223
+ return out
224
+
225
  unit = str(raw.get("unit") or "").strip().lower()
226
  if unit:
227
  if unit not in PERIOD_UNITS:
 
230
 
231
  start = str(raw.get("start") or "").strip()
232
  if start:
233
+ pattern = _PERIOD_DAY if unit in ("day", "week") else _PERIOD_START
234
+ if not pattern.fullmatch(start):
235
  raise SheetRefusal("period_invalid", start)
236
+ if unit in ("day", "week"):
237
+ try:
238
+ day = datetime.date.fromisoformat(start)
239
+ except ValueError:
240
+ raise SheetRefusal("period_invalid", start)
241
+ if unit == "week":
242
+ start = (day - datetime.timedelta(days=day.weekday())).isoformat()
243
  out["start"] = start
244
 
245
  if raw.get("frozen") is True:
 
282
  return out
283
 
284
 
285
+ #: Month-based periods retain their existing arithmetic. Day/Week advance in calendar days.
 
 
286
  PERIOD_MONTHS = {"month": 1, "quarter": 3, "year": 12}
287
 
288
 
289
+ def period_window(period, today=None, *, cell_date=None):
290
  """⭐⭐ R7 — a bound cell's PERIOD as a `harness.windows` CUSTOM window, or None.
291
 
292
  OWNER, R7: *"must also be bounded by date time lookup"*. A Metric column carries its OWN
 
324
  """
325
  if not isinstance(period, dict):
326
  return None
327
+ if "ending" in period:
328
+ from harness import windows as W
329
+ period = clean_period(period)
330
+ kind = period["window"]["kind"]
331
+ mode = period["ending"]["kind"]
332
+ value = cell_date if mode == "cell" else period["ending"].get("date")
333
+ if mode == "cell" and W.ending_date(value) is None:
334
+ raise SheetRefusal("ending_cell_unreadable", period.get("ref"),
335
+ "it has no readable date.")
336
+ bounds = W.ending_bounds(kind, mode, value, today or datetime.date.today(),
337
+ period["endingStep"], period.get("endingOffset", 0))
338
+ if bounds is None:
339
+ raise SheetRefusal("ending_invalid", W.ENDING_LABELS[mode],
340
+ "it falls before the lookback starts or outside the supported calendar.")
341
+ return {"kind": "custom", "from": bounds[0], "to": bounds[1]}
342
  if period.get("frozen") is True and period.get("from") and period.get("to"):
343
  return {"kind": "custom", "from": period["from"], "to": period["to"]}
344
  if period.get("window") is not None:
345
  return period["window"]
346
  start = str(period.get("start") or "").strip()
347
+ unit = str(period.get("unit") or "month").strip().lower()
348
+ if unit in ("day", "week"):
349
+ cleaned = clean_period(period)
350
+ if not cleaned or not cleaned.get("start"):
351
+ return None
352
+ first = datetime.date.fromisoformat(cleaned["start"])
353
+ last = first + datetime.timedelta(days=6 if unit == "week" else 0)
354
+ return {"kind": "custom", "from": first.isoformat(), "to": last.isoformat()}
355
  if not _PERIOD_START.match(start):
356
  return None
 
357
  months = PERIOD_MONTHS.get(unit)
358
  if not months:
359
  return None
 
365
  return {"kind": "custom", "from": f"{start}-01", "to": last.isoformat()}
366
 
367
 
368
+ #: MIRROR_NUMERIC_TYPES is imported from the SQL compiler above, so admission and comparison
369
+ #: use one declaration. verify_sheet also checks the evaluator's documented client-only types.
 
 
370
 
371
  #: ⭐ THE COMPUTED KINDS THE MIRROR HAS TO BE TOLD ABOUT. `_REGISTRY_COL_TYPE` maps the ordinary
372
  #: field types and falls back to VARCHAR for everything else, so a `metric` or `rating` column
 
578
  down = raw.get("down")
579
  if isinstance(down, dict) and str(down.get("field") or "").strip():
580
  out_down = {"field": str(down["field"]).strip()}
581
+ if down.get("mode") in ("value", "presence", "member"):
582
+ out_down["mode"] = down["mode"]
583
  else:
584
  out_down = DRAG_DOWN_NONE
585
+ if isinstance(raw.get("steps"), list):
586
+ steps = []
587
+ for step in raw["steps"]:
588
+ if not isinstance(step, dict):
589
+ continue
590
+ field = step.get("field")
591
+ if not isinstance(field, str) or not field.strip():
592
+ continue
593
+ if step.get("axis") not in ("across", "down"):
594
+ continue
595
+ if "size" in step and step["size"] not in ("day", "week", "month", "quarter", "year"):
596
+ continue
597
+ cleaned = {"field": field.strip(), "axis": step["axis"]}
598
+ if step.get("mode") in ("value", "presence", "member"):
599
+ cleaned["mode"] = step["mode"]
600
+ if "size" in step:
601
+ cleaned["size"] = step["size"]
602
+ steps.append(cleaned)
603
+ first_down = next((step for step in steps if step["axis"] == "down"), None)
604
+ out_down = ({key: first_down[key] for key in ("field", "mode") if key in first_down}
605
+ if first_down else DRAG_DOWN_NONE)
606
+ across = "period" if any(step["axis"] == "across" and step["field"] in
607
+ ("__period", "__ending") for step in steps) else "none"
608
+ return {"across": across, "down": out_down, "steps": steps}
609
  return {"across": across, "down": out_down}
610
 
611
 
 
627
  return out or None
628
 
629
 
630
+ def validate(date_from, date_to, observed, *, team_id, partner_ids=None):
631
+ """Reconcile T08's four sections to live Odoo, at the exact displayed scope.
632
+
633
+ sales.validate owns the broader sales-module reconciliation. Its public API
634
+ takes a YTD as-of, not arbitrary weeks or customer sets. Reuse its order and
635
+ line domains here for the template's narrower independent checks; never use
636
+ customer_data.validate (which validates addresses).
637
+ """
638
+ import math
639
+ from core import odoo as O
640
+ from modules import sales
641
+
642
+ first, last = datetime.date.fromisoformat(date_from), datetime.date.fromisoformat(date_to)
643
+ if first > last or team_id not in O.active_team_ids():
644
+ raise ValueError("Choose a valid date range and one permitted business unit.")
645
+ # The template's basis is fixed even if the caller's dashboard is in Invoice mode.
646
+ domain = [clause for clause in sales.order_domain(date_from, date_to, team_id, partner_ids)
647
+ if clause[0] != "invoice_status"]
648
+ lines = [clause for clause in O.sale_line_domain(date_from, date_to, team_id,
649
+ partner_ids=partner_ids)
650
+ if clause[0] != "order_id.invoice_status"]
651
+ revenue = O.sum_field("sale.order", domain, "amount_untaxed")
652
+ invoiced = O.sum_field("sale.order", domain + [("invoice_status", "=", "invoiced")], "amount_untaxed")
653
+ count = O.get_odoo().search_count("sale.order", domain)
654
+ expected = {"invoiced_sales": invoiced, "confirmed_sales": revenue, "order_count": count,
655
+ "average_order_value": revenue / count if count else 0.0}
656
+ checks = []
657
+ for key, value in expected.items():
658
+ actual = observed.get(key)
659
+ valid = isinstance(actual, (float, int)) and not isinstance(actual, bool) and math.isfinite(actual)
660
+ checks.append({"check": key, "a": actual, "b": value,
661
+ "gap": actual - value if valid else None,
662
+ "ok": valid and abs(actual - value) <= (0 if key == "order_count" else 0.01)})
663
+ for label, order_value, extra in (("Confirmed order and line revenue", revenue, []),
664
+ ("Fully invoiced order and line revenue", invoiced,
665
+ [("order_id.invoice_status", "=", "invoiced")])):
666
+ line_value = O.sum_field("sale.order.line", lines + extra, "price_subtotal")
667
+ checks.append({"check": label, "a": order_value, "b": line_value,
668
+ "gap": order_value - line_value, "ok": abs(order_value - line_value) <= 0.01})
669
+ return checks
670
+
671
+
672
+ def sales_summary_partition(all_values, agent_values, unassigned):
673
+ """Partition additive measures; AOV must be recomputed from the summed count."""
674
+ import math
675
+ keys = ("invoiced_sales", "confirmed_sales", "order_count", "average_order_value")
676
+ groups = [all_values, *agent_values, unassigned]
677
+ if len(agent_values) < 2 or any(not all(isinstance(g.get(k), (int, float))
678
+ and not isinstance(g[k], bool) and math.isfinite(g[k]) for k in keys) for g in groups):
679
+ return False
680
+ if any(g["confirmed_sales"] <= 0 or g["order_count"] <= 0 or g["invoiced_sales"] <= 0
681
+ for g in agent_values):
682
+ return False
683
+ if any(abs(sum(g[k] for g in [*agent_values, unassigned]) - all_values[k]) >
684
+ (0 if k == "order_count" else 0.01) for k in keys[:3]):
685
+ return False
686
+ return all(abs(g["average_order_value"] - (g["confirmed_sales"] / g["order_count"]
687
+ if g["order_count"] else 0)) <= 0.01 for g in groups)
688
+
689
+
690
  def clean_binding(raw):
691
  """Normalize a C2 `Binding`, or raise `SheetRefusal`.
692
 
 
755
  return out
756
 
757
 
758
+ def filter_cell_nodes(nodes):
759
+ """Cell value slots live on leaves at any depth, never on a fixed object path."""
760
+ for node in nodes or ():
761
+ if not isinstance(node, dict):
762
+ continue
763
+ if isinstance(node.get("children"), list):
764
+ yield from filter_cell_nodes(node["children"])
765
+ elif "valueRef" in node:
766
+ yield node
767
+
768
+
769
+ def resolve_filter_cells(nodes, read_cell):
770
+ """Resolve transient operands; retain authored references on the stored binding."""
771
+ import math
772
+ from harness.filter_sql import MULTI_VALUE_OPS, VALUE_FREE_OPS
773
+ from harness.windows import ANCHOR_VALUE_FREE
774
+ out = []
775
+ for node in nodes or ():
776
+ if not isinstance(node, dict):
777
+ out.append(node)
778
+ elif isinstance(node.get("children"), list):
779
+ out.append({**node, "children": resolve_filter_cells(node["children"], read_cell)})
780
+ elif "valueRef" in node:
781
+ slot = node["valueRef"]
782
+ ref = str(slot.get("ref") or "").strip() if isinstance(slot, dict) else ""
783
+ if (node.get("op") in VALUE_FREE_OPS or node.get("op") == "within"
784
+ or node.get("dateMode") in ANCHOR_VALUE_FREE or node.get("rhs") is not None):
785
+ raise SheetRefusal("filter_cell_unreadable", ref or "(blank)",
786
+ "this condition uses a window or another operand instead of a value.")
787
+ value = read_cell(ref)
788
+ if (not isinstance(value, (str, int, float, bool)) or str(value).strip() == ""
789
+ or isinstance(value, float) and not math.isfinite(value)):
790
+ raise SheetRefusal("filter_cell_unreadable", ref or "(blank)",
791
+ "its value is blank or is not a single usable value.")
792
+ text = str(value).lower() if isinstance(value, bool) else str(value)
793
+ leaf = {**node, "value": text, "_cell_value_resolved": True}
794
+ if node.get("op") in MULTI_VALUE_OPS:
795
+ leaf["values"] = [text]
796
+ out.append(leaf)
797
+ else:
798
+ out.append(node)
799
+ return out
800
+
801
+
802
+ # W60-T40: explicit persisted identity, separate from both flat columns and cell value slots.
803
+ LINKED_FILTER_PREFIX = "linked:"
804
+
805
+
806
+ def linked_field_parts(key):
807
+ text = str(key or "")
808
+ if not text.startswith(LINKED_FILTER_PREFIX):
809
+ return None
810
+ parts = text.split(":")
811
+ if len(parts) != 3 or not all(parts[1:]):
812
+ raise SheetRefusal("linked_filter_unreadable", text, "its saved link identity is invalid.")
813
+ return parts[1], parts[2]
814
+
815
+
816
+ def linked_filter_ids(nodes):
817
+ return {key for key in filter_columns_named(nodes) if key.startswith(LINKED_FILTER_PREFIX)}
818
+
819
+
820
+ def rewrite_linked_filters(nodes, resolve):
821
+ """Preserve every conjunction; the route resolves only explicit linked leaves."""
822
+ out = []
823
+ for node in nodes or ():
824
+ if not isinstance(node, dict):
825
+ out.append(node)
826
+ elif isinstance(node.get("children"), list):
827
+ out.append({**node, "children": rewrite_linked_filters(node["children"], resolve)})
828
+ elif linked_filter_ids([node]):
829
+ if not linked_field_parts(node.get("colId")) or node.get("rhs") is not None:
830
+ raise SheetRefusal("linked_filter_unreadable", ", ".join(sorted(linked_filter_ids([node]))),
831
+ "comparing columns across records is not supported. Type a value or use a cell.")
832
+ out.append(resolve(node))
833
+ else:
834
+ out.append(node)
835
+ return out
836
+
837
+
838
+ def linked_id_predicate(column, ids):
839
+ """Membership using existing numeric equality, with no ID cap or deep SQL OR chain.
840
+
841
+ isAnyOf deliberately refuses numeric columns in filter_sql. Balanced groups of eq leaves
842
+ express the same membership without changing that pure compiler or truncating its values.
843
+ """
844
+ values = sorted({int(pid) for pid in ids})
845
+
846
+ def tree(lo, hi):
847
+ if hi == lo:
848
+ return {"conj": "and", "children": [
849
+ {"colId": column, "op": "isEmpty"}, {"colId": column, "op": "isNotEmpty"}]}
850
+ if hi - lo == 1:
851
+ return {"colId": column, "op": "eq", "value": str(values[lo])}
852
+ mid = (lo + hi) // 2
853
+ return {"conj": "or", "children": [tree(lo, mid), tree(mid, hi)]}
854
+
855
+ return tree(0, len(values))
856
+
857
+
858
  def filter_columns_named(nodes):
859
  """Every `colId` a filter tree names, at any depth, including a right-hand column reference.
860
 
 
942
  is what a relative date condition needs, and it is exactly the value R14's `period.ref` feeds.
943
  """
944
  from harness.filter_sql import compile_filter_tree
945
+ import math
946
+ unresolved = linked_filter_ids(nodes)
947
+ if unresolved:
948
+ raise SheetRefusal("linked_filter_unreadable", ", ".join(sorted(unresolved)),
949
+ "the linked records have not been resolved.")
950
+ for leaf in filter_cell_nodes(nodes):
951
+ slot = leaf.get("valueRef")
952
+ ref = slot.get("ref") if isinstance(slot, dict) else "(blank)"
953
+ if leaf.get("_cell_value_resolved") is not True:
954
+ raise SheetRefusal("filter_cell_unreadable", ref, "the source value has not been read.")
955
+ try:
956
+ compiled = compile_filter_tree([leaf], conj="and", columns=columns or {},
957
+ today=today, cohort_sets=cohort_sets)
958
+ except ValueError:
959
+ raise SheetRefusal("filter_cell_unreadable", ref,
960
+ "its condition uses a value or operator this database cannot apply.")
961
+ if (compiled is None or leaf.get("colId") not in compiled.columns_used
962
+ or not compiled.params or any(isinstance(p, float) and not math.isfinite(p)
963
+ for p in compiled.params)):
964
+ raise SheetRefusal("filter_cell_unreadable", ref,
965
+ "its condition cannot use this value on the selected column.")
966
  return compile_filter_tree(list(nodes or ()), conj=conj or "and", columns=columns or {},
967
  today=today, cohort_sets=cohort_sets)
968
 
 
995
  col = (columns or {}).get(key)
996
  if not col or not col.get("sql"):
997
  raise SheetRefusal("field_unknown", key or "That column")
998
+ # An empty SUM is zero. AVG/MIN/MAX retain NULL because there is no value to report.
999
+ if fn == "sum":
1000
+ return f"COALESCE(SUM({col['sql']}), 0)", key
1001
  return f"{fn.upper()}({col['sql']})", key
1002
 
1003
 
 
1084
 
1085
  # ── W49-T10: the dependents provider (contract C3) ───────────────────────────────────────────
1086
 
1087
+ def _sheet_cell_link(workbook_id, tab, addr):
1088
+ """C2 address from stored identities, or the reason the reader cannot open this cell."""
1089
+ if not isinstance(workbook_id, str) or not workbook_id:
1090
+ return None, "The workbook ID is missing. Restore the workbook before opening this cell."
1091
+ tab_id = tab.get("id")
1092
+ if not isinstance(tab_id, str) or not tab_id:
1093
+ return None, "The tab ID is missing. Restore the tab before opening this cell."
1094
+ if not isinstance(addr, str) or not _PERIOD_REF.fullmatch(addr):
1095
+ return None, "The cell address is invalid. Restore its A1 address in the workbook."
1096
+ # W60-T12, 2026-09-14: T10's reader falls back when a tab, row or column is hidden.
1097
+ # Such a URL would open another cell, so report the cause and recovery instead.
1098
+ if tab.get("visibility", "visible") != "visible":
1099
+ return None, "The tab is hidden. Unhide it in the workbook before opening this cell."
1100
+ letters = addr.rstrip("0123456789")
1101
+ row_number = int(addr[len(letters):])
1102
+ col_number = 0
1103
+ for letter in letters:
1104
+ col_number = col_number * 26 + ord(letter) - ord("A") + 1
1105
+ if row_number in (tab.get("hiddenRows") or ()):
1106
+ return None, "The cell's row is hidden. Unhide the row before opening this cell."
1107
+ if col_number in (tab.get("hiddenCols") or ()):
1108
+ return None, "The cell's column is hidden. Unhide the column before opening this cell."
1109
+ return "#/sheet?" + urlencode({"wb": workbook_id, "tab": tab_id, "cell": addr}), ""
1110
+
1111
+
1112
  def sheet_dependents(st, target):
1113
  """Which Sheet cells depend on `target`, as C3 `Dependent` rows.
1114
 
 
1132
  if not kind or not key:
1133
  return []
1134
 
1135
+ hits, unreadable = [], []
1136
  for row in sheet_store.list_workbooks(st):
1137
  try:
1138
  book = sheet_store.get_workbook(st, row["id"])
1139
  except sheet_store.SheetRefusal:
1140
+ name = str(row.get("name") or row["id"])
1141
+ unreadable.append({
1142
+ "kind": "sheet_unreadable",
1143
+ "label": f"Workbook {name} that could not be read",
1144
+ "count": 1, "ids": [], "href": None,
1145
+ "refusal": f"{name} could not be opened because its workbook document could not be read. "
1146
+ "Restore the document or remove its stale workbook entry.",
1147
+ })
1148
  continue
1149
  for tab in book.get("sheets") or ():
1150
  for addr, cell in (tab.get("cells") or {}).items():
1151
  if _cell_depends_on(cell, kind, key, database):
1152
+ display = (f"{book.get('name') or book.get('id')} / "
1153
+ f"{tab.get('name') or tab.get('id')}!{addr}")
1154
+ href, reason = _sheet_cell_link(row["id"], tab, addr)
1155
+ # W60-T12, 2026-09-14: C3 now requires a label and a link per cell.
1156
+ # Retain the count/ids keys and display IDs; each singular label agrees
1157
+ # with count=1 so legacy refusal readers still describe real dependents.
1158
+ item = {"kind": "sheet_cell", "count": 1, "ids": [display],
1159
+ "label": f"Sheet cell in {display}"}
1160
+ item["href"] = href
1161
+ if reason:
1162
+ item["refusal"] = f"{display}: {reason}"
1163
+ hits.append(item)
1164
+ # Unreadable workbooks remain separate from the count of known dependent cells.
1165
+ return hits + unreadable
 
 
 
 
 
1166
 
1167
 
1168
  # ── W49-T11 (combine-owned): register the provider with the dependents registry ────────────
web/src/automation/AutomationSurface.tsx CHANGED
@@ -26,6 +26,7 @@ import { AUTOMATION_OPEN_EVENT } from "../apiContract";
26
  // WAVE'S BRAND while a comment asserted parity. So this imports the component that POINTS at the
27
  // generated artifact. [[loopable-nav-logo-toggle]] — one element paints the mark.
28
  import { Mark } from "../shell/Brand";
 
29
  import type { Automation, AutomationList } from "./automationApi";
30
  import {
31
  AutomationError,
@@ -34,6 +35,7 @@ import {
34
  listVoiceAgents,
35
  listAutomations,
36
  liveStepOf,
 
37
  patchAutomation,
38
  rememberAutomation,
39
  replaceVoiceAgent,
@@ -212,29 +214,6 @@ if (typeof window !== "undefined") {
212
  * that a database can be created BY asking for an automation.
213
  */
214
 
215
- /**
216
- * A default name for a brand-new automation, and it has to be one the server ACCEPTS.
217
- *
218
- * MEASURED against the live route rather than assumed (`scratchpad/probe_names.py`): a create
219
- * with no name is a 400 (`name the automation`), and duplicate names are ALLOWED. So the name
220
- * cannot be omitted, and a fixed literal would stack "New automation" three deep in a rail that
221
- * sorts by name with nothing to tell the rows apart. Numbering from the existing list is a
222
- * client-side convenience over a server that does not care: if two tabs race, the loser gets a
223
- * duplicate name, which is legal, visible and renameable — never an error the user has to read.
224
- */
225
- function nextAutomationName(existing: Automation[]): string {
226
- const taken = new Set(existing.map((a) => (a.name || "").trim().toLowerCase()));
227
- for (let n = existing.length + 1; ; n += 1) {
228
- // ⭐ WAVE 34 · R12 — "Agent N", not "Automation N". ⚠ THIS ONE IS STORED, so it is the only
229
- // string in the rename that leaves a visible seam: automations created before today keep
230
- // "Automation 3" as their NAME until somebody renames them. That is correct and deliberate —
231
- // a name is a person's own text, and rewriting stored names to match a caption change would
232
- // edit user data to tidy a word. The seam is in the rail for a while and then gone.
233
- const candidate = `Agent ${n}`;
234
- if (!taken.has(candidate.toLowerCase())) return candidate;
235
- }
236
- }
237
-
238
  export default function AutomationSurface() {
239
  /* ⭐ T22 — SEEDED FROM THE CLIENT MEMO, so a revisit inside the freshness window never passes
240
  through `data === null` and therefore never paints the skeleton. The lazy initialiser runs
@@ -282,6 +261,8 @@ export default function AutomationSurface() {
282
  wantedId.current = id;
283
  setActiveId(id);
284
  setActiveVoiceId("");
 
 
285
  }, []);
286
 
287
  const selectVoice = useCallback((id: string) => {
@@ -289,8 +270,28 @@ export default function AutomationSurface() {
289
  wantedId.current = "";
290
  setActiveId("");
291
  setActiveVoiceId(id);
 
 
292
  }, []);
293
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
294
  /**
295
  * ⭐⭐ W33 (C-18, from lane C) — WHICH PANE AN INBOX ITEM ASKED FOR, and it was DROPPED here.
296
  *
 
26
  // WAVE'S BRAND while a comment asserted parity. So this imports the component that POINTS at the
27
  // generated artifact. [[loopable-nav-logo-toggle]] — one element paints the mark.
28
  import { Mark } from "../shell/Brand";
29
+ import { agentAddressHash, readAgentAddress } from "../shell/nav";
30
  import type { Automation, AutomationList } from "./automationApi";
31
  import {
32
  AutomationError,
 
35
  listVoiceAgents,
36
  listAutomations,
37
  liveStepOf,
38
+ nextAutomationName,
39
  patchAutomation,
40
  rememberAutomation,
41
  replaceVoiceAgent,
 
214
  * that a database can be created BY asking for an automation.
215
  */
216
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
217
  export default function AutomationSurface() {
218
  /* ⭐ T22 — SEEDED FROM THE CLIENT MEMO, so a revisit inside the freshness window never passes
219
  through `data === null` and therefore never paints the skeleton. The lazy initialiser runs
 
261
  wantedId.current = id;
262
  setActiveId(id);
263
  setActiveVoiceId("");
264
+ const address = agentAddressHash("agent", id);
265
+ if (window.location.hash !== address) window.location.hash = address;
266
  }, []);
267
 
268
  const selectVoice = useCallback((id: string) => {
 
270
  wantedId.current = "";
271
  setActiveId("");
272
  setActiveVoiceId(id);
273
+ const address = agentAddressHash("voice", id);
274
+ if (window.location.hash !== address) window.location.hash = address;
275
  }, []);
276
 
277
+ useEffect(() => {
278
+ const readAddress = () => {
279
+ const address = readAgentAddress();
280
+ if (address.agent) select(address.agent);
281
+ else if (address.voice) selectVoice(address.voice);
282
+ else {
283
+ wantedId.current = "";
284
+ setActiveId("");
285
+ setActiveVoiceId("");
286
+ setSlackOpen(false);
287
+ }
288
+ };
289
+ // Select before the list arrives; a missing id simply has no matching rail row.
290
+ readAddress();
291
+ window.addEventListener("hashchange", readAddress);
292
+ return () => window.removeEventListener("hashchange", readAddress);
293
+ }, [select, selectVoice]);
294
+
295
  /**
296
  * ⭐⭐ W33 (C-18, from lane C) — WHICH PANE AN INBOX ITEM ASKED FOR, and it was DROPPED here.
297
  *
web/src/automation/automationApi.ts CHANGED
@@ -1396,6 +1396,29 @@ export function forgetAutomation(id: string): AutomationList | null {
1396
  return data;
1397
  }
1398
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1399
  export function createAutomation(body: unknown): Promise<{ automation: Automation }> {
1400
  return send<{ automation: Automation }>("/automations", {
1401
  method: "POST",
 
1396
  return data;
1397
  }
1398
 
1399
+ /**
1400
+ * A default name for a brand-new automation, and it has to be one the server ACCEPTS.
1401
+ *
1402
+ * MEASURED against the live route rather than assumed (`scratchpad/probe_names.py`): a create
1403
+ * with no name is a 400 (`name the automation`), and duplicate names are ALLOWED. So the name
1404
+ * cannot be omitted, and a fixed literal would stack "New automation" three deep in a rail that
1405
+ * sorts by name with nothing to tell the rows apart. Numbering from the existing list is a
1406
+ * client-side convenience over a server that does not care: if two tabs race, the loser gets a
1407
+ * duplicate name, which is legal, visible and renameable — never an error the user has to read.
1408
+ */
1409
+ export function nextAutomationName(existing: { name: string }[]): string {
1410
+ const taken = new Set(existing.map((a) => (a.name || "").trim().toLowerCase()));
1411
+ for (let n = existing.length + 1; ; n += 1) {
1412
+ // ⭐ WAVE 34 · R12 — "Agent N", not "Automation N". ⚠ THIS ONE IS STORED, so it is the only
1413
+ // string in the rename that leaves a visible seam: automations created before today keep
1414
+ // "Automation 3" as their NAME until somebody renames them. That is correct and deliberate —
1415
+ // a name is a person's own text, and rewriting stored names to match a caption change would
1416
+ // edit user data to tidy a word. The seam is in the rail for a while and then gone.
1417
+ const candidate = `Agent ${n}`;
1418
+ if (!taken.has(candidate.toLowerCase())) return candidate;
1419
+ }
1420
+ }
1421
+
1422
  export function createAutomation(body: unknown): Promise<{ automation: Automation }> {
1423
  return send<{ automation: Automation }>("/automations", {
1424
  method: "POST",
web/src/connectors/ConnectorModal.tsx CHANGED
@@ -275,6 +275,8 @@ export interface ConnectorDetail {
275
  databases: ConnectorDatabase[];
276
  enablement: ConnectorEnablement | null;
277
  materialization?: MaterializationCapability | null;
 
 
278
  introspection: ConnectorIntrospection;
279
  relationships: ConnectorRelationshipGraph;
280
  }
@@ -503,6 +505,9 @@ export function parseConnectorDetail(body: unknown, selectedKey: string): Connec
503
  keychain: parseKeychainHalf(source.keychain),
504
  databases: parseDatabases(source.databases),
505
  enablement: parseConnectorEnablement(source.enablement, selectedKey),
 
 
 
506
  materialization: obj(source.materialization).provider === selectedKey &&
507
  str(obj(source.materialization).statusPath) === `/connectors/${selectedKey}/jobs` &&
508
  str(obj(source.materialization).retryPath) === `/connectors/${selectedKey}/sync/retry`
@@ -815,11 +820,13 @@ export default function ConnectorModal({
815
  */
816
  const [pulling, setPulling] = useState(false);
817
  /**
818
- * ⛔⛔ THE PULL DIALOG'S OWN SURFACE, HELD IN STATE RATHER THAN A REF, because
819
  * `useOverlayLayer` reads `outsideElements` on every RENDER and a ref that fills in after mount
820
  * would never reach it. See the dismissal note on the layer below.
821
  */
822
  const [pullSurface, setPullSurface] = useState<HTMLElement | null>(null);
 
 
823
  const canPull = isAmazonConnector(row.key);
824
 
825
  const unsavedMessage = databasePendingCount === 1
@@ -862,14 +869,15 @@ export default function ConnectorModal({
862
  *
863
  * `useOverlayLayer` guards its handlers with `stack.isTop(id)` and that guard is INERT in this
864
  * app: `OverlaySurface.tsx` exports `OverlayProvider` and nothing mounts it, so the context is
865
- * null and every layer believes it is the top one. Both layers also listen on `document` in
866
  * the CAPTURE phase, where `stopPropagation` does not stop a sibling listener on the same
867
- * node. So Escape inside the pull dialog would close the dialog AND this modal underneath it.
868
- * Answering here keeps the fix in this ticket's own files: while the pull dialog is open,
869
- * this layer's dismissal closes THAT and stops.
 
870
  */
871
  onDismiss: () => {
872
- if (pendingLeave) return;
873
  if (pulling) {
874
  setPulling(false);
875
  return;
@@ -878,13 +886,16 @@ export default function ConnectorModal({
878
  },
879
  dismissOnOutside: true,
880
  /**
881
- * ⛔ AND THE POINTER HALF OF THE SAME PROBLEM. The dialog portals as a SIBLING of this
882
- * panel, so a press inside it is literally outside `panelRef` and would dismiss this modal
883
- * out from under it in the middle of a paid pull. `outsideElements` is the hook's own answer.
 
884
  */
885
- outsideElements: pullSurface ? [pullSurface] : [],
 
 
886
  initialFocus: "[data-overlay-autofocus]",
887
- trapFocus: pendingLeave === null,
888
  // The layer captures whatever was focused when it mounted and focuses it again on unmount,
889
  // which is the card's own open button. That is the done-when's "focus returns to the card".
890
  restoreFocus: true,
@@ -1013,6 +1024,7 @@ export default function ConnectorModal({
1013
  onChanged={reread}
1014
  onPendingChange={setDatabasePendingCount}
1015
  onBusyChange={setDatabaseTabBusy}
 
1016
  reveal={databaseReveal}
1017
  />
1018
  </>
@@ -1198,6 +1210,7 @@ export default function ConnectorModal({
1198
  tone="destructive"
1199
  onConfirm={confirmLeave}
1200
  onCancel={() => setPendingLeave(null)}
 
1201
  />
1202
  </BodyPortal>
1203
  );
 
275
  databases: ConnectorDatabase[];
276
  enablement: ConnectorEnablement | null;
277
  materialization?: MaterializationCapability | null;
278
+ /** Present only when the server says this administrator can request a provider sync. */
279
+ syncNow?: { provider: string; path: string } | null;
280
  introspection: ConnectorIntrospection;
281
  relationships: ConnectorRelationshipGraph;
282
  }
 
505
  keychain: parseKeychainHalf(source.keychain),
506
  databases: parseDatabases(source.databases),
507
  enablement: parseConnectorEnablement(source.enablement, selectedKey),
508
+ syncNow: obj(source.syncNow).provider === selectedKey &&
509
+ str(obj(source.syncNow).path) === `/connectors/${selectedKey}/sync/now`
510
+ ? { provider: selectedKey, path: `/connectors/${selectedKey}/sync/now` } : null,
511
  materialization: obj(source.materialization).provider === selectedKey &&
512
  str(obj(source.materialization).statusPath) === `/connectors/${selectedKey}/jobs` &&
513
  str(obj(source.materialization).retryPath) === `/connectors/${selectedKey}/sync/retry`
 
820
  */
821
  const [pulling, setPulling] = useState(false);
822
  /**
823
+ * ⛔⛔ THE PULL AND CONFIRM DIALOGS' OWN SURFACES, HELD IN STATE RATHER THAN REFS, because
824
  * `useOverlayLayer` reads `outsideElements` on every RENDER and a ref that fills in after mount
825
  * would never reach it. See the dismissal note on the layer below.
826
  */
827
  const [pullSurface, setPullSurface] = useState<HTMLElement | null>(null);
828
+ const [tabConfirmSurface, setTabConfirmSurface] = useState<HTMLElement | null>(null);
829
+ const [leaveSurface, setLeaveSurface] = useState<HTMLElement | null>(null);
830
  const canPull = isAmazonConnector(row.key);
831
 
832
  const unsavedMessage = databasePendingCount === 1
 
869
  *
870
  * `useOverlayLayer` guards its handlers with `stack.isTop(id)` and that guard is INERT in this
871
  * app: `OverlaySurface.tsx` exports `OverlayProvider` and nothing mounts it, so the context is
872
+ * null and every layer believes it is the top one. Both layers listen for pointers on `document` in
873
  * the CAPTURE phase, where `stopPropagation` does not stop a sibling listener on the same
874
+ * node. So a pointer press can dismiss the dialog AND this modal underneath it.
875
+ * Answering here keeps the fix in this ticket's own files: while either confirm is open,
876
+ * this layer refuses dismissal; while the pull dialog is open, it closes THAT and stops.
877
+ * Escape already belongs to the topmost entry in `useEscapeClose`'s shared stack.
878
  */
879
  onDismiss: () => {
880
+ if (pendingLeave || tabConfirmSurface) return;
881
  if (pulling) {
882
  setPulling(false);
883
  return;
 
886
  },
887
  dismissOnOutside: true,
888
  /**
889
+ * ⛔ AND THE POINTER HALF OF THE SAME PROBLEM. These dialogs portal as SIBLINGS of this
890
+ * panel, so a press inside one is literally outside `panelRef` and would dismiss this modal
891
+ * out from under a paid pull or a staged change. `outsideElements` is the hook's own answer.
892
+ * Each surface includes its scrim, so a stray press there cannot dismiss this modal either.
893
  */
894
+ outsideElements: [pullSurface, tabConfirmSurface, leaveSurface].filter(
895
+ (element): element is HTMLElement => element !== null,
896
+ ),
897
  initialFocus: "[data-overlay-autofocus]",
898
+ trapFocus: pendingLeave === null && tabConfirmSurface === null,
899
  // The layer captures whatever was focused when it mounted and focuses it again on unmount,
900
  // which is the card's own open button. That is the done-when's "focus returns to the card".
901
  restoreFocus: true,
 
1024
  onChanged={reread}
1025
  onPendingChange={setDatabasePendingCount}
1026
  onBusyChange={setDatabaseTabBusy}
1027
+ onConfirmSurface={setTabConfirmSurface}
1028
  reveal={databaseReveal}
1029
  />
1030
  </>
 
1210
  tone="destructive"
1211
  onConfirm={confirmLeave}
1212
  onCancel={() => setPendingLeave(null)}
1213
+ surfaceRef={setLeaveSurface}
1214
  />
1215
  </BodyPortal>
1216
  );
web/src/connectors/DatabasesTab.tsx CHANGED
@@ -57,6 +57,7 @@
57
  // ---------------------------------------------------------------------------
58
 
59
  import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
 
60
  import { API_V1, CREDENTIALS, WORKSPACE_STALE_EVENT, signal } from "../apiContract";
61
  import { ConfirmDialog } from "../ui/ConfirmDialog";
62
  import { useEscapeClose } from "../ui/useEscapeClose";
@@ -65,9 +66,200 @@ import type { ConnectorRow } from "./ConnectorsPage";
65
  import { watchMaterialization } from "./materializationJobs";
66
  import type { MaterializationJob } from "./materializationJobs";
67
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
68
  /** What `GET /dependents` said, or why it could not say anything. */
69
  type DependentsAnswer =
70
- | { ok: true; refusal: string }
71
  | { ok: false; message: string };
72
 
73
  /**
@@ -84,12 +276,15 @@ async function readDependents(tableKey: string): Promise<DependentsAnswer> {
84
  { credentials: CREDENTIALS }
85
  );
86
  const body = (await res.json().catch(() => null)) as
87
- | { refusal?: unknown; error?: { message?: string } }
88
  | null;
89
  if (!res.ok) {
90
  return { ok: false, message: body?.error?.message || `The server answered ${res.status}.` };
91
  }
92
- return { ok: true, refusal: typeof body?.refusal === "string" ? body.refusal : "" };
 
 
 
93
  } catch {
94
  return { ok: false, message: "Cannot reach the server." };
95
  }
@@ -113,6 +308,85 @@ async function write(path: string, method: "PUT" | "PATCH" | "POST", body: unkno
113
  }
114
  }
115
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
116
  /**
117
  * Enabling sets the flag and THEN materialises, so a refusal can still have changed the server.
118
  *
@@ -652,6 +926,7 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
652
  onPendingChange: (count: number) => void;
653
  /** Locks the modal actions while the dependents check or the batch is in flight. */
654
  onBusyChange: (busy: boolean) => void;
 
655
  /** The enabled row and its result survive the modal's loading remount. */
656
  reveal?: DatabaseReveal | null;
657
  }>(function DatabasesTab({
@@ -660,6 +935,7 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
660
  onChanged,
661
  onPendingChange,
662
  onBusyChange,
 
663
  reveal,
664
  }, ref) {
665
  const { databases, introspection } = detail;
@@ -677,6 +953,8 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
677
  const [busy, setBusy] = useState("");
678
  const [confirmOff, setConfirmOff] = useState<ConnectorDatabase | null>(null);
679
  const [refusals, setRefusals] = useState<Record<string, string>>({});
 
 
680
  const [autoEnableResults, setAutoEnableResults] = useState<Record<string, string>>(
681
  () => reveal?.key && reveal.status ? { [reveal.key]: reveal.status } : {}
682
  );
@@ -684,7 +962,10 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
684
  const [jobs, setJobs] = useState<MaterializationJob[]>([]);
685
  const [jobError, setJobError] = useState("");
686
  const [retrying, setRetrying] = useState("");
687
- const capability = detail.materialization;
 
 
 
688
  useEffect(() => {
689
  if (!capability) return;
690
  return watchMaterialization(capability, (next, message) => {
@@ -771,6 +1052,7 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
771
  setBusy(database.key);
772
  setError("");
773
  setRefusals((current) => ({ ...current, [database.key]: "" }));
 
774
  setAutoEnableResults((current) => ({ ...current, [database.key]: "" }));
775
  if (!next) {
776
  const answer = await readDependents(database.key);
@@ -787,6 +1069,7 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
787
  // The server's sentence, verbatim. C3 omits every zero-count kind, so this cannot
788
  // claim a count it does not have.
789
  setRefusals((current) => ({ ...current, [database.key]: answer.refusal }));
 
790
  return;
791
  }
792
  if (!usesProviderEnablement) {
@@ -847,6 +1130,19 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
847
  onPendingChange(0);
848
  }, [onPendingChange]);
849
 
 
 
 
 
 
 
 
 
 
 
 
 
 
850
  const savePending = useCallback(async () => {
851
  const snapshot = pending;
852
  if (!pendingChangeCount(snapshot)) return;
@@ -933,7 +1229,7 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
933
  onPendingChange(pendingChangeCount(failed));
934
  setBusy("");
935
  setError(failures.join(" "));
936
- if (detail.materialization) watchMaterialization(detail.materialization);
937
  // One batch gets one fresh detail payload. That payload also carries the newly derived graph.
938
  onChanged();
939
  }, [databases, detail.enablement, detail.materialization, onChanged, onPendingChange, pending, row.key]);
@@ -974,26 +1270,11 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
974
  onChanged();
975
  }, [onChanged]);
976
 
977
- if (!introspection.introspectable) {
978
- return <DatabasesUnavailable row={row} reason={introspection.reason} />;
979
- }
980
-
981
- if (!databases.length) {
982
- // One line plus the action that fills it (DESIGN.md section 4), and it names the cause
983
- // rather than implying the connector creates nothing.
984
- return (
985
- <p className="conn-db-note">
986
- This connection has not declared any databases in this workspace. Connect it from the
987
- Keychain tab to read its schema.
988
- </p>
989
- );
990
- }
991
-
992
- return (
993
- <div className="conn-db">
994
- {showsPopulation && introspection.fieldsVisible ? (
995
  <div className="conn-db-head">
996
  <div>
 
997
  <p className="conn-db-note" id="odoo-census-warning">
998
  Count rows stops at 101 rows per source table and displays 100+ from 100 onward.
999
  Each table still needs a request, so this can take about a minute or longer.
@@ -1012,7 +1293,28 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
1012
  )}
1013
  </p>
1014
  ) : null}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1015
  </div>
 
 
 
 
 
 
 
1016
  <button
1017
  type="button"
1018
  className="conn-db-count-action"
@@ -1031,8 +1333,30 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
1031
  >
1032
  Exact totals
1033
  </button>
 
1034
  </div>
1035
- ) : null}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1036
  {error ? (
1037
  <p className="conn-db-error" role="alert">
1038
  {error}
@@ -1138,6 +1462,8 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
1138
  {job?.error ? <span className="conn-job-error">{job.error}</span> : null}
1139
  </div>
1140
  ) : null}
 
 
1141
  </td>
1142
  <td>
1143
  <button
@@ -1217,6 +1543,29 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
1217
  <p className="conn-db-refusal" role="alert">
1218
  {refusal}
1219
  </p>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1220
  </td>
1221
  </tr>
1222
  ) : null}
@@ -1241,6 +1590,24 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
1241
  );
1242
  })}
1243
  </table>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1244
  <ConfirmDialog
1245
  open={confirmOff !== null}
1246
  title="Switch off this database"
@@ -1260,6 +1627,7 @@ const DatabasesTab = forwardRef<DatabasesTabHandle, {
1260
  setConfirmOff(null);
1261
  }}
1262
  onCancel={() => setConfirmOff(null)}
 
1263
  />
1264
  </div>
1265
  );
 
57
  // ---------------------------------------------------------------------------
58
 
59
  import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
60
+ import type { MouseEvent } from "react";
61
  import { API_V1, CREDENTIALS, WORKSPACE_STALE_EVENT, signal } from "../apiContract";
62
  import { ConfirmDialog } from "../ui/ConfirmDialog";
63
  import { useEscapeClose } from "../ui/useEscapeClose";
 
66
  import { watchMaterialization } from "./materializationJobs";
67
  import type { MaterializationJob } from "./materializationJobs";
68
 
69
+ interface AmazonTableSync {
70
+ rowsLoaded: number | null;
71
+ lastSuccess: string | null;
72
+ inProgress: boolean;
73
+ deferred: { reason: string } | null;
74
+ nextDue: string | null;
75
+ firstLoad: { remaining: number; etaSeconds: number; cause: string; needsAttention: boolean } | null;
76
+ stuck: boolean | null;
77
+ stuckCause: string;
78
+ unknownCause: string;
79
+ }
80
+
81
+ function syncObject(value: unknown): Record<string, unknown> {
82
+ return value !== null && typeof value === "object" && !Array.isArray(value)
83
+ ? value as Record<string, unknown> : {};
84
+ }
85
+
86
+ function syncText(value: unknown): string {
87
+ return typeof value === "string" && value.length <= 512 ? value : "";
88
+ }
89
+
90
+ function syncCount(value: unknown): number | null {
91
+ return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
92
+ }
93
+
94
+ function syncStamp(value: unknown): string | null {
95
+ const text = syncText(value);
96
+ return text && Number.isFinite(Date.parse(text)) ? text : null;
97
+ }
98
+
99
+ /** ConnectorModal's parser omits provider additions. Parse our own raw detail read here. */
100
+ export function parseAmazonSyncStates(value: unknown): Record<string, AmazonTableSync | null> | null {
101
+ const payload = syncObject(value);
102
+ if (syncObject(payload.overview).key !== "amazon_sp" || !Array.isArray(payload.databases)) return null;
103
+ const states: Record<string, AmazonTableSync | null> = {};
104
+ for (const raw of payload.databases) {
105
+ const database = syncObject(raw);
106
+ if (typeof database.key !== "string" || !database.key.startsWith("ut_amzn_")) continue;
107
+ if (!database.sync || typeof database.sync !== "object" || Array.isArray(database.sync)) {
108
+ states[database.key] = null;
109
+ continue;
110
+ }
111
+ const state = syncObject(database.sync);
112
+ const load = syncObject(state.firstLoad);
113
+ const remaining = syncCount(load.remaining);
114
+ const etaSeconds = syncCount(load.etaSeconds);
115
+ const cause = syncText(load.cause);
116
+ const reason = syncText(syncObject(state.deferred).reason);
117
+ states[database.key] = {
118
+ rowsLoaded: syncCount(state.rowsLoaded), lastSuccess: syncStamp(state.lastSuccess),
119
+ inProgress: state.inProgress === true,
120
+ deferred: reason ? { reason } : null, nextDue: syncStamp(state.nextDue),
121
+ firstLoad: remaining !== null && remaining > 0 && etaSeconds !== null && cause
122
+ ? { remaining, etaSeconds, cause, needsAttention: load.needsAttention === true } : null,
123
+ stuck: state.stuck === true ? true : state.stuck === false ? false : null,
124
+ stuckCause: syncText(state.stuckCause), unknownCause: syncText(state.unknownCause),
125
+ };
126
+ }
127
+ return states;
128
+ }
129
+
130
+ function useAmazonSyncStates(enabled: boolean, detail: ConnectorDetail, syncPhase?: string) {
131
+ const [states, setStates] = useState<Record<string, AmazonTableSync | null>>({});
132
+ const [error, setError] = useState("");
133
+ useEffect(() => {
134
+ setStates({});
135
+ setError("");
136
+ if (!enabled) return;
137
+ const controller = new AbortController();
138
+ let reading = false;
139
+ const poll = async () => {
140
+ if (reading || controller.signal.aborted) return;
141
+ reading = true;
142
+ try {
143
+ const response = await fetch(`${API_V1}/connectors/amazon_sp/detail`, {
144
+ credentials: CREDENTIALS, signal: controller.signal,
145
+ });
146
+ const raw: unknown = await response.json();
147
+ if (controller.signal.aborted) return;
148
+ const next = response.ok ? parseAmazonSyncStates(raw) : null;
149
+ if (!next) throw new Error("Unreadable sync status");
150
+ setStates(next);
151
+ setError("");
152
+ } catch {
153
+ if (controller.signal.aborted) return;
154
+ setStates({});
155
+ setError("Sync status could not be read. Reload to check again.");
156
+ } finally {
157
+ reading = false;
158
+ }
159
+ };
160
+ void poll();
161
+ const timer = window.setInterval(() => {
162
+ if (document.visibilityState !== "hidden") void poll();
163
+ }, 5000);
164
+ return () => { controller.abort(); window.clearInterval(timer); };
165
+ }, [enabled, detail, syncPhase]);
166
+ return { states, error };
167
+ }
168
+
169
+ function readableSyncStamp(value: string): string {
170
+ return new Date(value).toLocaleString(undefined, { dateStyle: "medium", timeStyle: "short" });
171
+ }
172
+
173
+ function plural(count: number, unit: string): string {
174
+ return `${count.toLocaleString()} ${unit}${count === 1 ? "" : "s"}`;
175
+ }
176
+
177
+ function firstLoadEstimate(seconds: number): string {
178
+ if (seconds < 60) return plural(seconds, "second");
179
+ const minutes = Math.ceil(seconds / 60);
180
+ if (minutes < 60) return plural(minutes, "minute");
181
+ const hours = Math.floor(minutes / 60);
182
+ const rest = minutes % 60;
183
+ return rest ? `${plural(hours, "hour")} ${plural(rest, "minute")}` : plural(hours, "hour");
184
+ }
185
+
186
+ export function AmazonSyncChip({ state, error }: { state?: AmazonTableSync | null; error?: string }) {
187
+ const phase = state?.inProgress ? "syncing" : state?.stuck ? "failed"
188
+ : state?.deferred ? "deferred" : state?.rowsLoaded != null ? "ready" : "unknown";
189
+ return <div className="conn-job" data-sync-state={phase} aria-live="polite">
190
+ <span className="conn-job-attempt">{state?.rowsLoaded == null ? "Not loaded yet"
191
+ : `${state.rowsLoaded.toLocaleString()} rows loaded`}</span>
192
+ {state?.lastSuccess ? <span>Last success {readableSyncStamp(state.lastSuccess)}</span> : null}
193
+ {state?.inProgress ? <span>Syncing</span> : null}
194
+ {state?.deferred ? <span className="conn-job-error">Deferred: {state.deferred.reason}</span> : null}
195
+ {state?.nextDue ? <span>Next due {readableSyncStamp(state.nextDue)}</span> : null}
196
+ {state?.stuckCause ? <span className="conn-job-error">{state.stuckCause}. Retry sync to refresh progress.</span> : null}
197
+ {state?.firstLoad ? <span className="conn-job-error">
198
+ First load for connection: {state.firstLoad.remaining.toLocaleString()} reports remaining.
199
+ {" "}Estimated minimum time: {firstLoadEstimate(state.firstLoad.etaSeconds)}.
200
+ {" "}{state.firstLoad.cause}
201
+ {state.firstLoad.needsAttention ? " First load needs attention. Retry sync to continue." : ""}
202
+ </span> : null}
203
+ {state?.unknownCause ? <span className="conn-job-error">{state.unknownCause}</span> : null}
204
+ {!state ? <span className="conn-job-error">{error || "Sync status is unknown in this container. Reload to check again."}</span> : null}
205
+ </div>;
206
+ }
207
+
208
+ interface DependentItem { id: string; label: string; href: string | null; reason: string }
209
+ interface DependentKind {
210
+ kind: string; label: string; count: number; ids: string[];
211
+ items?: DependentItem[]; href?: string | null; reason?: string;
212
+ }
213
+
214
+ function dependentHref(value: unknown): string | null {
215
+ return typeof value === "string" && (value.startsWith("#/data?") || value.startsWith("#/sheet?"))
216
+ ? value : null;
217
+ }
218
+
219
+ function parseDependents(value: unknown): DependentKind[] {
220
+ if (!Array.isArray(value)) return [];
221
+ return value.flatMap((entry: unknown): DependentKind[] => {
222
+ if (!entry || typeof entry !== "object") return [];
223
+ const row = entry as Record<string, unknown>;
224
+ if (typeof row.kind !== "string" || typeof row.label !== "string" ||
225
+ typeof row.count !== "number" || !Number.isFinite(row.count) || row.count <= 0 ||
226
+ !Array.isArray(row.ids) || !row.ids.every((id) => typeof id === "string")) return [];
227
+ const dependent: DependentKind = {
228
+ kind: row.kind, label: row.label, count: row.count, ids: row.ids,
229
+ };
230
+ if ("href" in row) dependent.href = dependentHref(row.href);
231
+ if (typeof row.reason === "string") dependent.reason = row.reason;
232
+ if (Array.isArray(row.items)) {
233
+ dependent.items = row.items.flatMap((raw: unknown): DependentItem[] => {
234
+ if (!raw || typeof raw !== "object") return [];
235
+ const item = raw as Record<string, unknown>;
236
+ if (typeof item.id !== "string" || typeof item.label !== "string" ||
237
+ typeof item.reason !== "string" ||
238
+ !(item.href === null || typeof item.href === "string")) return [];
239
+ return [{ id: item.id, label: item.label, href: dependentHref(item.href), reason: item.reason }];
240
+ });
241
+ }
242
+ return [dependent];
243
+ });
244
+ }
245
+
246
+ function dependentRows(dependent: DependentKind): DependentItem[] {
247
+ if (dependent.items?.length) return dependent.items;
248
+ // Lane A may supply its workbook address and name on the dependent itself instead
249
+ // of an items list. Render that shape too without guessing any Sheet address.
250
+ if ("href" in dependent) return [{
251
+ id: dependent.ids.join(":"), label: dependent.label, href: dependent.href ?? null,
252
+ reason: dependent.reason || "This dependent has no direct address available.",
253
+ }];
254
+ return dependent.ids.map((id) => ({
255
+ id, label: id, href: null,
256
+ reason: dependent.reason || "This dependent has no direct address available.",
257
+ }));
258
+ }
259
+
260
  /** What `GET /dependents` said, or why it could not say anything. */
261
  type DependentsAnswer =
262
+ | { ok: true; refusal: string; dependents: DependentKind[] }
263
  | { ok: false; message: string };
264
 
265
  /**
 
276
  { credentials: CREDENTIALS }
277
  );
278
  const body = (await res.json().catch(() => null)) as
279
+ | { refusal?: unknown; dependents?: unknown; error?: { message?: string } }
280
  | null;
281
  if (!res.ok) {
282
  return { ok: false, message: body?.error?.message || `The server answered ${res.status}.` };
283
  }
284
+ return {
285
+ ok: true, refusal: typeof body?.refusal === "string" ? body.refusal : "",
286
+ dependents: parseDependents(body?.dependents),
287
+ };
288
  } catch {
289
  return { ok: false, message: "Cannot reach the server." };
290
  }
 
308
  }
309
  }
310
 
311
+ type SyncNowReceipt = {
312
+ provider: string;
313
+ state: "idle" | "queued" | "running" | "done" | "failed";
314
+ detail: string;
315
+ };
316
+
317
+ async function readSyncNow(path: string, provider: string): Promise<
318
+ { receipt: SyncNowReceipt; message: "" } | { receipt: null; message: string }
319
+ > {
320
+ try {
321
+ const res = await fetch(`${API_V1}${path}`, { credentials: CREDENTIALS });
322
+ const payload = await res.json().catch(() => null) as
323
+ | { provider?: unknown; state?: unknown; detail?: unknown; error?: { message?: string } }
324
+ | null;
325
+ if (!res.ok) return { receipt: null, message: payload?.error?.message || `The server answered ${res.status}.` };
326
+ if (payload?.provider !== provider || typeof payload.state !== "string" ||
327
+ !["idle", "queued", "running", "done", "failed"].includes(payload.state) ||
328
+ typeof payload.detail !== "string") {
329
+ return { receipt: null, message: "The server returned an unreadable sync status." };
330
+ }
331
+ return { receipt: { provider, state: payload.state as SyncNowReceipt["state"], detail: payload.detail }, message: "" };
332
+ } catch {
333
+ return { receipt: null, message: "Cannot reach the server to check sync progress." };
334
+ }
335
+ }
336
+
337
+ function useSyncNow(capability: ConnectorDetail["syncNow"]) {
338
+ const path = capability?.path;
339
+ const provider = capability?.provider;
340
+ const [receipt, setReceipt] = useState<SyncNowReceipt | null>(null);
341
+ const [message, setMessage] = useState("");
342
+ const [requestError, setRequestError] = useState("");
343
+ const [posting, setPosting] = useState(false);
344
+ const [reads, setReads] = useState(0);
345
+ const postInFlight = useRef(false);
346
+ const readGeneration = useRef(0);
347
+ useEffect(() => {
348
+ if (!path || !provider) return;
349
+ const generation = ++readGeneration.current;
350
+ let stopped = false;
351
+ let reading = false;
352
+ const poll = async () => {
353
+ if (reading || stopped || generation !== readGeneration.current) return;
354
+ reading = true;
355
+ const answer = await readSyncNow(path, provider);
356
+ reading = false;
357
+ if (stopped || generation !== readGeneration.current) return;
358
+ setMessage(answer.message);
359
+ setPosting(false);
360
+ if (!answer.receipt) return; // A failed read does not prove that the run finished.
361
+ setReceipt(answer.receipt);
362
+ if (!["queued", "running"].includes(answer.receipt.state)) window.clearInterval(timer);
363
+ };
364
+ const timer = window.setInterval(() => void poll(), 1500);
365
+ void poll();
366
+ return () => { stopped = true; readGeneration.current += 1; window.clearInterval(timer); };
367
+ }, [path, provider, reads]);
368
+ const active = receipt !== null && receipt.provider === provider &&
369
+ (receipt.state === "queued" || receipt.state === "running");
370
+ const start = async () => {
371
+ if (!path || active || postInFlight.current) return;
372
+ const generation = ++readGeneration.current;
373
+ postInFlight.current = true;
374
+ setPosting(true);
375
+ setReceipt(null);
376
+ setMessage("");
377
+ setRequestError("");
378
+ const error = await write(path, "POST", {});
379
+ postInFlight.current = false;
380
+ if (generation !== readGeneration.current) return;
381
+ setRequestError(error);
382
+ // Read after every response, including an uncertain network failure. The server may have
383
+ // accepted the intent already. Only a readback may claim that it is queued or finished.
384
+ setReads((value) => value + 1);
385
+ };
386
+ return { receipt: receipt?.provider === provider ? receipt : null, message: requestError || message,
387
+ busy: Boolean(active || posting), start };
388
+ }
389
+
390
  /**
391
  * Enabling sets the flag and THEN materialises, so a refusal can still have changed the server.
392
  *
 
926
  onPendingChange: (count: number) => void;
927
  /** Locks the modal actions while the dependents check or the batch is in flight. */
928
  onBusyChange: (busy: boolean) => void;
929
+ onConfirmSurface?: (element: HTMLElement | null) => void;
930
  /** The enabled row and its result survive the modal's loading remount. */
931
  reveal?: DatabaseReveal | null;
932
  }>(function DatabasesTab({
 
935
  onChanged,
936
  onPendingChange,
937
  onBusyChange,
938
+ onConfirmSurface,
939
  reveal,
940
  }, ref) {
941
  const { databases, introspection } = detail;
 
953
  const [busy, setBusy] = useState("");
954
  const [confirmOff, setConfirmOff] = useState<ConnectorDatabase | null>(null);
955
  const [refusals, setRefusals] = useState<Record<string, string>>({});
956
+ const [refusalDependents, setRefusalDependents] = useState<Record<string, DependentKind[]>>({});
957
+ const [pendingDestination, setPendingDestination] = useState<string | null>(null);
958
  const [autoEnableResults, setAutoEnableResults] = useState<Record<string, string>>(
959
  () => reveal?.key && reveal.status ? { [reveal.key]: reveal.status } : {}
960
  );
 
962
  const [jobs, setJobs] = useState<MaterializationJob[]>([]);
963
  const [jobError, setJobError] = useState("");
964
  const [retrying, setRetrying] = useState("");
965
+ const capability = row.key === "amazon_sp" ? null : detail.materialization;
966
+ const syncNow = useSyncNow(detail.syncNow);
967
+ const showsAmazonSync = row.key === "amazon_sp" && introspection.fieldsVisible;
968
+ const amazonSync = useAmazonSyncStates(showsAmazonSync, detail, syncNow.receipt?.state);
969
  useEffect(() => {
970
  if (!capability) return;
971
  return watchMaterialization(capability, (next, message) => {
 
1052
  setBusy(database.key);
1053
  setError("");
1054
  setRefusals((current) => ({ ...current, [database.key]: "" }));
1055
+ setRefusalDependents((current) => ({ ...current, [database.key]: [] }));
1056
  setAutoEnableResults((current) => ({ ...current, [database.key]: "" }));
1057
  if (!next) {
1058
  const answer = await readDependents(database.key);
 
1069
  // The server's sentence, verbatim. C3 omits every zero-count kind, so this cannot
1070
  // claim a count it does not have.
1071
  setRefusals((current) => ({ ...current, [database.key]: answer.refusal }));
1072
+ setRefusalDependents((current) => ({ ...current, [database.key]: answer.dependents }));
1073
  return;
1074
  }
1075
  if (!usesProviderEnablement) {
 
1130
  onPendingChange(0);
1131
  }, [onPendingChange]);
1132
 
1133
+ const openDependent = (event: MouseEvent<HTMLAnchorElement>, href: string) => {
1134
+ if (busy) {
1135
+ event.preventDefault();
1136
+ return;
1137
+ }
1138
+ // Hash navigation never fires beforeunload. Reuse the modal's discard wording
1139
+ // and ConfirmDialog surface registration without extending its prop contract.
1140
+ if (pendingCount || renaming) {
1141
+ event.preventDefault();
1142
+ setPendingDestination(href);
1143
+ }
1144
+ };
1145
+
1146
  const savePending = useCallback(async () => {
1147
  const snapshot = pending;
1148
  if (!pendingChangeCount(snapshot)) return;
 
1229
  onPendingChange(pendingChangeCount(failed));
1230
  setBusy("");
1231
  setError(failures.join(" "));
1232
+ if (detail.materialization && row.key !== "amazon_sp") watchMaterialization(detail.materialization);
1233
  // One batch gets one fresh detail payload. That payload also carries the newly derived graph.
1234
  onChanged();
1235
  }, [databases, detail.enablement, detail.materialization, onChanged, onPendingChange, pending, row.key]);
 
1270
  onChanged();
1271
  }, [onChanged]);
1272
 
1273
+ const showCensus = showsPopulation && introspection.fieldsVisible;
1274
+ const header = showCensus || detail.syncNow ? (
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1275
  <div className="conn-db-head">
1276
  <div>
1277
+ {showCensus ? <>
1278
  <p className="conn-db-note" id="odoo-census-warning">
1279
  Count rows stops at 101 rows per source table and displays 100+ from 100 onward.
1280
  Each table still needs a request, so this can take about a minute or longer.
 
1293
  )}
1294
  </p>
1295
  ) : null}
1296
+ </> : null}
1297
+ {detail.syncNow ? (
1298
+ <p className={syncNow.receipt?.state === "failed" ? "conn-db-error" : "conn-db-note"}
1299
+ role="status" aria-live="polite">
1300
+ {syncNow.receipt?.state === "queued" ? "Sync queued."
1301
+ : syncNow.receipt?.state === "running" ? "Sync running."
1302
+ : syncNow.receipt?.state === "done" ? "Sync finished."
1303
+ : syncNow.receipt?.state === "failed" ? `Sync failed. ${syncNow.receipt.detail}`
1304
+ : syncNow.busy ? "Checking sync progress..." : ""}
1305
+ </p>
1306
+ ) : null}
1307
+ {detail.syncNow && syncNow.message ? (
1308
+ <p className="conn-db-error" role="alert">{syncNow.message}</p>
1309
+ ) : null}
1310
  </div>
1311
+ {detail.syncNow ? (
1312
+ <button type="button" className="conn-db-count-action" disabled={syncNow.busy}
1313
+ onClick={() => void syncNow.start()}>
1314
+ Sync now
1315
+ </button>
1316
+ ) : null}
1317
+ {showCensus ? <>
1318
  <button
1319
  type="button"
1320
  className="conn-db-count-action"
 
1333
  >
1334
  Exact totals
1335
  </button>
1336
+ </> : null}
1337
  </div>
1338
+ ) : null;
1339
+
1340
+ if (!introspection.introspectable) {
1341
+ return <div className="conn-db">{header}<DatabasesUnavailable row={row} reason={introspection.reason} /></div>;
1342
+ }
1343
+
1344
+ if (!databases.length) {
1345
+ // Sync now remains reachable before the first schema has arrived.
1346
+ return (
1347
+ <div className="conn-db">
1348
+ {header}
1349
+ <p className="conn-db-note">
1350
+ This connection has not declared any databases in this workspace. Connect it from the
1351
+ Keychain tab to read its schema.
1352
+ </p>
1353
+ </div>
1354
+ );
1355
+ }
1356
+
1357
+ return (
1358
+ <div className="conn-db">
1359
+ {header}
1360
  {error ? (
1361
  <p className="conn-db-error" role="alert">
1362
  {error}
 
1462
  {job?.error ? <span className="conn-job-error">{job.error}</span> : null}
1463
  </div>
1464
  ) : null}
1465
+ {showsAmazonSync ? <AmazonSyncChip state={amazonSync.states[database.key]}
1466
+ error={amazonSync.error} /> : null}
1467
  </td>
1468
  <td>
1469
  <button
 
1543
  <p className="conn-db-refusal" role="alert">
1544
  {refusal}
1545
  </p>
1546
+ {/* The named dependents sit under the sentence, indented to its text edge:
1547
+ `.conn-db-refusal` is 8px 10px inside a 3px left rule, so 13px lines the
1548
+ two up. The class lives in another lane's stylesheet, so the inset is
1549
+ declared here rather than by editing a file this ticket does not own. */}
1550
+ {(refusalDependents[database.key] || []).length ? (
1551
+ <ul className="conn-db-note"
1552
+ style={{ listStyle: "none", margin: "4px 0 0", padding: "0 0 0 13px" }}>
1553
+ {(refusalDependents[database.key] || []).flatMap((dependent, kindIndex) =>
1554
+ dependentRows(dependent).map((item, itemIndex) => (
1555
+ <li key={`${kindIndex}:${item.id}:${itemIndex}`}>
1556
+ {item.href ? (
1557
+ <a className="conn-db-link" href={item.href}
1558
+ onClick={(event) => openDependent(event, item.href!)}>
1559
+ {item.label}
1560
+ </a>
1561
+ ) : (
1562
+ <>{item.label}: {item.reason || "This dependent has no direct address available."}</>
1563
+ )}
1564
+ </li>
1565
+ ))
1566
+ )}
1567
+ </ul>
1568
+ ) : null}
1569
  </td>
1570
  </tr>
1571
  ) : null}
 
1590
  );
1591
  })}
1592
  </table>
1593
+ <ConfirmDialog
1594
+ open={pendingDestination !== null}
1595
+ title="Discard unsaved changes"
1596
+ body={<p>{pendingCount === 1
1597
+ ? "You have 1 unsaved change to this connection."
1598
+ : pendingCount ? `You have ${pendingCount} unsaved changes to this connection.`
1599
+ : "You have an unfinished database name change."}</p>}
1600
+ confirmLabel="Discard changes"
1601
+ tone="destructive"
1602
+ onConfirm={() => {
1603
+ const destination = pendingDestination;
1604
+ setPendingDestination(null);
1605
+ discardPending();
1606
+ if (destination) window.location.hash = destination;
1607
+ }}
1608
+ onCancel={() => setPendingDestination(null)}
1609
+ surfaceRef={onConfirmSurface}
1610
+ />
1611
  <ConfirmDialog
1612
  open={confirmOff !== null}
1613
  title="Switch off this database"
 
1627
  setConfirmOff(null);
1628
  }}
1629
  onCancel={() => setConfirmOff(null)}
1630
+ surfaceRef={onConfirmSurface}
1631
  />
1632
  </div>
1633
  );
web/src/customer-grid/ColumnMenu.tsx CHANGED
@@ -196,6 +196,10 @@ interface ColumnMenuProps {
196
  locked: boolean;
197
  /** Product-owned preset fields may still drive view actions, but their schema is immutable. */
198
  schemaLocked?: boolean;
 
 
 
 
199
  /**
200
  * ⭐⭐ W40-T24 — the grid is a `ut_*` runtime database rather than an Odoo-backed topic. It
201
  * feeds `columnDefinitionOffer` (display.ts), which is this menu's ONE statement of the pre-set
@@ -472,7 +476,7 @@ type CreatePosition = "left" | "right" | "end";
472
  * choices/stars/formula config), and the Change-field control that swaps the column to show
473
  * another field.
474
  */
475
- type MenuPane = "menu" | "edit" | "format" | "summary" | "showAs";
476
 
477
  /**
478
  * How each creatable type reads in the menu. DERIVED from CREATABLE_TYPES rather than listed
@@ -2511,6 +2515,9 @@ export default function ColumnMenu({
2511
  geocodable,
2512
  locked,
2513
  schemaLocked = false,
 
 
 
2514
  isUserTable = false,
2515
  viewer,
2516
  sortedDir,
@@ -2578,7 +2585,7 @@ export default function ColumnMenu({
2578
  * refusal in this file could only subtract from a door the host deliberately opened.
2579
  */
2580
  const offer = columnDefinitionOffer(field, { isUserTable, isPrimary: locked });
2581
- const canEditDefinition = !schemaLocked && mayEditFieldDefinition(field, viewer);
2582
  /**
2583
  * ⭐⭐ W41-T31 (owner instruction 1, ruling R19) — THE DESCRIPTION-ONLY DOOR.
2584
  *
@@ -2602,7 +2609,7 @@ export default function ColumnMenu({
2602
  * gate — but it is the handler the whole pane exists to reach, and `typeof` is how you write
2603
  * that without TS2774 ("this condition will always return true").
2604
  */
2605
- const canEditDescription = schemaLocked && typeof onNote === "function";
2606
  /**
2607
  * Either door opens the Edit-field pane; WHICH pane is decided at the render, below. Read by
2608
  * the menu row and by the seed, so the two can never disagree about whether it is on offer.
@@ -2615,12 +2622,13 @@ export default function ColumnMenu({
2615
  */
2616
  const editPaneOffered = canEditDefinition || canEditDescription;
2617
  const [pane, setPane] = useState<MenuPane>(
2618
- initialPane === "edit"
2619
  ? (editPaneOffered ? "edit" : "menu")
2620
  : (schemaLocked ? "menu" : initialPane ?? "menu")
2621
  );
2622
  const [note, setNote] = useState(field.note ?? "");
2623
- const [position, setPosition] = useState<CreatePosition | null>(initialPosition ?? null);
 
2624
  /** Delete is DESTRUCTIVE (a custom field's stored values go with it) — first click arms,
2625
  * second click fires. Reopening the menu disarms (state is per-mount, keyed by field). */
2626
  const [label, setLabel] = useState("");
@@ -3575,6 +3583,8 @@ export default function ColumnMenu({
3575
  * Item 6 — Insert left/right (and Add at end) jump STRAIGHT to the create form: name + type
3576
  * autofocused, and none of the note/change-field/other-column chrome rendered around it.
3577
  */
 
 
3578
  if (position) {
3579
  return (
3580
  <AnchoredOverlay
@@ -4743,6 +4753,52 @@ export default function ColumnMenu({
4743
  );
4744
  }
4745
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4746
  // ------------------------------------------------------------------ the MENU pane
4747
  // Wave-5 items 1/2/3: a flat action list. Editors open their OWN windows (the panes above);
4748
  // nothing edits inline here. Conditional entries render IFF they apply to the current view.
@@ -4852,10 +4908,11 @@ export default function ColumnMenu({
4852
  onDismiss={onClose}
4853
  role="dialog"
4854
  ariaLabel={`Column settings for ${field.label}`}
4855
- initialFocus="[data-overlay-autofocus]"
 
4856
  dataKind="column-menu"
4857
  >
4858
- <PaneHead title={field.label} sub={typeLine} onClose={onClose} />
4859
  {/* Item 8c — any measure-carrying column exposes its PERIOD, the property that defines
4860
  it. Item 21 (2026-08-02) moved the EDITOR into the Edit-field pane; what stays here
4861
  is one line that STATES the period and opens that pane, because the window is the
@@ -4879,6 +4936,7 @@ export default function ColumnMenu({
4879
  an icon on EVERY action. Presentation only — every handler and event is the one it
4880
  was before; entries not in Airtable's list slot into the nearest sensible group. */}
4881
  <div className="cg-column-actions">
 
4882
  {/* Owner item 8 (2026-07-31) — EDIT FIELD sits at the very top, above Duplicate:
4883
  the one window for the field's name, type (with per-type choices/stars/formula)
4884
  and the Change-field control. Offered on EVERY field — what a read-only field
@@ -5057,6 +5115,8 @@ export default function ColumnMenu({
5057
 
5058
  <div className="cg-menu-sep" role="separator" aria-hidden />
5059
 
 
 
5060
  {/* Group 3 — sort. Direction wording stays the shipped per-type directionLabel. */}
5061
  {onSort && fieldOfferable && <>
5062
  <button type="button" onClick={() => { onSort("asc"); onClose(); }}>
@@ -5109,12 +5169,12 @@ export default function ColumnMenu({
5109
  )}
5110
  {/* Item 11c — pin: freeze the columns up to this one; Unpin restores the identity
5111
  column alone. */}
5112
- {onPinTo && !pinnedTo && (
5113
  <button type="button" onClick={() => { onPinTo(); onClose(); }}>
5114
  <MenuLabel icon="pin" text="Pin up to this field" />
5115
  </button>
5116
  )}
5117
- {onUnpin && (
5118
  <button type="button" onClick={() => { onUnpin(); onClose(); }}>
5119
  <MenuLabel icon="unpin" text="Unpin all fields" />
5120
  </button>
@@ -5122,6 +5182,15 @@ export default function ColumnMenu({
5122
 
5123
  <div className="cg-menu-sep" role="separator" aria-hidden />
5124
 
 
 
 
 
 
 
 
 
 
5125
  {/* Group 5 — hide · delete. */}
5126
  <button
5127
  type="button"
@@ -5131,6 +5200,7 @@ export default function ColumnMenu({
5131
  >
5132
  <MenuLabel icon="hide" text="Hide field" />
5133
  </button>
 
5134
  {/* ⭐⭐ WAVE-34 (owner ruling R13) — THE BULK RUN, and it is TWO rows rather than one
5135
  because "run this column" is two different questions with two different bills.
5136
  ⛔ NEITHER LABEL SAYS "everything". `ai_enrich_may_write` refuses a human-edited cell
@@ -5300,6 +5370,7 @@ export default function ColumnMenu({
5300
  Only {deleteOwner} or an administrator can delete this field.
5301
  </p>
5302
  )}
 
5303
  </div>
5304
  </AnchoredOverlay>
5305
  );
 
196
  locked: boolean;
197
  /** Product-owned preset fields may still drive view actions, but their schema is immutable. */
198
  schemaLocked?: boolean;
199
+ /** Linked grids expose personal layout actions only, even when edit callbacks exist. */
200
+ embedded?: boolean;
201
+ columnWidth?: number;
202
+ onColumnWidth?: (width: number) => void;
203
  /**
204
  * ⭐⭐ W40-T24 — the grid is a `ut_*` runtime database rather than an Odoo-backed topic. It
205
  * feeds `columnDefinitionOffer` (display.ts), which is this menu's ONE statement of the pre-set
 
476
  * choices/stars/formula config), and the Change-field control that swaps the column to show
477
  * another field.
478
  */
479
+ type MenuPane = "menu" | "edit" | "format" | "summary" | "showAs" | "width";
480
 
481
  /**
482
  * How each creatable type reads in the menu. DERIVED from CREATABLE_TYPES rather than listed
 
2515
  geocodable,
2516
  locked,
2517
  schemaLocked = false,
2518
+ embedded = false,
2519
+ columnWidth = 160,
2520
+ onColumnWidth,
2521
  isUserTable = false,
2522
  viewer,
2523
  sortedDir,
 
2585
  * refusal in this file could only subtract from a door the host deliberately opened.
2586
  */
2587
  const offer = columnDefinitionOffer(field, { isUserTable, isPrimary: locked });
2588
+ const canEditDefinition = !embedded && !schemaLocked && mayEditFieldDefinition(field, viewer);
2589
  /**
2590
  * ⭐⭐ W41-T31 (owner instruction 1, ruling R19) — THE DESCRIPTION-ONLY DOOR.
2591
  *
 
2609
  * gate — but it is the handler the whole pane exists to reach, and `typeof` is how you write
2610
  * that without TS2774 ("this condition will always return true").
2611
  */
2612
+ const canEditDescription = !embedded && schemaLocked && typeof onNote === "function";
2613
  /**
2614
  * Either door opens the Edit-field pane; WHICH pane is decided at the render, below. Read by
2615
  * the menu row and by the seed, so the two can never disagree about whether it is on offer.
 
2622
  */
2623
  const editPaneOffered = canEditDefinition || canEditDescription;
2624
  const [pane, setPane] = useState<MenuPane>(
2625
+ embedded ? "menu" : initialPane === "edit"
2626
  ? (editPaneOffered ? "edit" : "menu")
2627
  : (schemaLocked ? "menu" : initialPane ?? "menu")
2628
  );
2629
  const [note, setNote] = useState(field.note ?? "");
2630
+ const [position, setPosition] = useState<CreatePosition | null>(embedded ? null : initialPosition ?? null);
2631
+ const [widthDraft, setWidthDraft] = useState(String(Math.round(columnWidth)));
2632
  /** Delete is DESTRUCTIVE (a custom field's stored values go with it) — first click arms,
2633
  * second click fires. Reopening the menu disarms (state is per-mount, keyed by field). */
2634
  const [label, setLabel] = useState("");
 
3583
  * Item 6 — Insert left/right (and Add at end) jump STRAIGHT to the create form: name + type
3584
  * autofocused, and none of the note/change-field/other-column chrome rendered around it.
3585
  */
3586
+ // R8: a retained pane or a caller-supplied initial pane cannot expose schema controls.
3587
+ if (!embedded) {
3588
  if (position) {
3589
  return (
3590
  <AnchoredOverlay
 
4753
  );
4754
  }
4755
 
4756
+ }
4757
+
4758
+ if (embedded && pane === "width" && onColumnWidth) {
4759
+ const width = Number(widthDraft);
4760
+ const validWidth = widthDraft.trim() !== "" && Number.isFinite(width) && width >= 50 && width <= 600;
4761
+ return (
4762
+ <AnchoredOverlay
4763
+ anchor={state.anchor}
4764
+ className="cg-column-menu"
4765
+ onDismiss={onClose}
4766
+ dismissOnOutside={false}
4767
+ role="dialog"
4768
+ ariaLabel={`Column width for ${field.label}`}
4769
+ initialFocus="[data-overlay-autofocus]"
4770
+ dataKind="column-menu"
4771
+ >
4772
+ <PaneHead title="Column width" sub={field.label} onClose={onClose} />
4773
+ <form className="cg-column-create cg-field-edit" onSubmit={(event) => {
4774
+ event.preventDefault();
4775
+ if (!validWidth) return;
4776
+ onColumnWidth(Math.round(width));
4777
+ onClose();
4778
+ }}>
4779
+ <label>
4780
+ <span>Width (px)</span>
4781
+ <input
4782
+ className="cg-input"
4783
+ type="number"
4784
+ min={50}
4785
+ max={600}
4786
+ step={1}
4787
+ required
4788
+ data-overlay-autofocus
4789
+ value={widthDraft}
4790
+ onChange={(event) => setWidthDraft(event.target.value)}
4791
+ />
4792
+ </label>
4793
+ <div className="cg-form-actions">
4794
+ <button type="submit" className="cg-btn cg-btn--primary" disabled={!validWidth}>Apply</button>
4795
+ <button type="button" className="cg-btn" onClick={() => setPane("menu")}>Back</button>
4796
+ </div>
4797
+ </form>
4798
+ </AnchoredOverlay>
4799
+ );
4800
+ }
4801
+
4802
  // ------------------------------------------------------------------ the MENU pane
4803
  // Wave-5 items 1/2/3: a flat action list. Editors open their OWN windows (the panes above);
4804
  // nothing edits inline here. Conditional entries render IFF they apply to the current view.
 
4908
  onDismiss={onClose}
4909
  role="dialog"
4910
  ariaLabel={`Column settings for ${field.label}`}
4911
+ initialFocus={embedded ? "first" : "[data-overlay-autofocus]"}
4912
+ dismissOnOutside={!embedded}
4913
  dataKind="column-menu"
4914
  >
4915
+ <PaneHead title={field.label} sub={embedded ? undefined : typeLine} onClose={onClose} />
4916
  {/* Item 8c — any measure-carrying column exposes its PERIOD, the property that defines
4917
  it. Item 21 (2026-08-02) moved the EDITOR into the Edit-field pane; what stays here
4918
  is one line that STATES the period and opens that pane, because the window is the
 
4936
  an icon on EVERY action. Presentation only — every handler and event is the one it
4937
  was before; entries not in Airtable's list slot into the nearest sensible group. */}
4938
  <div className="cg-column-actions">
4939
+ {!embedded && <>
4940
  {/* Owner item 8 (2026-07-31) — EDIT FIELD sits at the very top, above Duplicate:
4941
  the one window for the field's name, type (with per-type choices/stars/formula)
4942
  and the Change-field control. Offered on EVERY field — what a read-only field
 
5115
 
5116
  <div className="cg-menu-sep" role="separator" aria-hidden />
5117
 
5118
+ </>}
5119
+
5120
  {/* Group 3 — sort. Direction wording stays the shipped per-type directionLabel. */}
5121
  {onSort && fieldOfferable && <>
5122
  <button type="button" onClick={() => { onSort("asc"); onClose(); }}>
 
5169
  )}
5170
  {/* Item 11c — pin: freeze the columns up to this one; Unpin restores the identity
5171
  column alone. */}
5172
+ {!embedded && onPinTo && !pinnedTo && (
5173
  <button type="button" onClick={() => { onPinTo(); onClose(); }}>
5174
  <MenuLabel icon="pin" text="Pin up to this field" />
5175
  </button>
5176
  )}
5177
+ {!embedded && onUnpin && (
5178
  <button type="button" onClick={() => { onUnpin(); onClose(); }}>
5179
  <MenuLabel icon="unpin" text="Unpin all fields" />
5180
  </button>
 
5182
 
5183
  <div className="cg-menu-sep" role="separator" aria-hidden />
5184
 
5185
+ {embedded && onColumnWidth && (
5186
+ <button type="button" onClick={() => {
5187
+ setWidthDraft(String(Math.round(columnWidth)));
5188
+ setPane("width");
5189
+ }}>
5190
+ <MenuLabel icon="format" text="Column width" />
5191
+ </button>
5192
+ )}
5193
+
5194
  {/* Group 5 — hide · delete. */}
5195
  <button
5196
  type="button"
 
5200
  >
5201
  <MenuLabel icon="hide" text="Hide field" />
5202
  </button>
5203
+ {!embedded && <>
5204
  {/* ⭐⭐ WAVE-34 (owner ruling R13) — THE BULK RUN, and it is TWO rows rather than one
5205
  because "run this column" is two different questions with two different bills.
5206
  ⛔ NEITHER LABEL SAYS "everything". `ai_enrich_may_write` refuses a human-edited cell
 
5370
  Only {deleteOwner} or an administrator can delete this field.
5371
  </p>
5372
  )}
5373
+ </>}
5374
  </div>
5375
  </AnchoredOverlay>
5376
  );
web/src/customer-grid/CustomerGrid.tsx CHANGED
@@ -26,7 +26,7 @@ import type {
26
  } from "@glideapps/glide-data-grid";
27
  import "@glideapps/glide-data-grid/dist/index.css";
28
 
29
- import { useCustomerData } from "./useCustomerData";
30
  import type { SurfaceScope } from "./apiBridge";
31
  import { mutateQueryWorkspace, QUERY_BINDING_EVENT, refuseQueryMutation } from "../query/queryApi";
32
  import type { QueryVirtualBinding } from "../query/queryApi";
@@ -34,7 +34,7 @@ import { acceptsQueryPreview, routeQueryViewMutation } from "./queryPreview";
34
  // ⭐ WAVE 30 · W30-T42 (contract C2) — the WINDOWED grid's arithmetic, pure and node-run in
35
  // `verify_grid_ux.py`, because every one of these decisions is taken inside a callback where
36
  // only its own source text could otherwise be checked.
37
- import { WINDOW_ROWS, fetchAggregates } from "./apiBridge";
38
  // ⭐⭐ W50-T03 / CONTRACT C1 — the windowed aggregate's envelope. Lane F serves the route
39
  // (W50-T31); this side is written to C1's shape and degrades to the loaded window until it
40
  // lands, which is the done-when's own observable rather than a workaround.
@@ -124,7 +124,7 @@ import ViewSidebar, { viewMoveRefusal } from "./ViewSidebar";
124
  import ColumnMenu from "./ColumnMenu";
125
  import type { ColumnMenuState } from "./ColumnMenu";
126
  import { HEADER_ICONS } from "./iconShapes";
127
- import { emitHostEvent, eventId } from "./hostBridge";
128
  // ⭐ WAVE 27 item 21 (R14) — which of this table's views carry an alert. The SERVER's
129
  // list is the only answer; the rail's alert door is a one-way create.
130
  import { fetchAlerts } from "../alerts/alertsApi";
@@ -857,7 +857,7 @@ export interface FieldBulkDoorDeps {
857
  lockedKey: string;
858
  fieldByKey: Map<string, Field>;
859
  isUserTable: boolean;
860
- scope: string;
861
  rowsPath: string;
862
  setFields: (update: (current: Field[]) => Field[]) => void;
863
  stampFieldDelete: (key: string) => void;
@@ -894,6 +894,7 @@ function reportFieldDeleteRefusals(
894
  export function useFieldBulkDoors(deps: FieldBulkDoorDeps): FieldBulkDoors {
895
  const { config, updateConfig, order, visible, lockedKey, fieldByKey, isUserTable, scope,
896
  rowsPath, setFields, stampFieldDelete } = deps;
 
897
  const onSetFieldsHidden = useCallback((keys: string[], hidden: boolean) => {
898
  const next = new Set(visible);
899
  for (const key of keys) {
@@ -948,7 +949,7 @@ export function useFieldBulkDoors(deps: FieldBulkDoorDeps): FieldBulkDoors {
948
  }
949
  })();
950
  }, [config, fieldByKey, isUserTable, lockedKey, order, rowsPath, scope, setFields,
951
- stampFieldDelete, updateConfig, visible]);
952
 
953
  const onShareFields = useCallback((keys: string[]) => {
954
  if (keys.length > 0) signal(TOAST_EVENT,
@@ -1640,6 +1641,12 @@ export function serverGroupHeaders(
1640
  });
1641
  }
1642
 
 
 
 
 
 
 
1643
  interface CustomerGridProps {
1644
  scope?: SurfaceScope;
1645
  /** Shell-owned Data workspace location; grid resolves its view/field, never the global rail. */
@@ -1658,6 +1665,8 @@ interface CustomerGridProps {
1658
  /** Read-only Grid view embedded in a linked-record modal. It keeps the standard
1659
  * filter/sort/search toolbar while withdrawing schema and row mutations. */
1660
  embedded?: boolean;
 
 
1661
  /** Complete caller-scoped projection for an embedded grid. Null withholds rows while
1662
  * loading/refused; undefined retains the ordinary target reader. */
1663
  embeddedPayload?: CustomersPayload | null;
@@ -1680,10 +1689,9 @@ interface CustomerGridProps {
1680
  * | `embedded` | HIDDEN (`hostViews = []`) | the WHOLE table | filtered CLIENT-side |
1681
  * | **`related`** | **SHOWN, the target's own** | **server, PRE-FILTERED** | **only linked** |
1682
  *
1683
- * ⛔⛔ `related` IS NOT ROUTED THROUGH `embedded`, AND THAT IS THE WHOLE TICKET. `embedded`
1684
- * keeps hiding the rail and keeps fetching whole tables; R5 asks for the OTHER DATABASE'S OWN
1685
- * SAVED VIEWS, its rail included, with the record pinned. So this mode leaves every
1686
- * `embedded` guard alone and narrows the READ instead.
1687
  *
1688
  * `label` is the pinned record's NAME and is display-only: the chip reads "Linked to
1689
  * <label>". ⛔ It never reaches the wire (`RelatedPin` has no `label`) and it is never
@@ -1706,6 +1714,8 @@ interface CustomerGridProps {
1706
  cellFields?: string[];
1707
  /** Report a filter edit from the cell View data surface; its Sheet caller owns settling. */
1708
  onCellFilterChange?: (tree: FilterTree) => void;
 
 
1709
  /**
1710
  * ⭐ W51-T06 clause 9 — a row click NAVIGATES the record view instead of opening this grid's
1711
  * own drawer.
@@ -1728,9 +1738,8 @@ interface CustomerGridProps {
1728
  * `readLocal(storageKey)`. R2 gives two links between the same pair two tabs, so two tabs can
1729
  * target one database; a memory keyed by `storageKey` would make them share one answer and
1730
  * each would reopen on the other's view.
1731
- * ⛔ AND NOTHING NEW IS STORED SERVER-SIDE (R5's load-bearing clause): the view itself is the
1732
- * target database's own saved view, and what is remembered is only WHICH of them was last
1733
- * open, in this browser.
1734
  */
1735
  relatedViewId?: string;
1736
  onRelatedViewChange?: (viewId: string) => void;
@@ -1768,6 +1777,8 @@ interface LinkGridModalProps {
1768
  cellFields?: string[];
1769
  /** W56-T25: report a grid filter edit so the Sheet caller can settle and persist it. */
1770
  onCellFilterChange?: (tree: FilterTree) => void;
 
 
1771
  /** W56-T24: chrome the caller owns, in the header, right of the title and left of Close. */
1772
  headerActions?: ReactNode;
1773
  /** W56-T24: a statement under the rows. Only rendered on a non-editable modal. */
@@ -1782,7 +1793,8 @@ interface LinkGridModalProps {
1782
  // the two surfaces cannot drift into two popups that behave almost alike. W56-T24 adds optional
1783
  // chrome slots and a `cellView` modifier while leaving existing callers and the focus trap intact.
1784
  export function LinkGridModal({ label, table, recordIds, editable = false, single = false,
1785
- excludeRecordId, cellView = false, cellFilter, cellFields, onCellFilterChange, headerActions, footer,
 
1786
  onOpenRecord, onSave, onClose }: LinkGridModalProps) {
1787
  const panelRef = useRef<HTMLDivElement>(null);
1788
  const [selectedIds, setSelectedIds] = useState<number[]>(() => [...recordIds]);
@@ -1841,6 +1853,7 @@ export function LinkGridModal({ label, table, recordIds, editable = false, singl
1841
  cellFilter={cellFilter}
1842
  cellFields={cellFields}
1843
  onCellFilterChange={onCellFilterChange}
 
1844
  embeddedRecordIds={editable ? undefined : recordIds}
1845
  embeddedExcludeRecordId={editable ? excludeRecordId : undefined}
1846
  embeddedSelectable={editable}
@@ -1984,7 +1997,8 @@ function CustomerGridSurface({
1984
  renderDatabaseActions,
1985
  databaseCreateControl,
1986
  queryBinding,
1987
- embedded = false,
 
1988
  embeddedPayload,
1989
  embeddedRecordIds,
1990
  embeddedSelectable = false,
@@ -1996,10 +2010,18 @@ function CustomerGridSurface({
1996
  cellFilter,
1997
  cellFields,
1998
  onCellFilterChange,
 
1999
  onOpenRecord,
2000
  relatedViewId,
2001
  onRelatedViewChange,
2002
  }: CustomerGridProps = {}) {
 
 
 
 
 
 
 
2003
  const isQueryPreview = queryBinding !== undefined;
2004
  const isApplicationSurface = !!dataPath?.application && !embedded && !isQueryPreview;
2005
  /**
@@ -2030,8 +2052,8 @@ function CustomerGridSurface({
2030
  * the SOURCE database's own locks**, which is the predicate that does the work now.
2031
  *
2032
  * ⛔ TWO QUESTIONS, NOT ONE, AND CONFLATING THEM IS WHAT MADE THE SINGLE FLAG WRONG:
2033
- * · **`embedded`** — *may this surface WRITE anything at all?* A linked-record grid inside a
2034
- * modal may not, and keeps every refusal it has today. Unchanged, deliberately.
2035
  * · **`hostWorkspace`** — *does this surface own the SOURCE DATABASE's workspace?* Its views,
2036
  * its `storageKey`, its view rail, its alert list. **A Query surface does NOT**, and that
2037
  * has nothing to do with read-only: the artefact has its own single view, its own storage
@@ -2059,13 +2081,11 @@ function CustomerGridSurface({
2059
  clearAssignedView,
2060
  } = useCustomerData(scope, {
2061
  embeddedPayload: embedded ? embeddedPayload : undefined,
2062
- // ⚠ `bindSurface` is the MODULE-scope write target every emitted event carries. A Query
2063
- // surface's cell edits belong to the SOURCE database, so it must bind — the linked-record
2064
- // grid must not, because its parent still owns that scope.
2065
  bindSurface: !embedded,
2066
  // ⛔ The one flag that stays on the WIDE predicate: neither surface reads the source
2067
  // database's own saved views.
2068
- includeWorkspace: hostWorkspace,
2069
  // `writable: false` blocks `patchOverlay`, i.e. every cell edit. R2 wants them in Query.
2070
  writable: !embedded,
2071
  /* ⭐⭐ W51-T06 / C6 / R5 — THE PINNED READ. Not a fourth flag beside the three above: those
@@ -2628,7 +2648,9 @@ function CustomerGridSurface({
2628
  * ⚠ Existing browsers lose the contents of the old global localStorage bucket. That is the point: every
2629
  * byte in it is a workspace some other surface persisted, and there is no way to tell whose.
2630
  */
2631
- const storageKey = isQueryPreview && queryBinding
 
 
2632
  ? `query:${queryBinding.workspaceBinding.key}`
2633
  : payload?.workspace?.storageKey ?? `${LOCAL_KEY_PREFIX}${scope}`;
2634
  // A parent may rebuild an equivalent tree on every render. Depend on its value, not its identity,
@@ -2640,6 +2662,7 @@ function CustomerGridSurface({
2640
  // fills only missing objects and keeps the standalone path useful.
2641
  useEffect(() => {
2642
  if (!payload || payloadFields.length === 0 || initializedKey.current === storageKey) return;
 
2643
  if (isApplicationSurface) {
2644
  // App presentation is local to this mount. Never adopt a saved View, its selection, or
2645
  // its local-storage echo; the App's registry definition is applied after these fields load.
@@ -2698,13 +2721,15 @@ function CustomerGridSurface({
2698
  payload.workspace != null
2699
  );
2700
  const hostViews = embedded ? [] : payload.workspace?.views ?? [];
 
 
2701
  const byId = new Map<string, SavedView>();
2702
  byId.set(ALL_VIEW_ID, allRecordsView(initialFields, scope));
2703
  // D-19 — the HOST'S LIST DECIDES WHICH VIEWS EXIST. A local copy the host no longer
2704
  // names is a ghost (deleted elsewhere, share revoked, store moved) and is dropped here,
2705
  // guarded by this browser's own recent writes so an optimistic create survives.
2706
  viewWritesRef.current = pruneTombstones(local?.viewWrites, Date.now());
2707
- for (const view of seedLocalViews(local?.views ?? [], hostViews, viewWritesRef.current,
2708
  Date.now(), payload.workspace != null))
2709
  byId.set(view.id, view);
2710
  // Host state wins — EXCEPT when it is a lagged echo of this browser's own
@@ -2725,7 +2750,7 @@ function CustomerGridSurface({
2725
  // every host round trip was itself a remount.
2726
  const tombstones = pruneTombstones(local?.viewTombstones, Date.now());
2727
  viewTombstonesRef.current = tombstones;
2728
- for (const view of hostViews) {
2729
  // Both doors, the `reconcileFields` rule: a tombstone drops the host copy AND any
2730
  // local copy, so a delete that raced localStorage cannot re-enter through either.
2731
  if (tombstones[view.id] !== undefined) {
@@ -2761,8 +2786,8 @@ function CustomerGridSurface({
2761
  * the answer down; this is the one place it can be honoured, because it has to be resolved
2762
  * against `initialViews` like every other rung (a remembered view that has since been
2763
  * deleted falls through to `initialViews[0]` rather than showing an empty grid).
2764
- * ⛔ AND NOTHING NEW IS STORED (R5): the memory is `localStorage`, per person, per browser.
2765
- * No server record learns which tab anybody last looked at.
2766
  */
2767
  const requested = resolveActiveView(
2768
  { id: local?.activeViewId, at: local?.activeViewAt },
@@ -2790,7 +2815,7 @@ function CustomerGridSurface({
2790
  setFields(initialFields);
2791
  setViews(initialViews);
2792
  setActiveViewId(active.id);
2793
- setConfig(cellView && cellFilter ? {
2794
  ...active.config,
2795
  filters: cellFilter.nodes ?? [],
2796
  filterConj: cellFilter.conj ?? "and",
@@ -2798,7 +2823,10 @@ function CustomerGridSurface({
2798
  order: [...cellFields, ...active.config.order.filter((key) => !cellFields.includes(key))],
2799
  visible: cellFields,
2800
  } : {}),
2801
- } : active.config);
 
 
 
2802
  setWorkspaceReady(true);
2803
  initializedKey.current = storageKey;
2804
 
@@ -2839,18 +2867,19 @@ function CustomerGridSurface({
2839
  reemittedRef.current = { ...(local?.reemitted ?? {}) };
2840
  }
2841
  }, [payload, payloadFields, storageKey, hostWorkspace, scope, isQueryPreview, queryBinding, isApplicationSurface,
2842
- cellView, cellFilterKey, cellFieldsKey]);
2843
 
2844
  // Initialization runs once per scope. Keep the columns current after a cell filter settles,
2845
  // retaining hidden keys in the order so the reader can show them again.
2846
  useEffect(() => {
2847
  if (!workspaceReady || !cellView || !cellFields?.length) return;
 
2848
  setConfig((current) => ({
2849
  ...current,
2850
  order: [...cellFields, ...current.order.filter((key) => !cellFields.includes(key))],
2851
  visible: cellFields,
2852
  }));
2853
- }, [workspaceReady, cellView, cellFieldsKey]);
2854
 
2855
  /**
2856
  * ⭐ W36-T03 — the view-preference stamp, and it is its OWN effect on purpose.
@@ -3078,8 +3107,22 @@ function CustomerGridSurface({
3078
  default (every group closed) is the honest state to land in. EMPTY IS ALL-FOLDED. */
3079
  if (accepted.groupBy !== config.groupBy) setFold(new Set());
3080
  setConfig(accepted);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3081
  },
3082
- [config, activeViewId, views, isQueryPreview, queryBinding, setFold]
3083
  );
3084
  /** C2 returns the entire state so it can prove it did not rewrite user clauses. B consumes
3085
  * exactly its managed addition/removal; filters, conjunction, user membership and every other
@@ -3381,6 +3424,24 @@ function CustomerGridSurface({
3381
  const measureCols = useMemo(() => measureColumnIndex(fields), [fields]);
3382
 
3383
  // Airtable behavior: configuration changes to the active view autosave.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3384
  useEffect(() => {
3385
  // ⭐⭐ W35-T23 — a Query view AUTOSAVES like any other view; only its TRANSPORT differs.
3386
  if (!workspaceReady || embedded || isApplicationSurface) return;
@@ -3438,7 +3499,7 @@ function CustomerGridSurface({
3438
  return () => {
3439
  if (saveTimer.current !== null) window.clearTimeout(saveTimer.current);
3440
  };
3441
- }, [workspaceReady, activeViewId, config, views, embedded, queryBinding, scope, isApplicationSurface]);
3442
 
3443
  // Numeric dimensions force a glide relayout when either the component frame
3444
  // or Streamlit's main column changes width (notably sidebar collapse).
@@ -3469,7 +3530,7 @@ function CustomerGridSurface({
3469
  const mode = tableMode(payload?.counts);
3470
  const serverWindowed = mode === "server-windowed";
3471
  // Owner items 4+6 — the Cohort page's grid renders without the Views sidebar.
3472
- const hideViews = !hostWorkspace || payload?.workspace?.hideViews === true;
3473
  // Wave-6 item 10 — how this view displays. A WINDOWED table is always the grid: list/
3474
  // calendar/kanban compute over the whole matched set, and one page is not it (CG-3's rule,
3475
  // the same reason grouping is off there).
@@ -5168,7 +5229,7 @@ function CustomerGridSurface({
5168
  }
5169
  signal(TOAST_EVENT, describe(entry, dir));
5170
  },
5171
- [patchOverlay, withdrawPending]
5172
  );
5173
 
5174
  /**
@@ -6235,9 +6296,9 @@ function CustomerGridSurface({
6235
 
6236
  const openHeaderMenu = useCallback(
6237
  (column: number, bounds: Rectangle) => {
6238
- if (embedded) return;
6239
  const definition = visibleCols[column];
6240
  if (!definition?.id) return;
 
6241
  setColumnMenu({
6242
  fieldKey: definition.id,
6243
  anchor: {
@@ -6518,7 +6579,7 @@ function CustomerGridSurface({
6518
  * holds exactly one view), so Duplicate cannot smuggle a second one in.
6519
  */
6520
  const persistView = useCallback((view: SavedView, write?: { action?: string }) => {
6521
- if (isApplicationSurface) return;
6522
  // ⭐⭐ W50-T28 CLAUSE 3 — THE REVISION THIS BROWSER LAST READ, taken at emit time from a ref
6523
  // rather than from a dependency. `payload` changes on every workspace arrival and this
6524
  // callback is a dependency of nine memos and the autosave effect; taking the revision as a
@@ -6569,7 +6630,7 @@ function CustomerGridSurface({
6569
  void routed.result.then((result) => {
6570
  if (!result.ok) signal(TOAST_EVENT, result.message);
6571
  });
6572
- }, [queryBinding, scope, isApplicationSurface]);
6573
 
6574
  /**
6575
  * Item 12 (C-LOCK) — set or clear a view's cohort lock, from the rail's menu.
@@ -6649,7 +6710,7 @@ function CustomerGridSurface({
6649
  signal(NAV_MINIMIZE_EVENT);
6650
  },
6651
  [views, activeViewId, config, persistView, fields, isQueryPreview, recordStars.stars.view,
6652
- dataPath, selectAssignedView, clearAssignedView, isApplicationSurface]
6653
  );
6654
 
6655
  useEffect(() => {
@@ -6831,7 +6892,7 @@ function CustomerGridSurface({
6831
  // config here at all is what item 9 deletes.
6832
  // `dataPath` joins it for W50-T11's address write: a stale one would push the PREVIOUS
6833
  // database's hash and route the reader off the table they are standing on.
6834
- [fields, persistView, views, queryBinding, scope, dataPath]
6835
  );
6836
  /**
6837
  * ⭐⭐ WAVE 41 · T38 (owner instruction 17) — *"Sometimes the app will not let a view be
@@ -7341,7 +7402,7 @@ function CustomerGridSurface({
7341
  pids,
7342
  });
7343
  },
7344
- [views, computedRows, fields, serverWindowed, measureSets, cohortSets, today]
7345
  );
7346
 
7347
  // ---------------------------------------------------------------- I11c (C4)
@@ -7598,7 +7659,7 @@ function CustomerGridSurface({
7598
  pids,
7599
  });
7600
  },
7601
- [folderAddPreview]
7602
  );
7603
 
7604
  /**
@@ -8044,7 +8105,7 @@ function CustomerGridSurface({
8044
  setSelListName("");
8045
  clearSelection();
8046
  },
8047
- [selectedPids, serverWindowed, activeViewId, clearSelection]
8048
  );
8049
 
8050
  // Item 3c: the local write is the RENDERED truth (the def half of the no-blip contract) —
@@ -8104,7 +8165,7 @@ function CustomerGridSurface({
8104
  const recordLayout = payload?.workspace?.recordLayout?.order;
8105
  const onRecordLayout = useCallback((order: string[]) => {
8106
  emitHostEvent({ id: eventId("rlayout"), type: "record_layout", order });
8107
- }, []);
8108
  const saveField = useCallback(
8109
  (field: Field, scope?: FieldScope) => {
8110
  const requestId = eventId("field");
@@ -8131,7 +8192,7 @@ function CustomerGridSurface({
8131
  ...(scope ? { scope } : {}),
8132
  });
8133
  },
8134
- [stampFieldEdit, fields]
8135
  );
8136
  const createField = useCallback(
8137
  (
@@ -8458,7 +8519,7 @@ function CustomerGridSurface({
8458
  stampFieldDelete(key);
8459
  emitHostEvent({ id: eventId("fielddel"), type: "field_delete", key });
8460
  },
8461
- [config, updateConfig, order, visible, fieldByKey, lockedKey, stampFieldDelete]
8462
  );
8463
 
8464
  const deleteDefinitionField = useCallback(
@@ -8640,7 +8701,7 @@ function CustomerGridSurface({
8640
  // closed over a stale `isUserTable` would route a definition retype to the overlay on the
8641
  // first render after a scope change — the exact defect this ticket removes, reintroduced by
8642
  // a memo rather than by a predicate.
8643
- [fieldByKey, saveField, scope, isUserTable]
8644
  );
8645
 
8646
  /**
@@ -8725,7 +8786,7 @@ function CustomerGridSurface({
8725
  });
8726
  insertColumn(key, source.key, "right");
8727
  },
8728
- [insertColumn, scopeChoice, stampFieldEdit, fields, computedRows]
8729
  );
8730
 
8731
  /**
@@ -8778,7 +8839,7 @@ function CustomerGridSurface({
8778
  pids,
8779
  });
8780
  clearSelection();
8781
- }, [activeCohortId, selectedPids, cohortMemberSet, clearSelection]);
8782
 
8783
 
8784
  /**
@@ -8803,7 +8864,7 @@ function CustomerGridSurface({
8803
  setSelRemoveOpen(false);
8804
  clearSelection();
8805
  },
8806
- [cohortSets, selectedPids, clearSelection]
8807
  );
8808
 
8809
  /**
@@ -8848,7 +8909,7 @@ function CustomerGridSurface({
8848
  setAddCustPicked(new Set());
8849
  setAddCustQuery("");
8850
  setAddCustOpen(false);
8851
- }, [activeCohortId, addCustPicked]);
8852
 
8853
  /**
8854
  * The picker's candidates: the POOL minus the cohort's current members, narrowed by the
@@ -9925,7 +9986,9 @@ function CustomerGridSurface({
9925
  artefact; the grid draws the artefact. `queryCitationLabel` still formats it, from
9926
  `QueryPage`. */}
9927
  {!hideViews && (
9928
- <ViewSidebar
 
 
9929
  databases={databases}
9930
  activeDatabaseKey={activeDatabaseKey}
9931
  databaseFolders={databaseFolders}
@@ -10316,10 +10379,10 @@ function CustomerGridSurface({
10316
  nouns={topic.nouns}
10317
  viewer={viewer}
10318
  onSetFieldsHidden={fieldBulkDoors.onSetFieldsHidden}
10319
- onShareFields={fieldBulkDoors.onShareFields}
10320
- onReassignFields={fieldBulkDoors.onReassignFields}
10321
- onDeleteFields={fieldBulkDoors.onDeleteFields}
10322
- onRemoveField={fieldBulkDoors.onRemoveField}
10323
  // Item 12 (C-LOCK) — the banner's copy. ⚠ BOTH fields are omitted when this reader
10324
  // cannot see the locked set, and that omission is the SIGNAL, not an oversight: it
10325
  // is what selects RECORD's second sentence ("locked to a set you cannot see").
@@ -10354,8 +10417,8 @@ function CustomerGridSurface({
10354
  `route_order` column needed its own delete: a per-user `field_delete` would apply to
10355
  a bucket the shared definition never reads, so the column blinked out for one paint
10356
  and came back on the next fetch. No such column exists on any tenant any more. */
10357
- onDeleteField={(key) => deleteField(key)}
10358
- onEditField={(fieldKey, rect) => {
10359
  setColumnMenu({
10360
  fieldKey,
10361
  pane: "edit",
@@ -10365,7 +10428,7 @@ function CustomerGridSurface({
10365
  },
10366
  });
10367
  }}
10368
- onAddField={(rect) => setPlusMenu({ left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom, width: rect.width, height: rect.height })}
10369
  /* ⭐⭐ W38-T07 (owner instruction 12) — THE ONE COLOUR CONTROL. This was `colorOn` plus a
10370
  boolean toggle whose `true` arm guessed the column: `fields.find(type === "status")`,
10371
  so on a table with two status columns the person got the first one and had no way to
@@ -10462,7 +10525,7 @@ function CustomerGridSurface({
10462
  onRelational={setPivotVia}
10463
  onRelationalWindow={setPivotWindow}
10464
  sourceLabel={topic.nouns}
10465
- onViewActions={setViewActionsAnchor}
10466
  fullscreen={!!config.fullscreen}
10467
  onFullscreen={() => updateConfig({ ...config, fullscreen: !config.fullscreen })}
10468
  // W46-T09 (owner instructions 2 and 30) — the SAME workspaceDrawer state the launcher
@@ -11581,7 +11644,62 @@ function CustomerGridSurface({
11581
  )}
11582
  </main>
11583
 
11584
- {menuField && columnMenu && (
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
11585
  <ColumnMenu
11586
  key={menuField.key}
11587
  state={columnMenu}
 
26
  } from "@glideapps/glide-data-grid";
27
  import "@glideapps/glide-data-grid/dist/index.css";
28
 
29
+ import { useCustomerData, usePersonalGridLayout } from "./useCustomerData";
30
  import type { SurfaceScope } from "./apiBridge";
31
  import { mutateQueryWorkspace, QUERY_BINDING_EVENT, refuseQueryMutation } from "../query/queryApi";
32
  import type { QueryVirtualBinding } from "../query/queryApi";
 
34
  // ⭐ WAVE 30 · W30-T42 (contract C2) — the WINDOWED grid's arithmetic, pure and node-run in
35
  // `verify_grid_ux.py`, because every one of these decisions is taken inside a callback where
36
  // only its own source text could otherwise be checked.
37
+ import { WINDOW_ROWS, fetchAggregates, personalGridLayout } from "./apiBridge";
38
  // ⭐⭐ W50-T03 / CONTRACT C1 — the windowed aggregate's envelope. Lane F serves the route
39
  // (W50-T31); this side is written to C1's shape and degrades to the loaded window until it
40
  // lands, which is the done-when's own observable rather than a workaround.
 
124
  import ColumnMenu from "./ColumnMenu";
125
  import type { ColumnMenuState } from "./ColumnMenu";
126
  import { HEADER_ICONS } from "./iconShapes";
127
+ import { bindHostEvent, eventId } from "./hostBridge";
128
  // ⭐ WAVE 27 item 21 (R14) — which of this table's views carry an alert. The SERVER's
129
  // list is the only answer; the rail's alert door is a one-way create.
130
  import { fetchAlerts } from "../alerts/alertsApi";
 
857
  lockedKey: string;
858
  fieldByKey: Map<string, Field>;
859
  isUserTable: boolean;
860
+ scope: SurfaceScope;
861
  rowsPath: string;
862
  setFields: (update: (current: Field[]) => Field[]) => void;
863
  stampFieldDelete: (key: string) => void;
 
894
  export function useFieldBulkDoors(deps: FieldBulkDoorDeps): FieldBulkDoors {
895
  const { config, updateConfig, order, visible, lockedKey, fieldByKey, isUserTable, scope,
896
  rowsPath, setFields, stampFieldDelete } = deps;
897
+ const emitHostEvent = useMemo(() => bindHostEvent(scope), [scope]);
898
  const onSetFieldsHidden = useCallback((keys: string[], hidden: boolean) => {
899
  const next = new Set(visible);
900
  for (const key of keys) {
 
949
  }
950
  })();
951
  }, [config, fieldByKey, isUserTable, lockedKey, order, rowsPath, scope, setFields,
952
+ stampFieldDelete, updateConfig, visible, emitHostEvent]);
953
 
954
  const onShareFields = useCallback((keys: string[]) => {
955
  if (keys.length > 0) signal(TOAST_EVENT,
 
1641
  });
1642
  }
1643
 
1644
+ /** Cell-owned presentation reported to the caller without a dependency on Sheet bindings. */
1645
+ export interface CellDisplayChoice {
1646
+ mode: "grid" | "list" | "map";
1647
+ visible: string[];
1648
+ }
1649
+
1650
  interface CustomerGridProps {
1651
  scope?: SurfaceScope;
1652
  /** Shell-owned Data workspace location; grid resolves its view/field, never the global rail. */
 
1665
  /** Read-only Grid view embedded in a linked-record modal. It keeps the standard
1666
  * filter/sort/search toolbar while withdrawing schema and row mutations. */
1667
  embedded?: boolean;
1668
+ /** R8 per-user layout identity: source table + link; Sheet supplies its cell identity. */
1669
+ personalLayoutKey?: string;
1670
  /** Complete caller-scoped projection for an embedded grid. Null withholds rows while
1671
  * loading/refused; undefined retains the ordinary target reader. */
1672
  embeddedPayload?: CustomersPayload | null;
 
1689
  * | `embedded` | HIDDEN (`hostViews = []`) | the WHOLE table | filtered CLIENT-side |
1690
  * | **`related`** | **SHOWN, the target's own** | **server, PRE-FILTERED** | **only linked** |
1691
  *
1692
+ * W60 R8: `related` still selects the server-pinned READ and the target's view rail.
1693
+ * Its row/schema write guards now match `embedded`; view selection is read-only and
1694
+ * personalLayoutKey persists the user's layout separately from those target views.
 
1695
  *
1696
  * `label` is the pinned record's NAME and is display-only: the chip reads "Linked to
1697
  * <label>". ⛔ It never reaches the wire (`RelatedPin` has no `label`) and it is never
 
1714
  cellFields?: string[];
1715
  /** Report a filter edit from the cell View data surface; its Sheet caller owns settling. */
1716
  onCellFilterChange?: (tree: FilterTree) => void;
1717
+ /** C4: report cell column choices; the Sheet caller owns settling and persistence. */
1718
+ onCellDisplayChange?: (display: CellDisplayChoice) => void;
1719
  /**
1720
  * ⭐ W51-T06 clause 9 — a row click NAVIGATES the record view instead of opening this grid's
1721
  * own drawer.
 
1738
  * `readLocal(storageKey)`. R2 gives two links between the same pair two tabs, so two tabs can
1739
  * target one database; a memory keyed by `storageKey` would make them share one answer and
1740
  * each would reopen on the other's view.
1741
+ * W60 R8 supersedes R5's no-new-server-state clause: this prop still names the target
1742
+ * SavedView, while personalLayoutKey restores the per-user layout from /nav/prefs.
 
1743
  */
1744
  relatedViewId?: string;
1745
  onRelatedViewChange?: (viewId: string) => void;
 
1777
  cellFields?: string[];
1778
  /** W56-T25: report a grid filter edit so the Sheet caller can settle and persist it. */
1779
  onCellFilterChange?: (tree: FilterTree) => void;
1780
+ /** C4: forward column choices without writing the database's shared View. */
1781
+ onCellDisplayChange?: (display: CellDisplayChoice) => void;
1782
  /** W56-T24: chrome the caller owns, in the header, right of the title and left of Close. */
1783
  headerActions?: ReactNode;
1784
  /** W56-T24: a statement under the rows. Only rendered on a non-editable modal. */
 
1793
  // the two surfaces cannot drift into two popups that behave almost alike. W56-T24 adds optional
1794
  // chrome slots and a `cellView` modifier while leaving existing callers and the focus trap intact.
1795
  export function LinkGridModal({ label, table, recordIds, editable = false, single = false,
1796
+ excludeRecordId, cellView = false, cellFilter, cellFields, onCellFilterChange, onCellDisplayChange,
1797
+ headerActions, footer,
1798
  onOpenRecord, onSave, onClose }: LinkGridModalProps) {
1799
  const panelRef = useRef<HTMLDivElement>(null);
1800
  const [selectedIds, setSelectedIds] = useState<number[]>(() => [...recordIds]);
 
1853
  cellFilter={cellFilter}
1854
  cellFields={cellFields}
1855
  onCellFilterChange={onCellFilterChange}
1856
+ onCellDisplayChange={onCellDisplayChange}
1857
  embeddedRecordIds={editable ? undefined : recordIds}
1858
  embeddedExcludeRecordId={editable ? excludeRecordId : undefined}
1859
  embeddedSelectable={editable}
 
1997
  renderDatabaseActions,
1998
  databaseCreateControl,
1999
  queryBinding,
2000
+ embedded: requestedEmbedded = false,
2001
+ personalLayoutKey,
2002
  embeddedPayload,
2003
  embeddedRecordIds,
2004
  embeddedSelectable = false,
 
2010
  cellFilter,
2011
  cellFields,
2012
  onCellFilterChange,
2013
+ onCellDisplayChange,
2014
  onOpenRecord,
2015
  relatedViewId,
2016
  onRelatedViewChange,
2017
  }: CustomerGridProps = {}) {
2018
+ // R8: a server-pinned related read keeps the same row/schema refusal as a projection.
2019
+ const embedded = requestedEmbedded || !!related || !!personalLayoutKey;
2020
+ const emitHostEvent = useMemo(() => bindHostEvent(scope, !embedded), [scope, embedded]);
2021
+ const personalLayout = usePersonalGridLayout(personalLayoutKey);
2022
+ const personalLayoutStamp = useRef<string | null>(null);
2023
+ const [personalLayoutInitialized, setPersonalLayoutInitialized] = useState<string | null>(null);
2024
+ const personalSaveSequence = useRef(0);
2025
  const isQueryPreview = queryBinding !== undefined;
2026
  const isApplicationSurface = !!dataPath?.application && !embedded && !isQueryPreview;
2027
  /**
 
2052
  * the SOURCE database's own locks**, which is the predicate that does the work now.
2053
  *
2054
  * ⛔ TWO QUESTIONS, NOT ONE, AND CONFLATING THEM IS WHAT MADE THE SINGLE FLAG WRONG:
2055
+ * · **`embedded`**: row/schema and workspace events are withdrawn. W60 R8 gives linked
2056
+ * grids a separate personal layout writer; it never uses a workspace event.
2057
  * · **`hostWorkspace`** — *does this surface own the SOURCE DATABASE's workspace?* Its views,
2058
  * its `storageKey`, its view rail, its alert list. **A Query surface does NOT**, and that
2059
  * has nothing to do with read-only: the artefact has its own single view, its own storage
 
2081
  clearAssignedView,
2082
  } = useCustomerData(scope, {
2083
  embeddedPayload: embedded ? embeddedPayload : undefined,
2084
+ // Foreground shell identity only; every emitter now captures this instance's scope.
 
 
2085
  bindSurface: !embedded,
2086
  // ⛔ The one flag that stays on the WIDE predicate: neither surface reads the source
2087
  // database's own saved views.
2088
+ includeWorkspace: hostWorkspace || !!related,
2089
  // `writable: false` blocks `patchOverlay`, i.e. every cell edit. R2 wants them in Query.
2090
  writable: !embedded,
2091
  /* ⭐⭐ W51-T06 / C6 / R5 — THE PINNED READ. Not a fourth flag beside the three above: those
 
2648
  * ⚠ Existing browsers lose the contents of the old global localStorage bucket. That is the point: every
2649
  * byte in it is a workspace some other surface persisted, and there is no way to tell whose.
2650
  */
2651
+ const storageKey = personalLayoutKey
2652
+ ? `linked:${JSON.stringify([personalLayoutKey, payload?.workspace?.storageKey ?? scope])}`
2653
+ : isQueryPreview && queryBinding
2654
  ? `query:${queryBinding.workspaceBinding.key}`
2655
  : payload?.workspace?.storageKey ?? `${LOCAL_KEY_PREFIX}${scope}`;
2656
  // A parent may rebuild an equivalent tree on every render. Depend on its value, not its identity,
 
2662
  // fills only missing objects and keeps the standalone path useful.
2663
  useEffect(() => {
2664
  if (!payload || payloadFields.length === 0 || initializedKey.current === storageKey) return;
2665
+ if (!personalLayout.ready) return;
2666
  if (isApplicationSurface) {
2667
  // App presentation is local to this mount. Never adopt a saved View, its selection, or
2668
  // its local-storage echo; the App's registry definition is applied after these fields load.
 
2721
  payload.workspace != null
2722
  );
2723
  const hostViews = embedded ? [] : payload.workspace?.views ?? [];
2724
+ // Pinned linked tabs may read target views. Their selection and layout never write them.
2725
+ const readableViews = related ? payload.workspace?.views ?? [] : hostViews;
2726
  const byId = new Map<string, SavedView>();
2727
  byId.set(ALL_VIEW_ID, allRecordsView(initialFields, scope));
2728
  // D-19 — the HOST'S LIST DECIDES WHICH VIEWS EXIST. A local copy the host no longer
2729
  // names is a ghost (deleted elsewhere, share revoked, store moved) and is dropped here,
2730
  // guarded by this browser's own recent writes so an optimistic create survives.
2731
  viewWritesRef.current = pruneTombstones(local?.viewWrites, Date.now());
2732
+ for (const view of seedLocalViews(local?.views ?? [], readableViews, viewWritesRef.current,
2733
  Date.now(), payload.workspace != null))
2734
  byId.set(view.id, view);
2735
  // Host state wins — EXCEPT when it is a lagged echo of this browser's own
 
2750
  // every host round trip was itself a remount.
2751
  const tombstones = pruneTombstones(local?.viewTombstones, Date.now());
2752
  viewTombstonesRef.current = tombstones;
2753
+ for (const view of readableViews) {
2754
  // Both doors, the `reconcileFields` rule: a tombstone drops the host copy AND any
2755
  // local copy, so a delete that raced localStorage cannot re-enter through either.
2756
  if (tombstones[view.id] !== undefined) {
 
2786
  * the answer down; this is the one place it can be honoured, because it has to be resolved
2787
  * against `initialViews` like every other rung (a remembered view that has since been
2788
  * deleted falls through to `initialViews[0]` rather than showing an empty grid).
2789
+ * W60 R8: this browser hint still selects a base view. The per-user link layout is
2790
+ * restored separately from server prefs and does not mutate that base view.
2791
  */
2792
  const requested = resolveActiveView(
2793
  { id: local?.activeViewId, at: local?.activeViewAt },
 
2815
  setFields(initialFields);
2816
  setViews(initialViews);
2817
  setActiveViewId(active.id);
2818
+ const initialConfig = normalizeConfig({ ...(cellView && cellFilter ? {
2819
  ...active.config,
2820
  filters: cellFilter.nodes ?? [],
2821
  filterConj: cellFilter.conj ?? "and",
 
2823
  order: [...cellFields, ...active.config.order.filter((key) => !cellFields.includes(key))],
2824
  visible: cellFields,
2825
  } : {}),
2826
+ } : active.config), ...personalLayout.layout }, initialFields);
2827
+ setConfig(initialConfig);
2828
+ personalLayoutStamp.current = JSON.stringify(personalGridLayout(initialConfig));
2829
+ setPersonalLayoutInitialized(storageKey);
2830
  setWorkspaceReady(true);
2831
  initializedKey.current = storageKey;
2832
 
 
2867
  reemittedRef.current = { ...(local?.reemitted ?? {}) };
2868
  }
2869
  }, [payload, payloadFields, storageKey, hostWorkspace, scope, isQueryPreview, queryBinding, isApplicationSurface,
2870
+ cellView, cellFilterKey, cellFieldsKey, personalLayout.ready, personalLayout.layout, emitHostEvent]);
2871
 
2872
  // Initialization runs once per scope. Keep the columns current after a cell filter settles,
2873
  // retaining hidden keys in the order so the reader can show them again.
2874
  useEffect(() => {
2875
  if (!workspaceReady || !cellView || !cellFields?.length) return;
2876
+ if (personalLayoutKey) return; // R8: these fields seed once; the cell's personal layout wins.
2877
  setConfig((current) => ({
2878
  ...current,
2879
  order: [...cellFields, ...current.order.filter((key) => !cellFields.includes(key))],
2880
  visible: cellFields,
2881
  }));
2882
+ }, [workspaceReady, cellView, cellFieldsKey, personalLayoutKey]);
2883
 
2884
  /**
2885
  * ⭐ W36-T03 — the view-preference stamp, and it is its OWN effect on purpose.
 
3107
  default (every group closed) is the honest state to land in. EMPTY IS ALL-FOLDED. */
3108
  if (accepted.groupBy !== config.groupBy) setFold(new Set());
3109
  setConfig(accepted);
3110
+ // Only cellView user updates report. Initialization and echoed cellFields use setConfig
3111
+ // directly, never updateConfig, so neither can emit or start a persistence feedback loop.
3112
+ if (cellView && onCellDisplayChange) {
3113
+ const visible = accepted.order.filter((key) => accepted.visible.includes(key));
3114
+ const previous = config.order.filter((key) => config.visible.includes(key));
3115
+ // C4 carries only mode and ordered visibility. Sorts and widths remain in this mount.
3116
+ if (JSON.stringify(visible) !== JSON.stringify(previous) ||
3117
+ JSON.stringify(accepted.sorts) !== JSON.stringify(config.sorts) ||
3118
+ JSON.stringify(accepted.widths) !== JSON.stringify(config.widths) ||
3119
+ accepted.display?.mode !== config.display?.mode) {
3120
+ const mode = accepted.display?.mode;
3121
+ onCellDisplayChange({ mode: mode === "list" || mode === "map" ? mode : "grid", visible });
3122
+ }
3123
+ }
3124
  },
3125
+ [config, activeViewId, views, isQueryPreview, queryBinding, setFold, cellView, onCellDisplayChange]
3126
  );
3127
  /** C2 returns the entire state so it can prove it did not rewrite user clauses. B consumes
3128
  * exactly its managed addition/removal; filters, conjunction, user membership and every other
 
3424
  const measureCols = useMemo(() => measureColumnIndex(fields), [fields]);
3425
 
3426
  // Airtable behavior: configuration changes to the active view autosave.
3427
+ // R8's separate personal door. Saves are queued outside the mount so switching tabs cannot
3428
+ // drop a just-edited filter. This never modifies `views`, local workspace state, or host events.
3429
+ useEffect(() => {
3430
+ if (!personalLayoutKey || !workspaceReady || !personalLayout.ready || personalLayoutInitialized !== storageKey || personalLayoutStamp.current === null) return;
3431
+ const layout = personalGridLayout(config);
3432
+ const stamp = JSON.stringify(layout);
3433
+ if (stamp === personalLayoutStamp.current) return;
3434
+ personalLayoutStamp.current = stamp;
3435
+ const sequence = ++personalSaveSequence.current;
3436
+ setSaveState("saving");
3437
+ void personalLayout.save(layout).then((saved) => {
3438
+ if (sequence !== personalSaveSequence.current) return;
3439
+ if (!saved) personalLayoutStamp.current = "";
3440
+ setSaveState("saved");
3441
+ });
3442
+ }, [personalLayoutKey, workspaceReady, personalLayout.ready, personalLayout.save, config,
3443
+ personalLayoutInitialized, storageKey]);
3444
+
3445
  useEffect(() => {
3446
  // ⭐⭐ W35-T23 — a Query view AUTOSAVES like any other view; only its TRANSPORT differs.
3447
  if (!workspaceReady || embedded || isApplicationSurface) return;
 
3499
  return () => {
3500
  if (saveTimer.current !== null) window.clearTimeout(saveTimer.current);
3501
  };
3502
+ }, [workspaceReady, activeViewId, config, views, embedded, queryBinding, scope, isApplicationSurface, emitHostEvent]);
3503
 
3504
  // Numeric dimensions force a glide relayout when either the component frame
3505
  // or Streamlit's main column changes width (notably sidebar collapse).
 
3530
  const mode = tableMode(payload?.counts);
3531
  const serverWindowed = mode === "server-windowed";
3532
  // Owner items 4+6 — the Cohort page's grid renders without the Views sidebar.
3533
+ const hideViews = (!hostWorkspace && !related) || payload?.workspace?.hideViews === true;
3534
  // Wave-6 item 10 — how this view displays. A WINDOWED table is always the grid: list/
3535
  // calendar/kanban compute over the whole matched set, and one page is not it (CG-3's rule,
3536
  // the same reason grouping is off there).
 
5229
  }
5230
  signal(TOAST_EVENT, describe(entry, dir));
5231
  },
5232
+ [patchOverlay, withdrawPending, emitHostEvent]
5233
  );
5234
 
5235
  /**
 
6296
 
6297
  const openHeaderMenu = useCallback(
6298
  (column: number, bounds: Rectangle) => {
 
6299
  const definition = visibleCols[column];
6300
  if (!definition?.id) return;
6301
+ if (embedded) gridRef.current?.focus();
6302
  setColumnMenu({
6303
  fieldKey: definition.id,
6304
  anchor: {
 
6579
  * holds exactly one view), so Duplicate cannot smuggle a second one in.
6580
  */
6581
  const persistView = useCallback((view: SavedView, write?: { action?: string }) => {
6582
+ if (embedded || personalLayoutKey || isApplicationSurface) return;
6583
  // ⭐⭐ W50-T28 CLAUSE 3 — THE REVISION THIS BROWSER LAST READ, taken at emit time from a ref
6584
  // rather than from a dependency. `payload` changes on every workspace arrival and this
6585
  // callback is a dependency of nine memos and the autosave effect; taking the revision as a
 
6630
  void routed.result.then((result) => {
6631
  if (!result.ok) signal(TOAST_EVENT, result.message);
6632
  });
6633
+ }, [queryBinding, scope, isApplicationSurface, embedded, personalLayoutKey, emitHostEvent]);
6634
 
6635
  /**
6636
  * Item 12 (C-LOCK) — set or clear a view's cohort lock, from the rail's menu.
 
6710
  signal(NAV_MINIMIZE_EVENT);
6711
  },
6712
  [views, activeViewId, config, persistView, fields, isQueryPreview, recordStars.stars.view,
6713
+ dataPath, selectAssignedView, clearAssignedView, isApplicationSurface, emitHostEvent]
6714
  );
6715
 
6716
  useEffect(() => {
 
6892
  // config here at all is what item 9 deletes.
6893
  // `dataPath` joins it for W50-T11's address write: a stale one would push the PREVIOUS
6894
  // database's hash and route the reader off the table they are standing on.
6895
+ [fields, persistView, views, queryBinding, scope, dataPath, emitHostEvent]
6896
  );
6897
  /**
6898
  * ⭐⭐ WAVE 41 · T38 (owner instruction 17) — *"Sometimes the app will not let a view be
 
7402
  pids,
7403
  });
7404
  },
7405
+ [views, computedRows, fields, serverWindowed, measureSets, cohortSets, today, emitHostEvent]
7406
  );
7407
 
7408
  // ---------------------------------------------------------------- I11c (C4)
 
7659
  pids,
7660
  });
7661
  },
7662
+ [folderAddPreview, emitHostEvent]
7663
  );
7664
 
7665
  /**
 
8105
  setSelListName("");
8106
  clearSelection();
8107
  },
8108
+ [selectedPids, serverWindowed, activeViewId, clearSelection, emitHostEvent]
8109
  );
8110
 
8111
  // Item 3c: the local write is the RENDERED truth (the def half of the no-blip contract) —
 
8165
  const recordLayout = payload?.workspace?.recordLayout?.order;
8166
  const onRecordLayout = useCallback((order: string[]) => {
8167
  emitHostEvent({ id: eventId("rlayout"), type: "record_layout", order });
8168
+ }, [emitHostEvent]);
8169
  const saveField = useCallback(
8170
  (field: Field, scope?: FieldScope) => {
8171
  const requestId = eventId("field");
 
8192
  ...(scope ? { scope } : {}),
8193
  });
8194
  },
8195
+ [stampFieldEdit, fields, emitHostEvent]
8196
  );
8197
  const createField = useCallback(
8198
  (
 
8519
  stampFieldDelete(key);
8520
  emitHostEvent({ id: eventId("fielddel"), type: "field_delete", key });
8521
  },
8522
+ [config, updateConfig, order, visible, fieldByKey, lockedKey, stampFieldDelete, emitHostEvent]
8523
  );
8524
 
8525
  const deleteDefinitionField = useCallback(
 
8701
  // closed over a stale `isUserTable` would route a definition retype to the overlay on the
8702
  // first render after a scope change — the exact defect this ticket removes, reintroduced by
8703
  // a memo rather than by a predicate.
8704
+ [fieldByKey, saveField, scope, isUserTable, emitHostEvent]
8705
  );
8706
 
8707
  /**
 
8786
  });
8787
  insertColumn(key, source.key, "right");
8788
  },
8789
+ [insertColumn, scopeChoice, stampFieldEdit, fields, computedRows, emitHostEvent]
8790
  );
8791
 
8792
  /**
 
8839
  pids,
8840
  });
8841
  clearSelection();
8842
+ }, [activeCohortId, selectedPids, cohortMemberSet, clearSelection, emitHostEvent]);
8843
 
8844
 
8845
  /**
 
8864
  setSelRemoveOpen(false);
8865
  clearSelection();
8866
  },
8867
+ [cohortSets, selectedPids, clearSelection, emitHostEvent]
8868
  );
8869
 
8870
  /**
 
8909
  setAddCustPicked(new Set());
8910
  setAddCustQuery("");
8911
  setAddCustOpen(false);
8912
+ }, [activeCohortId, addCustPicked, emitHostEvent]);
8913
 
8914
  /**
8915
  * The picker's candidates: the POOL minus the cohort's current members, narrowed by the
 
9986
  artefact; the grid draws the artefact. `queryCitationLabel` still formats it, from
9987
  `QueryPage`. */}
9988
  {!hideViews && (
9989
+ <ViewSidebar
9990
+ scope={scope}
9991
+ readOnly={embedded}
9992
  databases={databases}
9993
  activeDatabaseKey={activeDatabaseKey}
9994
  databaseFolders={databaseFolders}
 
10379
  nouns={topic.nouns}
10380
  viewer={viewer}
10381
  onSetFieldsHidden={fieldBulkDoors.onSetFieldsHidden}
10382
+ onShareFields={embedded ? null : fieldBulkDoors.onShareFields}
10383
+ onReassignFields={embedded ? null : fieldBulkDoors.onReassignFields}
10384
+ onDeleteFields={embedded ? null : fieldBulkDoors.onDeleteFields}
10385
+ onRemoveField={embedded ? null : fieldBulkDoors.onRemoveField}
10386
  // Item 12 (C-LOCK) — the banner's copy. ⚠ BOTH fields are omitted when this reader
10387
  // cannot see the locked set, and that omission is the SIGNAL, not an oversight: it
10388
  // is what selects RECORD's second sentence ("locked to a set you cannot see").
 
10417
  `route_order` column needed its own delete: a per-user `field_delete` would apply to
10418
  a bucket the shared definition never reads, so the column blinked out for one paint
10419
  and came back on the next fetch. No such column exists on any tenant any more. */
10420
+ onDeleteField={embedded ? undefined : (key) => deleteField(key)}
10421
+ onEditField={embedded ? undefined : (fieldKey, rect) => {
10422
  setColumnMenu({
10423
  fieldKey,
10424
  pane: "edit",
 
10428
  },
10429
  });
10430
  }}
10431
+ onAddField={embedded ? undefined : (rect) => setPlusMenu({ left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom, width: rect.width, height: rect.height })}
10432
  /* ⭐⭐ W38-T07 (owner instruction 12) — THE ONE COLOUR CONTROL. This was `colorOn` plus a
10433
  boolean toggle whose `true` arm guessed the column: `fields.find(type === "status")`,
10434
  so on a table with two status columns the person got the first one and had no way to
 
10525
  onRelational={setPivotVia}
10526
  onRelationalWindow={setPivotWindow}
10527
  sourceLabel={topic.nouns}
10528
+ onViewActions={embedded ? undefined : setViewActionsAnchor}
10529
  fullscreen={!!config.fullscreen}
10530
  onFullscreen={() => updateConfig({ ...config, fullscreen: !config.fullscreen })}
10531
  // W46-T09 (owner instructions 2 and 30) — the SAME workspaceDrawer state the launcher
 
11644
  )}
11645
  </main>
11646
 
11647
+ {embedded && menuField && columnMenu && (
11648
+ <ColumnMenu
11649
+ key={menuField.key}
11650
+ embedded
11651
+ state={columnMenu}
11652
+ field={menuField}
11653
+ fields={fields}
11654
+ locked={menuField.key === lockedKey}
11655
+ schemaLocked
11656
+ geocodable={false}
11657
+ viewer={viewer}
11658
+ sortedDir={menuSortedDir}
11659
+ isFiltered={menuIsFiltered}
11660
+ isGrouped={config.groupBy === menuField.key}
11661
+ groupable={isGroupableField(menuField, lockedKey)}
11662
+ columnWidth={(visibleCols[menuVisIndex] as { width?: number } | undefined)?.width}
11663
+ onColumnWidth={(width) => {
11664
+ const column = visibleCols[menuVisIndex];
11665
+ if (column) onColumnResize(column, width);
11666
+ }}
11667
+ onClose={() => setColumnMenu(null)}
11668
+ onHide={() => {
11669
+ setColumnVisible(menuField.key, false);
11670
+ setColumnMenu(null);
11671
+ }}
11672
+ onSort={(dir) => {
11673
+ const refusal = routeSortRefusal(
11674
+ menuField.key, { nodes: config.filters, conj: config.filterConj }, fields,
11675
+ );
11676
+ if (refusal) { signal(TOAST_EVENT, refusal); return; }
11677
+ updateConfig({ ...config, sorts: [{ colId: menuField.key, dir }] });
11678
+ }}
11679
+ onClearSort={() => updateConfig({
11680
+ ...config, sorts: config.sorts.filter((s) => s.colId !== menuField.key),
11681
+ })}
11682
+ onFilterBy={() => setFilterSeed((prev) => ({
11683
+ n: (prev?.n ?? 0) + 1,
11684
+ ...(menuField.measure
11685
+ ? { measure: { key: menuField.measure.key, window: menuField.measure.window } }
11686
+ : { key: menuField.key }),
11687
+ }))}
11688
+ onClearFilter={() => applyFilters(
11689
+ dropFieldFromTree(config.filters, menuField.key, measureCols),
11690
+ )}
11691
+ onGroupByField={() => updateConfig({ ...config, groupBy: menuField.key })}
11692
+ onClearGroup={() => updateConfig({ ...config, groupBy: null })}
11693
+ onNote={() => undefined}
11694
+ onCreate={() => undefined}
11695
+ onChangeField={() => undefined}
11696
+ onCreateAndSwap={() => undefined}
11697
+ onRemoveFromMine={() => undefined}
11698
+ measures={measures}
11699
+ />
11700
+ )}
11701
+
11702
+ {!embedded && menuField && columnMenu && (
11703
  <ColumnMenu
11704
  key={menuField.key}
11705
  state={columnMenu}
web/src/customer-grid/MapView.tsx CHANGED
@@ -832,6 +832,19 @@ function MapViewSurface({
832
  window.addEventListener("aios:route-open", openRoute);
833
  return () => window.removeEventListener("aios:route-open", openRoute);
834
  }, []);
 
 
 
 
 
 
 
 
 
 
 
 
 
835
  const [routePinPrompt, setRoutePinPrompt] = useState<{
836
  routeId: string; customerPid: number; title: string; present: boolean;
837
  } | null>(null);
 
832
  window.addEventListener("aios:route-open", openRoute);
833
  return () => window.removeEventListener("aios:route-open", openRoute);
834
  }, []);
835
+ useEffect(() => {
836
+ const openHashRoute = () => {
837
+ const queryAt = window.location.hash.indexOf("?");
838
+ if (queryAt < 0) return;
839
+ const routeId = new URLSearchParams(window.location.hash.slice(queryAt + 1)).get("route");
840
+ if (!routeId) return;
841
+ pendingInboxRoute.current = routeId;
842
+ setActiveRouteId(routeId);
843
+ };
844
+ openHashRoute();
845
+ window.addEventListener("hashchange", openHashRoute);
846
+ return () => window.removeEventListener("hashchange", openHashRoute);
847
+ }, []);
848
  const [routePinPrompt, setRoutePinPrompt] = useState<{
849
  routeId: string; customerPid: number; title: string; present: boolean;
850
  } | null>(null);
web/src/customer-grid/RecordDetail.tsx CHANGED
@@ -64,8 +64,9 @@ import type { CustomerDoc, DisplayMode, Field, RelatedEntry, RelatedPin, Related
64
  `WINDOW_ROWS` are the one windowed read this product owns, and the sibling set a pushed
65
  frame's chevrons page is that read with the frame's own pin on it. */
66
  import { fetchLinkTargets, fetchRecordMeasureValues, fetchRelated, fetchRelatedProductMeasureValues,
67
- fetchTableWindow, fetchTopicRows, isRelatedProductMetricScope, probeRelatedRead,
68
- readThroughTables, WINDOW_ROWS } from "./apiBridge";
 
69
  import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal } from "../apiContract";
70
 
71
  /**
@@ -575,8 +576,7 @@ function RecordModeSkeleton({
575
  * ⛔ THIS AUTHORS NO PROSE AND MINES NONE. R13 asks "you may not see this table" and "this hop
576
  * was filtered" to NAME their subject, and the envelope already carries `table` and `hop` as
577
  * fields; reading the subject out of the sentence with a regular expression would make this file
578
- * a second author of one wire contract, which is the failure `unpinnableNote`'s comment guards
579
- * against directly above. The sentence stays the server's, whole; this only decides what is
580
  * emphasised above it.
581
  *
582
  * ⚠ THE TABLE GOES THROUGH THE DISPLAY-NAME ROSTER, the one producer of a database's name in
@@ -613,13 +613,7 @@ function refusalSubject(
613
  names the absent database in the server's own words, so there is nothing for a subject line
614
  to add and it stays empty unless a display name genuinely exists. */
615
  if (code === RELATED_REFUSAL.retiredTarget && table) return labelFor(table);
616
- /* ⭐⭐ W54-T40 — THE ONE STATE WITH NO SERVER **CODE** STILL HAS A SUBJECT, AND IT IS THE TAB
617
- THE OWNER NAMED. `unpinnableNote` is the client's own sentence for "the read-through roster
618
- does not name this database", so no code comes back with it and every branch above misses;
619
- the refusal then rendered as a lone paragraph with nothing saying WHICH database it was
620
- about. ⛔ THE DISPLAY NAME OR NOTHING, exactly as the retired branch above decided: this
621
- falls through to `labelFor` with no `|| table`, so a database with no roster entry stays
622
- silent rather than putting a raw key in bold on the owner's screen. */
623
  if (!code && table) return labelFor(table);
624
  return "";
625
  }
@@ -782,11 +776,9 @@ const EMPTY_ROWS: Row[] = [];
782
  const EMPTY_FIELDS: Field[] = [];
783
 
784
  /**
785
- * ⭐⭐ CLAUSE 10's STORE, AND IT IS `localStorage` BECAUSE R5 SAYS **"nothing new is stored"**.
786
- *
787
- * ⛔ THE VIEW ITSELF IS NOT STORED HERE, ONLY WHICH ONE WAS LAST OPEN. The views are the target
788
- * database's own saved views, written through its own door; this remembers a reading position,
789
- * per person, per browser, and no server record learns it.
790
  * ⚠ Every access is wrapped: a private window, a full quota or a disabled store all throw from
791
  * `localStorage` itself, and a record drawer that cannot open because a preference could not be
792
  * read is a much worse defect than a preference that does not persist.
@@ -852,12 +844,6 @@ function writeTabViews(value: Record<string, string>): void {
852
  * survive until the rows door itself learns a relation predicate, at which point the state it
853
  * describes stops existing and it goes with it.
854
  */
855
- function unpinnableNote(target: string): string {
856
- return `'${target}' is not read through the live mirror on this deployment, so its rows door `
857
- + `takes no relation pin and these records cannot be narrowed to this one. Open that `
858
- + `database on its own and filter it there, or ask for its stored read to accept a pin`;
859
- }
860
-
861
  /**
862
  * ⭐⭐ W53-T25 — THE PIDS IN A LINK CELL, and the shape is the one this product already stores.
863
  *
@@ -888,6 +874,8 @@ interface RelationTargetAnswer {
888
  ids: number[];
889
  code: string;
890
  reason: string;
 
 
891
  }
892
 
893
  /** Resolve a declared bridge onto a registry-module pool without pretending the pool is a mirror. */
@@ -896,10 +884,15 @@ async function fetchModuleRelationTargets(
896
  record: number,
897
  entry: RelatedEntry,
898
  ): Promise<RelationTargetAnswer> {
 
 
 
 
 
899
  const query = new URLSearchParams({
900
  source,
901
  record: String(record),
902
- via: entry.key,
903
  target: entry.target,
904
  });
905
  try {
@@ -921,8 +914,8 @@ async function fetchModuleRelationTargets(
921
  reason: "The related database returned an unreadable answer. Try again." };
922
  }
923
  const envelope = body as {
924
- error?: { code?: unknown; message?: unknown };
925
- detail?: { error?: { code?: unknown; message?: unknown } };
926
  } | null;
927
  const refusal = envelope?.error ?? envelope?.detail?.error;
928
  return {
@@ -930,6 +923,8 @@ async function fetchModuleRelationTargets(
930
  ids: [],
931
  code: String(refusal?.code ?? "relation_target_unavailable"),
932
  reason: String(refusal?.message ?? "This relation could not be read right now. Try again."),
 
 
933
  };
934
  } catch {
935
  return { ok: false, ids: [], code: "relation_target_unavailable",
@@ -1447,7 +1442,8 @@ export default function RecordDetail({
1447
  * and that is cheaper than a second effect whose only job is to mirror this state.
1448
  */
1449
  const [tabViews, setTabViews] = useState<Record<string, string>>(readTabViews);
1450
- /* Keep the pre-normalization edge key as a read fallback. Wave 55 made route selection
 
1451
  semantic so a shorter equivalent path can replace a longer one without losing the open tab,
1452
  but existing browsers may still hold the earlier edge-keyed preference. */
1453
  const legacyTabViewKey = activeRelated
@@ -1639,10 +1635,8 @@ export default function RecordDetail({
1639
  ⛔ THE SIBLING SET IS THE FRAME'S OWN PIN, READ THROUGH THE WINDOWED DOOR. `frame.pin` is
1640
  the pin that fetched the row this frame was pushed from, so the same pin fetches the rest of
1641
  that row set. One window, no predicate, no sort: whatever the related tab was showing.
1642
- ⚠ GUARDED ON `readThroughTables()` BEFORE THE CALL, mirroring `tabState`'s own guard below.
1643
- `fetchTableWindow` raises `DATA_ERROR_EVENT` on a refusal, which replaces the entire surface
1644
- with an error card — a sibling list that cannot be fetched must degrade to DISABLED
1645
- chevrons and a silent caption, never to a broken screen.
1646
  ═══════════════════════════════════════════════════════════════════════════════════════ */
1647
  const framePinKey = frame && frame.pin
1648
  ? JSON.stringify({ table: frame.table, pin: frame.pin })
@@ -1660,19 +1654,12 @@ export default function RecordDetail({
1660
  const asked = JSON.parse(framePinKey) as { table: string; pin: RelatedPin };
1661
  let live = true;
1662
  void (async () => {
 
 
 
 
1663
  if (isRelatedProductMetricScope(asked.table, asked.pin)) {
1664
- const listing = await fetchRelated(asked.pin.table, 1);
1665
- if (!live) return;
1666
- const entry = listing.entries.find((edge) => edge.target === asked.table
1667
- && edge.via.field === "products_ordered");
1668
- if (!entry) return;
1669
- const targets = await fetchModuleRelationTargets(asked.pin.table, asked.pin.record, entry);
1670
- if (!live || !targets.ok) return;
1671
- const payload = await fetchTopicRows(PRODUCT_TOPIC);
1672
- if (!live || !payload) return;
1673
- const ids = new Set(targets.ids);
1674
- const rows = payload.rows.filter((row) => ids.has(Number(row.pid)));
1675
- if (rows.length !== ids.size) return;
1676
  const scoped = await fetchRelatedProductMeasureValues(
1677
  rows.map((row) => Number(row.pid)), payload.fields, asked.pin, () => live);
1678
  if (!live || !scoped.values) return;
@@ -1680,12 +1667,6 @@ export default function RecordDetail({
1680
  rows: rows.map((row) => ({ ...row, ...scoped.values?.[row.pid] })) });
1681
  return;
1682
  }
1683
- const through = await readThroughTables();
1684
- // ⛔ Not read through ⇒ no request at all. See the guard note above.
1685
- if (!live || !through.has(asked.table)) return;
1686
- const payload = await fetchTableWindow(asked.table,
1687
- { offset: 0, limit: WINDOW_ROWS, related: asked.pin }, () => {});
1688
- if (!live || !payload) return;
1689
  setSiblings({ key: framePinKey, rows: payload.rows, fields: payload.fields });
1690
  })();
1691
  return () => {
@@ -1784,33 +1765,9 @@ export default function RecordDetail({
1784
  [baseLabel, stack]
1785
  );
1786
 
1787
- /**
1788
- * ⭐⭐ CAN THIS EDGE BE SERVED, AND IF NOT, IN WHOSE WORDS? See `RelatedTabState`.
1789
- *
1790
- * ⛔ TWO REASONS A DECLARED EDGE CANNOT BE PINNED TODAY, AND THE CLIENT CAN ONLY SEE ONE OF
1791
- * THEM ON ITS OWN. `served: false` is carried by the entry (`ut_odoo_invoices` is materialised
1792
- * and absent from `GRID_SOURCES`); the second is a target that is not read through at all,
1793
- * which `odoo-tables/status` answers and the entry does not. Both end in the same place: ask
1794
- * the pinned door for ONE row and print the sentence it refuses with.
1795
- * ⛔ THE SENTENCE IS THE SERVER'S, NOT THIS FILE'S. `relations.py` writes three of them, each
1796
- * naming a cause and a recommendation (R6's second sentence). A fourth spelled here would be a
1797
- * second opinion about one wire contract.
1798
- *
1799
- * ⛔⛔ THE **ROSTER** DECIDES WHETHER THE TAB MOUNTS. THE PROBE ONLY SUPPLIES WORDS, AND AN
1800
- * EARLIER DRAFT HAD THIS INVERTED WITH A WHOLE-DATABASE BUG IN IT.
1801
- * The mount has to be gated on THE SAME FACT THE READ CONSULTS, and the read consults
1802
- * `readThroughTables()` (`useCustomerData`: the pin reaches the server only for a `ut_*` scope
1803
- * that roster names). The probe asks a DIFFERENT question of a DIFFERENT door. Those two come
1804
- * apart on one flaky `odoo-tables/status` call, which fails SOFT to the empty set by design:
1805
- * the roster would answer "not read through", the genuinely-served orders door would answer
1806
- * 200 to the probe, the tab would mount `ready`, and `useCustomerData` would fall back to the
1807
- * whole-book read. The result is the ENTIRE orders table painted under a chip that reads
1808
- * "Linked to <one customer>" - a wrong answer wearing the right chrome, which is exactly the
1809
- * failure class this ticket exists to delete.
1810
- * ⇒ Not pinnable by the roster ⇒ REFUSED, whatever the probe says. The probe's only job is to
1811
- * fetch the server's sentence for the state, and `unpinnableNote` covers the one state that
1812
- * has no server sentence (the roster says no while the door answers 200).
1813
- */
1814
  const [tabStateResult, setTabState] = useState<RelatedTabState>(PROBING_TAB_STATE);
1815
  const [tabStateStamp, setTabStateStamp] = useState("");
1816
  const tabState = tabStateStamp === relatedPinKey ? tabStateResult : PROBING_TAB_STATE;
@@ -1870,48 +1827,22 @@ export default function RecordDetail({
1870
  `activeRelated` here would let a later click rewrite an earlier in-flight request. */
1871
  const activeRelated = asked;
1872
  const target = activeRelated.entry.target;
1873
- const through = await readThroughTables();
1874
- /* The roster read is cheap and shared. This check is deliberately BEFORE either route
1875
- that can compile a relation query, so a burst pays for the running intent and the
1876
- final intent, never for the records superseded between them. */
1877
  if (!current(asked)) continue;
1878
- const pinnable = activeRelated.entry.served && through.has(target);
1879
  if (pinnable) {
1880
- commit(asked, { status: "ready" });
1881
- continue;
1882
- }
1883
- if (!through.has(target) && asked.projectedIds) {
1884
- commit(asked, { status: "projected", ids: asked.projectedIds });
1885
- continue;
1886
- }
1887
- const isModuleCache = target === CUSTOMER_TOPIC.key || target === PRODUCT_TOPIC.key;
1888
- if (!through.has(target) && isModuleCache
1889
- && asked.entry.via.direction === "forward") {
1890
- const answer = await fetchModuleRelationTargets(
1891
- asked.pin.table, asked.pin.record, asked.entry);
1892
  if (!current(asked)) continue;
1893
- if (answer.ok) {
1894
- setTabStateStamp(asked.key);
1895
- setTabState({ status: "projected", ids: answer.ids });
1896
- } else {
1897
- commit(asked, {
1898
- status: "refused",
1899
- reason: answer.reason,
1900
- code: answer.code,
1901
- table: target,
1902
- });
1903
- }
1904
- continue;
1905
  }
1906
- const refused = through.has(target) ? await probeRelatedRead(target, asked.pin) : null;
1907
- if (!current(asked)) continue;
1908
- commit(asked, {
1909
- status: "refused",
1910
- reason: refused?.reason ?? unpinnableNote(target),
1911
- code: refused?.code ?? "",
1912
- table: refused?.table ?? target,
1913
- hop: refused?.hop,
1914
- });
1915
  }
1916
  } finally {
1917
  coordinator.running = false;
@@ -1946,7 +1877,7 @@ export default function RecordDetail({
1946
  return "";
1947
  }, [activeRelated, relatedPin, tabState, tabViewKey]);
1948
  const scopedProductProjection = Boolean(activeRelated
1949
- && isRelatedProductMetricScope(activeRelated.entry.target, relatedPin));
1950
  const [recordProjection, setRecordProjection] = useState<RecordModeProjection>(
1951
  { key: "", status: "idle" }
1952
  );
@@ -1971,7 +1902,7 @@ export default function RecordDetail({
1971
  const coordinator = recordRequest.current;
1972
  const sequence = coordinator.sequence + 1;
1973
  coordinator.sequence = sequence;
1974
- if ((relatedMode === "grid" && !scopedProductProjection)
1975
  || !recordProjectionKey || !activeRelated || !relatedPin) {
1976
  coordinator.wanted = null;
1977
  setRecordProjection({ key: "", status: "idle" });
@@ -2020,13 +1951,30 @@ export default function RecordDetail({
2020
  }
2021
 
2022
  let rows = payload.rows;
 
2023
  let notice: string | undefined;
2024
  if (asked.source === "pinned") {
2025
- if ((payload.counts?.matched ?? rows.length) > rows.length) {
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2026
  setRecordProjection({
2027
  key: asked.key,
2028
  status: "error",
2029
- message: "This related set is too large for this view. Use Grid to reach every record.",
2030
  });
2031
  continue;
2032
  }
@@ -2047,28 +1995,33 @@ export default function RecordDetail({
2047
  }
2048
  if (missing > 0) notice = "Some linked records are no longer available.";
2049
  }
2050
- if (isRelatedProductMetricScope(asked.target, asked.pin ?? null)
2051
- && payload.fields.some((field) => field.measure) && rows.length > 0 && asked.pin) {
2052
- const scoped = await fetchRelatedProductMeasureValues(
2053
- rows.map((row) => Number(row.pid)), payload.fields, asked.pin,
2054
  () => coordinator.mounted && coordinator.sequence === asked.sequence);
2055
  if (!coordinator.mounted || coordinator.sequence !== asked.sequence) continue;
2056
  if (!scoped.values) {
2057
  setRecordProjection({ key: asked.key, status: "error", message: scoped.reason });
2058
  continue;
2059
  }
2060
- rows = rows.map((row) => ({ ...row, ...scoped.values?.[row.pid] }));
 
 
 
 
 
2061
  if (scoped.reason) notice = scoped.reason;
2062
  }
2063
  const ready: Extract<RecordModeProjection, { status: "ready" }> = {
2064
  key: asked.key,
2065
  status: "ready",
2066
  rows,
2067
- fields: payload.fields,
2068
  today: payload.today,
2069
  notice,
2070
  };
2071
- if (!isRelatedProductMetricScope(asked.target, asked.pin ?? null))
2072
  recordProjectionCache.current.set(asked.key, ready);
2073
  setRecordProjection(ready);
2074
  }
@@ -2088,7 +2041,7 @@ export default function RecordDetail({
2088
  const navigationReadSettled = !activeRelated
2089
  || tabState.status === "refused"
2090
  || (tabState.status === "projected" && tabState.ids.length === 0)
2091
- || (tabState.status !== "probing" && relatedMode === "grid" && !scopedProductProjection)
2092
  || (Object.is(recordProjection.key, recordProjectionKey)
2093
  && (recordProjection.status === "ready" || recordProjection.status === "error"));
2094
  const recordNavigationBusy = Boolean(
@@ -2836,17 +2789,12 @@ export default function RecordDetail({
2836
  drawer only from the base record. R4 names Escape as the other half of drill history, beside
2837
  the breadcrumb, and a reader two hops deep who presses it expects to come back one hop, not
2838
  to lose the whole record.
2839
- ⚠ THIS HOOK TAKES **ONE** `onDismiss` AND FIRES IT FOR BOTH ESCAPE AND AN OUTSIDE
2840
- POINTERDOWN (`OverlaySurface.tsx::useOverlayLayer` — one `dismissRef`, read by
2841
- `useEscapeClose` and by the pointerdown listener alike); there is no second hook to split
2842
- them. So an outside click on a pushed frame ALSO goes up one level. That is a deliberate
2843
- reading of "dismiss the thing on top" rather than an oversight: the thing on top is the
2844
- frame, and dismissing the whole drawer from under a reader who is three hops in would throw
2845
- away more than the gesture asked for. */
2846
  useOverlayLayer({
2847
  panelRef,
2848
  onDismiss: stack.length > 0 ? popFrame : onClose,
2849
- dismissOnOutside: true,
2850
  initialFocus: "[data-overlay-autofocus]",
2851
  trapFocus: true,
2852
  });
@@ -3138,11 +3086,9 @@ export default function RecordDetail({
3138
  ordinary user table. This is wave 27's `LinkedGrid` mount, which W51-T06
3139
  removed the last caller of: the target read through its OWN ordinary door and
3140
  projected to the pid list this record's link cell already carries.
3141
- ⛔ `embedded` AND `related` ARE MUTUALLY EXCLUSIVE BY CONSTRUCTION and this
3142
- mount passes only the first, exactly as the `ready` mount above passes only the
3143
- second. The two modes disagree about WHO evaluates the predicate (the browser
3144
- here, the server there); passing both would ask one grid to do both and mean
3145
- neither. There is no `relatedViewId` for the same reason: `embedded` hides the
3146
  view rail (`hostViews = []`), so a remembered view would be a preference with
3147
  nothing to apply it to.
3148
  ⛔ AND THE CAP IS THE SERVER'S TO REPORT, NOT THIS PANEL'S TO GUESS.
@@ -3162,6 +3108,7 @@ export default function RecordDetail({
3162
  ) : <Suspense fallback={<RecordModeSkeleton mode="grid" />}>
3163
  <RelatedGrid
3164
  key={recordProjectionKey}
 
3165
  scope={relatedScope(activeRelated.entry.target)}
3166
  embedded
3167
  embeddedPayload={scopedProductProjection ? visibleRecordProjection : undefined}
@@ -3204,6 +3151,8 @@ export default function RecordDetail({
3204
  relatedMode === "grid" ? (
3205
  <Suspense fallback={<RecordModeSkeleton mode="grid" />}>
3206
  <RelatedGrid
 
 
3207
  scope={relatedScope(activeRelated.entry.target)}
3208
  related={relatedPin}
3209
  /* ⭐ CLAUSE 9 — a row click NAVIGATES THIS PANEL rather than stacking a
 
64
  `WINDOW_ROWS` are the one windowed read this product owns, and the sibling set a pushed
65
  frame's chevrons page is that read with the frame's own pin on it. */
66
  import { fetchLinkTargets, fetchRecordMeasureValues, fetchRelated, fetchRelatedProductMeasureValues,
67
+ fetchRelatedMeasureValues, fetchTableWindow, fetchTopicRows, isRelatedMetricScope,
68
+ isRelatedProductMetricScope, probeRelatedRead,
69
+ readThroughTables, usesPinnedRows, WINDOW_ROWS } from "./apiBridge";
70
  import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal } from "../apiContract";
71
 
72
  /**
 
576
  * ⛔ THIS AUTHORS NO PROSE AND MINES NONE. R13 asks "you may not see this table" and "this hop
577
  * was filtered" to NAME their subject, and the envelope already carries `table` and `hop` as
578
  * fields; reading the subject out of the sentence with a regular expression would make this file
579
+ * a second author of one wire contract. The sentence stays the server's, whole; this only decides what is
 
580
  * emphasised above it.
581
  *
582
  * ⚠ THE TABLE GOES THROUGH THE DISPLAY-NAME ROSTER, the one producer of a database's name in
 
613
  names the absent database in the server's own words, so there is nothing for a subject line
614
  to add and it stays empty unless a display name genuinely exists. */
615
  if (code === RELATED_REFUSAL.retiredTarget && table) return labelFor(table);
616
+ // A transport failure may have no code. Name its database only when a display name is known.
 
 
 
 
 
 
617
  if (!code && table) return labelFor(table);
618
  return "";
619
  }
 
776
  const EMPTY_FIELDS: Field[] = [];
777
 
778
  /**
779
+ * Legacy reading position only: which target view was last open in this browser.
780
+ * W60 R8 supersedes R5's no-new-server-state ruling: the layout now lives per user in
781
+ * /nav/prefs, keyed by source table and edge. It never edits the target's SavedView.
 
 
782
  * ⚠ Every access is wrapped: a private window, a full quota or a disabled store all throw from
783
  * `localStorage` itself, and a record drawer that cannot open because a preference could not be
784
  * read is a much worse defect than a preference that does not persist.
 
844
  * survive until the rows door itself learns a relation predicate, at which point the state it
845
  * describes stops existing and it goes with it.
846
  */
 
 
 
 
 
 
847
  /**
848
  * ⭐⭐ W53-T25 — THE PIDS IN A LINK CELL, and the shape is the one this product already stores.
849
  *
 
874
  ids: number[];
875
  code: string;
876
  reason: string;
877
+ table?: string;
878
+ hop?: string;
879
  }
880
 
881
  /** Resolve a declared bridge onto a registry-module pool without pretending the pool is a mirror. */
 
884
  record: number,
885
  entry: RelatedEntry,
886
  ): Promise<RelationTargetAnswer> {
887
+ const via = entry.via.direction === "path"
888
+ && Array.isArray(entry.path) && entry.path.length > 0
889
+ && entry.path.every(key => typeof key === "string" && key.trim().length > 0)
890
+ ? entry.path
891
+ : entry.via;
892
  const query = new URLSearchParams({
893
  source,
894
  record: String(record),
895
+ via: JSON.stringify(via),
896
  target: entry.target,
897
  });
898
  try {
 
914
  reason: "The related database returned an unreadable answer. Try again." };
915
  }
916
  const envelope = body as {
917
+ error?: { code?: unknown; message?: unknown; table?: string; hop?: string };
918
+ detail?: { error?: { code?: unknown; message?: unknown; table?: string; hop?: string } };
919
  } | null;
920
  const refusal = envelope?.error ?? envelope?.detail?.error;
921
  return {
 
923
  ids: [],
924
  code: String(refusal?.code ?? "relation_target_unavailable"),
925
  reason: String(refusal?.message ?? "This relation could not be read right now. Try again."),
926
+ table: refusal?.table,
927
+ hop: refusal?.hop,
928
  };
929
  } catch {
930
  return { ok: false, ids: [], code: "relation_target_unavailable",
 
1442
  * and that is cheaper than a second effect whose only job is to mirror this state.
1443
  */
1444
  const [tabViews, setTabViews] = useState<Record<string, string>>(readTabViews);
1445
+ /* R8 uses this exact source-edge identity for the server layout, independent of record pid.
1446
+ Also keep the pre-normalization edge key as a read fallback. Wave 55 made route selection
1447
  semantic so a shorter equivalent path can replace a longer one without losing the open tab,
1448
  but existing browsers may still hold the earlier edge-keyed preference. */
1449
  const legacyTabViewKey = activeRelated
 
1635
  ⛔ THE SIBLING SET IS THE FRAME'S OWN PIN, READ THROUGH THE WINDOWED DOOR. `frame.pin` is
1636
  the pin that fetched the row this frame was pushed from, so the same pin fetches the rest of
1637
  that row set. One window, no predicate, no sort: whatever the related tab was showing.
1638
+ Sibling reads use the same pinned door as the tab. A refused read disables navigation
1639
+ without replacing the surrounding screen.
 
 
1640
  ═══════════════════════════════════════════════════════════════════════════════════════ */
1641
  const framePinKey = frame && frame.pin
1642
  ? JSON.stringify({ table: frame.table, pin: frame.pin })
 
1654
  const asked = JSON.parse(framePinKey) as { table: string; pin: RelatedPin };
1655
  let live = true;
1656
  void (async () => {
1657
+ if (!live || !usesPinnedRows(asked.table, asked.pin)) return;
1658
+ const payload = await fetchTableWindow(asked.table,
1659
+ { offset: 0, limit: WINDOW_ROWS, related: asked.pin }, () => {});
1660
+ if (!live || !payload) return;
1661
  if (isRelatedProductMetricScope(asked.table, asked.pin)) {
1662
+ const rows = payload.rows;
 
 
 
 
 
 
 
 
 
 
 
1663
  const scoped = await fetchRelatedProductMeasureValues(
1664
  rows.map((row) => Number(row.pid)), payload.fields, asked.pin, () => live);
1665
  if (!live || !scoped.values) return;
 
1667
  rows: rows.map((row) => ({ ...row, ...scoped.values?.[row.pid] })) });
1668
  return;
1669
  }
 
 
 
 
 
 
1670
  setSiblings({ key: framePinKey, rows: payload.rows, fields: payload.fields });
1671
  })();
1672
  return () => {
 
1765
  [baseLabel, stack]
1766
  );
1767
 
1768
+ /* Linked reads always use the pinned window door. The tab, sibling reader and data hook
1769
+ consult usesPinnedRows, so a missing status roster cannot select a whole-book fallback.
1770
+ Server refusals stay in the tab, and the coordinator discards superseded requests. */
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1771
  const [tabStateResult, setTabState] = useState<RelatedTabState>(PROBING_TAB_STATE);
1772
  const [tabStateStamp, setTabStateStamp] = useState("");
1773
  const tabState = tabStateStamp === relatedPinKey ? tabStateResult : PROBING_TAB_STATE;
 
1827
  `activeRelated` here would let a later click rewrite an earlier in-flight request. */
1828
  const activeRelated = asked;
1829
  const target = activeRelated.entry.target;
 
 
 
 
1830
  if (!current(asked)) continue;
1831
+ const pinnable = usesPinnedRows(target, asked.pin);
1832
  if (pinnable) {
1833
+ // Both admissions ask the pinned server read. Neither can choose an unpinned
1834
+ // fallback, since useCustomerData consults usesPinnedRows before the roster.
1835
+ const isModuleCache = target === CUSTOMER_TOPIC.key || target === PRODUCT_TOPIC.key;
1836
+ const answer = isModuleCache ? await fetchModuleRelationTargets(
1837
+ asked.pin.table, asked.pin.record, asked.entry) : null;
1838
+ const refused = answer ? (answer.ok ? null : answer)
1839
+ : await probeRelatedRead(target, asked.pin);
 
 
 
 
 
1840
  if (!current(asked)) continue;
1841
+ commit(asked, refused ? {
1842
+ status: "refused", reason: refused.reason, code: refused.code,
1843
+ table: refused.table ?? target, hop: refused.hop,
1844
+ } : { status: "ready" });
 
 
 
 
 
 
 
 
1845
  }
 
 
 
 
 
 
 
 
 
1846
  }
1847
  } finally {
1848
  coordinator.running = false;
 
1877
  return "";
1878
  }, [activeRelated, relatedPin, tabState, tabViewKey]);
1879
  const scopedProductProjection = Boolean(activeRelated
1880
+ && isRelatedMetricScope(activeRelated.entry.target, relatedPin));
1881
  const [recordProjection, setRecordProjection] = useState<RecordModeProjection>(
1882
  { key: "", status: "idle" }
1883
  );
 
1902
  const coordinator = recordRequest.current;
1903
  const sequence = coordinator.sequence + 1;
1904
  coordinator.sequence = sequence;
1905
+ if ((relatedMode === "grid" && tabState.status !== "projected")
1906
  || !recordProjectionKey || !activeRelated || !relatedPin) {
1907
  coordinator.wanted = null;
1908
  setRecordProjection({ key: "", status: "idle" });
 
1951
  }
1952
 
1953
  let rows = payload.rows;
1954
+ let projectionFields = payload.fields;
1955
  let notice: string | undefined;
1956
  if (asked.source === "pinned") {
1957
+ // Complete the pinned set before applying local grid filters or aggregates.
1958
+ // Each page uses the same named pin. No maximum silently truncates the answer.
1959
+ let incomplete = false;
1960
+ while ((payload.counts?.matched ?? rows.length) > rows.length && asked.pin) {
1961
+ const page = await fetchTableWindow(asked.target, {
1962
+ offset: rows.length, limit: RECORD_MODE_WINDOW, related: asked.pin,
1963
+ });
1964
+ if (!coordinator.mounted || coordinator.sequence !== asked.sequence) break;
1965
+ const seen = new Set(rows.map((row) => Number(row.pid)));
1966
+ if (!page || page.rows.length === 0 || page.rows.some((row) => seen.has(Number(row.pid)))) {
1967
+ incomplete = true;
1968
+ break;
1969
+ }
1970
+ rows = [...rows, ...page.rows];
1971
+ }
1972
+ if (!coordinator.mounted || coordinator.sequence !== asked.sequence) continue;
1973
+ if (incomplete) {
1974
  setRecordProjection({
1975
  key: asked.key,
1976
  status: "error",
1977
+ message: "The linked records changed while loading. Reopen this tab to read the complete set.",
1978
  });
1979
  continue;
1980
  }
 
1995
  }
1996
  if (missing > 0) notice = "Some linked records are no longer available.";
1997
  }
1998
+ if (isRelatedMetricScope(asked.target, asked.pin ?? null)
1999
+ && payload.fields.some((field) => field.measure) && asked.pin) {
2000
+ const scoped = await fetchRelatedMeasureValues(
2001
+ asked.target, rows.map((row) => Number(row.pid)), asked.pin,
2002
  () => coordinator.mounted && coordinator.sequence === asked.sequence);
2003
  if (!coordinator.mounted || coordinator.sequence !== asked.sequence) continue;
2004
  if (!scoped.values) {
2005
  setRecordProjection({ key: asked.key, status: "error", message: scoped.reason });
2006
  continue;
2007
  }
2008
+ const allowed = new Set(scoped.fields);
2009
+ const hidden = new Set(payload.fields.filter((field) => field.measure && !allowed.has(field.key))
2010
+ .map((field) => field.key));
2011
+ projectionFields = payload.fields.filter((field) => !hidden.has(field.key));
2012
+ rows = rows.map((row) => ({ ...Object.fromEntries(Object.entries(row)
2013
+ .filter(([key]) => !hidden.has(key))), ...scoped.values?.[row.pid] } as Row));
2014
  if (scoped.reason) notice = scoped.reason;
2015
  }
2016
  const ready: Extract<RecordModeProjection, { status: "ready" }> = {
2017
  key: asked.key,
2018
  status: "ready",
2019
  rows,
2020
+ fields: projectionFields,
2021
  today: payload.today,
2022
  notice,
2023
  };
2024
+ if (!isRelatedMetricScope(asked.target, asked.pin ?? null))
2025
  recordProjectionCache.current.set(asked.key, ready);
2026
  setRecordProjection(ready);
2027
  }
 
2041
  const navigationReadSettled = !activeRelated
2042
  || tabState.status === "refused"
2043
  || (tabState.status === "projected" && tabState.ids.length === 0)
2044
+ || (tabState.status !== "probing" && relatedMode === "grid")
2045
  || (Object.is(recordProjection.key, recordProjectionKey)
2046
  && (recordProjection.status === "ready" || recordProjection.status === "error"));
2047
  const recordNavigationBusy = Boolean(
 
2789
  drawer only from the base record. R4 names Escape as the other half of drill history, beside
2790
  the breadcrumb, and a reader two hops deep who presses it expects to come back one hop, not
2791
  to lose the whole record.
2792
+ W60 R8 keeps pointer clicks outside this modal inert. Its embedded column menu registers
2793
+ above it, so Escape closes that menu first and returns focus to the linked grid. */
 
 
 
 
 
2794
  useOverlayLayer({
2795
  panelRef,
2796
  onDismiss: stack.length > 0 ? popFrame : onClose,
2797
+ dismissOnOutside: false,
2798
  initialFocus: "[data-overlay-autofocus]",
2799
  trapFocus: true,
2800
  });
 
3086
  ordinary user table. This is wave 27's `LinkedGrid` mount, which W51-T06
3087
  removed the last caller of: the target read through its OWN ordinary door and
3088
  projected to the pid list this record's link cell already carries.
3089
+ The projection and pinned read still use different row doors. R8 gives both
3090
+ the same row/schema refusal and the same personal layout store.
3091
+ There is no `relatedViewId` on a projection: `embedded` hides the
 
 
3092
  view rail (`hostViews = []`), so a remembered view would be a preference with
3093
  nothing to apply it to.
3094
  ⛔ AND THE CAP IS THE SERVER'S TO REPORT, NOT THIS PANEL'S TO GUESS.
 
3108
  ) : <Suspense fallback={<RecordModeSkeleton mode="grid" />}>
3109
  <RelatedGrid
3110
  key={recordProjectionKey}
3111
+ personalLayoutKey={legacyTabViewKey}
3112
  scope={relatedScope(activeRelated.entry.target)}
3113
  embedded
3114
  embeddedPayload={scopedProductProjection ? visibleRecordProjection : undefined}
 
3151
  relatedMode === "grid" ? (
3152
  <Suspense fallback={<RecordModeSkeleton mode="grid" />}>
3153
  <RelatedGrid
3154
+ key={legacyTabViewKey}
3155
+ personalLayoutKey={legacyTabViewKey}
3156
  scope={relatedScope(activeRelated.entry.target)}
3157
  related={relatedPin}
3158
  /* ⭐ CLAUSE 9 — a row click NAVIGATES THIS PANEL rather than stacking a
web/src/customer-grid/ViewSidebar.tsx CHANGED
@@ -99,7 +99,8 @@ import { TrashPanel } from "../views-trash/TrashPanel";
99
  * host reads it on the one door `core/grid_events.py::_folder_mutate` already opens. Emitting
100
  * host events from outside `CustomerGrid` is established here: `useCustomerData.ts` does it.
101
  */
102
- import { emitHostEvent, eventId } from "./hostBridge";
 
103
  // ⚠ `SHARED_FOLDER_ID` is no longer imported: W34-T25 replaced both of its call sites with
104
  // `isSyntheticFolderId`, and `noUnusedLocals` turns a leftover import into a build error rather
105
  // than into dead weight. The constant itself is still exported and still used by `folders.ts`.
@@ -343,6 +344,8 @@ export function viewShareMark(
343
  }
344
 
345
  interface ViewSidebarProps {
 
 
346
  /** Granted databases live in this secondary navigator, never in the global shell rail. */
347
  databases?: readonly DataDatabase[];
348
  activeDatabaseKey?: string;
@@ -1188,6 +1191,8 @@ function writeRailPath(databaseKey: string, folderId: string | null): void {
1188
  }
1189
 
1190
  export default function ViewSidebar({
 
 
1191
  databases = [],
1192
  activeDatabaseKey = "",
1193
  databaseFolders = [],
@@ -1239,6 +1244,7 @@ export default function ViewSidebar({
1239
  actionAnchor,
1240
  onActionAnchorConsumed,
1241
  }: ViewSidebarProps) {
 
1242
  // The old managed "Loopable" View folder put an origin label inside every database. Origin now
1243
  // belongs one level up in the Data tree, so its views fall back into the database's root group.
1244
  const folders = useMemo(
@@ -1433,11 +1439,11 @@ export default function ViewSidebar({
1433
  const addView = addFor ? views.find((view) => view.id === addFor.viewId) : undefined;
1434
  const menuView = menu ? views.find((view) => view.id === menu.viewId) : undefined;
1435
  useEffect(() => {
1436
- if (!actionAnchor) return;
1437
  const active = views.find((view) => view.id === activeViewId);
1438
  if (active) setMenu({ viewId: active.id, anchor: actionAnchor });
1439
  onActionAnchorConsumed?.();
1440
- }, [actionAnchor, activeViewId, onActionAnchorConsumed, views]);
1441
  /** C4 — may this viewer change the menu view's IDENTITY? Courtesy only; the host is the
1442
  * wall. C3's lock toggle ANDs with this rather than replacing it: the two contracts
1443
  * compose (C4 says who may edit, C3 says who may freeze the mode). */
@@ -1713,8 +1719,8 @@ export default function ViewSidebar({
1713
  reorderViews(dragged, viewId);
1714
  },
1715
  });
1716
- const viewsReorderable = views.length > 1;
1717
- const foldersOn = !!folders && !!folderIdOf && !!onItemMove;
1718
  /**
1719
  * ⭐⭐ WAVE 41 · T33 (instruction 12, R1, C9) — THE FOLDER LIST, READ AS A TREE.
1720
  *
@@ -2779,7 +2785,7 @@ export default function ViewSidebar({
2779
  ⛔ CONSEQUENCE FOR ANY LATER EDIT HERE: these class names are a shared contract now,
2780
  not private to this button. Changing the treatment means changing both call sites, and
2781
  moving it to a local class re-opens the drift the owner reported. */}
2782
- <div className="cg-create-new">
2783
  <button
2784
  type="button"
2785
  className="cg-link-btn cg-create-btn"
@@ -2811,7 +2817,7 @@ export default function ViewSidebar({
2811
  <span className="cg-create-icon" aria-hidden="true">+</span>
2812
  <span className="cg-create-label">Create new…</span>
2813
  </button>
2814
- </div>
2815
 
2816
  {/* Owner item 9 — "Find a view". Borderless on the white rail (no box until it is
2817
  being used); focus paints the brand-purple outline. Clearing the query restores
@@ -3351,7 +3357,7 @@ export default function ViewSidebar({
3351
  group, for the reason the block above gives: a colleague's shared folder is no
3352
  more the reader's to rename, duplicate or delete than "Shared with me" is, and
3353
  every row of that menu would be refused by a server that has no such folder. */}
3354
- {isSynthetic || isManaged ? null : (
3355
  <button
3356
  type="button"
3357
  className="cg-view-more"
@@ -3650,7 +3656,7 @@ export default function ViewSidebar({
3650
  )}
3651
  </button>
3652
  )}
3653
- <button
3654
  type="button"
3655
  className="cg-view-more"
3656
  aria-label={`Actions for ${viewDisplayName(view)}`}
@@ -3699,7 +3705,7 @@ export default function ViewSidebar({
3699
  }}
3700
  >
3701
  ···
3702
- </button>
3703
  {/* Wave-10 item 9 inverted this: the description now renders HERE, on the
3704
  row, and the across-the-table banner in CustomerGrid is gone. Still one
3705
  place, not two — and now it is the place that names the view, and EVERY
@@ -3733,7 +3739,7 @@ export default function ViewSidebar({
3733
  ⛔ DELETE ASKS ONCE, AND THE ASK IS NOT DECORATION: there is no store history behind a
3734
  deleted view, so the confirm is the only thing standing between a mis-shift and work
3735
  that cannot be brought back. `onDelete` is called from the armed branch alone. */}
3736
- {railSelected.length > 0 && (
3737
  <div className="cg-railsel" role="group" aria-label="Selected views">
3738
  {railDeleteArmed ? (
3739
  <>
 
99
  * host reads it on the one door `core/grid_events.py::_folder_mutate` already opens. Emitting
100
  * host events from outside `CustomerGrid` is established here: `useCustomerData.ts` does it.
101
  */
102
+ import { bindHostEvent, eventId } from "./hostBridge";
103
+ import type { SurfaceScope } from "./apiBridge";
104
  // ⚠ `SHARED_FOLDER_ID` is no longer imported: W34-T25 replaced both of its call sites with
105
  // `isSyntheticFolderId`, and `noUnusedLocals` turns a leftover import into a build error rather
106
  // than into dead weight. The constant itself is still exported and still used by `folders.ts`.
 
344
  }
345
 
346
  interface ViewSidebarProps {
347
+ scope?: SurfaceScope;
348
+ readOnly?: boolean;
349
  /** Granted databases live in this secondary navigator, never in the global shell rail. */
350
  databases?: readonly DataDatabase[];
351
  activeDatabaseKey?: string;
 
1191
  }
1192
 
1193
  export default function ViewSidebar({
1194
+ scope = "customer",
1195
+ readOnly = false,
1196
  databases = [],
1197
  activeDatabaseKey = "",
1198
  databaseFolders = [],
 
1244
  actionAnchor,
1245
  onActionAnchorConsumed,
1246
  }: ViewSidebarProps) {
1247
+ const emitHostEvent = useMemo(() => bindHostEvent(scope, !readOnly), [scope, readOnly]);
1248
  // The old managed "Loopable" View folder put an origin label inside every database. Origin now
1249
  // belongs one level up in the Data tree, so its views fall back into the database's root group.
1250
  const folders = useMemo(
 
1439
  const addView = addFor ? views.find((view) => view.id === addFor.viewId) : undefined;
1440
  const menuView = menu ? views.find((view) => view.id === menu.viewId) : undefined;
1441
  useEffect(() => {
1442
+ if (!actionAnchor || readOnly) return;
1443
  const active = views.find((view) => view.id === activeViewId);
1444
  if (active) setMenu({ viewId: active.id, anchor: actionAnchor });
1445
  onActionAnchorConsumed?.();
1446
+ }, [actionAnchor, activeViewId, onActionAnchorConsumed, views, readOnly]);
1447
  /** C4 — may this viewer change the menu view's IDENTITY? Courtesy only; the host is the
1448
  * wall. C3's lock toggle ANDs with this rather than replacing it: the two contracts
1449
  * compose (C4 says who may edit, C3 says who may freeze the mode). */
 
1719
  reorderViews(dragged, viewId);
1720
  },
1721
  });
1722
+ const viewsReorderable = !readOnly && views.length > 1;
1723
+ const foldersOn = !readOnly && !!folders && !!folderIdOf && !!onItemMove;
1724
  /**
1725
  * ⭐⭐ WAVE 41 · T33 (instruction 12, R1, C9) — THE FOLDER LIST, READ AS A TREE.
1726
  *
 
2785
  ⛔ CONSEQUENCE FOR ANY LATER EDIT HERE: these class names are a shared contract now,
2786
  not private to this button. Changing the treatment means changing both call sites, and
2787
  moving it to a local class re-opens the drift the owner reported. */}
2788
+ {!readOnly && <div className="cg-create-new">
2789
  <button
2790
  type="button"
2791
  className="cg-link-btn cg-create-btn"
 
2817
  <span className="cg-create-icon" aria-hidden="true">+</span>
2818
  <span className="cg-create-label">Create new…</span>
2819
  </button>
2820
+ </div>}
2821
 
2822
  {/* Owner item 9 — "Find a view". Borderless on the white rail (no box until it is
2823
  being used); focus paints the brand-purple outline. Clearing the query restores
 
3357
  group, for the reason the block above gives: a colleague's shared folder is no
3358
  more the reader's to rename, duplicate or delete than "Shared with me" is, and
3359
  every row of that menu would be refused by a server that has no such folder. */}
3360
+ {readOnly || isSynthetic || isManaged ? null : (
3361
  <button
3362
  type="button"
3363
  className="cg-view-more"
 
3656
  )}
3657
  </button>
3658
  )}
3659
+ {!readOnly && <button
3660
  type="button"
3661
  className="cg-view-more"
3662
  aria-label={`Actions for ${viewDisplayName(view)}`}
 
3705
  }}
3706
  >
3707
  ···
3708
+ </button>}
3709
  {/* Wave-10 item 9 inverted this: the description now renders HERE, on the
3710
  row, and the across-the-table banner in CustomerGrid is gone. Still one
3711
  place, not two — and now it is the place that names the view, and EVERY
 
3739
  ⛔ DELETE ASKS ONCE, AND THE ASK IS NOT DECORATION: there is no store history behind a
3740
  deleted view, so the confirm is the only thing standing between a mis-shift and work
3741
  that cannot be brought back. `onDelete` is called from the armed branch alone. */}
3742
+ {!readOnly && railSelected.length > 0 && (
3743
  <div className="cg-railsel" role="group" aria-label="Selected views">
3744
  {railDeleteArmed ? (
3745
  <>
web/src/customer-grid/apiBridge.ts CHANGED
@@ -44,7 +44,6 @@ import {
44
  API_V1,
45
  CREDENTIALS,
46
  DATA_ERROR_EVENT,
47
- DERIVED_CELLS_EVENT,
48
  ROWS_STALE_EVENT,
49
  TOAST_EVENT,
50
  WORKSPACE_STALE_EVENT,
@@ -57,11 +56,83 @@ import { changedBuckets } from "./liveWorkspace";
57
  import type { ChangeTokens } from "./liveWorkspace";
58
  import { CUSTOMER_TOPIC, relatedEntries, relatedRefusals } from "./types";
59
  import type { CustomersPayload, Field, FilterNode, GridLimit, GridWorkspace, HostEvent,
60
- RelatedEntry, RelatedPin, RelatedRefusal, Row, SortSpec, TopicConfig } from "./types";
61
  import type { TsPayload, TsRequest } from "./timeSeriesData";
62
 
63
  const JSON_HEADERS = { "Content-Type": "application/json" };
64
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
65
  async function readJson(res: Response): Promise<unknown> {
66
  try {
67
  return await res.json();
@@ -196,6 +267,7 @@ export function clearTopicRowsCache(rowsPath: string): void {
196
  * /tables/{key}/shared/{pid}` writes a cell that rides the window payload's own `fields`/rows.
197
  */
198
  export function dropTableRowsCache(tableKey: string): void {
 
199
  const prefixes = [`tables/${tableKey}/rows`, `odoo-tables/${tableKey}/rows`];
200
  for (const key of [...rowsCache.keys()])
201
  if (prefixes.some((p) => key === p || key.startsWith(`${p}?`))) rowsCache.delete(key);
@@ -354,7 +426,12 @@ export interface RowWindowRequest {
354
  * ⚠ Empty parts are OMITTED, not sent blank: a view with no filter must produce the identical
355
  * path the first (predicate-free) window used, or the very first scroll misses the cache.
356
  */
 
 
 
 
357
  export function windowRowsPath(tableKey: string, req: RowWindowRequest): string {
 
358
  const q = new URLSearchParams();
359
  q.set("offset", String(Math.max(0, Math.floor(req.offset || 0))));
360
  q.set("limit", String(Math.max(1, Math.floor(req.limit || WINDOW_ROWS))));
@@ -503,6 +580,7 @@ export async function fetchTableWindow(
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);
@@ -529,6 +607,24 @@ export async function fetchTableWindow(
529
  fail("The server sent an unreadable payload.");
530
  return null;
531
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
532
  rowsCache.set(path, { at: Date.now(), payload });
533
  return payload;
534
  }
@@ -545,6 +641,47 @@ export function isRelatedProductMetricScope(tableKey: string, related: RelatedPi
545
  : via.direction === "forward" && (via.field === "products_ordered" || via.key === "products_ordered");
546
  }
547
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
548
  /** Customer-scoped Metric overlays; no client amounts, field specs or Odoo ids are authority. */
549
  export async function fetchRelatedProductMeasureValues(
550
  pids: number[], fields: Field[], related: RelatedPin, isCurrent: () => boolean
@@ -915,7 +1052,7 @@ export async function fetchWorkspace(
915
  // to the server, which is what keeps the memo from becoming a second source of truth.
916
  if (opts.allowCached === true) {
917
  const hit = wsCache.get(scope);
918
- if (hit && Date.now() - hit.at < CUSTOMERS_FRESH_MS) return hit.ws;
919
  }
920
  let res: Response;
921
  try {
@@ -949,8 +1086,34 @@ export async function fetchWorkspace(
949
  // path can never leave a stale envelope behind for the next switch to serve.
950
  // ⚠ A FAILURE LEAVES THE PREVIOUS ENTRY ALONE rather than poisoning it with `null` — the same
951
  // "absent stays absent, never blank a live panel" posture `reread()` already takes.
952
- if (good) wsCache.set(scope, { at: Date.now(), ws: good });
953
- return good;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
954
  }
955
 
956
  // --- the CHANGE POLLER (wave 29, item 20 / R11 / contract C6) ---------------
@@ -1863,11 +2026,8 @@ let pending: QueuedEvent[] = [];
1863
  let inFlight = false;
1864
 
1865
  /**
1866
- * Which SURFACE this grid is drawing — `customer` (the whole scoped pool),
1867
- * `cohort` (hand-curated sets) or `product` (the SKU table — wave 16 C-TOPIC).
1868
- * It lives at module scope beside the queue on purpose: the queue is already
1869
- * module-level, and an event must carry the scope it was CREATED under even if
1870
- * it drains after a route change.
1871
  *
1872
  * ⚠ The server refuses an unknown value rather than defaulting it, so this is
1873
  * never a free-text field. Read and write must agree on what a scope is: the
@@ -1890,10 +2050,8 @@ export function setSurfaceScope(scope: SurfaceScope): void {
1890
  * so that derivation would have filed every alert raised there against the CUSTOMER topic:
1891
  * a silently wrong write, on a door that answers 200.
1892
  *
1893
- * This is the same value the grid stamps on every event it emits, read back. It is module
1894
- * state rather than a prop for the reason stated above it — an event must carry the scope it
1895
- * was CREATED under even if it drains after a route change — and that is precisely why it,
1896
- * and not the URL, is the honest answer to "which database is on screen".
1897
  */
1898
  export function currentSurfaceScope(): SurfaceScope {
1899
  return surfaceScope;
@@ -1982,8 +2140,12 @@ function applyEventResult(body: unknown): void {
1982
  // returned here rather than waiting for the `/workspace` re-read below. Raised BEFORE the
1983
  // stale signal so the numbers paint on the earlier of the two, whichever the server sent.
1984
  // Shape-checked, because a shortcut that corrupts rows is worse than no shortcut.
1985
- if (b?.derived && typeof b.derived === "object" && !Array.isArray(b.derived))
1986
- signal(DERIVED_CELLS_EVENT, b.derived);
 
 
 
 
1987
 
1988
  // The server already tells us when a write changed durable state — `rerender`
1989
  // is exactly the flag the Streamlit adapter uses to trigger its own rerun. We
@@ -1997,10 +2159,9 @@ function applyEventResult(body: unknown): void {
1997
 
1998
  /** The sink hostBridge falls through to in standalone. Returns true: the event
1999
  * is now OURS (queued and owned), which is all the caller ever needed. */
2000
- function standaloneSink(event: HostEvent): boolean {
2001
- // ⭐⭐ W51-T06 — STAMPED HERE, at the moment the event is created, which is the only moment
2002
- // the surface it belongs to is knowable. See `QueuedEvent`.
2003
- pending.push({ event, scope: surfaceScope });
2004
  if (pending.length > MAX_REPLAY) pending.shift();
2005
  void drain();
2006
  return true;
 
44
  API_V1,
45
  CREDENTIALS,
46
  DATA_ERROR_EVENT,
 
47
  ROWS_STALE_EVENT,
48
  TOAST_EVENT,
49
  WORKSPACE_STALE_EVENT,
 
56
  import type { ChangeTokens } from "./liveWorkspace";
57
  import { CUSTOMER_TOPIC, relatedEntries, relatedRefusals } from "./types";
58
  import type { CustomersPayload, Field, FilterNode, GridLimit, GridWorkspace, HostEvent,
59
+ RelatedEntry, RelatedPin, RelatedRefusal, Row, SortSpec, TopicConfig, ViewConfig } from "./types";
60
  import type { TsPayload, TsRequest } from "./timeSeriesData";
61
 
62
  const JSON_HEADERS = { "Content-Type": "application/json" };
63
 
64
+ /** R8 layout vocabulary. Membership, row values and schema never ride this door. */
65
+ export type PersonalGridLayout = Pick<ViewConfig,
66
+ "order" | "visible" | "widths" | "sorts" | "filters" | "filterConj" | "groupBy">;
67
+
68
+ export function personalGridLayout(config: ViewConfig): PersonalGridLayout {
69
+ return {
70
+ order: config.order, visible: config.visible, widths: config.widths,
71
+ sorts: config.sorts, filters: config.filters, filterConj: config.filterConj ?? "and",
72
+ groupBy: config.groupBy,
73
+ };
74
+ }
75
+
76
+ // Only outstanding writes live here, never a user's cached prefs. Remounts await the write
77
+ // before GET; a tab switch cannot cancel it or hydrate from the server's pre-save snapshot.
78
+ const personalLayoutWrites = new Map<string, {
79
+ next: PersonalGridLayout | null;
80
+ task: Promise<boolean>;
81
+ }>();
82
+
83
+ export function savePersonalGridLayout(key: string, layout: PersonalGridLayout): Promise<boolean> {
84
+ const pending = personalLayoutWrites.get(key);
85
+ if (pending) {
86
+ pending.next = layout;
87
+ return pending.task;
88
+ }
89
+ const entry = { next: layout as PersonalGridLayout | null, task: Promise.resolve(false) };
90
+ personalLayoutWrites.set(key, entry);
91
+ entry.task = Promise.resolve().then(async () => {
92
+ let saved = true;
93
+ try {
94
+ while (entry.next) {
95
+ const next = entry.next;
96
+ entry.next = null;
97
+ try {
98
+ const res = await fetch(`${API_V1}/nav/prefs`, {
99
+ method: "POST", credentials: CREDENTIALS, headers: JSON_HEADERS,
100
+ body: JSON.stringify({ linkedLayouts: { [key]: next } }),
101
+ keepalive: true,
102
+ });
103
+ if (handledSession(res)) { entry.next = null; return false; }
104
+ if (!res.ok) throw new Error("layout write refused");
105
+ } catch {
106
+ saved = false;
107
+ signal(TOAST_EVENT, "Your grid layout could not be saved. Change a view control to retry.");
108
+ }
109
+ }
110
+ return saved;
111
+ } finally {
112
+ personalLayoutWrites.delete(key);
113
+ }
114
+ });
115
+ return entry.task;
116
+ }
117
+
118
+ export async function fetchPersonalGridLayout(key: string): Promise<{
119
+ ok: boolean; layout: Partial<PersonalGridLayout> | null;
120
+ }> {
121
+ await personalLayoutWrites.get(key)?.task;
122
+ try {
123
+ const res = await fetch(`${API_V1}/nav/prefs`, { credentials: CREDENTIALS, cache: "no-store" });
124
+ if (handledSession(res)) return { ok: false, layout: null };
125
+ if (!res.ok) throw new Error("layout read refused");
126
+ const json = await readJson(res) as { prefs?: { linkedLayouts?: Record<string, PersonalGridLayout> } } | null;
127
+ if (!json?.prefs) throw new Error("invalid preferences");
128
+ const layout = json.prefs.linkedLayouts?.[key];
129
+ return { ok: true, layout: layout && typeof layout === "object" ? layout : null };
130
+ } catch {
131
+ signal(TOAST_EVENT, "Your saved grid layout could not be loaded. Reopen this tab to retry.");
132
+ return { ok: false, layout: null };
133
+ }
134
+ }
135
+
136
  async function readJson(res: Response): Promise<unknown> {
137
  try {
138
  return await res.json();
 
267
  * /tables/{key}/shared/{pid}` writes a cell that rides the window payload's own `fields`/rows.
268
  */
269
  export function dropTableRowsCache(tableKey: string): void {
270
+ tableKey = tableKey === "customer" ? "customer_data" : tableKey === "product" ? "product_data" : tableKey;
271
  const prefixes = [`tables/${tableKey}/rows`, `odoo-tables/${tableKey}/rows`];
272
  for (const key of [...rowsCache.keys()])
273
  if (prefixes.some((p) => key === p || key.startsWith(`${p}?`))) rowsCache.delete(key);
 
426
  * ⚠ Empty parts are OMITTED, not sent blank: a view with no filter must produce the identical
427
  * path the first (predicate-free) window used, or the very first scroll misses the cache.
428
  */
429
+ export function usesPinnedRows(tableKey: string, related: RelatedPin | null | undefined): boolean {
430
+ return Boolean(tableKey && related);
431
+ }
432
+
433
  export function windowRowsPath(tableKey: string, req: RowWindowRequest): string {
434
+ tableKey = tableKey === "customer" ? "customer_data" : tableKey === "product" ? "product_data" : tableKey;
435
  const q = new URLSearchParams();
436
  q.set("offset", String(Math.max(0, Math.floor(req.offset || 0))));
437
  q.set("limit", String(Math.max(1, Math.floor(req.limit || WINDOW_ROWS))));
 
580
  req: RowWindowRequest,
581
  onFailure?: (reason: string) => void
582
  ): Promise<CustomersPayload | null> {
583
+ tableKey = tableKey === "customer" ? "customer_data" : tableKey === "product" ? "product_data" : tableKey;
584
  // Optional record enrichment reports its failure inline without replacing the open drawer.
585
  const fail = onFailure ?? ((reason: string) => signal(DATA_ERROR_EVENT, reason));
586
  const path = windowRowsPath(tableKey, req);
 
607
  fail("The server sent an unreadable payload.");
608
  return null;
609
  }
610
+ if (req.related && payload.fields.some((field) => field.measure)) {
611
+ const scoped = await fetchRelatedMeasureValues(tableKey, payload.rows.map((row) => Number(row.pid)),
612
+ req.related, () => true);
613
+ if (!scoped.values) {
614
+ fail(scoped.reason);
615
+ return null;
616
+ }
617
+ const allowed = new Set(scoped.fields);
618
+ const hidden = new Set(payload.fields.filter((field) => field.measure && !allowed.has(field.key))
619
+ .map((field) => field.key));
620
+ payload.fields = payload.fields.filter((field) => !hidden.has(field.key));
621
+ payload.rows = payload.rows.map((row) => ({ ...Object.fromEntries(Object.entries(row)
622
+ .filter(([key]) => !hidden.has(key))), ...scoped.values?.[row.pid] } as Row));
623
+ if (scoped.reason) payload.limits = [...(payload.limits ?? []).filter((limit) => limit.subject !== "Linked metrics"), {
624
+ subject: "Linked metrics", cause: scoped.reason,
625
+ recommendation: "Check the metric source binding and period, then reopen this tab.",
626
+ }];
627
+ }
628
  rowsCache.set(path, { at: Date.now(), payload });
629
  return payload;
630
  }
 
641
  : via.direction === "forward" && (via.field === "products_ordered" || via.key === "products_ordered");
642
  }
643
 
644
+ /** Linked-grid metrics follow pin presence, including manual and two-hop paths. */
645
+ export function isRelatedMetricScope(tableKey: string, related: RelatedPin | null): boolean {
646
+ return usesPinnedRows(tableKey, related);
647
+ }
648
+
649
+ /** The server owns fields, catalogue admission, membership and refusals. */
650
+ export async function fetchRelatedMeasureValues(
651
+ tableKey: string, pids: number[], related: RelatedPin, isCurrent: () => boolean
652
+ ): Promise<{ values: Record<number, Partial<Row>> | null; fields: string[]; reason: string }> {
653
+ const unavailable = { values: null, fields: [], reason: "Metrics for these linked records are unavailable. Try again." };
654
+ if (!isCurrent()) return unavailable;
655
+ try {
656
+ const res = await fetch(`${API_V1}/tables/${encodeURIComponent(tableKey)}/related-metrics`, {
657
+ method: "POST", credentials: CREDENTIALS, headers: JSON_HEADERS,
658
+ body: JSON.stringify({ related, pids }),
659
+ });
660
+ if (handledSession(res) || !isCurrent()) return unavailable;
661
+ const body = await readJson(res) as {
662
+ ok?: boolean; values?: Record<number, Partial<Row>>; fields?: string[];
663
+ refusals?: { field?: string; message?: string }[];
664
+ scope?: { table?: string; related?: RelatedPin; pids?: number[] };
665
+ } | null;
666
+ if (!res.ok) return { ...unavailable, reason: refusalMessage(body, res.status) };
667
+ if (!body?.ok || body.scope?.table !== tableKey
668
+ || JSON.stringify(body.scope.related) !== JSON.stringify(related)
669
+ || !Array.isArray(body.fields) || !Array.isArray(body.refusals)) return unavailable;
670
+ const values: Record<number, Partial<Row>> = {};
671
+ for (const pid of pids) {
672
+ const cell = body.values?.[pid];
673
+ if (!cell || !body.scope.pids?.includes(pid)
674
+ || body.fields.some((key) => !Object.prototype.hasOwnProperty.call(cell, key))) return unavailable;
675
+ values[pid] = Object.fromEntries(body.fields.map((key) => [key,
676
+ body.refusals?.some((refusal) => !refusal.field || refusal.field === key) ? null : cell[key]]));
677
+ }
678
+ return { values, fields: body.fields,
679
+ reason: [...new Set(body.refusals.map((refusal) => refusal.message).filter(Boolean))].join(" ") };
680
+ } catch {
681
+ return unavailable;
682
+ }
683
+ }
684
+
685
  /** Customer-scoped Metric overlays; no client amounts, field specs or Odoo ids are authority. */
686
  export async function fetchRelatedProductMeasureValues(
687
  pids: number[], fields: Field[], related: RelatedPin, isCurrent: () => boolean
 
1052
  // to the server, which is what keeps the memo from becoming a second source of truth.
1053
  if (opts.allowCached === true) {
1054
  const hit = wsCache.get(scope);
1055
+ if (hit && Date.now() - hit.at < CUSTOMERS_FRESH_MS) return workspaceWithoutMetricCells(hit.ws);
1056
  }
1057
  let res: Response;
1058
  try {
 
1086
  // path can never leave a stale envelope behind for the next switch to serve.
1087
  // ⚠ A FAILURE LEAVES THE PREVIOUS ENTRY ALONE rather than poisoning it with `null` — the same
1088
  // "absent stays absent, never blank a live panel" posture `reread()` already takes.
1089
+ if (good) {
1090
+ const previous = wsCache.get(scope)?.ws;
1091
+ wsCache.set(scope, { at: Date.now(), ws: good });
1092
+ // A refreshed metric definition or answer is read again through each grid's own pin.
1093
+ // The same rows door still supplies the ordinary record's global Details values.
1094
+ if (previous && JSON.stringify(metricWorkspaceCells(previous)) !== JSON.stringify(metricWorkspaceCells(good))) {
1095
+ rowsCache.clear();
1096
+ signal(ROWS_STALE_EVENT);
1097
+ }
1098
+ }
1099
+ return good ? workspaceWithoutMetricCells(good) : null;
1100
+ }
1101
+
1102
+ function metricWorkspaceCells(workspace: GridWorkspace): unknown {
1103
+ const fields = (workspace.fields ?? []).filter((field) => field.measure);
1104
+ if (fields.length === 0) return null;
1105
+ const keys = new Set(fields.map((field) => field.key));
1106
+ return { fields, cells: Object.fromEntries(Object.entries(workspace.derived ?? {}).map(([pid, cells]) =>
1107
+ [pid, Object.fromEntries(Object.entries(cells).filter(([key]) => keys.has(key)))])) };
1108
+ }
1109
+
1110
+ /** Workspace metadata is shared by pinned and ordinary grids; metric amounts are row data. */
1111
+ export function workspaceWithoutMetricCells(workspace: GridWorkspace): GridWorkspace {
1112
+ const metrics = new Set((workspace.fields ?? []).filter((field) => field.measure).map((field) => field.key));
1113
+ const admitted = Array.isArray(workspace.measures) ? new Set(workspace.measures.map((measure) => measure.key)) : null;
1114
+ const fields = workspace.fields?.filter((field) => !field.measure || admitted === null || admitted.has(field.measure.key));
1115
+ return { ...workspace, fields, derived: Object.fromEntries(Object.entries(workspace.derived ?? {}).map(([pid, cells]) =>
1116
+ [pid, Object.fromEntries(Object.entries(cells).filter(([key]) => !metrics.has(key)))])) };
1117
  }
1118
 
1119
  // --- the CHANGE POLLER (wave 29, item 20 / R11 / contract C6) ---------------
 
2026
  let inFlight = false;
2027
 
2028
  /**
2029
+ * Foreground surface identity for legacy shell/read consumers. W60-T27 removes it from
2030
+ * event stamping: emitHostEvent takes a scope captured by the emitting grid instance.
 
 
 
2031
  *
2032
  * ⚠ The server refuses an unknown value rather than defaulting it, so this is
2033
  * never a free-text field. Read and write must agree on what a scope is: the
 
2050
  * so that derivation would have filed every alert raised there against the CUSTOMER topic:
2051
  * a silently wrong write, on a door that answers 200.
2052
  *
2053
+ * This reports the foreground grid only. A nested grid never binds it, and no event writer
2054
+ * reads it. Each event carries the scope of the instance that created its callback.
 
 
2055
  */
2056
  export function currentSurfaceScope(): SurfaceScope {
2057
  return surfaceScope;
 
2140
  // returned here rather than waiting for the `/workspace` re-read below. Raised BEFORE the
2141
  // stale signal so the numbers paint on the earlier of the two, whichever the server sent.
2142
  // Shape-checked, because a shortcut that corrupts rows is worse than no shortcut.
2143
+ if (b?.derived && typeof b.derived === "object" && !Array.isArray(b.derived)) {
2144
+ // A broadcast has no parent pin. Re-read every receiver through its own rows door.
2145
+ // Non-metric derived cells still arrive through the workspace refresh below.
2146
+ rowsCache.clear();
2147
+ signal(ROWS_STALE_EVENT);
2148
+ }
2149
 
2150
  // The server already tells us when a write changed durable state — `rerender`
2151
  // is exactly the flag the Streamlit adapter uses to trigger its own rerun. We
 
2159
 
2160
  /** The sink hostBridge falls through to in standalone. Returns true: the event
2161
  * is now OURS (queued and owned), which is all the caller ever needed. */
2162
+ function standaloneSink(event: HostEvent, scope: SurfaceScope): boolean {
2163
+ // W60-T27: the instance supplies the stamp. The foreground scope is never a write target.
2164
+ pending.push({ event, scope });
 
2165
  if (pending.length > MAX_REPLAY) pending.shift();
2166
  void drain();
2167
  return true;
web/src/customer-grid/hostBridge.ts CHANGED
@@ -1,4 +1,5 @@
1
  import type { HostEvent } from "./types";
 
2
 
3
  const READY = "streamlit:componentReady";
4
  const RENDER = "streamlit:render";
@@ -80,21 +81,27 @@ const PENDING: HostEvent[] = [];
80
  * left. Null until installed — an un-installed standalone drops events exactly
81
  * as it always did, which is what keeps this change inert in the embed.
82
  */
83
- type EventSink = (event: HostEvent) => boolean;
84
  let standaloneSink: EventSink | null = null;
85
 
86
  export function setStandaloneSink(sink: EventSink | null): void {
87
  standaloneSink = sink;
88
  }
89
 
90
- export function emitHostEvent(event: HostEvent): boolean {
91
- if (!isStreamlitComponent()) return standaloneSink ? standaloneSink(event) : false;
92
  PENDING.push(event);
93
  if (PENDING.length > 24) PENDING.shift();
94
  post(SET_VALUE, { value: { events: [...PENDING] }, dataType: "json" });
95
  return true;
96
  }
97
 
 
 
 
 
 
 
98
  export function eventId(prefix: string): string {
99
  const cryptoId =
100
  typeof crypto !== "undefined" && "randomUUID" in crypto
 
1
  import type { HostEvent } from "./types";
2
+ import type { SurfaceScope } from "./apiBridge";
3
 
4
  const READY = "streamlit:componentReady";
5
  const RENDER = "streamlit:render";
 
81
  * left. Null until installed — an un-installed standalone drops events exactly
82
  * as it always did, which is what keeps this change inert in the embed.
83
  */
84
+ type EventSink = (event: HostEvent, scope: SurfaceScope) => boolean;
85
  let standaloneSink: EventSink | null = null;
86
 
87
  export function setStandaloneSink(sink: EventSink | null): void {
88
  standaloneSink = sink;
89
  }
90
 
91
+ export function emitHostEvent(event: HostEvent, scope: SurfaceScope = "customer"): boolean {
92
+ if (!isStreamlitComponent()) return standaloneSink ? standaloneSink(event, scope) : false;
93
  PENDING.push(event);
94
  if (PENDING.length > 24) PENDING.shift();
95
  post(SET_VALUE, { value: { events: [...PENDING] }, dataType: "json" });
96
  return true;
97
  }
98
 
99
+ /** Capture the emitting grid's scope, including callbacks run after another grid renders.
100
+ * Read-only grids have no event write door; their personal layout uses /nav/prefs. */
101
+ export function bindHostEvent(scope: SurfaceScope, writable = true): (event: HostEvent) => boolean {
102
+ return (event) => writable ? emitHostEvent(event, scope) : false;
103
+ }
104
+
105
  export function eventId(prefix: string): string {
106
  const cryptoId =
107
  typeof crypto !== "undefined" && "randomUUID" in crypto
web/src/customer-grid/useCustomerData.ts CHANGED
@@ -33,20 +33,23 @@ import {
33
  fetchAssignedCustomerRows,
34
  fetchTopicRows,
35
  fetchWorkspace,
 
 
36
  mergeWindow,
37
  patchTopicRow,
38
  readThroughTables,
 
39
  setSurfaceScope,
40
  subscribeChanges,
41
  WINDOW_ROWS,
42
  } from "./apiBridge";
43
- import type { RowWindowRequest } from "./apiBridge";
44
  import { DERIVED_CELLS_EVENT, ROWS_STALE_EVENT, WORKSPACE_STALE_EVENT } from "../apiContract";
45
  import { planChangeReaction, rowsRefetchDelay } from "./liveWorkspace";
46
  import { signal } from "../apiContract";
47
  import type { SurfaceScope } from "./apiBridge";
48
  import {
49
- emitHostEvent,
50
  eventId,
51
  isStreamlitComponent,
52
  readHostArgs,
@@ -55,6 +58,27 @@ import {
55
  import { journalUpsert, reconcileCellJournal } from "./optimism";
56
  import type { CellJournalEntry } from "./optimism";
57
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
58
  // Embed handshake: the host page sets `window.__AIOS_GRID__ = { fields, rows }`.
59
  // Returns the payload when present & well-formed, else null (standalone mode).
60
  function readEmbed(): CustomersPayload | null {
@@ -260,6 +284,7 @@ export function useCustomerData(
260
  const bindSurface = !suppliedPayload && options.bindSurface !== false;
261
  const includeWorkspace = !suppliedPayload && options.includeWorkspace !== false;
262
  const writable = !suppliedPayload && options.writable !== false;
 
263
  /**
264
  * ⭐⭐ W51-T06 / C6 — THE PIN, AS A STRING, AND THAT IS THE WHOLE OF THE STALE-CLOSURE FIX.
265
  *
@@ -276,10 +301,7 @@ export function useCustomerData(
276
  () => (relatedKey ? (JSON.parse(relatedKey) as RelatedPin) : null),
277
  [relatedKey]
278
  );
279
- // ⛔ SET BEFORE THE FIRST FETCH, not in an effect. Every event the grid emits carries this
280
- // scope, and an effect would run AFTER the first render — so a write triggered by that render
281
- // would be posted as `customer` from the Cohort surface. Module scope + a synchronous set is
282
- // what keeps the read and the write talking about the same surface.
283
  if (bindSurface) setSurfaceScope(scope);
284
  // Wave 16 C-TOPIC: the topic is DERIVED from the scope (cohort = the customer topic), so
285
  // the rows fetch, the patch route and the workspace scope can never disagree about which
@@ -532,20 +554,10 @@ export function useCustomerData(
532
  // had not changed.
533
  ? fetchWorkspace(scope, { announceFailure: firstPaint, allowCached: true })
534
  : Promise.resolve(null);
535
- /**
536
- * ⭐⭐ W30-T42 (R7 / contract C2) — WHOLE BOOK, OR ONE WINDOW?
537
- *
538
- * ⛔ THE SERVER DECIDES, NOT A LIST HERE. `odoo-tables/status` reports `readThrough` per
539
- * table because the bindings convert one bucket at a time; a key list in the client goes
540
- * stale on the next spec row and fails in the dangerous direction (asking the window
541
- * route for a table it cannot serve, which answers 409).
542
- *
543
- * ⛔ AND IT FAILS SOFT TO TODAY'S BEHAVIOUR. An unreachable roster yields the empty set,
544
- * so the table loads whole exactly as it always has. The opposite default — assume
545
- * windowed, discover otherwise — would paint an empty grid over a working table.
546
- */
547
- const tableKey = scope.startsWith("ut_") ? scope : null;
548
- const readThrough = tableKey !== null && (await readThroughTables()).has(tableKey);
549
  if (cancelled || seq !== windowSeq.current) return;
550
  readThroughRef.current = readThrough;
551
  const [payload, workspace] = await Promise.all([
@@ -559,14 +571,7 @@ export function useCustomerData(
559
  carry it or the tab paints the whole database for one frame and then narrows,
560
  which is a wrong answer that happens to be brief. */
561
  ? fetchTableWindow(tableKey, { offset: 0, limit: WINDOW_ROWS, related })
562
- /* ⛔ AND THE WHOLE-BOOK DOOR TAKES NO PREDICATE, MEASURED RATHER THAN ASSUMED.
563
- `routes_tables.table_rows` (which `fetchTopicRows` reaches) accepts no filter
564
- arguments at all and is in no lane's fence this wave, so a related tab whose target
565
- is an ordinary user table has no pre-filtered read to call. The honest answer is a
566
- REPORTED limit, not a client-side filter over the whole table -- that is precisely
567
- the `embeddedRecordIds` pattern W51-T06 exists to delete. `RecordDetail` therefore
568
- probes the pinned door first (`probeRelatedRead`) and prints the server's refusal
569
- instead of mounting this read under a chip that claims one record. */
570
  : fetchTopicRows(topic),
571
  wsPromise,
572
  ]);
@@ -717,7 +722,7 @@ export function useCustomerData(
717
  return next;
718
  });
719
  });
720
- }, [topic, writable]);
721
 
722
  /**
723
  * ⭐⭐ WAVE 30 · W30-T42 — THE ONE DOOR THE GRID USES TO PAGE A READ-THROUGH TABLE.
 
33
  fetchAssignedCustomerRows,
34
  fetchTopicRows,
35
  fetchWorkspace,
36
+ fetchPersonalGridLayout,
37
+ savePersonalGridLayout,
38
  mergeWindow,
39
  patchTopicRow,
40
  readThroughTables,
41
+ usesPinnedRows,
42
  setSurfaceScope,
43
  subscribeChanges,
44
  WINDOW_ROWS,
45
  } from "./apiBridge";
46
+ import type { PersonalGridLayout, RowWindowRequest } from "./apiBridge";
47
  import { DERIVED_CELLS_EVENT, ROWS_STALE_EVENT, WORKSPACE_STALE_EVENT } from "../apiContract";
48
  import { planChangeReaction, rowsRefetchDelay } from "./liveWorkspace";
49
  import { signal } from "../apiContract";
50
  import type { SurfaceScope } from "./apiBridge";
51
  import {
52
+ bindHostEvent,
53
  eventId,
54
  isStreamlitComponent,
55
  readHostArgs,
 
58
  import { journalUpsert, reconcileCellJournal } from "./optimism";
59
  import type { CellJournalEntry } from "./optimism";
60
 
61
+ /** Read fresh per mount. The server session, rather than localStorage, owns user identity. */
62
+ export function usePersonalGridLayout(key?: string) {
63
+ const [loaded, setLoaded] = useState<{
64
+ key?: string; ready: boolean; ok: boolean; layout: Partial<PersonalGridLayout> | null;
65
+ }>({ key, ready: !key, ok: !key, layout: null });
66
+ useEffect(() => {
67
+ if (!key) return;
68
+ let current = true;
69
+ void fetchPersonalGridLayout(key).then((result) => {
70
+ if (current) setLoaded({ key, ready: true, ...result });
71
+ });
72
+ return () => { current = false; };
73
+ }, [key]);
74
+ const ready = !key || (loaded.key === key && loaded.ready);
75
+ const save = useCallback((layout: PersonalGridLayout) => {
76
+ if (!key || loaded.key !== key || !loaded.ok) return Promise.resolve(false);
77
+ return savePersonalGridLayout(key, layout);
78
+ }, [key, loaded.key, loaded.ok]);
79
+ return { ready, layout: loaded.key === key ? loaded.layout : null, save };
80
+ }
81
+
82
  // Embed handshake: the host page sets `window.__AIOS_GRID__ = { fields, rows }`.
83
  // Returns the payload when present & well-formed, else null (standalone mode).
84
  function readEmbed(): CustomersPayload | null {
 
284
  const bindSurface = !suppliedPayload && options.bindSurface !== false;
285
  const includeWorkspace = !suppliedPayload && options.includeWorkspace !== false;
286
  const writable = !suppliedPayload && options.writable !== false;
287
+ const emitHostEvent = useMemo(() => bindHostEvent(scope, writable), [scope, writable]);
288
  /**
289
  * ⭐⭐ W51-T06 / C6 — THE PIN, AS A STRING, AND THAT IS THE WHOLE OF THE STALE-CLOSURE FIX.
290
  *
 
301
  () => (relatedKey ? (JSON.parse(relatedKey) as RelatedPin) : null),
302
  [relatedKey]
303
  );
304
+ // Foreground identity for shell consumers only. Events use the instance-bound emitter above.
 
 
 
305
  if (bindSurface) setSurfaceScope(scope);
306
  // Wave 16 C-TOPIC: the topic is DERIVED from the scope (cohort = the customer topic), so
307
  // the rows fetch, the patch route and the workspace scope can never disagree about which
 
554
  // had not changed.
555
  ? fetchWorkspace(scope, { announceFailure: firstPaint, allowCached: true })
556
  : Promise.resolve(null);
557
+ // A pin selects the universal window reader before any status request. Unpinned
558
+ // grids retain their existing roster-based choice of window or whole-book reads.
559
+ const tableKey = topic.key;
560
+ const readThrough = usesPinnedRows(tableKey, related) || (await readThroughTables()).has(tableKey);
 
 
 
 
 
 
 
 
 
 
561
  if (cancelled || seq !== windowSeq.current) return;
562
  readThroughRef.current = readThrough;
563
  const [payload, workspace] = await Promise.all([
 
571
  carry it or the tab paints the whole database for one frame and then narrows,
572
  which is a wrong answer that happens to be brief. */
573
  ? fetchTableWindow(tableKey, { offset: 0, limit: WINDOW_ROWS, related })
574
+ // A related read always takes the pinned window door, even with an empty roster.
 
 
 
 
 
 
 
575
  : fetchTopicRows(topic),
576
  wsPromise,
577
  ]);
 
722
  return next;
723
  });
724
  });
725
+ }, [topic, writable, emitHostEvent]);
726
 
727
  /**
728
  * ⭐⭐ WAVE 30 · W30-T42 — THE ONE DOOR THE GRID USES TO PAGE A READ-THROUGH TABLE.
web/src/customer-grid/windows.ts CHANGED
@@ -194,6 +194,76 @@ function shiftMonths(d: Date, n: number): Date {
194
  return mkDate(ty, tm, Math.min(day, daysInMonth(ty, tm)));
195
  }
196
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
197
  /** Coerce an untrusted spec to a valid one, or null. Fail-closed on the KIND,
198
  * tolerant on the rest — one malformed window must not cost a saved view. */
199
  export function normalizeWindow(spec: unknown): WindowSpec | null {
 
194
  return mkDate(ty, tm, Math.min(day, daysInMonth(ty, tm)));
195
  }
196
 
197
+ // Sheet Ending metadata lives on the binding period, never on WindowSpec.
198
+ export const ENDING_KINDS = ["today", "yesterday", "last_week", "last_month", "last_quarter",
199
+ "last_year", "fixed", "cell"] as const;
200
+ export type EndingKind = (typeof ENDING_KINDS)[number];
201
+ export const ENDING_LABELS: Record<EndingKind, string> = {
202
+ today: "Today (live)", yesterday: "Yesterday", last_week: "End of last week",
203
+ last_month: "End of last month", last_quarter: "End of last quarter",
204
+ last_year: "End of last year", fixed: "A fixed date", cell: "From a cell",
205
+ };
206
+ export const TO_DATE_KINDS = ["ytd", "ytd_last_year", "this_month", "this_quarter"] as const;
207
+ export const ENDING_STEPS = ["day", "week", "month", "quarter", "year"] as const;
208
+ export type EndingStep = (typeof ENDING_STEPS)[number];
209
+ export const endingStepDefault = (kind: string): EndingStep =>
210
+ kind === "this_quarter" ? "quarter" : "month";
211
+
212
+ /** A real ISO day only, without truncation, calendar rollover or blank fallback. */
213
+ export function endingDate(value: unknown): string | null {
214
+ if (typeof value !== "string" || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/.test(value.trim())) return null;
215
+ const d = parseDate(value);
216
+ return d && iso(d) === value.trim() && d.getUTCFullYear() >= 1 ? iso(d) : null;
217
+ }
218
+
219
+ /** Inclusive ending date. Cell values are supplied by the caller's trusted read. */
220
+ export function resolveEnding(
221
+ mode: string, value: unknown, today: string, step: string = "month", offset = 0,
222
+ ): string | null {
223
+ const d = parseDate(today);
224
+ if (!d) throw new Error("Ending needs a valid today date");
225
+ if (!(ENDING_KINDS as readonly string[]).includes(mode)
226
+ || !(ENDING_STEPS as readonly string[]).includes(step)
227
+ || !Number.isSafeInteger(offset) || offset < 0) return null;
228
+ let end: Date;
229
+ if (mode === "fixed" || mode === "cell") {
230
+ const parsed = endingDate(value);
231
+ if (!parsed) return null;
232
+ end = parseDate(parsed)!;
233
+ } else if (mode === "today") end = d;
234
+ else if (mode === "yesterday") end = addDays(d, -1);
235
+ else if (mode === "last_week") end = addDays(d, -isoWeekday(d) - 1);
236
+ else if (mode === "last_month") end = addDays(monthStart(d), -1);
237
+ else if (mode === "last_quarter") end = addDays(quarterStart(d), -1);
238
+ else end = mkDate(d.getUTCFullYear() - 1, 12, 31);
239
+ if (step === "day" || step === "week") end = addDays(end, offset * (step === "week" ? 7 : 1));
240
+ else end = shiftMonths(end, offset * ({ month: 1, quarter: 3, year: 12 }[step] ?? 1));
241
+ return Number.isNaN(end.getTime()) || end.getUTCFullYear() < 1 || end.getUTCFullYear() > 9999
242
+ ? null : iso(end);
243
+ }
244
+
245
+ /** Sheet dates may be ISO days or Excel serials in the workbook's declared epoch. */
246
+ export function endingCellDate(value: unknown, dateSystem = "1900"): string | null {
247
+ if (typeof value !== "number") return endingDate(value);
248
+ if (!Number.isFinite(value) || value < (dateSystem === "1904" ? 0 : 1)) return null;
249
+ const days = Math.floor(value);
250
+ if (dateSystem !== "1904" && days === 60) return null;
251
+ const epoch = dateSystem === "1904" ? "1904-01-01" : days < 60 ? "1899-12-31" : "1899-12-30";
252
+ const date = addDays(parseDate(epoch)!, days);
253
+ return Number.isNaN(date.getTime()) || date.getUTCFullYear() > 9999 ? null : iso(date);
254
+ }
255
+
256
+ /** Keep the kind's own start; refuse an ending before it instead of reversing bounds. */
257
+ export function endingBounds(
258
+ kind: string, mode: string, value: unknown, today: string, step: string = "month", offset = 0,
259
+ ): [string, string] | null {
260
+ if (!(TO_DATE_KINDS as readonly string[]).includes(kind)) return null;
261
+ const end = resolveEnding(mode, value, today, step, offset);
262
+ if (!end) return null;
263
+ const start = resolveWindow({ kind }, today)![0]!;
264
+ return start <= end ? [start, end] : null;
265
+ }
266
+
267
  /** Coerce an untrusted spec to a valid one, or null. Fail-closed on the KIND,
268
  * tolerant on the rest — one malformed window must not cost a saved view. */
269
  export function normalizeWindow(spec: unknown): WindowSpec | null {
web/src/home/HomePage.tsx CHANGED
@@ -22,6 +22,7 @@
22
 
23
  import { useEffect, useId, useRef, useState } from "react";
24
  import { FolderMark } from "../customer-grid/icons";
 
25
  import { appPathHash } from "../customer-grid/dataPath";
26
  import { BodyPortal, useOverlayLayer } from "../customer-grid/OverlaySurface";
27
  import DatabaseTile from "./DatabaseTile";
@@ -36,6 +37,7 @@ import "../styles/wave58/app-data.css";
36
  // paints the mark).
37
  import { AGENTS_MODULE_LABEL } from "../inbox/inboxModel";
38
  import { Mark } from "../shell/Brand";
 
39
  import type { DatabaseEntry, NavFolder, Recent } from "../shell/nav";
40
  import { API_V1, CREDENTIALS } from "../apiContract";
41
  // ⭐ WAVE 35 · W35-T15 (R4, C2) — ONE STAR CONTROL, drawn in the module that owns the concept and
@@ -46,6 +48,8 @@ import { QueryIcon, StarButton, Tile } from "../starred/StarredPage";
46
  import { shapeStarred, useStarred, viewCount, viewCountKey } from "../starred/starredApi";
47
  import type { StarKind, Starred, StarredCounts, StarredLoad } from "../starred/starredApi";
48
  import { StarIcon } from "../ui/icons";
 
 
49
  import {
50
  HOME_LAYOUT_KEY,
51
  applyHomeFilter,
@@ -153,6 +157,19 @@ function ApplicationIcon() {
153
  );
154
  }
155
 
 
 
 
 
 
 
 
 
 
 
 
 
 
156
  interface ApplicationTile {
157
  id: string;
158
  name: string;
@@ -164,6 +181,11 @@ interface ApplicationTile {
164
  capabilities?: { star?: boolean; delete?: boolean };
165
  }
166
 
 
 
 
 
 
167
  /** Typed-name disclosure using the shared dialog kit and modal focus/Escape contract. */
168
  function AppDeleteDialog({ application, onDelete, onCancel }: {
169
  application: ApplicationTile;
@@ -251,15 +273,17 @@ function QuickCard({
251
  title,
252
  detail,
253
  onClick,
 
254
  }: {
255
  icon: React.ReactNode;
256
  title: string;
257
  /** ONE line. R13: the app does not narrate itself, and this is a passing-through surface. */
258
  detail: string;
259
  onClick: () => void;
 
260
  }) {
261
  return (
262
- <button type="button" className="home-card" onClick={onClick}>
263
  <span className="home-card-head">
264
  {icon}
265
  <span className="home-card-title">{title}</span>
@@ -272,8 +296,8 @@ function QuickCard({
272
  /** What the FRAME hands Home. Unchanged by the wave-35 split, and named so both halves take
273
  * exactly the same shape rather than drifting. */
274
  export interface HomeProps {
275
- /** Data renders Home's database list; App renders its Application directory. */
276
- mode?: "home" | "app" | "data";
277
  /** Compatibility entry for a retired `#/starred` bookmark. */
278
  initialStarredOnly?: boolean;
279
  /**
@@ -302,6 +326,9 @@ export interface HomeProps {
302
  * rather than an error card about a surface they may not have.
303
  */
304
  automations: AutomationTile[];
 
 
 
305
  onTemplates: () => void;
306
  onNewDatabase: () => void;
307
  /* ⛔ `onAutomated` LEFT WITH THE CARD IT OPENED (wave 25 item 5a, R8). */
@@ -358,6 +385,15 @@ export function HomeSurface({
358
  applicationBusy = new Set<string>(),
359
  onToggleApplication = () => undefined,
360
  onDeleteApplication = () => undefined,
 
 
 
 
 
 
 
 
 
361
  starLoad,
362
  starred,
363
  busy,
@@ -370,6 +406,13 @@ export function HomeSurface({
370
  applicationBusy?: ReadonlySet<string>;
371
  onToggleApplication?: (application: ApplicationTile, on: boolean) => void;
372
  onDeleteApplication?: (application: ApplicationTile) => void;
 
 
 
 
 
 
 
373
  starLoad: StarredLoad;
374
  starred: Starred;
375
  busy: boolean;
@@ -413,6 +456,9 @@ export function HomeSurface({
413
  const known = starLoad.phase === "ready";
414
  const dbStarred = new Set(starred.databases);
415
  const agentStarred = new Set(starred.agents);
 
 
 
416
  const visibleDatabases = applyHomeFilter(
417
  databases,
418
  filter,
@@ -423,6 +469,11 @@ export function HomeSurface({
423
  filter,
424
  (automation) => agentStarred.has(automation.id),
425
  );
 
 
 
 
 
426
  const visibleApplications = applyHomeFilter(
427
  applications,
428
  mode === "app" ? "all" : filter,
@@ -441,10 +492,92 @@ export function HomeSurface({
441
  const starredQueries = starredRows.queries;
442
  const starredOnly = mode !== "app" && filter === "starred";
443
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
444
  return (
445
  <div className="shell-home">
446
  <div className="home-page-head">
447
- <h1 className="home-title">{mode === "app" ? "App" : mode === "data" ? "Data" : "Home"}</h1>
448
  </div>
449
 
450
  {mode === "home" ? <div className="home-cards">
@@ -510,6 +643,26 @@ export function HomeSurface({
510
  />
511
  <span className="home-card-ghost" aria-hidden="true" />
512
  <span className="home-card-ghost" aria-hidden="true" />
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
513
  </div> : null}
514
 
515
  <div className="home-recents-bar">
@@ -554,7 +707,7 @@ export function HomeSurface({
554
  </div>
555
  </div>
556
 
557
- {mode !== "app" && !starredOnly && databases.length === 0 ? (
558
  // ⛔ ONE LINE, AND IT NAMES THE DOOR THAT FILLS IT (DESIGN.md 4 / R13). This is also
559
  // where wave 18's tenant hero went: a workspace with no databases lands here, and the
560
  // cards above ARE the "create your first database" affordance the hero carried. Two
@@ -567,7 +720,7 @@ export function HomeSurface({
567
  ? "This workspace has no databases yet."
568
  : "This workspace has no databases yet. Create one above, or connect a source."}
569
  </p>
570
- ) : mode !== "app" && visibleDatabases.length ? (
571
  <section className="home-section">
572
  <h2 className="home-section-title">Databases</h2>
573
  <div className={"home-tiles is-" + layout}>
@@ -585,10 +738,10 @@ export function HomeSurface({
585
  </section>
586
  ) : null}
587
  {mode === "home" && !starredOnly && folders.length > 0 && <section className="home-section"><h2 className="home-section-title">Folders</h2><div className={"home-tiles is-" + layout}>{folders.map((folder) => { const count = Object.values(folderPlacement).filter((id) => id === folder.id).length; return <a className="home-tile" href={`#/data?folder=${encodeURIComponent(folder.id)}`} key={folder.id}><span className="home-tile-chip home-folder-glyph" aria-hidden><FolderMark size={16} /></span><span className="home-tile-text"><span className="home-tile-name">{folder.name}</span><span className="home-tile-ago">{count} database{count === 1 ? "" : "s"}</span></span></a>; })}</div></section>}
588
- {mode !== "data" && applicationsError ? (
589
  <p className="home-app-note" role="alert">{applicationsError}</p>
590
  ) : null}
591
- {mode !== "data" && visibleApplications.length > 0 ? (
592
  <section className="home-section">
593
  <h2 className="home-section-title">Applications</h2>
594
  <div className={"home-tiles is-" + layout}>
@@ -648,6 +801,9 @@ export function HomeSurface({
648
  </div>
649
  ) : null}
650
 
 
 
 
651
  {/* ⭐ WAVE 24 item 13 (R10) — THE AUTOMATIONS SECTION.
652
  Same tiles, same rhythm.
653
  ⭐ WAVE 26 ITEM 18 (R14) — AND NO LONGER A STATUS DOT. This comment used to call
@@ -778,10 +934,13 @@ export function HomeSurface({
778
  </div>
779
  </section>
780
  ) : null}
781
- {known && starredOnly && visibleDatabases.length === 0
782
- && (mode === "data" || (applicationsKnown && !applicationsError
 
 
 
783
  && visibleAutomations.length === 0 && visibleApplications.length === 0
784
- && starredViews.length === 0 && starredQueries.length === 0)) ? (
785
  <p className="home-empty">Nothing starred yet.</p>
786
  ) : null}
787
  </div>
@@ -801,6 +960,75 @@ export function HomeSurface({
801
  */
802
  export default function HomePage(props: HomeProps) {
803
  const { load: starLoad, starred, busy, counts, toggle } = useStarred();
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
804
  const [applications, setApplications] = useState<ApplicationTile[]>([]);
805
  const [applicationsKnown, setApplicationsKnown] = useState(false);
806
  const [applicationsError, setApplicationsError] = useState("");
@@ -833,7 +1061,7 @@ export default function HomePage(props: HomeProps) {
833
  };
834
  }, []);
835
  useEffect(() => {
836
- if (props.mode === "data") return;
837
  const controller = new AbortController();
838
  const requestEpoch = ++applicationRequestEpoch.current;
839
  setApplicationsError("");
@@ -926,6 +1154,14 @@ export default function HomePage(props: HomeProps) {
926
  busy={busy}
927
  counts={counts}
928
  toggle={toggle}
 
 
 
 
 
 
 
 
929
  applications={applications}
930
  applicationsKnown={applicationsKnown}
931
  applicationsError={applicationsError}
@@ -942,3 +1178,14 @@ export default function HomePage(props: HomeProps) {
942
  </>
943
  );
944
  }
 
 
 
 
 
 
 
 
 
 
 
 
22
 
23
  import { useEffect, useId, useRef, useState } from "react";
24
  import { FolderMark } from "../customer-grid/icons";
25
+ import { SHEET_SHAPE } from "../customer-grid/iconShapes";
26
  import { appPathHash } from "../customer-grid/dataPath";
27
  import { BodyPortal, useOverlayLayer } from "../customer-grid/OverlaySurface";
28
  import DatabaseTile from "./DatabaseTile";
 
37
  // paints the mark).
38
  import { AGENTS_MODULE_LABEL } from "../inbox/inboxModel";
39
  import { Mark } from "../shell/Brand";
40
+ import { agentAddressHash } from "../shell/nav";
41
  import type { DatabaseEntry, NavFolder, Recent } from "../shell/nav";
42
  import { API_V1, CREDENTIALS } from "../apiContract";
43
  // ⭐ WAVE 35 · W35-T15 (R4, C2) — ONE STAR CONTROL, drawn in the module that owns the concept and
 
48
  import { shapeStarred, useStarred, viewCount, viewCountKey } from "../starred/starredApi";
49
  import type { StarKind, Starred, StarredCounts, StarredLoad } from "../starred/starredApi";
50
  import { StarIcon } from "../ui/icons";
51
+ import { createWorkbook, readIndex } from "../sheet/sheetApi";
52
+ import { AutomationError, createAutomation, nextAutomationName } from "../automation/automationApi";
53
  import {
54
  HOME_LAYOUT_KEY,
55
  applyHomeFilter,
 
157
  );
158
  }
159
 
160
+ /** The sheet mark, taken from the geometry the Sheet rail and the shell rail already draw
161
+ * (`iconShapes.ts::SHEET_SHAPE`) rather than drawn a fourth time, and wearing the Application
162
+ * tile's stroke class so a Sheets tile and an Applications tile read as one family. */
163
+ function SheetGlyph() {
164
+ return (
165
+ <svg viewBox="0 0 16 16" aria-hidden="true" className="home-app-icon">
166
+ {SHEET_SHAPE.map((shape) => (
167
+ <path key={shape.d} d={shape.d} />
168
+ ))}
169
+ </svg>
170
+ );
171
+ }
172
+
173
  interface ApplicationTile {
174
  id: string;
175
  name: string;
 
181
  capabilities?: { star?: boolean; delete?: boolean };
182
  }
183
 
184
+ interface SheetTile {
185
+ id: string;
186
+ name: string;
187
+ }
188
+
189
  /** Typed-name disclosure using the shared dialog kit and modal focus/Escape contract. */
190
  function AppDeleteDialog({ application, onDelete, onCancel }: {
191
  application: ApplicationTile;
 
273
  title,
274
  detail,
275
  onClick,
276
+ disabled = false,
277
  }: {
278
  icon: React.ReactNode;
279
  title: string;
280
  /** ONE line. R13: the app does not narrate itself, and this is a passing-through surface. */
281
  detail: string;
282
  onClick: () => void;
283
+ disabled?: boolean;
284
  }) {
285
  return (
286
+ <button type="button" className="home-card" onClick={onClick} disabled={disabled}>
287
  <span className="home-card-head">
288
  {icon}
289
  <span className="home-card-title">{title}</span>
 
296
  /** What the FRAME hands Home. Unchanged by the wave-35 split, and named so both halves take
297
  * exactly the same shape rather than drifting. */
298
  export interface HomeProps {
299
+ /** Each gallery reuses Home's directory anatomy. */
300
+ mode?: "home" | "app" | "data" | "sheet" | "agents";
301
  /** Compatibility entry for a retired `#/starred` bookmark. */
302
  initialStarredOnly?: boolean;
303
  /**
 
326
  * rather than an error card about a surface they may not have.
327
  */
328
  automations: AutomationTile[];
329
+ /** Voice tiles belong to the Agents gallery; existing Home callers keep their own list. */
330
+ voiceAgents?: AutomationTile[];
331
+ agentsError?: string;
332
  onTemplates: () => void;
333
  onNewDatabase: () => void;
334
  /* ⛔ `onAutomated` LEFT WITH THE CARD IT OPENED (wave 25 item 5a, R8). */
 
385
  applicationBusy = new Set<string>(),
386
  onToggleApplication = () => undefined,
387
  onDeleteApplication = () => undefined,
388
+ sheets = [],
389
+ sheetsKnown = true,
390
+ sheetsError = "",
391
+ onNewSheet = () => undefined,
392
+ sheetBusy = false,
393
+ voiceAgents = [],
394
+ onNewAgent = () => undefined,
395
+ agentBusy = false,
396
+ agentsError = "",
397
  starLoad,
398
  starred,
399
  busy,
 
406
  applicationBusy?: ReadonlySet<string>;
407
  onToggleApplication?: (application: ApplicationTile, on: boolean) => void;
408
  onDeleteApplication?: (application: ApplicationTile) => void;
409
+ sheets?: SheetTile[];
410
+ sheetsKnown?: boolean;
411
+ sheetsError?: string;
412
+ onNewSheet?: () => void;
413
+ sheetBusy?: boolean;
414
+ onNewAgent?: () => void;
415
+ agentBusy?: boolean;
416
  starLoad: StarredLoad;
417
  starred: Starred;
418
  busy: boolean;
 
456
  const known = starLoad.phase === "ready";
457
  const dbStarred = new Set(starred.databases);
458
  const agentStarred = new Set(starred.agents);
459
+ const sheetStarred = new Set(starred.sheets);
460
+ // C2/R28: the index owns visibility and order; this is only the user's display filter.
461
+ const visibleSheets = applyHomeFilter(sheets, filter, (row) => sheetStarred.has(row.id));
462
  const visibleDatabases = applyHomeFilter(
463
  databases,
464
  filter,
 
469
  filter,
470
  (automation) => agentStarred.has(automation.id),
471
  );
472
+ const visibleVoiceAgents = applyHomeFilter(
473
+ voiceAgents,
474
+ filter,
475
+ (agent) => agentStarred.has(agent.id),
476
+ );
477
  const visibleApplications = applyHomeFilter(
478
  applications,
479
  mode === "app" ? "all" : filter,
 
492
  const starredQueries = starredRows.queries;
493
  const starredOnly = mode !== "app" && filter === "starred";
494
 
495
+ // One link builder keeps flow and voice tiles on the same encoded address contract.
496
+ const agentHref = (kind: "agent" | "voice", id: string) => agentAddressHash(kind, id);
497
+ const galleryAgents = [
498
+ ...visibleAutomations.map((row) => ({ ...row, kind: "agent" as const })),
499
+ ...visibleVoiceAgents.map((row) => ({ ...row, kind: "voice" as const })),
500
+ ];
501
+ const renderAgents = () => (
502
+ <>
503
+ {agentsError ? <p className="home-app-note" role="alert">{agentsError}</p> : null}
504
+ {galleryAgents.length > 0 ? (
505
+ <section className="home-section">
506
+ <h2 className="home-section-title">{AGENTS_MODULE_LABEL}</h2>
507
+ <div className={"home-tiles is-" + layout}>
508
+ {galleryAgents.map((row) => (
509
+ <div className="st-tilewrap" key={row.kind + ":" + row.id}>
510
+ <a className="home-tile" href={agentHref(row.kind, row.id)}>
511
+ <span className="home-tile-chip shell-db-chip" aria-hidden="true">
512
+ <Mark size={16} />
513
+ </span>
514
+ <span className="home-tile-text">
515
+ <span className="home-tile-name">{row.name}</span>
516
+ {row.sub ? <span className="home-tile-ago">{row.sub}</span> : null}
517
+ </span>
518
+ </a>
519
+ {known ? (
520
+ <StarButton
521
+ on={agentStarred.has(row.id)}
522
+ label={row.name}
523
+ busy={busy}
524
+ onToggle={() => toggle("agent", row.id, !agentStarred.has(row.id))}
525
+ />
526
+ ) : null}
527
+ </div>
528
+ ))}
529
+ </div>
530
+ </section>
531
+ ) : !agentsError && !starredOnly ? (
532
+ <p className="home-empty">No agents yet. Create one above.</p>
533
+ ) : null}
534
+ </>
535
+ );
536
+
537
+ // One renderer serves Home and the Sheet gallery, including their C2 links and per-user stars.
538
+ const renderSheets = () => (
539
+ <>
540
+ {sheetsError ? <p className="home-app-note" role="alert">{sheetsError}</p> : null}
541
+ {mode === "sheet" && !sheetsKnown && !sheetsError ? (
542
+ <div className="st-loading">
543
+ <span className="lp-spin lp-spin--lg" role="status" aria-label="Loading sheets" />
544
+ </div>
545
+ ) : sheetsKnown && visibleSheets.length > 0 ? (
546
+ <section className="home-section">
547
+ <h2 className="home-section-title">Sheets</h2>
548
+ <div className={"home-tiles is-" + layout}>
549
+ {visibleSheets.map((row) => (
550
+ <div className="st-tilewrap" key={row.id}>
551
+ <a className="home-tile" href={"#/sheet?wb=" + encodeURIComponent(row.id)}>
552
+ <span className="home-tile-chip home-app-glyph" aria-hidden="true">
553
+ <SheetGlyph />
554
+ </span>
555
+ <span className="home-tile-text">
556
+ <span className="home-tile-name">{row.name}</span>
557
+ </span>
558
+ </a>
559
+ {known ? (
560
+ <StarButton
561
+ on={sheetStarred.has(row.id)}
562
+ label={row.name}
563
+ busy={busy}
564
+ onToggle={() => toggle("sheet", row.id, !sheetStarred.has(row.id))}
565
+ />
566
+ ) : null}
567
+ </div>
568
+ ))}
569
+ </div>
570
+ </section>
571
+ ) : mode === "sheet" && sheetsKnown && !sheetsError && !starredOnly ? (
572
+ <p className="home-empty">This workspace has no sheets yet. Create one above.</p>
573
+ ) : null}
574
+ </>
575
+ );
576
+
577
  return (
578
  <div className="shell-home">
579
  <div className="home-page-head">
580
+ <h1 className="home-title">{mode === "agents" ? AGENTS_MODULE_LABEL : mode === "sheet" ? "Sheet" : mode === "app" ? "App" : mode === "data" ? "Data" : "Home"}</h1>
581
  </div>
582
 
583
  {mode === "home" ? <div className="home-cards">
 
643
  />
644
  <span className="home-card-ghost" aria-hidden="true" />
645
  <span className="home-card-ghost" aria-hidden="true" />
646
+ </div> : mode === "sheet" ? <div className="home-cards is-app">
647
+ <QuickCard
648
+ icon={<TemplateIcon />}
649
+ title="Create new"
650
+ detail="Start a blank workbook in this workspace."
651
+ onClick={onNewSheet}
652
+ disabled={sheetBusy}
653
+ />
654
+ <span className="home-card-ghost" aria-hidden="true" />
655
+ <span className="home-card-ghost" aria-hidden="true" />
656
+ </div> : mode === "agents" ? <div className="home-cards is-app">
657
+ <QuickCard
658
+ icon={<Mark size={16} />}
659
+ title="New agent"
660
+ detail="A job this workspace runs for you, on demand or on a schedule."
661
+ onClick={onNewAgent}
662
+ disabled={agentBusy}
663
+ />
664
+ <span className="home-card-ghost" aria-hidden="true" />
665
+ <span className="home-card-ghost" aria-hidden="true" />
666
  </div> : null}
667
 
668
  <div className="home-recents-bar">
 
707
  </div>
708
  </div>
709
 
710
+ {mode !== "app" && mode !== "sheet" && mode !== "agents" && !starredOnly && databases.length === 0 ? (
711
  // ⛔ ONE LINE, AND IT NAMES THE DOOR THAT FILLS IT (DESIGN.md 4 / R13). This is also
712
  // where wave 18's tenant hero went: a workspace with no databases lands here, and the
713
  // cards above ARE the "create your first database" affordance the hero carried. Two
 
720
  ? "This workspace has no databases yet."
721
  : "This workspace has no databases yet. Create one above, or connect a source."}
722
  </p>
723
+ ) : mode !== "app" && mode !== "sheet" && mode !== "agents" && visibleDatabases.length ? (
724
  <section className="home-section">
725
  <h2 className="home-section-title">Databases</h2>
726
  <div className={"home-tiles is-" + layout}>
 
738
  </section>
739
  ) : null}
740
  {mode === "home" && !starredOnly && folders.length > 0 && <section className="home-section"><h2 className="home-section-title">Folders</h2><div className={"home-tiles is-" + layout}>{folders.map((folder) => { const count = Object.values(folderPlacement).filter((id) => id === folder.id).length; return <a className="home-tile" href={`#/data?folder=${encodeURIComponent(folder.id)}`} key={folder.id}><span className="home-tile-chip home-folder-glyph" aria-hidden><FolderMark size={16} /></span><span className="home-tile-text"><span className="home-tile-name">{folder.name}</span><span className="home-tile-ago">{count} database{count === 1 ? "" : "s"}</span></span></a>; })}</div></section>}
741
+ {mode !== "data" && mode !== "sheet" && mode !== "agents" && applicationsError ? (
742
  <p className="home-app-note" role="alert">{applicationsError}</p>
743
  ) : null}
744
+ {mode !== "data" && mode !== "sheet" && mode !== "agents" && visibleApplications.length > 0 ? (
745
  <section className="home-section">
746
  <h2 className="home-section-title">Applications</h2>
747
  <div className={"home-tiles is-" + layout}>
 
801
  </div>
802
  ) : null}
803
 
804
+ {mode === "home" || mode === "sheet" ? renderSheets() : null}
805
+ {mode === "agents" ? renderAgents() : null}
806
+
807
  {/* ⭐ WAVE 24 item 13 (R10) — THE AUTOMATIONS SECTION.
808
  Same tiles, same rhythm.
809
  ⭐ WAVE 26 ITEM 18 (R14) — AND NO LONGER A STATUS DOT. This comment used to call
 
934
  </div>
935
  </section>
936
  ) : null}
937
+ {known && starredOnly
938
+ && (mode === "agents" ? !agentsError && galleryAgents.length === 0
939
+ : mode === "sheet" ? sheetsKnown && !sheetsError && visibleSheets.length === 0
940
+ : visibleDatabases.length === 0 && (mode === "data" || (applicationsKnown && !applicationsError
941
+ && sheetsKnown && !sheetsError && visibleSheets.length === 0
942
  && visibleAutomations.length === 0 && visibleApplications.length === 0
943
+ && starredViews.length === 0 && starredQueries.length === 0))) ? (
944
  <p className="home-empty">Nothing starred yet.</p>
945
  ) : null}
946
  </div>
 
960
  */
961
  export default function HomePage(props: HomeProps) {
962
  const { load: starLoad, starred, busy, counts, toggle } = useStarred();
963
+ const [sheets, setSheets] = useState<SheetTile[]>([]);
964
+ const [sheetsKnown, setSheetsKnown] = useState(false);
965
+ const [sheetsError, setSheetsError] = useState("");
966
+ const [sheetBusy, setSheetBusy] = useState(false);
967
+ const sheetCreating = useRef(false);
968
+ useEffect(() => {
969
+ if (props.mode === "app" || props.mode === "data" || props.mode === "agents") return;
970
+ let active = true;
971
+ setSheetsKnown(false);
972
+ setSheetsError("");
973
+ void readIndex().then((result) => {
974
+ if (!active) return;
975
+ setSheetsKnown(true);
976
+ if (result.ok) {
977
+ // C2/R28: render exactly the server's workbook directory, in its order.
978
+ setSheets(result.value.workbooks);
979
+ } else {
980
+ setSheetsError("Sheets could not be loaded. Reload to retry.");
981
+ }
982
+ }).catch(() => {
983
+ if (!active) return;
984
+ setSheetsKnown(true);
985
+ setSheetsError("Sheets could not be loaded. Reload to retry.");
986
+ });
987
+ return () => { active = false; };
988
+ }, [props.mode]);
989
+
990
+ const onNewSheet = async () => {
991
+ if (sheetCreating.current) return;
992
+ sheetCreating.current = true;
993
+ setSheetBusy(true);
994
+ try {
995
+ const result = await createWorkbook();
996
+ if (result.ok) {
997
+ window.location.hash = "#/sheet?wb=" + encodeURIComponent(result.value.id);
998
+ } else {
999
+ setSheetsError("The sheet could not be created. Try again.");
1000
+ }
1001
+ } catch {
1002
+ setSheetsError("The sheet could not be created. Try again.");
1003
+ } finally {
1004
+ sheetCreating.current = false;
1005
+ setSheetBusy(false);
1006
+ }
1007
+ };
1008
+ const [agentBusy, setAgentBusy] = useState(false);
1009
+ const [agentsError, setAgentsError] = useState("");
1010
+ const agentCreating = useRef(false);
1011
+ const onNewAgent = async () => {
1012
+ if (agentCreating.current) return;
1013
+ agentCreating.current = true;
1014
+ setAgentBusy(true);
1015
+ setAgentsError("");
1016
+ try {
1017
+ const result = await createAutomation({ name: nextAutomationName(props.automations) });
1018
+ if (result.automation?.id) {
1019
+ window.location.hash = agentAddressHash("agent", result.automation.id);
1020
+ } else {
1021
+ setAgentsError("The agent could not be created. Try again.");
1022
+ }
1023
+ } catch (failure) {
1024
+ setAgentsError(failure instanceof AutomationError && failure.status === 403
1025
+ ? "You do not have permission to create an agent."
1026
+ : "The agent could not be created. Try again.");
1027
+ } finally {
1028
+ agentCreating.current = false;
1029
+ setAgentBusy(false);
1030
+ }
1031
+ };
1032
  const [applications, setApplications] = useState<ApplicationTile[]>([]);
1033
  const [applicationsKnown, setApplicationsKnown] = useState(false);
1034
  const [applicationsError, setApplicationsError] = useState("");
 
1061
  };
1062
  }, []);
1063
  useEffect(() => {
1064
+ if (props.mode === "data" || props.mode === "sheet" || props.mode === "agents") return;
1065
  const controller = new AbortController();
1066
  const requestEpoch = ++applicationRequestEpoch.current;
1067
  setApplicationsError("");
 
1154
  busy={busy}
1155
  counts={counts}
1156
  toggle={toggle}
1157
+ sheets={sheets}
1158
+ sheetsKnown={sheetsKnown}
1159
+ sheetsError={sheetsError}
1160
+ onNewSheet={onNewSheet}
1161
+ sheetBusy={sheetBusy}
1162
+ onNewAgent={onNewAgent}
1163
+ agentBusy={agentBusy}
1164
+ agentsError={agentsError || props.agentsError || ""}
1165
  applications={applications}
1166
  applicationsKnown={applicationsKnown}
1167
  applicationsError={applicationsError}
 
1178
  </>
1179
  );
1180
  }
1181
+
1182
+ // verify_shell_rail.py pins Shell's FIRST HomePage tag to its Home/Data/App mode expression.
1183
+ // Keep this distinct tag for the Sheet gallery so that mount contract remains intact.
1184
+ export function SheetGalleryPage(props: HomeProps) {
1185
+ return <HomePage {...props} mode="sheet" />;
1186
+ }
1187
+
1188
+ // A distinct Agents tag preserves the same FIRST HomePage mount contract as SheetGalleryPage.
1189
+ export function AgentsGalleryPage(props: HomeProps) {
1190
+ return <HomePage {...props} mode="agents" />;
1191
+ }
web/src/sheet/BindingEditor.tsx CHANGED
@@ -37,16 +37,19 @@
37
  // ease-out on opacity and transform, no emoji, and no em dash or en dash in any string on screen.
38
 
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 { dayText } from "../customer-grid/display";
43
  import { FieldSelectButton } from "../customer-grid/FieldSelect";
44
- import { FieldTypeIcon } from "../customer-grid/icons";
45
  import { BodyPortal, OverlayProvider, useOverlayLayer } from "../customer-grid/OverlaySurface";
46
  import type { Field, FilterTree, GridWorkspace, Measure, Row, SavedView } from "../customer-grid/types";
47
- import { choiceVocabulary, topicForScope } from "../customer-grid/types";
48
  import type { WindowSpec } from "../customer-grid/windows";
49
- import { normalizeWindow } from "../customer-grid/windows";
 
 
50
  // ⭐⭐ W53-T15 (ruling R8) — THE FILTER BUILDER IS NO LONGER MOUNTED IN THIS COLUMN. The SHARED
51
  // `FilterBuilderPanel` the Data module also uses is untouched; `SheetFilterPopup` wraps it in the
52
  // base kit's centred dialog so its condition rows have room, and only the Sheet mounts that
@@ -55,19 +58,21 @@ import { countConditions, isNumericType } from "../filter-kit/ops";
55
  import { SheetFilterPopup } from "../filter-kit/SheetFilterPopup";
56
  import { WindowPicker } from "../filter-kit/WindowPicker";
57
  import { useEscapeClose } from "../ui/useEscapeClose";
58
- import { previewCell } from "./sheetApi";
59
- import { bindingAggregate, bindingDisplay, bindingFilterClauses } from "./types";
60
- import type { BindingAggregate } from "./types";
61
- import { bindingStepMode, bindingStepValues, seedBindingStep } from "./bindingRefs";
 
 
62
  import "../styles/wave57/binding-actions.css";
63
  import "../styles/wave58/sheet.css";
64
  import "../styles/wave59/binding.css";
65
 
66
  const BINDING_SECTIONS = [
67
- { key: "data", label: "Data" },
68
- { key: "rows", label: "Filter" },
69
- { key: "period", label: "Period" },
70
- { key: "copied", label: "When copied" },
71
  ] as const;
72
 
73
  const AGGREGATES = [
@@ -133,9 +138,8 @@ const scopeOf = (database: string): SurfaceScope | null => {
133
  // ══ THE PERIOD (R9) ═══════════════════════════════════════════════════════════════════════════
134
  //
135
  // ⛔⛔ CONTRACT C2 SPELLS THIS ON THE WIRE AND THE UI DOES NOT GET A VOTE:
136
- // `period: {unit: "month"|"quarter"|"year", start: "YYYY-MM", locked: boolean, ref?: A1}`. The
137
- // unit values are LOWERCASE on the wire even though the picker reads Month / Quarter / Year, and
138
- // `start` is a MONTH string for every unit.
139
  // A frozen period keeps that pair for returning to the calendar, and adds only
140
  // `frozen: true, from: "YYYY-MM-DD", to: "YYYY-MM-DD"` in place of a cell reference.
141
  //
@@ -145,7 +149,7 @@ const scopeOf = (database: string): SurfaceScope | null => {
145
  // server compiler reads the pair, and two readings of `2026-08` under `quarter` (August, or Q3)
146
  // are a silent disagreement that no screen shows.
147
 
148
- export type PeriodUnit = "month" | "quarter" | "year";
149
 
150
  export interface PeriodBinding {
151
  unit: PeriodUnit;
@@ -156,9 +160,14 @@ export interface PeriodBinding {
156
  from?: string;
157
  to?: string;
158
  window?: WindowSpec;
 
 
 
159
  }
160
 
161
  export const PERIOD_UNITS: { unit: PeriodUnit; label: string }[] = [
 
 
162
  { unit: "month", label: "Month" },
163
  { unit: "quarter", label: "Quarter" },
164
  { unit: "year", label: "Year" },
@@ -170,11 +179,11 @@ const MONTH_NAMES = [
170
  ];
171
 
172
  /** How many months one step of a unit covers. The only place that arithmetic is stated. */
173
- const MONTHS_PER_UNIT: Record<PeriodUnit, number> = { month: 1, quarter: 3, year: 12 };
174
 
175
  /** The noun a sentence uses for one step. Sentence case, and no dash anywhere near it. */
176
  const UNIT_NOUN: Record<PeriodUnit, string> = {
177
- month: "month", quarter: "quarter", year: "year",
178
  };
179
 
180
  const pad2 = (n: number) => String(n).padStart(2, "0");
@@ -194,7 +203,14 @@ const joinYm = (y: number, m: number) => `${y}-${pad2(m)}`;
194
 
195
  /** THE PERIOD'S FIRST MONTH, which is what `start` means. See the block above. */
196
  export function normalizePeriodStart(unit: PeriodUnit, ym: string): string {
197
- const { y, m } = splitYm(ym);
 
 
 
 
 
 
 
198
  if (unit === "year") return joinYm(y, 1);
199
  if (unit === "quarter") return joinYm(y, 1 + 3 * Math.floor((m - 1) / 3));
200
  return joinYm(y, m);
@@ -202,8 +218,14 @@ export function normalizePeriodStart(unit: PeriodUnit, ym: string): string {
202
 
203
  /** Move a start by whole periods. Negative steps go back; this is also the drag rule's maths. */
204
  export function shiftPeriodStart(unit: PeriodUnit, ym: string, steps: number): string {
 
 
 
 
 
 
205
  const { y, m } = splitYm(normalizePeriodStart(unit, ym));
206
- const total = y * 12 + (m - 1) + steps * MONTHS_PER_UNIT[unit];
207
  return joinYm(Math.floor(total / 12), (total % 12) + 1);
208
  }
209
 
@@ -211,6 +233,12 @@ export function shiftPeriodStart(unit: PeriodUnit, ym: string, steps: number): s
211
  * `platform/modules/sheet.py::period_window`, whose `to` is the LAST DAY of the period. */
212
  export function periodRange(unit: PeriodUnit, ym: string): { from: string; to: string } {
213
  const start = normalizePeriodStart(unit, ym);
 
 
 
 
 
 
214
  const last = new Date(`${shiftPeriodStart(unit, start, 1)}-01T00:00:00Z`);
215
  last.setUTCDate(last.getUTCDate() - 1);
216
  return { from: `${start}-01`, to: last.toISOString().slice(0, 10) };
@@ -259,6 +287,12 @@ export function migratePeriod(raw: unknown): PeriodBinding | null {
259
  start: normalizePeriodStart("month", todayYm()),
260
  locked: true,
261
  window,
 
 
 
 
 
 
262
  };
263
  }
264
  const declared = PERIOD_UNITS.some((u) => u.unit === p.unit);
@@ -270,7 +304,8 @@ export function migratePeriod(raw: unknown): PeriodBinding | null {
270
  const unit = p.unit as PeriodUnit;
271
  const stored = typeof p.start === "string" ? p.start.trim() : "";
272
  // D-660: no window named, and no cell to take one from, so there is no period to read.
273
- if (!/^\d{4}-\d{2}$/.test(stored) && !ref) return null;
 
274
  const start = normalizePeriodStart(unit, stored || todayYm());
275
  const locked = p.locked === true;
276
  if (p.frozen === true) {
@@ -293,6 +328,7 @@ export type DragAcross = "period" | "none";
293
  export interface OnDragBinding {
294
  across: DragAcross;
295
  down: { field: string } | "none";
 
296
  }
297
 
298
  /** A copy step walks a column's stored values. Measure-backed and Metric columns are computed
@@ -304,14 +340,8 @@ export function isDragDownField(f: Field): boolean {
304
 
305
  /** The saved `onDrag`, defaulted. `down` is carried as a field key, empty meaning nothing. */
306
  export function readOnDrag(raw: unknown): { across: DragAcross; down: string } {
307
- const d = (raw && typeof raw === "object" ? raw : {}) as Record<string, unknown>;
308
- const across: DragAcross = d.across === "none" ? "none" : "period";
309
- const down = d.down;
310
- if (down && typeof down === "object") {
311
- const key = (down as Record<string, unknown>).field;
312
- if (typeof key === "string" && key) return { across, down: key };
313
- }
314
- return { across, down: "" };
315
  }
316
 
317
  /** `scope.adoptedFrom` (R11): the view was purged and its filter was copied into this cell. */
@@ -667,6 +697,10 @@ export default function BindingEditor({
667
  // built out of groups is not undercounted into reading as empty.
668
  const conditionCount = useMemo(() => countConditions(tree.nodes ?? []), [tree]);
669
  const [fields, setFields] = useState<Field[]>([]);
 
 
 
 
670
  const catalogueDatabase = useRef("");
671
  const [measures, setMeasures] = useState<Measure[]>([]);
672
  const [views, setViews] = useState<BindingView[]>([]);
@@ -738,7 +772,7 @@ export default function BindingEditor({
738
  // render would re-read `initial` after the person had already changed a control, which is how an
739
  // editor forgets an edit the moment its parent re-renders for an unrelated reason.
740
  const migrated = useState(() => migratePeriod(initial?.period))[0];
741
- const savedDrag = useState(() => readOnDrag(initial?.onDrag))[0];
742
 
743
  const [unit, setUnit] = useState<PeriodUnit>(migrated?.unit ?? "month");
744
  const [start, setStart] = useState<string>(
@@ -787,6 +821,17 @@ export default function BindingEditor({
787
  migrated?.window ? "window" : "calendar",
788
  );
789
  const [windowSpec, setWindowSpec] = useState<WindowSpec>(migrated?.window ?? { kind: "ytd" });
 
 
 
 
 
 
 
 
 
 
 
790
  // "Use a cell" is a LINK that REVEALS the A1 input (R9). The input was the whole period control
791
  // before this ticket and it is not deleted, only demoted to the thing behind that link.
792
  const [refOpen, setRefOpen] = useState<boolean>(Boolean(migrated?.ref));
@@ -805,8 +850,33 @@ export default function BindingEditor({
805
  // at all, which is standing rule 1's second sentence - a limit nobody was told about. The switch
806
  // below states which of the two a cell is, and either answer is one click from the other.
807
  const [periodOn, setPeriodOn] = useState<boolean>(Boolean(migrated));
808
- const [across, setAcross] = useState<DragAcross>(savedDrag.across);
809
- const [downField, setDownField] = useState<string>(savedDrag.down);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
810
 
811
  const adoptedFrom = adoptedFromOf(initial);
812
 
@@ -943,6 +1013,30 @@ export default function BindingEditor({
943
  return () => { live = false; };
944
  }, [database, rowsWanted]);
945
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
946
  /** The binding names a view the fresh list does not have. Said in the panel, not after a save.
947
  *
948
  * ⛔ IT STOPS BEING SAID THE MOMENT THE PERSON ANSWERS IT. The sentence asks for one of two acts,
@@ -962,7 +1056,7 @@ export default function BindingEditor({
962
  * already gated, so this is not a second definition of the rule, only a second caller of it. */
963
  const statusValues = useMemo(() => {
964
  const map: Record<string, string[]> = {};
965
- for (const f of fields) {
966
  if (f.type === "user") {
967
  map[f.key] = userOptions;
968
  continue;
@@ -971,7 +1065,7 @@ export default function BindingEditor({
971
  map[f.key] = choiceVocabulary(f, rawRows);
972
  }
973
  return map;
974
- }, [fields, rawRows, userOptions]);
975
 
976
  // Offer every numeric column this database can total, including Metrics created in the app.
977
  // `isNumericType` checks numeric behaviour and `canTotal` checks whether the database can
@@ -1012,24 +1106,27 @@ export default function BindingEditor({
1012
  field: candidate,
1013
  values: bindingStepValues(candidate, rawRows, userOptions),
1014
  }));
1015
- const savedDragDriverMissing = Boolean(downField) && rowsResolved
1016
- && !stepFields.some((candidate) => candidate.key === downField);
1017
- const chooseStepField = (key: string) => {
1018
- if (!key) { setDownField(""); return; }
 
 
 
 
 
 
 
 
 
1019
  const offer = filterClauseOffers.find((candidate) => candidate.field.key === key);
1020
  if (!offer?.values.length || !rowsResolved) return;
1021
- setTree(seedBindingStep(driverTree, offer.field, offer.values[0]));
 
1022
  setScopeKind("filter");
1023
  setViewId("");
1024
- setDownField(key);
1025
  };
1026
- const localDriver = bindingFilterClauses(tree).find((clause) => clause.colId === downField);
1027
- const driverField = fields.find((candidate) => candidate.key === downField);
1028
- const driverValue = localDriver?.op === "isEmpty"
1029
- ? (driverField?.type === "checkbox" ? "Unchecked" : "Empty")
1030
- : localDriver?.op === "isNotEmpty"
1031
- ? (driverField?.type === "checkbox" ? "Checked" : "Filled")
1032
- : localDriver?.value || localDriver?.values?.[0] || "";
1033
 
1034
  /**
1035
  * ⭐⭐ W50-T21 (owner instruction 24: *"Sheet column picker (sum/count) shows the Field icons."*)
@@ -1069,7 +1166,7 @@ export default function BindingEditor({
1069
  setMetricKey("");
1070
  setField("");
1071
  setFn("sum");
1072
- setPeriodOn(false);
1073
  setPreview("");
1074
  setColPickerOpen(false);
1075
  };
@@ -1079,8 +1176,8 @@ export default function BindingEditor({
1079
  setField("");
1080
  setViewId("");
1081
  setTree({ conj: "and", nodes: [] });
1082
- setDownField("");
1083
- setPeriodOn(false);
1084
  setPreview("");
1085
  };
1086
 
@@ -1117,7 +1214,11 @@ export default function BindingEditor({
1117
  // ⛔ C5 - EMIT EXACTLY ONE DIALECT. `clean_period` prefers unit/start when both are present,
1118
  // so combining these branches would silently discard the rolling window.
1119
  if (periodMode === "window") {
1120
- out.period = { window: windowSpec };
 
 
 
 
1121
  } else {
1122
  const period: Record<string, unknown> = {
1123
  unit, start, locked: chosenIsMetric ? locked : true,
@@ -1133,14 +1234,55 @@ export default function BindingEditor({
1133
  // ⛔⛔ R8 REVOKED W51-T12'S ONE-AXIS-AT-A-TIME RULE. The wire keys keep C2's spelling
1134
  // because `clean_on_drag` rebuilds anything else; emitting both slots independently lets one
1135
  // Metric cell step its period and one filter clause without either choice erasing the other.
1136
- out.onDrag = {
1137
- across: chosenIsMetric && periodOn && periodMode === "calendar" && !locked ? across : "none",
1138
- down: downField ? { field: downField, ...(driverField ? { mode: bindingStepMode(driverField) } : {}) } : "none",
1139
- };
 
 
 
1140
  return out;
1141
  }, [database, sourceKind, metricKey, fn, field, scopeKind, viewId, views, tree, initial,
1142
  unit, start, locked, frozen, frozenFrom, frozenTo, refOpen, periodRef, periodOn, periodMode, windowSpec,
1143
- across, downField, driverField, chosenIsMetric]);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1144
 
1145
  // ⭐ THE NUMBER APPEARS BEFORE SAVING. `preview` evaluates the binding without persisting it,
1146
  // which is what lets someone see whether they picked the right thing while they can still change
@@ -1148,7 +1290,9 @@ export default function BindingEditor({
1148
  const runPreview = async () => {
1149
  setNotice("");
1150
  setPreview("");
1151
- const got = await previewCell(workbookId, addr, binding);
 
 
1152
  if (!got.ok) {
1153
  setNotice(got.message);
1154
  return;
@@ -1253,7 +1397,7 @@ export default function BindingEditor({
1253
  <>
1254
  <div className="sheet-binding-body">
1255
  <nav className="sheet-binding-rail" aria-label="Cell database sections">
1256
- {sectionGates.map(({ key, label, reachable, blockedHint }) => (
1257
  <button
1258
  key={key}
1259
  type="button"
@@ -1263,10 +1407,11 @@ export default function BindingEditor({
1263
  title={blockedHint}
1264
  onClick={() => setActiveSection(key)}
1265
  >
1266
- {label}
 
1267
  {!reachable ? (
1268
  <span className="sheet-binding-rail-hint">{blockedHint}</span>
1269
- ) : key === "period" && chosenIsMetric && !periodOn && (
1270
  <>{" "}<span className="sheet-binding-rail-required">Required</span></>
1271
  )}
1272
  </button>
@@ -1396,8 +1541,10 @@ export default function BindingEditor({
1396
  asked for; saying it here means the choice is corrected before a save. */}
1397
  {savedFieldUnavailable && (
1398
  <p className="sheet-notice" role="alert">
1399
- {`The saved column ${field} cannot be totalled on this database. `
1400
- + "Pick a column from the list, or count the records instead."}
 
 
1401
  </p>
1402
  )}
1403
  </div>
@@ -1454,6 +1601,49 @@ export default function BindingEditor({
1454
  : `Edit filter (${conditionCount === 1
1455
  ? "1 condition" : `${conditionCount} conditions`})`}
1456
  </button>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1457
  {/* ⛔⛔ MOUNTED ONLY WHILE OPEN, and that is what orders Escape correctly rather
1458
  than a flag inside the dialog. `useOverlayLayer` claims Escape as soon as it
1459
  runs and `ui/useEscapeClose` gives the key to the LAST entry pushed, so a
@@ -1461,10 +1651,11 @@ export default function BindingEditor({
1461
  editor opened. Mounting it here, later in time, puts it ABOVE this panel's own
1462
  claim (pushed at mount, a few hundred lines up) and unmounting it hands Escape
1463
  straight back, so one press closes the filter and the next closes the panel. */}
 
1464
  {filterPopupOpen && (
1465
  <SheetFilterPopup
1466
  addr={addr}
1467
- fields={fields}
1468
  filters={tree}
1469
  onChange={setTree}
1470
  statusValues={statusValues}
@@ -1493,7 +1684,9 @@ export default function BindingEditor({
1493
  role="switch"
1494
  aria-checked={periodOn}
1495
  className={"sheet-lock-toggle" + (periodOn ? " is-on" : "")}
1496
- onClick={() => setPeriodOn((v) => !v)}
 
 
1497
  >
1498
  <span className="sheet-lock-dot" aria-hidden />
1499
  <span>Limit this cell to a period</span>
@@ -1525,10 +1718,48 @@ export default function BindingEditor({
1525
  </label>
1526
 
1527
  {periodMode === "window" ? (
 
1528
  <label className="sheet-field">
1529
  <span>Lookback</span>
1530
- <WindowPicker window={windowSpec} onWindow={setWindowSpec} />
 
 
 
1531
  </label>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1532
  ) : (
1533
  <>
1534
  <label className="sheet-field">
@@ -1549,7 +1780,16 @@ export default function BindingEditor({
1549
  </select>
1550
  </label>
1551
 
1552
- <div className="sheet-field-row">
 
 
 
 
 
 
 
 
 
1553
  <label className="sheet-field">
1554
  <span>Year</span>
1555
  <select
@@ -1586,7 +1826,7 @@ export default function BindingEditor({
1586
  </select>
1587
  </label>
1588
  )}
1589
- </div>
1590
 
1591
  <div className="sheet-field-row sheet-period-dates">
1592
  <label className="sheet-field">
@@ -1707,85 +1947,79 @@ export default function BindingEditor({
1707
  <fieldset className="sheet-scope sheet-drag">
1708
  <legend>When copied</legend>
1709
 
1710
- {chosenIsMetric && periodOn && periodMode === "calendar" && (
1711
- <>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1712
  <label className="sheet-field">
1713
- <span>{periodClauseLabel}</span>
1714
- <select
1715
- value={!locked && across === "period" ? "period" : "none"}
1716
- aria-label={periodClauseLabel}
1717
- onChange={(e) => {
1718
- const step = e.target.value === "period";
1719
- setAcross(step ? "period" : "none");
1720
- setLocked(!step);
1721
- }}
1722
- >
1723
- <option value="period">{`Step by ${UNIT_NOUN[unit]}`}</option>
1724
- <option value="none">Keep this period</option>
1725
  </select>
1726
  </label>
1727
- <p className="sheet-period-note">
1728
- Right and down move forward. Left and up move backward.
1729
- </p>
1730
- </>
1731
- )}
1732
-
1733
- {/* ⛔ C5 - A ROLLING WINDOW HAS NO START TO SHIFT. Offering the calendar step here
1734
- would promise an action `dragBoundCell` cannot perform. */}
1735
- {periodOn && periodMode === "window" && (
1736
- <p className="sheet-period-note">
1737
- A rolling window is measured from today, so every copy of this cell answers the
1738
- same window. Use a calendar period when the period should step as the cell is copied.
1739
- </p>
1740
- )}
1741
-
1742
- {/* ⚠ AN ALL-TIME METRIC SAYS WHY NO PERIOD PICKER IS PRESENT. Without this note the
1743
- absent control looks like a loading or configuration failure. */}
1744
- {chosenIsMetric && !periodOn && (
1745
- <p className="sheet-period-note">
1746
- Choose a Period or Lookback before saving this Metric.
1747
- </p>
1748
- )}
1749
-
1750
- <div className="sheet-field sheet-field--pick">
1751
- <span>Step field</span>
1752
- <FieldSelectButton
1753
- ariaLabel="Step field when copied"
1754
- placeholder="Keep this filter"
1755
- value={downField}
1756
- onChange={chooseStepField}
1757
- disabled={!rowsResolved}
1758
- searchable
1759
- searchPlaceholder="Find a step field…"
1760
- emptyMessage="No step fields available."
1761
- fields={[
1762
- { key: "", label: "Keep this filter" },
1763
- ...filterClauseOffers.map(({ field: candidate, values }) => ({
1764
- key: candidate.key,
1765
- label: `Step ${candidate.label}`,
1766
- type: candidate.type,
1767
- disabled: !values.length,
1768
- hint: values.length ? undefined : "No values",
1769
- })),
1770
- ...(savedDragDriverMissing ? [{
1771
- key: downField,
1772
- label: `${downField} (unavailable)`,
1773
- disabled: true,
1774
- }] : []),
1775
- ]}
1776
- />
1777
- </div>
1778
  {!rowsResolved && <p className="sheet-period-note" role="status">{rowsNotice || "Loading all field values…"}</p>}
1779
  {savedDragDriverMissing && <p className="sheet-notice" role="alert">The saved Step field is unavailable. Choose another field.</p>}
1780
- {localDriver && driverField && (
1781
- <div className="sheet-step-driver">
1782
- <span>{`${driverField.label}: ${driverValue}`}</span>
1783
- </div>
1784
- )}
1785
- <p className="sheet-period-note">
1786
- Right and down choose later values. Left and up choose earlier values.
1787
- Copies stop at the first or last value.
1788
- </p>
1789
  </fieldset>
1790
  </>
1791
  )}
@@ -1816,7 +2050,9 @@ export default function BindingEditor({
1816
  <button type="button" className="lp-btn lp-btn-quiet" onClick={runPreview} disabled={!ready}>
1817
  Preview
1818
  </button>
1819
- <button type="button" className="lp-btn lp-btn-primary" onClick={() => onSave(binding)}
 
 
1820
  disabled={!ready}>
1821
  Save
1822
  </button>
 
37
  // ease-out on opacity and transform, no emoji, and no em dash or en dash in any string on screen.
38
 
39
  import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
40
+ import { API_V1, CREDENTIALS } from "../apiContract";
41
  import { fetchTopicRows, fetchWorkspace } from "../customer-grid/apiBridge";
42
  import type { SurfaceScope } from "../customer-grid/apiBridge";
43
  import { dayText } from "../customer-grid/display";
44
  import { FieldSelectButton } from "../customer-grid/FieldSelect";
45
+ import { FieldTypeIcon, MenuIcon } from "../customer-grid/icons";
46
  import { BodyPortal, OverlayProvider, useOverlayLayer } from "../customer-grid/OverlaySurface";
47
  import type { Field, FilterTree, GridWorkspace, Measure, Row, SavedView } from "../customer-grid/types";
48
+ import { choiceVocabulary, topicForScope, MULTI_VALUE_OPS } from "../customer-grid/types";
49
  import type { WindowSpec } from "../customer-grid/windows";
50
+ import { normalizeWindow, ENDING_KINDS, ENDING_LABELS, ENDING_STEPS, TO_DATE_KINDS,
51
+ endingBounds, endingStepDefault, ANCHOR_VALUE_FREE } from "../customer-grid/windows";
52
+ import type { EndingKind, EndingStep } from "../customer-grid/windows";
53
  // ⭐⭐ W53-T15 (ruling R8) — THE FILTER BUILDER IS NO LONGER MOUNTED IN THIS COLUMN. The SHARED
54
  // `FilterBuilderPanel` the Data module also uses is untouched; `SheetFilterPopup` wraps it in the
55
  // base kit's centred dialog so its condition rows have room, and only the Sheet mounts that
 
58
  import { SheetFilterPopup } from "../filter-kit/SheetFilterPopup";
59
  import { WindowPicker } from "../filter-kit/WindowPicker";
60
  import { useEscapeClose } from "../ui/useEscapeClose";
61
+ import { previewCell, readWorkbook } from "./sheetApi";
62
+ import { formatRef, parseRef } from "./a1";
63
+ import { bindingAggregate, bindingDisplay, bindingFilterClauses, bindingOnDrag, BINDING_ENDING_STEP, BINDING_PERIOD_STEP } from "./types";
64
+ import type { BindingAggregate, BindingPeriod, BindingDragStep, BindingOnDrag } from "./types";
65
+ import { bindingStepMode, bindingStepValues, resolveEndingCell, seedBindingStep,
66
+ bindingRefSlots, filterValueLeaves, resolveFilterCell, updateFilterValueLeaf } from "./bindingRefs";
67
  import "../styles/wave57/binding-actions.css";
68
  import "../styles/wave58/sheet.css";
69
  import "../styles/wave59/binding.css";
70
 
71
  const BINDING_SECTIONS = [
72
+ { key: "data", label: "Data", icon: <MenuIcon name="description" /> },
73
+ { key: "rows", label: "Filter", icon: <MenuIcon name="filter" /> },
74
+ { key: "period", label: "Period", icon: <FieldTypeIcon type="date" size={16} /> },
75
+ { key: "copied", label: "When copied", icon: <MenuIcon name="duplicate" /> },
76
  ] as const;
77
 
78
  const AGGREGATES = [
 
138
  // ══ THE PERIOD (R9) ═══════════════════════════════════════════════════════════════════════════
139
  //
140
  // ⛔⛔ CONTRACT C2 SPELLS THIS ON THE WIRE AND THE UI DOES NOT GET A VOTE:
141
+ // Unit values are lowercase on the wire. Day/Week starts use `YYYY-MM-DD`, with Week starting
142
+ // on Monday; Month/Quarter/Year starts retain `YYYY-MM`.
 
143
  // A frozen period keeps that pair for returning to the calendar, and adds only
144
  // `frozen: true, from: "YYYY-MM-DD", to: "YYYY-MM-DD"` in place of a cell reference.
145
  //
 
149
  // server compiler reads the pair, and two readings of `2026-08` under `quarter` (August, or Q3)
150
  // are a silent disagreement that no screen shows.
151
 
152
+ export type PeriodUnit = "day" | "week" | "month" | "quarter" | "year";
153
 
154
  export interface PeriodBinding {
155
  unit: PeriodUnit;
 
160
  from?: string;
161
  to?: string;
162
  window?: WindowSpec;
163
+ ending?: BindingPeriod["ending"];
164
+ endingStep?: EndingStep;
165
+ endingOffset?: number;
166
  }
167
 
168
  export const PERIOD_UNITS: { unit: PeriodUnit; label: string }[] = [
169
+ { unit: "day", label: "Day" },
170
+ { unit: "week", label: "Week" },
171
  { unit: "month", label: "Month" },
172
  { unit: "quarter", label: "Quarter" },
173
  { unit: "year", label: "Year" },
 
179
  ];
180
 
181
  /** How many months one step of a unit covers. The only place that arithmetic is stated. */
182
+ const MONTHS_PER_UNIT: Partial<Record<PeriodUnit, number>> = { month: 1, quarter: 3, year: 12 };
183
 
184
  /** The noun a sentence uses for one step. Sentence case, and no dash anywhere near it. */
185
  const UNIT_NOUN: Record<PeriodUnit, string> = {
186
+ day: "day", week: "week", month: "month", quarter: "quarter", year: "year",
187
  };
188
 
189
  const pad2 = (n: number) => String(n).padStart(2, "0");
 
203
 
204
  /** THE PERIOD'S FIRST MONTH, which is what `start` means. See the block above. */
205
  export function normalizePeriodStart(unit: PeriodUnit, ym: string): string {
206
+ if (unit === "day" || unit === "week") {
207
+ const text = /^\d{4}-\d{2}$/.test(ym) ? `${ym}-01` : ym;
208
+ const date = new Date(`${text}T00:00:00Z`);
209
+ if (!Number.isFinite(date.getTime()) || date.toISOString().slice(0, 10) !== text) return text;
210
+ if (unit === "week") date.setUTCDate(date.getUTCDate() - (date.getUTCDay() + 6) % 7);
211
+ return date.toISOString().slice(0, 10);
212
+ }
213
+ const { y, m } = splitYm(ym.slice(0, 7));
214
  if (unit === "year") return joinYm(y, 1);
215
  if (unit === "quarter") return joinYm(y, 1 + 3 * Math.floor((m - 1) / 3));
216
  return joinYm(y, m);
 
218
 
219
  /** Move a start by whole periods. Negative steps go back; this is also the drag rule's maths. */
220
  export function shiftPeriodStart(unit: PeriodUnit, ym: string, steps: number): string {
221
+ if (unit === "day" || unit === "week") {
222
+ const date = new Date(`${normalizePeriodStart(unit, ym)}T00:00:00Z`);
223
+ if (!Number.isFinite(date.getTime())) return ym;
224
+ date.setUTCDate(date.getUTCDate() + steps * (unit === "week" ? 7 : 1));
225
+ return date.toISOString().slice(0, 10);
226
+ }
227
  const { y, m } = splitYm(normalizePeriodStart(unit, ym));
228
+ const total = y * 12 + (m - 1) + steps * MONTHS_PER_UNIT[unit]!;
229
  return joinYm(Math.floor(total / 12), (total % 12) + 1);
230
  }
231
 
 
233
  * `platform/modules/sheet.py::period_window`, whose `to` is the LAST DAY of the period. */
234
  export function periodRange(unit: PeriodUnit, ym: string): { from: string; to: string } {
235
  const start = normalizePeriodStart(unit, ym);
236
+ if (unit === "day" || unit === "week") {
237
+ const last = new Date(`${start}T00:00:00Z`);
238
+ if (!Number.isFinite(last.getTime())) return { from: "", to: "" };
239
+ last.setUTCDate(last.getUTCDate() + (unit === "week" ? 6 : 0));
240
+ return { from: start, to: last.toISOString().slice(0, 10) };
241
+ }
242
  const last = new Date(`${shiftPeriodStart(unit, start, 1)}-01T00:00:00Z`);
243
  last.setUTCDate(last.getUTCDate() - 1);
244
  return { from: `${start}-01`, to: last.toISOString().slice(0, 10) };
 
287
  start: normalizePeriodStart("month", todayYm()),
288
  locked: true,
289
  window,
290
+ ...(p.ending && typeof p.ending === "object" ? {
291
+ ending: p.ending as BindingPeriod["ending"],
292
+ endingStep: (p.endingStep ?? endingStepDefault(window.kind)) as EndingStep,
293
+ endingOffset: Number(p.endingOffset ?? 0), locked: p.locked === true,
294
+ ...(ref ? { ref } : {}),
295
+ } : {}),
296
  };
297
  }
298
  const declared = PERIOD_UNITS.some((u) => u.unit === p.unit);
 
304
  const unit = p.unit as PeriodUnit;
305
  const stored = typeof p.start === "string" ? p.start.trim() : "";
306
  // D-660: no window named, and no cell to take one from, so there is no period to read.
307
+ const startPattern = unit === "day" || unit === "week" ? /^\d{4}-\d{2}-\d{2}$/ : /^\d{4}-\d{2}$/;
308
+ if (!startPattern.test(stored) && !ref && p.frozen !== true) return null;
309
  const start = normalizePeriodStart(unit, stored || todayYm());
310
  const locked = p.locked === true;
311
  if (p.frozen === true) {
 
328
  export interface OnDragBinding {
329
  across: DragAcross;
330
  down: { field: string } | "none";
331
+ steps?: readonly BindingDragStep[];
332
  }
333
 
334
  /** A copy step walks a column's stored values. Measure-backed and Metric columns are computed
 
340
 
341
  /** The saved `onDrag`, defaulted. `down` is carried as a field key, empty meaning nothing. */
342
  export function readOnDrag(raw: unknown): { across: DragAcross; down: string } {
343
+ const rules = bindingOnDrag({ onDrag: raw });
344
+ return { across: rules.across, down: rules.down === "none" ? "" : rules.down.field };
 
 
 
 
 
 
345
  }
346
 
347
  /** `scope.adoptedFrom` (R11): the view was purged and its filter was copied into this cell. */
 
697
  // built out of groups is not undercounted into reading as empty.
698
  const conditionCount = useMemo(() => countConditions(tree.nodes ?? []), [tree]);
699
  const [fields, setFields] = useState<Field[]>([]);
700
+ const [linkedOffer, setLinkedOffer] = useState<{ database: string; fields: Field[] }>({ database: "", fields: [] });
701
+ const [linkedNotice, setLinkedNotice] = useState("");
702
+ const filterFields = useMemo(() => [...fields,
703
+ ...(linkedOffer.database === database ? linkedOffer.fields : [])], [fields, linkedOffer, database]);
704
  const catalogueDatabase = useRef("");
705
  const [measures, setMeasures] = useState<Measure[]>([]);
706
  const [views, setViews] = useState<BindingView[]>([]);
 
772
  // render would re-read `initial` after the person had already changed a control, which is how an
773
  // editor forgets an edit the moment its parent re-renders for an unrelated reason.
774
  const migrated = useState(() => migratePeriod(initial?.period))[0];
775
+ const savedDrag = useState(() => bindingOnDrag(initial))[0];
776
 
777
  const [unit, setUnit] = useState<PeriodUnit>(migrated?.unit ?? "month");
778
  const [start, setStart] = useState<string>(
 
821
  migrated?.window ? "window" : "calendar",
822
  );
823
  const [windowSpec, setWindowSpec] = useState<WindowSpec>(migrated?.window ?? { kind: "ytd" });
824
+ const [ending, setEnding] = useState<EndingKind>(migrated?.ending?.kind ?? "today");
825
+ const [endingFixed, setEndingFixed] = useState(migrated?.ending?.date ?? "");
826
+ const [endingStep, setEndingStep] = useState<EndingStep>(
827
+ migrated?.endingStep ?? endingStepDefault(windowSpec.kind));
828
+ const [endingOffset, setEndingOffset] = useState(migrated?.endingOffset ?? 0);
829
+ const [endingSheets, setEndingSheets] = useState<{ id: string; name: string }[]>([]);
830
+ const [endingSheet, setEndingSheet] = useState(() => parseRef(migrated?.ref ?? "")?.sheet ?? "");
831
+ const parsedEndingRef = parseRef(periodRef);
832
+ const endingRef = parsedEndingRef && !parsedEndingRef.sheet && endingSheet
833
+ ? formatRef({ ...parsedEndingRef, sheet: endingSheet }) : periodRef.trim();
834
+ const hasEnding = (TO_DATE_KINDS as readonly string[]).includes(windowSpec.kind);
835
  // "Use a cell" is a LINK that REVEALS the A1 input (R9). The input was the whole period control
836
  // before this ticket and it is not deleted, only demoted to the thing behind that link.
837
  const [refOpen, setRefOpen] = useState<boolean>(Boolean(migrated?.ref));
 
850
  // at all, which is standing rule 1's second sentence - a limit nobody was told about. The switch
851
  // below states which of the two a cell is, and either answer is one click from the other.
852
  const [periodOn, setPeriodOn] = useState<boolean>(Boolean(migrated));
853
+ useEffect(() => {
854
+ if (!periodOn || periodMode !== "window" || ending !== "cell") return;
855
+ let cancelled = false;
856
+ void readWorkbook(workbookId).then((got) => {
857
+ if (cancelled) return;
858
+ if (!got.ok) { setNotice(got.message); return; }
859
+ setEndingSheets(got.value.sheets.map(({ id, name }) => ({ id, name })));
860
+ setEndingSheet((held) => held || got.value.sheets[0]?.name || "");
861
+ });
862
+ return () => { cancelled = true; };
863
+ }, [workbookId, periodOn, periodMode, ending]);
864
+ const [copySteps, setCopySteps] = useState<readonly BindingDragStep[]>(() =>
865
+ (savedDrag.steps ?? []).filter((step) =>
866
+ (step.field !== BINDING_PERIOD_STEP && step.field !== BINDING_ENDING_STEP) || !migrated?.locked));
867
+ const [copyStepsEdited, setCopyStepsEdited] = useState(false);
868
+ const updateCopySteps = (steps: readonly BindingDragStep[]) => {
869
+ setCopySteps(steps); setCopyStepsEdited(true);
870
+ };
871
+ const across: DragAcross = copySteps.some((step) =>
872
+ step.field === BINDING_PERIOD_STEP || step.field === BINDING_ENDING_STEP) ? "period" : "none";
873
+ const setAcross = (value: DragAcross) => {
874
+ const field = hasEnding ? BINDING_ENDING_STEP : BINDING_PERIOD_STEP;
875
+ const kept = copySteps.filter((step) => step.field !== field);
876
+ updateCopySteps(value === "none" ? kept : [...kept, { field, axis: "across",
877
+ ...(hasEnding ? { size: endingStep } : {}),
878
+ }]);
879
+ };
880
 
881
  const adoptedFrom = adoptedFromOf(initial);
882
 
 
1013
  return () => { live = false; };
1014
  }, [database, rowsWanted]);
1015
 
1016
+ // The related grid's field wall is checked on the server. Keep its labelled fields in the
1017
+ // existing Filter picker only; a customer's amount is not an order aggregate column.
1018
+ useEffect(() => {
1019
+ if (!rowsWanted || !database) return undefined;
1020
+ const controller = new AbortController();
1021
+ setLinkedOffer({ database, fields: [] });
1022
+ setLinkedNotice("");
1023
+ (async () => {
1024
+ try {
1025
+ const response = await fetch(`${API_V1}/sheets/filter-fields/${encodeURIComponent(database)}`, {
1026
+ credentials: CREDENTIALS, signal: controller.signal,
1027
+ });
1028
+ const body = await response.json().catch(() => null);
1029
+ if (!response.ok || !Array.isArray(body?.fields))
1030
+ throw new Error(body?.error?.message || "Linked fields could not be loaded. Close and reopen this panel to retry.");
1031
+ if (!controller.signal.aborted) setLinkedOffer({ database, fields: body.fields as Field[] });
1032
+ } catch (error) {
1033
+ if (!controller.signal.aborted) setLinkedNotice(error instanceof Error ? error.message
1034
+ : "Linked fields could not be loaded. Close and reopen this panel to retry.");
1035
+ }
1036
+ })();
1037
+ return () => controller.abort();
1038
+ }, [database, rowsWanted]);
1039
+
1040
  /** The binding names a view the fresh list does not have. Said in the panel, not after a save.
1041
  *
1042
  * ⛔ IT STOPS BEING SAID THE MOMENT THE PERSON ANSWERS IT. The sentence asks for one of two acts,
 
1056
  * already gated, so this is not a second definition of the rule, only a second caller of it. */
1057
  const statusValues = useMemo(() => {
1058
  const map: Record<string, string[]> = {};
1059
+ for (const f of filterFields) {
1060
  if (f.type === "user") {
1061
  map[f.key] = userOptions;
1062
  continue;
 
1065
  map[f.key] = choiceVocabulary(f, rawRows);
1066
  }
1067
  return map;
1068
+ }, [filterFields, rawRows, userOptions]);
1069
 
1070
  // Offer every numeric column this database can total, including Metrics created in the app.
1071
  // `isNumericType` checks numeric behaviour and `canTotal` checks whether the database can
 
1106
  field: candidate,
1107
  values: bindingStepValues(candidate, rawRows, userOptions),
1108
  }));
1109
+ const savedDragDriverMissing = rowsResolved && copySteps.some((step) => step.field
1110
+ && step.field !== BINDING_ENDING_STEP && step.field !== BINDING_PERIOD_STEP
1111
+ && !stepFields.some((candidate) => candidate.key === step.field));
1112
+ const chooseStepField = (index: number, key: string) => {
1113
+ const replace = (step: BindingDragStep) => updateCopySteps(copySteps.map((held, i) => i === index ? step : held));
1114
+ if (key === BINDING_ENDING_STEP || key === BINDING_PERIOD_STEP) {
1115
+ replace({ field: key, axis: copySteps[index].axis,
1116
+ ...(key === BINDING_ENDING_STEP ? { size: endingStepDefault(windowSpec.kind) } : {}),
1117
+ });
1118
+ setLocked(false);
1119
+ return;
1120
+ }
1121
+ if (!key) { replace({ field: "", axis: copySteps[index].axis }); return; }
1122
  const offer = filterClauseOffers.find((candidate) => candidate.field.key === key);
1123
  if (!offer?.values.length || !rowsResolved) return;
1124
+ setTree(bindingFilterClauses(driverTree).some((clause) => clause.colId === key)
1125
+ ? driverTree : seedBindingStep(driverTree, offer.field, offer.values[0]));
1126
  setScopeKind("filter");
1127
  setViewId("");
1128
+ replace({ field: key, axis: copySteps[index].axis, mode: bindingStepMode(offer.field) });
1129
  };
 
 
 
 
 
 
 
1130
 
1131
  /**
1132
  * ⭐⭐ W50-T21 (owner instruction 24: *"Sheet column picker (sum/count) shows the Field icons."*)
 
1166
  setMetricKey("");
1167
  setField("");
1168
  setFn("sum");
1169
+ setPeriodOn(kind === "number");
1170
  setPreview("");
1171
  setColPickerOpen(false);
1172
  };
 
1176
  setField("");
1177
  setViewId("");
1178
  setTree({ conj: "and", nodes: [] });
1179
+ updateCopySteps([]);
1180
+ setPeriodOn(chosenIsMetric);
1181
  setPreview("");
1182
  };
1183
 
 
1214
  // ⛔ C5 - EMIT EXACTLY ONE DIALECT. `clean_period` prefers unit/start when both are present,
1215
  // so combining these branches would silently discard the rolling window.
1216
  if (periodMode === "window") {
1217
+ out.period = { window: windowSpec, ...(hasEnding ? {
1218
+ ending: { kind: ending, ...(ending === "fixed" ? { date: endingFixed } : {}) },
1219
+ endingStep, ...(endingOffset ? { endingOffset } : {}),
1220
+ locked: across === "none", ...(ending === "cell" ? { ref: endingRef } : {}),
1221
+ } : {}) };
1222
  } else {
1223
  const period: Record<string, unknown> = {
1224
  unit, start, locked: chosenIsMetric ? locked : true,
 
1234
  // ⛔⛔ R8 REVOKED W51-T12'S ONE-AXIS-AT-A-TIME RULE. The wire keys keep C2's spelling
1235
  // because `clean_on_drag` rebuilds anything else; emitting both slots independently lets one
1236
  // Metric cell step its period and one filter clause without either choice erasing the other.
1237
+ const steps = copySteps.filter((step) => step.field && (step.field === BINDING_ENDING_STEP
1238
+ ? periodOn && hasEnding && periodMode === "window" : step.field === BINDING_PERIOD_STEP
1239
+ ? periodOn && chosenIsMetric && !locked && periodMode === "calendar" : true));
1240
+ // An unchanged legacy editor keeps the old copy semantics on save as well as on read.
1241
+ out.onDrag = !copyStepsEdited && !Array.isArray((initial?.onDrag as BindingOnDrag | undefined)?.steps)
1242
+ ? { across: savedDrag.across, down: savedDrag.down }
1243
+ : bindingOnDrag({ onDrag: { steps } });
1244
  return out;
1245
  }, [database, sourceKind, metricKey, fn, field, scopeKind, viewId, views, tree, initial,
1246
  unit, start, locked, frozen, frozenFrom, frozenTo, refOpen, periodRef, periodOn, periodMode, windowSpec,
1247
+ across, copySteps, copyStepsEdited, savedDrag, chosenIsMetric, hasEnding, ending, endingFixed, endingStep, endingOffset, endingRef]);
1248
+
1249
+ // Read before either send; the server reads the stored source again independently.
1250
+ const prepareBinding = async (): Promise<Record<string, unknown> | null> => {
1251
+ let value = endingFixed;
1252
+ let prepared = binding;
1253
+ try {
1254
+ const filterRefs = bindingRefSlots(binding).filter((slot) => slot.kind === "filter");
1255
+ if (filterRefs.length) {
1256
+ const got = await readWorkbook(workbookId);
1257
+ if (!got.ok) throw new Error(got.message);
1258
+ const scope = binding.scope as { filter: FilterTree };
1259
+ let previewTree = scope.filter;
1260
+ for (const slot of filterRefs) {
1261
+ const operand = resolveFilterCell(got.value, slot.text);
1262
+ previewTree = updateFilterValueLeaf(previewTree, slot.indices!, (node) => ({ ...node,
1263
+ value: operand, ...((MULTI_VALUE_OPS as ReadonlySet<string>).has(node.op) ? { values: [operand] } : {}),
1264
+ }));
1265
+ }
1266
+ prepared = { ...binding, scope: { ...scope, filter: previewTree } };
1267
+ }
1268
+ if (!periodOn || periodMode !== "window" || !hasEnding) return prepared;
1269
+ if (ending === "cell") {
1270
+ const got = await readWorkbook(workbookId);
1271
+ if (!got.ok) throw new Error(got.message);
1272
+ value = resolveEndingCell(got.value, endingRef);
1273
+ }
1274
+ const today = new Date();
1275
+ const day = `${today.getFullYear()}-${pad2(today.getMonth() + 1)}-${pad2(today.getDate())}`;
1276
+ if (!endingBounds(windowSpec.kind, ending, value, day, endingStep, endingOffset))
1277
+ throw new Error("Ending cannot be used because its date is invalid or falls before the lookback starts. Choose a later ending date.");
1278
+ return ending === "cell" ? { ...prepared, period: {
1279
+ ...(binding.period as Record<string, unknown>), ending: { kind: "cell", date: value },
1280
+ } } : prepared;
1281
+ } catch (error) {
1282
+ setNotice(error instanceof Error ? error.message : "The Ending date could not be read. Choose a valid date.");
1283
+ return null;
1284
+ }
1285
+ };
1286
 
1287
  // ⭐ THE NUMBER APPEARS BEFORE SAVING. `preview` evaluates the binding without persisting it,
1288
  // which is what lets someone see whether they picked the right thing while they can still change
 
1290
  const runPreview = async () => {
1291
  setNotice("");
1292
  setPreview("");
1293
+ const prepared = await prepareBinding();
1294
+ if (!prepared) return;
1295
+ const got = await previewCell(workbookId, addr, prepared);
1296
  if (!got.ok) {
1297
  setNotice(got.message);
1298
  return;
 
1397
  <>
1398
  <div className="sheet-binding-body">
1399
  <nav className="sheet-binding-rail" aria-label="Cell database sections">
1400
+ {sectionGates.map(({ key, label, icon, reachable, blockedHint }) => (
1401
  <button
1402
  key={key}
1403
  type="button"
 
1407
  title={blockedHint}
1408
  onClick={() => setActiveSection(key)}
1409
  >
1410
+ <span className="sheet-binding-rail-icon">{icon}</span>
1411
+ <span className="sheet-binding-rail-label">{label}</span>
1412
  {!reachable ? (
1413
  <span className="sheet-binding-rail-hint">{blockedHint}</span>
1414
+ ) : key === "period" && chosenIsMetric && !periodComplete && (
1415
  <>{" "}<span className="sheet-binding-rail-required">Required</span></>
1416
  )}
1417
  </button>
 
1541
  asked for; saying it here means the choice is corrected before a save. */}
1542
  {savedFieldUnavailable && (
1543
  <p className="sheet-notice" role="alert">
1544
+ {chosenField && isMetricField(chosenField) && !isNumericType(chosenField.type)
1545
+ ? `The saved Metric column ${chosenField.label || field} has no numeric type. Choose Metric as the source.`
1546
+ : `The saved column ${chosenField?.label || field} cannot be totalled on this database. `
1547
+ + "Pick a column from the list, or count the records instead."}
1548
  </p>
1549
  )}
1550
  </div>
 
1601
  : `Edit filter (${conditionCount === 1
1602
  ? "1 condition" : `${conditionCount} conditions`})`}
1603
  </button>
1604
+ {filterValueLeaves(tree).map(({ node, indices }, index) => {
1605
+ const title = filterFields.find((candidate) => candidate.key === node.colId)?.label || node.colId;
1606
+ const supported = !["isEmpty", "isNotEmpty", "aboveAvg", "belowAvg", "within"].includes(node.op)
1607
+ && !node.colId.startsWith("__") && !node.rhs && !ANCHOR_VALUE_FREE.has(node.dateMode ?? "");
1608
+ if (!supported && !node.valueRef) return null;
1609
+ return <div key={indices.join(".")} className="sheet-step-driver">
1610
+ <label className="sheet-field">
1611
+ <span>{`${title} value source`}</span>
1612
+ <select aria-label={`Filter condition ${index + 1} value source`}
1613
+ value={node.valueRef ? "cell" : "typed"}
1614
+ onChange={(e) => {
1615
+ setPreview("");
1616
+ setTree(updateFilterValueLeaf(tree, indices, (leaf) => {
1617
+ const { valueRef: _old, ...typed } = leaf;
1618
+ return e.target.value === "cell"
1619
+ ? { ...typed, valueRef: { ref: "" } } : typed;
1620
+ }));
1621
+ }}>
1622
+ <option value="typed">Typed value</option>
1623
+ <option value="cell">From a cell</option>
1624
+ </select>
1625
+ </label>
1626
+ {node.valueRef && <>
1627
+ <label className="sheet-field">
1628
+ <span>Cell</span>
1629
+ <input type="text" aria-label={`Filter condition ${index + 1} value cell`}
1630
+ placeholder="Sheet1!$A$1" value={node.valueRef.ref}
1631
+ onChange={(e) => {
1632
+ setPreview("");
1633
+ setTree(updateFilterValueLeaf(tree, indices, (leaf) => ({ ...leaf,
1634
+ valueRef: { ...leaf.valueRef, ref: e.target.value } })));
1635
+ }} />
1636
+ </label>
1637
+ <label className="sheet-radio">
1638
+ <input type="checkbox" checked={node.valueRef.locked === true}
1639
+ onChange={(e) => setTree(updateFilterValueLeaf(tree, indices, (leaf) => ({ ...leaf,
1640
+ valueRef: { ...leaf.valueRef!, locked: e.target.checked } })))} />
1641
+ <span>Keep this cell when copied</span>
1642
+ </label>
1643
+ <p className="sheet-period-note">Include the sheet name when this workbook has several sheets.</p>
1644
+ </>}
1645
+ </div>;
1646
+ })}
1647
  {/* ⛔⛔ MOUNTED ONLY WHILE OPEN, and that is what orders Escape correctly rather
1648
  than a flag inside the dialog. `useOverlayLayer` claims Escape as soon as it
1649
  runs and `ui/useEscapeClose` gives the key to the LAST entry pushed, so a
 
1651
  editor opened. Mounting it here, later in time, puts it ABOVE this panel's own
1652
  claim (pushed at mount, a few hundred lines up) and unmounting it hands Escape
1653
  straight back, so one press closes the filter and the next closes the panel. */}
1654
+ {linkedNotice && <p className="sheet-notice" role="alert">{linkedNotice}</p>}
1655
  {filterPopupOpen && (
1656
  <SheetFilterPopup
1657
  addr={addr}
1658
+ fields={filterFields}
1659
  filters={tree}
1660
  onChange={setTree}
1661
  statusValues={statusValues}
 
1684
  role="switch"
1685
  aria-checked={periodOn}
1686
  className={"sheet-lock-toggle" + (periodOn ? " is-on" : "")}
1687
+ disabled={chosenIsMetric}
1688
+ title={chosenIsMetric ? "A Metric cell always covers a period." : undefined}
1689
+ onClick={() => { if (!chosenIsMetric) setPeriodOn((v) => !v); }}
1690
  >
1691
  <span className="sheet-lock-dot" aria-hidden />
1692
  <span>Limit this cell to a period</span>
 
1718
  </label>
1719
 
1720
  {periodMode === "window" ? (
1721
+ <>
1722
  <label className="sheet-field">
1723
  <span>Lookback</span>
1724
+ <WindowPicker window={windowSpec} onWindow={(next) => {
1725
+ setWindowSpec(next); setEndingStep(endingStepDefault(next.kind));
1726
+ setEndingOffset(0);
1727
+ }} />
1728
  </label>
1729
+ {hasEnding && <>
1730
+ <label className="sheet-field">
1731
+ <span>Ending</span>
1732
+ <select aria-label="Ending" value={ending} onChange={(e) => {
1733
+ setEnding(e.target.value as EndingKind); setEndingOffset(0);
1734
+ }}>
1735
+ {ENDING_KINDS.map((kind) => <option key={kind} value={kind}>{ENDING_LABELS[kind]}</option>)}
1736
+ </select>
1737
+ </label>
1738
+ {ending === "fixed" && <label className="sheet-field">
1739
+ <span>Ending date</span>
1740
+ <input type="date" aria-label="Ending date" value={endingFixed}
1741
+ onChange={(e) => { setEndingFixed(e.target.value); setEndingOffset(0); }} />
1742
+ </label>}
1743
+ {ending === "cell" && <>
1744
+ {!parsedEndingRef?.sheet && <label className="sheet-field">
1745
+ <span>Source sheet</span>
1746
+ <select aria-label="Ending source sheet" value={endingSheet}
1747
+ disabled={!endingSheets.length} onChange={(e) => setEndingSheet(e.target.value)}>
1748
+ {!endingSheets.length && <option value="">Loading sheets…</option>}
1749
+ {endingSheets.map((sheet) => <option key={sheet.id} value={sheet.name}>{sheet.name}</option>)}
1750
+ </select>
1751
+ </label>}
1752
+ <label className="sheet-field">
1753
+ <span>Date cell</span>
1754
+ <input type="text" aria-label="Ending date cell" value={periodRef}
1755
+ placeholder="A1" onChange={(e) => { setPeriodRef(e.target.value); setEndingOffset(0); }} />
1756
+ </label>
1757
+ </>}
1758
+ {endingOffset > 0 && <p className="sheet-period-note">
1759
+ {`Ending moved later by ${endingOffset} ${endingStep}${endingOffset === 1 ? "" : "s"} when copied.`}
1760
+ </p>}
1761
+ </>}
1762
+ </>
1763
  ) : (
1764
  <>
1765
  <label className="sheet-field">
 
1780
  </select>
1781
  </label>
1782
 
1783
+ {unit === "day" || unit === "week" ? (
1784
+ <label className="sheet-field">
1785
+ <span>{unit === "week" ? "Week starting" : "Day"}</span>
1786
+ <input type="date" aria-label="Calendar period date" value={start}
1787
+ onChange={(e) => {
1788
+ resumeRollingPeriod();
1789
+ setStart(normalizePeriodStart(unit, e.target.value));
1790
+ }} />
1791
+ </label>
1792
+ ) : <div className="sheet-field-row">
1793
  <label className="sheet-field">
1794
  <span>Year</span>
1795
  <select
 
1826
  </select>
1827
  </label>
1828
  )}
1829
+ </div>}
1830
 
1831
  <div className="sheet-field-row sheet-period-dates">
1832
  <label className="sheet-field">
 
1947
  <fieldset className="sheet-scope sheet-drag">
1948
  <legend>When copied</legend>
1949
 
1950
+ {copySteps.map((step, index) => {
1951
+ const isEnding = step.field === BINDING_ENDING_STEP;
1952
+ const isPeriod = step.field === BINDING_PERIOD_STEP;
1953
+ const driverField = fields.find((candidate) => candidate.key === step.field);
1954
+ const localDriver = bindingFilterClauses(tree).find((clause) => clause.colId === step.field);
1955
+ const driverValue = localDriver?.op === "isEmpty" ? "Empty"
1956
+ : localDriver?.op === "isNotEmpty" ? "Filled"
1957
+ : localDriver?.value || localDriver?.values?.[0] || "";
1958
+ const missing = step.field && !isEnding && !isPeriod && rowsResolved && !driverField;
1959
+ return <div key={index} className="sheet-step-driver">
1960
+ <div className="sheet-field sheet-field--pick">
1961
+ <span>Step field</span>
1962
+ <FieldSelectButton
1963
+ ariaLabel={index ? `Step field ${index + 1} when copied` : "Step field when copied"}
1964
+ placeholder="Choose a step field"
1965
+ value={step.field}
1966
+ onChange={(key) => chooseStepField(index, key)}
1967
+ searchable
1968
+ searchPlaceholder="Find a step field…"
1969
+ emptyMessage="No step fields available."
1970
+ fields={[
1971
+ ...(periodOn && hasEnding && periodMode === "window" ? [{
1972
+ key: BINDING_ENDING_STEP, label: "Ending",
1973
+ disabled: copySteps.some((held, i) => i !== index && held.field === BINDING_ENDING_STEP),
1974
+ }] : []),
1975
+ ...(chosenIsMetric && periodOn && periodMode === "calendar" ? [{
1976
+ key: BINDING_PERIOD_STEP, label: periodClauseLabel,
1977
+ disabled: copySteps.some((held, i) => i !== index && held.field === BINDING_PERIOD_STEP),
1978
+ }] : []),
1979
+ ...filterClauseOffers.map(({ field: candidate, values }) => ({
1980
+ key: candidate.key, label: `Step ${candidate.label}`, type: candidate.type,
1981
+ disabled: !rowsResolved || !values.length
1982
+ || copySteps.some((held, i) => i !== index && held.field === candidate.key),
1983
+ hint: values.length ? undefined : "No values",
1984
+ })),
1985
+ ...(missing ? [{ key: step.field, label: `${step.field} (unavailable)`, disabled: true }] : []),
1986
+ ]}
1987
+ />
1988
+ </div>
1989
  <label className="sheet-field">
1990
+ <span>Direction</span>
1991
+ <select aria-label={`Step ${index + 1} direction`} value={step.axis}
1992
+ onChange={(e) => updateCopySteps(copySteps.map((held, i) => i === index
1993
+ ? { ...held, axis: e.target.value as BindingDragStep["axis"] } : held))}>
1994
+ <option value="across">Across</option>
1995
+ <option value="down">Down</option>
 
 
 
 
 
 
1996
  </select>
1997
  </label>
1998
+ {isEnding && <label className="sheet-field">
1999
+ <span>Ending step size</span>
2000
+ <select aria-label="Ending step size" value={step.size ?? endingStepDefault(windowSpec.kind)}
2001
+ onChange={(e) => updateCopySteps(copySteps.map((held, i) => i === index
2002
+ ? { ...held, size: e.target.value as EndingStep } : held))}>
2003
+ {ENDING_STEPS.map((size) => <option key={size} value={size}>
2004
+ {size[0].toUpperCase() + size.slice(1)}
2005
+ </option>)}
2006
+ </select>
2007
+ </label>}
2008
+ {localDriver && driverField && <span>{`${driverField.label}: ${driverValue}`}</span>}
2009
+ <button type="button" className="sheet-link"
2010
+ aria-label={`Remove step field ${index + 1}`}
2011
+ onClick={() => updateCopySteps(copySteps.filter((_, i) => i !== index))}>
2012
+ Remove step field
2013
+ </button>
2014
+ </div>;
2015
+ })}
2016
+ <button type="button" className="sheet-link"
2017
+ disabled={copySteps.some((step) => !step.field)}
2018
+ onClick={() => updateCopySteps([...copySteps, { field: "", axis: "across" }])}>
2019
+ Add step field
2020
+ </button>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2021
  {!rowsResolved && <p className="sheet-period-note" role="status">{rowsNotice || "Loading all field values…"}</p>}
2022
  {savedDragDriverMissing && <p className="sheet-notice" role="alert">The saved Step field is unavailable. Choose another field.</p>}
 
 
 
 
 
 
 
 
 
2023
  </fieldset>
2024
  </>
2025
  )}
 
2050
  <button type="button" className="lp-btn lp-btn-quiet" onClick={runPreview} disabled={!ready}>
2051
  Preview
2052
  </button>
2053
+ <button type="button" className="lp-btn lp-btn-primary" onClick={async () => {
2054
+ setNotice(""); const prepared = await prepareBinding(); if (prepared) onSave(binding);
2055
+ }}
2056
  disabled={!ready}>
2057
  Save
2058
  </button>
web/src/sheet/ChartDialog.tsx CHANGED
@@ -43,19 +43,26 @@
43
  // rather than a spinner while the database list is in flight, press feedback that does not change
44
  // layout, reduced motion honoured, and no em dash or en dash in any string that reaches a screen.
45
 
46
- import { createContext, useContext, useEffect, useId, useMemo, useRef, useState } from "react";
 
47
  import { BodyPortal, useOverlayLayer } from "../customer-grid/OverlaySurface";
48
  // The document's own addresser, in SHEET coordinates. A second spelling of A1 in this file would
49
  // be a second answer to a question the document already answers.
50
  import { addressOf } from "./sheetState";
51
  import { parseRange } from "./rules";
52
- import type { Cell, SheetChartRange, SheetChartSpec, SheetTab, SheetChartPresentation, SheetChartColor } from "./types";
53
  import { defaultChartPresentation } from "./types";
54
- import { chartDataForRange, DrawnChart } from "./SheetChart";
55
  import type { SheetChartData } from "./SheetChart";
56
  import "../styles/wave58/sheet.css";
57
  import "../styles/wave59/chart-dialog.css";
58
 
 
 
 
 
 
 
59
  /** The page owns the atomic workbook write; isolated legacy mounts retain their old callback. */
60
  export const ChartWorkbookContext = createContext<{
61
  sheets: SheetTab[]; activeSheetId: string;
@@ -368,6 +375,27 @@ export function planDatabaseBlock(opts: {
368
  };
369
  }
370
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
371
 
372
  type SourceTab = "range" | "database";
373
 
@@ -438,9 +466,11 @@ export default function ChartDialog({
438
  const [chartHeight, setChartHeight] = useState(String(chart?.geometry?.height ?? 360));
439
  const [section, setSection] = useState(opening.section);
440
  const [galleryTab, setGalleryTab] = useState<"recommended" | "all">(editing || initialKind ? "all" : "recommended");
441
- const [bounds, setBounds] = useState<Record<string,string>>(() => Object.fromEntries(["yMin","yMax","yMajor","yMinor"].map(k=>[k,String(chart?.presentation?.[k as "yMin"]??"")])));
442
  const setOption = <K extends keyof SheetChartPresentation>(key: K, value: SheetChartPresentation[K]) =>
443
  setPresentation(current => ({...current,[key]:value}));
 
 
444
 
445
  const [tab, setTab] = useState<SourceTab>("range");
446
  const [kind, setKind] = useState<SheetChartSpec["kind"]>(opening.kind);
@@ -506,6 +536,22 @@ export default function ChartDialog({
506
  const model = candidates.find(candidate => candidate.kind === kind)!.model;
507
  const recommended = useMemo(() => range ? recommendChartKinds(candidates) : [], [candidates,range]);
508
  const previewError = range ? chartPreviewError(kind, model) : "Enter a valid data range.";
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
509
  const galleryKinds = galleryTab === "recommended" ? recommended : CHART_KINDS.map(entry => entry.kind);
510
  const thumbnailPresentation: SheetChartPresentation = {
511
  ...presentation, showLegend: false, showDataLabels: false, showAxisTitles: false, layout: "compact",
@@ -522,13 +568,15 @@ export default function ChartDialog({
522
  railRef.current?.querySelector<HTMLElement>('[aria-selected="true"]')
523
  ?.scrollIntoView({ block: "nearest" });
524
  }, [kind, galleryTab, section, tab]);
525
- const offeredSeries = useMemo(() => chartDataForRange(sourceCells, range ?? seedRange, {...presentation,series:[]}, ranges ?? [seedRange], kind).series, [sourceCells,range,presentation,ranges,kind]);
 
526
  const configuredSeries = (presentation.series ?? []).flatMap(setting => {
527
  const offered = offeredSeries.find(s => s.sourceKey === setting.key || s.y === setting.key);
528
  return offered ? [{...setting,key:offered.sourceKey || offered.y}] : [];
529
  });
530
  const settings: NonNullable<SheetChartPresentation["series"]> = [...configuredSeries,
531
  ...offeredSeries.filter(s => !configuredSeries.some(c => c.key === (s.sourceKey||s.y))).map(s => ({key:s.sourceKey||s.y}))];
 
532
  const seriesName = (s: NonNullable<SheetChartPresentation["series"]>[number]) =>
533
  s.label || offeredSeries.find(offer => (offer.sourceKey||offer.y) === s.key)?.label || s.key;
534
  const updateSeries = (key: string, patch: Partial<NonNullable<SheetChartPresentation["series"]>[number]>) =>
@@ -538,9 +586,10 @@ export default function ChartDialog({
538
  [reordered[index],reordered[other]]=[reordered[other],reordered[index]];
539
  setOption("series",reordered);
540
  };
541
- const boundsError = Object.entries(bounds).some(([key,value])=>value!==""&&(!Number.isFinite(Number(value))||((key==="yMajor"||key==="yMinor")&&Number(value)<=0)))
542
  ? "Enter finite bounds and positive units."
543
- : bounds.yMin!==""&&bounds.yMax!==""&&Number(bounds.yMin)>=Number(bounds.yMax) ? "The Y maximum must exceed the minimum." : "";
 
544
  const validGeometry = location && location.col0===location.col1 && location.row0===location.row1
545
  && Number(chartWidth)>=320 && Number(chartWidth)<=2400 && Number(chartHeight)>=240 && Number(chartHeight)<=1600;
546
  const newNameError = destination==="__new__" && (!newName.trim() || [...newName].some(c => "[]:*?/\\\\'".includes(c)) || workbook?.sheets.some(s=>s.name.toLowerCase()===newName.trim().toLowerCase()));
@@ -558,9 +607,11 @@ export default function ChartDialog({
558
  }) : null;
559
  const dataRanges = plan ? [plan.range] : ranges!;
560
  const display = {...presentation, series: configuredSeries};
561
- for (const key of ["yMin","yMax","yMajor","yMinor"] as const) {
562
  if (bounds[key] === "") delete display[key]; else display[key] = Number(bounds[key]);
563
  }
 
 
564
  if (plan) { display.orientation = "rows"; display.headers = "none"; display.categoryLabels = "firstColumn"; }
565
  const next: SheetChartSpec = {
566
  ...chart, id: chart?.id ?? `chart-${crypto.randomUUID()}`, kind, range:dataRanges[0],
@@ -573,8 +624,15 @@ export default function ChartDialog({
573
  else onCreate?.(kind,next.range,plan?.cells);
574
  };
575
 
576
- const rangeField = (
577
- <div className="sheet-chart-fields">
 
 
 
 
 
 
 
578
  <label className="sheet-chart-label" htmlFor={`${titleId}-range`}>Data range</label>
579
  <input
580
  id={`${titleId}-range`}
@@ -595,7 +653,7 @@ export default function ChartDialog({
595
  Enter ranges such as B2:E8 or A1:A8, C1:C8.
596
  </p>
597
  ) : null}
598
- </div>
599
  );
600
 
601
  const kindPicker = <label className="sheet-chart-setting">Chart type<select aria-label="Chart type" value={kind} onChange={event=>setKind(event.target.value as SheetChartSpec["kind"])}>{CHART_KINDS.map(entry=><option key={entry.kind} value={entry.kind}>{entry.label}</option>)}</select></label>;
@@ -611,7 +669,9 @@ export default function ChartDialog({
611
  </div>
612
  <div className="sheet-chart-chooser-body" id={`${titleId}-choices-panel`} role="tabpanel"
613
  aria-labelledby={`${titleId}-choices-${galleryTab}`}>
614
- <div className="sheet-chart-thumbnail-rail" ref={railRef} role="tablist" aria-label="Chart types" aria-orientation="vertical">
 
 
615
  {galleryKinds.map(candidateKind => {
616
  const candidateModel = candidates.find(candidate => candidate.kind === candidateKind)!.model;
617
  const error = range ? chartPreviewError(candidateKind, candidateModel) : "Enter a valid data range.";
@@ -626,17 +686,7 @@ export default function ChartDialog({
626
  </span>}
627
  </button>;
628
  })}
629
- </div>
630
- <div className="sheet-chart-live-preview" id={`${titleId}-live-preview`} role="tabpanel"
631
- aria-labelledby={galleryKinds.includes(kind) ? `${titleId}-kind-${kind}` : undefined}>
632
- {galleryKinds.length ? <>
633
- <h3 className="sheet-chart-live-heading">{CHART_KINDS.find(entry => entry.kind === kind)!.label}</h3>
634
- <p className="sheet-chart-live-description">{previewError || CHART_DESCRIPTIONS[kind]}</p>
635
- {!previewError ? <div className="sheet-chart-live-drawing">
636
- <DrawnChart {...model} kind={kind} presentation={presentation} width={Number(chartWidth)} height={Number(chartHeight)}/>
637
- </div> : null}
638
- </> : <p className="sheet-chart-live-description" role="status">Choose a range with numeric values to see recommendations.</p>}
639
- </div>
640
  </div>
641
  </div>;
642
  const select = <K extends keyof SheetChartPresentation>(label: string,key:K,choices: readonly (readonly [string,string])[]) =>
@@ -645,11 +695,49 @@ export default function ChartDialog({
645
  <label className="sheet-chart-setting">{label}<input aria-label={label} maxLength={160} value={presentation[key]??""} onChange={e=>setOption(key,e.target.value)}/></label>;
646
  const toggle = (label:string,key:"showLegend"|"showAxisTitles"|"showDataLabels") =>
647
  <label className="sheet-chart-check"><input type="checkbox" checked={presentation[key]!==false} onChange={e=>setOption(key,e.target.checked)}/>{label}</label>;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
648
  const resetFormatting = () => {
649
  const defaults=defaultChartPresentation();
650
  setPresentation({...defaults,headers:presentation.headers,categoryLabels:presentation.categoryLabels,orientation:presentation.orientation,
651
  series:configuredSeries.map(s=>({key:s.key,label:s.label,hidden:s.hidden})),ganttMode:presentation.ganttMode,title:presentation.title,xTitle:presentation.xTitle,yTitle:presentation.yTitle,categoryTitle:presentation.categoryTitle});
652
- setBounds({yMin:"",yMax:"",yMajor:"",yMinor:""});
653
  };
654
  const settingsPanel = <div className="sheet-chart-settings">
655
  {section==="Chart"?<>{tab==="range" ? chartGallery : kindPicker}
@@ -666,14 +754,15 @@ export default function ChartDialog({
666
  </details>
667
  </>:null}
668
  {section==="Text"?<>{text("Chart title","title")}{text("X axis title","xTitle")}{text("Y axis title","yTitle")}{text("Category name","categoryTitle")}
669
- {toggle("Show legend","showLegend")}{toggle("Show axis titles","showAxisTitles")}{toggle("Show data labels","showDataLabels")}
670
- {select("Legend position","legendPosition",[["bottom","Bottom"],["top","Top"],["right","Right"]])}
671
- {select("Legend font","legendFont",[["small","Small"],["medium","Medium"],["large","Large"]])}
672
  {select("Axis font","axisFont",[["small","Small"],["medium","Medium"],["large","Large"]])}
673
- <p className="sheet-chart-caption">Charts with two or more series always keep their legend.</p>
674
  </>:null}
675
- {section==="Axes"?<>{["pie","donut","funnel","treemap","polar"].includes(kind)?<p className="sheet-chart-caption">This chart type has no value axis.</p>:<>{(["yMin","yMax","yMajor","yMinor"] as const).filter(key=>!["gauge","radar"].includes(kind)||key==="yMin"||key==="yMax").map((key,i)=><label className="sheet-chart-setting" key={key}>{["Y minimum","Y maximum","Major unit","Minor unit"][i]}<input aria-label={["Y minimum","Y maximum","Major unit","Minor unit"][i]} type="number" step="any" placeholder="Auto" value={bounds[key]} onChange={e=>{const value=e.target.value;setBounds(current=>({...current,[key]:value}));setOption(key,value===""?undefined:Number(value));}}/></label>)}
676
- {select("Display units","displayUnits",[["none","None"],["thousands","Thousands"],["millions","Millions"],["percent","Percent"]])}
 
677
  </>}</>:null}
678
  {section==="Series"?<>{settings.length?settings.map((s,i)=><div className="sheet-chart-series-row" key={s.key}>
679
  <label className="sheet-chart-check"><input type="checkbox" aria-label={`Show ${seriesName(s)}`} checked={!s.hidden} onChange={e=>updateSeries(s.key,{hidden:!e.target.checked})}/></label>
@@ -690,18 +779,40 @@ export default function ChartDialog({
690
  <label className="sheet-chart-setting">Anchor cell<input aria-label="Anchor cell" value={anchor} onChange={e=>setAnchor(e.target.value)}/></label>
691
  <label className="sheet-chart-setting">Width<input aria-label="Width" type="number" min={320} max={2400} step={8} value={chartWidth} onChange={e=>setChartWidth(e.target.value)}/></label>
692
  <label className="sheet-chart-setting">Height<input aria-label="Height" type="number" min={240} max={1600} step={8} value={chartHeight} onChange={e=>setChartHeight(e.target.value)}/></label>
 
 
693
  </>:null}
694
  </div>;
695
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
696
  return (
697
  <BodyPortal>
698
  <div className="lp-dialog-scrim">
699
  <div
700
  ref={panelRef}
701
- // `sheet-chart-dialog` carries no rule of its own and is not meant to: it is the name a
702
- // gate, a screenshot or a person in the inspector can point at. The paint is `.lp-dialog`.
703
  className="lp-dialog sheet-chart-dialog"
704
- style={{ width: section === "Chart" && tab === "range" ? "min(880px, calc(100vw - 32px))" : "min(680px, calc(100vw - 32px))" }}
705
  role="dialog"
706
  aria-modal="true"
707
  aria-labelledby={titleId}
@@ -728,6 +839,11 @@ export default function ChartDialog({
728
  </button>
729
  </div>
730
 
 
 
 
 
 
731
  {section==="Data" && !editing ? (
732
  <div className="sheet-chart-tabs" role="tablist" aria-label="What the chart reads">
733
  {SOURCE_TABS.map((entry) => (
@@ -761,16 +877,47 @@ export default function ChartDialog({
761
  >
762
  {section!=="Data" ? settingsPanel : tab === "range" ? (
763
  <>
764
- {workbook?<label className="sheet-chart-setting">Source worksheet<select aria-label="Source worksheet" value={sourceSheetId} onChange={e=>{setSourceSheetId(e.target.value);setOption("series",[]);}}>{workbook.sheets.map(s=><option key={s.id} value={s.id}>{s.name}</option>)}</select></label>:null}
765
- {rangeField}
766
- {select("Headings","headers",[["auto","Automatic"],["firstRow","First row"],["none","None"]])}
767
- {select("Category labels","categoryLabels",[["auto","Automatic"],["firstColumn","First column"],["none","None"]])}
768
- {select("Series in","orientation",[["columns","Columns"],["rows","Rows"]])}
769
- <button type="button" className="sheet-chart-quiet" onClick={()=>setOption("orientation",presentation.orientation==="rows"?"columns":"rows")}>Switch row / column</button>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
770
  </>
771
  ) : (
772
  <>
773
- <div className="sheet-chart-fields" aria-busy={loading}>
774
  <label className="sheet-chart-label" htmlFor={`${titleId}-db`}>Database</label>
775
  {loading ? (
776
  <div className="sheet-chart-skeleton" />
@@ -819,6 +966,13 @@ export default function ChartDialog({
819
  </>
820
  )}
821
 
 
 
 
 
 
 
 
822
  <label className="sheet-chart-label" htmlFor={`${titleId}-unit`}>Period</label>
823
  <select
824
  id={`${titleId}-unit`}
@@ -843,13 +997,7 @@ export default function ChartDialog({
843
  value={periods}
844
  onChange={(event) => setPeriods(event.target.value)}
845
  />
846
- </div>
847
- {/* The gallery is the same one the cell range tab shows, and the chosen kind is
848
- shared between the two: the source is what the tabs choose, never the picture. */}
849
- <div className="sheet-chart-kindblock">
850
- <span className="sheet-chart-label">Chart type</span>
851
- {kindPicker}
852
- </div>
853
  {/* ⚠ SAID AT THE POINT OF CREATION, because a person who expected only a picture
854
  must not be surprised to find a block of numbers. One sentence, not a
855
  paragraph (DESIGN.md section 4: never over-explain). */}
@@ -861,10 +1009,10 @@ export default function ChartDialog({
861
  {boundsError?<p role="alert" className="sheet-chart-caption">{boundsError}</p>:null}
862
  {!validGeometry?<p role="alert" className="sheet-chart-caption">Choose one anchor cell, width 320 to 2400 and height 240 to 1600.</p>:null}
863
  {newNameError?<p role="alert" className="sheet-chart-caption">Choose a unique, valid sheet name.</p>:null}
864
- {workbook&&tab==="range"&&section!=="Chart"?<details className="sheet-chart-preview"><summary>Preview</summary>
865
- {previewError?<p role="status">{previewError}</p>:<DrawnChart {...model} kind={kind} presentation={presentation} width={600} height={280}/>}
866
- </details>:null}
867
- </div>
868
 
869
  <div className="lp-dialog-actions">
870
  {editing && onDelete ? (
 
43
  // rather than a spinner while the database list is in flight, press feedback that does not change
44
  // layout, reduced motion honoured, and no em dash or en dash in any string that reaches a screen.
45
 
46
+ import { createContext, Fragment, useContext, useEffect, useId, useMemo, useRef, useState } from "react";
47
+ import type { ReactNode } from "react";
48
  import { BodyPortal, useOverlayLayer } from "../customer-grid/OverlaySurface";
49
  // The document's own addresser, in SHEET coordinates. A second spelling of A1 in this file would
50
  // be a second answer to a question the document already answers.
51
  import { addressOf } from "./sheetState";
52
  import { parseRange } from "./rules";
53
+ import type { Cell, SheetChartRange, SheetChartSpec, SheetTab, SheetChartPresentation, SheetChartColor, ChartAxisFormat } from "./types";
54
  import { defaultChartPresentation } from "./types";
55
+ import { chartDataForRange, chartLegendEntries, DrawnChart } from "./SheetChart";
56
  import type { SheetChartData } from "./SheetChart";
57
  import "../styles/wave58/sheet.css";
58
  import "../styles/wave59/chart-dialog.css";
59
 
60
+ /** R-instruction 11: a new chart is born named, so every label is something the user can click and
61
+ * rename. A chart saved before this release keeps whatever titles it had, which is why this is
62
+ * applied at CREATION and never in `defaultChartPresentation` or at render time. */
63
+ const UNTITLED = "Untitled";
64
+ const BOUND_KEYS = ["yMin", "yMax", "yMajor", "yMinor", "xMin", "xMax"] as const;
65
+
66
  /** The page owns the atomic workbook write; isolated legacy mounts retain their old callback. */
67
  export const ChartWorkbookContext = createContext<{
68
  sheets: SheetTab[]; activeSheetId: string;
 
375
  };
376
  }
377
 
378
+ // Database plans keep real period labels but stale values, which the chart treats as empty.
379
+ // Preview-only samples preserve the labels and chart shape without pretending to be real figures.
380
+ const PREVIEW_SAMPLE = [42, 68, 51, 84, 63, 97, 75, 89, 58, 72, 46, 91];
381
+
382
+ export function previewDatabaseCells(plan: DatabaseBlockPlan): Record<string, Cell> {
383
+ const cells = { ...plan.cells };
384
+ let i = 0;
385
+ for (let col = plan.range.col0; col <= plan.range.col1; col += 1) {
386
+ for (let row = plan.range.row0; row <= plan.range.row1; row += 1) {
387
+ const address = addressOf(col, row);
388
+ if (cells[address]?.state === "stale") {
389
+ cells[address] = {
390
+ kind: "literal", state: "typed", text: String(PREVIEW_SAMPLE[i % PREVIEW_SAMPLE.length]),
391
+ };
392
+ i += 1;
393
+ }
394
+ }
395
+ }
396
+ return cells;
397
+ }
398
+
399
 
400
  type SourceTab = "range" | "database";
401
 
 
466
  const [chartHeight, setChartHeight] = useState(String(chart?.geometry?.height ?? 360));
467
  const [section, setSection] = useState(opening.section);
468
  const [galleryTab, setGalleryTab] = useState<"recommended" | "all">(editing || initialKind ? "all" : "recommended");
469
+ const [bounds, setBounds] = useState<Record<string,string>>(() => Object.fromEntries(BOUND_KEYS.map(k=>[k,String(chart?.presentation?.[k]??"")])));
470
  const setOption = <K extends keyof SheetChartPresentation>(key: K, value: SheetChartPresentation[K]) =>
471
  setPresentation(current => ({...current,[key]:value}));
472
+ const setAxis = (axis: "valueAxis" | "categoryAxis", patch: Partial<ChartAxisFormat>) =>
473
+ setOption(axis, { ...(presentation[axis] ?? {}), ...patch });
474
 
475
  const [tab, setTab] = useState<SourceTab>("range");
476
  const [kind, setKind] = useState<SheetChartSpec["kind"]>(opening.kind);
 
536
  const model = candidates.find(candidate => candidate.kind === kind)!.model;
537
  const recommended = useMemo(() => range ? recommendChartKinds(candidates) : [], [candidates,range]);
538
  const previewError = range ? chartPreviewError(kind, model) : "Enter a valid data range.";
539
+ const databasePlan = useMemo(() => tab === "database" ? planDatabaseBlock({
540
+ anchor: landingOf(selection), database, fn, field: field.trim(), unit, periods: Number(periods),
541
+ }) : null, [tab, selection, database, fn, field, unit, periods]);
542
+ const databasePresentation = useMemo<SheetChartPresentation>(() => ({
543
+ ...presentation, orientation: "rows", headers: "none", categoryLabels: "firstColumn",
544
+ }), [presentation]);
545
+ const databaseModel = useMemo(() => databasePlan ? chartDataForRange(
546
+ previewDatabaseCells(databasePlan), databasePlan.range, databasePresentation, [databasePlan.range], kind,
547
+ ) : null, [databasePlan, databasePresentation, kind]);
548
+ const previewModel = tab === "database" && databaseModel ? databaseModel : model;
549
+ const previewPresentation = tab === "database" ? databasePresentation : presentation;
550
+ const previewMessage = tab === "range" ? previewError
551
+ : !database || !databaseModel ? "Choose a database to see a preview." : chartPreviewError(kind, databaseModel);
552
+ const previewNote = previewMessage || (tab === "database"
553
+ ? "Sample values. The chart reads the real figures once the periods land in the sheet."
554
+ : CHART_DESCRIPTIONS[kind]);
555
  const galleryKinds = galleryTab === "recommended" ? recommended : CHART_KINDS.map(entry => entry.kind);
556
  const thumbnailPresentation: SheetChartPresentation = {
557
  ...presentation, showLegend: false, showDataLabels: false, showAxisTitles: false, layout: "compact",
 
568
  railRef.current?.querySelector<HTMLElement>('[aria-selected="true"]')
569
  ?.scrollIntoView({ block: "nearest" });
570
  }, [kind, galleryTab, section, tab]);
571
+ const offeredModel = useMemo(() => chartDataForRange(sourceCells, range ?? seedRange, {...presentation,series:[]}, ranges ?? [seedRange], kind), [sourceCells,range,presentation,ranges,kind]);
572
+ const offeredSeries = offeredModel.series;
573
  const configuredSeries = (presentation.series ?? []).flatMap(setting => {
574
  const offered = offeredSeries.find(s => s.sourceKey === setting.key || s.y === setting.key);
575
  return offered ? [{...setting,key:offered.sourceKey || offered.y}] : [];
576
  });
577
  const settings: NonNullable<SheetChartPresentation["series"]> = [...configuredSeries,
578
  ...offeredSeries.filter(s => !configuredSeries.some(c => c.key === (s.sourceKey||s.y))).map(s => ({key:s.sourceKey||s.y}))];
579
+ const legendEntries = chartLegendEntries(kind, settings.filter(s => !s.hidden).length, offeredModel.rows.length);
580
  const seriesName = (s: NonNullable<SheetChartPresentation["series"]>[number]) =>
581
  s.label || offeredSeries.find(offer => (offer.sourceKey||offer.y) === s.key)?.label || s.key;
582
  const updateSeries = (key: string, patch: Partial<NonNullable<SheetChartPresentation["series"]>[number]>) =>
 
586
  [reordered[index],reordered[other]]=[reordered[other],reordered[index]];
587
  setOption("series",reordered);
588
  };
589
+ const boundsError = BOUND_KEYS.some(key=>bounds[key]!==""&&(!Number.isFinite(Number(bounds[key]))||((key==="yMajor"||key==="yMinor")&&Number(bounds[key])<=0)))
590
  ? "Enter finite bounds and positive units."
591
+ : bounds.yMin!==""&&bounds.yMax!==""&&Number(bounds.yMin)>=Number(bounds.yMax) ? "The Y maximum must exceed the minimum."
592
+ : bounds.xMin!==""&&bounds.xMax!==""&&Number(bounds.xMin)>=Number(bounds.xMax) ? "The X maximum must exceed the minimum." : "";
593
  const validGeometry = location && location.col0===location.col1 && location.row0===location.row1
594
  && Number(chartWidth)>=320 && Number(chartWidth)<=2400 && Number(chartHeight)>=240 && Number(chartHeight)<=1600;
595
  const newNameError = destination==="__new__" && (!newName.trim() || [...newName].some(c => "[]:*?/\\\\'".includes(c)) || workbook?.sheets.some(s=>s.name.toLowerCase()===newName.trim().toLowerCase()));
 
607
  }) : null;
608
  const dataRanges = plan ? [plan.range] : ranges!;
609
  const display = {...presentation, series: configuredSeries};
610
+ for (const key of BOUND_KEYS) {
611
  if (bounds[key] === "") delete display[key]; else display[key] = Number(bounds[key]);
612
  }
613
+ if (!editing) for (const key of ["title", "xTitle", "yTitle"] as const)
614
+ if (!display[key]) display[key] = UNTITLED;
615
  if (plan) { display.orientation = "rows"; display.headers = "none"; display.categoryLabels = "firstColumn"; }
616
  const next: SheetChartSpec = {
617
  ...chart, id: chart?.id ?? `chart-${crypto.randomUUID()}`, kind, range:dataRanges[0],
 
624
  else onCreate?.(kind,next.range,plan?.cells);
625
  };
626
 
627
+ const group = (name: string, body: ReactNode, busy?: boolean) => (
628
+ <section className="sheet-chart-group" aria-label={name} aria-busy={busy}>
629
+ <h3 className="sheet-chart-group-name">{name}</h3>
630
+ <div className="sheet-chart-fields">{body}</div>
631
+ </section>
632
+ );
633
+
634
+ const rangeFieldRows = (
635
+ <>
636
  <label className="sheet-chart-label" htmlFor={`${titleId}-range`}>Data range</label>
637
  <input
638
  id={`${titleId}-range`}
 
653
  Enter ranges such as B2:E8 or A1:A8, C1:C8.
654
  </p>
655
  ) : null}
656
+ </>
657
  );
658
 
659
  const kindPicker = <label className="sheet-chart-setting">Chart type<select aria-label="Chart type" value={kind} onChange={event=>setKind(event.target.value as SheetChartSpec["kind"])}>{CHART_KINDS.map(entry=><option key={entry.kind} value={entry.kind}>{entry.label}</option>)}</select></label>;
 
669
  </div>
670
  <div className="sheet-chart-chooser-body" id={`${titleId}-choices-panel`} role="tabpanel"
671
  aria-labelledby={`${titleId}-choices-${galleryTab}`}>
672
+ {/* [W60-T16] The sentence used to live under the gallery's own preview, which moved out to
673
+ the dialog's right column. An empty tablist is not an answer, so it is said here. */}
674
+ {galleryKinds.length ? <div className="sheet-chart-thumbnail-rail" ref={railRef} role="tablist" aria-label="Chart types" aria-orientation="vertical">
675
  {galleryKinds.map(candidateKind => {
676
  const candidateModel = candidates.find(candidate => candidate.kind === candidateKind)!.model;
677
  const error = range ? chartPreviewError(candidateKind, candidateModel) : "Enter a valid data range.";
 
686
  </span>}
687
  </button>;
688
  })}
689
+ </div> : <p className="sheet-chart-live-description" role="status">Choose a range with numeric values to see recommendations.</p>}
 
 
 
 
 
 
 
 
 
 
690
  </div>
691
  </div>;
692
  const select = <K extends keyof SheetChartPresentation>(label: string,key:K,choices: readonly (readonly [string,string])[]) =>
 
695
  <label className="sheet-chart-setting">{label}<input aria-label={label} maxLength={160} value={presentation[key]??""} onChange={e=>setOption(key,e.target.value)}/></label>;
696
  const toggle = (label:string,key:"showLegend"|"showAxisTitles"|"showDataLabels") =>
697
  <label className="sheet-chart-check"><input type="checkbox" checked={presentation[key]!==false} onChange={e=>setOption(key,e.target.checked)}/>{label}</label>;
698
+ const axisFields = (axis: "valueAxis" | "categoryAxis") => {
699
+ const format = presentation[axis] ?? {};
700
+ const fieldId = (name: string) => `${titleId}-${axis}-${name}`;
701
+ const value = axis === "valueAxis";
702
+ return <>
703
+ {BOUND_KEYS.filter(key => value
704
+ ? key.startsWith("y") && (!["gauge", "radar"].includes(kind) || key === "yMin" || key === "yMax")
705
+ : key.startsWith("x") && ["scatter", "bubble"].includes(kind)).map(key => <Fragment key={key}>
706
+ <label className="sheet-chart-label" htmlFor={fieldId(key)}>{key.endsWith("Min") ? "Minimum" : key.endsWith("Max") ? "Maximum" : key === "yMajor" ? "Major unit" : "Minor unit"}</label>
707
+ <input id={fieldId(key)} type="number" step="any" placeholder="Auto" value={bounds[key]} onChange={event => {
708
+ const next = event.target.value;
709
+ setBounds(current => ({...current, [key]: next}));
710
+ setOption(key, next === "" ? undefined : Number(next));
711
+ }}/>
712
+ </Fragment>)}
713
+ <label className="sheet-chart-label" htmlFor={fieldId("decimals")}>Decimal places</label>
714
+ <input id={fieldId("decimals")} type="number" min={0} max={6} step={1} placeholder="Auto" value={format.decimals ?? ""}
715
+ onChange={event => setAxis(axis, {decimals: event.target.value === "" ? null : Number(event.target.value)})}/>
716
+ <label className="sheet-chart-label" htmlFor={fieldId("format")}>Format</label>
717
+ <select id={fieldId("format")} value={format.format ?? "number"} onChange={event => setAxis(axis, {format: event.target.value as ChartAxisFormat["format"]})}>
718
+ {([["number", "Number"], ["currency", "Currency"], ["percent", "Percent"]] as const).map(([key, name]) => <option key={key} value={key}>{name}</option>)}
719
+ </select>
720
+ <label className="sheet-chart-check"><input type="checkbox" checked={format.thousands !== false}
721
+ onChange={event => setAxis(axis, {thousands: event.target.checked})}/>Thousands separator</label>
722
+ <label className="sheet-chart-check"><input type="checkbox" checked={value ? format.gridlines !== false : format.gridlines === true}
723
+ onChange={event => setAxis(axis, {gridlines: event.target.checked})}/>Gridlines</label>
724
+ <label className="sheet-chart-label" htmlFor={fieldId("angle")}>Label angle</label>
725
+ <select id={fieldId("angle")} value={format.labelAngle ?? 0} onChange={event => setAxis(axis, {labelAngle: Number(event.target.value) as ChartAxisFormat["labelAngle"]})}>
726
+ {[["0", "0 degrees"], ["45", "45 degrees"], ["90", "90 degrees"], ["-45", "Minus 45 degrees"], ["-90", "Minus 90 degrees"]].map(([key, name]) => <option key={key} value={key}>{name}</option>)}
727
+ </select>
728
+ {value ? <>
729
+ <label className="sheet-chart-label" htmlFor={fieldId("units")}>Display units</label>
730
+ <select id={fieldId("units")} value={presentation.displayUnits ?? "none"} onChange={event => setOption("displayUnits", event.target.value as SheetChartPresentation["displayUnits"])}>
731
+ {[["none", "None"], ["thousands", "Thousands"], ["millions", "Millions"], ["percent", "Percent"]].map(([key, name]) => <option key={key} value={key}>{name}</option>)}
732
+ </select>
733
+ </> : null}
734
+ </>;
735
+ };
736
  const resetFormatting = () => {
737
  const defaults=defaultChartPresentation();
738
  setPresentation({...defaults,headers:presentation.headers,categoryLabels:presentation.categoryLabels,orientation:presentation.orientation,
739
  series:configuredSeries.map(s=>({key:s.key,label:s.label,hidden:s.hidden})),ganttMode:presentation.ganttMode,title:presentation.title,xTitle:presentation.xTitle,yTitle:presentation.yTitle,categoryTitle:presentation.categoryTitle});
740
+ setBounds(Object.fromEntries(BOUND_KEYS.map(key => [key, ""])));
741
  };
742
  const settingsPanel = <div className="sheet-chart-settings">
743
  {section==="Chart"?<>{tab==="range" ? chartGallery : kindPicker}
 
754
  </details>
755
  </>:null}
756
  {section==="Text"?<>{text("Chart title","title")}{text("X axis title","xTitle")}{text("Y axis title","yTitle")}{text("Category name","categoryTitle")}
757
+ {legendEntries>=2?toggle("Show legend","showLegend"):null}{toggle("Show axis titles","showAxisTitles")}{toggle("Show data labels","showDataLabels")}
758
+ {legendEntries>=2?select("Legend position","legendPosition",[["bottom","Bottom"],["top","Top"],["right","Right"]]):null}
759
+ {legendEntries>=2?select("Legend font","legendFont",[["small","Small"],["medium","Medium"],["large","Large"]]):null}
760
  {select("Axis font","axisFont",[["small","Small"],["medium","Medium"],["large","Large"]])}
761
+ {legendEntries>=2?<p className="sheet-chart-caption">Charts with two or more series always keep their legend.</p>:null}
762
  </>:null}
763
+ {section==="Axes"?<>{["pie","donut","funnel","treemap","polar"].includes(kind)?<p className="sheet-chart-caption">This chart type has no value axis.</p>:<>
764
+ {group("Value axis", axisFields("valueAxis"))}
765
+ {group("Category axis", axisFields("categoryAxis"))}
766
  </>}</>:null}
767
  {section==="Series"?<>{settings.length?settings.map((s,i)=><div className="sheet-chart-series-row" key={s.key}>
768
  <label className="sheet-chart-check"><input type="checkbox" aria-label={`Show ${seriesName(s)}`} checked={!s.hidden} onChange={e=>updateSeries(s.key,{hidden:!e.target.checked})}/></label>
 
779
  <label className="sheet-chart-setting">Anchor cell<input aria-label="Anchor cell" value={anchor} onChange={e=>setAnchor(e.target.value)}/></label>
780
  <label className="sheet-chart-setting">Width<input aria-label="Width" type="number" min={320} max={2400} step={8} value={chartWidth} onChange={e=>setChartWidth(e.target.value)}/></label>
781
  <label className="sheet-chart-setting">Height<input aria-label="Height" type="number" min={240} max={1600} step={8} value={chartHeight} onChange={e=>setChartHeight(e.target.value)}/></label>
782
+ <label className="sheet-chart-check"><input type="checkbox" aria-label="Lock aspect ratio" checked={presentation.lockAspect === true}
783
+ onChange={e=>setOption("lockAspect", e.target.checked)}/>Lock aspect ratio</label>
784
  </>:null}
785
  </div>;
786
 
787
+ const previewPane = (
788
+ <div
789
+ className="sheet-chart-live-preview"
790
+ id={`${titleId}-live-preview`}
791
+ role="tabpanel"
792
+ aria-label="Chart preview"
793
+ {...(section === "Chart" && tab === "range" && galleryKinds.includes(kind)
794
+ ? { "aria-labelledby": `${titleId}-kind-${kind}` } : {})}
795
+ >
796
+ <h3 className="sheet-chart-live-heading">{CHART_KINDS.find(entry => entry.kind === kind)!.label}</h3>
797
+ <p className="sheet-chart-live-description">{previewNote}</p>
798
+ {previewMessage ? null : (
799
+ <div className="sheet-chart-live-drawing">
800
+ <DrawnChart {...previewModel} kind={kind} presentation={previewPresentation}
801
+ width={Number(chartWidth) || 640} height={Number(chartHeight) || 360}/>
802
+ </div>
803
+ )}
804
+ </div>
805
+ );
806
+
807
  return (
808
  <BodyPortal>
809
  <div className="lp-dialog-scrim">
810
  <div
811
  ref={panelRef}
812
+ // The class scopes the split layout; size stays inline because `.lp-dialog`
813
+ // in wave51/kit.css already sets width.
814
  className="lp-dialog sheet-chart-dialog"
815
+ style={{ width: "min(1040px, calc(100vw - 32px))", height: "min(720px, calc(100dvh - 32px))" }}
816
  role="dialog"
817
  aria-modal="true"
818
  aria-labelledby={titleId}
 
839
  </button>
840
  </div>
841
 
842
+ {/* [W60-T16, R23] The one split: settings scroll on the left, the preview never hides on
843
+ the right. The two strips and the panel below are UNCHANGED and simply sit one level
844
+ deeper; the children keep their old indentation so the move stays readable as a diff. */}
845
+ <div className="sheet-chart-body">
846
+ <div className="sheet-chart-settings-column">
847
  {section==="Data" && !editing ? (
848
  <div className="sheet-chart-tabs" role="tablist" aria-label="What the chart reads">
849
  {SOURCE_TABS.map((entry) => (
 
877
  >
878
  {section!=="Data" ? settingsPanel : tab === "range" ? (
879
  <>
880
+ {workbook ? group("Source", <>
881
+ <label className="sheet-chart-label" htmlFor={`${titleId}-sheet`}>Source worksheet</label>
882
+ <select id={`${titleId}-sheet`} className="sheet-chart-select" value={sourceSheetId}
883
+ onChange={e=>{setSourceSheetId(e.target.value);setOption("series",[]);}}>
884
+ {workbook.sheets.map(s=><option key={s.id} value={s.id}>{s.name}</option>)}
885
+ </select>
886
+ </>) : null}
887
+ {group("Range", rangeFieldRows)}
888
+ {group("Headers and categories", <>
889
+ <label className="sheet-chart-label" htmlFor={`${titleId}-headers`}>Headings</label>
890
+ <select id={`${titleId}-headers`} className="sheet-chart-select" value={presentation.headers ?? ""}
891
+ onChange={e=>setOption("headers",e.target.value as SheetChartPresentation["headers"])}>
892
+ <option value="auto">Automatic</option>
893
+ <option value="firstRow">First row</option>
894
+ <option value="none">None</option>
895
+ </select>
896
+ <label className="sheet-chart-label" htmlFor={`${titleId}-categories`}>Category labels</label>
897
+ <select id={`${titleId}-categories`} className="sheet-chart-select" value={presentation.categoryLabels ?? ""}
898
+ onChange={e=>setOption("categoryLabels",e.target.value as SheetChartPresentation["categoryLabels"])}>
899
+ <option value="auto">Automatic</option>
900
+ <option value="firstColumn">First column</option>
901
+ <option value="none">None</option>
902
+ </select>
903
+ </>)}
904
+ {group("Series orientation", <>
905
+ <label className="sheet-chart-label" htmlFor={`${titleId}-orientation`}>Series in</label>
906
+ <select id={`${titleId}-orientation`} className="sheet-chart-select" value={presentation.orientation ?? ""}
907
+ onChange={e=>setOption("orientation",e.target.value as SheetChartPresentation["orientation"])}>
908
+ <option value="columns">Columns</option>
909
+ <option value="rows">Rows</option>
910
+ </select>
911
+ <span className="sheet-chart-label" aria-hidden="true" />
912
+ <button type="button" className="sheet-chart-switch"
913
+ onClick={()=>setOption("orientation",presentation.orientation==="rows"?"columns":"rows")}>
914
+ Switch row and column
915
+ </button>
916
+ </>)}
917
  </>
918
  ) : (
919
  <>
920
+ {group("Source", <>
921
  <label className="sheet-chart-label" htmlFor={`${titleId}-db`}>Database</label>
922
  {loading ? (
923
  <div className="sheet-chart-skeleton" />
 
966
  </>
967
  )}
968
 
969
+ <label className="sheet-chart-label" htmlFor={`${titleId}-kind`}>Chart type</label>
970
+ <select id={`${titleId}-kind`} className="sheet-chart-select" value={kind}
971
+ onChange={event=>setKind(event.target.value as SheetChartSpec["kind"])}>
972
+ {CHART_KINDS.map(entry=><option key={entry.kind} value={entry.kind}>{entry.label}</option>)}
973
+ </select>
974
+ </>, loading)}
975
+ {group("Range", <>
976
  <label className="sheet-chart-label" htmlFor={`${titleId}-unit`}>Period</label>
977
  <select
978
  id={`${titleId}-unit`}
 
997
  value={periods}
998
  onChange={(event) => setPeriods(event.target.value)}
999
  />
1000
+ </>)}
 
 
 
 
 
 
1001
  {/* ⚠ SAID AT THE POINT OF CREATION, because a person who expected only a picture
1002
  must not be surprised to find a block of numbers. One sentence, not a
1003
  paragraph (DESIGN.md section 4: never over-explain). */}
 
1009
  {boundsError?<p role="alert" className="sheet-chart-caption">{boundsError}</p>:null}
1010
  {!validGeometry?<p role="alert" className="sheet-chart-caption">Choose one anchor cell, width 320 to 2400 and height 240 to 1600.</p>:null}
1011
  {newNameError?<p role="alert" className="sheet-chart-caption">Choose a unique, valid sheet name.</p>:null}
1012
+ </div>{/* .sheet-chart-panel */}
1013
+ </div>{/* .sheet-chart-settings-column */}
1014
+ {previewPane}
1015
+ </div>{/* .sheet-chart-body */}
1016
 
1017
  <div className="lp-dialog-actions">
1018
  {editing && onDelete ? (
web/src/sheet/DrillModal.tsx CHANGED
@@ -56,6 +56,7 @@
56
  import { Suspense, lazy, useCallback, useEffect, useMemo, useRef, useState } from "react";
57
  import { fetchTopicRows, fetchWorkspace } from "../customer-grid/apiBridge";
58
  import type { SurfaceScope } from "../customer-grid/apiBridge";
 
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";
@@ -66,6 +67,7 @@ import { cellForcedFieldKeys, cellViewVisibleKeys } from "./bindingRefs";
66
  import { drillCell } from "./sheetApi";
67
  import type { CellDrill } from "./sheetApi";
68
  import type { BindingDisplay } from "./types";
 
69
 
70
  /**
71
  * ⛔⛔ LAZY, AND THE BUILD IS WHAT SAID SO. A plain `import { LinkGridModal } from
@@ -177,7 +179,7 @@ export type DrillCellScope = (
177
  | { kind: "view"; name: string }
178
  )
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;
@@ -266,15 +268,15 @@ export interface DrillModalProps {
266
  */
267
  onFilterChange?: (addr: string, tree: FilterTree) => void | Promise<void>;
268
  /**
269
- * W56-T24 moved presentation to the Data grid's own switcher. This accepted-but-unused seam stays
270
- * optional so an existing Sheet host does not need a coordinated edit.
271
  */
272
  onDisplayChange?: (addr: string, display: BindingDisplay) => void | Promise<void>;
273
  }
274
 
275
  export default function DrillModal(
276
  {
277
- workbookId, addr, label, onClose, onSettled, cellScope, onFilterChange,
278
  }: DrillModalProps,
279
  ) {
280
  const [drill, setDrill] = useState<CellDrill | null>(null);
@@ -315,6 +317,13 @@ export default function DrillModal(
315
  base: string; tree: FilterTree;
316
  } | null>(null);
317
  const cellFilterTimerRef = useRef<number | null>(null);
 
 
 
 
 
 
 
318
  /** Bumped when a filter change has landed, so the rows are read again. */
319
  const [reloadSeq, setReloadSeq] = useState(0);
320
  /** Fields for the filter sentence and export, fetched once the drill has answered. */
@@ -414,6 +423,12 @@ export default function DrillModal(
414
  const shown = cellScope ?? scopeFromDrill(drill);
415
  const shownKind = shown?.kind ?? "";
416
  const shownTree = shown?.kind === "filter" ? shown.tree : null;
 
 
 
 
 
 
417
  /** The cell's current tree at the instant a delayed grid edit settles. */
418
  const shownTreeRef = useRef<FilterTree | null>(shownTree);
419
  shownTreeRef.current = shownTree;
@@ -503,6 +518,29 @@ export default function DrillModal(
503
  pendingCellFilterRef.current = null;
504
  }, []);
505
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
506
  /**
507
  * ⭐⭐ WHERE THE KEYSTROKE ACTUALLY ARRIVES, WHICH IS NOT WHERE THE SHEET'S UNDO LIVES.
508
  *
@@ -576,7 +614,7 @@ export default function DrillModal(
576
  .map((field) => field.key);
577
  const visibleKeys = cellViewVisibleKeys(
578
  defaultFieldKeys,
579
- [],
580
  forcedFieldKeys,
581
  fields.map((field) => field.key),
582
  identityField?.key ?? "",
@@ -707,6 +745,7 @@ export default function DrillModal(
707
  editable={false}
708
  cellView
709
  cellFields={visibleKeys}
 
710
  // A view-bound cell passes neither prop: its rows remain the saved view's business.
711
  cellFilter={shownTree ?? undefined}
712
  onCellFilterChange={shownKind === "filter" ? settleCellFilter : undefined}
 
56
  import { Suspense, lazy, useCallback, useEffect, useMemo, useRef, useState } from "react";
57
  import { fetchTopicRows, fetchWorkspace } from "../customer-grid/apiBridge";
58
  import type { SurfaceScope } from "../customer-grid/apiBridge";
59
+ import type { CellDisplayChoice } from "../customer-grid/CustomerGrid";
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";
 
67
  import { drillCell } from "./sheetApi";
68
  import type { CellDrill } from "./sheetApi";
69
  import type { BindingDisplay } from "./types";
70
+ import { bindingDisplay } from "./types";
71
 
72
  /**
73
  * ⛔⛔ LAZY, AND THE BUILD IS WHAT SAID SO. A plain `import { LinkGridModal } from
 
179
  | { kind: "view"; name: string }
180
  )
181
  & {
182
+ /** C4: the cell's persisted column choices, independent of any shared View. */
183
  display?: BindingDisplay;
184
  /** The host supplies these from the current binding alongside its filter or saved view. */
185
  aggregateField?: string;
 
268
  */
269
  onFilterChange?: (addr: string, tree: FilterTree) => void | Promise<void>;
270
  /**
271
+ * C4: persist column choices for this cell. The grid reports ordered visibility; this modal
272
+ * settles the edits before calling the Sheet host's binding writer.
273
  */
274
  onDisplayChange?: (addr: string, display: BindingDisplay) => void | Promise<void>;
275
  }
276
 
277
  export default function DrillModal(
278
  {
279
+ workbookId, addr, label, onClose, onSettled, cellScope, onFilterChange, onDisplayChange,
280
  }: DrillModalProps,
281
  ) {
282
  const [drill, setDrill] = useState<CellDrill | null>(null);
 
317
  base: string; tree: FilterTree;
318
  } | null>(null);
319
  const cellFilterTimerRef = useRef<number | null>(null);
320
+ const [cellDisplayDraft, setCellDisplayDraft] = useState<{
321
+ base: string; display: BindingDisplay;
322
+ } | null>(null);
323
+ const cellDisplayTimerRef = useRef<number | null>(null);
324
+ const pendingCellDisplayRef = useRef<{
325
+ addr: string; display: BindingDisplay; report: DrillModalProps["onDisplayChange"];
326
+ } | null>(null);
327
  /** Bumped when a filter change has landed, so the rows are read again. */
328
  const [reloadSeq, setReloadSeq] = useState(0);
329
  /** Fields for the filter sentence and export, fetched once the drill has answered. */
 
423
  const shown = cellScope ?? scopeFromDrill(drill);
424
  const shownKind = shown?.kind ?? "";
425
  const shownTree = shown?.kind === "filter" ? shown.tree : null;
426
+ const shownDisplayKey = JSON.stringify([workbookId, addr, shown?.display ?? null]);
427
+ const cellDisplay = cellDisplayDraft?.base === shownDisplayKey
428
+ ? cellDisplayDraft.display : shown?.display;
429
+ useEffect(() => {
430
+ setCellDisplayDraft((draft) => draft?.base === shownDisplayKey ? draft : null);
431
+ }, [shownDisplayKey]);
432
  /** The cell's current tree at the instant a delayed grid edit settles. */
433
  const shownTreeRef = useRef<FilterTree | null>(shownTree);
434
  shownTreeRef.current = shownTree;
 
518
  pendingCellFilterRef.current = null;
519
  }, []);
520
 
521
+ const flushCellDisplay = useCallback(() => {
522
+ if (cellDisplayTimerRef.current !== null)
523
+ window.clearTimeout(cellDisplayTimerRef.current);
524
+ cellDisplayTimerRef.current = null;
525
+ const pending = pendingCellDisplayRef.current;
526
+ pendingCellDisplayRef.current = null;
527
+ if (pending) void pending.report?.(pending.addr, pending.display);
528
+ }, []);
529
+
530
+ // Mirror the filter's quiet period, but keep presentation edits when the reader closes early.
531
+ // Capture the address and writer together so a later cell cannot receive an earlier edit.
532
+ const settleCellDisplay = useCallback((display: CellDisplayChoice) => {
533
+ const next = bindingDisplay({ display });
534
+ if (!next) return;
535
+ setCellDisplayDraft({ base: shownDisplayKey, display: next });
536
+ pendingCellDisplayRef.current = { addr, display: next, report: onDisplayChange };
537
+ if (cellDisplayTimerRef.current !== null)
538
+ window.clearTimeout(cellDisplayTimerRef.current);
539
+ cellDisplayTimerRef.current = window.setTimeout(flushCellDisplay, 800);
540
+ }, [addr, shownDisplayKey, onDisplayChange, flushCellDisplay]);
541
+
542
+ useEffect(() => () => flushCellDisplay(), [workbookId, addr, flushCellDisplay]);
543
+
544
  /**
545
  * ⭐⭐ WHERE THE KEYSTROKE ACTUALLY ARRIVES, WHICH IS NOT WHERE THE SHEET'S UNDO LIVES.
546
  *
 
614
  .map((field) => field.key);
615
  const visibleKeys = cellViewVisibleKeys(
616
  defaultFieldKeys,
617
+ cellDisplay?.visible ?? [],
618
  forcedFieldKeys,
619
  fields.map((field) => field.key),
620
  identityField?.key ?? "",
 
745
  editable={false}
746
  cellView
747
  cellFields={visibleKeys}
748
+ onCellDisplayChange={settleCellDisplay}
749
  // A view-bound cell passes neither prop: its rows remain the saved view's business.
750
  cellFilter={shownTree ?? undefined}
751
  onCellFilterChange={shownKind === "filter" ? settleCellFilter : undefined}
web/src/sheet/Ribbon.tsx CHANGED
@@ -48,7 +48,7 @@
48
 
49
  import { Children, cloneElement, createContext, isValidElement, useContext, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
50
  import type { KeyboardEvent, MouseEvent as ReactMouseEvent, ReactNode } from "react";
51
- import type { Cell, CellStyle, CellStylePatch, SheetChartSpec, Workbook, SheetPrintSettings } from "./types";
52
  import { AnchoredOverlay } from "../customer-grid/OverlaySurface";
53
  import {
54
  EXPORT_FORMATS,
@@ -168,7 +168,13 @@ export interface RibbonAction {
168
  * every other lane's tree at the merge. Where it is absent the Insert tab renders every control
169
  * DISABLED rather than wired to nothing, which is the fake affordance `canImport` refuses by name.
170
  */
171
- export interface RibbonInsertDoor {
 
 
 
 
 
 
172
  /** The selection as a SHEET-coordinate rectangle, or null when nothing is selected. */
173
  selection: { col0: number; row0: number; col1: number; row1: number } | null;
174
  /** This tab's charts, and the one door that replaces the list. */
 
48
 
49
  import { Children, cloneElement, createContext, isValidElement, useContext, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
50
  import type { KeyboardEvent, MouseEvent as ReactMouseEvent, ReactNode } from "react";
51
+ import type { Cell, CellStyle, CellStylePatch, SheetChartSpec, Workbook, SheetPrintSettings, SheetViewDoor } from "./types";
52
  import { AnchoredOverlay } from "../customer-grid/OverlaySurface";
53
  import {
54
  EXPORT_FORMATS,
 
168
  * every other lane's tree at the merge. Where it is absent the Insert tab renders every control
169
  * DISABLED rather than wired to nothing, which is the fake affordance `canImport` refuses by name.
170
  */
171
+ export interface RibbonInsertDoor extends Partial<SheetViewDoor> {
172
+ /** Fit the selected range using the grid's own visible geometry. */
173
+ zoomToSelection?: () => void;
174
+ /** Tabs the user has hidden, for the View tab's Unhide list. `veryHidden` tabs are NOT here:
175
+ * Excel does not offer them either, and the kit has no door to restore one. */
176
+ hiddenTabs?: readonly { id: string; name: string }[];
177
+ canHideTab?: boolean;
178
  /** The selection as a SHEET-coordinate rectangle, or null when nothing is selected. */
179
  selection: { col0: number; row0: number; col1: number; row1: number } | null;
180
  /** This tab's charts, and the one door that replaces the list. */