fsanyoto commited on
Commit
a93637f
·
verified ·
1 Parent(s): 5df142b

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 +1 -1
  2. VERSION +1 -1
  3. api/ai_enrich.py +6 -3
  4. api/amazon_relational.py +176 -4
  5. api/application_registry.py +72 -0
  6. api/assistant_mirror.py +240 -40
  7. api/connectors_amazon.py +80 -4
  8. api/content_studio.py +638 -0
  9. api/deps.py +225 -17
  10. api/formula_runtime.py +67 -3
  11. api/main.py +34 -2
  12. api/odoo_relational.py +217 -6
  13. api/routes_connectors.py +131 -22
  14. api/routes_external.py +109 -3
  15. api/routes_module_index.py +22 -2
  16. api/routes_odoo_tables.py +256 -40
  17. api/routes_sheet.py +16 -3
  18. api/routes_templates.py +60 -2
  19. platform/core/daily_sales_repair.py +436 -5
  20. platform/core/external_tools.py +22 -5
  21. platform/core/grid_events.py +60 -1
  22. platform/core/perm_scope.py +31 -4
  23. platform/core/registry.py +10 -0
  24. platform/core/sheet_import.py +177 -4
  25. platform/core/sheets.py +62 -1
  26. platform/harness/amazon_client.py +4 -1
  27. platform/harness/amazon_store.py +1126 -80
  28. platform/modules/sheet.py +18 -0
  29. web/public/AIOS_DEPLOY_RECEIPT +1 -1
  30. web/src/apps/contentStudio/ContentStudioApp.tsx +271 -0
  31. web/src/apps/contentStudio/ContentStudioSetup.tsx +83 -0
  32. web/src/apps/contentStudio/DraftPanel.tsx +179 -0
  33. web/src/connectors/ConnectorModal.tsx +13 -6
  34. web/src/connectors/ConnectorsPage.tsx +51 -0
  35. web/src/connectors/OdooConfig.tsx +82 -0
  36. web/src/customer-grid/CustomerGrid.tsx +177 -23
  37. web/src/customer-grid/useGetCellContent.ts +24 -2
  38. web/src/home/HomePage.tsx +179 -34
  39. web/src/home/TemplatePicker.tsx +9 -0
  40. web/src/home/homeModel.ts +8 -0
  41. web/src/sheet/CellContextMenu.tsx +412 -0
  42. web/src/sheet/FormatCellsDialog.tsx +582 -0
  43. web/src/sheet/FormulaBar.tsx +107 -14
  44. web/src/sheet/KeyTips.tsx +120 -25
  45. web/src/sheet/RulesDialog.tsx +370 -99
  46. web/src/sheet/SheetGrid.tsx +513 -153
  47. web/src/sheet/SheetPage.tsx +107 -6
  48. web/src/sheet/a1.ts +42 -0
  49. web/src/sheet/bindingRefs.ts +45 -2
  50. web/src/sheet/borderIcons.tsx +148 -0
RELEASES.json CHANGED
@@ -1,4 +1,4 @@
1
  {
2
- "current": "3dfe966",
3
  "releases": []
4
  }
 
1
  {
2
+ "current": "d11ecc04",
3
  "releases": []
4
  }
VERSION CHANGED
@@ -1 +1 @@
1
- 3dfe966
 
1
+ d11ecc04
api/ai_enrich.py CHANGED
@@ -269,12 +269,15 @@ _SYSTEM = ('You fill in ONE cell of a spreadsheet. Answer with the value only: n
269
  'exactly: UNKNOWN')
270
 
271
 
272
- def _ask(provider, model, prompt, max_tokens, timeout):
273
  """One cell's answer. `(text, tokens_or_None, problem)`; a truthy `problem` means no text.
274
 
275
  ⚠ Both request shapes are `ai_review`'s, changed in exactly two ways: they carry the COLUMN's
276
  ceiling instead of a hardcoded 300, and they read `usage` back.
 
 
277
  """
 
278
  key = (os.environ.get(provider['env']) or '').strip()
279
  if not key:
280
  return '', None, f"{provider['name']} has no key on this deployment"
@@ -284,7 +287,7 @@ def _ask(provider, model, prompt, max_tokens, timeout):
284
  provider['url'], timeout=timeout,
285
  headers={'x-api-key': key, 'anthropic-version': '2023-06-01',
286
  'content-type': 'application/json'},
287
- json={'model': model, 'max_tokens': max_tokens, 'system': _SYSTEM,
288
  'messages': [{'role': 'user', 'content': prompt}]})
289
  if r.status_code >= 400:
290
  return '', None, f"{provider['name']} answered {r.status_code}"
@@ -300,7 +303,7 @@ def _ask(provider, model, prompt, max_tokens, timeout):
300
  provider['url'], timeout=timeout,
301
  headers={'Authorization': f"Bearer {key}", 'Content-Type': 'application/json'},
302
  json={'model': model, 'max_tokens': max_tokens, 'temperature': 0,
303
- 'messages': [{'role': 'system', 'content': _SYSTEM},
304
  {'role': 'user', 'content': prompt}]})
305
  if r.status_code >= 400:
306
  return '', None, f"{provider['name']} answered {r.status_code}"
 
269
  'exactly: UNKNOWN')
270
 
271
 
272
+ def _ask(provider, model, prompt, max_tokens, timeout, system=None):
273
  """One cell's answer. `(text, tokens_or_None, problem)`; a truthy `problem` means no text.
274
 
275
  ⚠ Both request shapes are `ai_review`'s, changed in exactly two ways: they carry the COLUMN's
276
  ceiling instead of a hardcoded 300, and they read `usage` back.
277
+ S67-T41: `system` replaces the one-cell instruction for a caller that is not filling a cell
278
+ (Content Studio's drafts); every existing caller passes nothing and keeps `_SYSTEM`.
279
  """
280
+ system = system or _SYSTEM
281
  key = (os.environ.get(provider['env']) or '').strip()
282
  if not key:
283
  return '', None, f"{provider['name']} has no key on this deployment"
 
287
  provider['url'], timeout=timeout,
288
  headers={'x-api-key': key, 'anthropic-version': '2023-06-01',
289
  'content-type': 'application/json'},
290
+ json={'model': model, 'max_tokens': max_tokens, 'system': system,
291
  'messages': [{'role': 'user', 'content': prompt}]})
292
  if r.status_code >= 400:
293
  return '', None, f"{provider['name']} answered {r.status_code}"
 
303
  provider['url'], timeout=timeout,
304
  headers={'Authorization': f"Bearer {key}", 'Content-Type': 'application/json'},
305
  json={'model': model, 'max_tokens': max_tokens, 'temperature': 0,
306
+ 'messages': [{'role': 'system', 'content': system},
307
  {'role': 'user', 'content': prompt}]})
308
  if r.status_code >= 400:
309
  return '', None, f"{provider['name']} answered {r.status_code}"
api/amazon_relational.py CHANGED
@@ -170,6 +170,116 @@ def mirror_columns(cur, table):
170
  return []
171
 
172
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
173
  def _fields_for(cur, key):
174
  """One preset field per mirror column — the whole schema, derived. See the header."""
175
  cols = mirror_columns(cur, SOURCE[key])
@@ -177,6 +287,12 @@ def _fields_for(cur, key):
177
  return []
178
  names = {c[0] for c in cols}
179
  pinned = PINNED.get(key) if PINNED.get(key) in names else None
 
 
 
 
 
 
180
  out = []
181
  # The identity column goes FIRST, the rest keep the report's own order. A record reached
182
  # through a link is titled by its first field (the record drawer's frame label), and a
@@ -186,9 +302,16 @@ def _fields_for(cur, key):
186
  out.append(_odoo._preset({
187
  "key": name, "label": _label(name), "type": _ftype(name, dtype),
188
  "source": "overlay",
189
- "default": name == pinned or name in _DEFAULT_COLUMNS,
190
  "pinned": name == pinned,
191
  }, flow="amazon_relational"))
 
 
 
 
 
 
 
192
  # ⚠ BOTH SIDES MUST CARRY THE COLUMN, EVERY TIME. A `measured_at_sync` table's header is not
193
  # known until it syncs, so a link to a table that has never run would name a column that does
194
  # not exist. **Absent is a normal state here, not a failure** — which is exactly what lets the
@@ -324,6 +447,10 @@ def grid_source(cur, key):
324
  if kind in ("currency", "int"):
325
  expr = f"TRY_CAST({expr} AS {'DOUBLE' if kind == 'currency' else 'BIGINT'})"
326
  cols[name] = (expr, {"currency": _number, "int": _integer}.get(kind, _text))
 
 
 
 
327
  return {"table": SOURCE[key], "where": "", "id": ident,
328
  "needs_excluded": False, "cols": cols}
329
 
@@ -393,11 +520,16 @@ def _read(cur, key):
393
  return []
394
  quoted = ", ".join(f'"{c}"' for c in cols)
395
  spec = grid_source(cur, key)
396
- rows = cur.execute(f'SELECT {spec["id"]}, {quoted} FROM {SOURCE[key]}').fetchall()
 
 
 
 
 
397
  out = []
398
  for r in rows:
399
  row = {}
400
- for name, val in zip(cols, r[1:]):
401
  # Postgres JSON cannot hold U+0000, and one such byte refused the whole Amazon write.
402
  row[name] = "" if val is None else (val if isinstance(val, (int, float))
403
  else str(val).replace("\x00", ""))
@@ -497,6 +629,43 @@ def plan_fingerprint(cur, built):
497
  return hashlib.sha256(payload.encode("utf-8")).hexdigest()
498
 
499
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
500
  def _lead_with_identity(stored, report, pinned):
501
  """An EXISTING table's fields with its identity column moved first, while the order is still
502
  the report's own.
@@ -564,13 +733,16 @@ def apply_plan(rt, built, username="amazon", today=None):
564
  # Preserve fields a person created or explicitly took over.
565
  current = doc.get(key) or {}
566
  wanted = {f["key"] for f in fields}
 
567
  current["fields"] = _lead_with_identity(
568
  [f for f in current.get("fields", [])
569
- if not (f.get("type") == "link"
570
  and (f.get("automation") or {}).get("flowId") == "amazon_relational"
571
  and not _odoo._ut().user_edited(f)
572
  and f.get("key") not in wanted)],
573
  report_order.get(key) or [], PINNED.get(key))
 
 
574
  stub = isinstance(rows, dict) and rows.get("readThrough") is True
575
  if not stub:
576
  stored = current.get("rows") or {}
 
170
  return []
171
 
172
 
173
+ #: ⭐⭐ S67-T30 (instr 13, R29 / O23) — THE PRODUCT LOOKUPS. Every Amazon database with an ASIN
174
+ #: shows its "Parent ASIN" and "SKU" beside it, and every one with a SKU its "ASIN" and "Parent
175
+ #: ASIN", with no configuration. They are PLAIN TEXT fields whose value the SERVER derives, not
176
+ #: link fields, on purpose: a link renders as a count bubble, is not groupable
177
+ #: (`types.ts:isGroupableField`) and has no SQL binding for a filter (`routes_odoo_tables.
178
+ #: _filter_columns` and `_group_pin` read `spec["cols"]` only). A text field with a `cols`
179
+ #: expression groups, filters and sorts through the machinery every other column already uses.
180
+ #: ⚠ The ASIN / SKU column of a table is the `from_col` of its declared listings link (on `asin1`
181
+ #: / `seller_sku`), so the spec's links are the one statement of which column is which. A table
182
+ #: that carries its own `parent_asin` (pricing, economics) gains no derived Parent ASIN; one that
183
+ #: carries its own SKU or ASIN gains no duplicate of it; listings gains Parent ASIN only.
184
+ #: ⛔ Parent comes from `amazon_store.asin_parents_sql` ALONE (latest catalog, else economics, else
185
+ #: the ASIN itself), never from `amzn_catalog_items` directly: that table keeps older snapshot days
186
+ #: (D-3031) and five own ASINs have no catalog row. SKU and ASIN come from the LATEST listings day
187
+ #: only, because listings keeps one copy per snapshot date.
188
+ LISTINGS = PREFIX + "listings"
189
+ LOOKUP_PARENT, LOOKUP_SKU, LOOKUP_ASIN = "lookup_parent_asin", "lookup_sku", "lookup_asin"
190
+ LOOKUP_KEYS = frozenset((LOOKUP_PARENT, LOOKUP_SKU, LOOKUP_ASIN))
191
+ _LOOKUP_LABELS = {LOOKUP_PARENT: "Parent ASIN", LOOKUP_SKU: "SKU", LOOKUP_ASIN: "ASIN"}
192
+ _LOOKUP_DESCRIPTIONS = {
193
+ LOOKUP_PARENT: ("The parent ASIN of this row's product, from Amazon's catalog, else the "
194
+ "economics report, else the ASIN itself. Click it to open the listing."),
195
+ LOOKUP_SKU: ("Your seller SKUs for this row's ASIN in the latest listings report. "
196
+ "Click it to open the listing."),
197
+ LOOKUP_ASIN: ("The ASIN of this row's SKU in the latest listings report. "
198
+ "Click it to open the listing."),
199
+ }
200
+
201
+
202
+ def _product_columns(key):
203
+ """`(asin_col, sku_col, asin_link_key, sku_link_key)` as the spec declares them for `key`."""
204
+ if key == LISTINGS:
205
+ return "asin1", "seller_sku", None, None # the row IS the listing: Parent ASIN only
206
+ asin = sku = asin_via = sku_via = None
207
+ for edge in connector_spec.edges_for(key):
208
+ if edge["target"] != LISTINGS:
209
+ continue
210
+ if edge["to_col"] == "asin1" and asin is None:
211
+ asin, asin_via = edge["from_col"], edge["key"]
212
+ elif edge["to_col"] == "seller_sku" and sku is None:
213
+ sku, sku_via = edge["from_col"], edge["key"]
214
+ return asin, sku, asin_via, sku_via
215
+
216
+
217
+ def _latest_listings_sql(listing_names):
218
+ """`SELECT sku, asin` over the LATEST listings snapshot day, or None without both columns."""
219
+ if not {"seller_sku", "asin1"} <= set(listing_names):
220
+ return None
221
+ table = SOURCE[LISTINGS]
222
+ latest = (f' AND "_snapshot_date" = (SELECT MAX("_snapshot_date") FROM {table})'
223
+ if "_snapshot_date" in listing_names else "")
224
+ return ("SELECT DISTINCT sku, asin FROM (SELECT TRIM(CAST(seller_sku AS VARCHAR)) AS sku, "
225
+ f"TRIM(CAST(asin1 AS VARCHAR)) AS asin FROM {table} "
226
+ f"WHERE seller_sku IS NOT NULL AND asin1 IS NOT NULL{latest}) "
227
+ "WHERE sku <> '' AND asin <> ''")
228
+
229
+
230
+ def lookups(cur, key, names=None):
231
+ """`[{key, label, after, expr, opens, description}]`: the product lookups `key` gains.
232
+
233
+ `expr` is ONE correlated scalar subquery per lookup, qualified by the mirror table's own name
234
+ (every reader selects `FROM <table>` unaliased), so it binds to the outer row and never to the
235
+ resolver's own `asin`. DuckDB decorrelates it into a single hash join per query, which is what
236
+ keeps a grouped page of a read-through grid set-based rather than per-row. No match is NULL,
237
+ which every reader serialises as a blank cell. Nothing is capped (standing rule 1).
238
+ """
239
+ if names is None:
240
+ names = {name for name, _dtype in mirror_columns(cur, SOURCE[key])}
241
+ asin, sku, asin_via, sku_via = _product_columns(key)
242
+ asin = asin if asin in names else None
243
+ sku = sku if sku in names else None
244
+ if not asin and not sku:
245
+ return []
246
+ listing_names = {name for name, _dtype in mirror_columns(cur, SOURCE[LISTINGS])}
247
+ parents = None if "parent_asin" in names else amazon_store.asin_parents_sql(cur)
248
+ latest = _latest_listings_sql(listing_names)
249
+ table = SOURCE[key]
250
+ out = []
251
+
252
+ def add(lookup_key, after, expr, via):
253
+ if lookup_key in names:
254
+ return
255
+ out.append({"key": lookup_key, "label": _LOOKUP_LABELS[lookup_key], "after": after,
256
+ "expr": expr, "opens": {"via": via} if via else None,
257
+ "description": _LOOKUP_DESCRIPTIONS[lookup_key]})
258
+
259
+ if asin:
260
+ ref = f"TRIM(CAST({table}.{_quoted(asin)} AS VARCHAR))"
261
+ via = asin_via if "asin1" in listing_names else None
262
+ if parents:
263
+ add(LOOKUP_PARENT, asin,
264
+ f"(SELECT _p.parent_asin FROM ({parents}) AS _p WHERE _p.asin = {ref})", via)
265
+ if latest and not sku:
266
+ add(LOOKUP_SKU, asin,
267
+ f"(SELECT string_agg(DISTINCT _l.sku, ', ' ORDER BY _l.sku) "
268
+ f"FROM ({latest}) AS _l WHERE _l.asin = {ref})", via)
269
+ elif sku and latest:
270
+ ref = f"TRIM(CAST({table}.{_quoted(sku)} AS VARCHAR))"
271
+ via = sku_via if "seller_sku" in listing_names else None
272
+ add(LOOKUP_ASIN, sku,
273
+ f"(SELECT string_agg(DISTINCT _l.asin, ', ' ORDER BY _l.asin) "
274
+ f"FROM ({latest}) AS _l WHERE _l.sku = {ref})", via)
275
+ if parents:
276
+ add(LOOKUP_PARENT, sku,
277
+ f"(SELECT string_agg(DISTINCT _p.parent_asin, ', ' ORDER BY _p.parent_asin) "
278
+ f"FROM ({latest}) AS _l JOIN ({parents}) AS _p ON _p.asin = _l.asin "
279
+ f"WHERE _l.sku = {ref})", via)
280
+ return out
281
+
282
+
283
  def _fields_for(cur, key):
284
  """One preset field per mirror column — the whole schema, derived. See the header."""
285
  cols = mirror_columns(cur, SOURCE[key])
 
287
  return []
288
  names = {c[0] for c in cols}
289
  pinned = PINNED.get(key) if PINNED.get(key) in names else None
290
+ # S67-T30: each lookup lands IMMEDIATELY after the column it derives from, shown by default,
291
+ # and the ASIN / SKU column it sits beside is shown by default too (inventory's `msku` was not).
292
+ derived = {}
293
+ for lookup in lookups(cur, key, names):
294
+ derived.setdefault(lookup["after"], []).append(lookup)
295
+ product = {c for c in _product_columns(key)[:2] if c in names}
296
  out = []
297
  # The identity column goes FIRST, the rest keep the report's own order. A record reached
298
  # through a link is titled by its first field (the record drawer's frame label), and a
 
302
  out.append(_odoo._preset({
303
  "key": name, "label": _label(name), "type": _ftype(name, dtype),
304
  "source": "overlay",
305
+ "default": name == pinned or name in _DEFAULT_COLUMNS or name in product,
306
  "pinned": name == pinned,
307
  }, flow="amazon_relational"))
308
+ for lookup in derived.get(name, ()):
309
+ field = {"key": lookup["key"], "label": lookup["label"], "type": "text",
310
+ "source": "overlay", "default": True,
311
+ "description": lookup["description"]}
312
+ if lookup["opens"]:
313
+ field["opens"] = dict(lookup["opens"])
314
+ out.append(_odoo._preset(field, flow="amazon_relational"))
315
  # ⚠ BOTH SIDES MUST CARRY THE COLUMN, EVERY TIME. A `measured_at_sync` table's header is not
316
  # known until it syncs, so a link to a table that has never run would name a column that does
317
  # not exist. **Absent is a normal state here, not a failure** — which is exactly what lets the
 
447
  if kind in ("currency", "int"):
448
  expr = f"TRY_CAST({expr} AS {'DOUBLE' if kind == 'currency' else 'BIGINT'})"
449
  cols[name] = (expr, {"currency": _number, "int": _integer}.get(kind, _text))
450
+ # S67-T30: the product lookups bind like any mirror column, so a filter (`=` a parent), a
451
+ # group (count by parent) and a sort compile against them in SQL with no per-row Python.
452
+ for lookup in lookups(cur, key, names):
453
+ cols[lookup["key"]] = (lookup["expr"], _text)
454
  return {"table": SOURCE[key], "where": "", "id": ident,
455
  "needs_excluded": False, "cols": cols}
456
 
 
520
  return []
521
  quoted = ", ".join(f'"{c}"' for c in cols)
522
  spec = grid_source(cur, key)
523
+ # S67-T30: a stored snapshot carries the same product lookups, computed by the SAME SQL
524
+ # expressions the read-through binding uses, in this one SELECT (never per row).
525
+ derived = [(lookup["key"], lookup["expr"]) for lookup in lookups(cur, key)]
526
+ extra = "".join(f", {expr}" for _k, expr in derived)
527
+ rows = cur.execute(f'SELECT {spec["id"]}, {quoted}{extra} FROM {SOURCE[key]}').fetchall()
528
+ names = cols + [k for k, _expr in derived]
529
  out = []
530
  for r in rows:
531
  row = {}
532
+ for name, val in zip(names, r[1:]):
533
  # Postgres JSON cannot hold U+0000, and one such byte refused the whole Amazon write.
534
  row[name] = "" if val is None else (val if isinstance(val, (int, float))
535
  else str(val).replace("\x00", ""))
 
629
  return hashlib.sha256(payload.encode("utf-8")).hexdigest()
630
 
631
 
632
+ def _place_lookups(stored, fields):
633
+ """An EXISTING table's fields with each NEW product lookup placed right after its source.
634
+
635
+ `_ensure_table_inplace` only appends, so a lookup first planned for a table stored before
636
+ S67-T30 would land at the far end of the grid instead of beside the ASIN or SKU it derives
637
+ from. A lookup already stored keeps its place (a person may have moved it) and only has its
638
+ `opens` bag brought up to date, which `_ensure_table_inplace` does not forward-migrate.
639
+ """
640
+ out = list(stored)
641
+ have = {f.get("key"): i for i, f in enumerate(out)}
642
+ anchor = None
643
+ for field in fields:
644
+ fkey = field.get("key")
645
+ if fkey not in LOOKUP_KEYS:
646
+ anchor = fkey
647
+ continue
648
+ if fkey in have:
649
+ old = out[have[fkey]]
650
+ if (old.get("automation") or {}).get("flowId") == "amazon_relational" \
651
+ and not _odoo._ut().user_edited(old):
652
+ if field.get("opens"):
653
+ old["opens"] = dict(field["opens"])
654
+ else:
655
+ old.pop("opens", None)
656
+ continue
657
+ keys = [f.get("key") for f in out]
658
+ if anchor not in keys:
659
+ continue # no source column stored yet: the append places it
660
+ at = keys.index(anchor) + 1
661
+ while at < len(keys) and keys[at] in LOOKUP_KEYS:
662
+ at += 1 # after any lookup already beside the same source
663
+ out.insert(at, dict(field))
664
+ have = {f.get("key"): i for i, f in enumerate(out)}
665
+ anchor = fkey
666
+ return out
667
+
668
+
669
  def _lead_with_identity(stored, report, pinned):
670
  """An EXISTING table's fields with its identity column moved first, while the order is still
671
  the report's own.
 
733
  # Preserve fields a person created or explicitly took over.
734
  current = doc.get(key) or {}
735
  wanted = {f["key"] for f in fields}
736
+ # S67-T30: a product lookup the mirror no longer supports retires the same way.
737
  current["fields"] = _lead_with_identity(
738
  [f for f in current.get("fields", [])
739
+ if not ((f.get("type") == "link" or f.get("key") in LOOKUP_KEYS)
740
  and (f.get("automation") or {}).get("flowId") == "amazon_relational"
741
  and not _odoo._ut().user_edited(f)
742
  and f.get("key") not in wanted)],
743
  report_order.get(key) or [], PINNED.get(key))
744
+ if current["fields"]:
745
+ current["fields"] = _place_lookups(current["fields"], fields)
746
  stub = isinstance(rows, dict) and rows.get("readThrough") is True
747
  if not stub:
748
  stored = current.get("rows") or {}
api/application_registry.py CHANGED
@@ -16,6 +16,11 @@ APPLICATION_TYPES = ("chart", "route", "map", "timeseries")
16
  APPLICATION_WIZARD_TEMPLATE_KINDS = ("route", "catalog")
17
  FINANCE_TEMPLATE_KIND = "finance"
18
  APPLICATION_TEMPLATE_KINDS = APPLICATION_WIZARD_TEMPLATE_KINDS + (FINANCE_TEMPLATE_KIND,)
 
 
 
 
 
19
  _KEY = "applications_v1"
20
  _MAX = 500
21
 
@@ -65,6 +70,17 @@ _TEMPLATE_CONTRACTS = {
65
  "fieldRoles": [],
66
  "defaultPlacement": {"section": "app", "order": 0},
67
  },
 
 
 
 
 
 
 
 
 
 
 
68
  }
69
 
70
 
@@ -363,6 +379,18 @@ def _template_definition(kind, payload, *, semantic_records=None, field_contract
363
  raise ApplicationError("navPlacement order must be an integer from 0 to 999")
364
  return {"templateKind": kind, "financeKey": finance_key, "deepLink": app["deepLink"],
365
  "navPlacement": {"section": "app", "order": order}}
 
 
 
 
 
 
 
 
 
 
 
 
366
  source = str(payload.get("sourceDatabase") or "").strip()[:120]
367
  if not source:
368
  raise ApplicationError("sourceDatabase is required")
@@ -470,12 +498,49 @@ def _public(app, user, is_admin=False, *, allowed_databases=None, target_databas
470
  "edit", "share", "delete", "duplicate", "star", "default")})
471
  row["starred"] = False
472
  row["isDefault"] = False
 
 
 
 
 
 
473
  target_database = target_database if target_database in compatible else (compatible[0] if compatible else None)
474
  row["openTarget"]={"kind":"application","id":row["id"],"type":row["type"],
475
  "database":target_database}
476
  return row
477
 
478
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
479
  def list_apps(runtime, user, is_admin=False, *, database=None, kind=None, starred=None,
480
  allowed_databases=None):
481
  doc = load(runtime)
@@ -491,6 +556,13 @@ def list_apps(runtime, user, is_admin=False, *, database=None, kind=None, starre
491
  rows.append(_public(app,user,is_admin,allowed_databases=allowed_databases,
492
  target_database=database,
493
  is_default=bool(default_key and doc["defaults"].get(default_key)==app.get("id"))))
 
 
 
 
 
 
 
494
  return sorted(rows,key=lambda x:(str(x.get("updatedAt") or ""),str(x.get("id"))),reverse=True)
495
 
496
 
 
16
  APPLICATION_WIZARD_TEMPLATE_KINDS = ("route", "catalog")
17
  FINANCE_TEMPLATE_KIND = "finance"
18
  APPLICATION_TEMPLATE_KINDS = APPLICATION_WIZARD_TEMPLATE_KINDS + (FINANCE_TEMPLATE_KIND,)
19
+ # S67-T40: Content Studio creates its OWN databases (content_studio.py), so it is never offered to
20
+ # the five-step wizard either; its catalogue POST provisions References + Posts and binds Posts.
21
+ # Appended on its own line so the wizard / Finance separation above reads exactly as S65-T10 pins it.
22
+ CONTENT_STUDIO_TEMPLATE_KIND = "content_studio"
23
+ APPLICATION_TEMPLATE_KINDS = APPLICATION_TEMPLATE_KINDS + (CONTENT_STUDIO_TEMPLATE_KIND,)
24
  _KEY = "applications_v1"
25
  _MAX = 500
26
 
 
70
  "fieldRoles": [],
71
  "defaultPlacement": {"section": "app", "order": 0},
72
  },
73
+ # S67-T40 (R17, R21, O3: one declarative row, no new type). S67-T41 owner correction: the App
74
+ # opens on its OWN surface in the App module (`content_studio.app_link`), like Catalog and
75
+ # Route, so the governed type only has to be a real one; its calendar is time.
76
+ "content_studio": {
77
+ "kind": "content_studio",
78
+ "label": "Content Studio",
79
+ "applicationType": "timeseries",
80
+ "displayMode": "timeseries",
81
+ "fieldRoles": [],
82
+ "defaultPlacement": {"section": "app", "order": 0},
83
+ },
84
  }
85
 
86
 
 
379
  raise ApplicationError("navPlacement order must be an integer from 0 to 999")
380
  return {"templateKind": kind, "financeKey": finance_key, "deepLink": app["deepLink"],
381
  "navPlacement": {"section": "app", "order": order}}
382
+ if kind == CONTENT_STUDIO_TEMPLATE_KIND:
383
+ # Created server-side by content_studio.create right after it made the Posts database, so
384
+ # the binding is the one database it just created; the link can only open that database.
385
+ source = str(payload.get("sourceDatabase") or "").strip()[:120]
386
+ if not source.startswith("ut_"):
387
+ raise ApplicationError("Content Studio binds the Posts database it created.")
388
+ if allowed_databases is not None and source not in set(allowed_databases):
389
+ raise PermissionError("an Application cannot bind a database you cannot open")
390
+ # S67-T41 owner correction: no stored link. `_public` derives the App's own address from
391
+ # its id, so every Studio, including one created before the correction, opens in App.
392
+ return {"templateKind": kind, "sourceDatabase": source,
393
+ "navPlacement": {"section": "app", "order": 0}}
394
  source = str(payload.get("sourceDatabase") or "").strip()[:120]
395
  if not source:
396
  raise ApplicationError("sourceDatabase is required")
 
498
  "edit", "share", "delete", "duplicate", "star", "default")})
499
  row["starred"] = False
500
  row["isDefault"] = False
501
+ if row.get("templateKind") == CONTENT_STUDIO_TEMPLATE_KIND:
502
+ # S67-T41 owner correction: a Studio opens on its own App surface, never in Data. The
503
+ # database-bound edit, share, duplicate and default doors cannot reach an App bound to a
504
+ # user table, so they are off; star and delete stay, routed to `/content-studio/apps`.
505
+ row["deepLink"] = f"/app?studio={row['id']}"
506
+ row["capabilities"].update({key: False for key in ("edit", "share", "duplicate", "default")})
507
  target_database = target_database if target_database in compatible else (compatible[0] if compatible else None)
508
  row["openTarget"]={"kind":"application","id":row["id"],"type":row["type"],
509
  "database":target_database}
510
  return row
511
 
512
 
513
+ #: `core.table_store.RESERVED_MEMBERS`: workspace members that are registries, not users.
514
+ _RESERVED_WORKSPACE_MEMBERS = ("__shared__", "__assigned__", "__audit__")
515
+
516
+
517
+ def dependent_view_counts(runtime, database):
518
+ """S67-T39 / R36: {app_id: number of saved Views on `database` bound to it}, over EVERY
519
+ user's Views in that database's workspace. The Delete App dialog names this count before
520
+ confirm. None when the workspace cannot be read, so the dialog never states a guessed 0.
521
+ """
522
+ from core.view_templates import workspace_key
523
+ key = workspace_key(database)
524
+ if not key:
525
+ return {}
526
+ try:
527
+ doc = runtime.get(key)
528
+ except Exception:
529
+ return None
530
+ counts = {}
531
+ for member, bucket in (doc.items() if isinstance(doc, dict) else ()):
532
+ if member in _RESERVED_WORKSPACE_MEMBERS or not isinstance(bucket, dict):
533
+ continue
534
+ views = bucket.get("views")
535
+ for view in (views.values() if isinstance(views, dict) else ()):
536
+ config = view.get("config") if isinstance(view, dict) else None
537
+ ref = config.get("application") if isinstance(config, dict) else None
538
+ app_id = str(ref.get("id") or "") if isinstance(ref, dict) else ""
539
+ if app_id:
540
+ counts[app_id] = counts.get(app_id, 0) + 1
541
+ return counts
542
+
543
+
544
  def list_apps(runtime, user, is_admin=False, *, database=None, kind=None, starred=None,
545
  allowed_databases=None):
546
  doc = load(runtime)
 
556
  rows.append(_public(app,user,is_admin,allowed_databases=allowed_databases,
557
  target_database=database,
558
  is_default=bool(default_key and doc["defaults"].get(default_key)==app.get("id"))))
559
+ # S67-T39: the dependent-View count rides a DATABASE-filtered read only, and only for rows
560
+ # the caller may delete, so the unfiltered nav read (App home tiles) pays nothing for it.
561
+ deletable = [row for row in rows if row["capabilities"].get("delete")]
562
+ if database and deletable:
563
+ counts = dependent_view_counts(runtime, database)
564
+ for row in deletable:
565
+ row["dependentViews"] = None if counts is None else counts.get(row["id"], 0)
566
  return sorted(rows,key=lambda x:(str(x.get("updatedAt") or ""),str(x.get("id"))),reverse=True)
567
 
568
 
api/assistant_mirror.py CHANGED
@@ -28,6 +28,15 @@ that need them. A module-level import either way is a cycle at startup.
28
  """
29
 
30
 
 
 
 
 
 
 
 
 
 
31
  class MirrorRefusal(Exception):
32
  """A named, fail-closed refusal with the status and code `deps` should raise it as.
33
 
@@ -49,9 +58,14 @@ def _rot():
49
  return routes_odoo_tables
50
 
51
 
52
- def open_cursor(session):
53
  """`(cursor, MirrorRefusal | None)` for THIS session's tenant. Exactly one is None.
54
 
 
 
 
 
 
55
  ⛔ THE TWO FAILURES ARE NOT THE SAME FAILURE and the statuses differ, exactly as they do on
56
  the grid door. `_mirror_cur` has already consumed `DatastoreMismatch` and hands it back as a
57
  sentence, so a bare `RuntimeError` escaping it means the mirror is completing its first sync
@@ -61,7 +75,7 @@ def open_cursor(session):
61
  """
62
  rot = _rot()
63
  try:
64
- cur, mismatch = rot._mirror_cur(session)
65
  except RuntimeError as exc:
66
  return None, MirrorRefusal(503, "assistant_store_not_ready", str(exc))
67
  except Exception as exc: # noqa: BLE001
@@ -118,8 +132,26 @@ def is_bound(cur, table_key):
118
  """
119
  from harness import datastore
120
  try:
121
- spec = _rot()._sources().get(str(table_key or ""))
122
- if not spec:
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
123
  return False
124
  aliases = dict(spec.get("tables") or {})
125
  if spec.get("table"):
@@ -129,8 +161,13 @@ def is_bound(cur, table_key):
129
  return False
130
 
131
 
132
- def declared_fields(table_key):
133
- """`mk_fields()` for one connected grid, or None when this key is not a connected Odoo grid.
 
 
 
 
 
134
 
135
  ⭐ THE STABLE MIRROR CONTRACT, NOT THE STORED DEFINITION. `odoo_relational.apply_plan` built
136
  each table's stored `fields` from this same function, so reading it directly is reading the
@@ -142,10 +179,20 @@ def declared_fields(table_key):
142
  if key == str(table_key or ""):
143
  return [dict(field) for field in (mk_fields() or [])
144
  if isinstance(field, dict) and field.get("key")]
145
- return None
 
 
 
 
 
 
 
 
 
 
146
 
147
 
148
- def answerable_fields(table_key, spec):
149
  """The declared field contract INTERSECTED with the columns the mirror can actually express.
150
 
151
  ⛔ THE INTERSECTION IS THE POINT, and dropping it would be the quiet defect. A declared field
@@ -155,7 +202,8 @@ def answerable_fields(table_key, spec):
155
  refused - a wrong answer with nothing on screen saying so. Left out, `deps` answers a request
156
  for it with a loud `assistant_unknown_field`.
157
  """
158
- fields = declared_fields(table_key)
 
159
  if fields is None:
160
  return None
161
  cols = set((spec or {}).get("cols") or ())
@@ -197,30 +245,14 @@ def _compiled(nodes, conj, columns, *, code, subject, rot):
197
  return pred
198
 
199
 
200
- def read_rows(session, table_key, cur, spec, fields, *, wall_tree=None, filter_tree=None,
201
- filter_keys=None):
202
- """Every permitted row of a mirror-served grid, or a refusal that names its cause.
203
-
204
- Returns `(rows, stamp, total)`. `rows` are FULL canonical rows in `scoped_pool`'s shape
205
- (`{pid, **cells}`), sorted by pid.
206
 
207
- ⛔ NO TRUNCATION, EVER, AND THAT IS WHY THIS REFUSES RATHER THAN PAGES. Standing rule 1: a
208
- connector's records get no cap, and a limit that genuinely cannot be removed must be REPORTED
209
- with its cause and a recommended fix, never silently enforced. `routes_query._system_prompt`
210
- states `PERMISSION-FILTERED RECORD COUNT: {len(records)}` to the model and the server computes
211
- every aggregate from those same records, so a short set does not produce a smaller answer, it
212
- produces a confidently WRONG one with nothing on screen saying so. `whole_pool` one file over
213
- already settled this policy in the same words: REFUSE, NEVER TRIM.
214
-
215
- ⛔ FULL CANONICAL ROWS, NOT THE PROJECTION. `deps.assistant_read_scope` runs the row wall and
216
- the field projection in Python AFTER this returns. Hand it a row missing a column the wall
217
- names and `filter_eval` reads `None` there and its verdict changes, so the belt-and-braces
218
- pass would quietly disagree with the pushdown it is meant to double-check.
219
  """
220
- from harness import datastore
221
- rot = _rot()
222
  fe = rot._fe()
223
-
224
  cols = rot._filter_columns(spec, fields)
225
 
226
  # ── the administrator's wall, compiled FIRST and pushed down ──────────────────────────────
@@ -267,23 +299,191 @@ def read_rows(session, table_key, cur, spec, fields, *, wall_tree=None, filter_t
267
  where = f"({where}) AND {pred.sql}" if where else pred.sql
268
  params.extend(pred.params)
269
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
270
  # ⚠ EXACTLY ONE of `table`/`from_sql` - `window` raises if both or neither arrive, so the
271
  # spec's own shape decides and a malformed spec fails loudly instead of serving a wrong FROM.
272
  select = ", ".join(f'{expr} AS "{key}"' for key, (expr, _c) in spec["cols"].items())
273
  frm = {"from_sql": spec["from_sql"]} if spec.get("from_sql") else {"table": spec["table"]}
274
- win = datastore.window(select=f'{spec["id"]} AS "_pid", {select}',
275
- where=where, params=tuple(params), order_by=spec["id"],
276
- limit=datastore.WINDOW_MAX, cur=cur, **frm)
277
- if win["total"] > len(win["rows"]):
 
 
 
 
 
 
 
 
 
278
  raise MirrorRefusal(
279
  409, "assistant_source_too_large",
280
- f"this database matches {win['total']:,} rows for that question, and the assistant "
281
- f"reads a connected database in one pass of at most "
282
- f"{datastore.WINDOW_MAX:,} rows, so answering now would mean counting only part of "
283
- f"them and reporting the total as if it were whole. Narrow it with a filter and ask "
284
- f"again")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
285
 
286
- stamp = rot.mirror_stamp(spec, cur, table_key, getattr(session, "runtime", None))
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
287
  rows = rot._pool_from_window(spec, win, stamp=stamp)
288
  rows.sort(key=lambda row: row["pid"])
289
  return rows, stamp, int(win["total"])
 
28
  """
29
 
30
 
31
+ #: ⭐ S67-T33: the most rows ONE assistant answer materialises in this process. Not a cap on what
32
+ #: the connector may hold (rule 1: the read walks every row up to here, never a 5,000-row window):
33
+ #: it is the memory bound of computing an answer in Python. MEASURED on staging, 2026-09-28: an
34
+ #: unbounded read of one Amazon grid grew this process past 15 GB before it was stopped, which is
35
+ #: the Space's whole memory. Past it, the read REFUSES BY NAME with the cause and the fix (rule 1's
36
+ #: second sentence); server-side aggregates over larger tables are S67-T34 (D-2631).
37
+ ASSISTANT_READ_MAX = 200_000
38
+
39
+
40
  class MirrorRefusal(Exception):
41
  """A named, fail-closed refusal with the status and code `deps` should raise it as.
42
 
 
58
  return routes_odoo_tables
59
 
60
 
61
+ def open_cursor(session, table_key=None):
62
  """`(cursor, MirrorRefusal | None)` for THIS session's tenant. Exactly one is None.
63
 
64
+ ⭐ S67-T33: `table_key` CHOOSES THE CURSOR BY THE TABLE'S OWN SOURCE, through the grid's
65
+ `_table_cursor` (reached via `_mirror_cur`). An Amazon grid asserts the tenant and opens its
66
+ own mirror without the Odoo first-sync gate, exactly as the grid door has since be3edb6e, so
67
+ the assistant no longer answers 503 for Amazon while Odoo is still backfilling.
68
+
69
  ⛔ THE TWO FAILURES ARE NOT THE SAME FAILURE and the statuses differ, exactly as they do on
70
  the grid door. `_mirror_cur` has already consumed `DatastoreMismatch` and hands it back as a
71
  sentence, so a bare `RuntimeError` escaping it means the mirror is completing its first sync
 
75
  """
76
  rot = _rot()
77
  try:
78
+ cur, mismatch = rot._mirror_cur(session, table_key)
79
  except RuntimeError as exc:
80
  return None, MirrorRefusal(503, "assistant_store_not_ready", str(exc))
81
  except Exception as exc: # noqa: BLE001
 
132
  """
133
  from harness import datastore
134
  try:
135
+ rot = _rot()
136
+ key = str(table_key or "")
137
+ spec = rot._sources().get(key)
138
+ if not spec and key.startswith("ut_amzn_"):
139
+ # S67-T33: a registry built before the Amazon mirror loaded holds no Amazon key.
140
+ # `_source_for` and `_materialised_table` both learn them on demand; so must this.
141
+ rot._learn_amazon_sources()
142
+ spec = rot.GRID_SOURCES.get(key)
143
+ if not spec:
144
+ # A dynamically sized Amazon snapshot is admitted per key by the grid door, not by
145
+ # the provider build, so the registry can lack a key the grid serves (measured on
146
+ # staging: `ut_amzn_fba_inventory` listed unanswerable, then answered). Ask the
147
+ # provider's own per-key resolver, exactly as `require_amazon_mirror` does, without
148
+ # admitting it (the read path admits it through that same door).
149
+ import amazon_relational as amazon
150
+ if key not in amazon.SOURCE:
151
+ return False
152
+ current = amazon.grid_source(cur, key) or {}
153
+ return bool(current) and not current.get("missing")
154
+ if not spec or spec.get("missing"):
155
  return False
156
  aliases = dict(spec.get("tables") or {})
157
  if spec.get("table"):
 
161
  return False
162
 
163
 
164
+ def declared_fields(table_key, definition=None):
165
+ """`mk_fields()` for one connected grid, or None when this key is not a connected grid.
166
+
167
+ ⭐ S67-T33: THE SAME FALLBACK THE GRID TAKES (`routes_odoo_tables._compiled_read`). A key that
168
+ is not one of `odoo_relational.TABLES` but IS a registered read-through source (an Amazon grid,
169
+ a generated `ut_odoo_model_*` table) answers from its stored definition's `fields`. Before
170
+ this, those databases were listed as answerable and then refused 409 on every read.
171
 
172
  ⭐ THE STABLE MIRROR CONTRACT, NOT THE STORED DEFINITION. `odoo_relational.apply_plan` built
173
  each table's stored `fields` from this same function, so reading it directly is reading the
 
179
  if key == str(table_key or ""):
180
  return [dict(field) for field in (mk_fields() or [])
181
  if isinstance(field, dict) and field.get("key")]
182
+ key = str(table_key or "")
183
+ if not isinstance(definition, dict) or not key.startswith("ut_"):
184
+ return None
185
+ try:
186
+ if _rot()._materialised_table(key):
187
+ return None
188
+ except Exception: # noqa: BLE001
189
+ return None
190
+ fields = [dict(field) for field in (definition.get("fields") or [])
191
+ if isinstance(field, dict) and field.get("key")]
192
+ return fields or None
193
 
194
 
195
+ def answerable_fields(table_key, spec, fields=None):
196
  """The declared field contract INTERSECTED with the columns the mirror can actually express.
197
 
198
  ⛔ THE INTERSECTION IS THE POINT, and dropping it would be the quiet defect. A declared field
 
202
  refused - a wrong answer with nothing on screen saying so. Left out, `deps` answers a request
203
  for it with a loud `assistant_unknown_field`.
204
  """
205
+ if fields is None:
206
+ fields = declared_fields(table_key)
207
  if fields is None:
208
  return None
209
  cols = set((spec or {}).get("cols") or ())
 
245
  return pred
246
 
247
 
248
+ def _predicate(rot, spec, fields, wall_tree, filter_tree, filter_keys):
249
+ """`(where, params, cols)`: the ONE compiled predicate every mirror read runs. S67-T34.
 
 
 
 
250
 
251
+ Extracted verbatim from `read_rows` so the row walk, the page read and the server-side
252
+ aggregate run the SAME wall and the SAME caller filter, compiled once, by the grid's compiler.
253
+ Three readers with one predicate cannot disagree about which rows the caller may see.
 
 
 
 
 
 
 
 
 
254
  """
 
 
255
  fe = rot._fe()
 
256
  cols = rot._filter_columns(spec, fields)
257
 
258
  # ── the administrator's wall, compiled FIRST and pushed down ──────────────────────────────
 
299
  where = f"({where}) AND {pred.sql}" if where else pred.sql
300
  params.extend(pred.params)
301
 
302
+ return where, params, cols
303
+
304
+
305
+ def read_rows(session, table_key, cur, spec, fields, *, wall_tree=None, filter_tree=None,
306
+ filter_keys=None, defn=None):
307
+ """Every permitted row of a mirror-served grid, or a refusal that names its cause.
308
+
309
+ Returns `(rows, stamp, total)`. `rows` are FULL canonical rows in `scoped_pool`'s shape
310
+ (`{pid, **cells}`), sorted by pid.
311
+
312
+ ⛔ NO TRUNCATION, EVER, AND THAT IS WHY THIS REFUSES RATHER THAN PAGES. Standing rule 1: a
313
+ connector's records get no cap, and a limit that genuinely cannot be removed must be REPORTED
314
+ with its cause and a recommended fix, never silently enforced. `routes_query._system_prompt`
315
+ states `PERMISSION-FILTERED RECORD COUNT: {len(records)}` to the model and the server computes
316
+ every aggregate from those same records, so a short set does not produce a smaller answer, it
317
+ produces a confidently WRONG one with nothing on screen saying so. `whole_pool` one file over
318
+ already settled this policy in the same words: REFUSE, NEVER TRIM.
319
+
320
+ ⛔ FULL CANONICAL ROWS, NOT THE PROJECTION. `deps.assistant_read_scope` runs the row wall and
321
+ the field projection in Python AFTER this returns. Hand it a row missing a column the wall
322
+ names and `filter_eval` reads `None` there and its verdict changes, so the belt-and-braces
323
+ pass would quietly disagree with the pushdown it is meant to double-check.
324
+ """
325
+ from harness import datastore
326
+ rot = _rot()
327
+ where, params, _cols = _predicate(rot, spec, fields, wall_tree, filter_tree, filter_keys)
328
+
329
  # ⚠ EXACTLY ONE of `table`/`from_sql` - `window` raises if both or neither arrive, so the
330
  # spec's own shape decides and a malformed spec fails loudly instead of serving a wrong FROM.
331
  select = ", ".join(f'{expr} AS "{key}"' for key, (expr, _c) in spec["cols"].items())
332
  frm = {"from_sql": spec["from_sql"]} if spec.get("from_sql") else {"table": spec["table"]}
333
+ # ⭐⭐ S67-T33 / STANDING RULE 1: EVERY ROW, NOT THE FIRST 5,000. The single `WINDOW_MAX`
334
+ # pass this replaced refused any connected database past 5,000 matching rows, which is a cap
335
+ # on a connector's records. The read now walks the whole predicate in `WINDOW_MAX` pages,
336
+ # KEYSET-paged on the spec's own id (the order the pass already used), so a deep page costs
337
+ # one index seek rather than an OFFSET walk. The keyset bound is a pagination cursor, not a
338
+ # user condition: every condition above still comes from the grid's compiler.
339
+ # ⛔ STILL NEVER A PARTIAL ANSWER: the first page's `total` is the population, and a walk that
340
+ # ends anywhere else (the mirror resynced mid-read) refuses by name rather than answering short.
341
+ first = datastore.window(select=f'{spec["id"]} AS "_pid", {select}',
342
+ where=where, params=tuple(params), order_by=spec["id"],
343
+ limit=datastore.WINDOW_MAX, cur=cur, **frm)
344
+ total = int(first["total"])
345
+ if total > ASSISTANT_READ_MAX:
346
  raise MirrorRefusal(
347
  409, "assistant_source_too_large",
348
+ f"this database matches {total:,} rows for that question, and one assistant answer "
349
+ f"is computed over at most {ASSISTANT_READ_MAX:,} rows so that a single question "
350
+ f"cannot exhaust the server's memory. Answering over part of them would report a "
351
+ f"wrong total, so it is refused instead. Narrow it with a filter (for example a date "
352
+ f"range) and ask again, or ask for totals as aggregates, which the server computes "
353
+ f"over every row")
354
+ got = list(first["rows"])
355
+ page = list(first["rows"])
356
+ while len(got) < total and len(page) >= datastore.WINDOW_MAX:
357
+ last = page[-1][0]
358
+ more_where = f"({where}) AND {spec['id']} > ?" if where else f"{spec['id']} > ?"
359
+ nxt = datastore.window(select=f'{spec["id"]} AS "_pid", {select}',
360
+ where=more_where, params=tuple(params) + (last,),
361
+ order_by=spec["id"], limit=datastore.WINDOW_MAX, cur=cur, **frm)
362
+ page = list(nxt["rows"])
363
+ if not page:
364
+ break
365
+ got.extend(page)
366
+ if len(got) != total:
367
+ raise MirrorRefusal(
368
+ 409, "assistant_source_changed",
369
+ f"this database changed while it was being read ({len(got):,} rows read against "
370
+ f"{total:,} counted), so the answer would not describe one consistent set of rows. "
371
+ f"Ask again once its connector sync has finished")
372
+ win = {**first, "rows": got, "total": total}
373
+
374
+ # S67-T33: the caller's rows-free definition is LENT, as the grid lends it, so the stamp does
375
+ # not re-read the whole tenant document (measured about 3 s a question on staging).
376
+ stamp = rot.mirror_stamp(spec, cur, table_key, getattr(session, "runtime", None),
377
+ defn=defn if isinstance(defn, dict) else None)
378
+ rows = rot._pool_from_window(spec, win, stamp=stamp)
379
+ rows.sort(key=lambda row: row["pid"])
380
+ return rows, stamp, int(win["total"])
381
+
382
 
383
+ #: The connector's function names mapped onto the grid's aggregate compiler (`filter_sql`).
384
+ _GRID_AGG = {"sum": "sum", "avg": "average", "count_distinct": "count_distinct"}
385
+
386
+
387
+ def _json_value(rot, value):
388
+ """A DuckDB aggregate result as plain JSON: a number through the grid's `_agg_number`, a
389
+ date or timestamp as its ISO text, anything else as is. Never a substituted 0."""
390
+ if value is None:
391
+ return None
392
+ if isinstance(value, (int, float)) and not isinstance(value, bool):
393
+ return rot._agg_number(value)
394
+ iso = getattr(value, "isoformat", None)
395
+ if callable(iso):
396
+ return iso()
397
+ try:
398
+ from decimal import Decimal
399
+ if isinstance(value, Decimal):
400
+ return rot._agg_number(value)
401
+ except Exception: # noqa: BLE001
402
+ pass
403
+ return value
404
+
405
+
406
+ def aggregate(session, table_key, cur, spec, fields, specs, *, wall_tree=None,
407
+ filter_tree=None, filter_keys=None):
408
+ """Server-side aggregates over EVERY permitted row, in SQL. S67-T34 (D-616, D-2631).
409
+
410
+ Returns `(values, total)`: `values` is `[{fn, field?, value}]` in `specs` order, `total` the
411
+ count of rows the permitted predicate matches, from `datastore.window`'s own count statement
412
+ over the SAME `where` as the aggregates beside it (the grid's `_aggregate_over` contract).
413
+
414
+ ⛔⛔ THE PERMISSION FILTER IS INSIDE THE QUERY. `_predicate` compiles the administrator's wall
415
+ and the caller's filter with the grid's compiler, so a sum over a million-row table runs over
416
+ exactly the rows this caller may read and no row is pulled into Python to compute it. There
417
+ is no row ceiling here (rule 1): the answer is a handful of numbers whatever the table size.
418
+
419
+ ⛔ AN AGGREGATE MAY NAME ONLY A VISIBLE FIELD. `filter_keys` is the caller's visible list, and
420
+ a field outside it has no expression here at all, so a sum over a hidden column cannot be
421
+ built (the caller's `_normalise_aggregates` has already refused it by name).
422
+ """
423
+ from harness import datastore
424
+ rot = _rot()
425
+ where, params, cols = _predicate(rot, spec, fields, wall_tree, filter_tree, filter_keys)
426
+ visible = set(filter_keys) if filter_keys is not None else set(cols)
427
+ fs = rot._fs()
428
+ proj, slots = [], []
429
+ for item in specs or ():
430
+ fn, field = item.get("fn"), item.get("field")
431
+ if field is None:
432
+ slots.append(None) # count(*): the window's own total
433
+ continue
434
+ col = cols.get(field) if field in visible else None
435
+ if col is None:
436
+ raise MirrorRefusal(400, "assistant_unknown_field",
437
+ "every requested field must be readable in this database")
438
+ if fn in {"sum", "avg"} and col["type"] not in fs.NUMERIC_TYPES:
439
+ raise MirrorRefusal(400, "query_aggregate_type",
440
+ "sum and avg require a readable numeric field.")
441
+ if fn in _GRID_AGG:
442
+ expr = fs.aggregate_sql(col, _GRID_AGG[fn])
443
+ elif fn in {"min", "max"}:
444
+ expr = (fs.aggregate_sql(col, fn) if col["type"] in fs.NUMERIC_TYPES
445
+ else f"{fn}({col['sql']})")
446
+ elif fn == "count":
447
+ expr = f"count({col['sql']})"
448
+ else:
449
+ raise MirrorRefusal(400, "query_aggregates_invalid",
450
+ "That aggregate is not available.")
451
+ slots.append(len(proj))
452
+ proj.append(f'{expr} AS "a{len(proj)}"')
453
+ frm = {"from_sql": spec["from_sql"]} if spec.get("from_sql") else {"table": spec["table"]}
454
+ win = datastore.window(select=(", ".join(proj) or "1"), where=where, params=tuple(params),
455
+ order_by="1", limit=1, cur=cur, **frm)
456
+ row = (win["rows"] or [()])[0]
457
+ total = int(win["total"])
458
+ out = []
459
+ for item, slot in zip(specs or (), slots):
460
+ value = total if slot is None else (_json_value(rot, row[slot]) if slot < len(row)
461
+ else None)
462
+ out.append({**item, "value": value})
463
+ return out, total
464
+
465
+
466
+ def read_page(session, table_key, cur, spec, fields, *, offset, limit, wall_tree=None,
467
+ filter_tree=None, filter_keys=None, defn=None):
468
+ """ONE page of the permitted rows, paged IN SQL, in pid order. S67-T34 (rule 1).
469
+
470
+ Returns `(rows, stamp, total)` in `read_rows`'s shape. This is how a table past
471
+ `ASSISTANT_READ_MAX` still answers its rows: the page is `LIMIT/OFFSET` over the same
472
+ predicate `read_rows` runs, so only `limit` rows ever reach this process, and `total` is the
473
+ population that predicate matches. It carries no sort other than the pid; a caller asking for
474
+ one past the ceiling is refused by name upstream, because sorting a million rows in Python
475
+ is the memory failure the ceiling exists to prevent.
476
+ """
477
+ from harness import datastore
478
+ rot = _rot()
479
+ where, params, _cols = _predicate(rot, spec, fields, wall_tree, filter_tree, filter_keys)
480
+ select = ", ".join(f'{expr} AS "{key}"' for key, (expr, _c) in spec["cols"].items())
481
+ frm = {"from_sql": spec["from_sql"]} if spec.get("from_sql") else {"table": spec["table"]}
482
+ win = datastore.window(select=f'{spec["id"]} AS "_pid", {select}', where=where,
483
+ params=tuple(params), order_by=spec["id"], offset=int(offset),
484
+ limit=int(limit), cur=cur, **frm)
485
+ stamp = rot.mirror_stamp(spec, cur, table_key, getattr(session, "runtime", None),
486
+ defn=defn if isinstance(defn, dict) else None)
487
  rows = rot._pool_from_window(spec, win, stamp=stamp)
488
  rows.sort(key=lambda row: row["pid"])
489
  return rows, stamp, int(win["total"])
api/connectors_amazon.py CHANGED
@@ -49,11 +49,80 @@ class AmazonStatusSafetyError(ValueError):
49
  """A status response contains a forbidden credential shape."""
50
 
51
 
52
- def status_payload_has_secret(serialized_payload):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
53
  """Scan serialized JSON for C2's credential keys, token shapes and oversized values.
54
 
55
  Pure and usable without a server. Invalid JSON is unsafe too; never echo rejected content.
56
  The credential key roster is the same one the connector accepts at connect time.
 
57
  """
58
  import json
59
  import re
@@ -73,10 +142,11 @@ def status_payload_has_secret(serialized_payload):
73
  elif isinstance(value, list):
74
  pending.extend(value)
75
  elif isinstance(value, str):
76
- if (len(value) > 512 or 'Atzr|' in value
77
  or re.search(r'\bbearer\s+\S+', value, flags=re.IGNORECASE)):
78
  return True
79
- elif value is not None and len(str(value)) > 512:
 
80
  return True
81
  return False
82
 
@@ -162,7 +232,13 @@ def sync_state(rt, tenant_key, *, cadence_seconds=None, now=None):
162
  row["syncCause"] = cause
163
  cause = cause[:budget - 3].rsplit(" ", 1)[0] + "..."
164
  row["unknownCause"] = " ".join(part for part in (cause, purge_message) if part)
165
- return assert_safe_status(status)
 
 
 
 
 
 
166
 
167
  declared = {name: {"rowsLoaded": None, "declared": True, "unknownCause": spec["reason"]}
168
  for name, spec in DECLARED_DATASETS.items()}
 
49
  """A status response contains a forbidden credential shape."""
50
 
51
 
52
+ class AmazonStatusRowsRefused(AmazonStatusSafetyError):
53
+ """S67-T31: some status ROWS were refused; the rest are carried, already guarded.
54
+
55
+ Still an `AmazonStatusSafetyError`, so every caller that refuses on the base class keeps
56
+ refusing. `safe_status` holds only rows that passed the guard and `refused` only table NAMES:
57
+ neither carries the refused content, so a caller may degrade those rows and keep the others.
58
+ """
59
+
60
+ def __init__(self, safe_status, refused):
61
+ super().__init__('Amazon status contains a forbidden credential shape.')
62
+ self.safe_status = safe_status
63
+ self.refused = tuple(refused)
64
+
65
+
66
+ #: The status guard's scalar ceiling, and the sentence a row wears when its status is refused.
67
+ STATUS_SCALAR_LIMIT = 512
68
+ STATUS_UNAVAILABLE = "Sync status is unavailable for this database."
69
+
70
+
71
+ def trim_status(value, limit=STATUS_SCALAR_LIMIT):
72
+ """Cut every string over `limit` to a word-bounded excerpt that fits, recursively.
73
+
74
+ S67-T31: a long, honest cause (staging's Search Query Performance cause measured 935
75
+ characters) used to trip the length branch of the guard and take the whole connector modal
76
+ down with a 500. ⛔ Call this only AFTER the credential-shape scan of the UNTRIMMED value
77
+ (`screen_status_rows`): cutting first could slice a token shape out of a string and accept
78
+ the rest, which would trim a refusal into acceptance.
79
+ """
80
+ if isinstance(value, dict):
81
+ return {key: trim_status(item, limit) for key, item in value.items()}
82
+ if isinstance(value, list):
83
+ return [trim_status(item, limit) for item in value]
84
+ if isinstance(value, tuple):
85
+ return tuple(trim_status(item, limit) for item in value)
86
+ if isinstance(value, str) and len(value) > limit:
87
+ head = value[:limit - 3]
88
+ cut = head.rsplit(" ", 1)[0] if " " in head else head
89
+ return cut.rstrip(" ,;:") + "..."
90
+ return value
91
+
92
+
93
+ def screen_status_rows(status):
94
+ """`(safe, refused)` for a `{table: row}` status: each row judged on its own.
95
+
96
+ A row carrying a credential key, an `Atzr|` token or a bearer shape ANYWHERE in its untrimmed
97
+ form is refused whole (NC: never trimmed into acceptance, its value never returned). A row that
98
+ is only too long is trimmed, then held to the full guard again.
99
+ """
100
+ import json
101
+
102
+ safe, refused = {}, []
103
+ for name, row in (status or {}).items():
104
+ try:
105
+ whole = json.dumps(row, ensure_ascii=False, allow_nan=False)
106
+ if status_payload_has_secret(whole, max_length=None):
107
+ refused.append(name)
108
+ continue
109
+ trimmed = trim_status(row)
110
+ if status_payload_has_secret(json.dumps(trimmed, ensure_ascii=False, allow_nan=False)):
111
+ refused.append(name)
112
+ continue
113
+ except (TypeError, ValueError, RecursionError):
114
+ refused.append(name)
115
+ continue
116
+ safe[name] = trimmed
117
+ return safe, refused
118
+
119
+
120
+ def status_payload_has_secret(serialized_payload, *, max_length=STATUS_SCALAR_LIMIT):
121
  """Scan serialized JSON for C2's credential keys, token shapes and oversized values.
122
 
123
  Pure and usable without a server. Invalid JSON is unsafe too; never echo rejected content.
124
  The credential key roster is the same one the connector accepts at connect time.
125
+ `max_length=None` scans for credential shapes only (the pre-trim pass of `screen_status_rows`).
126
  """
127
  import json
128
  import re
 
142
  elif isinstance(value, list):
143
  pending.extend(value)
144
  elif isinstance(value, str):
145
+ if ((max_length is not None and len(value) > max_length) or 'Atzr|' in value
146
  or re.search(r'\bbearer\s+\S+', value, flags=re.IGNORECASE)):
147
  return True
148
+ elif (value is not None and max_length is not None
149
+ and len(str(value)) > max_length):
150
  return True
151
  return False
152
 
 
232
  row["syncCause"] = cause
233
  cause = cause[:budget - 3].rsplit(" ", 1)[0] + "..."
234
  row["unknownCause"] = " ".join(part for part in (cause, purge_message) if part)
235
+ # S67-T31: judged PER ROW. An over-long cause is trimmed (staging's 500 was
236
+ # `search_query_performance.unknownCause` at 935 characters); a credential shape still
237
+ # refuses, now naming only its rows so the caller degrades those and keeps the rest.
238
+ safe, refused = screen_status_rows(status)
239
+ if refused:
240
+ raise AmazonStatusRowsRefused(assert_safe_status(safe), refused)
241
+ return assert_safe_status(safe)
242
 
243
  declared = {name: {"rowsLoaded": None, "declared": True, "unknownCause": spec["reason"]}
244
  for name, spec in DECLARED_DATASETS.items()}
api/content_studio.py ADDED
@@ -0,0 +1,638 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Content Studio: an App template that creates its own References and Posts databases.
2
+
3
+ S67-T40 (owner instruction 1; rulings R17, R18, R21, R11). Plan-only (round 1 R5): nothing here
4
+ publishes to any network. The template creates two TENANT-OWNED databases and binds the App to
5
+ Posts, opening on a calendar of posts. The App is delete-safe (rule 13, ARCHITECTURE section 24):
6
+ deleting it removes only the App record, so References and Posts and every row in them outlive it.
7
+
8
+ This module is the App's own code. Shared files reach it only through a guarded import
9
+ (`routes_templates.py`), so deleting this file removes the template and nothing else breaks.
10
+ """
11
+ from __future__ import annotations
12
+
13
+ TEMPLATE_KEY = "content_studio"
14
+ LABEL = "Content Studio"
15
+ DESCRIPTION = "Plan posts from your references. Creates References and Posts databases."
16
+
17
+ #: R4: the channels a post is planned for. Channel length limits are ADVISED, never enforced (O4).
18
+ CHANNELS = ["LinkedIn", "X", "Instagram", "TikTok", "YouTube", "Reddit"]
19
+ NETWORKS = CHANNELS + ["Other"]
20
+ STATUSES = ["Idea", "Draft", "Ready", "Posted", "Skipped"]
21
+ CALENDAR_VIEW_ID = "cs_calendar"
22
+
23
+ #: R15 (structure, not words): the three fields a Reference is drafted FROM are extracted from its
24
+ #: pasted text by the per-row AI field machinery (`ai_enrich`), re-run when that text changes.
25
+ _EXTRACT = {
26
+ "hook": ("Hook", "In one sentence, describe the opening move this post uses to earn attention "
27
+ "(for example a surprising number, a contrarian claim, a question). Describe "
28
+ "the technique; do not quote the post. Post: {pasted_text}"),
29
+ "structure": ("Structure", "List the post's structure as 3 to 6 short numbered beats, each "
30
+ "naming what that part does (setup, proof, turn, ask). Describe, "
31
+ "never quote. Post: {pasted_text}"),
32
+ "angle": ("Angle", "In one sentence, name the point of view or argument the post takes and "
33
+ "who it is for. Do not quote the post. Post: {pasted_text}"),
34
+ }
35
+
36
+
37
+ #: The platform ladder leads with a REASONING model, which spends a few hundred tokens thinking
38
+ #: before it answers; at 300 the column's ceiling was reached with no answer ("the model had
39
+ #: nothing to answer from"), so each extraction gets room for thought plus a short answer.
40
+ EXTRACT_MAX_TOKENS = 1500
41
+
42
+
43
+ def reference_fields():
44
+ """References: URL, network, author, pasted text, tags, hook, structure, angle (T40 done-when)."""
45
+ fields = [
46
+ {"key": "title", "label": "Title", "type": "text"},
47
+ {"key": "url", "label": "URL", "type": "url"},
48
+ {"key": "network", "label": "Network", "type": "select", "options": list(NETWORKS)},
49
+ {"key": "author", "label": "Author", "type": "text"},
50
+ {"key": "pasted_text", "label": "Pasted text", "type": "text"},
51
+ {"key": "tags", "label": "Tags", "type": "multiselect", "options": []},
52
+ ]
53
+ for key, (label, prompt) in _EXTRACT.items():
54
+ fields.append({"key": key, "label": label, "type": "ai_enrich",
55
+ "aiEnrich": {"prompt": prompt, "maxTokens": EXTRACT_MAX_TOKENS,
56
+ "trigger": {"mode": "on_change"}, "overwrite": "always"}})
57
+ return fields
58
+
59
+
60
+ def post_fields(references_key):
61
+ """Posts: caption, channel, scheduled, status, media, campaign, post URL, References link,
62
+ attribution (T40 done-when). `media` is an `image` field: the store has no attachment type."""
63
+ return [
64
+ {"key": "caption", "label": "Caption", "type": "text"},
65
+ {"key": "channel", "label": "Channel", "type": "select", "options": list(CHANNELS)},
66
+ {"key": "scheduled", "label": "Scheduled", "type": "date"},
67
+ {"key": "status", "label": "Status", "type": "select", "options": list(STATUSES)},
68
+ {"key": "media", "label": "Media", "type": "image"},
69
+ {"key": "campaign", "label": "Campaign", "type": "text"},
70
+ {"key": "post_url", "label": "Post URL", "type": "url"},
71
+ {"key": "references", "label": "References", "type": "link",
72
+ "link": {"table": references_key, "selectionMode": "manual"}},
73
+ {"key": "attribution", "label": "Attribution", "type": "text"},
74
+ ]
75
+
76
+
77
+ class ContentStudioError(RuntimeError):
78
+ """A refusal the route turns into a plain sentence; nothing half-created is left behind."""
79
+
80
+
81
+ def _create_table(label, username, fields, st):
82
+ """`user_tables.create` refuses a duplicate label, so a second Studio gets "Posts 2" and so on."""
83
+ from core import user_tables
84
+ for attempt in range(1, 10):
85
+ name = label if attempt == 1 else f"{label} {attempt}"
86
+ key = user_tables.create(name, username, fields=fields, st=st)
87
+ if key:
88
+ return key
89
+ raise ContentStudioError(f"The {label} database could not be created. "
90
+ "Rename or delete an older one, then try again.")
91
+
92
+
93
+ def create(session, name=""):
94
+ """Create References + Posts (tenant-owned), a calendar View on Posts, and the App bound to
95
+ Posts. Returns `{address, application, databases}`; on a failure part-way, the databases this
96
+ call created are deleted again, so a refusal leaves the workspace as it was."""
97
+ import application_registry
98
+ from core import user_tables, view_templates
99
+ from core import table_store
100
+
101
+ st = session.runtime
102
+ user = session.uname
103
+ app_name = " ".join(str(name or "").split())[:120] or LABEL
104
+ created = []
105
+ try:
106
+ references = _create_table("References", user, reference_fields(), st)
107
+ created.append(references)
108
+ posts = _create_table("Posts", user, post_fields(references), st)
109
+ created.append(posts)
110
+ ops = table_store.make(view_templates.workspace_key(posts), st=st)
111
+ ops.save_view(user, {"id": CALENDAR_VIEW_ID, "name": "Calendar", "createdBy": user,
112
+ "config": {"filters": [], "sorts": [],
113
+ "display": {"mode": "calendar", "dateField": "scheduled",
114
+ "titleField": "caption"}}})
115
+ application = application_registry.create(
116
+ st, session.tenant, user,
117
+ {"templateKind": TEMPLATE_KEY, "name": app_name, "sourceDatabase": posts,
118
+ "navPlacement": {"section": "app", "order": 0}},
119
+ allowed_databases=None)
120
+ except Exception:
121
+ for key in reversed(created):
122
+ try:
123
+ user_tables.delete(key, st=st)
124
+ except Exception:
125
+ pass
126
+ raise
127
+ # S67-T41 owner correction: the App opens on its own surface in the App module, not in Data.
128
+ return {"address": "#" + app_link(application["id"]), "application": application,
129
+ "databases": {"references": references, "posts": posts}}
130
+
131
+
132
+ # ---------------------------------------------------------------------------------------------
133
+ # S67-T41 (R13, R14, R15, R19, R20, R5, O4): DRAFTING. One Draft row per chosen channel, from
134
+ # several selected References plus a one-line topic, written from their extracted STRUCTURE
135
+ # (hook, structure, angle), never their words, with every author credited. Plan-only: a draft
136
+ # is a Posts row with status Draft; nothing is published anywhere.
137
+ # ---------------------------------------------------------------------------------------------
138
+ import re
139
+
140
+ from fastapi import APIRouter, Body, Depends
141
+
142
+ from deps import Session, err, require_session
143
+
144
+ router = APIRouter(prefix="/content-studio")
145
+
146
+ #: O4: channel limits are ADVICE in the prompt and on screen, never a truncation.
147
+ CHANNEL_ADVICE = {
148
+ "LinkedIn": "LinkedIn post: up to about 3,000 characters, short paragraphs, no hashtag wall.",
149
+ "X": "X post: aim for 280 characters or fewer.",
150
+ "Instagram": "Instagram caption: up to about 2,200 characters; a strong first line.",
151
+ "TikTok": "TikTok caption: short, about 150 characters.",
152
+ "YouTube": "YouTube: a title line, then a two or three sentence description.",
153
+ "Reddit": "Reddit: a title line, then the body; plain, specific, no marketing tone.",
154
+ }
155
+ DRAFT_SYSTEM = (
156
+ "You draft ONE original social media post for the channel named. You are given a one-line "
157
+ "topic and the STRUCTURE of several reference posts: the technique of each hook, its beats "
158
+ "and its angle. Borrow those structural moves; write entirely new sentences. Never copy or "
159
+ "closely paraphrase any sentence from anywhere. Answer with the post text only: no preamble, "
160
+ "no quotation marks around it, no markdown heading. Never use an em dash or an en dash; use "
161
+ "a comma, a colon or a full stop.")
162
+ LEDGER_SURFACE = "field_agent"
163
+ DRAFT_MAX_TOKENS = 3000 # a reasoning model thinks first; see EXTRACT_MAX_TOKENS
164
+ DRAFT_TIMEOUT_S = 60
165
+ #: A shared run of this many words is a copied sentence, whatever surrounds it (R15).
166
+ VERBATIM_WORDS = 8
167
+
168
+
169
+ def _studio(session, app_id):
170
+ """(app, posts_key, references_key) for a Content Studio App this session may open."""
171
+ import application_registry
172
+ from core import user_tables
173
+ doc = application_registry.load(session.runtime)
174
+ app = doc["applications"].get(str(app_id or ""))
175
+ if (not isinstance(app, dict) or app.get("templateKind") != TEMPLATE_KEY
176
+ or not application_registry.may_read(app, session.uname, session.admin)):
177
+ raise err(404, "content_studio_not_found", "That Content Studio does not exist.")
178
+ posts = str(app.get("sourceDatabase") or "")
179
+ defn = user_tables.get(posts, session.runtime) or {}
180
+ link = next((f.get("link") for f in defn.get("fields") or ()
181
+ if isinstance(f, dict) and f.get("key") == "references"), None)
182
+ references = str((link or {}).get("table") or "")
183
+ if not posts or not references:
184
+ raise err(409, "content_studio_incomplete",
185
+ "This Content Studio has lost its Posts or References database.")
186
+ return app, posts, references
187
+
188
+
189
+ def _reference_rows(session, references):
190
+ from core import user_tables
191
+ defn = user_tables.get(references, session.runtime) or {}
192
+ rows = defn.get("rows") or {}
193
+ return {str(rid): (row if isinstance(row, dict) else {}) for rid, row in rows.items()}
194
+
195
+
196
+ # ---------------------------------------------------------------------------------------------
197
+ # S67-T42 (R35, standing rule 1): THE MONTHLY DRAFTING ALLOWANCE. Drafting runs on Loopable's
198
+ # platform keys, so each tenant gets a monthly count of drafts (one Draft row = one draft). Past
199
+ # it, Draft pauses with a sentence naming the reset date; the platform admin raises it per tenant
200
+ # (`PUT /content-studio/allowance`). A tenant admin cannot: that would defeat R35.
201
+ # One per-tenant bucket, owned by this module: {"allowance": int (absent = default),
202
+ # "months": {"YYYY-MM": drafts made}}. Month and reset are UTC.
203
+ # ---------------------------------------------------------------------------------------------
204
+ ALLOWANCE_KEY = "content_studio_usage"
205
+ DEFAULT_MONTHLY_DRAFTS = 100
206
+ ALLOWANCE_KEEP_MONTHS = 12
207
+ _MONTH_NAMES = ("January", "February", "March", "April", "May", "June", "July", "August",
208
+ "September", "October", "November", "December")
209
+
210
+
211
+ def _now():
212
+ from datetime import datetime, timezone
213
+ return datetime.now(timezone.utc)
214
+
215
+
216
+ def _month_key(now):
217
+ return f"{now.year:04d}-{now.month:02d}"
218
+
219
+
220
+ def _reset_on(now):
221
+ """The first day of next month (UTC): the day this month's count stops counting."""
222
+ from datetime import date
223
+ return date(now.year + 1, 1, 1) if now.month == 12 else date(now.year, now.month + 1, 1)
224
+
225
+
226
+ def _spoken_date(day):
227
+ return f"{_MONTH_NAMES[day.month - 1]} {day.day}, {day.year}"
228
+
229
+
230
+ def _limit(doc):
231
+ raw = (doc or {}).get("allowance")
232
+ if isinstance(raw, bool) or not isinstance(raw, int) or raw < 0:
233
+ return DEFAULT_MONTHLY_DRAFTS
234
+ return raw
235
+
236
+
237
+ def allowance_state(doc, now=None):
238
+ """{used, limit, remaining, resetsOn, paused, message}: the ONE reading of month and reset
239
+ that both the panel and the enforcement use."""
240
+ now = now or _now()
241
+ doc = doc if isinstance(doc, dict) else {}
242
+ months = doc.get("months") if isinstance(doc.get("months"), dict) else {}
243
+ try:
244
+ used = max(0, int(months.get(_month_key(now)) or 0))
245
+ except (TypeError, ValueError):
246
+ used = 0
247
+ limit = _limit(doc)
248
+ remaining = max(0, limit - used)
249
+ reset = _reset_on(now)
250
+ paused = remaining <= 0
251
+ message = (f"This workspace has used this month's drafting allowance. "
252
+ f"It resets on {_spoken_date(reset)}.") if paused else ""
253
+ return {"used": used, "limit": limit, "remaining": remaining,
254
+ "resetsOn": reset.isoformat(), "paused": paused, "message": message}
255
+
256
+
257
+ def _short_message(remaining):
258
+ drafts = "1 draft" if remaining == 1 else f"{remaining} drafts"
259
+ channels = "1 channel" if remaining == 1 else f"up to {remaining} channels"
260
+ return f"This workspace has {drafts} left this month. Choose {channels}."
261
+
262
+
263
+ def _refusal(state, wanted):
264
+ """The 429 a draft of `wanted` drafts earns against `state`, or None when it fits."""
265
+ if state["remaining"] <= 0:
266
+ return err(429, "drafting_allowance_used", state["message"])
267
+ if state["remaining"] < wanted:
268
+ return err(429, "drafting_allowance_short", _short_message(state["remaining"]))
269
+ return None
270
+
271
+
272
+ def _read_allowance(st):
273
+ doc = st.get(ALLOWANCE_KEY)
274
+ return doc if isinstance(doc, dict) else {}
275
+
276
+
277
+ def _count(st, month, delta):
278
+ """Add `delta` drafts to `month` in one read-modify-write; keeps the last 12 months."""
279
+ def _up(doc):
280
+ doc = dict(doc) if isinstance(doc, dict) else {}
281
+ months = dict(doc.get("months")) if isinstance(doc.get("months"), dict) else {}
282
+ months[month] = max(0, int(months.get(month) or 0) + int(delta))
283
+ for stale in sorted(months)[:-ALLOWANCE_KEEP_MONTHS]:
284
+ months.pop(stale, None)
285
+ doc["months"] = months
286
+ return doc
287
+ st.update(ALLOWANCE_KEY, _up, flush="sync")
288
+
289
+
290
+ def reserve_drafts(st, wanted, now=None):
291
+ """Check AND reserve `wanted` drafts in ONE store update, so two concurrent drafts cannot both
292
+ take the last slot. Raises the 429 (no write) when it does not fit; returns the month key the
293
+ reservation was booked to, for `release_drafts` on a failure."""
294
+ now = now or _now()
295
+ try:
296
+ current = _read_allowance(st)
297
+ except Exception: # noqa: BLE001
298
+ raise err(503, "allowance_unavailable",
299
+ "The drafting allowance could not be checked, so nothing was drafted. Try again.")
300
+ refusal = _refusal(allowance_state(current, now), wanted)
301
+ if refusal is not None: # fast path: a paused workspace writes nothing
302
+ raise refusal
303
+ month = _month_key(now)
304
+ verdict = {}
305
+
306
+ def _up(doc):
307
+ doc = dict(doc) if isinstance(doc, dict) else {}
308
+ refused = _refusal(allowance_state(doc, now), wanted)
309
+ if refused is not None:
310
+ verdict["refusal"] = refused
311
+ return doc
312
+ months = dict(doc.get("months")) if isinstance(doc.get("months"), dict) else {}
313
+ months[month] = max(0, int(months.get(month) or 0)) + int(wanted)
314
+ for stale in sorted(months)[:-ALLOWANCE_KEEP_MONTHS]:
315
+ months.pop(stale, None)
316
+ doc["months"] = months
317
+ return doc
318
+
319
+ try:
320
+ st.update(ALLOWANCE_KEY, _up, flush="sync")
321
+ except Exception: # noqa: BLE001
322
+ raise err(503, "allowance_unavailable",
323
+ "The drafting allowance could not be checked, so nothing was drafted. Try again.")
324
+ if "refusal" in verdict:
325
+ raise verdict["refusal"]
326
+ return month
327
+
328
+
329
+ def release_drafts(st, month, n):
330
+ """Hand back a reservation whose drafts were never written (AI failure, copy refusal, store)."""
331
+ try:
332
+ _count(st, month, -int(n))
333
+ except Exception: # noqa: BLE001
334
+ pass
335
+
336
+
337
+ @router.put("/allowance")
338
+ def set_allowance(body: dict = Body(default=None), session: Session = Depends(require_session)):
339
+ """The owner raises (or resets) one tenant's monthly drafting allowance. Platform admin only."""
340
+ import core.platform_admin as platform_admin
341
+ from harness import runtime
342
+ if not platform_admin.is_platform_admin(session.user):
343
+ raise err(403, "forbidden", "your account does not have access to this surface")
344
+ body = body if isinstance(body, dict) else {}
345
+ slug = str(body.get("tenant") or "").strip().lower()
346
+ monthly = body.get("monthly")
347
+ if monthly is not None and (isinstance(monthly, bool) or not isinstance(monthly, int)
348
+ or monthly < 0):
349
+ raise err(400, "bad_allowance",
350
+ "The monthly allowance must be a whole number of drafts, 0 or more.")
351
+ if not slug or slug not in runtime.known_tenants():
352
+ raise err(404, "tenant_not_found", "That workspace does not exist.")
353
+ try:
354
+ st = runtime.get_runtime(slug)
355
+ except KeyError:
356
+ raise err(404, "tenant_not_found", "That workspace does not exist.")
357
+
358
+ def _up(doc):
359
+ doc = dict(doc) if isinstance(doc, dict) else {}
360
+ if monthly is None:
361
+ doc.pop("allowance", None)
362
+ else:
363
+ doc["allowance"] = int(monthly)
364
+ return doc
365
+
366
+ st.update(ALLOWANCE_KEY, _up, flush="sync")
367
+ return {"tenant": slug, "allowance": allowance_state(_read_allowance(st))}
368
+
369
+
370
+ @router.get("/references")
371
+ def list_references(app: str = "", session: Session = Depends(require_session)):
372
+ """The References a Draft can use: id, title, author, network, and whether its structure is in.
373
+ Also this workspace's drafting allowance, so the panel reports the limit before it bites."""
374
+ _app, _posts, references = _studio(session, app)
375
+ rows = _reference_rows(session, references)
376
+ try:
377
+ allowance = allowance_state(_read_allowance(session.runtime))
378
+ except Exception: # noqa: BLE001
379
+ allowance = None # unreadable: the draft route still enforces it
380
+ return {"references": [
381
+ {"id": rid, "title": str(row.get("title") or row.get("url") or "Untitled reference")[:160],
382
+ "author": str(row.get("author") or "")[:120], "network": str(row.get("network") or ""),
383
+ "extracted": bool(str(row.get("structure") or "").strip())}
384
+ for rid, row in rows.items()],
385
+ "channels": list(CHANNELS), "advice": dict(CHANNEL_ADVICE), "allowance": allowance}
386
+
387
+
388
+ # ---------------------------------------------------------------------------------------------
389
+ # S67-T41 OWNER CORRECTION (Telegram update 437342853, 2026-09-28): "Content studio should be an
390
+ # App ... it should act like Catalog / Route where it just uses the data module as what its
391
+ # building on top." So the App opens in the App module on its OWN surface (`#/app?studio=<id>`,
392
+ # `apps/contentStudio/ContentStudioApp.tsx`): a calendar and a board over Posts, the Draft door,
393
+ # and the two databases underneath. Data still holds References and Posts; the App never sends
394
+ # anyone there to use it.
395
+ # ⚠ The shared `/applications` doors (`routes_assets.py`) admit only topic-backed databases, so
396
+ # they refuse an App bound to a user table; the read, star and delete this App needs live here,
397
+ # on the registry's own writers, behind the same `_studio` + `may_read` / `may_edit` walls.
398
+ # ---------------------------------------------------------------------------------------------
399
+ def app_link(app_id):
400
+ """The one address a Content Studio App opens at (App module, its own surface)."""
401
+ return f"/app?studio={app_id}"
402
+
403
+
404
+ #: The Posts fields the surface draws, in the grid's own Field shape so `viewModes.CalendarView`
405
+ #: (by Scheduled) and `KanbanView` (by Status) render them unchanged.
406
+ SURFACE_FIELDS = ("caption", "channel", "scheduled", "status", "attribution", "campaign")
407
+
408
+
409
+ def _surface_field(defn):
410
+ kind = {"date": "date", "select": "select"}.get(defn.get("type"), "text")
411
+ field = {"key": defn["key"], "label": str(defn.get("label") or defn["key"]), "type": kind,
412
+ "source": "overlay"}
413
+ if kind == "select":
414
+ field["options"] = [str(o) for o in (defn.get("options") or ())]
415
+ return field
416
+
417
+
418
+ def _studio_or_missing(session, app_id):
419
+ """`_studio`, answering an absent App with the code the App home already reads as 'gone'."""
420
+ try:
421
+ return _studio(session, app_id)
422
+ except Exception as exc: # noqa: BLE001
423
+ if getattr(exc, "status_code", None) == 404:
424
+ raise err(404, "application_not_found", "That Content Studio no longer exists.")
425
+ raise
426
+
427
+
428
+ @router.get("/studio")
429
+ def studio(app: str = "", session: Session = Depends(require_session)):
430
+ """Everything the App surface draws: the App, Posts (surface fields + rows), References'
431
+ count, the statuses in board order, and the drafting allowance."""
432
+ from core import user_tables
433
+ application, posts, references = _studio(session, app)
434
+ if not user_tables.may_open(posts, session.uname, session.admin, st=session.runtime):
435
+ raise err(404, "content_studio_not_found", "That Content Studio does not exist.")
436
+ posts_def = user_tables.get(posts, session.runtime) or {}
437
+ refs_def = user_tables.get(references, session.runtime) or {}
438
+ by_key = {f.get("key"): f for f in posts_def.get("fields") or () if isinstance(f, dict)}
439
+ fields = [_surface_field(by_key[key]) for key in SURFACE_FIELDS if key in by_key]
440
+ rows = []
441
+ for rid, row in (posts_def.get("rows") or {}).items():
442
+ try:
443
+ pid = int(rid)
444
+ except (TypeError, ValueError):
445
+ continue
446
+ row = row if isinstance(row, dict) else {}
447
+ rows.append({"pid": pid, **{key: row.get(key) for key in SURFACE_FIELDS}})
448
+ rows.sort(key=lambda r: r["pid"])
449
+ try:
450
+ allowance = allowance_state(_read_allowance(session.runtime))
451
+ except Exception: # noqa: BLE001
452
+ allowance = None
453
+ return {"app": {"id": application["id"], "name": application.get("name") or LABEL},
454
+ "posts": {"database": posts, "label": str(posts_def.get("label") or "Posts"),
455
+ "fields": fields, "rows": rows},
456
+ "references": {"database": references,
457
+ "label": str(refs_def.get("label") or "References"),
458
+ "count": len(refs_def.get("rows") or {})},
459
+ "statuses": list(STATUSES), "allowance": allowance}
460
+
461
+
462
+ @router.patch("/apps/{app_id}")
463
+ def star_app(app_id: str, body: dict = Body(default=None),
464
+ session: Session = Depends(require_session)):
465
+ """Star or unstar a Content Studio on the App home (the registry's own star writer)."""
466
+ import application_registry
467
+ _app, posts, _references = _studio_or_missing(session, app_id)
468
+ body = body if isinstance(body, dict) else {}
469
+ if set(body) != {"starred"} or not isinstance(body.get("starred"), bool):
470
+ raise err(400, "bad_patch", "Only the star of a Content Studio changes here.")
471
+ try:
472
+ landed = application_registry.mutate(session.runtime, app_id, session.uname, session.admin,
473
+ {"starred": body["starred"]}, allowed_databases=[posts])
474
+ except PermissionError:
475
+ raise err(403, "forbidden", "You cannot change this App.")
476
+ except application_registry.ApplicationError:
477
+ raise err(404, "application_not_found", "That Content Studio no longer exists.")
478
+ return {"application": landed}
479
+
480
+
481
+ @router.delete("/apps/{app_id}")
482
+ def delete_app(app_id: str, body: dict = Body(default=None),
483
+ session: Session = Depends(require_session)):
484
+ """Delete the App and nothing else (rule 13): References and Posts, every row in them, and
485
+ every View on them outlive it. The name is confirmed inside the registry's own update."""
486
+ import application_registry
487
+ application, posts, _references = _studio_or_missing(session, app_id)
488
+ confirm = (body or {}).get("confirmName") if isinstance(body, dict) else None
489
+ if not isinstance(confirm, str) or confirm != application.get("name"):
490
+ raise err(400, "confirm_name", "Enter the exact App name to confirm.")
491
+
492
+ class _NameConfirmed:
493
+ def update(self, key, delete):
494
+ def confirmed(raw):
495
+ deleted = delete(raw)
496
+ if (raw.get("applications") or {}).get(app_id, {}).get("name") != confirm:
497
+ raise application_registry.ApplicationError("the App name changed")
498
+ return deleted
499
+ return session.runtime.update(key, confirmed)
500
+
501
+ try:
502
+ return application_registry.delete(_NameConfirmed(), app_id, session.uname, session.admin,
503
+ allowed_databases=[posts])
504
+ except PermissionError:
505
+ raise err(403, "forbidden", "You no longer have permission to delete this App.")
506
+ except application_registry.ApplicationError:
507
+ raise err(400, "confirm_name", "The App name may have changed. Close this dialog and reload to retry.")
508
+
509
+
510
+ def _words(text):
511
+ return re.findall(r"[a-z0-9']+", str(text or "").lower())
512
+
513
+
514
+ def copied_sentence(draft, sources):
515
+ """The first run of VERBATIM_WORDS consecutive words a draft shares with any source, or ''."""
516
+ grams = set()
517
+ for source in sources:
518
+ words = _words(source)
519
+ grams.update(" ".join(words[i:i + VERBATIM_WORDS])
520
+ for i in range(0, max(0, len(words) - VERBATIM_WORDS + 1)))
521
+ words = _words(draft)
522
+ for i in range(0, max(0, len(words) - VERBATIM_WORDS + 1)):
523
+ gram = " ".join(words[i:i + VERBATIM_WORDS])
524
+ if gram in grams:
525
+ return gram
526
+ return ""
527
+
528
+
529
+ def attribution(rows):
530
+ """Every selected reference's author, credited in plain words (R14 traceability)."""
531
+ names = list(dict.fromkeys(
532
+ str(row.get("author") or row.get("title") or "an unnamed source").strip() for row in rows))
533
+ joined = names[0] if len(names) == 1 else ", ".join(names[:-1]) + " and " + names[-1]
534
+ return f"Structure drawn from posts by {joined}."
535
+
536
+
537
+ def draft_prompt(topic, channel, rows):
538
+ parts = [f"Channel: {channel}. {CHANNEL_ADVICE.get(channel, '')}", f"Topic: {topic}", ""]
539
+ for n, row in enumerate(rows, 1):
540
+ parts.append(f"Reference {n} ({row.get('network') or 'post'}):")
541
+ for key, label in (("hook", "Hook technique"), ("structure", "Structure"), ("angle", "Angle")):
542
+ value = " ".join(str(row.get(key) or "").split())[:900]
543
+ if value:
544
+ parts.append(f" {label}: {value}")
545
+ parts.append("")
546
+ parts.append("Write the post now.")
547
+ return "\n".join(parts)
548
+
549
+
550
+ def draft_posts(session, app_id, reference_ids, topic, channels, *, ask=None):
551
+ """Generate EVERY channel first; write the Posts rows only if all succeeded (no half row)."""
552
+ topic = " ".join(str(topic or "").split())[:200]
553
+ ids = [str(x) for x in dict.fromkeys(reference_ids or ())][:50]
554
+ wanted = [c for c in dict.fromkeys(channels or ()) if c in CHANNELS]
555
+ if not ids:
556
+ raise err(400, "no_references", "Select at least one reference to draft from.")
557
+ if not topic:
558
+ raise err(400, "no_topic", "Type a one-line topic for the draft.")
559
+ if not wanted:
560
+ raise err(400, "no_channels", "Choose at least one channel.")
561
+ _app, posts, references = _studio(session, app_id)
562
+ rows_by_id = _reference_rows(session, references)
563
+ missing = [rid for rid in ids if rid not in rows_by_id]
564
+ if missing:
565
+ raise err(409, "references_missing", "A selected reference no longer exists. Reload and try again.")
566
+ chosen = [rows_by_id[rid] for rid in ids]
567
+ if not any(str(row.get("structure") or "").strip() for row in chosen):
568
+ raise err(409, "references_not_extracted",
569
+ "The selected references have no extracted structure yet. Paste their text first.")
570
+ # R35: the allowance is checked and reserved BEFORE any provider is resolved or called. One
571
+ # draft per channel; the reservation is handed back unless every row is written.
572
+ month = reserve_drafts(session.runtime, len(wanted))
573
+ try:
574
+ return _generate_and_save(session, posts, ids, topic, wanted, chosen, ask=ask)
575
+ except BaseException:
576
+ release_drafts(session.runtime, month, len(wanted))
577
+ raise
578
+
579
+
580
+ def _generate_and_save(session, posts, ids, topic, wanted, chosen, *, ask=None):
581
+ import ai_enrich
582
+ import ai_review
583
+ import usage_ledger
584
+ from core import user_tables
585
+
586
+ live = ai_review.ladder()
587
+ if not live and ask is None:
588
+ raise err(503, "ai_unavailable", "No AI provider is configured here, so nothing was drafted.")
589
+ provider = (live or [{"name": "injected", "model": "injected"}])[0]
590
+ model = provider["model"]
591
+ caller = ask or ai_enrich._ask
592
+ sources = [row.get("pasted_text") or "" for row in chosen]
593
+ drafts, tokens, calls = [], 0, 0
594
+ try:
595
+ for channel in wanted:
596
+ prompt = draft_prompt(topic, channel, chosen)
597
+ text = ""
598
+ for attempt in range(2):
599
+ answer, used, problem = caller(provider, model, prompt, DRAFT_MAX_TOKENS,
600
+ DRAFT_TIMEOUT_S, system=DRAFT_SYSTEM)
601
+ calls += 1
602
+ tokens += int(used or 0)
603
+ if problem or not str(answer or "").strip():
604
+ raise err(502, "draft_failed", f"The {channel} draft could not be written "
605
+ f"({problem or 'the model returned nothing'}). Nothing was saved.")
606
+ text = ai_enrich.no_dashes(str(answer).strip())
607
+ copied = copied_sentence(text, sources)
608
+ if not copied:
609
+ break
610
+ prompt += f"\n\nYour last draft reused this wording from a reference: \"{copied}\". Rewrite it in new words."
611
+ text = ""
612
+ if not text:
613
+ raise err(502, "draft_copied", f"The {channel} draft kept repeating a reference's "
614
+ "wording, so it was not saved. Nothing was saved.")
615
+ drafts.append({"channel": channel, "caption": text})
616
+ finally:
617
+ if calls:
618
+ # `usage_ledger.SURFACES` names four surfaces and refuses any other, so drafts are
619
+ # booked as `field_agent` (AI-written cells of a user table) until a `content_studio`
620
+ # surface exists there (a finding for the ledger's owner; this module cannot add it).
621
+ usage_ledger.record(LEDGER_SURFACE, provider["name"], model, total=tokens,
622
+ calls=calls, st=session.runtime, user=session.uname)
623
+ credit = attribution(chosen)
624
+ new_rows = [{"caption": d["caption"], "channel": d["channel"], "status": "Draft",
625
+ "references": ",".join(ids), "attribution": credit} for d in drafts]
626
+ created = user_tables.add_rows(posts, new_rows, username=session.uname, st=session.runtime)
627
+ if not created:
628
+ raise err(503, "store_unavailable", "The drafts could not be saved. Nothing was saved.")
629
+ return {"created": list(created) if isinstance(created, (list, tuple)) else created,
630
+ "drafts": drafts, "attribution": credit, "tokens": tokens, "calls": calls,
631
+ "provider": provider["name"], "model": model}
632
+
633
+
634
+ @router.post("/draft")
635
+ def draft(body: dict = Body(default=None), session: Session = Depends(require_session)):
636
+ body = body if isinstance(body, dict) else {}
637
+ return draft_posts(session, body.get("app"), body.get("references"), body.get("topic"),
638
+ body.get("channels"))
api/deps.py CHANGED
@@ -232,6 +232,28 @@ def _assistant_cached_builtin(session: Session, database: str, requested_fields=
232
  else ("product_pool", team_id))
233
  cache = getattr(session.runtime, "pool_cache", None)
234
  entry = cache.get(cache_key) if isinstance(cache, dict) else None
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
235
  if (not isinstance(entry, tuple) or len(entry) < 2
236
  or not isinstance(entry[1], (list, tuple))
237
  or any(not isinstance(row, dict) for row in entry[1])):
@@ -247,6 +269,44 @@ def _assistant_cached_builtin(session: Session, database: str, requested_fields=
247
  _ASSISTANT_USER_TABLE_KINDS = frozenset({"materialised_user_table", "mirror_user_table"})
248
 
249
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
250
  def _assistant_table_defn(session: Session, database: str):
251
  """The rows-free definition for one `ut_*` database plus its lent runtime, after `may_open`.
252
 
@@ -276,7 +336,9 @@ def _assistant_table_defn(session: Session, database: str):
276
  if not isinstance(definition, dict):
277
  _assistant_refuse(404, "assistant_unknown_database", "that database is not available")
278
  definition_runtime = user_tables.lend(session.runtime, user_tables=definitions)
279
- if not user_tables.may_open(database, session.uname, session.admin, st=definition_runtime):
 
 
280
  # Deliberately no label/owner in this response: knowing a key must not become an oracle
281
  # for somebody else's database.
282
  _assistant_refuse(403, "assistant_forbidden",
@@ -346,7 +408,7 @@ def _assistant_user_table(session: Session, database: str, requested_fields=None
346
 
347
 
348
  def _assistant_mirror_table(session: Session, database: str, requested_fields=None, filters=None,
349
- *, defn=None, lent=None):
350
  """Read a MIRROR-SERVED user table through the same filter compiler the grid uses (R11 / C7).
351
 
352
  Returns `_assistant_user_table`'s 4-tuple - `(rows, fields, source_version, label)` - so the
@@ -382,11 +444,24 @@ def _assistant_mirror_table(session: Session, database: str, requested_fields=No
382
  # THE CHEAP QUESTION FIRST, and it needs no cursor: is this key a connected Odoo grid at all?
383
  # A `readThrough` table that is not one has no mirror rows anywhere, and asking the mirror
384
  # about it would open a cursor to learn nothing.
385
- if assistant_mirror.declared_fields(database) is None:
 
 
 
 
 
 
 
 
 
 
386
  _assistant_refuse(409, "assistant_snapshot_unavailable",
387
  "this database does not store its rows and it is not one of the "
388
  "connected databases the assistant can read from the mirror")
389
- cur, refusal = assistant_mirror.open_cursor(session)
 
 
 
390
  if refusal is not None:
391
  _assistant_refuse(refusal.status, refusal.code, refusal.message)
392
  spec = assistant_mirror.binding(cur, database)
@@ -394,7 +469,7 @@ def _assistant_mirror_table(session: Session, database: str, requested_fields=No
394
  _assistant_refuse(409, "assistant_snapshot_unavailable",
395
  "this database is served live from its connector and this deployment "
396
  "has no read-through binding for it yet, so it holds no rows to read")
397
- fields = assistant_mirror.answerable_fields(database, spec)
398
  if not fields:
399
  _assistant_refuse(409, "assistant_snapshot_unavailable",
400
  "this database's connector mirror carries none of its declared columns "
@@ -422,12 +497,36 @@ def _assistant_mirror_table(session: Session, database: str, requested_fields=No
422
  if grant is None:
423
  wall_tree = None
424
 
 
 
 
 
 
 
 
425
  try:
426
- rows, stamp, total = assistant_mirror.read_rows(
427
- session, database, cur, spec, fields,
428
- wall_tree=wall_tree, filter_tree=filter_tree,
429
- filter_keys=[field["key"] for field in visible
430
- if isinstance(field, dict) and field.get("key")])
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
431
  except assistant_mirror.MirrorRefusal as exc:
432
  _assistant_refuse(exc.status, exc.code, exc.message)
433
  raise # unreachable; see above
@@ -459,7 +558,33 @@ def _assistant_requested_fields(fields, visible_fields):
459
  return out
460
 
461
 
462
- def assistant_read_scope(session: Session, database, fields=None, filters=None):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
463
  """Return a detached, permissioned snapshot for one Assistant tool call.
464
 
465
  Signature (the C8 contract for E):
@@ -468,6 +593,12 @@ def assistant_read_scope(session: Session, database, fields=None, filters=None):
468
  permission_scope_applied, fields, filters, records
469
  }
470
 
 
 
 
 
 
 
471
  `database` is exactly one source. `fields` is an explicit list of visible field keys (or
472
  ``None`` for every visible field). `filters` is ``None`` or the strict tree accepted by
473
  `core.perm_scope.validate_assistant_filter`; it rejects unknown, hidden, inactive and
@@ -478,6 +609,7 @@ def assistant_read_scope(session: Session, database, fields=None, filters=None):
478
  from harness import filter_eval
479
 
480
  key = str(database or "").strip()
 
481
  if key in _ASSISTANT_BUILT_INS:
482
  rows, canonical_fields, source_version = _assistant_cached_builtin(session, key, fields, filters)
483
  label = _ASSISTANT_BUILT_INS[key]["label"]
@@ -494,12 +626,15 @@ def assistant_read_scope(session: Session, database, fields=None, filters=None):
494
  from core import user_tables
495
  _defn, _lent = _assistant_table_defn(session, key)
496
  if user_tables.materialises(key, st=_lent, defn=_defn):
 
 
 
497
  rows, canonical_fields, source_version, label = _assistant_user_table(
498
  session, key, fields, filters, defn=_defn, lent=_lent)
499
  source_kind = "materialised_user_table"
500
  else:
501
  rows, canonical_fields, source_version, label = _assistant_mirror_table(
502
- session, key, fields, filters, defn=_defn, lent=_lent)
503
  source_kind = "mirror_user_table"
504
  else:
505
  _assistant_refuse(404, "assistant_unknown_database", "that database is not available")
@@ -556,7 +691,7 @@ def assistant_read_scope(session: Session, database, fields=None, filters=None):
556
  records.append({"pid": copy.deepcopy(row["pid"]),
557
  **{field: copy.deepcopy(row.get(field)) for field in selected_keys}})
558
 
559
- return {
560
  "database": key,
561
  "label": str(label),
562
  "source_kind": source_kind,
@@ -568,6 +703,11 @@ def assistant_read_scope(session: Session, database, fields=None, filters=None):
568
  "filters": copy.deepcopy(requested_filter),
569
  "records": records,
570
  }
 
 
 
 
 
571
 
572
 
573
  def assistant_permitted_sources(session: Session, databases):
@@ -672,6 +812,19 @@ def assistant_source_status(session: Session, databases=None):
672
  mirror_cur = None
673
  return mirror_cur
674
 
 
 
 
 
 
 
 
 
 
 
 
 
 
675
  def _definitions():
676
  nonlocal definitions, read_definitions
677
  if not read_definitions:
@@ -752,6 +905,10 @@ def assistant_source_status(session: Session, databases=None):
752
  entry = cache.get(cache_key) if isinstance(cache, dict) else None
753
  if isinstance(entry, tuple) and len(entry) >= 2 and isinstance(entry[1], (list, tuple)):
754
  row["answerable"] = True
 
 
 
 
755
  else:
756
  row["reason"] = "no snapshot loaded yet. Open this database once, then ask"
757
  continue
@@ -762,10 +919,16 @@ def assistant_source_status(session: Session, databases=None):
762
  if not isinstance(definition, dict):
763
  continue
764
  lent = user_tables.lend(session.runtime, user_tables=defs)
765
- if not user_tables.may_open(key, session.uname, session.admin, st=lent):
 
766
  continue
767
  row["permitted"] = True
768
  if user_tables.materialises(key, st=lent, defn=definition):
 
 
 
 
 
769
  row["answerable"] = True
770
  continue
771
  # ⭐⭐ W47-T23 / R11 - THE SECOND WAY TO BE ANSWERABLE. This used to end here with a flat
@@ -778,7 +941,9 @@ def assistant_source_status(session: Session, databases=None):
778
  # is transient and retrying works, while a grid this deployment has no read-through
779
  # binding for will not fix itself by waiting. One sentence for both would make the first
780
  # look permanent, which is the failure mode the ruling exists to prevent.
781
- cur = _mirror()
 
 
782
  if cur is None:
783
  row["reason"] = ("this database is read live from its connector mirror, and that "
784
  "mirror is not open on this deployment right now; try again shortly")
@@ -801,6 +966,49 @@ def assistant_source_status(session: Session, databases=None):
801
  return out
802
 
803
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
804
  def _user_for(claims):
805
  """The account named by a verified cookie, or None — with the epoch check that makes a
806
  stateless cookie revocable.
@@ -833,12 +1041,12 @@ def _user_for(claims):
833
  # `Exception` into `{}`, so a store `PoolTimeout` on staging answered a valid cookie with 401
834
  # `invalid_session` and the client signed the owner out. Still fail-closed: nobody is admitted.
835
  try:
836
- reg = users.registry() or {}
837
  except Exception as exc:
838
  print(f"[aios-api] session account store unavailable: {type(exc).__name__}: {exc}")
839
  raise err(503, "session_store_unavailable",
840
  "your account could not be checked just now. Try again in a moment")
841
- rec = reg.get(uname)
842
  if (rec and rec.get("active", True)
843
  and int(rec.get("epoch") or 0) == int(claims.get("e") or 0)):
844
  pub = users._public(uname, rec)
 
232
  else ("product_pool", team_id))
233
  cache = getattr(session.runtime, "pool_cache", None)
234
  entry = cache.get(cache_key) if isinstance(cache, dict) else None
235
+ if not isinstance(entry, tuple) and isinstance(cache, dict):
236
+ # ⭐⭐ S67-T33 / D-778: A DATABASE NEVER OPENED ANSWERS. The snapshot used to exist only
237
+ # once somebody opened the grid in this process, so after every restart the assistant
238
+ # refused a database its caller demonstrably holds. The miss is now filled by the GRID'S
239
+ # OWN pool builder, for the SAME scope key the grid would fill (`derive_pool_scope`
240
+ # above), so this is the grid's first open, not a second reader. It is read-only on Odoo
241
+ # (rule 4) and honours the connector pause exactly as the grid does (503 when paused
242
+ # with nothing cached). Permission and field checks above have already run.
243
+ try:
244
+ if database == "customer_data":
245
+ import routes_customers
246
+ routes_customers._pool_for(session.runtime, team_id, agent)
247
+ else:
248
+ import routes_products
249
+ routes_products._pool_for(session.runtime, team_id)
250
+ except HTTPException:
251
+ raise
252
+ except Exception as exc: # noqa: BLE001
253
+ _assistant_refuse(409, "assistant_snapshot_unavailable",
254
+ f"this database's snapshot could not be built for your current "
255
+ f"scope ({type(exc).__name__}); try again shortly")
256
+ entry = cache.get(cache_key)
257
  if (not isinstance(entry, tuple) or len(entry) < 2
258
  or not isinstance(entry[1], (list, tuple))
259
  or any(not isinstance(row, dict) for row in entry[1])):
 
269
  _ASSISTANT_USER_TABLE_KINDS = frozenset({"materialised_user_table", "mirror_user_table"})
270
 
271
 
272
+ def _assistant_nav_opens(session: Session, database: str, lent, definition=None) -> bool:
273
+ """Does the NAVIGATION offer this `ut_*` database to this caller? S67-T33 / R33.
274
+
275
+ ⭐⭐ THE AI CONNECTOR'S LIST IS THE NAV'S LIST, BY CONSTRUCTION RATHER THAN BY AGREEMENT.
276
+ `routes_nav.nav` admits a user table when `user_tables.nav_entries` lists it (which is
277
+ `may_open` plus the route-system exclusion), it is not a retired key, and
278
+ `perm_scope.nav_may_open` agrees (an administrator's explicit untick denies). The assistant
279
+ used to ask `may_open` alone, so a database the member's navigation did not show could still
280
+ be listed and read through the connector. This asks the nav's own predicates, in the nav's
281
+ order; it is not a second permission rule.
282
+ ⚠ `session.admin` short-circuits leg 1 of `nav_may_open` exactly as the nav's own admin
283
+ session does; `nav_may_open` itself returns True for an administrator.
284
+ """
285
+ import core.perm_scope as perm_scope
286
+ from core import route_system, user_tables
287
+
288
+ key = str(database or "")
289
+ try:
290
+ from odoo_relational import RETIRED_KEYS as retired
291
+ except Exception: # noqa: BLE001
292
+ retired = ()
293
+ if key in retired:
294
+ return False
295
+ if not user_tables.may_open(key, session.uname, session.admin, st=lent):
296
+ return False
297
+ if isinstance(definition, dict) and (route_system.is_managed(definition)
298
+ or route_system.is_managed(key)):
299
+ return False
300
+ if session.admin:
301
+ return True
302
+ user = getattr(session, "user", None)
303
+ if not isinstance(user, dict):
304
+ # No account record means no explicit per-key deny can exist, and `nav_may_open` leg 3
305
+ # then defers to `may_open`, which has already answered above.
306
+ return True
307
+ return bool(perm_scope.nav_may_open(user, key, st=lent))
308
+
309
+
310
  def _assistant_table_defn(session: Session, database: str):
311
  """The rows-free definition for one `ut_*` database plus its lent runtime, after `may_open`.
312
 
 
336
  if not isinstance(definition, dict):
337
  _assistant_refuse(404, "assistant_unknown_database", "that database is not available")
338
  definition_runtime = user_tables.lend(session.runtime, user_tables=definitions)
339
+ # S67-T33: the NAV's predicate, not `may_open` alone, so a database the caller's navigation
340
+ # does not show is refused here too (403), not merely left off the list.
341
+ if not _assistant_nav_opens(session, database, definition_runtime, definition):
342
  # Deliberately no label/owner in this response: knowing a key must not become an oracle
343
  # for somebody else's database.
344
  _assistant_refuse(403, "assistant_forbidden",
 
408
 
409
 
410
  def _assistant_mirror_table(session: Session, database: str, requested_fields=None, filters=None,
411
+ *, defn=None, lent=None, mode=None, extra=None):
412
  """Read a MIRROR-SERVED user table through the same filter compiler the grid uses (R11 / C7).
413
 
414
  Returns `_assistant_user_table`'s 4-tuple - `(rows, fields, source_version, label)` - so the
 
444
  # THE CHEAP QUESTION FIRST, and it needs no cursor: is this key a connected Odoo grid at all?
445
  # A `readThrough` table that is not one has no mirror rows anywhere, and asking the mirror
446
  # about it would open a cursor to learn nothing.
447
+ if database.startswith("ut_amzn_"):
448
+ # ⭐ S67-T33: THE GRID'S OWN ADMISSION FIRST. A dynamically sized Amazon snapshot enters
449
+ # the source registry only through `require_amazon_mirror`, so without it a database
450
+ # never opened in this process had no binding here (measured on staging for
451
+ # `ut_amzn_fba_inventory`). It refuses by name (503) while the Amazon mirror is unloaded.
452
+ import routes_odoo_tables
453
+ routes_odoo_tables.require_amazon_mirror(database, session, definition=definition)
454
+ # ⭐ S67-T33: the stored definition rides along, so an Amazon grid or a generated
455
+ # `ut_odoo_model_*` table answers from its own field contract, as it does on the grid.
456
+ declared = assistant_mirror.declared_fields(database, definition)
457
+ if declared is None:
458
  _assistant_refuse(409, "assistant_snapshot_unavailable",
459
  "this database does not store its rows and it is not one of the "
460
  "connected databases the assistant can read from the mirror")
461
+ # ⭐ S67-T33: THE TABLE'S OWN CURSOR (`_table_cursor`), so Amazon never waits on Odoo's
462
+ # first sync. Passed only for an Amazon key, which is the one family it changes.
463
+ cur, refusal = (assistant_mirror.open_cursor(session, database)
464
+ if database.startswith("ut_amzn_") else assistant_mirror.open_cursor(session))
465
  if refusal is not None:
466
  _assistant_refuse(refusal.status, refusal.code, refusal.message)
467
  spec = assistant_mirror.binding(cur, database)
 
469
  _assistant_refuse(409, "assistant_snapshot_unavailable",
470
  "this database is served live from its connector and this deployment "
471
  "has no read-through binding for it yet, so it holds no rows to read")
472
+ fields = assistant_mirror.answerable_fields(database, spec, declared)
473
  if not fields:
474
  _assistant_refuse(409, "assistant_snapshot_unavailable",
475
  "this database's connector mirror carries none of its declared columns "
 
497
  if grant is None:
498
  wall_tree = None
499
 
500
+ filter_keys = [field["key"] for field in visible
501
+ if isinstance(field, dict) and field.get("key")]
502
+ # ⭐⭐ S67-T34: THREE READS BEHIND THE ONE PREFLIGHT ABOVE, chosen by `mode`, all compiling the
503
+ # SAME wall and filter (`assistant_mirror._predicate`). "schema" reads and counts no row
504
+ # (D-2630: describe answers the field list of a million-row table without counting it);
505
+ # ("aggregate", specs) runs the aggregates IN SQL over every permitted row (D-616, D-2631);
506
+ # ("page", offset, limit) pages IN SQL for a table past the one-pass ceiling (rule 1).
507
  try:
508
+ if mode == "schema":
509
+ return [], fields, {"read": "connector mirror"}, definition.get("label") or database
510
+ if isinstance(mode, tuple) and mode and mode[0] == "aggregate":
511
+ values, total = assistant_mirror.aggregate(
512
+ session, database, cur, spec, fields, mode[1],
513
+ wall_tree=wall_tree, filter_tree=filter_tree, filter_keys=filter_keys)
514
+ if isinstance(extra, dict):
515
+ extra["aggregates"], extra["total"] = values, total
516
+ return ([], fields, {"read": "connector mirror", "rows": total},
517
+ definition.get("label") or database)
518
+ if isinstance(mode, tuple) and mode and mode[0] == "page":
519
+ rows, stamp, total = assistant_mirror.read_page(
520
+ session, database, cur, spec, fields, offset=mode[1], limit=mode[2],
521
+ wall_tree=wall_tree, filter_tree=filter_tree, filter_keys=filter_keys,
522
+ defn=definition)
523
+ if isinstance(extra, dict):
524
+ extra["total"] = total
525
+ else:
526
+ rows, stamp, total = assistant_mirror.read_rows(
527
+ session, database, cur, spec, fields,
528
+ wall_tree=wall_tree, filter_tree=filter_tree, filter_keys=filter_keys,
529
+ defn=definition)
530
  except assistant_mirror.MirrorRefusal as exc:
531
  _assistant_refuse(exc.status, exc.code, exc.message)
532
  raise # unreachable; see above
 
558
  return out
559
 
560
 
561
+ def _assistant_oversize_reason(database: str, definition, lent) -> str:
562
+ """The named cause an oversize stored table carries, or "". S67-T33 / rule 1.
563
+
564
+ ⛔ AN EVICTED TABLE KEEPS ITS DEFINITION AND LOSES ITS ROWS, so the materialised reader used
565
+ to answer it as a complete table of 0 rows. `user_tables.limit_report` is the one evaluator
566
+ of that stamp (the grid serves the same sentence), so its cause and recommendation are read
567
+ from there rather than re-worded here.
568
+ """
569
+ from core import user_tables
570
+
571
+ if not user_tables.oversize_of(database, defn=definition if isinstance(definition, dict)
572
+ else {}):
573
+ return ""
574
+ report = user_tables.limit_report(database, st=lent) or {}
575
+ label = str((definition or {}).get("label") or database)
576
+ return (f"{label} is not stored: {report.get('cause') or 'its rows were not stored'}. "
577
+ f"{str(report.get('recommendation') or '').rstrip('.')}. The assistant refuses "
578
+ f"rather than answering 0 rows").replace("\u2014", ",").replace("\u2013", "-")
579
+
580
+
581
+ def _assistant_refuse_oversize(database: str, definition, lent) -> None:
582
+ reason = _assistant_oversize_reason(database, definition, lent)
583
+ if reason:
584
+ _assistant_refuse(409, "assistant_source_too_large", reason)
585
+
586
+
587
+ def assistant_read_scope(session: Session, database, fields=None, filters=None, *, mode=None):
588
  """Return a detached, permissioned snapshot for one Assistant tool call.
589
 
590
  Signature (the C8 contract for E):
 
593
  permission_scope_applied, fields, filters, records
594
  }
595
 
596
+ ⭐ S67-T34: `mode` changes only HOW a mirror-served database is read, never who may read it
597
+ (every wall below runs unchanged): "schema" returns the field contract with no row read,
598
+ ("aggregate", specs) adds `server_aggregates` and `total_rows` computed in SQL over every
599
+ permitted row, ("page", offset, limit) returns one SQL page plus `total_rows`. Every other
600
+ source kind ignores it and answers as before.
601
+
602
  `database` is exactly one source. `fields` is an explicit list of visible field keys (or
603
  ``None`` for every visible field). `filters` is ``None`` or the strict tree accepted by
604
  `core.perm_scope.validate_assistant_filter`; it rejects unknown, hidden, inactive and
 
609
  from harness import filter_eval
610
 
611
  key = str(database or "").strip()
612
+ extra = {}
613
  if key in _ASSISTANT_BUILT_INS:
614
  rows, canonical_fields, source_version = _assistant_cached_builtin(session, key, fields, filters)
615
  label = _ASSISTANT_BUILT_INS[key]["label"]
 
626
  from core import user_tables
627
  _defn, _lent = _assistant_table_defn(session, key)
628
  if user_tables.materialises(key, st=_lent, defn=_defn):
629
+ # S67-T33: a stored table whose rows were evicted refuses by name, never answers 0.
630
+ # Only on the STORED reader: a read-through table's rows come from the mirror.
631
+ _assistant_refuse_oversize(key, _defn, _lent)
632
  rows, canonical_fields, source_version, label = _assistant_user_table(
633
  session, key, fields, filters, defn=_defn, lent=_lent)
634
  source_kind = "materialised_user_table"
635
  else:
636
  rows, canonical_fields, source_version, label = _assistant_mirror_table(
637
+ session, key, fields, filters, defn=_defn, lent=_lent, mode=mode, extra=extra)
638
  source_kind = "mirror_user_table"
639
  else:
640
  _assistant_refuse(404, "assistant_unknown_database", "that database is not available")
 
691
  records.append({"pid": copy.deepcopy(row["pid"]),
692
  **{field: copy.deepcopy(row.get(field)) for field in selected_keys}})
693
 
694
+ out = {
695
  "database": key,
696
  "label": str(label),
697
  "source_kind": source_kind,
 
703
  "filters": copy.deepcopy(requested_filter),
704
  "records": records,
705
  }
706
+ if "aggregates" in extra:
707
+ out["server_aggregates"] = copy.deepcopy(extra["aggregates"])
708
+ if "total" in extra:
709
+ out["total_rows"] = int(extra["total"])
710
+ return out
711
 
712
 
713
  def assistant_permitted_sources(session: Session, databases):
 
812
  mirror_cur = None
813
  return mirror_cur
814
 
815
+ amazon_cur = {}
816
+
817
+ def _amazon_mirror(key):
818
+ """ONE Amazon cursor for the batch, chosen by `_table_cursor` for an Amazon key."""
819
+ if "cur" not in amazon_cur:
820
+ try:
821
+ import assistant_mirror
822
+ cur, refusal = assistant_mirror.open_cursor(session, key)
823
+ amazon_cur["cur"] = None if refusal is not None else cur
824
+ except Exception: # noqa: BLE001
825
+ amazon_cur["cur"] = None
826
+ return amazon_cur["cur"]
827
+
828
  def _definitions():
829
  nonlocal definitions, read_definitions
830
  if not read_definitions:
 
905
  entry = cache.get(cache_key) if isinstance(cache, dict) else None
906
  if isinstance(entry, tuple) and len(entry) >= 2 and isinstance(entry[1], (list, tuple)):
907
  row["answerable"] = True
908
+ elif isinstance(cache, dict):
909
+ # ⭐ S67-T33 / D-778: a miss is no longer a refusal; the read builds the snapshot
910
+ # through the grid's own pool builder, so this source is answerable now.
911
+ row["answerable"] = True
912
  else:
913
  row["reason"] = "no snapshot loaded yet. Open this database once, then ask"
914
  continue
 
919
  if not isinstance(definition, dict):
920
  continue
921
  lent = user_tables.lend(session.runtime, user_tables=defs)
922
+ # ⭐ S67-T33 / R33: the NAV's predicate, so this list and the navigation are one set.
923
+ if not _assistant_nav_opens(session, key, lent, definition):
924
  continue
925
  row["permitted"] = True
926
  if user_tables.materialises(key, st=lent, defn=definition):
927
+ oversize = _assistant_oversize_reason(key, definition, lent)
928
+ if oversize:
929
+ # Rule 1's second sentence: listed, with its cause, never answered as 0 rows.
930
+ row["reason"] = oversize
931
+ continue
932
  row["answerable"] = True
933
  continue
934
  # ⭐⭐ W47-T23 / R11 - THE SECOND WAY TO BE ANSWERABLE. This used to end here with a flat
 
941
  # is transient and retrying works, while a grid this deployment has no read-through
942
  # binding for will not fix itself by waiting. One sentence for both would make the first
943
  # look permanent, which is the failure mode the ruling exists to prevent.
944
+ # ⭐ S67-T33: an Amazon grid asks ITS OWN mirror (`_table_cursor`), never the Odoo
945
+ # first-sync gate, so "not open right now" is never Odoo's backfill answering for Amazon.
946
+ cur = _amazon_mirror(key) if key.startswith("ut_amzn_") else _mirror()
947
  if cur is None:
948
  row["reason"] = ("this database is read live from its connector mirror, and that "
949
  "mirror is not open on this deployment right now; try again shortly")
 
966
  return out
967
 
968
 
969
+ #: S67 lane D (S67-T28 finding): the session resolver re-read the WHOLE `users` bucket on every
970
+ #: authenticated request, uncached; on a saturated cluster that read queued ahead of every page.
971
+ #: It is now held against the bucket's durable revision token (`store.revision`), the S67-T28
972
+ #: `_REV_MEMO` pattern: the token is read BEFORE the value, so a write racing the read can only
973
+ #: cache newer bytes under the older token (a miss next time, never a stale hit). Every Postgres
974
+ #: `put` / `update` bumps `rev`, so a deactivation or an epoch rotation misses on the very next
975
+ #: request. ⛔ FAIL-CLOSED: no token, or a token read that fails, means a direct read (which still
976
+ #: answers 503 when the store is unreadable); a cached registry is never served in its place.
977
+ #: The key carries the identity of the reader and the store it reads, so a swapped store or a
978
+ #: patched `users.registry` / `store.get` misses instead of replaying another registry.
979
+ _SESSION_REGISTRY = {"key": None, "reg": None}
980
+ _SESSION_REGISTRY_LOCK = __import__("threading").Lock()
981
+
982
+
983
+ def _session_registry():
984
+ """`users.registry()` for `_user_for`, re-read only when the `users` bucket changed.
985
+
986
+ ⛔ POSTGRES ONLY. There `rev` is a durable column every `put` / `update` bumps (`store_pg`),
987
+ and nothing else writes `store_kv`. The HF backend's token is a per-process counter that a
988
+ fixture or a cache-level write can leave unmoved (measured: `verify_scopes` 346/687 with the
989
+ memo on HF), and its `get()` already holds the bucket for the life of the process, so the
990
+ re-read this memo removes does not exist there: it reads straight through.
991
+ """
992
+ key = None
993
+ try:
994
+ backend = store.backend()
995
+ token = (store.revision("users") or {}).get("token") if backend == "pg" else None
996
+ if token not in (None, ""):
997
+ where = os.environ.get("AIOS_TENANT") or "royal-imports"
998
+ key = (backend, where, id(users.registry), id(store.get), str(token))
999
+ except Exception: # noqa: BLE001 -- fail-closed below
1000
+ key = None
1001
+ if key is not None:
1002
+ with _SESSION_REGISTRY_LOCK:
1003
+ if _SESSION_REGISTRY["key"] == key:
1004
+ return _SESSION_REGISTRY["reg"]
1005
+ reg = users.registry() or {}
1006
+ if key is not None:
1007
+ with _SESSION_REGISTRY_LOCK:
1008
+ _SESSION_REGISTRY["key"], _SESSION_REGISTRY["reg"] = key, copy.deepcopy(reg)
1009
+ return reg
1010
+
1011
+
1012
  def _user_for(claims):
1013
  """The account named by a verified cookie, or None — with the epoch check that makes a
1014
  stateless cookie revocable.
 
1041
  # `Exception` into `{}`, so a store `PoolTimeout` on staging answered a valid cookie with 401
1042
  # `invalid_session` and the client signed the owner out. Still fail-closed: nobody is admitted.
1043
  try:
1044
+ reg = _session_registry()
1045
  except Exception as exc:
1046
  print(f"[aios-api] session account store unavailable: {type(exc).__name__}: {exc}")
1047
  raise err(503, "session_store_unavailable",
1048
  "your account could not be checked just now. Try again in a moment")
1049
+ rec = copy.deepcopy(reg.get(uname)) # the registry may be the held copy: never mutate it
1050
  if (rec and rec.get("active", True)
1051
  and int(rec.get("epoch") or 0) == int(claims.get("e") or 0)):
1052
  pub = users._public(uname, rec)
api/formula_runtime.py CHANGED
@@ -83,6 +83,8 @@ FN_ARITY = {
83
  "ISNUMBER": (1, 1), "ISTEXT": (1, 1), "ISERROR": (1, 1),
84
  "OFFSET": (3, 5), "INDIRECT": (1, 2), "RAND": (0, 0),
85
  "FILTER": (2, 3), "SORT": (1, 4),
 
 
86
  }
87
  # Excel workbooks in the Daily Sales lineage use both spellings. Keep the authored formula text
88
  # untouched in the workbook; normalization maps AVG to the same AST/function the catalogue's
@@ -457,6 +459,15 @@ FN_CATALOGUE = {
457
  "description": "Returns TRUE when a value is a number.", "contexts": _BOTH},
458
  "ISTEXT": {"category": "Information", "signature": "ISTEXT(value)",
459
  "description": "Returns TRUE when a value is text.", "contexts": _BOTH},
 
 
 
 
 
 
 
 
 
460
  "ISERROR": {"category": "Information", "signature": "ISERROR(value)",
461
  "description": "Returns TRUE when a formula would refuse to produce a value.",
462
  "contexts": _BOTH},
@@ -625,6 +636,9 @@ PARITY_FIXTURES = {
625
  "EXACT": ("EXACT(\"A\", \"a\")", "FALSE"),
626
  "ISNUMBER": ("ISNUMBER(1)", "TRUE"),
627
  "ISTEXT": ("ISTEXT(\"a\")", "TRUE"),
 
 
 
628
  "ISERROR": ("ISERROR(1 / 0)", "TRUE"),
629
  }
630
 
@@ -917,7 +931,7 @@ RANGE_ARGS = {
917
 
918
  #: ⭐ THE ARGUMENT IS AN ADDRESS, NOT A VALUE. `ROW(B4)` asks what row `B4` is on and must not read
919
  #: what is written there; the cell may well be empty. Handled beside `RANGE_ARGS` in `_eval`.
920
- ADDR_ARGS = {"ROW": (0,), "COLUMN": (0,)}
921
 
922
 
923
  def _is_range_position(fn, index):
@@ -1863,6 +1877,17 @@ def _eval_value(node, row, today, diagnostics=None):
1863
  for code in local:
1864
  _diagnose(diagnostics, code)
1865
  return "" if first is None and isinstance(row, _SheetInputs) and not local else first
 
 
 
 
 
 
 
 
 
 
 
1866
  if fn == "ISERROR":
1867
  # The whole job is to ask whether a refusal happened, so the refusal must stay LOCAL.
1868
  local = []
@@ -1893,6 +1918,11 @@ def _eval_value(node, row, today, diagnostics=None):
1893
  _diagnose(diagnostics, "bad_value")
1894
  return None
1895
  args.append(here)
 
 
 
 
 
1896
  return _call(fn, args, today, diagnostics)
1897
  # ⭐ RANGES FLATTEN HERE, INTO THE SAME FLAT LIST `_call` ALREADY TAKES. `SUM`, `AVERAGE`,
1898
  # `COUNT`, `MIN` and `MAX` are declared `(1, MANY)` and simply iterate their argument list,
@@ -1928,6 +1958,27 @@ def _eval_value(node, row, today, diagnostics=None):
1928
  raise FormulaError("formula AST node is not supported")
1929
 
1930
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1931
  def _addr_arg(node, diagnostics):
1932
  """The ADDRESS a1 node names, as a key. Anything else is not an address and refuses."""
1933
  if isinstance(node, dict) and node.get("t") == "a1":
@@ -2324,6 +2375,19 @@ def _call(fn, a, today, diagnostics=None):
2324
  if fn == "FIND":
2325
  start = int(nums[2] or 1)-1 if len(a)>2 else 0; pos = _text(a[1]).find(_text(a[0]), start)
2326
  return pos+1 if pos >= 0 else None
 
 
 
 
 
 
 
 
 
 
 
 
 
2327
  if fn in ("REGEX_EXTRACT", "REGEX_REPLACE"):
2328
  pattern, subject = _safe_regex(a[1], a[0]); m = re.search(pattern, subject)
2329
  if fn == "REGEX_EXTRACT": return m.group(0) if m else None
@@ -3727,7 +3791,7 @@ def recompute_document(book, *, cache_key=None, changes=None, today=None):
3727
  excel = {**REFERENCE_ERRORS, "no_match": "#N/A", "bad_value": "#VALUE!", "div_zero": "#DIV/0!", "numeric_error": "#NUM!"}.get(code)
3728
  if excel: cell["error"]["excelCode"] = excel
3729
  else:
3730
- cell.update(state="fresh", display="" if cell["value"] is None else str(cell["value"]))
3731
  cell.pop("refusal", None)
3732
  cell.pop("error", None)
3733
  cell.pop("spill", None)
@@ -3770,7 +3834,7 @@ def recompute_document(book, *, cache_key=None, changes=None, today=None):
3770
  base = engine.specs.get(child, {})
3771
  style = {**(owner.get("style") or {}), **(base.get("style") or {})}
3772
  record = {"kind": "literal", "value": engine.values.get(child), "state": "fresh",
3773
- "display": "" if engine.values.get(child) is None else str(engine.values[child]),
3774
  "spillParent": origin, "style": style,
3775
  "formulaMeta": {"spillChild": {"version": 1, "origin": origin, "address": child,
3776
  **({"base": base} if base else {})}}}
 
83
  "ISNUMBER": (1, 1), "ISTEXT": (1, 1), "ISERROR": (1, 1),
84
  "OFFSET": (3, 5), "INDIRECT": (1, 2), "RAND": (0, 0),
85
  "FILTER": (2, 3), "SORT": (1, 4),
86
+ # S67-T24: the reference workbooks' `IF(ISNUMBER(SEARCH(...)))` and `ISFORMULA(...)`.
87
+ "SEARCH": (2, 3), "SEARCHB": (2, 3), "ISFORMULA": (1, 1),
88
  }
89
  # Excel workbooks in the Daily Sales lineage use both spellings. Keep the authored formula text
90
  # untouched in the workbook; normalization maps AVG to the same AST/function the catalogue's
 
459
  "description": "Returns TRUE when a value is a number.", "contexts": _BOTH},
460
  "ISTEXT": {"category": "Information", "signature": "ISTEXT(value)",
461
  "description": "Returns TRUE when a value is text.", "contexts": _BOTH},
462
+ "ISFORMULA": {"category": "Information", "signature": "ISFORMULA(reference)",
463
+ "description": "Returns TRUE when the cell it names holds a formula.",
464
+ "contexts": _SHEET},
465
+ "SEARCH": {"category": "Text", "signature": "SEARCH(find_text, within_text, [start_num])",
466
+ "description": "Returns the position of one text value inside another, ignoring "
467
+ "case; ? matches one character and * any run.", "contexts": _BOTH},
468
+ "SEARCHB": {"category": "Text", "signature": "SEARCHB(find_text, within_text, [start_num])",
469
+ "description": "Counts like SEARCH; each character is one byte in this workbook.",
470
+ "contexts": _BOTH},
471
  "ISERROR": {"category": "Information", "signature": "ISERROR(value)",
472
  "description": "Returns TRUE when a formula would refuse to produce a value.",
473
  "contexts": _BOTH},
 
636
  "EXACT": ("EXACT(\"A\", \"a\")", "FALSE"),
637
  "ISNUMBER": ("ISNUMBER(1)", "TRUE"),
638
  "ISTEXT": ("ISTEXT(\"a\")", "TRUE"),
639
+ "SEARCH": ("SEARCH(\"B\", \"abc\")", 2),
640
+ "SEARCHB": ("SEARCHB(\"c?\", \"abcd\")", 3),
641
+ "ISFORMULA": ("ISFORMULA(B2)", "FALSE"),
642
  "ISERROR": ("ISERROR(1 / 0)", "TRUE"),
643
  }
644
 
 
931
 
932
  #: ⭐ THE ARGUMENT IS AN ADDRESS, NOT A VALUE. `ROW(B4)` asks what row `B4` is on and must not read
933
  #: what is written there; the cell may well be empty. Handled beside `RANGE_ARGS` in `_eval`.
934
+ ADDR_ARGS = {"ROW": (0,), "COLUMN": (0,), "ISFORMULA": (0,)}
935
 
936
 
937
  def _is_range_position(fn, index):
 
1877
  for code in local:
1878
  _diagnose(diagnostics, code)
1879
  return "" if first is None and isinstance(row, _SheetInputs) and not local else first
1880
+ if fn in ("ISNUMBER", "ISTEXT") and len(node.get("args") or ()) == 1:
1881
+ # ⭐ S67-T24: AN IS-FUNCTION NEVER PASSES AN ERROR ON. Excel answers FALSE for
1882
+ # `ISNUMBER(#VALUE!)`, which is what makes `IF(ISNUMBER(SEARCH(x, y)), ...)` (2,512 cells
1883
+ # in the Inventory System's Catalog) take its FALSE branch instead of failing whole.
1884
+ local = []
1885
+ try:
1886
+ value = _eval(node["args"][0], row, today, local)
1887
+ except (ArithmeticError, TypeError, ValueError, OverflowError, KeyError, re.error,
1888
+ FormulaError, _ReferenceFault):
1889
+ return False
1890
+ return False if local else _call(fn, [value], today, diagnostics)
1891
  if fn == "ISERROR":
1892
  # The whole job is to ask whether a refusal happened, so the refusal must stay LOCAL.
1893
  local = []
 
1918
  _diagnose(diagnostics, "bad_value")
1919
  return None
1920
  args.append(here)
1921
+ if fn == "ISFORMULA":
1922
+ # ⭐ S67-T24: ASKED OF THE CELL, NOT OF ITS VALUE. Only a Sheet document knows which
1923
+ # cells hold formulas (`SheetCalculation.specs`); a grid row has no formula cells.
1924
+ spec = row.engine.specs.get(args[0]) if isinstance(row, _SheetInputs) and args[0] else None
1925
+ return bool(isinstance(spec, dict) and spec.get("formula"))
1926
  return _call(fn, args, today, diagnostics)
1927
  # ⭐ RANGES FLATTEN HERE, INTO THE SAME FLAT LIST `_call` ALREADY TAKES. `SUM`, `AVERAGE`,
1928
  # `COUNT`, `MIN` and `MAX` are declared `(1, MANY)` and simply iterate their argument list,
 
1958
  raise FormulaError("formula AST node is not supported")
1959
 
1960
 
1961
+ def _display_text(value):
1962
+ """A calculated value as the grid shows it: Excel's TRUE / FALSE for a boolean (S67-T24; a
1963
+ Python `str(True)` painted "True"), blank for nothing, else the value's own text."""
1964
+ if value is None:
1965
+ return ""
1966
+ if isinstance(value, bool):
1967
+ return "TRUE" if value else "FALSE"
1968
+ return str(value)
1969
+
1970
+
1971
+ def _search_pattern(text):
1972
+ """SEARCH's wildcard text as a regex: `?` one character, `*` any run, `~x` a literal x."""
1973
+ out, index = [], 0
1974
+ while index < len(text):
1975
+ ch = text[index]
1976
+ if ch == "~" and index + 1 < len(text) and text[index + 1] in "?*~":
1977
+ out.append(re.escape(text[index + 1])); index += 2; continue
1978
+ out.append(".*?" if ch == "*" else "." if ch == "?" else re.escape(ch)); index += 1
1979
+ return "".join(out)
1980
+
1981
+
1982
  def _addr_arg(node, diagnostics):
1983
  """The ADDRESS a1 node names, as a key. Anything else is not an address and refuses."""
1984
  if isinstance(node, dict) and node.get("t") == "a1":
 
2375
  if fn == "FIND":
2376
  start = int(nums[2] or 1)-1 if len(a)>2 else 0; pos = _text(a[1]).find(_text(a[0]), start)
2377
  return pos+1 if pos >= 0 else None
2378
+ if fn in ("SEARCH", "SEARCHB"):
2379
+ # Excel's SEARCH: case-insensitive, `?` one character, `*` any run, `~` escapes the next;
2380
+ # absent text or a start outside the text is #VALUE!. SEARCHB counts bytes only in a
2381
+ # double-byte locale, so in this one it is SEARCH.
2382
+ within = _text(a[1])
2383
+ start = _strict_num(a[2], diagnostics) if len(a) > 2 else 1
2384
+ if start is None or not 1 <= int(start) <= len(within) + 1:
2385
+ _diagnose(diagnostics, "bad_value"); return None
2386
+ found = re.compile(_search_pattern(_text(a[0])), re.IGNORECASE | re.DOTALL).search(
2387
+ within, int(start) - 1)
2388
+ if not found:
2389
+ _diagnose(diagnostics, "bad_value"); return None
2390
+ return found.start() + 1
2391
  if fn in ("REGEX_EXTRACT", "REGEX_REPLACE"):
2392
  pattern, subject = _safe_regex(a[1], a[0]); m = re.search(pattern, subject)
2393
  if fn == "REGEX_EXTRACT": return m.group(0) if m else None
 
3791
  excel = {**REFERENCE_ERRORS, "no_match": "#N/A", "bad_value": "#VALUE!", "div_zero": "#DIV/0!", "numeric_error": "#NUM!"}.get(code)
3792
  if excel: cell["error"]["excelCode"] = excel
3793
  else:
3794
+ cell.update(state="fresh", display=_display_text(cell["value"]))
3795
  cell.pop("refusal", None)
3796
  cell.pop("error", None)
3797
  cell.pop("spill", None)
 
3834
  base = engine.specs.get(child, {})
3835
  style = {**(owner.get("style") or {}), **(base.get("style") or {})}
3836
  record = {"kind": "literal", "value": engine.values.get(child), "state": "fresh",
3837
+ "display": _display_text(engine.values.get(child)),
3838
  "spillParent": origin, "style": style,
3839
  "formulaMeta": {"spillChild": {"version": 1, "origin": origin, "address": child,
3840
  **({"base": base} if base else {})}}}
api/main.py CHANGED
@@ -92,6 +92,7 @@ from core import store # noqa: E402
92
  # 409: a view write whose caller was looking at an older revision. See its handler below.
93
  from core import view_audit # noqa: E402
94
  from deps import Session, module_gate # noqa: E402
 
95
 
96
  _WEB_DIST = _HERE.parents[1] / "web" / "dist"
97
 
@@ -351,6 +352,21 @@ app.include_router(routes_uploads.router)
351
  # control is that the enumeration must NAME every router in this file.**
352
  app.include_router(routes_templates.router) # item 7 / C12 — template registry, session-gated
353
  app.include_router(routes_connectors.router) # item 10 / C11 — the connectors directory
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
354
  # ⚠ routes_forms is the FIRST NEW PUBLIC DOOR since the `_DEV_FIXTURES` scar (see :257 below). Its
355
  # two paths are DELIBERATELY unauthenticated — a form is filled in by someone with no account — so
356
  # it joins `/api/health`, the automation hook and the tick on the exempt list. It resolves a token
@@ -1359,11 +1375,17 @@ def _rebuild_odoo_relational(why, previous_meta_fingerprint=None, meta_state_out
1359
  cid = str(cid or default_cid)
1360
  report = report if isinstance(report, dict) else {}
1361
  failed = report.get("failed")
 
 
1362
  database_failures, unmatched_failures = (
1363
- routes_connectors._odoo_result_database_failures(_rt, cid, report))
 
1364
  failure = (routes_connectors._odoo_failure(failed, "materialization")
1365
  if failed else None)
1366
- if not failure and (database_failures or unmatched_failures):
 
 
 
1367
  failure = routes_connectors._odoo_failure(
1368
  "one or more databases failed", "materialization")
1369
  tables = report.get("tables") if isinstance(report.get("tables"), dict) else {}
@@ -1440,6 +1462,13 @@ def _rebuild_odoo_relational(why, previous_meta_fingerprint=None, meta_state_out
1440
  _ut.record_odoo_sync_status(
1441
  phase="error" if safe_errors else "ok", errors=safe_errors,
1442
  st=_rt, connection_id=cid)
 
 
 
 
 
 
 
1443
  meta_state = _rebuild_meta_relational(
1444
  why, _rt, previous_fingerprint=previous_meta_fingerprint, force_relations=True)
1445
  if isinstance(meta_state_out, dict):
@@ -1469,6 +1498,9 @@ def _rebuild_odoo_relational(why, previous_meta_fingerprint=None, meta_state_out
1469
  _ut.record_odoo_sync_status(
1470
  phase="error", errors=[f"{failure['code']}: {failure['message']}"],
1471
  st=_rt, connection_id=cid)
 
 
 
1472
  except Exception:
1473
  pass
1474
  return False
 
92
  # 409: a view write whose caller was looking at an older revision. See its handler below.
93
  from core import view_audit # noqa: E402
94
  from deps import Session, module_gate # noqa: E402
95
+ from deps import require_session as deps_require_session # noqa: E402 (S67-T20 freshness door)
96
 
97
  _WEB_DIST = _HERE.parents[1] / "web" / "dist"
98
 
 
352
  # control is that the enumeration must NAME every router in this file.**
353
  app.include_router(routes_templates.router) # item 7 / C12 — template registry, session-gated
354
  app.include_router(routes_connectors.router) # item 10 / C11 — the connectors directory
355
+
356
+
357
+ @app.get("/api/v1/connectors/odoo/freshness")
358
+ def odoo_sync_freshness(session: Session = Depends(deps_require_session)):
359
+ """⭐⭐ S67-T20 / C4 — IS THIS WORKSPACE'S ODOO DATA STALE, AND DID THE LAST SYNC FAIL.
360
+
361
+ `{stale, lastGoodSyncAt, schedule, staleAfterSeconds, lastRunAt, phase, frozen, failure}`
362
+ from `odoo_relational.sync_freshness`. The Connectors card and Connectors > Odoo word it.
363
+ ⚠ A SIBLING OF `GET /connectors/odoo/status`, not a field on it, because that route is another
364
+ lane's file this wave; the integrator may fold these fields into it (COMBINE-AMEND, S67-T20).
365
+ Same administrator door as that route.
366
+ """
367
+ routes_connectors._odoo_admin(session)
368
+ import odoo_relational as _rel_fresh
369
+ return _rel_fresh.sync_freshness(session.runtime)
370
  # ⚠ routes_forms is the FIRST NEW PUBLIC DOOR since the `_DEV_FIXTURES` scar (see :257 below). Its
371
  # two paths are DELIBERATELY unauthenticated — a form is filled in by someone with no account — so
372
  # it joins `/api/health`, the automation hook and the tick on the exempt list. It resolves a token
 
1375
  cid = str(cid or default_cid)
1376
  report = report if isinstance(report, dict) else {}
1377
  failed = report.get("failed")
1378
+ # S67-T19: a read-through `limits` notice is the design working, not a failed
1379
+ # database; health reads only the entries that withheld rows (`_rel.health_view`).
1380
  database_failures, unmatched_failures = (
1381
+ routes_connectors._odoo_result_database_failures(
1382
+ _rt, cid, _rel.health_view(report)))
1383
  failure = (routes_connectors._odoo_failure(failed, "materialization")
1384
  if failed else None)
1385
+ # S67-T19: count drift within tolerance is recorded per database (below) and does not
1386
+ # fail the connection; a real failure or a stale mirror's gap still does.
1387
+ if not failure and (_rel.blocking_failures(database_failures, report)
1388
+ or unmatched_failures):
1389
  failure = routes_connectors._odoo_failure(
1390
  "one or more databases failed", "materialization")
1391
  tables = report.get("tables") if isinstance(report.get("tables"), dict) else {}
 
1462
  _ut.record_odoo_sync_status(
1463
  phase="error" if safe_errors else "ok", errors=safe_errors,
1464
  st=_rt, connection_id=cid)
1465
+ # S67-T20 / C4: the tenant-wide freshness stamp follows the DEFAULT connection, the
1466
+ # one this mirror serves. Best effort: a stamp must never fail the rebuild it records.
1467
+ if cid == str(default_cid):
1468
+ try:
1469
+ _rel.record_sync_outcome(_rt, ok=not safe_errors, at=refreshed_at)
1470
+ except Exception: # noqa: BLE001
1471
+ pass
1472
  meta_state = _rebuild_meta_relational(
1473
  why, _rt, previous_fingerprint=previous_meta_fingerprint, force_relations=True)
1474
  if isinstance(meta_state_out, dict):
 
1498
  _ut.record_odoo_sync_status(
1499
  phase="error", errors=[f"{failure['code']}: {failure['message']}"],
1500
  st=_rt, connection_id=cid)
1501
+ # S67-T20 / C4: a failed rebuild is a sync that did NOT end well.
1502
+ import odoo_relational as _rel_failed
1503
+ _rel_failed.record_sync_outcome(_rt, ok=False)
1504
  except Exception:
1505
  pass
1506
  return False
api/odoo_relational.py CHANGED
@@ -3619,6 +3619,112 @@ def sync_seconds(rt):
3619
  return max(int(secs), SYNC_FLOOR_SECONDS)
3620
 
3621
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3622
  def frozen(rt):
3623
  """Has this tenant DISCONNECTED Odoo (R10)? Frozen grids keep every row and every field and
3624
  stop being refreshed — distinct from PAUSED, which is temporary and keeps the credential."""
@@ -4558,6 +4664,93 @@ def available(rt=None, tenant_key=None, connection_id=None):
4558
  return False
4559
 
4560
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4561
  def refresh_curated(rt, cur, buckets, *, connection_id=None, username="automation",
4562
  today=None, retire=True, on_apply=None, source_client=None):
4563
  """Refresh each enabled database independently; retain failed databases unchanged.
@@ -4844,6 +5037,16 @@ def refresh(rt, tenant, username="automation", cur=None, today=None, connection_
4844
  return out
4845
 
4846
 
 
 
 
 
 
 
 
 
 
 
4847
  def refresh_all(rt, tenant, username="automation", cur=None, today=None):
4848
  """Refresh EVERY Odoo connection this tenant holds, one at a time (R4 / R7 / C4).
4849
 
@@ -4880,12 +5083,20 @@ def refresh_all(rt, tenant, username="automation", cur=None, today=None):
4880
  primary = None
4881
  for entry_cid in order:
4882
  named = None if (entry_cid is None or entry_cid == default) else entry_cid
4883
- try:
4884
- one = refresh(rt, tenant, username=username,
4885
- cur=(cur if named is None else None),
4886
- today=today, connection_id=named)
4887
- except Exception as exc: # noqa: BLE001
4888
- one = {"tables": {}, "failed": f"{type(exc).__name__}: Odoo connection refresh failed"}
 
 
 
 
 
 
 
 
4889
  reports[str(entry_cid or default or DEFAULT_CONNECTION)] = one
4890
  if named is None and primary is None:
4891
  primary = one
 
3619
  return max(int(secs), SYNC_FLOOR_SECONDS)
3620
 
3621
 
3622
+ #: ⭐⭐ S67-T20 / C4 — how far past its cadence a sync may run before its data is called stale.
3623
+ #: Two hours of grace on top of the interval: a daily sync is stale after 26 hours (C4's number),
3624
+ #: long enough that one slow pass does not raise a warning and short enough that a dead sync is
3625
+ #: named on the next day, not three weeks later as staging's was.
3626
+ STALE_GRACE_SECONDS = 2 * 3600
3627
+
3628
+
3629
+ def _utc_now():
3630
+ return _dt.datetime.now(_dt.timezone.utc)
3631
+
3632
+
3633
+ def _parse_iso(value):
3634
+ """An ISO timestamp as an aware UTC datetime, or None when it is not one."""
3635
+ if not value:
3636
+ return None
3637
+ try:
3638
+ at = _dt.datetime.fromisoformat(str(value).replace("Z", "+00:00"))
3639
+ except ValueError:
3640
+ return None
3641
+ return at if at.tzinfo else at.replace(tzinfo=_dt.timezone.utc)
3642
+
3643
+
3644
+ def record_sync_outcome(rt, ok, at=None):
3645
+ """Stamp this tenant's last sync, and its last GOOD sync when `ok`, on the connector's config.
3646
+
3647
+ ⛔ ON THE CONFIG DOCUMENT, NOT ON `odoo_sync_status`, because that document is REPLACED whole
3648
+ on every phase write (`core.user_tables.record_odoo_sync_status`), so a stamp kept there would
3649
+ be erased by the next `syncing`. Every writer of this config document updates it in place.
3650
+ """
3651
+ stamp = at or _utc_now().isoformat()
3652
+
3653
+ def _up(cur):
3654
+ cur = dict(cur) if isinstance(cur, dict) else {}
3655
+ cur["lastSyncAt"] = stamp
3656
+ if ok:
3657
+ cur["lastGoodSyncAt"] = stamp
3658
+ return cur
3659
+
3660
+ rt.update(CONFIG_KEY, _up, flush="sync")
3661
+ return stamp
3662
+
3663
+
3664
+ def _effective_sync_seconds(preset):
3665
+ """The interval a sync can actually keep: the tenant's preset, floored, and never faster than
3666
+ the deployment's own resync floor (`AIOS_STORE_RESYNC_SECONDS`), which `main.py` applies with
3667
+ `max()`. None for `manual`: a person who asked not to be synced has no schedule to fall
3668
+ behind."""
3669
+ secs = SYNC_PRESETS.get(preset)
3670
+ if secs is None:
3671
+ return None
3672
+ secs = max(int(secs), SYNC_FLOOR_SECONDS)
3673
+ import os
3674
+ try:
3675
+ env = int(str(os.environ.get("AIOS_STORE_RESYNC_SECONDS") or "").strip() or 0)
3676
+ except ValueError:
3677
+ env = 0
3678
+ return max(secs, env)
3679
+
3680
+
3681
+ def sync_freshness(rt, now=None):
3682
+ """C4: is this tenant's Odoo data stale, when was it last synced well, and did the last run
3683
+ fail. PURE over the store reads.
3684
+
3685
+ `stale` is true when the last good sync is older than the effective cadence plus
3686
+ `STALE_GRACE_SECONDS`, or when none has ever been recorded. A `manual` or disconnected
3687
+ (frozen) connector is never stale: it is not behind a schedule it does not have. `failure` is
3688
+ the last run's own reason, its code prefix removed, when that run ended in error.
3689
+ """
3690
+ now = now or _utc_now()
3691
+ try:
3692
+ raw = rt.get(CONFIG_KEY) if rt is not None else None
3693
+ except Exception: # noqa: BLE001
3694
+ raw = None
3695
+ raw = raw if isinstance(raw, dict) else {}
3696
+ cfg = read_config(rt)
3697
+ try:
3698
+ status = rt.get(_ut().ODOO_SYNC_STATUS_KEY) if rt is not None else None
3699
+ except Exception: # noqa: BLE001
3700
+ status = None
3701
+ status = status if isinstance(status, dict) else {}
3702
+ phase = str(status.get("phase") or "unknown")
3703
+ last_good = raw.get("lastGoodSyncAt") or None
3704
+ # Before the first stamp this deployment writes, a status that last read `ok` IS a good sync.
3705
+ if not last_good and phase == "ok":
3706
+ last_good = status.get("lastRun") or None
3707
+ every = _effective_sync_seconds(cfg["syncEvery"])
3708
+ allowed = None if every is None else every + STALE_GRACE_SECONDS
3709
+ stale = False
3710
+ if allowed is not None and not cfg["frozen"]:
3711
+ good_at = _parse_iso(last_good)
3712
+ stale = good_at is None or (now - good_at).total_seconds() > allowed
3713
+ failure = None
3714
+ errors = status.get("errors") if isinstance(status.get("errors"), list) else []
3715
+ if phase == "error" and errors:
3716
+ text = str(errors[0])
3717
+ code, _sep, message = text.partition(": ")
3718
+ if not _sep:
3719
+ code, message = "sync_failed", text
3720
+ failure = {"code": code.strip()[:80], "message": message.strip()[:300],
3721
+ "at": status.get("lastRun") or None}
3722
+ return {"stale": bool(stale), "lastGoodSyncAt": last_good,
3723
+ "schedule": cfg["syncEvery"], "staleAfterSeconds": allowed,
3724
+ "lastRunAt": status.get("lastRun") or None, "phase": phase,
3725
+ "frozen": cfg["frozen"], "failure": failure}
3726
+
3727
+
3728
  def frozen(rt):
3729
  """Has this tenant DISCONNECTED Odoo (R10)? Frozen grids keep every row and every field and
3730
  stop being refreshed — distinct from PAUSED, which is temporary and keeps the credential."""
 
4664
  return False
4665
 
4666
 
4667
+ #: ⭐ S67-T19 — the `limits` effects that REPORT a serving choice rather than withheld rows.
4668
+ #: `read_through` says a database is served THROUGH the mirror with no ceiling at all
4669
+ #: (`core.user_tables.limit_report`), which is the design working, not a failure.
4670
+ INFORMATIONAL_LIMIT_EFFECTS = frozenset({"read_through"})
4671
+
4672
+
4673
+ def failing_limits(limits):
4674
+ """Only the `limits` entries that describe rows a pass did NOT serve, PURE.
4675
+
4676
+ ⛔⛔ STAGING'S `materialization_failed` WAS THIS, NAMED 2026-09-28 FROM ITS OWN RECEIPTS. The
4677
+ rebuild handed its whole `limits` map to the health classifier, which reads EVERY entry as a
4678
+ materialization failure, so the two read-through grains (`ut_odoo_order_lines`,
4679
+ `ut_odoo_gl_lines`, "no ceiling applies to them") failed the connection on every single sync
4680
+ and `odoo_sync_status` could never read `ok`. The report keeps them; only health drops them.
4681
+ """
4682
+ if not isinstance(limits, dict):
4683
+ return limits
4684
+ return {key: entry for key, entry in limits.items()
4685
+ if not (isinstance(entry, dict)
4686
+ and entry.get("effect") in INFORMATIONAL_LIMIT_EFFECTS)}
4687
+
4688
+
4689
+ #: ⭐ S67-T19 — the reconciliation DRIFT a good sync may carry: Odoo keeps taking invoices while a
4690
+ #: rebuild runs, and a hard delete leaves a mirror row until `reconcile_deletes` (every fourth
4691
+ #: pass). Measured on a mirror pulled 25 minutes before its rebuild: invoices 32,980 vs 32,978,
4692
+ #: orders 34,059 vs 34,058, agents 17 vs 18, GL lines 1,024,102 vs 1,024,178, customers 3,715 vs
4693
+ #: 3,716. A stale mirror is nothing like that: staging's unpulled seed was 626 orders and 732
4694
+ #: invoices short. The receipt keeps its exact counts either way; this only decides whether the
4695
+ #: CONNECTION's sync counts as good.
4696
+ RECONCILE_DRIFT_ROWS = 10
4697
+ RECONCILE_DRIFT_RATIO = 0.002
4698
+
4699
+
4700
+ def reconciliation_drift(receipt):
4701
+ """`(difference, tolerance)` for a count-reconciliation receipt, or None when it has no counts."""
4702
+ if not isinstance(receipt, dict):
4703
+ return None
4704
+ source = receipt.get("sourceCount")
4705
+ if isinstance(receipt.get("unexplainedCount"), int):
4706
+ diff = int(receipt["unexplainedCount"])
4707
+ else:
4708
+ mirror = receipt.get("mirrorCount")
4709
+ if not isinstance(source, int) or not isinstance(mirror, int):
4710
+ return None
4711
+ diff = abs(source - mirror)
4712
+ base = source if isinstance(source, int) and source > 0 else 0
4713
+ return diff, max(RECONCILE_DRIFT_ROWS, int(base * RECONCILE_DRIFT_RATIO))
4714
+
4715
+
4716
+ def blocking_failures(database_failures, report):
4717
+ """The database failures that make a sync NOT good, PURE.
4718
+
4719
+ A reconciliation failure whose count drift is within `reconciliation_drift`'s tolerance is
4720
+ recorded against its database and does not fail the connection; every other failure does.
4721
+ """
4722
+ receipts = {}
4723
+ for name in ("databases", "canonicalDatabases"):
4724
+ group = report.get(name) if isinstance(report, dict) else None
4725
+ if isinstance(group, dict):
4726
+ receipts.update(group)
4727
+ out = {}
4728
+ for key, failure in (database_failures or {}).items():
4729
+ if isinstance(failure, dict) and failure.get("code") == "reconciliation_incomplete":
4730
+ drift = reconciliation_drift(receipts.get(key))
4731
+ if drift is not None and drift[0] <= drift[1]:
4732
+ continue
4733
+ out[key] = failure
4734
+ return out
4735
+
4736
+
4737
+ def health_view(report):
4738
+ """The refresh report as the sync-health classifier must read it, PURE.
4739
+
4740
+ Identical to `report` except that `limits` carries only `failing_limits`; the returned report
4741
+ itself (the log line, the Sync report) still names every read-through database.
4742
+ """
4743
+ if not isinstance(report, dict) or not isinstance(report.get("limits"), dict):
4744
+ return report
4745
+ view = dict(report)
4746
+ remaining = failing_limits(report["limits"])
4747
+ if remaining:
4748
+ view["limits"] = remaining
4749
+ else:
4750
+ view.pop("limits", None)
4751
+ return view
4752
+
4753
+
4754
  def refresh_curated(rt, cur, buckets, *, connection_id=None, username="automation",
4755
  today=None, retire=True, on_apply=None, source_client=None):
4756
  """Refresh each enabled database independently; retain failed databases unchanged.
 
5037
  return out
5038
 
5039
 
5040
+ #: ⭐ S67-T19 — the store errors a connection refresh retries ONCE. Staging's rebuild at
5041
+ #: 2026-09-28 16:03Z failed whole with `ProtocolViolation` (SQLSTATE 08P01), which is how the
5042
+ #: DigitalOcean pool (PgBouncer) reports its own timeouts while every lane container shares it;
5043
+ #: nothing was written and the next scheduled pass was a day away. `refresh` is idempotent, so a
5044
+ #: second attempt after a pause is safe; a refusal or any other exception is never retried.
5045
+ TRANSIENT_STORE_ERRORS = frozenset({"ProtocolViolation", "OperationalError", "PoolTimeout",
5046
+ "ConnectionTimeout", "AdminShutdown"})
5047
+ REFRESH_RETRY_SECONDS = 20
5048
+
5049
+
5050
  def refresh_all(rt, tenant, username="automation", cur=None, today=None):
5051
  """Refresh EVERY Odoo connection this tenant holds, one at a time (R4 / R7 / C4).
5052
 
 
5083
  primary = None
5084
  for entry_cid in order:
5085
  named = None if (entry_cid is None or entry_cid == default) else entry_cid
5086
+ for attempt in (1, 2):
5087
+ try:
5088
+ one = refresh(rt, tenant, username=username,
5089
+ cur=(cur if named is None else None),
5090
+ today=today, connection_id=named)
5091
+ break
5092
+ except Exception as exc: # noqa: BLE001
5093
+ # S67-T19: one retry for a TRANSIENT store error only; every other failure is
5094
+ # recorded exactly as before.
5095
+ if attempt == 1 and type(exc).__name__ in TRANSIENT_STORE_ERRORS:
5096
+ _time.sleep(REFRESH_RETRY_SECONDS)
5097
+ continue
5098
+ one = {"tables": {}, "failed": f"{type(exc).__name__}: Odoo connection refresh failed"}
5099
+ break
5100
  reports[str(entry_cid or default or DEFAULT_CONNECTION)] = one
5101
  if named is None and primary is None:
5102
  primary = one
api/routes_connectors.py CHANGED
@@ -31,7 +31,7 @@ from datetime import datetime, timezone
31
  from collections import OrderedDict
32
  from typing import Annotated, Literal
33
 
34
- from fastapi import APIRouter, Body, Depends, Query
35
 
36
  import oauth_connect
37
  from deps import Session, err, require_session, running_main
@@ -326,9 +326,11 @@ TOKEN_CONNECTORS = [
326
  "hint": "Create a Production app client in the Solution Provider Portal, self authorize "
327
  "it, then paste client_id, client_secret, refresh_token, seller_id and "
328
  "marketplace_id.",
329
- "note": "The credential is verified live against your marketplace participations before "
330
- "it is stored. Bulk reads use the Reports API, so a backfill is one document "
331
- "rather than a page loop."},
 
 
332
  ]
333
 
334
  #: ⭐⭐ WAVE 31 · R7 — THE NANGO BREADTH REGISTRY. Owner: *"for Nango, i want to explore as many
@@ -446,6 +448,11 @@ _register_probers()
446
  # W48C-T08 / C6 — the graph is a reader-scoped DTO over tables that exist in THIS workspace,
447
  # never a provider-shaped example. `CONNECTED_PREFIXES` only classifies the connector family;
448
  # `user_tables.is_connected` below is the second proof that a user-named lookalike did not enter.
 
 
 
 
 
449
  def _graph_refusal(connection_key, reason, status="refused"):
450
  return {"connectionKey": str(connection_key or ""), "status": status,
451
  "reason": str(reason or ""), "tables": [], "relationships": []}
@@ -598,7 +605,12 @@ def relationship_graphs(rows, user, rt, uname, is_admin=False):
598
  graphs = {}
599
  connected = set()
600
  for connection_key, row in row_by_key.items():
601
- if row.get("state") == "connected":
 
 
 
 
 
602
  connected.add(connection_key)
603
  graphs[connection_key] = _graph_refusal(
604
  connection_key,
@@ -978,9 +990,21 @@ def directory(rt, uname, is_admin=False, incomplete=None):
978
  else "keychain_personal"),
979
  # Said once, on the row, rather than in a paragraph somewhere (R13): storing the
980
  # key is real and useful, and it is not the same as the data being on screen.
981
- "note": "Storing the key connects the account; reading its data lands in a later "
982
- "release.",
 
 
 
 
 
983
  })
 
 
 
 
 
 
 
984
 
985
  contribute("token", _tokens,
986
  "the token-connector registry could not be composed",
@@ -3791,7 +3815,17 @@ def _amazon_databases(rt, is_admin, spec=None):
3791
  enabled = enablement.get("databases") or {}
3792
  cat = amazon_schema.catalogue()
3793
  tables = cat.get("tables") or {}
3794
- states = cx.sync_state(rt, getattr(rt, "key", "")) if is_admin else None
 
 
 
 
 
 
 
 
 
 
3795
 
3796
  # Which OTHER declared tables are filled from the SAME report document. Derived from the
3797
  # report map so a table added to `REPORT_TYPES` gets this disclosure for free.
@@ -4289,6 +4323,8 @@ def connector_detail(rt, user, uname, is_admin, connector_key, *, databases_offs
4289
  # question about a PERSON and a table, not about an administrator flag alone.
4290
  databases = _detail_databases(rt, bool(is_admin), key, uname=str(uname or ""),
4291
  page=page, fields=fields)
 
 
4292
  budget.check()
4293
  overview = _detail_overview(row, databases, graph)
4294
  if page is not None and page.total:
@@ -4325,6 +4361,36 @@ def connector_detail(rt, user, uname, is_admin, connector_key, *, databases_offs
4325
  "relationships": graph})
4326
 
4327
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4328
  def _set_amazon_database_enablement(database_key, body, session):
4329
  """The testable core of Amazon's tenant-scoped administrator enablement door."""
4330
  if not session.admin:
@@ -4406,16 +4472,46 @@ def connectors_detail(connector_key: str, session: Session = Depends(require_ses
4406
  workspace is connected to. What a member does NOT get is the tenant-wide credential door
4407
  (`canConnect` carries the card's own answer) or the administrator-only Odoo field catalogue.
4408
  """
4409
- detail = connector_detail(
4410
- session.runtime, session.user, session.uname,
4411
- bool(session.admin), connector_key, databases_offset=databases_offset,
4412
- databases_limit=databases_limit, fields=fields)
 
 
 
 
 
 
4413
  if detail is None:
4414
  raise err(404, "unknown_connector",
4415
  "this workspace has no connector with that key")
4416
  return detail
4417
 
4418
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4419
  def _detail_row(rt, uname, is_admin, connector_key):
4420
  row = next((row for row in directory(rt, uname, is_admin)
4421
  if row.get("key") == connector_key), None)
@@ -4429,22 +4525,35 @@ def connector_database_fields(connector_key: str, database_key: str,
4429
  session: Session = Depends(require_session)):
4430
  """The same field disclosure and database access as detail, for one database only."""
4431
  rt = _ConnectorDetailReads(session.runtime)
4432
- _detail_row(rt, session.uname, bool(session.admin), connector_key)
4433
- rows = _detail_databases(rt, bool(session.admin), connector_key, uname=session.uname,
4434
- page=_DatabasePage(database_key=database_key))
4435
- if not rows:
4436
- raise err(404, "unknown_database", "This connector has no visible database with that key.")
4437
- return _safe_connector_status(connector_key, {
4438
- "key": database_key, "fields": rows[0]["fields"], "excluded": rows[0]["excluded"]})
 
 
 
 
 
 
 
4439
 
4440
 
4441
  @router.get("/connectors/{connector_key}/relationships")
4442
  def connector_relationships(connector_key: str, session: Session = Depends(require_session)):
4443
  """Load the permitted graph when the summary client's Relationships tab opens."""
4444
  rt = _ConnectorDetailReads(session.runtime)
4445
- row = _detail_row(rt, session.uname, bool(session.admin), connector_key)
4446
- return _safe_connector_status(connector_key, relationship_graphs(
4447
- [row], session.user, rt, session.uname, bool(session.admin))[connector_key])
 
 
 
 
 
 
4448
 
4449
 
4450
  class _ReplacementConflict(Exception):
 
31
  from collections import OrderedDict
32
  from typing import Annotated, Literal
33
 
34
+ from fastapi import APIRouter, Body, Depends, HTTPException, Query
35
 
36
  import oauth_connect
37
  from deps import Session, err, require_session, running_main
 
326
  "hint": "Create a Production app client in the Solution Provider Portal, self authorize "
327
  "it, then paste client_id, client_secret, refresh_token, seller_id and "
328
  "marketplace_id.",
329
+ # S66-T27: storing is offline (`keychain._test_amazon_entry` probes only on an explicit
330
+ # Test), so this no longer claims the key was verified before it was stored.
331
+ "note": "Choose Test in the Keychain tab to verify the credential live against your "
332
+ "marketplace participations. Bulk reads use the Reports API, so a backfill is one "
333
+ "document rather than a page loop."},
334
  ]
335
 
336
  #: ⭐⭐ WAVE 31 · R7 — THE NANGO BREADTH REGISTRY. Owner: *"for Nango, i want to explore as many
 
448
  # W48C-T08 / C6 — the graph is a reader-scoped DTO over tables that exist in THIS workspace,
449
  # never a provider-shaped example. `CONNECTED_PREFIXES` only classifies the connector family;
450
  # `user_tables.is_connected` below is the second proof that a user-named lookalike did not enter.
451
+ #: The directory states that mean "this workspace holds this connection": connected, stored but
452
+ #: asking to be reconnected, or stored past its rotation deadline (`ConnectorsPage`'s `held`).
453
+ _GRAPH_HELD_STATES = frozenset(("connected", "reconnect", "expired"))
454
+
455
+
456
  def _graph_refusal(connection_key, reason, status="refused"):
457
  return {"connectionKey": str(connection_key or ""), "status": status,
458
  "reason": str(reason or ""), "tables": [], "relationships": []}
 
605
  graphs = {}
606
  connected = set()
607
  for connection_key, row in row_by_key.items():
608
+ # ⭐ S67-T31 / D-718 — A HELD CONNECTION HAS A GRAPH. Staging's Amazon card reads
609
+ # `reconnect` (its stored key has no passing test on record) while 38 `ut_amzn_*` tables
610
+ # are materialised, and the old `== "connected"` test refused the graph as "Connect this
611
+ # provider" over a connection that is plainly there. The nodes are still only tables that
612
+ # exist and that this reader may open, so admitting the held states draws no template.
613
+ if row.get("state") in _GRAPH_HELD_STATES:
614
  connected.add(connection_key)
615
  graphs[connection_key] = _graph_refusal(
616
  connection_key,
 
990
  else "keychain_personal"),
991
  # Said once, on the row, rather than in a paragraph somewhere (R13): storing the
992
  # key is real and useful, and it is not the same as the data being on screen.
993
+ # ⭐ S66-T27 / S67-T31 — EXCEPT AMAZON, whose data DOES land (38 `ut_amzn_*`
994
+ # tables on staging), so the generic sentence told an administrator the opposite
995
+ # of the truth. Amazon carries its own authored note.
996
+ # S67 lane D: so does Meta Ads, whose authored note this line used to overwrite
997
+ # with the generic one; every card now shows its own (Stripe's and Shopify's own
998
+ # note IS the generic sentence, so theirs is unchanged).
999
+ "note": t["note"],
1000
  })
1001
+ # S66-T27 — WHAT `reconnect` MEANS, said on the card. On Amazon it is "a key is stored
1002
+ # but no passing Test is on record for it" (`keychain.entry_verified`), measured on
1003
+ # staging's admin view with the data still syncing. The bare word read as a broken
1004
+ # connection with no way to tell what to do.
1005
+ if rows[-1]["state"] == "reconnect" and t["entry"] == "amazon_sp":
1006
+ rows[-1]["needs"] = ("Amazon access for the stored key is not confirmed yet. "
1007
+ "Choose Test in the Keychain tab, or replace the key.")
1008
 
1009
  contribute("token", _tokens,
1010
  "the token-connector registry could not be composed",
 
3815
  enabled = enablement.get("databases") or {}
3816
  cat = amazon_schema.catalogue()
3817
  tables = cat.get("tables") or {}
3818
+ # ⭐ S67-T31 — A STATUS THE GUARD REFUSES COSTS ITS OWN ROW, NEVER THE MODAL. `sync_state`
3819
+ # trims an over-long cause itself; a credential shape still refuses, and the refusal carries
3820
+ # the guarded rows that passed, so only the refused tables read "Sync status is unavailable
3821
+ # for this database." (a missing status is exactly what `_amazon_database_sync_health`
3822
+ # degrades). Any other failure reading status degrades every row, never the whole page.
3823
+ try:
3824
+ states = cx.sync_state(rt, getattr(rt, "key", "")) if is_admin else None
3825
+ except cx.AmazonStatusSafetyError as refused:
3826
+ states = dict(getattr(refused, "safe_status", None) or {})
3827
+ except Exception: # noqa: BLE001
3828
+ states = {}
3829
 
3830
  # Which OTHER declared tables are filled from the SAME report document. Derived from the
3831
  # report map so a table added to `REPORT_TYPES` gets this disclosure for free.
 
4323
  # question about a PERSON and a table, not about an administrator flag alone.
4324
  databases = _detail_databases(rt, bool(is_admin), key, uname=str(uname or ""),
4325
  page=page, fields=fields)
4326
+ if key == "amazon_sp":
4327
+ databases = _screen_amazon_database_rows(databases)
4328
  budget.check()
4329
  overview = _detail_overview(row, databases, graph)
4330
  if page is not None and page.total:
 
4361
  "relationships": graph})
4362
 
4363
 
4364
+ def _screen_amazon_database_rows(rows):
4365
+ """S67-T31: each Amazon database row answers the status guard ON ITS OWN.
4366
+
4367
+ `_safe_connector_status` still guards the whole detail below, and it used to be the first and
4368
+ only judge, so one oversized scalar in one row aborted every row, the Overview and the
4369
+ Keychain with a bare 500. Here an over-long string is trimmed, and a row that still fails (a
4370
+ credential shape anywhere in it) keeps only its key, its shipped name and its switch, with
4371
+ "Sync status is unavailable for this database." as its status. The refused value is dropped,
4372
+ never echoed.
4373
+ """
4374
+ import connectors_amazon as cx # noqa: PLC0415 - provider owns the guard
4375
+ listed = list(rows or [])
4376
+ safe, _refused = cx.screen_status_rows(dict(enumerate(listed)))
4377
+ out = []
4378
+ for index, row in enumerate(listed):
4379
+ if index in safe:
4380
+ out.append(safe[index])
4381
+ continue
4382
+ key = str((row or {}).get("key") or "")
4383
+ enabled = (row or {}).get("enabled") is True
4384
+ label = LABELS_AMAZON.get(key) or key
4385
+ out.append({"key": key, "label": label, "defaultLabel": label, "native": "",
4386
+ "enabled": enabled,
4387
+ **({"sync": None} if "sync" in (row or {}) else {}),
4388
+ "syncHealth": _amazon_database_sync_health(None, enabled),
4389
+ "fields": [], "excluded": [], "sharesFieldsWith": [],
4390
+ **({"fieldsDeferred": True} if (row or {}).get("fieldsDeferred") else {})})
4391
+ return out
4392
+
4393
+
4394
  def _set_amazon_database_enablement(database_key, body, session):
4395
  """The testable core of Amazon's tenant-scoped administrator enablement door."""
4396
  if not session.admin:
 
4472
  workspace is connected to. What a member does NOT get is the tenant-wide credential door
4473
  (`canConnect` carries the card's own answer) or the administrator-only Odoo field catalogue.
4474
  """
4475
+ try:
4476
+ detail = connector_detail(
4477
+ session.runtime, session.user, session.uname,
4478
+ bool(session.admin), connector_key, databases_offset=databases_offset,
4479
+ databases_limit=databases_limit, fields=fields)
4480
+ except HTTPException:
4481
+ raise
4482
+ except Exception as exc: # noqa: BLE001
4483
+ raise _plain_read_failure(exc, "connector_detail_failed",
4484
+ "The connector details could not be read.")
4485
  if detail is None:
4486
  raise err(404, "unknown_connector",
4487
  "this workspace has no connector with that key")
4488
  return detail
4489
 
4490
 
4491
+ def _plain_read_failure(exc, code, sentence):
4492
+ """S67-T31: an unexpected failure on a connector read answers the app's JSON error shape.
4493
+
4494
+ The owner's modal read "The server answered 500." because a guard refusal escaped as a bare
4495
+ `Internal Server Error` with no body. Every read the modal makes now answers
4496
+ `{error: {code, message}}` with a plain cause instead; the traceback goes to the server log,
4497
+ and no exception text (which can echo a payload) reaches the wire.
4498
+ """
4499
+ import logging # noqa: PLC0415
4500
+ logging.getLogger(__name__).exception("connector read failed: %s", code)
4501
+ name = type(exc).__name__
4502
+ if name in ("StoreUnavailable", "PoolTimeout"):
4503
+ return err(503, "store_unavailable",
4504
+ "The workspace store did not answer in time, so nothing could be read.")
4505
+ try:
4506
+ import connectors_amazon as cx # noqa: PLC0415
4507
+ if isinstance(exc, cx.AmazonStatusSafetyError):
4508
+ return err(500, "connector_status_withheld",
4509
+ "This connector's status could not be shown safely, so it was withheld.")
4510
+ except Exception: # noqa: BLE001
4511
+ pass
4512
+ return err(500, code, sentence)
4513
+
4514
+
4515
  def _detail_row(rt, uname, is_admin, connector_key):
4516
  row = next((row for row in directory(rt, uname, is_admin)
4517
  if row.get("key") == connector_key), None)
 
4525
  session: Session = Depends(require_session)):
4526
  """The same field disclosure and database access as detail, for one database only."""
4527
  rt = _ConnectorDetailReads(session.runtime)
4528
+ try:
4529
+ _detail_row(rt, session.uname, bool(session.admin), connector_key)
4530
+ rows = _detail_databases(rt, bool(session.admin), connector_key, uname=session.uname,
4531
+ page=_DatabasePage(database_key=database_key))
4532
+ if not rows:
4533
+ raise err(404, "unknown_database",
4534
+ "This connector has no visible database with that key.")
4535
+ return _safe_connector_status(connector_key, {
4536
+ "key": database_key, "fields": rows[0]["fields"], "excluded": rows[0]["excluded"]})
4537
+ except HTTPException:
4538
+ raise
4539
+ except Exception as exc: # noqa: BLE001
4540
+ raise _plain_read_failure(exc, "connector_fields_failed",
4541
+ "The fields of this database could not be read.")
4542
 
4543
 
4544
  @router.get("/connectors/{connector_key}/relationships")
4545
  def connector_relationships(connector_key: str, session: Session = Depends(require_session)):
4546
  """Load the permitted graph when the summary client's Relationships tab opens."""
4547
  rt = _ConnectorDetailReads(session.runtime)
4548
+ try:
4549
+ row = _detail_row(rt, session.uname, bool(session.admin), connector_key)
4550
+ return _safe_connector_status(connector_key, relationship_graphs(
4551
+ [row], session.user, rt, session.uname, bool(session.admin))[connector_key])
4552
+ except HTTPException:
4553
+ raise
4554
+ except Exception as exc: # noqa: BLE001
4555
+ raise _plain_read_failure(exc, "connector_relationships_failed",
4556
+ "The relationship graph could not be read.")
4557
 
4558
 
4559
  class _ReplacementConflict(Exception):
api/routes_external.py CHANGED
@@ -728,8 +728,12 @@ def _resolve_external_scope(
728
  if include_schema:
729
  if row["answerable"] or strict_schema:
730
  try:
 
 
 
 
731
  scoped = deps.assistant_read_scope(
732
- session, database, fields=None, filters=None,
733
  )
734
  except HTTPException as exc:
735
  # HOTFIX 2026-09-24: ONE refusing source (measured: a 996,203-row mirror
@@ -1821,8 +1825,11 @@ def _query_database(session: Session, database: str, payload: dict):
1821
 
1822
  # This is the same permissioned record reader the in-app Assistant uses. It resolves the
1823
  # database, field and row walls on every call before this adapter sorts, caps, or aggregates.
 
 
1824
  scoped = deps.assistant_read_scope(
1825
- session, database, fields=None, filters=payload.get("filters"))
 
1826
  visible_fields = list(scoped.get("fields") or [])
1827
  visible_keys = {
1828
  field.get("key") for field in visible_fields
@@ -1851,6 +1858,104 @@ def _query_database(session: Session, database: str, payload: dict):
1851
  sorts.append({"field": rule["field"], "direction": rule["direction"]})
1852
  aggregates = _normalise_aggregates(payload.get("aggregates"), visible_keys)
1853
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1854
  rows = list(scoped.get("records") or [])
1855
  inspected_keys = (set(selected_keys)
1856
  | {rule["field"] for rule in sorts}
@@ -1901,7 +2006,8 @@ def _query_database(session: Session, database: str, payload: dict):
1901
  "filters": copy.deepcopy(scoped.get("filters")),
1902
  "sorts": copy.deepcopy(sorts),
1903
  "records": records,
1904
- "aggregates": _aggregate_records(rows, aggregates),
 
1905
  "page": {"limit": limit, "returned": len(records), "offset": offset,
1906
  "has_more": next_cursor is not None, "next_cursor": next_cursor},
1907
  "caps": {"max_page_size": _QUERY_MAX_LIMIT, "max_sorts": _QUERY_MAX_SORTS,
 
728
  if include_schema:
729
  if row["answerable"] or strict_schema:
730
  try:
731
+ # ⭐ S67-T34 (D-2630): THE FIELD CONTRACT, NOT THE ROWS. Describing a
732
+ # database used to read (and count) every row first, so the largest
733
+ # connected table refused its own schema. "schema" runs every wall and
734
+ # reads no row; sources that are not mirror-served ignore it.
735
  scoped = deps.assistant_read_scope(
736
+ session, database, fields=None, filters=None, mode="schema",
737
  )
738
  except HTTPException as exc:
739
  # HOTFIX 2026-09-24: ONE refusing source (measured: a 996,203-row mirror
 
1825
 
1826
  # This is the same permissioned record reader the in-app Assistant uses. It resolves the
1827
  # database, field and row walls on every call before this adapter sorts, caps, or aggregates.
1828
+ # ⭐ S67-T34: a MIRROR-SERVED database is first resolved schema-only (every wall, no row), so
1829
+ # its aggregates run in SQL over every permitted row and its rows are read only as needed.
1830
  scoped = deps.assistant_read_scope(
1831
+ session, database, fields=None, filters=payload.get("filters"), mode="schema")
1832
+ mirror = scoped.get("source_kind") == "mirror_user_table"
1833
  visible_fields = list(scoped.get("fields") or [])
1834
  visible_keys = {
1835
  field.get("key") for field in visible_fields
 
1858
  sorts.append({"field": rule["field"], "direction": rule["direction"]})
1859
  aggregates = _normalise_aggregates(payload.get("aggregates"), visible_keys)
1860
 
1861
+ server_aggregates = None
1862
+ paged_total = None
1863
+ if mirror:
1864
+ # ⭐⭐ S67-T34 (D-616, D-2631): THE PERMISSION FILTER IS INSIDE THE QUERY. The aggregates
1865
+ # are computed by the mirror in SQL over exactly the rows this caller may read, never
1866
+ # over a fetched slice, and never by pulling a million rows into this process.
1867
+ if aggregates:
1868
+ summary = deps.assistant_read_scope(
1869
+ session, database, fields=None, filters=payload.get("filters"),
1870
+ mode=("aggregate", aggregates))
1871
+ server_aggregates = summary.get("server_aggregates")
1872
+ import assistant_mirror
1873
+ # The summary already counted the permitted population, so a table past the one-pass
1874
+ # ceiling goes straight to SQL paging instead of pulling a first 5,000-row page only to
1875
+ # refuse it.
1876
+ known = (summary.get("total_rows") if aggregates else None)
1877
+ try:
1878
+ if known is not None and int(known) > assistant_mirror.ASSISTANT_READ_MAX:
1879
+ raise err(409, "assistant_source_too_large",
1880
+ f"this database matches {int(known):,} rows for that question, "
1881
+ f"past the {assistant_mirror.ASSISTANT_READ_MAX:,} rows one answer "
1882
+ f"holds in memory")
1883
+ scoped = deps.assistant_read_scope(
1884
+ session, database, fields=None, filters=payload.get("filters"))
1885
+ except HTTPException as exc:
1886
+ info = exc.detail.get("error", {}) if isinstance(exc.detail, dict) else {}
1887
+ if info.get("code") != "assistant_source_too_large":
1888
+ raise
1889
+ # ⭐ RULE 1: PAST THE ONE-PASS CEILING THE ROWS ARE PAGED IN SQL, NOT REFUSED. Only
1890
+ # this page reaches the process. A sort cannot be honoured at this size without
1891
+ # holding every row, so it is refused by name with the fix, never silently dropped.
1892
+ if sorts:
1893
+ raise err(409, "query_sort_too_large",
1894
+ f"{info.get('message') or 'This database is too large to sort here.'} "
1895
+ f"Sorting is refused at this size because it would need every row in "
1896
+ f"memory. Ask without sorts to page it in record order, or narrow it "
1897
+ f"with a filter and sort again.") from exc
1898
+ paged_total = True
1899
+ if paged_total:
1900
+ offset = (0 if payload.get("cursor") is None else None)
1901
+ page_digest = _json_digest({
1902
+ "database": database, "fields": selected_keys, "filters": payload.get("filters"),
1903
+ "sorts": [], "aggregates": aggregates, "limit": limit, "paged": True,
1904
+ })
1905
+ first = deps.assistant_read_scope(
1906
+ session, database, fields=None, filters=payload.get("filters"), mode=("page", 0, 1))
1907
+ snap = _json_digest({
1908
+ "source_version": first.get("source_version"),
1909
+ "visible_fields": [field["key"] for field in visible_fields
1910
+ if isinstance(field, dict) and field.get("key") in visible_keys],
1911
+ "total_rows": first.get("total_rows"),
1912
+ })
1913
+ if offset is None:
1914
+ offset = _decode_query_cursor(session, payload.get("cursor"), page_digest, snap)
1915
+ total_rows = int(first.get("total_rows") or 0)
1916
+ if offset > total_rows:
1917
+ raise err(409, "query_cursor_stale",
1918
+ "The permitted result set changed. Start again without a cursor.")
1919
+ page = deps.assistant_read_scope(
1920
+ session, database, fields=None, filters=payload.get("filters"),
1921
+ mode=("page", offset, limit))
1922
+ page_rows = list(page.get("records") or [])
1923
+ for row in page_rows:
1924
+ _assert_finite_query_value({"pid": row.get("pid"),
1925
+ **{key: row.get(key) for key in selected_keys}})
1926
+ records = [{"pid": copy.deepcopy(row.get("pid")),
1927
+ **{key: copy.deepcopy(row.get(key)) for key in selected_keys}}
1928
+ for row in page_rows]
1929
+ next_offset = offset + limit
1930
+ next_cursor = (_encode_query_cursor(session, page_digest, snap, next_offset)
1931
+ if next_offset < total_rows else None)
1932
+ result = {
1933
+ "database": page.get("database"), "label": page.get("label"),
1934
+ "source_kind": page.get("source_kind"),
1935
+ "source_version": copy.deepcopy(page.get("source_version")),
1936
+ "retrieved_at": page.get("retrieved_at"), "permission_scope_applied": True,
1937
+ "fields": [copy.deepcopy(field) for field in visible_fields
1938
+ if field.get("key") in selected_keys],
1939
+ "filters": copy.deepcopy(page.get("filters")), "sorts": [],
1940
+ "records": records, "aggregates": copy.deepcopy(server_aggregates or []),
1941
+ "page": {"limit": limit, "returned": len(records), "offset": offset,
1942
+ "has_more": next_cursor is not None, "next_cursor": next_cursor},
1943
+ "caps": {"max_page_size": _QUERY_MAX_LIMIT, "max_sorts": _QUERY_MAX_SORTS,
1944
+ "max_aggregates": _QUERY_MAX_AGGREGATES,
1945
+ "max_filter_depth": _QUERY_MAX_FILTER_DEPTH,
1946
+ "max_filter_nodes": _QUERY_MAX_FILTER_NODES,
1947
+ "max_filter_siblings": _QUERY_MAX_FILTER_SIBLINGS},
1948
+ }
1949
+ _assert_finite_query_value(result)
1950
+ audit.record("external.query", session.tenant, session.uname, {
1951
+ "surface": "ai_api",
1952
+ "authentication": session.claims.get("external_auth_type", "api_key"),
1953
+ "field_count": len(selected_keys), "filter_applied": page.get("filters") is not None,
1954
+ "sort_count": 0, "aggregate_count": len(aggregates), "page_size": limit,
1955
+ "returned_count": len(records), "cursor_used": offset > 0,
1956
+ })
1957
+ return result
1958
+
1959
  rows = list(scoped.get("records") or [])
1960
  inspected_keys = (set(selected_keys)
1961
  | {rule["field"] for rule in sorts}
 
2006
  "filters": copy.deepcopy(scoped.get("filters")),
2007
  "sorts": copy.deepcopy(sorts),
2008
  "records": records,
2009
+ "aggregates": (copy.deepcopy(server_aggregates) if server_aggregates is not None
2010
+ else _aggregate_records(rows, aggregates)),
2011
  "page": {"limit": limit, "returned": len(records), "offset": offset,
2012
  "has_more": next_cursor is not None, "next_cursor": next_cursor},
2013
  "caps": {"max_page_size": _QUERY_MAX_LIMIT, "max_sorts": _QUERY_MAX_SORTS,
api/routes_module_index.py CHANGED
@@ -5,8 +5,10 @@ from fastapi import APIRouter, Body, Depends, HTTPException
5
 
6
  from core.sheets import SheetFolderRefusal, validate_folder_tree
7
  from deps import Session, err, module_gate, require_session
 
8
  import routes_assets
9
  import routes_automation
 
10
  from routes_nav import _placeable_top_keys
11
  import voice_control_plane as voice
12
 
@@ -18,10 +20,16 @@ def _sentence(value):
18
  return " ".join(str(value).replace("\u2014", "-").replace("\u2013", "-").split())
19
 
20
 
 
 
 
 
 
 
21
  def _refuse(exc):
22
  status = {"module_index_unknown": 404, "module_index_user_forbidden": 403,
23
  "module_index_item_forbidden": 403, "index_revision_stale": 409}.get(exc.code, 400)
24
- return err(status, exc.code, _sentence(exc.message))
25
 
26
 
27
  def _access(module: str, session: Session = Depends(require_session)):
@@ -57,7 +65,19 @@ def _readable_ids(module, session):
57
  # only listed items, so an unverifiable placement renders no tile. Use local voice
58
  # records, never audience-option assembly, just to verify placement ids.
59
  if module == "app":
60
- return {row["id"] for row in routes_assets.application_index(session=session)["applications"]}
 
 
 
 
 
 
 
 
 
 
 
 
61
  # ⭐⭐ W62-T17 — THE ID-ONLY ACCESSOR THIS COMMENT USED TO ASK FOR NOW EXISTS. It read
62
  # *"all_definitions omits synthetic field/Odoo agents. Keep the complete automation list until
63
  # it has an id-only accessor"*, and the whole Agents rail payload was being built to answer a
 
5
 
6
  from core.sheets import SheetFolderRefusal, validate_folder_tree
7
  from deps import Session, err, module_gate, require_session
8
+ import application_registry
9
  import routes_assets
10
  import routes_automation
11
+ from routes_applications import _may_open
12
  from routes_nav import _placeable_top_keys
13
  import voice_control_plane as voice
14
 
 
20
  return " ".join(str(value).replace("\u2014", "-").replace("\u2013", "-").split())
21
 
22
 
23
+ # D-3282 (standing rule 1): a limit the server cannot lift is reported with its cause and the fix.
24
+ _REFUSAL_SENTENCES = {
25
+ "too_many_folders": "Folders hold at most 200 per rail. Delete or merge a folder, then try again.",
26
+ }
27
+
28
+
29
  def _refuse(exc):
30
  status = {"module_index_unknown": 404, "module_index_user_forbidden": 403,
31
  "module_index_item_forbidden": 403, "index_revision_stale": 409}.get(exc.code, 400)
32
+ return err(status, exc.code, _sentence(_REFUSAL_SENTENCES.get(exc.code, exc.message)))
33
 
34
 
35
  def _access(module: str, session: Session = Depends(require_session)):
 
65
  # only listed items, so an unverifiable placement renders no tile. Use local voice
66
  # records, never audience-option assembly, just to verify placement ids.
67
  if module == "app":
68
+ # S67-T38 (O24): the App home also renders the seeded Finance projections, so the wall
69
+ # admits their ids through the SAME grant filter /nav/applications uses. Never ungated:
70
+ # a Finance card the session cannot open is not placeable.
71
+ stored = {row["id"] for row in routes_assets.application_index(session=session)["applications"]}
72
+ finance = application_registry.finance_application_records(
73
+ may_open=lambda permission: _may_open(session, permission))
74
+ # S67-T41 owner correction: a Content Studio App is bound to a USER table, which the
75
+ # topic-only `/applications` index refuses, so its tile arrives from /nav/applications.
76
+ # Its id is admitted through the registry's own `may_read` (the same read that lists it).
77
+ studios = {row["id"] for row in application_registry.list_apps(
78
+ session.runtime, session.uname, session.admin)
79
+ if row.get("templateKind") == application_registry.CONTENT_STUDIO_TEMPLATE_KIND}
80
+ return stored | {row["id"] for row in finance} | studios
81
  # ⭐⭐ W62-T17 — THE ID-ONLY ACCESSOR THIS COMMENT USED TO ASK FOR NOW EXISTS. It read
82
  # *"all_definitions omits synthetic field/Odoo agents. Keep the complete automation list until
83
  # it has an id-only accessor"*, and the whole Agents rail payload was being built to answer a
api/routes_odoo_tables.py CHANGED
@@ -23,6 +23,7 @@ import hashlib
23
  import hmac
24
  import json
25
  import math
 
26
  import time
27
  from contextlib import contextmanager
28
 
@@ -622,10 +623,27 @@ GRID_SOURCES = {}
622
  _SOURCE_PROVIDERS = []
623
  _SOURCE_ANALYSES = {}
624
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
625
 
626
  def invalidate_sources():
627
  """Forget measured bindings after a connector publishes a new mirror schema."""
628
- GRID_SOURCES.clear()
 
 
 
629
 
630
 
631
  def register_source_provider(fn):
@@ -672,20 +690,60 @@ def _sources():
672
  ⚠ STILL LAZY, for the original reason: `_odoo_sources` names `odoo_relational` constants, and
673
  importing that module at file-import time would drag the Odoo layer into every process that
674
  mounts a router. A provider is a CALLABLE precisely so it stays unimported until first read.
 
 
 
 
675
  """
676
- if GRID_SOURCES:
 
677
  return GRID_SOURCES
678
- for build in list(_SOURCE_PROVIDERS):
 
 
 
679
  try:
680
- extra = build() or {}
681
- except Exception: # noqa: BLE001
682
- # ⛔ ONE PROVIDER'S FAILURE COSTS ITS OWN GRIDS, NEVER THE PAGE. The Odoo grids must
683
- # not go dark because a newer connector's module is unhappy — and vice versa.
684
- continue
685
- if extra:
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
686
  GRID_SOURCES.update(extra)
687
  _ut().register_connected(*extra)
688
- return GRID_SOURCES
689
 
690
 
691
  def _odoo_sources():
@@ -1055,11 +1113,13 @@ def _amazon_sources():
1055
  return {}
1056
 
1057
 
1058
- def require_amazon_mirror(table_key, session, definition=None):
1059
  """Refuse a persisted Amazon stub whose mirror has not loaded, even on a cold registry.
1060
 
1061
  The provider contributes no keys on an Odoo-only mirror. A persisted read-through
1062
  definition still must refuse there instead of falling through to its empty stored rows.
 
 
1063
  """
1064
  if not str(table_key).startswith("ut_amzn_"):
1065
  return
@@ -1069,7 +1129,8 @@ def require_amazon_mirror(table_key, session, definition=None):
1069
  if table_key not in amazon.SOURCE:
1070
  return
1071
  if definition is None:
1072
- definition = _defn_or_refuse(session, table_key, defs_only=True, scope_applied=True)
 
1073
  try:
1074
  cur, mismatch = _mirror_cur(session, table_key)
1075
  except RuntimeError as exc:
@@ -1086,8 +1147,17 @@ def require_amazon_mirror(table_key, session, definition=None):
1086
  raise err(503, "amazon_mirror_not_loaded", current["missing"])
1087
  # A dynamically oversized snapshot may have a durable stub before this process
1088
  # has measured it. Admit its binding without changing another source's registry.
 
 
 
 
1089
  if spec is None or spec.get("missing"):
1090
- GRID_SOURCES[table_key] = current
 
 
 
 
 
1091
  finally:
1092
  cur.close()
1093
 
@@ -1322,18 +1392,14 @@ def _source_for(cur, table_key):
1322
  if module_cache_source(key) is not None:
1323
  return None
1324
  spec = _sources().get(key)
1325
- if not spec and key.startswith("ut_amzn_") and not any(
1326
- k.startswith("ut_amzn_") for k in GRID_SOURCES):
1327
  # HOTFIX 2026-09-27: a registry built at boot BEFORE the Amazon mirror restore holds no
1328
  # Amazon key, and only `amazon_relational.refresh_state` invalidates it, which the resync
1329
  # runs AFTER the Odoo rebuild. On staging that rebuild hung for 14+ minutes, so every
1330
  # read-through Amazon grid answered "no read-through binding". Ask the Amazon provider
1331
  # alone, once it can answer; a registry that already knows one Amazon key is not re-asked.
1332
- extra = _amazon_sources()
1333
- if extra:
1334
- GRID_SOURCES.update(extra)
1335
- _ut().register_connected(*extra)
1336
- spec = GRID_SOURCES.get(key)
1337
  if not spec:
1338
  return None
1339
  if spec.get("missing"):
@@ -1721,11 +1787,133 @@ def _related_source_value(session, entry, record):
1721
 
1722
 
1723
  def _materialised_table(table_key):
1724
- """Storage dispatch, independent of the browser's fallible status roster."""
1725
- return module_cache_source(table_key) is not None or table_key not in _sources()
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1726
 
1727
 
1728
- def _traversal_defn_or_refuse(session, table_key):
1729
  """R50 / C4: admit an intermediate after the caller has established both end grants.
1730
 
1731
  The session may already open both ends of a declared two-hop link. Its intermediate
@@ -1733,7 +1921,7 @@ def _traversal_defn_or_refuse(session, table_key):
1733
  read still applies the row wall, hidden-field closure, BU scope and mirror guard.
1734
  """
1735
  ut = _ut()
1736
- st = ut.lend_defs(session.runtime)
1737
  defn = ut.get(table_key, st=st)
1738
  if not defn:
1739
  raise err(404, "unknown_table", "that database does not exist")
@@ -1741,21 +1929,26 @@ def _traversal_defn_or_refuse(session, table_key):
1741
 
1742
 
1743
  def _relation_rows(session, table, columns, *, ids=None, match=None, where=None,
1744
- traversal_of=None):
1745
  """Internal join values, after the ordinary row wall, with no row-count ceiling.
1746
 
1747
  Join columns may be hidden on the wire. Only identities leave the resolver; the native
1748
  payload builders still apply their complete hidden-field closure before returning cells.
1749
  With traversal_of, the caller must already have established both ends of the declared
1750
  edge named by that key. Only join values leave this intermediate read, never a cell.
 
 
 
 
 
1751
  """
1752
  import core.perm_scope as perm_scope
1753
  import core.relations as relations
1754
 
1755
  columns = set(columns) | {relations.IDENTITY_COL}
1756
  if not _materialised_table(table):
1757
- read = (_compiled_read(table, session, traversal_intermediate=True)
1758
- if traversal_of is not None else _compiled_read(table, session))
1759
  spec = read["spec"]
1760
  bindings = dict(spec["cols"], pid=(spec["id"], int))
1761
  if columns - set(bindings):
@@ -1778,11 +1971,16 @@ def _relation_rows(session, table, columns, *, ids=None, match=None, where=None,
1778
 
1779
  # This is an internal join, never a cell response. Apply the same permanent wall on the
1780
  # complete contract before taking any join value, including a join on a hidden column.
1781
- if traversal_of is None and not perm_scope.may_read(session.user, table, st=session.runtime):
 
1782
  raise err(403, "forbidden_table", "This account cannot open the linked database.")
1783
  if module_cache_source(table) is not None:
1784
  session.require(table)
1785
- fields, rows = perm_scope._read(table, session.user, session.runtime)
 
 
 
 
1786
  rows = perm_scope.apply_row_scope(rows, session.user, table, fields, st=session.runtime)
1787
  if where:
1788
  raise err(409, "relation_target_unavailable", "This relation needs a connected database predicate.")
@@ -2570,7 +2768,8 @@ def _may_see_view(session, vid, store):
2570
 
2571
 
2572
  def _compiled_read(table_key, session, *, filters=None, filterConj="and", sorts=None,
2573
- search=None, tree=_TREE_UNSET, related=None, traversal_intermediate=False):
 
2574
  """EVERYTHING THAT DECIDES **WHICH ROWS** A CONNECTED GRID MAY ANSWER OVER, compiled once.
2575
 
2576
  Returns `{defn, fields, cur, spec, cols, base_where, wall_params, where, params, limits,
@@ -2630,10 +2829,12 @@ def _compiled_read(table_key, session, *, filters=None, filterConj="and", sorts=
2630
  # tenant #0's eight databases is read-through. Left un-applied, an administrator could set a
2631
  # filter in Manage user, see it saved, and the scoped user would meet a 409 where their rows
2632
  # used to be. So the wall is APPLIED here, in SQL, three paragraphs down.
 
 
2633
  if traversal_intermediate:
2634
- defn = _traversal_defn_or_refuse(session, table_key)
2635
  else:
2636
- defn = _defn_or_refuse(session, table_key, defs_only=True, scope_applied=True)
2637
  fields = None
2638
  for _bucket, key, _label, mk_fields in rel.TABLES:
2639
  if key == table_key:
@@ -3105,7 +3306,12 @@ def odoo_table_rows(table_key: str,
3105
  "limit, filters, sorts and search in the query string.")
3106
  ids = _record_ids(body)
3107
 
3108
- require_amazon_mirror(table_key, session)
 
 
 
 
 
3109
  if _materialised_table(table_key):
3110
  return _materialised_window(table_key, session, offset, limit, filters, filterConj,
3111
  sorts, search, related, groupBy, groupKey, ids=ids)
@@ -3116,8 +3322,11 @@ def odoo_table_rows(table_key: str,
3116
  # is a page of* - and that is provable only while there is one of it. What stays here is what
3117
  # a WINDOW alone needs: the total order, the projection, the overlay merge and the two
3118
  # sentences a page earns (`window_clamped`, the deep-page walk).
 
 
 
3119
  read = _compiled_read(table_key, session, filters=filters, filterConj=filterConj,
3120
- sorts=sorts, search=search, related=related)
3121
  read = _restrict_row_ids(read, ids)
3122
  defn, fields, cur, spec = read["defn"], read["fields"], read["cur"], read["spec"]
3123
  cols, limits, frm = read["cols"], read["limits"], read["frm"]
@@ -3184,14 +3393,16 @@ def odoo_table_rows(table_key: str,
3184
 
3185
  def read_amazon_targets(target, column, values):
3186
  if target not in _opened:
3187
- _opened[target] = _may_open(session, target)
3188
  if not _opened[target]:
3189
  return []
3190
  if not _materialised_table(target):
3191
- return _relation_rows(session, target, [column], match=(column, values))
 
3192
  if target not in _stored:
3193
  _stored[target] = _relation_rows(
3194
- session, target, sorted(_stored_cols.get(target, set()) | {column}))
 
3195
  wanted = {str(value) for value in values}
3196
  # The same string comparison `_relation_rows`' own `match=` applies to a stored table.
3197
  return [row for row in _stored[target] if str(row.get(column)) in wanted]
@@ -3214,11 +3425,14 @@ def odoo_table_rows(table_key: str,
3214
  # the wall and the predicate, so the argument it demands is the list we just fetched.
3215
  # ⚠ It is NOT a permission wall (its header says so twice); `_defn_or_refuse` above already
3216
  # answered "may this session open this surface".
3217
- shared_defs = _so().fields(table_key, st=session.runtime)
 
 
 
3218
  if shared_defs:
3219
  fields = list(fields) + [dict(f, source="overlay") for f in shared_defs.values()]
3220
  for pid, cells in _so().cells(table_key, [r["pid"] for r in rows_src],
3221
- st=session.runtime).items():
3222
  overlays.setdefault(pid, {}).update(cells)
3223
  # RECOMPUTED ON THE **MERGED** CONTRACT, and that is not belt-and-braces. The closure above
3224
  # ran before `shared_defs` appended this database's tenant-wide overlay columns, so a formula
@@ -3549,9 +3763,11 @@ def odoo_table_aggregates(table_key: str, body: dict = Body(default=None),
3549
  # who assumed both were bodies would have wired the rows and left the summaries answering over
3550
  # the entire database under a tab that names one record. `_compiled_read` accepts either shape,
3551
  # so the two doors cannot pin differently without this argument being deleted.
 
 
3552
  read = _compiled_read(table_key, session, tree=query["filters"],
3553
  filterConj=query["filterConj"], search=query["search"],
3554
- related=payload.get("related"))
3555
  read = _restrict_row_ids(read, ids)
3556
  out = _aggregate_over(read["cur"], read["spec"], read["cols"], read["where"],
3557
  read["params"], read["frm"], aggs, group_by=group_by,
 
23
  import hmac
24
  import json
25
  import math
26
+ import threading
27
  import time
28
  from contextlib import contextmanager
29
 
 
623
  _SOURCE_PROVIDERS = []
624
  _SOURCE_ANALYSES = {}
625
 
626
+ #: S67-T28: `GRID_SOURCES` is PUBLISHED WHOLE, never seen half built. The first build asks every
627
+ #: provider in turn, and the Amazon one runs count(*) queries; the old loop added each provider's
628
+ #: keys to the shared dict as it went, and returned the dict to any caller that found it
629
+ #: non-empty. So a concurrent request saw Odoo's keys with no Amazon key, answered
630
+ #: `_materialised_table("ut_amzn_orders") == True`, and a 559,363-row read-through target was read
631
+ #: as a stored table: a first-page 500 (lane D, 2026-09-28). Now a build fills a LOCAL dict under
632
+ #: this lock and publishes it in one `dict.update`; a reader waits on the lock until
633
+ #: `_SOURCES_BUILT` says a whole build is visible. An admission (`require_amazon_mirror`, the
634
+ #: Amazon fallback) happens only after a build has been published, so it can never stand in
635
+ #: for one either.
636
+ _SOURCES_LOCK = threading.RLock()
637
+ _SOURCES_BUILT = False
638
+ _SOURCES_BUILDER = None # the thread inside a build, so a re-entrant call cannot recurse
639
+
640
 
641
  def invalidate_sources():
642
  """Forget measured bindings after a connector publishes a new mirror schema."""
643
+ global _SOURCES_BUILT
644
+ with _SOURCES_LOCK:
645
+ _SOURCES_BUILT = False
646
+ GRID_SOURCES.clear()
647
 
648
 
649
  def register_source_provider(fn):
 
690
  ⚠ STILL LAZY, for the original reason: `_odoo_sources` names `odoo_relational` constants, and
691
  importing that module at file-import time would drag the Odoo layer into every process that
692
  mounts a router. A provider is a CALLABLE precisely so it stays unimported until first read.
693
+
694
+ ⭐ S67-T28: built into a LOCAL dict under `_SOURCES_LOCK` and published in one step (see the
695
+ lock's comment). An empty registry still means "build" (gates clear it to force a rebuild),
696
+ and so does one that holds only admissions made since the last invalidation.
697
  """
698
+ global _SOURCES_BUILT, _SOURCES_BUILDER
699
+ if _SOURCES_BUILT and GRID_SOURCES:
700
  return GRID_SOURCES
701
+ with _SOURCES_LOCK:
702
+ if (_SOURCES_BUILT and GRID_SOURCES) or _SOURCES_BUILDER == threading.get_ident():
703
+ return GRID_SOURCES
704
+ _SOURCES_BUILDER = threading.get_ident()
705
  try:
706
+ built = {}
707
+ for build in list(_SOURCE_PROVIDERS):
708
+ try:
709
+ extra = build() or {}
710
+ except Exception: # noqa: BLE001
711
+ # ⛔ ONE PROVIDER'S FAILURE COSTS ITS OWN GRIDS, NEVER THE PAGE. The Odoo
712
+ # grids must not go dark because a newer connector's module is unhappy, and
713
+ # vice versa.
714
+ continue
715
+ if extra:
716
+ built.update(extra)
717
+ _ut().register_connected(*extra)
718
+ # A key admitted since the last invalidation was measured at least as recently as
719
+ # this build, so it stands; everything else comes from the build. ONE update, so a
720
+ # lock-free reader of the dict sees the old entry or the new one, never a gap.
721
+ GRID_SOURCES.update({**built, **GRID_SOURCES})
722
+ _SOURCES_BUILT = True
723
+ finally:
724
+ _SOURCES_BUILDER = None
725
+ return GRID_SOURCES
726
+
727
+
728
+ def _learn_amazon_sources():
729
+ """Publish the Amazon provider's keys into a registry that was built without any of them.
730
+
731
+ HOTFIX 2026-09-27 (moved here by S67-T28 so every door shares it): a registry built at boot
732
+ BEFORE the Amazon mirror restore holds no Amazon key, and only `refresh_state` invalidates
733
+ it. `_source_for` learned them on demand; `_materialised_table` did not, so a read-through
734
+ Amazon LINK TARGET (orders, 559k rows) was dispatched as a stored table and refused as more
735
+ than one window. A registry that already knows one Amazon key is not re-asked.
736
+ """
737
+ _sources()
738
+ if any(k.startswith("ut_amzn_") for k in list(GRID_SOURCES)):
739
+ return
740
+ extra = _amazon_sources()
741
+ if not extra:
742
+ return
743
+ with _SOURCES_LOCK:
744
+ if not any(k.startswith("ut_amzn_") for k in list(GRID_SOURCES)):
745
  GRID_SOURCES.update(extra)
746
  _ut().register_connected(*extra)
 
747
 
748
 
749
  def _odoo_sources():
 
1113
  return {}
1114
 
1115
 
1116
+ def require_amazon_mirror(table_key, session, definition=None, st=None):
1117
  """Refuse a persisted Amazon stub whose mirror has not loaded, even on a cold registry.
1118
 
1119
  The provider contributes no keys on an Odoo-only mirror. A persisted read-through
1120
  definition still must refuse there instead of falling through to its empty stored rows.
1121
+ S67-T28: `st` is a definitions snapshot the caller already holds (`_page_defs`), so the
1122
+ window route stops paying a second definitions projection for this one check.
1123
  """
1124
  if not str(table_key).startswith("ut_amzn_"):
1125
  return
 
1129
  if table_key not in amazon.SOURCE:
1130
  return
1131
  if definition is None:
1132
+ definition = _defn_or_refuse(session, table_key, st=st, defs_only=True,
1133
+ scope_applied=True)
1134
  try:
1135
  cur, mismatch = _mirror_cur(session, table_key)
1136
  except RuntimeError as exc:
 
1147
  raise err(503, "amazon_mirror_not_loaded", current["missing"])
1148
  # A dynamically oversized snapshot may have a durable stub before this process
1149
  # has measured it. Admit its binding without changing another source's registry.
1150
+ # ⛔ S67-T28: ONLY INTO A PUBLISHED BUILD, and never as the registry's only Amazon
1151
+ # key. Admitted into an empty or Amazon-less registry, this one key used to make
1152
+ # `_sources()` skip its build, so the grid resolved while its link targets
1153
+ # (orders, read-through) were dispatched as stored tables: a first-page 500.
1154
  if spec is None or spec.get("missing"):
1155
+ _learn_amazon_sources()
1156
+ with _SOURCES_LOCK:
1157
+ _sources()
1158
+ held = GRID_SOURCES.get(table_key)
1159
+ if held is None or held.get("missing"):
1160
+ GRID_SOURCES[table_key] = current
1161
  finally:
1162
  cur.close()
1163
 
 
1392
  if module_cache_source(key) is not None:
1393
  return None
1394
  spec = _sources().get(key)
1395
+ if not spec and key.startswith("ut_amzn_"):
 
1396
  # HOTFIX 2026-09-27: a registry built at boot BEFORE the Amazon mirror restore holds no
1397
  # Amazon key, and only `amazon_relational.refresh_state` invalidates it, which the resync
1398
  # runs AFTER the Odoo rebuild. On staging that rebuild hung for 14+ minutes, so every
1399
  # read-through Amazon grid answered "no read-through binding". Ask the Amazon provider
1400
  # alone, once it can answer; a registry that already knows one Amazon key is not re-asked.
1401
+ _learn_amazon_sources()
1402
+ spec = GRID_SOURCES.get(key)
 
 
 
1403
  if not spec:
1404
  return None
1405
  if spec.get("missing"):
 
1787
 
1788
 
1789
  def _materialised_table(table_key):
1790
+ """Storage dispatch, independent of the browser's fallible status roster.
1791
+
1792
+ ⛔ S67-T28: an Amazon key the registry does not hold is asked of the Amazon provider first
1793
+ (`_learn_amazon_sources`, the same fallback `_source_for` takes), so a registry built before
1794
+ the Amazon mirror loaded cannot dispatch a read-through Amazon table as a stored one.
1795
+ """
1796
+ if module_cache_source(table_key) is not None:
1797
+ return True
1798
+ if table_key in _sources():
1799
+ return False
1800
+ if str(table_key).startswith("ut_amzn_"):
1801
+ _learn_amazon_sources()
1802
+ return table_key not in GRID_SOURCES
1803
+ return True
1804
+
1805
+
1806
+ #: ⭐ S67-T28 (R38, D-3480 point 1) — the tenant's table DEFINITIONS and a stored link target's
1807
+ #: ROWS, each held against the durable `user_tables` revision it was read at. A grouped Amazon page
1808
+ #: used to re-read the definitions projection once for its own wall and once more for EVERY link
1809
+ #: target, plus the stored listings entry, on every page; on staging each of those reads is one
1810
+ #: large JSONB projection (measured 33 to 186 s a page under load, 2026-09-28). Every `put` and
1811
+ #: `update` bumps the revision column in the same statement, so an unchanged token proves the
1812
+ #: bytes unchanged; the token is read BEFORE the value, so a write racing the read can only cache
1813
+ #: newer bytes under the older token (a miss next time, never a stale hit). ⚠ Nothing cached here
1814
+ #: is a permission: the wall (`may_read`, `apply_row_scope`, the compiled predicate) is evaluated
1815
+ #: per request against the session's own user, only the bytes it evaluates over are reused.
1816
+ _REV_MEMO: dict = {}
1817
+ _REV_MEMO_MAX = 64
1818
+ # Route handlers run on a thread pool: the lock makes the evict (`next(iter(...))`) and the
1819
+ # insert one step, so a concurrent insert can never raise "dictionary changed size".
1820
+ _REV_MEMO_LOCK = threading.Lock()
1821
+ #: "No token was handed in, read one." Distinct from None, which means "unreadable, hold nothing".
1822
+ #: It is the `...` literal (a singleton) so a signature can spell its default `...` and still
1823
+ #: define when `verify_grid_ux.py` execs `_relation_rows` on its own, without this module name.
1824
+ _UNREAD = ...
1825
+
1826
+
1827
+ def _user_tables_token(rt):
1828
+ """The durable change token of this tenant's `user_tables` bucket, or None when unreadable."""
1829
+ try:
1830
+ return rt.revision(_ut().STORE_KEY)["token"]
1831
+ except Exception: # noqa: BLE001
1832
+ return None
1833
+
1834
+
1835
+ def _rev_memo(kind, rt, name, read, keep, clone, token=_UNREAD):
1836
+ """`read()`, reused while this tenant's `user_tables` revision is unchanged.
1837
+
1838
+ ⛔ `clone` runs on the way in AND on every hit, so a caller that edits what it was handed
1839
+ cannot edit the next request's answer. `keep(value)` decides what may be held: an empty
1840
+ answer never is (it is the shape a failed read takes, and caching it would make one outage
1841
+ outlive itself), and neither is the whole-document fallback `all_defs` takes on a failure.
1842
+ `token` is one this REQUEST already read (`_page_defs`), so a page pays one revision round
1843
+ trip, not one per memo. It was read before any value this call reads, which is the only
1844
+ ordering the staleness argument above needs.
1845
+ """
1846
+ if token is _UNREAD:
1847
+ token = _user_tables_token(rt)
1848
+ tenant = getattr(rt, "key", None)
1849
+ slot = (kind, tenant, name)
1850
+ if token is not None and tenant:
1851
+ with _REV_MEMO_LOCK:
1852
+ hit = _REV_MEMO.get(slot)
1853
+ if hit is not None and hit[0] == token:
1854
+ return clone(hit[1])
1855
+ value = read()
1856
+ if token is not None and tenant and keep(value):
1857
+ held = (token, clone(value))
1858
+ with _REV_MEMO_LOCK:
1859
+ if slot not in _REV_MEMO and len(_REV_MEMO) >= _REV_MEMO_MAX:
1860
+ _REV_MEMO.pop(next(iter(_REV_MEMO)), None)
1861
+ _REV_MEMO[slot] = held
1862
+ return value
1863
+
1864
+
1865
+ def _page_defs(session):
1866
+ """ONE lent definitions snapshot for a whole `/rows` page: its own wall and every link target's.
1867
+
1868
+ Returns `(st, token)`: the lent snapshot, and the `user_tables` revision it was checked
1869
+ against (None when unreadable), which the page hands to `_stored_link_rows` so a stored link
1870
+ target does not pay a second revision round trip.
1871
+ The same `lend_defs` the table wall takes for itself (`_defn_or_refuse`, D-213), read once per
1872
+ `user_tables` revision instead of once per question. Kept only when every definition really is
1873
+ a projection (`store.is_projected`), because `all_defs` silently falls back to the whole
1874
+ 28 MB document on a failed read and that must never be held, let alone copied per request.
1875
+ ⚠ The snapshot is a fresh `_Lent` per call, so the `object_shares` and `__shared` buckets it
1876
+ lends lazily live for this one request and are never carried to the next.
1877
+ """
1878
+ import copy
1879
+ import core.store as store
1880
+
1881
+ ut = _ut()
1882
+ rt = session.runtime
1883
+ token = _user_tables_token(rt)
1884
+
1885
+ def keep(v):
1886
+ tables = [d for d in (v or {}).values() if isinstance(d, dict)]
1887
+ return bool(tables) and all(store.is_projected(d) for d in tables)
1888
+
1889
+ defs = _rev_memo("defs", rt, ut.STORE_KEY, lambda: ut.all_defs(rt),
1890
+ keep=keep, clone=copy.deepcopy, token=token)
1891
+ return ut.lend(rt, **{ut.STORE_KEY: defs}), token
1892
+
1893
+
1894
+ def _stored_link_rows(session, table, token=_UNREAD):
1895
+ """`perm_scope._read` for a STORED `ut_*` link target, reused per `user_tables` revision.
1896
+
1897
+ ⚠ Only a table whose rows live in `user_tables` qualifies: a registered row source (a module
1898
+ cache, an app reader) or a read-through binding answers from somewhere this token does not
1899
+ watch, so those read exactly as before. The wall is NOT applied here; the caller applies
1900
+ `apply_row_scope` for its own user on every request. Holding it across users is sound only
1901
+ because `perm_scope._read_user_table` never consults `user` for a `ut_*` key: every
1902
+ user-dependent step (hidden fields, row wall, BU scope) sits above it, in the caller.
1903
+ """
1904
+ import core.perm_scope as perm_scope
1905
+
1906
+ rt = session.runtime
1907
+ if (not str(table).startswith(_ut().KEY_PREFIX) or table in perm_scope._ROW_SOURCES
1908
+ or module_cache_source(table) is not None or not _materialised_table(table)):
1909
+ return perm_scope._read(table, session.user, rt)
1910
+ return _rev_memo("rows", rt, table, lambda: perm_scope._read(table, session.user, rt),
1911
+ keep=lambda v: bool(v[1]),
1912
+ clone=lambda v: ([dict(f) for f in v[0]], [dict(r) for r in v[1]]),
1913
+ token=token)
1914
 
1915
 
1916
+ def _traversal_defn_or_refuse(session, table_key, st=None):
1917
  """R50 / C4: admit an intermediate after the caller has established both end grants.
1918
 
1919
  The session may already open both ends of a declared two-hop link. Its intermediate
 
1921
  read still applies the row wall, hidden-field closure, BU scope and mirror guard.
1922
  """
1923
  ut = _ut()
1924
+ st = st if st is not None else ut.lend_defs(session.runtime)
1925
  defn = ut.get(table_key, st=st)
1926
  if not defn:
1927
  raise err(404, "unknown_table", "that database does not exist")
 
1929
 
1930
 
1931
  def _relation_rows(session, table, columns, *, ids=None, match=None, where=None,
1932
+ traversal_of=None, st=None, rev=...): # `...` IS `_UNREAD`
1933
  """Internal join values, after the ordinary row wall, with no row-count ceiling.
1934
 
1935
  Join columns may be hidden on the wire. Only identities leave the resolver; the native
1936
  payload builders still apply their complete hidden-field closure before returning cells.
1937
  With traversal_of, the caller must already have established both ends of the declared
1938
  edge named by that key. Only join values leave this intermediate read, never a cell.
1939
+ S67-T28: `st` is a lent DEFINITIONS snapshot the caller already holds (`_page_defs`); the wall
1940
+ is asked of it instead of re-reading every definition per target. A stored target's rows come
1941
+ through `_stored_link_rows`, reused per `user_tables` revision; its wall still runs here.
1942
+ `rev` is the revision token `_page_defs` already read for this request; absent, the stored
1943
+ target is read directly, as before S67-T28.
1944
  """
1945
  import core.perm_scope as perm_scope
1946
  import core.relations as relations
1947
 
1948
  columns = set(columns) | {relations.IDENTITY_COL}
1949
  if not _materialised_table(table):
1950
+ read = (_compiled_read(table, session, traversal_intermediate=True, st=st)
1951
+ if traversal_of is not None else _compiled_read(table, session, st=st))
1952
  spec = read["spec"]
1953
  bindings = dict(spec["cols"], pid=(spec["id"], int))
1954
  if columns - set(bindings):
 
1971
 
1972
  # This is an internal join, never a cell response. Apply the same permanent wall on the
1973
  # complete contract before taking any join value, including a join on a hidden column.
1974
+ if traversal_of is None and not perm_scope.may_read(
1975
+ session.user, table, st=st if st is not None else session.runtime):
1976
  raise err(403, "forbidden_table", "This account cannot open the linked database.")
1977
  if module_cache_source(table) is not None:
1978
  session.require(table)
1979
+ # The revision memo serves a caller that handed this request's token (the page's link fills,
1980
+ # S67-T28); any other caller reads exactly as before, which is also what lets
1981
+ # `verify_grid_ux.py` exec this function alone with a stubbed `perm_scope`.
1982
+ fields, rows = (perm_scope._read(table, session.user, session.runtime) if rev is ...
1983
+ else _stored_link_rows(session, table, token=rev))
1984
  rows = perm_scope.apply_row_scope(rows, session.user, table, fields, st=session.runtime)
1985
  if where:
1986
  raise err(409, "relation_target_unavailable", "This relation needs a connected database predicate.")
 
2768
 
2769
 
2770
  def _compiled_read(table_key, session, *, filters=None, filterConj="and", sorts=None,
2771
+ search=None, tree=_TREE_UNSET, related=None, traversal_intermediate=False,
2772
+ st=None):
2773
  """EVERYTHING THAT DECIDES **WHICH ROWS** A CONNECTED GRID MAY ANSWER OVER, compiled once.
2774
 
2775
  Returns `{defn, fields, cur, spec, cols, base_where, wall_params, where, params, limits,
 
2829
  # tenant #0's eight databases is read-through. Left un-applied, an administrator could set a
2830
  # filter in Manage user, see it saved, and the scoped user would meet a 409 where their rows
2831
  # used to be. So the wall is APPLIED here, in SQL, three paragraphs down.
2832
+ # S67-T28: `st` lends a definitions snapshot the caller already holds (`_page_defs`), the
2833
+ # same `st=` `_defn_or_refuse` has always accepted. None keeps its own `lend_defs` read.
2834
  if traversal_intermediate:
2835
+ defn = _traversal_defn_or_refuse(session, table_key, st=st)
2836
  else:
2837
+ defn = _defn_or_refuse(session, table_key, st=st, defs_only=True, scope_applied=True)
2838
  fields = None
2839
  for _bucket, key, _label, mk_fields in rel.TABLES:
2840
  if key == table_key:
 
3306
  "limit, filters, sorts and search in the query string.")
3307
  ids = _record_ids(body)
3308
 
3309
+ # S67-T28: an Amazon grid's page snapshot is taken BEFORE the mirror check, so that check
3310
+ # asks it instead of reading its own definitions projection (one store round trip fewer on
3311
+ # every Amazon page). Not reordered past it: the check may register this grid's binding,
3312
+ # which is what `_materialised_table` below then reads.
3313
+ page = _page_defs(session) if str(table_key).startswith("ut_amzn_") else None
3314
+ require_amazon_mirror(table_key, session, st=page[0] if page else None)
3315
  if _materialised_table(table_key):
3316
  return _materialised_window(table_key, session, offset, limit, filters, filterConj,
3317
  sorts, search, related, groupBy, groupKey, ids=ids)
 
3322
  # is a page of* - and that is provable only while there is one of it. What stays here is what
3323
  # a WINDOW alone needs: the total order, the projection, the overlay merge and the two
3324
  # sentences a page earns (`window_clamped`, the deep-page walk).
3325
+ # S67-T28 (D-3480 point 1): ONE definitions snapshot answers this page's own wall and every
3326
+ # link target's below, re-read only when `user_tables` has moved (`_page_defs`).
3327
+ page_st, page_rev = page if page is not None else _page_defs(session)
3328
  read = _compiled_read(table_key, session, filters=filters, filterConj=filterConj,
3329
+ sorts=sorts, search=search, related=related, st=page_st)
3330
  read = _restrict_row_ids(read, ids)
3331
  defn, fields, cur, spec = read["defn"], read["fields"], read["cur"], read["spec"]
3332
  cols, limits, frm = read["cols"], read["limits"], read["frm"]
 
3393
 
3394
  def read_amazon_targets(target, column, values):
3395
  if target not in _opened:
3396
+ _opened[target] = _may_open(session, target, st=page_st)
3397
  if not _opened[target]:
3398
  return []
3399
  if not _materialised_table(target):
3400
+ return _relation_rows(session, target, [column], match=(column, values),
3401
+ st=page_st, rev=page_rev)
3402
  if target not in _stored:
3403
  _stored[target] = _relation_rows(
3404
+ session, target, sorted(_stored_cols.get(target, set()) | {column}),
3405
+ st=page_st, rev=page_rev)
3406
  wanted = {str(value) for value in values}
3407
  # The same string comparison `_relation_rows`' own `match=` applies to a stored table.
3408
  return [row for row in _stored[target] if str(row.get(column)) in wanted]
 
3425
  # the wall and the predicate, so the argument it demands is the list we just fetched.
3426
  # ⚠ It is NOT a permission wall (its header says so twice); `_defn_or_refuse` above already
3427
  # answered "may this session open this surface".
3428
+ # S67-T28: through `page_st`, which lends a `__shared` bucket lazily ONCE for this request
3429
+ # (`user_tables._Lent`), so `fields` and `cells` share one read of the stratum instead of two.
3430
+ # Both only read it (`shared_overlay._read` copies the top level, `cells` copies each row).
3431
+ shared_defs = _so().fields(table_key, st=page_st)
3432
  if shared_defs:
3433
  fields = list(fields) + [dict(f, source="overlay") for f in shared_defs.values()]
3434
  for pid, cells in _so().cells(table_key, [r["pid"] for r in rows_src],
3435
+ st=page_st).items():
3436
  overlays.setdefault(pid, {}).update(cells)
3437
  # RECOMPUTED ON THE **MERGED** CONTRACT, and that is not belt-and-braces. The closure above
3438
  # ran before `shared_defs` appended this database's tenant-wide overlay columns, so a formula
 
3763
  # who assumed both were bodies would have wired the rows and left the summaries answering over
3764
  # the entire database under a tab that names one record. `_compiled_read` accepts either shape,
3765
  # so the two doors cannot pin differently without this argument being deleted.
3766
+ # S67-T28: the same page snapshot `/rows` takes, so opening a grouped view (its group counts
3767
+ # come from here) no longer re-reads every definition while `user_tables` is unchanged.
3768
  read = _compiled_read(table_key, session, tree=query["filters"],
3769
  filterConj=query["filterConj"], search=query["search"],
3770
+ related=payload.get("related"), st=_page_defs(session)[0])
3771
  read = _restrict_row_ids(read, ids)
3772
  out = _aggregate_over(read["cur"], read["spec"], read["cols"], read["where"],
3773
  read["params"], read["frm"], aggs, group_by=group_by,
api/routes_sheet.py CHANGED
@@ -2565,8 +2565,13 @@ def _ending_window(session, binding, *, book=None, tab=None, today=None, seen=()
2565
 
2566
 
2567
  def _read_binding_cell(session, ref, *, book=None, tab=None, today=None, seen=(),
2568
- code="ending_cell_unreadable"):
2569
- """Shared cell read for Ending and Filter, including scoped bound and formula inputs."""
 
 
 
 
 
2570
  from modules import sheet as sheet_mod
2571
  import formula_runtime as fr
2572
 
@@ -2648,6 +2653,13 @@ def _read_binding_cell(session, ref, *, book=None, tab=None, today=None, seen=()
2648
  if cell.get("state") == "stale":
2649
  refuse("the cell needs to be refreshed.")
2650
  value = cell.get("value", cell.get("text"))
 
 
 
 
 
 
 
2651
  return value
2652
 
2653
 
@@ -2655,7 +2667,8 @@ def _filter_cell_values(session, nodes, *, book=None, tab=None, today=None, seen
2655
  from modules import sheet as sheet_mod
2656
  try:
2657
  return sheet_mod.resolve_filter_cells(nodes, lambda ref: _read_binding_cell(
2658
- session, ref, book=book, tab=tab, today=today, seen=seen, code="filter_cell_unreadable"))
 
2659
  except sheet_mod.SheetRefusal as exc:
2660
  raise err(400, exc.code, exc.message)
2661
 
 
2565
 
2566
 
2567
  def _read_binding_cell(session, ref, *, book=None, tab=None, today=None, seen=(),
2568
+ code="ending_cell_unreadable", as_date=False):
2569
+ """Shared cell read for Ending and Filter, including scoped bound and formula inputs.
2570
+
2571
+ S67-T10: with ``as_date`` a date-formatted number (typed, or a formula's result such as
2572
+ 46293) is returned as its ISO day, so a Filter condition compares it as that date for every
2573
+ operator; a plain number with no date format is returned unchanged.
2574
+ """
2575
  from modules import sheet as sheet_mod
2576
  import formula_runtime as fr
2577
 
 
2653
  if cell.get("state") == "stale":
2654
  refuse("the cell needs to be refreshed.")
2655
  value = cell.get("value", cell.get("text"))
2656
+ if (as_date and isinstance(value, (int, float)) and not isinstance(value, bool)
2657
+ and sheet_mod.date_formatted_cell(cell)):
2658
+ from harness import windows as W
2659
+ day = W.ending_cell_date(value, book.get("dateSystem", "1900"))
2660
+ if not day:
2661
+ refuse("its value is not a real date.")
2662
+ return day
2663
  return value
2664
 
2665
 
 
2667
  from modules import sheet as sheet_mod
2668
  try:
2669
  return sheet_mod.resolve_filter_cells(nodes, lambda ref: _read_binding_cell(
2670
+ session, ref, book=book, tab=tab, today=today, seen=seen, code="filter_cell_unreadable",
2671
+ as_date=True))
2672
  except sheet_mod.SheetRefusal as exc:
2673
  raise err(400, exc.code, exc.message)
2674
 
api/routes_templates.py CHANGED
@@ -137,6 +137,16 @@ def apply_template(key: str, body: dict = Body(default=None),
137
  import core.table_store as table_store
138
  ops = table_store.make(ws_key, st=session.runtime)
139
  applied = []
 
 
 
 
 
 
 
 
 
 
140
  for view in tpl.get('views') or ():
141
  # ⛔ A COPY PER APPLY, and `createdBy` STAMPED HERE. The registry's dicts are module-level
142
  # — mutating one would write this caller's username into the template every other tenant
@@ -145,6 +155,10 @@ def apply_template(key: str, body: dict = Body(default=None),
145
  # side.
146
  payload = dict(view)
147
  payload['config'] = dict(view.get('config') or {})
 
 
 
 
148
  payload['createdBy'] = session.uname
149
  saved = ops.save_view(session.uname, payload)
150
  applied.append({"id": payload['id'], "name": saved.get('name') or payload['name']})
@@ -316,8 +330,17 @@ def _agent_templates():
316
  ]
317
 
318
 
 
 
 
 
 
 
 
 
 
319
  def _module_templates(session):
320
- from core import sheet_templates, user_tables
321
  from routes_connectors import _entry_types
322
  from routes_keychain import env_odoo_available
323
  from routes_nav import application_templates
@@ -332,7 +355,9 @@ def _module_templates(session):
332
  saved = _saved_sheet_templates(session.runtime)
333
  data_templates = [(row, _data_template_database(row, definitions))
334
  for row in _templates().TEMPLATES]
335
- agent_templates = _agent_templates() if _may_open(session, "automation") else []
 
 
336
  databases = {row["database_hint"] for row in sheet_templates.TEMPLATES}
337
  databases.update(db for row in saved for db in row["databases"])
338
  databases.update(database for _row, database in data_templates if database)
@@ -361,6 +386,16 @@ def _module_templates(session):
361
  sections = [{"module": "sheet", "templates": sheet},
362
  {"module": "data", "templates": data},
363
  {"module": "app", "templates": app}]
 
 
 
 
 
 
 
 
 
 
364
  if agent_templates:
365
  sections.append({"module": "agents", "templates": [
366
  _catalog_row(row["key"], row["name"], row["description"],
@@ -509,6 +544,16 @@ def create_module_template(module: str, key: str, body: dict = Body(default=None
509
  raise err(404, "unknown_template", "That template does not exist.")
510
  if not template["creatable"]:
511
  raise err(409, "template_unavailable", "Connect the required source and switch on its databases.")
 
 
 
 
 
 
 
 
 
 
512
  if module == "sheet":
513
  database = template["requires"][0]["database"] if template["requires"] else ""
514
  result = apply_sheet_template(key, {"database": database, "name": body.get("name", "")}, session)
@@ -529,3 +574,16 @@ def create_module_template(module: str, key: str, body: dict = Body(default=None
529
  app = result["application"]
530
  return {"address": "#/app?database=" + quote(app["sourceDatabase"], safe="") + "&application=" + quote(app["id"], safe=""),
531
  **result}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
137
  import core.table_store as table_store
138
  ops = table_store.make(ws_key, st=session.runtime)
139
  applied = []
140
+ # S67-T39 (R12, D-2233): a template View bound to an App that no longer exists instantiates as
141
+ # a plain view of its database; the live App ids are read once, and an unreadable registry
142
+ # keeps the reference (the read projection in `grid_events.table_workspace` still masks it).
143
+ try:
144
+ import application_registry
145
+ raw_registry = session.runtime.get(application_registry._KEY)
146
+ live_apps = (set(raw_registry["applications"]) if isinstance(raw_registry, dict)
147
+ and isinstance(raw_registry.get("applications"), dict) else None)
148
+ except Exception:
149
+ live_apps = None
150
  for view in tpl.get('views') or ():
151
  # ⛔ A COPY PER APPLY, and `createdBy` STAMPED HERE. The registry's dicts are module-level
152
  # — mutating one would write this caller's username into the template every other tenant
 
155
  # side.
156
  payload = dict(view)
157
  payload['config'] = dict(view.get('config') or {})
158
+ dead_ref = payload['config'].get('application')
159
+ if (live_apps is not None and isinstance(dead_ref, dict)
160
+ and str(dead_ref.get('id') or '') not in live_apps):
161
+ payload['config'].pop('application')
162
  payload['createdBy'] = session.uname
163
  saved = ops.save_view(session.uname, payload)
164
  applied.append({"id": payload['id'], "name": saved.get('name') or payload['name']})
 
330
  ]
331
 
332
 
333
+ def _content_studio():
334
+ """The Content Studio App's own module, or None when it is absent (rule 13: delete-safe)."""
335
+ try:
336
+ import content_studio
337
+ except ImportError:
338
+ return None
339
+ return content_studio
340
+
341
+
342
  def _module_templates(session):
343
+ from core import registry, sheet_templates, user_tables
344
  from routes_connectors import _entry_types
345
  from routes_keychain import env_odoo_available
346
  from routes_nav import application_templates
 
355
  saved = _saved_sheet_templates(session.runtime)
356
  data_templates = [(row, _data_template_database(row, definitions))
357
  for row in _templates().TEMPLATES]
358
+ # S67-T36 (R25): an archived Agents module offers no agent template; the create route stays.
359
+ agent_templates = (_agent_templates() if _may_open(session, "automation")
360
+ and not registry.is_archived("automation") else [])
361
  databases = {row["database_hint"] for row in sheet_templates.TEMPLATES}
362
  databases.update(db for row in saved for db in row["databases"])
363
  databases.update(database for _row, database in data_templates if database)
 
386
  sections = [{"module": "sheet", "templates": sheet},
387
  {"module": "data", "templates": data},
388
  {"module": "app", "templates": app}]
389
+ # S67-T40 (R18): every tenant's App catalogue offers Content Studio, which creates its own
390
+ # databases. Guarded (rule 13): without the module the catalogue simply omits the row.
391
+ # ⚠ Appended AFTER `sections` (it is the App section's own list, so the order stays Finance,
392
+ # then Studio): `verify_shell_rail.py` scopes its S65-T10 needles to the span from the Finance
393
+ # offer to `sections = [`, and its finance-offer-wizard control mutates the FIRST
394
+ # `creation_mode="post"` in this file. A Studio row inside that span, or above it, masks it.
395
+ studio = _content_studio()
396
+ if studio is not None:
397
+ app.append(_catalog_row(studio.TEMPLATE_KEY, studio.LABEL, studio.DESCRIPTION, [],
398
+ creation_mode="post"))
399
  if agent_templates:
400
  sections.append({"module": "agents", "templates": [
401
  _catalog_row(row["key"], row["name"], row["description"],
 
544
  raise err(404, "unknown_template", "That template does not exist.")
545
  if not template["creatable"]:
546
  raise err(409, "template_unavailable", "Connect the required source and switch on its databases.")
547
+ studio = _content_studio() if module == "app" else None
548
+ if studio is not None and key == studio.TEMPLATE_KEY:
549
+ if not session.runtime.available():
550
+ raise err(503, "store_unavailable", "The tenant store is unavailable. Nothing was created.")
551
+ try:
552
+ return studio.create(session, body.get("name") or "")
553
+ except studio.ContentStudioError as exc:
554
+ raise err(409, "content_studio_refused", str(exc))
555
+ except PermissionError as exc:
556
+ raise err(403, "forbidden", str(exc))
557
  if module == "sheet":
558
  database = template["requires"][0]["database"] if template["requires"] else ""
559
  result = apply_sheet_template(key, {"database": database, "name": body.get("name", "")}, session)
 
574
  app = result["application"]
575
  return {"address": "#/app?database=" + quote(app["sourceDatabase"], safe="") + "&application=" + quote(app["id"], safe=""),
576
  **result}
577
+
578
+ # S67-T41: Content Studio's own routes (`/api/v1/content-studio/*`) ride this router because the
579
+ # App wires no mount of its own into main.py; GUARDED, so deleting content_studio.py drops the
580
+ # routes and nothing else (rule 13).
581
+ # ⚠ An inline guarded import, NOT a call to `_content_studio()`: this tail belongs to the
582
+ # dispatcher block, which `verify_home.py`'s W61-T23 declaration-order control moves ABOVE that
583
+ # helper's definition, where a call is a NameError that crashes the whole gate.
584
+ try:
585
+ import content_studio as _studio_module
586
+ except ImportError:
587
+ _studio_module = None
588
+ if _studio_module is not None and getattr(_studio_module, "router", None) is not None:
589
+ router.include_router(_studio_module.router)
platform/core/daily_sales_repair.py CHANGED
@@ -498,7 +498,8 @@ def _checked_projection(projected, edits, formula_check):
498
  != {key: recalculated[key] for key in _VISUAL_CELL_KEYS if key in recalculated}:
499
  raise RepairRefusal(
500
  "repair_unplanned_formula_change",
501
- "Formula validation would change a cell outside the supplied source diff.")
 
502
  desired = sheets.clean_cell(_preserve_visual(previous, recalculated), slot[1])
503
  if row is None:
504
  sheet = sheet_names[slot[0]]
@@ -515,7 +516,8 @@ def _checked_projection(projected, edits, formula_check):
515
  or row["after"].get("kind") != "formula":
516
  raise RepairRefusal(
517
  "repair_unplanned_formula_change",
518
- "Formula validation would change a cell outside the supplied source diff.")
 
519
  recalculated = after.get(slot)
520
  if not isinstance(recalculated, dict) \
521
  or (row["kind"] == "source"
@@ -1333,6 +1335,404 @@ def _build_daily_sales_bindings_plan(current, request, resolve_binding, formula_
1333
  "helper": helper, "ending_row": ending, "observed": observed}
1334
 
1335
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1336
  def _build_plan(current, request, resolve_binding):
1337
  if not isinstance(request.get("source_cells"), list) or not request["source_cells"]:
1338
  raise RepairRefusal(
@@ -1525,12 +1925,24 @@ def execute(st, backup_store, request, *, target_workbook_id=TARGET_WORKBOOK_ID,
1525
  raise RepairRefusal("repair_revision_mismatch",
1526
  "The named workbook is not at the expected repair revision.")
1527
  digest = sheets.workbook_digest(current)
 
 
 
1528
  summary_evidence = None
1529
  summary_errors_before = None
1530
  migrated = None
1531
  formula_evidence = None
1532
  daily_evidence = None
1533
- if "daily_sales_bindings" in request:
 
 
 
 
 
 
 
 
 
1534
  formula_check = _daily_sales_formula_checker(formula_check)
1535
  edits, daily_evidence = _build_daily_sales_bindings_plan(
1536
  current, request, resolve_binding, formula_check)
@@ -1579,7 +1991,11 @@ def execute(st, backup_store, request, *, target_workbook_id=TARGET_WORKBOOK_ID,
1579
  "The projected repair introduces a formula error or leaves one in its repair scope, "
1580
  "so no repair was applied.")
1581
  visual_before = visual_metadata(current)
1582
- if visual_metadata(projected) != visual_before:
 
 
 
 
1583
  raise RepairRefusal("repair_visual_metadata_changed",
1584
  "The projected repair changes Daily Sales visual metadata.")
1585
 
@@ -1611,7 +2027,7 @@ def execute(st, backup_store, request, *, target_workbook_id=TARGET_WORKBOOK_ID,
1611
  or _cell_map(checked_readback) != _cell_map(readback):
1612
  raise RepairRefusal("repair_readback_formula_state",
1613
  "The repaired workbook did not read back calculation-current.")
1614
- if visual_metadata(readback) != visual_before:
1615
  raise RepairRefusal("repair_readback_visual_metadata",
1616
  "Daily Sales visual metadata changed during repair.")
1617
  if formula_evidence is not None:
@@ -1667,4 +2083,19 @@ def execute(st, backup_store, request, *, target_workbook_id=TARGET_WORKBOOK_ID,
1667
  result["daily_sales_bindings"] = daily_evidence
1668
  result["formula_error_census"] = {
1669
  "before": _formula_repair_census(current), "after": _formula_repair_census(readback)}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1670
  return result
 
498
  != {key: recalculated[key] for key in _VISUAL_CELL_KEYS if key in recalculated}:
499
  raise RepairRefusal(
500
  "repair_unplanned_formula_change",
501
+ "Formula validation would change " + str(sheet_names.get(slot[0]) or slot[0])
502
+ + "!" + slot[1] + ", a cell outside the supplied source diff.")
503
  desired = sheets.clean_cell(_preserve_visual(previous, recalculated), slot[1])
504
  if row is None:
505
  sheet = sheet_names[slot[0]]
 
516
  or row["after"].get("kind") != "formula":
517
  raise RepairRefusal(
518
  "repair_unplanned_formula_change",
519
+ "Formula validation would change " + str(sheet_names.get(slot[0]) or slot[0])
520
+ + "!" + slot[1] + ", a cell outside the supplied source diff.")
521
  recalculated = after.get(slot)
522
  if not isinstance(recalculated, dict) \
523
  or (row["kind"] == "source"
 
1335
  "helper": helper, "ending_row": ending, "observed": observed}
1336
 
1337
 
1338
+ # ═════════════════════════════════════════════════════════════════════════════════════════════
1339
+ # ⭐⭐ S67-T21 / R34 — EVERY METRIC COMPUTED; ONLY THE OWNER'S OWN INPUTS STAY TYPED
1340
+ # ═════════════════════════════════════════════════════════════════════════════════════════════
1341
+ #
1342
+ # The owner's weekly scorecard read pasted numbers: the weekly block and the middle of a dozen
1343
+ # rows were values copied once and never recomputed. This mode applies an explicit, fully named
1344
+ # cell plan (each cell a formula, a Cell Database binding or a blank), resolved and recalculated
1345
+ # BEFORE a byte moves, and REFUSES unless the projected workbook keeps no hardcoded number but the
1346
+ # owner's inputs. The plan itself is built by the operator from the Excel reference; this module is
1347
+ # what makes it safe to apply: owner inputs and labels are untouchable, every binding resolves to
1348
+ # a fresh value with no limits, the formula census stays empty, and the backup lands first.
1349
+
1350
+ SR_TAB = "Summary (SR)"
1351
+
1352
+ #: R34 (owner, 2026-09-28), verbatim cells. Summary (All)'s six are the owner's inputs; Summary
1353
+ #: (SR)'s are the only numbers the Excel file itself types on that tab (its targets and goals).
1354
+ OWNER_INPUTS = {
1355
+ SUMMARY_TAB: frozenset({"Q25", "T20", "T37", "T38", "T51", "T55"}),
1356
+ SR_TAB: frozenset({"T24", "T25", "T34", "T67", "T71", "T105", "T112"}),
1357
+ }
1358
+ _PLANNED_KINDS = ("formula", "bound", "empty")
1359
+ #: The tab-level visual keys a plan may DECLARE (O42: match the Excel file's freeze). Anything else
1360
+ #: visual still refuses, exactly as every content-only repair above does.
1361
+ _PLANNED_TAB_VISUAL_KEYS = ("freeze",)
1362
+
1363
+
1364
+ def hardcoded_numbers(book):
1365
+ """`{tab name: {address: number}}` for every literal numeric cell, PURE. R34's census."""
1366
+ out = {}
1367
+ for tab in book.get("sheets") or ():
1368
+ found = {}
1369
+ for address, cell in (tab.get("cells") or {}).items():
1370
+ value = (cell or {}).get("value")
1371
+ if (cell or {}).get("kind") == "literal" and type(value) in (int, float):
1372
+ found[address] = value
1373
+ out[str(tab.get("name") or "")] = found
1374
+ return out
1375
+
1376
+
1377
+ def _bound_value(value, fn):
1378
+ """A resolved binding's value as the document stores it, or a refusal.
1379
+
1380
+ ⭐ A `min`/`max` over a date column answers a DATE ("Latest data" is `max(invoice_date)`), which
1381
+ is stored as its ISO text, the shape every formula date in this workbook already has.
1382
+ """
1383
+ import datetime as _dtm
1384
+ if isinstance(value, (_dtm.date, _dtm.datetime)):
1385
+ if fn not in ("min", "max"):
1386
+ raise RepairRefusal("repair_binding_unreadable", "Only min or max may answer a date.")
1387
+ return value.isoformat()[:10]
1388
+ if isinstance(value, str) and fn in ("min", "max") and re.fullmatch(r"\d{4}-\d{2}-\d{2}.*", value):
1389
+ return value[:10]
1390
+ if value is None and fn in ("avg", "min", "max"):
1391
+ return None
1392
+ if type(value) not in (int, float) or not math.isfinite(value):
1393
+ raise RepairRefusal("repair_binding_unreadable", "A binding must resolve a finite number.")
1394
+ return value
1395
+
1396
+
1397
+ def _visual_without(book, planned_notes, keys=("note",)):
1398
+ """`visual_metadata` with each planned cell's declared visual `keys` removed (a note for
1399
+ T21, a sparkline for T23), so a declared change is the only visual change a plan may make."""
1400
+ shaped = copy.deepcopy(book)
1401
+ for tab in shaped.get("sheets") or ():
1402
+ name = str(tab.get("name") or "").casefold()
1403
+ for address, cell in (tab.get("cells") or {}).items():
1404
+ if (name, address) in planned_notes and isinstance(cell, dict):
1405
+ for key in keys:
1406
+ cell.pop(key, None)
1407
+ return visual_metadata(shaped)
1408
+
1409
+
1410
+ def _build_computed_metrics_plan(current, request, resolve_binding, formula_check):
1411
+ """R34: validate and resolve an explicit per-cell plan; refuse unless it leaves no hardcode."""
1412
+ spec = request["computed_metrics"]
1413
+ if not isinstance(spec, dict) or any(key in request for key in (
1414
+ "formula_repair", "related_migration", "summary_block", "source_cells",
1415
+ "binding_cells", "daily_sales_bindings")):
1416
+ raise RepairRefusal("repair_metrics_plan_conflict",
1417
+ "Run the computed metrics plan as its own repair.")
1418
+ if not callable(formula_check) or not callable(resolve_binding):
1419
+ raise RepairRefusal("repair_binding_resolver_required",
1420
+ "Computed metrics require the resolver and the formula engine.")
1421
+ refreshed_at = str(request.get("refreshed_at") or "").strip()
1422
+ if not refreshed_at:
1423
+ raise RepairRefusal("repair_timestamp_required", "Computed metrics require a refresh timestamp.")
1424
+ rows = spec.get("cells")
1425
+ if not isinstance(rows, list) or not rows:
1426
+ raise RepairRefusal("repair_metrics_plan_empty", "The computed metrics plan names no cell.")
1427
+ edits, observed, seen, planned_notes = [], [], set(), set()
1428
+ # ⭐ A binding may read a cell this same plan writes (a month's helper start/end dates, a
1429
+ # year header), so bindings resolve against the workbook WITH the planned formulas and blanks
1430
+ # applied and recalculated, never against the stale current one.
1431
+ staged = []
1432
+ for row in rows:
1433
+ want = row.get("cell") if isinstance(row, dict) else None
1434
+ if isinstance(want, dict) and want.get("kind") in ("formula", "empty"):
1435
+ tab = _tab(current, str(row.get("sheet") or ""))
1436
+ address = _addr(row.get("address"))
1437
+ before = copy.deepcopy((tab.get("cells") or {}).get(address))
1438
+ cell = ({"kind": "formula", "state": "stale", "formula": str(want.get("formula") or "")}
1439
+ if want["kind"] == "formula" else {"kind": "empty", "state": "typed"})
1440
+ staged.append({"sheet": str(tab.get("name")), "address": address, "before": before,
1441
+ "after": sheets.clean_cell(_preserve_visual(before, cell) or cell, address)})
1442
+ def recalculated(extra):
1443
+ projected = _project(current, staged + extra)
1444
+ checked = formula_check(copy.deepcopy(projected))
1445
+ return checked["book"] if isinstance(checked, dict) and isinstance(
1446
+ checked.get("book"), dict) else projected
1447
+
1448
+ def resolve_row(row, book):
1449
+ sheet = str(_tab(current, str(row.get("sheet") or "")).get("name"))
1450
+ address = _addr(row.get("address"))
1451
+ binding = sheets.clean_cell({"kind": "bound", "binding": row["cell"].get("binding")},
1452
+ address)["binding"]
1453
+ try:
1454
+ result = resolve_binding(copy.deepcopy(binding), copy.deepcopy(book),
1455
+ copy.deepcopy(_tab(book, sheet)))
1456
+ except Exception as exc: # noqa: BLE001
1457
+ detail = getattr(exc, "detail", None)
1458
+ info = (detail.get("error") or {}) if isinstance(detail, dict) else {}
1459
+ code = getattr(exc, "code", None) or info.get("code") or "repair_binding_unreadable"
1460
+ return None, RepairRefusal(code, sheet + "!" + address + " binding resolution refused.")
1461
+ return (binding, result), None
1462
+
1463
+ # ⭐ ROUNDS, because a binding may read a date another binding produces through formulas
1464
+ # (Summary (SR)'s week axis runs E12 `max(invoice_date)` -> E15 -> R8 -> F8 -> F31's window).
1465
+ # Each round resolves what it can read, the next projection carries those values, and only a
1466
+ # cell whose filter input was not yet readable waits; no progress in a round refuses by name.
1467
+ resolved, pending = {}, [row for row in rows if isinstance(row, dict)
1468
+ and isinstance(row.get("cell"), dict)
1469
+ and row["cell"].get("kind") == "bound"]
1470
+ for _round in range(6):
1471
+ if not pending:
1472
+ break
1473
+ extra = []
1474
+ for (sheet, address), (binding, result) in resolved.items():
1475
+ value = result.get("value") if isinstance(result, dict) else None
1476
+ try:
1477
+ value = _bound_value(value, (binding.get("aggregate") or {}).get("fn"))
1478
+ except RepairRefusal:
1479
+ value = None
1480
+ extra.append({"sheet": sheet, "address": address, "before": None,
1481
+ "after": sheets.clean_cell({"kind": "bound", "state": "fresh",
1482
+ "binding": binding, "value": value,
1483
+ "display": "" if value is None else str(value)},
1484
+ address)})
1485
+ book = recalculated(extra)
1486
+ waiting, first_error = [], None
1487
+ for row in pending:
1488
+ got, error = resolve_row(row, book)
1489
+ if got is not None:
1490
+ resolved[(str(_tab(current, str(row["sheet"])).get("name")),
1491
+ _addr(row.get("address")))] = got
1492
+ elif error.code == "filter_cell_unreadable":
1493
+ waiting.append(row)
1494
+ first_error = first_error or error
1495
+ else:
1496
+ raise error
1497
+ if len(waiting) == len(pending):
1498
+ raise first_error
1499
+ pending = waiting
1500
+ if pending:
1501
+ raise RepairRefusal("filter_cell_unreadable", "A binding's filter cell never became readable.")
1502
+ for row in rows:
1503
+ if not isinstance(row, dict):
1504
+ raise RepairRefusal("repair_metrics_cell_invalid", "Every planned cell must be an object.")
1505
+ sheet_name = str(row.get("sheet") or "").strip()
1506
+ address = _addr(row.get("address"))
1507
+ tab = _tab(current, sheet_name)
1508
+ sheet_name = str(tab.get("name") or sheet_name)
1509
+ slot = (sheet_name.casefold(), address)
1510
+ if slot in seen:
1511
+ raise RepairRefusal("repair_edit_duplicate", "A planned cell may be named only once.")
1512
+ seen.add(slot)
1513
+ if address in OWNER_INPUTS.get(sheet_name, ()):
1514
+ raise RepairRefusal("repair_owner_input", sheet_name + "!" + address
1515
+ + " is one of the owner's typed inputs and stays typed.")
1516
+ cells = tab.get("cells") or {}
1517
+ before = copy.deepcopy(cells.get(address))
1518
+ prior_value = (before or {}).get("value")
1519
+ want = row.get("cell")
1520
+ if not isinstance(want, dict) or want.get("kind") not in (*_PLANNED_KINDS, "note_only"):
1521
+ raise RepairRefusal("repair_metrics_cell_invalid", sheet_name + "!" + address
1522
+ + " must be planned as a formula, a binding, a blank or a note.")
1523
+ kind = want["kind"]
1524
+ # A typed ISO date is a value (Summary (SR)'s frozen E13/E15), never a label.
1525
+ if (before or {}).get("kind") == "literal" and isinstance(prior_value, str) \
1526
+ and prior_value.strip() and kind != "note_only" \
1527
+ and not re.fullmatch(r"\d{4}-\d{2}-\d{2}", prior_value.strip()):
1528
+ raise RepairRefusal("repair_label_protected", sheet_name + "!" + address
1529
+ + " holds a label, which a metrics plan never replaces.")
1530
+ if kind == "note_only":
1531
+ desired = copy.deepcopy(before) if before else {"kind": "empty", "state": "typed"}
1532
+ elif kind == "formula":
1533
+ text = str(want.get("formula") or "")
1534
+ if not text.startswith("="):
1535
+ raise RepairRefusal("repair_metrics_cell_invalid", sheet_name + "!" + address
1536
+ + " needs a formula that starts with =.")
1537
+ desired = _preserve_visual(before, {"kind": "formula", "state": "stale", "formula": text})
1538
+ elif kind == "empty":
1539
+ desired = _preserve_visual(before, {"kind": "empty", "state": "typed"}) \
1540
+ or {"kind": "empty", "state": "typed"}
1541
+ else:
1542
+ binding, result = resolved[(sheet_name, address)]
1543
+ fn = (binding.get("aggregate") or {}).get("fn")
1544
+ if not isinstance(result, dict) or "value" not in result or result.get("refusal") \
1545
+ or result.get("error") or result.get("state") not in (None, "fresh"):
1546
+ raise RepairRefusal("repair_binding_unreadable", sheet_name + "!" + address
1547
+ + " did not resolve a fresh bound value.")
1548
+ if result.get("limits"):
1549
+ raise RepairRefusal("repair_binding_limits", sheet_name + "!" + address
1550
+ + " has unapplied or limited binding conditions.")
1551
+ value = _bound_value(result["value"], fn)
1552
+ if (before or {}).get("kind") == "bound" and before.get("binding") == binding \
1553
+ and type(prior_value) in (int, float) and type(value) in (int, float) \
1554
+ and math.isclose(prior_value, value, rel_tol=1e-9, abs_tol=1e-9):
1555
+ value = prior_value # the same number; a rerun changes nothing
1556
+ desired = _preserve_visual(before, {
1557
+ "kind": "bound", "state": "fresh", "binding": binding, "value": value,
1558
+ "display": "" if value is None else str(value), "refreshed_at": refreshed_at})
1559
+ observed.append({"sheet": sheet_name, "address": address, "value": value})
1560
+ if "note" in row:
1561
+ note = str(row.get("note") or "").strip()
1562
+ if note:
1563
+ desired["note"] = note
1564
+ else:
1565
+ desired.pop("note", None)
1566
+ planned_notes.add(slot)
1567
+ after = sheets.clean_cell(desired, address)
1568
+ # A planned formula is `derived`: the recalculation below is what fills its value, and
1569
+ # `_checked_projection` accepts a recalculated planned cell only under that kind.
1570
+ edit_kind = {"formula": "derived", "bound": "binding"}.get(kind, "metric")
1571
+ edits.append({"kind": edit_kind, "name": sheet_name + "!" + address, "sheet": sheet_name,
1572
+ "address": address, "before": before, "after": after})
1573
+ tab_visual = spec.get("tab_visual") or {}
1574
+ if not isinstance(tab_visual, dict):
1575
+ raise RepairRefusal("repair_metrics_visual_invalid", "Tab visual changes must be an object.")
1576
+ for sheet_name, keys in tab_visual.items():
1577
+ _tab(current, sheet_name)
1578
+ if not isinstance(keys, dict) or not keys or set(keys) - set(_PLANNED_TAB_VISUAL_KEYS):
1579
+ raise RepairRefusal("repair_metrics_visual_invalid",
1580
+ "A metrics plan may declare only a tab's freeze.")
1581
+ projected, _errors = _checked_projection(_project(current, edits), edits, formula_check)
1582
+ _daily_sales_invariants(projected, formula_check)
1583
+ remaining = {name: sorted(set(found) - OWNER_INPUTS.get(name, frozenset()))
1584
+ for name, found in hardcoded_numbers(projected).items()
1585
+ if name in OWNER_INPUTS}
1586
+ if any(remaining.values()):
1587
+ raise RepairRefusal("repair_hardcoded_remain", "Hardcoded numbers would remain: "
1588
+ + json.dumps(remaining, sort_keys=True))
1589
+ return [edit for edit in edits if edit["before"] != edit["after"]], {
1590
+ "observed": observed, "planned_notes": sorted(f"{s}!{a}" for s, a in planned_notes),
1591
+ "tab_visual": copy.deepcopy(tab_visual),
1592
+ "hardcoded_before": hardcoded_numbers(current), "hardcoded_after": hardcoded_numbers(projected)}
1593
+
1594
+
1595
+ def _apply_tab_visual(st, workbook_id, tab_visual, *, actor="", actor_name=""):
1596
+ """Write the DECLARED tab-level visual keys through the ordinary document door, then prove
1597
+ nothing else moved. Returns the readback snapshot."""
1598
+ doc = sheets.workbook_snapshot(st, workbook_id)
1599
+ before_cells = {str(t.get("name")): copy.deepcopy(t.get("cells") or {}) for t in doc["sheets"]}
1600
+ before_visual = visual_metadata(doc)
1601
+ for sheet_name, keys in tab_visual.items():
1602
+ tab = _tab(doc, sheet_name)
1603
+ for key, value in keys.items():
1604
+ tab[key] = copy.deepcopy(value)
1605
+ sheets.put_workbook(st, workbook_id, doc, expect_rev=int(doc.get("rev") or 0),
1606
+ actor=actor, actor_name=actor_name, lossless=True)
1607
+ readback = sheets.workbook_snapshot(st, workbook_id)
1608
+ for sheet_name, keys in tab_visual.items():
1609
+ tab = _tab(readback, sheet_name)
1610
+ for key, value in keys.items():
1611
+ if _canonical(tab.get(key)) != _canonical(value):
1612
+ raise RepairRefusal("repair_visual_readback", sheet_name + " " + key
1613
+ + " did not read back as declared.")
1614
+ if {str(t.get("name")): t.get("cells") or {} for t in readback["sheets"]} != before_cells:
1615
+ raise RepairRefusal("repair_visual_readback", "A declared visual change moved cell content.")
1616
+ expected = copy.deepcopy(before_visual)
1617
+ for item in expected:
1618
+ for key, value in (tab_visual.get(item.get("name")) or {}).items():
1619
+ item[key] = copy.deepcopy(value)
1620
+ if visual_metadata(readback) != _canonical(expected):
1621
+ raise RepairRefusal("repair_visual_readback", "An undeclared visual property changed.")
1622
+ return readback
1623
+
1624
+
1625
+ # ═════════════════════════════════════════════════════════════════════════════════════════════
1626
+ # ⭐⭐ S67-T22 / S67-T23 — DECLARED VISUAL REPAIRS: Excel's rule colours and its 3M sparklines
1627
+ # ═════════════════════════════════════════════════════════════════════════════════════════════
1628
+ #
1629
+ # Every repair above REFUSES a visual change, on purpose. These two tickets ARE visual changes, so
1630
+ # they get their own mode that names exactly what may move: a tab's `rules` (T22, O31) and a cell's
1631
+ # `sparkline` (T23, O32). Cell content, every other visual key and every other cell must read back
1632
+ # unchanged; the backup lands before anything is written.
1633
+
1634
+ _VISUAL_REPAIR_TAB_KEYS = ("rules",)
1635
+
1636
+
1637
+ def _build_visual_repair_plan(current, request):
1638
+ spec = request["visual_repair"]
1639
+ if not isinstance(spec, dict) or any(key in request for key in (
1640
+ "formula_repair", "related_migration", "summary_block", "source_cells",
1641
+ "binding_cells", "daily_sales_bindings", "computed_metrics")):
1642
+ raise RepairRefusal("repair_visual_plan_conflict", "Run the visual repair as its own repair.")
1643
+ tab_visual = copy.deepcopy(spec.get("tab_visual") or {})
1644
+ for sheet_name, keys in tab_visual.items():
1645
+ _tab(current, sheet_name)
1646
+ if not isinstance(keys, dict) or not keys or set(keys) - set(_VISUAL_REPAIR_TAB_KEYS):
1647
+ raise RepairRefusal("repair_visual_invalid", "A visual repair may declare only a tab's rules.")
1648
+ keys["rules"] = sheets._clean_rules(keys["rules"], lossless=True)
1649
+ edits, seen = [], set()
1650
+ for row in spec.get("cells") or ():
1651
+ if not isinstance(row, dict) or "sparkline" not in row:
1652
+ raise RepairRefusal("repair_visual_invalid", "A visual repair cell names only its sparkline.")
1653
+ tab = _tab(current, str(row.get("sheet") or ""))
1654
+ sheet_name, address = str(tab.get("name")), _addr(row.get("address"))
1655
+ if (sheet_name.casefold(), address) in seen:
1656
+ raise RepairRefusal("repair_edit_duplicate", "A repaired cell may be named only once.")
1657
+ seen.add((sheet_name.casefold(), address))
1658
+ before = copy.deepcopy((tab.get("cells") or {}).get(address))
1659
+ desired = copy.deepcopy(before) if before else {"kind": "empty", "state": "typed"}
1660
+ if row["sparkline"] is None:
1661
+ desired.pop("sparkline", None)
1662
+ else:
1663
+ clean = sheets._clean_sparkline(row["sparkline"])
1664
+ if clean is None:
1665
+ raise RepairRefusal("repair_visual_invalid", sheet_name + "!" + address
1666
+ + " names a sparkline that cannot be drawn.")
1667
+ desired["sparkline"] = clean
1668
+ after = sheets.clean_cell(desired, address)
1669
+ content = ("kind", "state", "value", "display", "formula", "binding", "text")
1670
+ if any((before or {}).get(key) != after.get(key) for key in content if key != "state") \
1671
+ and not (before is None and after.get("kind") == "empty"):
1672
+ raise RepairRefusal("repair_visual_content_changed", sheet_name + "!" + address
1673
+ + " would change content, which a visual repair never does.")
1674
+ edits.append({"kind": "visual", "name": sheet_name + "!" + address, "sheet": sheet_name,
1675
+ "address": address, "before": before, "after": after})
1676
+ return [e for e in edits if e["before"] != e["after"]], {
1677
+ "tab_visual": tab_visual, "sparkline_cells": sorted(e["name"] for e in edits)}
1678
+
1679
+ def _execute_visual_repair(st, backup_store, request, current, revision, digest, workbook_id,
1680
+ *, actor="", actor_name=""):
1681
+ """Back up, then write ONLY the declared sparklines (exact cell edits) and tab rules."""
1682
+ edits, evidence = _build_visual_repair_plan(current, request)
1683
+ if not edits and not evidence["tab_visual"]:
1684
+ return {"workbook_id": workbook_id, "revision_before": revision, "revision_after": revision,
1685
+ "applied": 0, "noop": True, "visual_repair": evidence}
1686
+ planned = {(row["sheet"].casefold(), row["address"]) for row in edits}
1687
+ projected = _project(current, edits)
1688
+ if _visual_without(projected, planned, ("sparkline",)) != \
1689
+ _visual_without(current, planned, ("sparkline",)):
1690
+ raise RepairRefusal("repair_visual_metadata_changed",
1691
+ "The projected repair changes a visual property it did not declare.")
1692
+ exact = [{key: copy.deepcopy(row[key]) for key in ("sheet", "address", "before", "after")}
1693
+ for row in edits]
1694
+ diff_digest = sheets.workbook_digest({"edits": exact, "tab_visual": evidence["tab_visual"]})
1695
+ backup_key = _write_backup(backup_store, current, digest, diff_digest, workbook_id)
1696
+ revision_after = revision
1697
+ if exact:
1698
+ sheets.apply_exact_cell_edits(st, workbook_id, exact, revision, digest,
1699
+ actor=actor, actor_name=actor_name)
1700
+ readback = sheets.workbook_snapshot(st, workbook_id)
1701
+ if int(readback.get("rev") or 0) != revision + 1:
1702
+ raise RepairRefusal("repair_readback_revision",
1703
+ "The repaired workbook revision did not read back as expected.")
1704
+ for row in edits:
1705
+ actual = (_tab(readback, row["sheet"]).get("cells") or {}).get(row["address"])
1706
+ if actual != sheets.clean_cell(row["after"], row["address"]):
1707
+ raise RepairRefusal("repair_readback_cell",
1708
+ row["sheet"] + "!" + row["address"] + " did not read back exactly.")
1709
+ revision_after = int(readback["rev"])
1710
+ if evidence["tab_visual"]:
1711
+ revision_after = int(_apply_tab_visual(st, workbook_id, evidence["tab_visual"],
1712
+ actor=actor, actor_name=actor_name)["rev"])
1713
+ return {"workbook_id": workbook_id, "revision_before": revision,
1714
+ "revision_after": revision_after, "applied": len(exact), "backup_key": backup_key,
1715
+ "backup_digest": digest, "diff_digest": diff_digest, "visual_repair": evidence}
1716
+
1717
+
1718
+ def restore_backup(st, backup_store, backup_key, *, workbook_id, actor="", actor_name=""):
1719
+ """NC for every mode here: put a backup's workbook back and prove it round-trips."""
1720
+ record = backup_store.get(backup_key)
1721
+ if not isinstance(record, dict) or record.get("workbook_id") != workbook_id:
1722
+ raise RepairRefusal("repair_backup_missing", "That backup does not exist for this workbook.")
1723
+ saved = copy.deepcopy(record["workbook"])
1724
+ current = sheets.workbook_snapshot(st, workbook_id)
1725
+ sheets.put_workbook(st, workbook_id, saved, expect_rev=int(current.get("rev") or 0),
1726
+ actor=actor, actor_name=actor_name, lossless=True)
1727
+ readback = sheets.workbook_snapshot(st, workbook_id)
1728
+ same = ({str(t.get("name")): t.get("cells") or {} for t in readback["sheets"]}
1729
+ == {str(t.get("name")): t.get("cells") or {} for t in saved["sheets"]}
1730
+ and visual_metadata(readback) == visual_metadata(saved))
1731
+ if not same:
1732
+ raise RepairRefusal("repair_restore_unverified", "The restored workbook did not round-trip.")
1733
+ return readback
1734
+
1735
+
1736
  def _build_plan(current, request, resolve_binding):
1737
  if not isinstance(request.get("source_cells"), list) or not request["source_cells"]:
1738
  raise RepairRefusal(
 
1925
  raise RepairRefusal("repair_revision_mismatch",
1926
  "The named workbook is not at the expected repair revision.")
1927
  digest = sheets.workbook_digest(current)
1928
+ if "visual_repair" in request:
1929
+ return _execute_visual_repair(st, backup_store, request, current, revision, digest,
1930
+ target_workbook_id, actor=actor, actor_name=actor_name)
1931
  summary_evidence = None
1932
  summary_errors_before = None
1933
  migrated = None
1934
  formula_evidence = None
1935
  daily_evidence = None
1936
+ metrics_evidence = None
1937
+ if "computed_metrics" in request:
1938
+ formula_check = _daily_sales_formula_checker(formula_check)
1939
+ edits, metrics_evidence = _build_computed_metrics_plan(
1940
+ current, request, resolve_binding, formula_check)
1941
+ if not edits and not metrics_evidence["tab_visual"]:
1942
+ return {"workbook_id": target_workbook_id, "revision_before": revision,
1943
+ "revision_after": revision, "applied": 0, "noop": True,
1944
+ "computed_metrics": metrics_evidence}
1945
+ elif "daily_sales_bindings" in request:
1946
  formula_check = _daily_sales_formula_checker(formula_check)
1947
  edits, daily_evidence = _build_daily_sales_bindings_plan(
1948
  current, request, resolve_binding, formula_check)
 
1991
  "The projected repair introduces a formula error or leaves one in its repair scope, "
1992
  "so no repair was applied.")
1993
  visual_before = visual_metadata(current)
1994
+ planned_notes = set()
1995
+ if metrics_evidence is not None:
1996
+ planned_notes = {tuple(item.split("!", 1)) for item in metrics_evidence["planned_notes"]}
1997
+ planned_notes = {(sheet.casefold(), address) for sheet, address in planned_notes}
1998
+ if _visual_without(projected, planned_notes) != _visual_without(current, planned_notes):
1999
  raise RepairRefusal("repair_visual_metadata_changed",
2000
  "The projected repair changes Daily Sales visual metadata.")
2001
 
 
2027
  or _cell_map(checked_readback) != _cell_map(readback):
2028
  raise RepairRefusal("repair_readback_formula_state",
2029
  "The repaired workbook did not read back calculation-current.")
2030
+ if _visual_without(readback, planned_notes) != _visual_without(current, planned_notes):
2031
  raise RepairRefusal("repair_readback_visual_metadata",
2032
  "Daily Sales visual metadata changed during repair.")
2033
  if formula_evidence is not None:
 
2083
  result["daily_sales_bindings"] = daily_evidence
2084
  result["formula_error_census"] = {
2085
  "before": _formula_repair_census(current), "after": _formula_repair_census(readback)}
2086
+ if metrics_evidence is not None:
2087
+ _daily_sales_invariants(readback, formula_check)
2088
+ remaining = {name: sorted(set(found) - OWNER_INPUTS.get(name, frozenset()))
2089
+ for name, found in hardcoded_numbers(readback).items() if name in OWNER_INPUTS}
2090
+ if any(remaining.values()):
2091
+ raise RepairRefusal("repair_hardcoded_remain", "Hardcoded numbers remain after the write: "
2092
+ + json.dumps(remaining, sort_keys=True))
2093
+ if metrics_evidence["tab_visual"]:
2094
+ visual_readback = _apply_tab_visual(st, target_workbook_id, metrics_evidence["tab_visual"],
2095
+ actor=actor, actor_name=actor_name)
2096
+ result["revision_after"] = visual_readback["rev"]
2097
+ metrics_evidence["hardcoded_readback"] = hardcoded_numbers(readback)
2098
+ result["computed_metrics"] = metrics_evidence
2099
+ result["formula_error_census"] = {
2100
+ "before": _formula_repair_census(current), "after": _formula_repair_census(readback)}
2101
  return result
platform/core/external_tools.py CHANGED
@@ -42,12 +42,19 @@ _STRING = {"type": "string"}
42
  _ADDRESS = {"type": "string", "description": "An A1 cell address on the named tab."}
43
  _FORMAT = _object({"kind": _STRING, "code": _STRING, "decimals": {"type": "integer"},
44
  "currency": _STRING, "thousands": {"type": "boolean"}}, ("kind",))
 
 
 
 
 
 
 
45
  _STYLE = _object({
46
  **{key: {"type": "boolean"} for key in ("bold", "italic", "underline", "strike", "wrap")},
47
  **{key: _STRING for key in ("fill", "color", "font", "align", "valign")},
48
  "size": {"type": ["number", "string"]}, "indent": {"type": "integer"},
49
  "textRotation": {"type": "number"}, "format": _FORMAT,
50
- "border": _object({side: {"type": "boolean"} for side in ("top", "right", "bottom", "left")}),
51
  })
52
  _VALIDATION = _object({"list": {"type": "array", "items": _STRING}}, ("list",))
53
  _FILTER = _object({"conj": {"enum": ["and", "or"]}, "nodes": {"type": "array", "items": _object({
@@ -62,15 +69,25 @@ _BINDING = _object({
62
  "period": _object({"unit": _STRING, "start": _STRING}),
63
  "ending": {"type": "object"},
64
  }, ("database", "aggregate", "scope"))
65
- _CELL = _object({"kind": {"enum": ["literal", "formula", "bound", "empty"]},
66
- "value": {}, "text": _STRING, "formula": _STRING, "state": _STRING,
67
- "style": _STYLE, "validation": _VALIDATION, "binding": _BINDING}, ("kind",))
68
  _RANGE = {"oneOf": [_STRING, _object({key: {"type": "integer", "minimum": 0}
69
  for key in ("col0", "row0", "col1", "row1")},
70
  ("col0", "row0", "col1", "row1"))]}
 
 
 
 
 
 
 
 
 
 
 
71
  _RULE = _object({"id": _STRING, "range": _RANGE, "kind": _STRING, "op": _STRING,
72
  "value": {}, "value2": {}, "formula": _STRING, "style": _STYLE,
73
- "scale": {"type": "object"}}, ("range", "op"))
 
 
74
  _CHART = _object({"id": _STRING, "kind": _STRING, "range": _RANGE, "title": _STRING,
75
  "stacking": _STRING, "source": {"type": "object"},
76
  "series": {"type": "array", "items": {"type": "object"}},
 
42
  _ADDRESS = {"type": "string", "description": "An A1 cell address on the named tab."}
43
  _FORMAT = _object({"kind": _STRING, "code": _STRING, "decimals": {"type": "integer"},
44
  "currency": _STRING, "thousands": {"type": "boolean"}}, ("kind",))
45
+ # S67-T14 / contract C2: a border side is the legacy `true` (read as a thin black line) or
46
+ # `{style, color}` with one of Excel's seven line styles and a six digit hex colour; `false` or an
47
+ # absent side is no side. `sheets.py::_clean_border_side` refuses anything else by code, and this
48
+ # publishes the same shape so an AI client can draw a styled border at all.
49
+ _BORDER_SIDE = {"oneOf": [{"type": "boolean"}, _object({
50
+ "style": {"enum": list(sheets.CELL_BORDER_STYLES)},
51
+ "color": {"type": "string", "pattern": "^#[0-9A-Fa-f]{6}$"}}, ("style", "color"))]}
52
  _STYLE = _object({
53
  **{key: {"type": "boolean"} for key in ("bold", "italic", "underline", "strike", "wrap")},
54
  **{key: _STRING for key in ("fill", "color", "font", "align", "valign")},
55
  "size": {"type": ["number", "string"]}, "indent": {"type": "integer"},
56
  "textRotation": {"type": "number"}, "format": _FORMAT,
57
+ "border": _object({side: _BORDER_SIDE for side in ("top", "right", "bottom", "left")}),
58
  })
59
  _VALIDATION = _object({"list": {"type": "array", "items": _STRING}}, ("list",))
60
  _FILTER = _object({"conj": {"enum": ["and", "or"]}, "nodes": {"type": "array", "items": _object({
 
69
  "period": _object({"unit": _STRING, "start": _STRING}),
70
  "ending": {"type": "object"},
71
  }, ("database", "aggregate", "scope"))
 
 
 
72
  _RANGE = {"oneOf": [_STRING, _object({key: {"type": "integer", "minimum": 0}
73
  for key in ("col0", "row0", "col1", "row1")},
74
  ("col0", "row0", "col1", "row1"))]}
75
+ # S67-T18: an in-cell sparkline, `{kind, range}` exactly as `sheets.py::_clean_sparkline` stores
76
+ # it; the range is a rectangle on the SAME tab (an A1 range such as "B2:M2", or the dict).
77
+ _SPARKLINE = _object({"kind": {"enum": list(sheets.SPARKLINE_KINDS)}, "range": _RANGE},
78
+ ("kind", "range"))
79
+ _CELL = _object({"kind": {"enum": ["literal", "formula", "bound", "empty"]},
80
+ "value": {}, "text": _STRING, "formula": _STRING, "state": _STRING,
81
+ "style": _STYLE, "validation": _VALIDATION, "binding": _BINDING,
82
+ "sparkline": _SPARKLINE}, ("kind",))
83
+ # S67-T13: a colour scale's two ends and what each end means. `sheets.py::_clean_rules` refuses
84
+ # a type outside `SHEET_RULE_SCALE_TYPES`; the enum publishes the same list to the caller.
85
+ _SCALE_TYPE = {"enum": list(sheets.SHEET_RULE_SCALE_TYPES)}
86
  _RULE = _object({"id": _STRING, "range": _RANGE, "kind": _STRING, "op": _STRING,
87
  "value": {}, "value2": {}, "formula": _STRING, "style": _STYLE,
88
+ "scale": _object({"low": _STRING, "high": _STRING,
89
+ "minType": _SCALE_TYPE, "maxType": _SCALE_TYPE})},
90
+ ("range", "op"))
91
  _CHART = _object({"id": _STRING, "kind": _STRING, "range": _RANGE, "title": _STRING,
92
  "stacking": _STRING, "source": {"type": "object"},
93
  "series": {"type": "array", "items": {"type": "object"}},
platform/core/grid_events.py CHANGED
@@ -632,6 +632,57 @@ def _grant_marker(ctx, ws):
632
  return _has_grants
633
 
634
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
635
  def table_workspace(ctx, allowed_pids=None, consume_corrections=True, capture_document=False):
636
  """Durable Airtable-style view/schema/overlay state, with an honest session fallback.
637
 
@@ -707,6 +758,8 @@ def table_workspace(ctx, allowed_pids=None, consume_corrections=True, capture_do
707
  merged.update(ws.get('views') or {}) # own views win the id collision
708
  ws['views'] = {vid: scope_view(v, uname, allowed_pids)
709
  for vid, v in merged.items()}
 
 
710
  return ws
711
  # Store down. Streamlit degrades to its captioned session workspace exactly as before; an
712
  # API caller has no durable dict and must be told, not quietly served memory.
@@ -1584,7 +1637,13 @@ def handle_one(event, ctx):
1584
  _refuse(ctx, 'invalid_application_ref',
1585
  'that Application reference is not a valid typed identity', view_id)
1586
  return False
1587
- config['application'] = application
 
 
 
 
 
 
1588
  # Wave-6 item 10: a direct non-grid display mode rides the view config, validated
1589
  # structurally (mode whitelist, refs must be this table's fields). A bound Application's
1590
  # config remains in the registry and is resolved on read, so an offered clone is dropped.
 
632
  return _has_grants
633
 
634
 
635
+ #: S67-T39 / R36: the Application registry's store key. READ here, never imported:
636
+ #: `application_registry` lives in the api layer and core never imports up (ARCHITECTURE).
637
+ _APPLICATIONS_KEY = 'applications_v1'
638
+
639
+
640
+ def _live_application_ids(ctx):
641
+ """The set of App ids the tenant registry holds, or None when that is not KNOWN.
642
+
643
+ None (read failed, or no registry document with an `applications` map) means "strip
644
+ nothing": an unknown answer must never turn a live App binding into a plain view.
645
+ """
646
+ try:
647
+ doc = _store_of(ctx).get(_APPLICATIONS_KEY)
648
+ except Exception as exc:
649
+ _tel.error('applications:live', exc)
650
+ return None
651
+ apps = doc.get('applications') if isinstance(doc, dict) else None
652
+ return {str(key) for key in apps} if isinstance(apps, dict) else None
653
+
654
+
655
+ def _application_ref_id(view):
656
+ config = view.get('config') if isinstance(view, dict) else None
657
+ ref = config.get('application') if isinstance(config, dict) else None
658
+ return str(ref.get('id') or '') if isinstance(ref, dict) else None
659
+
660
+
661
+ def _drop_dead_application_refs(ctx, views):
662
+ """S67-T39 / R36 / D-2233: a View bound to a DELETED App is served as a plain view of its
663
+ database (the `application` member dropped, everything else kept), so it opens with no
664
+ error. Projection only, and it never raises: any failure serves the views unchanged.
665
+ The registry is read only when some View actually carries a reference.
666
+ """
667
+ try:
668
+ if not any(_application_ref_id(v) is not None for v in (views or {}).values()):
669
+ return views
670
+ live = _live_application_ids(ctx)
671
+ if live is None:
672
+ return views
673
+ out = {}
674
+ for vid, view in views.items():
675
+ ref_id = _application_ref_id(view)
676
+ if ref_id is not None and ref_id not in live:
677
+ config = {k: v for k, v in view['config'].items() if k != 'application'}
678
+ view = {**view, 'config': config}
679
+ out[vid] = view
680
+ return out
681
+ except Exception as exc:
682
+ _tel.error('applications:dead_refs', exc)
683
+ return views
684
+
685
+
686
  def table_workspace(ctx, allowed_pids=None, consume_corrections=True, capture_document=False):
687
  """Durable Airtable-style view/schema/overlay state, with an honest session fallback.
688
 
 
758
  merged.update(ws.get('views') or {}) # own views win the id collision
759
  ws['views'] = {vid: scope_view(v, uname, allowed_pids)
760
  for vid, v in merged.items()}
761
+ if ws.get('views'):
762
+ ws['views'] = _drop_dead_application_refs(ctx, ws['views'])
763
  return ws
764
  # Store down. Streamlit degrades to its captioned session workspace exactly as before; an
765
  # API caller has no durable dict and must be told, not quietly served memory.
 
1637
  _refuse(ctx, 'invalid_application_ref',
1638
  'that Application reference is not a valid typed identity', view_id)
1639
  return False
1640
+ # S67-T39 / R36: a reference to a DELETED App is dropped, not stored, so the View
1641
+ # saves as a plain view of its database. Unknown registry state keeps the ref.
1642
+ _live = _live_application_ids(ctx)
1643
+ if _live is not None and application['id'] not in _live:
1644
+ application = None
1645
+ else:
1646
+ config['application'] = application
1647
  # Wave-6 item 10: a direct non-grid display mode rides the view config, validated
1648
  # structurally (mode whitelist, refs must be this table's fields). A bound Application's
1649
  # config remains in the registry and is resolved on read, so an offered clone is dropped.
platform/core/perm_scope.py CHANGED
@@ -221,12 +221,39 @@ def assistant_entry(user, module):
221
  that reader must be able to name the migrated grant that admitted a database. In particular,
222
  a store-outage admin identity with no ``perms`` document is not an unresolved permission that
223
  may be widened into data access.
 
 
 
 
 
224
  """
225
  e = entry(user, module)
226
- if (not is_migrated(user) or not isinstance(e, dict)
227
- or not bool(e.get('access', True)) or not may_access(user, module)):
228
- return None
229
- return e
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
230
 
231
 
232
  # ── FIELDS ───────────────────────────────────────────────────────────────────────────────────
 
221
  that reader must be able to name the migrated grant that admitted a database. In particular,
222
  a store-outage admin identity with no ``perms`` document is not an unresolved permission that
223
  may be widened into data access.
224
+
225
+ ⭐ S67-T34 / D-276: ONE NAMED EXCEPTION, the grant the NAVIGATION uses. For the two registry
226
+ topics in ``ASSISTANT_NAV_TOPICS`` an administrator account is admitted unfiltered (unless
227
+ explicitly unticked), because ``nav_may_open`` leg 1 opens them to it; the AI list must equal
228
+ the nav (R33). See the comment at that leg for why the outage identity no longer reaches it.
229
  """
230
  e = entry(user, module)
231
+ if (is_migrated(user) and isinstance(e, dict)
232
+ and bool(e.get('access', True)) and may_access(user, module)):
233
+ return e
234
+ # ⭐⭐ S67-T34 / D-276 / R26: THE ADMINISTRATOR THE NAVIGATION ADMITS. `nav_may_open` leg 1
235
+ # opens every registry topic to an administrator, and `_clean_perms` writes no per-topic
236
+ # entry for one, so an administrator saw `customer_data` and `product_data` (Odoo products,
237
+ # R26's Inventory source) in the nav and had them refused here. MEASURED on staging
238
+ # 2026-09-28: aaron (admin, no `perms_v`) had both in the nav and neither in the AI list. The
239
+ # answer is the grant the nav already uses, admitted for exactly these topics: an account
240
+ # whose ROLE is admin, minus an explicit `access: false` (narrower than the nav, never wider).
241
+ # Unfiltered, as the nav's break-glass is.
242
+ # ⚠ THE STORE-OUTAGE IDENTITY the docstring names is no longer built by `deps._user_for`
243
+ # (it admits a stored record or the QA runner, nothing else), so the role is read off a
244
+ # stored account here. If a synthetic admin identity is ever reintroduced, it must be kept
245
+ # out of this leg.
246
+ # ⛔ NOT A MEMBER. A non-administrator still needs the explicit migrated grant above, so a
247
+ # user without it does not see the database (the NC).
248
+ if (module in ASSISTANT_NAV_TOPICS and perms.is_admin(user)
249
+ and not (isinstance(e, dict) and e.get('access') is False)):
250
+ return dict(e) if isinstance(e, dict) else {'access': True, 'filter': None}
251
+ return None
252
+
253
+
254
+ #: S67-T34: the registry topics the navigation opens to an administrator by break-glass, which
255
+ #: `assistant_entry` therefore admits for a migrated administrator without a per-topic entry.
256
+ ASSISTANT_NAV_TOPICS = frozenset({'customer_data', 'product_data'})
257
 
258
 
259
  # ── FIELDS ───────────────────────────────────────────────────────────────────────────────────
platform/core/registry.py CHANGED
@@ -203,7 +203,12 @@ REGISTRY = [
203
  'proof). No nav, no page. Wave 17 R8 ("I don\'t even know what it does. Delete '
204
  'them") made that literal: `validate_only` takes it out of the account menu too, '
205
  'which is the last place it was still visible. The proof survives; the door does not.'},
 
 
 
 
206
  {'key': 'automation', 'label': 'Agents', 'brand': False, 'hq': True, 'validate': False,
 
207
  'nav': True,
208
  'note': 'Wave 18 (C-AUTONAV): scheduled jobs that create and refresh user databases '
209
  '(website scrape-to-DB, the Instagram field). React-only surface (no PAGE_FUNCS '
@@ -280,6 +285,11 @@ def brand_filterable(key) -> bool:
280
  return bool(BY_KEY.get(key, {}).get('brand'))
281
 
282
 
 
 
 
 
 
283
  # ═════════════════════════════════════════════════════════════════════════════════════════════
284
  # ⭐⭐ W33-T41 / item 12a — ONE SUBJECT, ONE DATABASE
285
  # ═════════════════════════════════════════════════════════════════════════════════════════════
 
203
  'proof). No nav, no page. Wave 17 R8 ("I don\'t even know what it does. Delete '
204
  'them") made that literal: `validate_only` takes it out of the account menu too, '
205
  'which is the last place it was still visible. The proof survives; the door does not.'},
206
+ # S67-T36 (owner instr 24, R25, 2026-09-28): Agents is TABLED. `archived` hides the UI only:
207
+ # no rail row, no Settings module toggle, no Home section, no agent templates. The
208
+ # `/automations` APIs, stored automations and their schedules are untouched and keep running.
209
+ # ⭐ RESTORING IS THIS ONE LINE: delete `'archived': True` below and every door comes back.
210
  {'key': 'automation', 'label': 'Agents', 'brand': False, 'hq': True, 'validate': False,
211
+ 'archived': True,
212
  'nav': True,
213
  'note': 'Wave 18 (C-AUTONAV): scheduled jobs that create and refresh user databases '
214
  '(website scrape-to-DB, the Instagram field). React-only surface (no PAGE_FUNCS '
 
285
  return bool(BY_KEY.get(key, {}).get('brand'))
286
 
287
 
288
+ def is_archived(key) -> bool:
289
+ """True when the registry row `key` is archived (tabled for everyone). Unknown keys: False."""
290
+ return bool(BY_KEY.get(key, {}).get('archived'))
291
+
292
+
293
  # ═════════════════════════════════════════════════════════════════════════════════════════════
294
  # ⭐⭐ W33-T41 / item 12a — ONE SUBJECT, ONE DATABASE
295
  # ═════════════════════════════════════════════════════════════════════════════════════════════
platform/core/sheet_import.py CHANGED
@@ -43,9 +43,11 @@ from __future__ import annotations
43
  import re
44
  import zipfile
45
  import hashlib
 
46
  import json
47
  import math
48
  import os
 
49
  import tempfile
50
  import xml.etree.ElementTree as ET
51
  from datetime import date, datetime, time, timezone
@@ -392,12 +394,11 @@ def style_of(cell, notes):
392
  if border is not None:
393
  sides = {}
394
  for side in sheets._BORDER_SIDES:
395
- edge = getattr(border, side, None)
396
- if edge is not None and getattr(edge, "style", None):
397
- sides[side] = True
398
  if sides:
399
  out["border"] = sides
400
- notes.add("a border keeps its side but not its weight, style or colour")
401
 
402
  fmt, note = classify_format(getattr(cell, "number_format", ""))
403
  if fmt:
@@ -407,6 +408,47 @@ def style_of(cell, notes):
407
  return out
408
 
409
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
410
  # ── values ───────────────────────────────────────────────────────────────────────────────────
411
 
412
  def json_value(value):
@@ -1037,6 +1079,134 @@ def guard_import_archive(path):
1037
  "That file could not be read as a workbook. Save it again as .xlsx and try once more.") from exc
1038
 
1039
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1040
  def _print_of(ws):
1041
  """Store print setup and inclusive print areas; export executes these settings later."""
1042
  setup = {key: getattr(ws.page_setup, key) for key in ws.page_setup.__attrs__
@@ -1148,6 +1318,7 @@ def import_workbook(path, *, source="", progress=None):
1148
 
1149
  counts = {"cells": 0, "formulas": 0}
1150
  book_notes = set()
 
1151
  authored = _authored_chart_document(path, book_notes)
1152
  chart_tabs = {tab["name"]: tab for tab in authored["sheets"]} if authored else {}
1153
  if authored and len(chart_tabs) != len(authored["sheets"]):
@@ -1209,6 +1380,8 @@ def import_workbook(path, *, source="", progress=None):
1209
  cells = _cells_of(ws, cached, notes, counts, excel)
1210
  _say("formats", 0.7 + 0.25 * (index / total))
1211
  _validations_of(ws, cells, notes)
 
 
1212
  cols, rows, widths, freeze, hidden_rows, hidden_cols, heights = _geometry_of(ws, notes)
1213
  tab = {"id": "", "name": name[:sheets._MAX_NAME], "cols": cols, "rows": rows,
1214
  "cells": cells, "usedExtent": sheets._used_extent(cells, excel["blankStyles"]),
 
43
  import re
44
  import zipfile
45
  import hashlib
46
+ import io
47
  import json
48
  import math
49
  import os
50
+ import posixpath
51
  import tempfile
52
  import xml.etree.ElementTree as ET
53
  from datetime import date, datetime, time, timezone
 
394
  if border is not None:
395
  sides = {}
396
  for side in sheets._BORDER_SIDES:
397
+ line = border_line(getattr(border, side, None), notes)
398
+ if line is not None:
399
+ sides[side] = line
400
  if sides:
401
  out["border"] = sides
 
402
 
403
  fmt, note = classify_format(getattr(cell, "number_format", ""))
404
  if fmt:
 
408
  return out
409
 
410
 
411
+ #: S67-T14: the OOXML line styles that are not one of C2's seven, each drawn as its nearest.
412
+ #: The dash and dot variants keep their PATTERN over their weight, because a patterned line drawn
413
+ #: solid reads as a different border while a medium dash drawn at 1px still reads as dashed.
414
+ _BORDER_NEAREST = {
415
+ "mediumDashed": "dashed", "dashDot": "dashed", "dashDotDot": "dashed",
416
+ "mediumDashDot": "dashed", "mediumDashDotDot": "dashed", "slantDashDot": "dashed",
417
+ }
418
+
419
+
420
+ def border_line(edge, notes):
421
+ """One openpyxl border side as C2's `{style, color}`, or None when the side draws nothing.
422
+
423
+ The seven Excel names C2 shares pass through unchanged; the dash dot variants become their
424
+ nearest with a note naming the approximation. The colour is the explicit RGB when there is one;
425
+ an automatic colour is black, which is what Excel draws; a theme or indexed colour is drawn in
426
+ black too, with a note, because a colour nobody chose is never guessed (see `argb_of`).
427
+ """
428
+ style = str(getattr(edge, "style", None) or "") if edge is not None else ""
429
+ if not style or style == "none":
430
+ return None
431
+ if style not in sheets.CELL_BORDER_STYLES:
432
+ nearest = _BORDER_NEAREST.get(style, "thin")
433
+ notes.add("a " + style + " border is drawn as " + nearest)
434
+ style = nearest
435
+ colour = getattr(edge, "color", None)
436
+ argb = argb_of(colour)
437
+ if argb:
438
+ hex_colour = "#" + argb.lower()
439
+ else:
440
+ hex_colour = "#000000"
441
+ kind = getattr(colour, "type", "") if colour is not None else ""
442
+ # ⚠ `type`, never `.auto`: openpyxl answers an unset descriptor with a (truthy) error
443
+ # STRING, so `colour.auto` reads as set on every theme colour.
444
+ automatic = (colour is None or kind == "auto"
445
+ or (kind == "indexed" and getattr(colour, "indexed", None) == 64)
446
+ or (kind == "rgb" and str(getattr(colour, "rgb", "")).upper() == "00000000"))
447
+ if not automatic:
448
+ notes.add("a theme or indexed border colour was drawn in black")
449
+ return {"style": style, "color": hex_colour}
450
+
451
+
452
  # ── values ───────────────────────────────────────────────────────────────────────────────────
453
 
454
  def json_value(value):
 
1079
  "That file could not be read as a workbook. Save it again as .xlsx and try once more.") from exc
1080
 
1081
 
1082
+ # ── sparklines (S67-T18) ─────────────────────────────────────────────────────────────────────
1083
+
1084
+ #: ⭐ S67-T18: Excel keeps sparkline groups in the worksheet's x14 extension, which openpyxl drops,
1085
+ #: so they are read from the worksheet PART itself. A group with no `type` draws lines, `column`
1086
+ #: draws columns and `stacked` draws win/loss bars (Excel's name for `sheets.SPARKLINE_KINDS`'s
1087
+ #: `winloss`). The part was already admitted by `guard_import_archive`, so this second read adds
1088
+ #: no new exposure.
1089
+ _X14 = "{http://schemas.microsoft.com/office/spreadsheetml/2009/9/main}"
1090
+ _XM = "{http://schemas.microsoft.com/office/excel/2006/main}"
1091
+ _MAIN_NS = "{http://schemas.openxmlformats.org/spreadsheetml/2006/main}"
1092
+ _DOC_REL_NS = "{http://schemas.openxmlformats.org/officeDocument/2006/relationships}"
1093
+ _PKG_REL_NS = "{http://schemas.openxmlformats.org/package/2006/relationships}"
1094
+ _SPARKLINE_KIND_OF = {"line": "line", "column": "column", "stacked": "winloss"}
1095
+
1096
+
1097
+ def _worksheet_parts(archive):
1098
+ """`{tab name: worksheet part}` through `xl/workbook.xml` and its relationships, never by index."""
1099
+ names = set(archive.namelist())
1100
+ if "xl/workbook.xml" not in names or "xl/_rels/workbook.xml.rels" not in names:
1101
+ return {}
1102
+ targets = {}
1103
+ for rel in ET.fromstring(archive.read("xl/_rels/workbook.xml.rels")).iter(_PKG_REL_NS + "Relationship"):
1104
+ target = str(rel.get("Target") or "")
1105
+ targets[rel.get("Id")] = (target.lstrip("/") if target.startswith("/")
1106
+ else posixpath.normpath("xl/" + target))
1107
+ out = {}
1108
+ for sheet in ET.fromstring(archive.read("xl/workbook.xml")).iter(_MAIN_NS + "sheet"):
1109
+ part = targets.get(sheet.get(_DOC_REL_NS + "id"))
1110
+ if part in names:
1111
+ out[str(sheet.get("name") or "")] = part
1112
+ return out
1113
+
1114
+
1115
+ def _sparkline_groups(stream):
1116
+ """`[(type, [(formula, sqref), ...]), ...]` for one worksheet part's x14 sparkline groups."""
1117
+ groups = []
1118
+ inside = 0 # a group's subtree is kept until the group itself ends
1119
+ for event, element in ET.iterparse(stream, events=("start", "end")):
1120
+ if element.tag == _X14 + "sparklineGroup":
1121
+ if event == "start":
1122
+ inside += 1
1123
+ continue
1124
+ inside -= 1
1125
+ entries = [((spark.findtext(_XM + "f") or "").strip(),
1126
+ (spark.findtext(_XM + "sqref") or "").strip())
1127
+ for spark in element.iter(_X14 + "sparkline")]
1128
+ groups.append((str(element.get("type") or "line"), entries))
1129
+ element.clear()
1130
+ elif event == "end" and not inside:
1131
+ element.clear()
1132
+ return groups
1133
+
1134
+
1135
+ def _sparklines_of(path, notes):
1136
+ """`{tab name: groups}` for every worksheet that carries x14 sparklines; `{}` for the rest.
1137
+
1138
+ A part whose bytes never mention a sparkline group is not parsed at all, so a workbook with
1139
+ no sparklines imports exactly as it did before S67-T18.
1140
+ """
1141
+ out = {}
1142
+ try:
1143
+ with zipfile.ZipFile(path) as archive:
1144
+ for name, part in _worksheet_parts(archive).items():
1145
+ raw = archive.read(part)
1146
+ if b"sparklineGroup" not in raw:
1147
+ continue
1148
+ groups = _sparkline_groups(io.BytesIO(raw))
1149
+ if groups:
1150
+ out[name] = groups
1151
+ except (KeyError, OSError, ET.ParseError, zipfile.BadZipFile):
1152
+ notes.add("the workbook's sparklines could not be read, so none were imported")
1153
+ return {}
1154
+ return out
1155
+
1156
+
1157
+ def _count_phrase(count, one, many):
1158
+ return (one if count == 1 else str(count) + " " + many)
1159
+
1160
+
1161
+ def _apply_sparklines(tab_name, cells, groups, blank_styles, notes):
1162
+ """Write `cell.sparkline {kind, range}` on each location cell of this tab's groups.
1163
+
1164
+ `sheets._clean_sparkline` stores a rectangle LOCAL to its tab, so a sparkline drawn from
1165
+ another tab's data cannot be carried: it is left out and NAMED, never dropped in silence
1166
+ (the module note). A location that is not one cell, or data that is not a range, is named too.
1167
+ A blank location becomes an `empty` cell holding only the sparkline, which is exactly what
1168
+ `clean_cell`'s empty branch keeps; its compact blank-style reference moves onto it.
1169
+ """
1170
+ other_tab = unreadable = 0
1171
+ for kind_name, entries in groups:
1172
+ kind = _SPARKLINE_KIND_OF.get(kind_name)
1173
+ if kind is None:
1174
+ unreadable += len(entries)
1175
+ continue
1176
+ for formula, sqref in entries:
1177
+ source = sheet_of_ref(formula)
1178
+ if source and source.casefold() != tab_name.casefold():
1179
+ other_tab += 1
1180
+ continue
1181
+ rect = rect_of(formula)
1182
+ places = sqref.replace("$", "").upper().split()
1183
+ if (rect is None or len(places) != 1 or ":" in places[0]
1184
+ or not _address_in_document(places[0])):
1185
+ unreadable += 1
1186
+ continue
1187
+ addr = places[0]
1188
+ spark = {"kind": kind, "range": rect}
1189
+ cell = cells.get(addr)
1190
+ if cell is None:
1191
+ if len(cells) >= sheets._MAX_CELLS_PER_SHEET:
1192
+ unreadable += 1
1193
+ continue
1194
+ cell = {"kind": "empty", "sparkline": spark}
1195
+ if addr in blank_styles:
1196
+ cell["excel"] = {"styleId": blank_styles.pop(addr)}
1197
+ cells[addr] = cell
1198
+ else:
1199
+ cell["sparkline"] = spark
1200
+ if other_tab:
1201
+ notes.add(_count_phrase(other_tab, "a sparkline", "sparklines")
1202
+ + " drawn from another tab's data " + ("was" if other_tab == 1 else "were")
1203
+ + " left out")
1204
+ if unreadable:
1205
+ notes.add(_count_phrase(unreadable, "a sparkline", "sparklines")
1206
+ + " with a location or data range that could not be read "
1207
+ + ("was" if unreadable == 1 else "were") + " left out")
1208
+
1209
+
1210
  def _print_of(ws):
1211
  """Store print setup and inclusive print areas; export executes these settings later."""
1212
  setup = {key: getattr(ws.page_setup, key) for key in ws.page_setup.__attrs__
 
1318
 
1319
  counts = {"cells": 0, "formulas": 0}
1320
  book_notes = set()
1321
+ sparklines = _sparklines_of(path, book_notes) # S67-T18
1322
  authored = _authored_chart_document(path, book_notes)
1323
  chart_tabs = {tab["name"]: tab for tab in authored["sheets"]} if authored else {}
1324
  if authored and len(chart_tabs) != len(authored["sheets"]):
 
1380
  cells = _cells_of(ws, cached, notes, counts, excel)
1381
  _say("formats", 0.7 + 0.25 * (index / total))
1382
  _validations_of(ws, cells, notes)
1383
+ if name in sparklines: # S67-T18, before usedExtent
1384
+ _apply_sparklines(name, cells, sparklines[name], excel["blankStyles"], notes)
1385
  cols, rows, widths, freeze, hidden_rows, hidden_cols, heights = _geometry_of(ws, notes)
1386
  tab = {"id": "", "name": name[:sheets._MAX_NAME], "cols": cols, "rows": rows,
1387
  "cells": cells, "usedExtent": sheets._used_extent(cells, excel["blankStyles"]),
platform/core/sheets.py CHANGED
@@ -152,6 +152,14 @@ MAX_FONT_PT = 96
152
  _STYLE_MARKS = ("bold", "italic", "underline")
153
  _BORDER_SIDES = ("top", "right", "bottom", "left")
154
 
 
 
 
 
 
 
 
 
155
  #: R8's indent, in steps rather than pixels: a stored pixel count would be a layout decision that
156
  #: outlives every layout change, exactly as a stored hex outlives a palette.
157
  _MAX_INDENT = 8
@@ -204,6 +212,12 @@ SHEET_RULE_OPS = ("gt", "lt", "gte", "lte", "eq", "neq", "between", "contains",
204
  #: every rule written before this ticket already is, so writing the word onto them would make a
205
  #: reload compare unequal to the save. Mirrored in `web/src/sheet/types.ts::SHEET_RULE_KINDS`.
206
  SHEET_RULE_KINDS = ("cell", "scale", "bar", "formula")
 
 
 
 
 
 
207
  # The client compiler accepts 500 characters per condition.
208
  MAX_RULE_FORMULA_LENGTH = 500
209
 
@@ -652,13 +666,44 @@ def _clean_style(raw):
652
 
653
  border = raw.get("border")
654
  if isinstance(border, dict):
655
- sides = {side: True for side in _BORDER_SIDES if border.get(side) is True}
 
 
 
 
656
  if sides:
657
  out["border"] = sides
658
 
659
  return out or None
660
 
661
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
662
  # ── the cell ─────────────────────────────────────────────────────────────────────────────────
663
 
664
  def _clean_validation(raw):
@@ -1131,15 +1176,31 @@ def _clean_rule_scale(raw):
1131
  ⚠ THE SCALE'S BOUNDS ARE NOT HERE. They ride `value` and `value2` on the rule itself, which
1132
  `_clean_rules` already persists for every op that takes operands, so a colour scale needed no
1133
  new numeric slot at all.
 
 
 
 
 
1134
  """
1135
  if not isinstance(raw, dict):
1136
  return None
 
 
 
 
 
 
 
 
 
 
1137
  out = {}
1138
  for key in ("low", "high"):
1139
  token = _text(raw.get(key), 40)
1140
  if not token or not _COLOUR.match(token):
1141
  return None
1142
  out[key] = token
 
1143
  return out
1144
 
1145
 
 
152
  _STYLE_MARKS = ("bold", "italic", "underline")
153
  _BORDER_SIDES = ("top", "right", "bottom", "left")
154
 
155
+ #: ⭐⭐ S67-T14 / CONTRACT C2: Excel's seven border line styles, name for name. Mirrored in
156
+ #: `aios-web/web/src/sheet/types.ts::CELL_BORDER_STYLES`, and `verify_sheet.py` compares the two
157
+ #: lists. A side is either the legacy `True` (read as a thin black line and stored unchanged, so a
158
+ #: document written before S67 reads back byte for byte) or `{"style": <one of these>,
159
+ #: "color": "#rrggbb"}`.
160
+ CELL_BORDER_STYLES = ("thin", "medium", "thick", "dashed", "dotted", "double", "hair")
161
+ _BORDER_COLOUR = re.compile(r"^#[0-9a-f]{6}$")
162
+
163
  #: R8's indent, in steps rather than pixels: a stored pixel count would be a layout decision that
164
  #: outlives every layout change, exactly as a stored hex outlives a palette.
165
  _MAX_INDENT = 8
 
212
  #: every rule written before this ticket already is, so writing the word onto them would make a
213
  #: reload compare unequal to the save. Mirrored in `web/src/sheet/types.ts::SHEET_RULE_KINDS`.
214
  SHEET_RULE_KINDS = ("cell", "scale", "bar", "formula")
215
+ #: ⭐ S67-T13: Excel's colour scale point types, one list for both ends. `lowest` / `highest` are
216
+ #: measured from the range at paint, so the scale re-spreads as the data changes; the other three
217
+ #: read their number from the rule's `value` (low end) or `value2` (high end). A type outside this
218
+ #: list is REFUSED by name, never dropped: a dropped type reads back as a different scale. Mirrored
219
+ #: in `web/src/sheet/types.ts::SheetRuleScaleType`.
220
+ SHEET_RULE_SCALE_TYPES = ("lowest", "highest", "number", "percent", "percentile")
221
  # The client compiler accepts 500 characters per condition.
222
  MAX_RULE_FORMULA_LENGTH = 500
223
 
 
666
 
667
  border = raw.get("border")
668
  if isinstance(border, dict):
669
+ sides = {}
670
+ for side in _BORDER_SIDES:
671
+ line = _clean_border_side(border.get(side))
672
+ if line is not None:
673
+ sides[side] = line
674
  if sides:
675
  out["border"] = sides
676
 
677
  return out or None
678
 
679
 
680
+ def _clean_border_side(raw):
681
+ """One C2 border side: `True`, a `{style, color}` dict, or None when the side is absent.
682
+
683
+ ⛔⛔ THE SECOND DOCUMENTED EXCEPTION TO "UNKNOWN KEYS ARE DROPPED IN SILENCE". A border side
684
+ that names a line style outside the seven, or a colour that is not a six digit hex, is
685
+ REFUSED by name. Dropping it would store a cell with no line where the person drew one, and
686
+ the caller could not learn its request went nowhere: `_clean_format`'s reason, one key over.
687
+ A side that is `False`, None or absent is simply no side. A legacy `True` stays `True`.
688
+ """
689
+ if raw is None or raw is False:
690
+ return None
691
+ if raw is True:
692
+ return True
693
+ if not isinstance(raw, dict):
694
+ return None
695
+ style = raw.get("style")
696
+ colour = raw.get("color")
697
+ if isinstance(colour, str):
698
+ colour = colour.strip().lower()
699
+ if (not isinstance(style, str) or style not in CELL_BORDER_STYLES
700
+ or not isinstance(colour, str) or not _BORDER_COLOUR.match(colour)):
701
+ raise SheetRefusal(
702
+ "cell_border_invalid",
703
+ "A border needs a line style such as thin and a six digit hex colour such as #000000.")
704
+ return {"style": style, "color": colour}
705
+
706
+
707
  # ── the cell ─────────────────────────────────────────────────────────────────────────────────
708
 
709
  def _clean_validation(raw):
 
1176
  ⚠ THE SCALE'S BOUNDS ARE NOT HERE. They ride `value` and `value2` on the rule itself, which
1177
  `_clean_rules` already persists for every op that takes operands, so a colour scale needed no
1178
  new numeric slot at all.
1179
+
1180
+ ⭐ S67-T13: `minType` / `maxType` say what each end MEANS (`SHEET_RULE_SCALE_TYPES`). Each is
1181
+ kept only when present and never injected, so a stored boundless scale reads back byte for
1182
+ byte, and input with no types returns exactly the `{low, high}` it always did. An unknown type
1183
+ is refused by name.
1184
  """
1185
  if not isinstance(raw, dict):
1186
  return None
1187
+ types = {}
1188
+ for key in ("minType", "maxType"):
1189
+ kind = raw.get(key)
1190
+ if kind is None or kind == "":
1191
+ continue
1192
+ if kind not in SHEET_RULE_SCALE_TYPES:
1193
+ raise SheetRefusal(
1194
+ "sheet_rule_scale_type_unknown",
1195
+ "A colour scale end must be one of " + ", ".join(SHEET_RULE_SCALE_TYPES) + ".")
1196
+ types[key] = kind
1197
  out = {}
1198
  for key in ("low", "high"):
1199
  token = _text(raw.get(key), 40)
1200
  if not token or not _COLOUR.match(token):
1201
  return None
1202
  out[key] = token
1203
+ out.update(types)
1204
  return out
1205
 
1206
 
platform/harness/amazon_client.py CHANGED
@@ -1457,7 +1457,10 @@ def group_a_records(fields, operation, *, start=None, end=None, asins=(),
1457
  params.update(includedData="summaries,issues,offers,fulfillmentAvailability,attributes", pageSize=20)
1458
  root, payload_key, next_key = "items", None, "pageToken"
1459
  else:
1460
- params.update(identifiersType="ASIN", includedData="summaries,salesRanks,dimensions,attributes",
 
 
 
1461
  pageSize=20)
1462
  root, payload_key, next_key = "items", None, "pageToken"
1463
  batches = [None]
 
1457
  params.update(includedData="summaries,issues,offers,fulfillmentAvailability,attributes", pageSize=20)
1458
  root, payload_key, next_key = "items", None, "pageToken"
1459
  else:
1460
+ # `relationships` (S67-T29, O23): same Catalog Items endpoint and Product Listing role;
1461
+ # it carries VARIATION parentAsins so the mirror can map every own ASIN to its parent.
1462
+ params.update(identifiersType="ASIN",
1463
+ includedData="summaries,salesRanks,dimensions,attributes,relationships",
1464
  pageSize=20)
1465
  root, payload_key, next_key = "items", None, "pageToken"
1466
  batches = [None]
platform/harness/amazon_store.py CHANGED
@@ -853,6 +853,206 @@ def _sqp_catalogue(con):
853
  return []
854
 
855
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
856
  def sqp_limit_sentence(marker):
857
  """Pure projection of saved sync facts; never asks Amazon for a catalogue."""
858
  numbers = [marker[k] for k in ("maxChars", "maxPerBatch", "asinCount", "batchCount")]
@@ -1470,6 +1670,21 @@ def _blob_metadata(data):
1470
  return {"bytes": len(data), "sha256": hashlib.sha256(data).hexdigest()}
1471
 
1472
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1473
  def _checked_mirror_blob(rt, path, metadata):
1474
  data = rt.download_bytes(MIRROR_PREFIX + path)
1475
  if data is None or _blob_metadata(data) != {k: metadata.get(k) for k in ("bytes", "sha256")}:
@@ -1477,11 +1692,195 @@ def _checked_mirror_blob(rt, path, metadata):
1477
  return data
1478
 
1479
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1480
  def restore_mirror(tenant_key, rt, log=None):
1481
  """Restore once per process and tenant, with all blobs validated before one atomic commit.
1482
 
1483
  The tenant runtime is the only store door. A bad snapshot never partially replaces tables;
1484
  the caller gets a problem and the unchanged first-load decision can rebuild it from Amazon.
 
1485
  """
1486
  log = print if log is None else log
1487
  cache_key = _mirror_cache_key(tenant_key, rt)
@@ -1496,46 +1895,25 @@ def restore_mirror(tenant_key, rt, log=None):
1496
  # a process whose mirror survived re-uploaded EVERY table on its first checkpoint
1497
  # (39 tables, 19.5 MB). The small stored manifest lets unchanged bytes be skipped.
1498
  try:
1499
- raw = rt.download_bytes(MIRROR_PREFIX + "manifest.json")
1500
  saved = json.loads(raw) if raw else {}
1501
- if (saved.get("version") == 1 and saved.get("tenant") == _tenant_key(tenant_key)
1502
  and isinstance(saved.get("tables"), dict)):
1503
  result["manifest"] = saved
1504
  except Exception: # noqa: BLE001
1505
  pass
 
1506
  _MIRROR_CACHE[cache_key] = result
1507
  return result
1508
- raw = rt.download_bytes(MIRROR_PREFIX + "manifest.json")
1509
  if raw is None:
1510
  result["state"] = "absent"
1511
  else:
1512
  obligation = retention_check(tenant_key, rt=rt, raise_overdue=True)
1513
  if obligation["earliestTriggerAt"]:
1514
  raise ValueError("Amazon deletion is outstanding; saved data cannot be restored")
1515
- manifest = json.loads(raw)
1516
- if (manifest.get("version") != 1 or manifest.get("tenant") != _tenant_key(tenant_key)
1517
- or not isinstance(manifest.get("tables"), dict)):
1518
- raise ValueError("Amazon mirror manifest has an invalid version, tenant or table map")
1519
- state_bytes = _checked_mirror_blob(rt, "sync_state.json", manifest["sync_state"])
1520
- rows = json.loads(state_bytes)
1521
- if (not isinstance(rows, list) or len(rows) != manifest["sync_state"]["rows"]
1522
- or not rows or any(not isinstance(row, list) or len(row) != 6
1523
- or not isinstance(row[0], str) or not row[0].startswith(PREFIX) for row in rows)
1524
- or len({row[0] for row in rows}) != len(rows)):
1525
- raise ValueError("Amazon mirror state is incomplete or contains unrelated entities")
1526
  with tempfile.TemporaryDirectory(prefix="amazon-restore-") as tmp:
1527
- paths, total = {}, 0
1528
- for name, metadata in manifest["tables"].items():
1529
- if not re.fullmatch(r"amzn_[a-z0-9_]+", name):
1530
- raise ValueError("Amazon mirror manifest contains an invalid table name")
1531
- data = _checked_mirror_blob(rt, name + ".parquet", metadata)
1532
- path = Path(tmp) / (name + ".parquet")
1533
- path.write_bytes(data)
1534
- count = con.execute("SELECT count(*) FROM read_parquet(?)", [str(path)]).fetchone()[0]
1535
- if type(metadata.get("rows")) is not int or count != metadata["rows"]:
1536
- raise ValueError("Amazon mirror parquet row count mismatch")
1537
- paths[name] = str(path)
1538
- total += count
1539
  con.execute("BEGIN TRANSACTION")
1540
  try:
1541
  for name, path in paths.items():
@@ -1559,6 +1937,7 @@ def restore_mirror(tenant_key, rt, log=None):
1559
  line = (f"Amazon mirror restored from the store: {len(paths)} tables, {total:,} rows; "
1560
  f"resuming {resume}; settlements after document {document}")
1561
  log(line.replace("\u2014", "-").replace("\u2013", "-").replace("\n", " ").replace("\r", " "))
 
1562
  except Exception as exc:
1563
  result["state"] = "refused"
1564
  message = (f"Amazon mirror restore refused ({type(exc).__name__}); saved manifest, checksums, "
@@ -1572,26 +1951,110 @@ def restore_mirror(tenant_key, rt, log=None):
1572
  return result
1573
 
1574
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1575
  def persist_mirror(tenant_key, rt, con, changed_tables, *, report, log=print):
1576
  """Checkpoint changed tables and all Amazon markers, publishing the manifest last.
1577
 
1578
  Candidates include partially written tables. Hashing their parquet locally avoids reuploading
1579
  identical content; no previous blobs are downloaded on a sync pass. Failed candidates remain
1580
  dirty for retry on the next pass, while landed local rows and cursors stay usable.
 
 
 
 
 
 
1581
  """
1582
  uploaded = 0
1583
  with _MIRROR_LOCK:
1584
  cache = restore_mirror(tenant_key, rt, log=log)
1585
  cache["dirty"].update(changed_tables)
1586
  try:
 
 
 
 
 
 
 
1587
  old = cache["manifest"]
 
1588
  tables = {name for name, kind in _amazon_objects(con)
1589
  if name.startswith(PREFIX) and kind == "BASE TABLE"}
1590
- manifest = {"version": 1, "tenant": _tenant_key(tenant_key),
1591
  "tables": {name: meta for name, meta in old.get("tables", {}).items() if name in tables}}
1592
- changed = []
1593
  with tempfile.TemporaryDirectory(prefix="amazon-persist-") as tmp:
1594
- for name in sorted((cache["dirty"] | (tables - set(manifest["tables"]))) & tables):
 
 
1595
  if not re.fullmatch(r"amzn_[a-z0-9_]+", name):
1596
  raise ValueError("Amazon mirror table name is invalid")
1597
  path = Path(tmp) / (name + ".parquet")
@@ -1599,28 +2062,49 @@ def persist_mirror(tenant_key, rt, con, changed_tables, *, report, log=print):
1599
  "(FORMAT PARQUET, COMPRESSION ZSTD)", [str(path)])
1600
  data = path.read_bytes()
1601
  metadata = _blob_metadata(data)
1602
- if metadata["sha256"] == manifest["tables"].get(name, {}).get("sha256"):
 
1603
  continue
 
1604
  metadata.update(rows=con.execute(f"SELECT count(*) FROM {_quoted_identifier(name)}").fetchone()[0],
1605
- written_at=_iso(datetime.now(timezone.utc)))
1606
- rt.upload_bytes(MIRROR_PREFIX + name + ".parquet", data)
1607
- uploaded += len(data)
1608
  manifest["tables"][name] = metadata
1609
  changed.append(name)
1610
- rows = [row for row in _sync_state_rows(con) if str(row[0]).startswith(PREFIX)]
1611
- state = _mirror_json(rows)
1612
- state_meta = {**_blob_metadata(state), "rows": len(rows)}
1613
- if rows and (changed or state_meta != old.get("sync_state")
1614
- or manifest["tables"] != old.get("tables", {})):
1615
- rt.upload_bytes(MIRROR_PREFIX + "sync_state.json", state)
1616
- uploaded += len(state)
1617
- manifest.update(sync_state=state_meta, written_at=_iso(datetime.now(timezone.utc)))
1618
- data = _mirror_json(manifest)
1619
- rt.upload_bytes(MIRROR_PREFIX + "manifest.json", data)
1620
- uploaded += len(data)
1621
- cache["manifest"] = manifest
1622
- cache["problems"].clear()
1623
- cache["dirty"].clear()
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1624
  log(f"Amazon mirror persisted to the store: {len(changed)} changed tables, {uploaded:,} bytes uploaded")
1625
  except Exception as exc:
1626
  message = (f"Amazon mirror persistence failed ({type(exc).__name__}); {uploaded:,} bytes uploaded. "
@@ -1629,20 +2113,41 @@ def persist_mirror(tenant_key, rt, con, changed_tables, *, report, log=print):
1629
  log(message)
1630
 
1631
 
 
 
 
 
 
 
 
 
 
 
1632
  def _purge_saved_mirror(tenant_key, rt, local_tables):
1633
- """Delete data before its inventory so a failed deletion remains retryable after restart."""
 
 
 
 
 
1634
  with _MIRROR_LOCK:
1635
  key = _mirror_cache_key(tenant_key, rt)
1636
  cached = _MIRROR_CACHE.get(key, {})
1637
- raw = rt.download_bytes(MIRROR_PREFIX + "manifest.json")
1638
- manifest = json.loads(raw) if raw else {}
 
 
 
 
1639
  names = ({table_name(t) for t in TABLES} | set(local_tables) | set(manifest.get("tables", {}))
1640
  | set(cached.get("manifest", {}).get("tables", {})) | set(cached.get("dirty", ())))
1641
- paths = []
1642
- for name in sorted(names):
1643
- if re.fullmatch(r"amzn_[a-z0-9_]+", name):
1644
- paths.append(MIRROR_PREFIX + name + ".parquet")
1645
- paths.extend((MIRROR_PREFIX + "sync_state.json", MIRROR_PREFIX + "manifest.json"))
 
 
1646
  for path in paths:
1647
  if rt.delete_path(path) is False or rt.download_bytes(path) is not None:
1648
  raise RuntimeError("Amazon saved mirror deletion failed or left residue")
@@ -2117,8 +2622,14 @@ def _record_reconciliation(con, table, marker):
2117
  _record_state(con, key, "done", detail=json.dumps(marker, separators=(",", ":")))
2118
 
2119
 
2120
- def _replace_period(con, table, rows, columns, column, start, end=None, marker=None):
2121
- """Atomic range/date replacement and proof; an empty restatement removes old rows too."""
 
 
 
 
 
 
2122
  mirror = table_name(table)
2123
  columns = list(dict.fromkeys([*columns, column, *_ORIGIN_TYPES]))
2124
  # All JSON money columns remain fractional even when today's amounts are integers.
@@ -2129,6 +2640,10 @@ def _replace_period(con, table, rows, columns, column, start, end=None, marker=N
2129
  predicate = ('CAST(posted_date AS TIMESTAMPTZ) >= CAST(? AS TIMESTAMPTZ) AND '
2130
  'CAST(posted_date AS TIMESTAMPTZ) < CAST(? AS TIMESTAMPTZ)')
2131
  params = [start, end] if end else [start]
 
 
 
 
2132
  con.execute("BEGIN TRANSACTION")
2133
  try:
2134
  con.execute(f'DELETE FROM {mirror} WHERE {predicate}', params)
@@ -2177,11 +2692,13 @@ def _snapshot_identity(table, row):
2177
 
2178
 
2179
  def _replace_legacy_snapshot(con, table, columns, rows, meta, source_count):
2180
- """Replace complete returned data dates, preserving history and the separate AWD leg.
2181
 
2182
  Listings is a catalogue as of the vendor's data/creation date. The ledger is a DAILY
2183
  summary: its row date wins over the report creation date, including multi-date documents.
2184
  Duplicate source identities refuse the whole document rather than silently dropping rows.
 
 
2185
  """
2186
  stamp = meta.get("dataEndTime") or meta.get("dataStartTime") or meta.get("createdTime")
2187
  if not stamp and (table == "listings" or not rows):
@@ -2210,16 +2727,11 @@ def _replace_legacy_snapshot(con, table, columns, rows, meta, source_count):
2210
  dates = sorted(counts)
2211
  marker = {"start": dates[0], "end": dates[-1], "column": "_snapshot_date",
2212
  "count": source_count, "dates": counts, "document": meta.get("reportDocumentId")}
2213
- placeholders = ",".join("?" for _ in dates)
2214
- predicate = f"_snapshot_date IN ({placeholders})"
2215
- # Undated pre-migration copies cannot be attributed to a day. Replace them once with
2216
- # dated source evidence; never fabricate a date from the time we happened to fetch.
2217
- predicate = f"({predicate} OR _snapshot_date IS NULL)"
2218
- if table == "inventory":
2219
- predicate += " AND COALESCE(inventory_source, 'FBA') <> 'AWD'"
2220
  con.execute("BEGIN TRANSACTION")
2221
  try:
2222
- con.execute(f"DELETE FROM {mirror} WHERE {predicate}", dates)
2223
  count = _replace(con, mirror, columns, types, rows)
2224
  _record_reconciliation(con, table, marker)
2225
  con.execute("COMMIT")
@@ -2306,6 +2818,13 @@ def _sync_margin_window(con, table, fields, w0, w1, *, max_wait, log):
2306
  document = "operation:" + uuid.uuid4().hex
2307
  rows = [_origin(_flatten_row(_without_buyer_data(row)), document, i, spec["api"])
2308
  for i, row in enumerate(records, 1)]
 
 
 
 
 
 
 
2309
  column = "_snapshot_date" if spec.get("snapshot") else "_period_start"
2310
  period = datetime.now(timezone.utc).date().isoformat() if spec.get("snapshot") else start
2311
  for row in rows:
@@ -2322,7 +2841,8 @@ def _sync_margin_window(con, table, fields, w0, w1, *, max_wait, log):
2322
  raise ValueError("Amazon order metrics returned an interval outside the requested period")
2323
  row[column] = _iso(day)
2324
  return _replace_period(con, table, rows, sorted({k for r in rows for k in r}),
2325
- column, period, end if table == "order_metrics" else None, marker=marker)
 
2326
  kwargs = {} if spec.get("snapshot") else {
2327
  "start": _iso(w0), "end": _iso(w1 - timedelta(seconds=1))}
2328
  options = dict(spec.get("options") or {})
@@ -2370,7 +2890,8 @@ def _sync_margin_window(con, table, fields, w0, w1, *, max_wait, log):
2370
  marker = {"start": period, "end": _iso(w1) if column == "_period_start" else period,
2371
  "column": column, "count": document_row_count(
2372
  text, (spec["json_root"], *spec.get("json_extra_roots", ())) if spec.get("json_root") else ())}
2373
- return _replace_period(con, table, rows, columns, column, period, marker=marker)
 
2374
 
2375
 
2376
  def _order_metric_totals(records, *, flattened=False):
@@ -2605,7 +3126,13 @@ def sync(tenant_key="royal-imports", tables=None, since=None, log=print, rt=None
2605
  pending = list(dict.fromkeys([head for head, sibling in SHARED_REPORT_SIBLINGS.items()
2606
  if head in want and sibling in want] + want))
2607
  handled, noted = set(), set()
 
2608
  changed_tables = set()
 
 
 
 
 
2609
 
2610
  def write_window(table, cols, types, rows):
2611
  count, note = replace_window(con, table_name(table), cols, types, rows,
@@ -2875,7 +3402,8 @@ def sync(tenant_key="royal-imports", tables=None, since=None, log=print, rt=None
2875
  {"state": "access", "operation": "report_document"}, rt, report, log)
2876
  text, meta = cx.report_document(
2877
  fields, rtype, start=_iso(w0), end=_iso(w1), max_wait=max_wait,
2878
- log=lambda message: log(f"{table}: {message}"))
 
2879
  if root:
2880
  parsed_cols, rows = parse_json_report(
2881
  text, root, document_id=meta.get("reportDocumentId"), report_type=rtype)
@@ -2937,6 +3465,8 @@ def sync(tenant_key="royal-imports", tables=None, since=None, log=print, rt=None
2937
  cols.append("inventory_source")
2938
  if table == "pricing":
2939
  pricing_asins.extend(_pricing_asins(rows))
 
 
2940
  types = _ensure(con, mirror, cols, rows, declared=declared,
2941
  preserve_rows=True) if cols else {}
2942
  # Explicit windows and first loads replace the mirror; incremental passes keep history.
@@ -3364,16 +3894,16 @@ def snapshot_selftest(log=print, check=None):
3364
  "FROM amzn_listings").fetchone() == (2, 2))
3365
  meta["createdTime"] = "2026-09-26T11:00:00Z"
3366
  sync(rt.key, tables=[table], rt=rt, log=lambda *_a: None)
3367
- ck("NC two listing dates keep two copies", lambda:
 
3368
  con.execute("SELECT _snapshot_date, COUNT(*) FROM amzn_listings "
3369
- "GROUP BY 1 ORDER BY 1").fetchall() == [("2026-09-25", 2), ("2026-09-26", 2)]
3370
  and len(calls) == 2 and all("start" not in c and "end" not in c for c in calls))
3371
  payload[0] = "seller-sku\tquantity\nA\t9\n"
3372
  sync(rt.key, tables=[table], since=start, rt=rt, log=lambda *_a: None)
3373
- ck("same listing date replaces removed SKUs and retains the previous date", lambda:
3374
  con.execute("SELECT _snapshot_date, seller_sku, quantity FROM amzn_listings "
3375
- "ORDER BY 1, 2").fetchall()
3376
- == [("2026-09-25", "A", 2), ("2026-09-25", "B", 3), ("2026-09-26", "A", 9)]
3377
  and valid()["state"] == "ok")
3378
  else:
3379
  ck("ledger keeps one row per data date, SKU, disposition and location", lambda:
@@ -3387,10 +3917,11 @@ def snapshot_selftest(log=print, check=None):
3387
  before_awd = con.execute("SELECT * FROM amzn_inventory WHERE inventory_source='AWD'").fetchall()
3388
  payload[0] = ledger_header + "09/24/2026\tA\tFA\tAA\tSELLABLE\tUS\t9\n"
3389
  sync(rt.key, tables=[table], since=start, rt=rt, log=lambda *_a: None)
3390
- ck("ledger same data date replaces while older dates survive", lambda:
 
3391
  con.execute("SELECT _snapshot_date, ending_warehouse_balance FROM amzn_inventory "
3392
  "WHERE inventory_source='FBA' ORDER BY 1").fetchall()
3393
- == [("2026-09-23", 2), ("2026-09-24", 9)])
3394
  ck("FBA replacement preserves AWD rows exactly", lambda:
3395
  con.execute("SELECT * FROM amzn_inventory WHERE inventory_source='AWD'").fetchall() == before_awd)
3396
  # The AWD operation's existing reconciliation still checks its own rows.
@@ -3419,8 +3950,8 @@ def snapshot_selftest(log=print, check=None):
3419
  if table == "listings":
3420
  payload[0] = "seller-sku\tquantity\n"
3421
  sync(rt.key, tables=[table], rt=rt, log=lambda *_a: None)
3422
- ck("empty listing restatement clears only that date and stays unproven", lambda:
3423
- count() == 2 and valid()["state"] == "unproven")
3424
  meta["dataEndTime"] = "2026-09-27T23:00:00Z"
3425
  payload[0] = "seller-sku\tquantity\n" + "".join(f"S{i}\t1\n" for i in range(1205))
3426
  sync(rt.key, tables=[table], rt=rt, log=lambda *_a: None)
@@ -3436,6 +3967,308 @@ def snapshot_selftest(log=print, check=None):
3436
  "SELECT COUNT(*) FROM amzn_inventory WHERE _snapshot_date='2026-09-25' "
3437
  "AND fnsku='F-fallback'").fetchone()[0] == 1)
3438
  con.close()
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3439
  return len(failures)
3440
 
3441
 
@@ -3666,8 +4499,19 @@ def margin_selftest(log=print, check=None):
3666
  "sku\tasin\nS1\tA1\n", {"reportDocumentId": "next-snapshot", "dataEndTime": "2026-09-03T00:00:00Z"})):
3667
  _sync_margin_window(con, "referral_fees", {}, None, None, max_wait=1, log=log)
3668
  _sync_margin_window(con, "referral_fees", {}, None, None, max_wait=1, log=log)
3669
- ck("margin two snapshot dates survive while same-date replay stays idempotent",
3670
- con.execute("SELECT COUNT(*), COUNT(DISTINCT _snapshot_date) FROM amzn_referral_fees").fetchone() == (2, 2))
 
 
 
 
 
 
 
 
 
 
 
3671
  _replace_period(con, "economics", [], [c[1] for c in con.execute("PRAGMA table_info('amzn_economics')").fetchall()],
3672
  "start_date", "2026-09-01", "2026-09-03")
3673
  ck("margin empty economics restatement deletes stale detail and stays unproven",
@@ -4188,6 +5032,9 @@ def group_a_selftest(log=print, check=None):
4188
  sent = [a for _, params in requests[::3] for a in params["identifiers"].split(",")]
4189
  ck("catalog search covers all forty-one own ASINs in batches of twenty",
4190
  sent == args["asins"] and all(len(p["identifiers"].split(",")) <= 20 for _, p in requests))
 
 
 
4191
  if operation == "getInventorySummaries":
4192
  ck("FBA inventory requests detailed inventory on every page",
4193
  all(p["details"] == "true" for _, p in requests))
@@ -4204,6 +5051,205 @@ def group_a_selftest(log=print, check=None):
4204
  return len(requests) == 3 and len(rows) == 2 and requests[1]["createdBefore"] == requests[2]["createdAfter"]
4205
  ck("Listings search splits date ranges at the real thousand-SKU ceiling",
4206
  not partition_probe(False) and partition_probe(True))
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4207
  return 1 if failures else 0
4208
 
4209
 
 
853
  return []
854
 
855
 
856
+ _ASIN_RE = re.compile(r"[A-Z0-9]{10}")
857
+
858
+
859
+ def _columns_of(con, table):
860
+ return {r[0] for r in con.execute(
861
+ "SELECT column_name FROM information_schema.columns WHERE table_name=?", [table]).fetchall()}
862
+
863
+
864
+ _NEWEST_ORDER = ("start_date", "_period_start", "_snapshot_date", "_report_row_number")
865
+
866
+
867
+ def _newest_child_parent_sql(columns, table, only=None):
868
+ """SELECT child_asin, parent_asin: one row per child, the newest period's parent; None if absent.
869
+
870
+ `only` is an optional SQL SELECT of the child ASINs wanted. It filters BEFORE the window, which
871
+ keeps or drops whole `child_asin` partitions, so every kept child's answer is unchanged. Once
872
+ the catalog carries parents (its first sync after S67-T29), `asin_parents_sql` passes only the
873
+ few own ASINs the catalog leaves without one, so S67-T30's per-page lookup stops ranking all of
874
+ economics (572,320 rows on staging, about 100 ms a query) to answer them.
875
+ """
876
+ if not {"child_asin", "parent_asin"} <= columns:
877
+ return None
878
+ order = ", ".join(f'"{c}" DESC NULLS LAST' for c in _NEWEST_ORDER if c in columns) or "1"
879
+ wanted = f" AND TRIM(CAST(child_asin AS VARCHAR)) IN ({only})" if only else ""
880
+ return (f'SELECT child_asin, parent_asin FROM (SELECT TRIM(CAST(child_asin AS VARCHAR)) AS child_asin, '
881
+ f'TRIM(CAST(parent_asin AS VARCHAR)) AS parent_asin, ROW_NUMBER() OVER ('
882
+ f'PARTITION BY TRIM(CAST(child_asin AS VARCHAR)) ORDER BY {order}) AS _rn FROM "{table}" '
883
+ f"WHERE child_asin IS NOT NULL AND parent_asin IS NOT NULL "
884
+ f"AND TRIM(CAST(parent_asin AS VARCHAR)) <> ''{wanted}) WHERE _rn = 1")
885
+
886
+
887
+ def _child_parent_map(con, table):
888
+ """child ASIN -> parent ASIN from the newest rows of `table`; {} when it has no child_asin."""
889
+ sql = _newest_child_parent_sql(_columns_of(con, table), table)
890
+ if sql is None:
891
+ return {}
892
+ return {str(c): str(p) for c, p in con.execute(sql).fetchall()
893
+ if _ASIN_RE.fullmatch(str(c)) and _ASIN_RE.fullmatch(str(p))}
894
+
895
+
896
+ def _pricing_parent_map(con):
897
+ """O23 fallback. Used only when pricing HAS child_asin: the live Sales and Traffic mirror is
898
+ stored at parent granularity (parent_asin only), so this is {} there and economics carries on."""
899
+ return _child_parent_map(con, "amzn_pricing")
900
+
901
+
902
+ def _economics_parent_map(con):
903
+ """Data Kiosk economics child_asin -> parent_asin, newest start_date wins."""
904
+ return _child_parent_map(con, "amzn_economics")
905
+
906
+
907
+ def _catalog_parent(item, asin, pricing_map, marketplace, economics_map=None):
908
+ """One item's (parent_asin, source); never raises on a missing or malformed `relationships`."""
909
+ parents, is_parent = [], False
910
+ groups = item.get("relationships")
911
+ for group in groups if isinstance(groups, list) else ():
912
+ if not isinstance(group, dict):
913
+ continue
914
+ if marketplace and group.get("marketplaceId") not in (None, marketplace):
915
+ continue
916
+ entries = group.get("relationships")
917
+ for rel in entries if isinstance(entries, list) else ():
918
+ # Only VARIATION defines a parent; PACKAGE_HIERARCHY is a pack, not a family.
919
+ if not isinstance(rel, dict) or rel.get("type") != "VARIATION":
920
+ continue
921
+ found = rel.get("parentAsins")
922
+ parents += [str(a).strip() for a in (found if isinstance(found, list) else ())
923
+ if _ASIN_RE.fullmatch(str(a).strip())]
924
+ if isinstance(rel.get("childAsins"), list) and rel["childAsins"]:
925
+ is_parent = True
926
+ if parents:
927
+ return parents[0], "relationships"
928
+ if is_parent:
929
+ return asin, "relationships"
930
+ for source, mapping in (("pricing", pricing_map), ("economics", economics_map)):
931
+ fallback = str((mapping or {}).get(asin) or "").strip()
932
+ if _ASIN_RE.fullmatch(fallback):
933
+ return fallback, source
934
+ return asin, "self"
935
+
936
+
937
+ def catalog_parent_map(items, pricing_map=None, marketplace=None, economics_map=None):
938
+ """S67-T29 (O23): own ASIN -> (parent ASIN, source) for every catalog item.
939
+
940
+ Source order: the catalog VARIATION `parentAsins` for the requested marketplace; an item that
941
+ is itself a variation parent maps to itself; else pricing's `parent_asin` for that ASIN as
942
+ `child_asin` (O23); else economics child_asin -> parent_asin; else itself. A standalone ASIN
943
+ therefore maps to itself, never an error.
944
+ """
945
+ out = {}
946
+ for item in items or ():
947
+ if not isinstance(item, dict):
948
+ continue
949
+ asin = str(item.get("asin") or "").strip()
950
+ if asin:
951
+ out[asin] = _catalog_parent(item, asin, pricing_map, marketplace, economics_map)
952
+ return out
953
+
954
+
955
+ #: S67 lane D (S67-T29 finding): Sales and Traffic defaults `asinGranularity` to PARENT, so the
956
+ #: saved `amzn_pricing` mirror carried `parent_asin` with no `child_asin` and no `sku`, and
957
+ #: `connector_spec`'s pricing identity `(child_asin, parent_asin)` and its two listings links never
958
+ #: formed. SKU grain returns parentAsin, childAsin and sku per row: the SAME report type and role
959
+ #: (the PRD's Amazon compliance line: no new endpoint or role).
960
+ REPORT_OPTIONS = {"pricing": {"asinGranularity": "SKU"}}
961
+
962
+
963
+ def _pricing_regrain(con, mirror, rows, log=print):
964
+ """Clear a PARENT-grain pricing mirror before the first SKU-grain rows land; True if cleared.
965
+
966
+ `amzn_pricing` keeps history across incremental passes, so without this the old parent-grain
967
+ days would sit beside SKU-grain days and any sum across days would count twice. A mirror that
968
+ already holds any `child_asin`, an empty or absent mirror, or rows without `child_asin` are
969
+ left alone.
970
+ """
971
+ if not any((row or {}).get("child_asin") for row in rows):
972
+ return False
973
+ have = _columns_of(con, mirror) # empty for an absent table (first load), never raises
974
+ if not have:
975
+ return False
976
+ if "child_asin" in have and con.execute(
977
+ f'SELECT COUNT(*) FROM {mirror} WHERE "child_asin" IS NOT NULL').fetchone()[0]:
978
+ return False
979
+ stale = con.execute(f"SELECT COUNT(*) FROM {mirror}").fetchone()[0]
980
+ if not stale:
981
+ return False
982
+ con.execute(f"DELETE FROM {mirror} WHERE 1=1")
983
+ log(f" pricing: replaced {stale} parent-grain rows with SKU-grain rows (one grain per table)")
984
+ return True
985
+
986
+
987
+ def asin_parents_sql(con):
988
+ """S67-T29: ONE read-time resolver, one row per own ASIN: `(asin, parent_asin, parent_asin_source)`.
989
+
990
+ Own ASINs = DISTINCT listings `asin1` UNION the LATEST catalog `_snapshot_date`'s `asin` (the
991
+ snapshot tables keep one copy per sync day, D-3031, so only the newest day counts). Parent =
992
+ that latest catalog row's `parent_asin` (source as stamped at sync), else pricing child_asin ->
993
+ parent_asin when the pricing mirror carries child_asin (source `pricing`, O23), else economics
994
+ child_asin -> parent_asin (newest start_date, source `economics`), else the ASIN itself
995
+ (`self`). Covers own ASINs Amazon's catalog search returns no item for, without stub catalog
996
+ rows. Degrades with absent tables or columns; None only when no own-ASIN source exists.
997
+ Reusable verbatim by a SQL join (S67-T30): wrap it as a subquery.
998
+ """
999
+ listings, catalog = _columns_of(con, "amzn_listings"), _columns_of(con, "amzn_catalog_items")
1000
+ latest = ('(SELECT MAX("_snapshot_date") FROM amzn_catalog_items)')
1001
+ own = []
1002
+ if "asin1" in listings:
1003
+ own.append("SELECT TRIM(CAST(asin1 AS VARCHAR)) AS asin FROM amzn_listings WHERE asin1 IS NOT NULL")
1004
+ has_catalog = {"asin", "_snapshot_date"} <= catalog
1005
+ if has_catalog:
1006
+ own.append("SELECT TRIM(CAST(asin AS VARCHAR)) AS asin FROM amzn_catalog_items "
1007
+ f'WHERE asin IS NOT NULL AND "_snapshot_date" = {latest}')
1008
+ if not own:
1009
+ return None
1010
+ ctes = ["own AS (SELECT DISTINCT asin FROM (" + " UNION ".join(own) + ") WHERE asin <> '')"]
1011
+ joins, parents, sources = [], [], []
1012
+ if has_catalog and "parent_asin" in catalog:
1013
+ source = ("CAST(parent_asin_source AS VARCHAR)" if "parent_asin_source" in catalog
1014
+ else "'relationships'")
1015
+ order = '"_report_row_number"' if "_report_row_number" in catalog else "1"
1016
+ ctes.append(
1017
+ "cat AS (SELECT asin, parent_asin, parent_asin_source FROM (SELECT TRIM(CAST(asin AS VARCHAR)) AS asin, "
1018
+ "TRIM(CAST(parent_asin AS VARCHAR)) AS parent_asin, "
1019
+ f"COALESCE({source}, 'relationships') AS parent_asin_source, ROW_NUMBER() OVER ("
1020
+ f"PARTITION BY TRIM(CAST(asin AS VARCHAR)) ORDER BY {order}) AS _rn FROM amzn_catalog_items "
1021
+ f"WHERE \"_snapshot_date\" = {latest} AND parent_asin IS NOT NULL "
1022
+ "AND TRIM(CAST(parent_asin AS VARCHAR)) <> '') WHERE _rn = 1)")
1023
+ joins.append("LEFT JOIN cat ON cat.asin = own.asin")
1024
+ parents.append("cat.parent_asin")
1025
+ sources.append("WHEN cat.parent_asin IS NOT NULL THEN cat.parent_asin_source")
1026
+ # Economics is only the fallback, so rank only the own ASINs the catalog left without a parent.
1027
+ only = "SELECT asin FROM own" + (" WHERE asin NOT IN (SELECT asin FROM cat)" if joins else "")
1028
+ # O23: pricing is the fallback BEFORE economics. None (no step) while the pricing mirror has no
1029
+ # `child_asin`, which is the live Sales and Traffic mirror today (S67-T29 finding).
1030
+ pricing = _newest_child_parent_sql(_columns_of(con, "amzn_pricing"), "amzn_pricing", only=only)
1031
+ if pricing:
1032
+ ctes.append(f"pri AS ({pricing})")
1033
+ joins.append("LEFT JOIN pri ON pri.child_asin = own.asin")
1034
+ parents.append("pri.parent_asin")
1035
+ sources.append("WHEN pri.parent_asin IS NOT NULL THEN 'pricing'")
1036
+ economics = _newest_child_parent_sql(_columns_of(con, "amzn_economics"), "amzn_economics",
1037
+ only=only)
1038
+ if economics:
1039
+ ctes.append(f"eco AS ({economics})")
1040
+ joins.append("LEFT JOIN eco ON eco.child_asin = own.asin")
1041
+ parents.append("eco.parent_asin")
1042
+ sources.append("WHEN eco.parent_asin IS NOT NULL THEN 'economics'")
1043
+ return ("WITH " + ", ".join(ctes) + " SELECT own.asin AS asin, "
1044
+ f"COALESCE({', '.join([*parents, 'own.asin'])}) AS parent_asin, "
1045
+ + (f"CASE {' '.join(sources)} ELSE 'self' END" if sources else "'self'")
1046
+ + " AS parent_asin_source "
1047
+ "FROM own " + " ".join(joins) + " ORDER BY own.asin")
1048
+
1049
+
1050
+ def asin_parents(con):
1051
+ """`asin_parents_sql` as `{asin: (parent_asin, source)}`; {} when no own-ASIN source exists."""
1052
+ sql = asin_parents_sql(con)
1053
+ return {} if sql is None else {a: (p, s) for a, p, s in con.execute(sql).fetchall()}
1054
+
1055
+
1056
  def sqp_limit_sentence(marker):
1057
  """Pure projection of saved sync facts; never asks Amazon for a catalogue."""
1058
  numbers = [marker[k] for k in ("maxChars", "maxPerBatch", "asinCount", "batchCount")]
 
1670
  return {"bytes": len(data), "sha256": hashlib.sha256(data).hexdigest()}
1671
 
1672
 
1673
+ #: S67-T32 (D-3481): v1 names in-place keys (`<table>.parquet`, `sync_state.json`) and still
1674
+ #: restores; v2 names each blob's CONTENT key, so a manifest only ever names complete blobs and a
1675
+ #: key it names is never overwritten. `keys.json` is the write-ahead ledger of every key ever
1676
+ #: uploaded: the store has no list-by-prefix, so without it an orphan is unpurgeable.
1677
+ MANIFEST_VERSIONS = (1, 2)
1678
+ MANIFEST_VERSION = 2
1679
+ _MANIFEST_KEY = "manifest.json"
1680
+ _KEY_LEDGER = "keys.json"
1681
+ _TABLE_BLOB_RE = re.compile(r"(amzn_[a-z0-9_]+)(?:\.([0-9a-f]{16}))?\.parquet")
1682
+ _STATE_BLOB_RE = re.compile(r"sync_state(?:\.([0-9a-f]{16}))?\.json")
1683
+ #: A ledger key no manifest names is a killed checkpoint's orphan once it is this old. A live
1684
+ #: checkpoint publishes within minutes, so the grace never races an in-flight writer.
1685
+ ORPHAN_GRACE = timedelta(hours=24)
1686
+
1687
+
1688
  def _checked_mirror_blob(rt, path, metadata):
1689
  data = rt.download_bytes(MIRROR_PREFIX + path)
1690
  if data is None or _blob_metadata(data) != {k: metadata.get(k) for k in ("bytes", "sha256")}:
 
1692
  return data
1693
 
1694
 
1695
+ def _content_key(stem, suffix, metadata):
1696
+ return f"{stem}.{metadata['sha256'][:16]}{suffix}"
1697
+
1698
+
1699
+ def _table_blob_key(name, metadata, *, strict=True):
1700
+ """The key a manifest entry names: its content key, or the legacy in-place key."""
1701
+ key = str(metadata.get("key") or name + ".parquet")
1702
+ match = _TABLE_BLOB_RE.fullmatch(key)
1703
+ if not match or match.group(1) != name or (
1704
+ strict and match.group(2) and not str(metadata.get("sha256") or "").startswith(match.group(2))):
1705
+ raise ValueError("Amazon mirror manifest names an invalid table blob key")
1706
+ return key
1707
+
1708
+
1709
+ def _state_blob_key(metadata, *, strict=True):
1710
+ key = str(metadata.get("key") or "sync_state.json")
1711
+ match = _STATE_BLOB_RE.fullmatch(key)
1712
+ if not match or (strict and match.group(1)
1713
+ and not str(metadata.get("sha256") or "").startswith(match.group(1))):
1714
+ raise ValueError("Amazon mirror manifest names an invalid state blob key")
1715
+ return key
1716
+
1717
+
1718
+ def _is_mirror_blob_key(key):
1719
+ return bool(_TABLE_BLOB_RE.fullmatch(str(key)) or _STATE_BLOB_RE.fullmatch(str(key)))
1720
+
1721
+
1722
+ def _manifest_keys(manifest, *, strict=True):
1723
+ """{key: sha256} for every blob a manifest names; malformed entries are skipped, never raised."""
1724
+ out = {}
1725
+ if not isinstance(manifest, dict):
1726
+ return out
1727
+ tables = manifest.get("tables")
1728
+ for name, metadata in (tables.items() if isinstance(tables, dict) else ()):
1729
+ try:
1730
+ out[_table_blob_key(str(name), metadata, strict=strict)] = metadata.get("sha256")
1731
+ except (ValueError, AttributeError, TypeError):
1732
+ continue
1733
+ state = manifest.get("sync_state")
1734
+ if isinstance(state, dict):
1735
+ try:
1736
+ out[_state_blob_key(state, strict=strict)] = state.get("sha256")
1737
+ except (ValueError, AttributeError, TypeError):
1738
+ pass
1739
+ return out
1740
+
1741
+
1742
+ def _read_key_ledger(rt, tenant_key):
1743
+ """The write-ahead key ledger. Unreadable is an error: a purge must not guess."""
1744
+ raw = rt.download_bytes(MIRROR_PREFIX + _KEY_LEDGER)
1745
+ key = _tenant_key(tenant_key)
1746
+ if raw is None:
1747
+ return {"version": 1, "tenant": key, "keys": {}}
1748
+ doc = json.loads(raw)
1749
+ if (not isinstance(doc, dict) or doc.get("tenant") != key or not isinstance(doc.get("keys"), dict)):
1750
+ raise ValueError("Amazon mirror key ledger is unreadable or belongs to another tenant")
1751
+ doc["keys"] = {str(k): v for k, v in doc["keys"].items() if _is_mirror_blob_key(k)}
1752
+ return doc
1753
+
1754
+
1755
+ def _ledger_add(rt, tenant_key, keys):
1756
+ """Record keys BEFORE their upload, so a killed checkpoint's blob is always enumerable."""
1757
+ ledger = _read_key_ledger(rt, tenant_key)
1758
+ stamp = _iso(datetime.now(timezone.utc))
1759
+ fresh = [key for key in keys if key not in ledger["keys"]]
1760
+ if not fresh:
1761
+ return
1762
+ for key in fresh:
1763
+ if not _is_mirror_blob_key(key):
1764
+ raise ValueError("Amazon mirror key is outside the naming contract")
1765
+ ledger["keys"][key] = stamp
1766
+ rt.upload_bytes(MIRROR_PREFIX + _KEY_LEDGER, _mirror_json(ledger))
1767
+
1768
+
1769
+ def _validated_snapshot(tenant_key, rt, con, raw, tmp):
1770
+ """Every check restore makes, without writing. -> (manifest, state rows, parquet paths, rows).
1771
+
1772
+ Raises ValueError for anything the stored snapshot itself gets wrong; a store-access failure
1773
+ propagates as its own type, so a caller can tell "unrestorable" from "unreachable".
1774
+ """
1775
+ try:
1776
+ manifest = json.loads(raw)
1777
+ except ValueError as exc:
1778
+ raise ValueError("Amazon mirror manifest is not JSON") from exc
1779
+ if (not isinstance(manifest, dict) or manifest.get("version") not in MANIFEST_VERSIONS
1780
+ or manifest.get("tenant") != _tenant_key(tenant_key)
1781
+ or not isinstance(manifest.get("tables"), dict) or not isinstance(manifest.get("sync_state"), dict)):
1782
+ raise ValueError("Amazon mirror manifest has an invalid version, tenant or table map")
1783
+ state_meta = manifest["sync_state"]
1784
+ state_bytes = _checked_mirror_blob(rt, _state_blob_key(state_meta), state_meta)
1785
+ rows = json.loads(state_bytes)
1786
+ if (not isinstance(rows, list) or len(rows) != state_meta.get("rows")
1787
+ or not rows or any(not isinstance(row, list) or len(row) != 6
1788
+ or not isinstance(row[0], str) or not row[0].startswith(PREFIX) for row in rows)
1789
+ or len({row[0] for row in rows}) != len(rows)):
1790
+ raise ValueError("Amazon mirror state is incomplete or contains unrelated entities")
1791
+ paths, total = {}, 0
1792
+ for name, metadata in manifest["tables"].items():
1793
+ if not re.fullmatch(r"amzn_[a-z0-9_]+", name) or not isinstance(metadata, dict):
1794
+ raise ValueError("Amazon mirror manifest contains an invalid table name")
1795
+ data = _checked_mirror_blob(rt, _table_blob_key(name, metadata), metadata)
1796
+ path = Path(tmp) / (name + ".parquet")
1797
+ path.write_bytes(data)
1798
+ try:
1799
+ count = con.execute("SELECT count(*) FROM read_parquet(?)", [str(path)]).fetchone()[0]
1800
+ except Exception as exc: # noqa: BLE001
1801
+ raise ValueError("Amazon mirror parquet is unreadable") from exc
1802
+ if type(metadata.get("rows")) is not int or count != metadata["rows"]:
1803
+ raise ValueError("Amazon mirror parquet row count mismatch")
1804
+ paths[name] = str(path)
1805
+ total += count
1806
+ return manifest, rows, paths, total
1807
+
1808
+
1809
+ def _snapshot_tables():
1810
+ """Current-state tables: every report or API the client declares `snapshot`."""
1811
+ cx = _client()
1812
+ return tuple(t for t in TABLES if (cx.REPORT_TYPES.get(t) or {}).get("snapshot"))
1813
+
1814
+
1815
+ def _collapse_snapshots(con, log=None):
1816
+ """D-3031 heal: a snapshot table holding more than one pull keeps only the latest.
1817
+
1818
+ -> {mirror: (rows before, rows after, copies)}. The ledger keeps its latest document's
1819
+ dates (a DAILY document spans several), every other table its newest `_snapshot_date`;
1820
+ AWD rows are another leg and never touched. Idempotent: one copy is left alone.
1821
+ """
1822
+ existing = {name for name, kind in _amazon_objects(con) if kind == "BASE TABLE"}
1823
+ collapsed = {}
1824
+ for table in _snapshot_tables():
1825
+ mirror = table_name(table)
1826
+ if mirror not in existing:
1827
+ continue
1828
+ cols = _columns_of(con, mirror)
1829
+ if "_snapshot_date" not in cols:
1830
+ continue
1831
+ scope = ("COALESCE(inventory_source, 'FBA') <> 'AWD'"
1832
+ if table == "inventory" and "inventory_source" in cols else "TRUE")
1833
+ dates = [row[0] for row in con.execute(
1834
+ f"SELECT DISTINCT CAST(_snapshot_date AS VARCHAR) FROM {mirror} WHERE {scope}").fetchall()]
1835
+ present = sorted(d for d in dates if d is not None)
1836
+ if len(dates) <= 1 or not present:
1837
+ continue
1838
+ keep = []
1839
+ if table == "inventory":
1840
+ saved = _read_state(con, entity_key("reconcile_" + table))
1841
+ try:
1842
+ marked = json.loads(saved["detail"])["dates"] if saved and saved.get("detail") else {}
1843
+ except (ValueError, KeyError, TypeError):
1844
+ marked = {}
1845
+ keep = [d for d in present if d in marked]
1846
+ keep = keep or present[-1:]
1847
+ stale = (f"{scope} AND (_snapshot_date IS NULL OR "
1848
+ f"CAST(_snapshot_date AS VARCHAR) NOT IN ({','.join('?' for _ in keep)}))")
1849
+ if not con.execute(f"SELECT count(*) FROM {mirror} WHERE {stale}", keep).fetchone()[0]:
1850
+ continue
1851
+ before = con.execute(f"SELECT count(*) FROM {mirror}").fetchone()[0]
1852
+ con.execute("BEGIN TRANSACTION")
1853
+ try:
1854
+ con.execute(f"DELETE FROM {mirror} WHERE {stale}", keep)
1855
+ con.execute("COMMIT")
1856
+ except Exception:
1857
+ con.execute("ROLLBACK")
1858
+ raise
1859
+ after = con.execute(f"SELECT count(*) FROM {mirror}").fetchone()[0]
1860
+ collapsed[mirror] = (before, after, len(dates))
1861
+ if log:
1862
+ log(f"Amazon snapshot {mirror}: {len(dates)} copies collapsed to the latest, "
1863
+ f"{before:,} rows to {after:,}")
1864
+ return collapsed
1865
+
1866
+
1867
+ def _heal_snapshots(con, result, log):
1868
+ """Collapse after a restore; the healed tables are dirty so the next checkpoint saves one copy."""
1869
+ try:
1870
+ result["dirty"].update(_collapse_snapshots(con, log))
1871
+ except Exception as exc: # noqa: BLE001
1872
+ message = (f"Amazon snapshot collapse failed ({type(exc).__name__}); the next resync of each "
1873
+ "snapshot table replaces its earlier copies.")
1874
+ result["problems"].append(message)
1875
+ log(message)
1876
+
1877
+
1878
  def restore_mirror(tenant_key, rt, log=None):
1879
  """Restore once per process and tenant, with all blobs validated before one atomic commit.
1880
 
1881
  The tenant runtime is the only store door. A bad snapshot never partially replaces tables;
1882
  the caller gets a problem and the unchanged first-load decision can rebuild it from Amazon.
1883
+ Both manifest versions restore: v1's in-place keys exactly as saved, v2's content keys.
1884
  """
1885
  log = print if log is None else log
1886
  cache_key = _mirror_cache_key(tenant_key, rt)
 
1895
  # a process whose mirror survived re-uploaded EVERY table on its first checkpoint
1896
  # (39 tables, 19.5 MB). The small stored manifest lets unchanged bytes be skipped.
1897
  try:
1898
+ raw = rt.download_bytes(MIRROR_PREFIX + _MANIFEST_KEY)
1899
  saved = json.loads(raw) if raw else {}
1900
+ if (saved.get("version") in MANIFEST_VERSIONS and saved.get("tenant") == _tenant_key(tenant_key)
1901
  and isinstance(saved.get("tables"), dict)):
1902
  result["manifest"] = saved
1903
  except Exception: # noqa: BLE001
1904
  pass
1905
+ _heal_snapshots(con, result, log)
1906
  _MIRROR_CACHE[cache_key] = result
1907
  return result
1908
+ raw = rt.download_bytes(MIRROR_PREFIX + _MANIFEST_KEY)
1909
  if raw is None:
1910
  result["state"] = "absent"
1911
  else:
1912
  obligation = retention_check(tenant_key, rt=rt, raise_overdue=True)
1913
  if obligation["earliestTriggerAt"]:
1914
  raise ValueError("Amazon deletion is outstanding; saved data cannot be restored")
 
 
 
 
 
 
 
 
 
 
 
1915
  with tempfile.TemporaryDirectory(prefix="amazon-restore-") as tmp:
1916
+ manifest, rows, paths, total = _validated_snapshot(tenant_key, rt, con, raw, tmp)
 
 
 
 
 
 
 
 
 
 
 
1917
  con.execute("BEGIN TRANSACTION")
1918
  try:
1919
  for name, path in paths.items():
 
1937
  line = (f"Amazon mirror restored from the store: {len(paths)} tables, {total:,} rows; "
1938
  f"resuming {resume}; settlements after document {document}")
1939
  log(line.replace("\u2014", "-").replace("\u2013", "-").replace("\n", " ").replace("\r", " "))
1940
+ _heal_snapshots(con, result, log)
1941
  except Exception as exc:
1942
  result["state"] = "refused"
1943
  message = (f"Amazon mirror restore refused ({type(exc).__name__}); saved manifest, checksums, "
 
1951
  return result
1952
 
1953
 
1954
+ def _refused_may_publish(tenant_key, rt, con, cache):
1955
+ """D-3481: a process that could not restore must not publish over a snapshot that is valid.
1956
+
1957
+ It publishes once its own first load is complete (its rebuild is then whole), or once a
1958
+ fresh re-validation proves the stored snapshot unrestorable (nothing valid is lost). A
1959
+ store-access failure during that re-check proves nothing, so it holds and asks again later.
1960
+ """
1961
+ if cache.get("publish_ok"):
1962
+ return True
1963
+ load = _read_state(con, entity_key(FIRST_LOAD_END_KEY))
1964
+ if load and load["state"] == "done":
1965
+ cache["publish_ok"] = True
1966
+ return True
1967
+ if cache.get("stored_valid") is None:
1968
+ try:
1969
+ raw = rt.download_bytes(MIRROR_PREFIX + _MANIFEST_KEY)
1970
+ if raw is None:
1971
+ cache["stored_valid"] = False
1972
+ else:
1973
+ with tempfile.TemporaryDirectory(prefix="amazon-recheck-") as tmp:
1974
+ _validated_snapshot(tenant_key, rt, con, raw, tmp)
1975
+ cache["stored_valid"] = True
1976
+ except (ValueError, KeyError, TypeError, AttributeError):
1977
+ cache["stored_valid"] = False
1978
+ except Exception: # noqa: BLE001
1979
+ return False
1980
+ if cache["stored_valid"] is False:
1981
+ cache["publish_ok"] = True
1982
+ return True
1983
+ return False
1984
+
1985
+
1986
+ def _retire_blobs(tenant_key, rt, published, previous, log, *, orphans=True):
1987
+ """After a publish only: delete what the previous manifest named and the new one does not,
1988
+ plus ledger orphans older than ORPHAN_GRACE. Best effort; a failure is retried next time."""
1989
+ try:
1990
+ if rt.download_bytes(MIRROR_PREFIX + _MANIFEST_KEY) != published:
1991
+ log("Amazon mirror cleanup skipped: the stored manifest changed after this checkpoint")
1992
+ return 0
1993
+ current = _manifest_keys(json.loads(published), strict=False)
1994
+ ledger = _read_key_ledger(rt, tenant_key)
1995
+ doomed = set(previous) - set(current)
1996
+ if orphans:
1997
+ cutoff = datetime.now(timezone.utc) - ORPHAN_GRACE
1998
+ for key, stamp in ledger["keys"].items():
1999
+ try:
2000
+ aged = _utc(stamp) < cutoff
2001
+ except Exception: # noqa: BLE001
2002
+ aged = True
2003
+ if key not in current and aged:
2004
+ doomed.add(key)
2005
+ removed = []
2006
+ for key in sorted(doomed):
2007
+ if key in current or not _is_mirror_blob_key(key):
2008
+ continue
2009
+ rt.delete_path(MIRROR_PREFIX + key)
2010
+ removed.append(key)
2011
+ if any(key in ledger["keys"] for key in removed):
2012
+ ledger = _read_key_ledger(rt, tenant_key)
2013
+ ledger["keys"] = {k: v for k, v in ledger["keys"].items() if k not in removed}
2014
+ rt.upload_bytes(MIRROR_PREFIX + _KEY_LEDGER, _mirror_json(ledger))
2015
+ return len(removed)
2016
+ except Exception as exc: # noqa: BLE001
2017
+ log(f"Amazon mirror cleanup deferred ({type(exc).__name__}); superseded blobs stay in the "
2018
+ "key ledger for the next checkpoint or purge.")
2019
+ return 0
2020
+
2021
+
2022
  def persist_mirror(tenant_key, rt, con, changed_tables, *, report, log=print):
2023
  """Checkpoint changed tables and all Amazon markers, publishing the manifest last.
2024
 
2025
  Candidates include partially written tables. Hashing their parquet locally avoids reuploading
2026
  identical content; no previous blobs are downloaded on a sync pass. Failed candidates remain
2027
  dirty for retry on the next pass, while landed local rows and cursors stay usable.
2028
+
2029
+ S67-T32 (D-3481), the order that makes a killed checkpoint harmless: (1) every new blob gets a
2030
+ CONTENT key, and a key the current manifest names is never written; (2) the key ledger lists
2031
+ every new key before its upload; (3) the blobs upload; (4) ONE manifest upload, a single-row
2032
+ upsert, publishes them; (5) only then are superseded blobs deleted. Dying anywhere before (4)
2033
+ leaves the previous manifest naming only complete, untouched blobs.
2034
  """
2035
  uploaded = 0
2036
  with _MIRROR_LOCK:
2037
  cache = restore_mirror(tenant_key, rt, log=log)
2038
  cache["dirty"].update(changed_tables)
2039
  try:
2040
+ if cache.get("state") == "refused" and not _refused_may_publish(tenant_key, rt, con, cache):
2041
+ message = ("Amazon mirror checkpoint held: this process could not restore the saved snapshot "
2042
+ "at start, and that snapshot is still valid or unreachable. It is kept; restart to "
2043
+ "restore it. This process saves only after its own first load completes.")
2044
+ report["problems"].append(message)
2045
+ log(message)
2046
+ return
2047
  old = cache["manifest"]
2048
+ named = _manifest_keys(old)
2049
  tables = {name for name, kind in _amazon_objects(con)
2050
  if name.startswith(PREFIX) and kind == "BASE TABLE"}
2051
+ manifest = {"version": MANIFEST_VERSION, "tenant": _tenant_key(tenant_key),
2052
  "tables": {name: meta for name, meta in old.get("tables", {}).items() if name in tables}}
2053
+ changed, pending = [], []
2054
  with tempfile.TemporaryDirectory(prefix="amazon-persist-") as tmp:
2055
+ # A legacy entry (no content key) is a candidate too: the first checkpoint migrates.
2056
+ legacy = {name for name, meta in manifest["tables"].items() if not meta.get("key")}
2057
+ for name in sorted((cache["dirty"] | legacy | (tables - set(manifest["tables"]))) & tables):
2058
  if not re.fullmatch(r"amzn_[a-z0-9_]+", name):
2059
  raise ValueError("Amazon mirror table name is invalid")
2060
  path = Path(tmp) / (name + ".parquet")
 
2062
  "(FORMAT PARQUET, COMPRESSION ZSTD)", [str(path)])
2063
  data = path.read_bytes()
2064
  metadata = _blob_metadata(data)
2065
+ prior = manifest["tables"].get(name, {})
2066
+ if metadata["sha256"] == prior.get("sha256") and prior.get("key"):
2067
  continue
2068
+ key = _content_key(name, ".parquet", metadata)
2069
  metadata.update(rows=con.execute(f"SELECT count(*) FROM {_quoted_identifier(name)}").fetchone()[0],
2070
+ written_at=_iso(datetime.now(timezone.utc)), key=key)
 
 
2071
  manifest["tables"][name] = metadata
2072
  changed.append(name)
2073
+ if key in named:
2074
+ # The same content under its own name is already stored and published.
2075
+ if named[key] != metadata["sha256"]:
2076
+ raise ValueError("Amazon mirror content key collides with a published blob")
2077
+ continue
2078
+ pending.append((key, path))
2079
+ rows = [row for row in _sync_state_rows(con) if str(row[0]).startswith(PREFIX)]
2080
+ state = _mirror_json(rows)
2081
+ state_meta = {**_blob_metadata(state), "rows": len(rows)}
2082
+ state_meta["key"] = _content_key("sync_state", ".json", state_meta)
2083
+ published = None
2084
+ if rows and (changed or state_meta != old.get("sync_state")
2085
+ or manifest["tables"] != old.get("tables", {})
2086
+ or old.get("version") != MANIFEST_VERSION):
2087
+ state_path = None
2088
+ if state_meta["key"] not in named:
2089
+ state_path = Path(tmp) / "sync_state.json"
2090
+ state_path.write_bytes(state)
2091
+ pending.append((state_meta["key"], state_path))
2092
+ if pending:
2093
+ _ledger_add(rt, tenant_key, [key for key, _path in pending])
2094
+ for key, path in pending:
2095
+ data = path.read_bytes()
2096
+ rt.upload_bytes(MIRROR_PREFIX + key, data)
2097
+ uploaded += len(data)
2098
+ manifest.update(sync_state=state_meta, written_at=_iso(datetime.now(timezone.utc)))
2099
+ published = _mirror_json(manifest)
2100
+ rt.upload_bytes(MIRROR_PREFIX + _MANIFEST_KEY, published)
2101
+ uploaded += len(published)
2102
+ cache["manifest"] = manifest
2103
+ cache["problems"].clear()
2104
+ if published:
2105
+ _retire_blobs(tenant_key, rt, published, named, log, orphans=cache.get("state") != "refused")
2106
+ if published or not changed:
2107
+ cache["dirty"].clear()
2108
  log(f"Amazon mirror persisted to the store: {len(changed)} changed tables, {uploaded:,} bytes uploaded")
2109
  except Exception as exc:
2110
  message = (f"Amazon mirror persistence failed ({type(exc).__name__}); {uploaded:,} bytes uploaded. "
 
2113
  log(message)
2114
 
2115
 
2116
+ def _purge_json(rt, name):
2117
+ """A saved mirror JSON document for a purge: the parsed dict, or {} when absent or unreadable."""
2118
+ try:
2119
+ raw = rt.download_bytes(MIRROR_PREFIX + name)
2120
+ doc = json.loads(raw) if raw else {}
2121
+ except (TypeError, ValueError, UnicodeError, RecursionError):
2122
+ return {}
2123
+ return doc if isinstance(doc, dict) else {}
2124
+
2125
+
2126
  def _purge_saved_mirror(tenant_key, rt, local_tables):
2127
+ """Delete data before its inventory so a failed deletion remains retryable after restart.
2128
+
2129
+ Every version goes: each legacy in-place key, each key any manifest names, and each key the
2130
+ write-ahead ledger lists, which includes blobs a killed checkpoint uploaded but never
2131
+ published. Then the manifest, then the ledger itself, each read back.
2132
+ """
2133
  with _MIRROR_LOCK:
2134
  key = _mirror_cache_key(tenant_key, rt)
2135
  cached = _MIRROR_CACHE.get(key, {})
2136
+ # Deletion never refuses on unreadable inventory: a corrupt or foreign manifest or ledger
2137
+ # still yields every blob name it holds, and every path below goes through THIS tenant's
2138
+ # runtime, so a ledger labelled with another tenant cannot point a delete outside it.
2139
+ manifest = _purge_json(rt, _MANIFEST_KEY)
2140
+ ledger_keys = {str(k) for k in (_purge_json(rt, _KEY_LEDGER).get("keys") or {})
2141
+ if _is_mirror_blob_key(str(k))}
2142
  names = ({table_name(t) for t in TABLES} | set(local_tables) | set(manifest.get("tables", {}))
2143
  | set(cached.get("manifest", {}).get("tables", {})) | set(cached.get("dirty", ())))
2144
+ blobs = {name + ".parquet" for name in names if re.fullmatch(r"amzn_[a-z0-9_]+", name)}
2145
+ blobs.add("sync_state.json")
2146
+ blobs |= set(_manifest_keys(manifest, strict=False))
2147
+ blobs |= set(_manifest_keys(cached.get("manifest", {}), strict=False))
2148
+ blobs |= ledger_keys
2149
+ paths = [MIRROR_PREFIX + blob for blob in sorted(blobs)]
2150
+ paths.extend((MIRROR_PREFIX + _MANIFEST_KEY, MIRROR_PREFIX + _KEY_LEDGER))
2151
  for path in paths:
2152
  if rt.delete_path(path) is False or rt.download_bytes(path) is not None:
2153
  raise RuntimeError("Amazon saved mirror deletion failed or left residue")
 
2622
  _record_state(con, key, "done", detail=json.dumps(marker, separators=(",", ":")))
2623
 
2624
 
2625
+ def _replace_period(con, table, rows, columns, column, start, end=None, marker=None, *, snapshot=False):
2626
+ """Atomic range/date replacement and proof; an empty restatement removes old rows too.
2627
+
2628
+ `snapshot=True` (S67-T32, D-3031): a current-state report is ONE copy. A successful, parsed
2629
+ pull replaces every earlier `_snapshot_date` of the table, not only its own day, because the
2630
+ grid pid hashes the date and a kept day doubles every row downstream. A failed pull raises
2631
+ before this runs, so it never empties the table.
2632
+ """
2633
  mirror = table_name(table)
2634
  columns = list(dict.fromkeys([*columns, column, *_ORIGIN_TYPES]))
2635
  # All JSON money columns remain fractional even when today's amounts are integers.
 
2640
  predicate = ('CAST(posted_date AS TIMESTAMPTZ) >= CAST(? AS TIMESTAMPTZ) AND '
2641
  'CAST(posted_date AS TIMESTAMPTZ) < CAST(? AS TIMESTAMPTZ)')
2642
  params = [start, end] if end else [start]
2643
+ if snapshot:
2644
+ if column != "_snapshot_date" or end:
2645
+ raise ValueError("a snapshot replacement is keyed by one _snapshot_date")
2646
+ predicate, params = "TRUE", []
2647
  con.execute("BEGIN TRANSACTION")
2648
  try:
2649
  con.execute(f'DELETE FROM {mirror} WHERE {predicate}', params)
 
2692
 
2693
 
2694
  def _replace_legacy_snapshot(con, table, columns, rows, meta, source_count):
2695
+ """Replace the whole FBA snapshot with one parsed document, preserving the separate AWD leg.
2696
 
2697
  Listings is a catalogue as of the vendor's data/creation date. The ledger is a DAILY
2698
  summary: its row date wins over the report creation date, including multi-date documents.
2699
  Duplicate source identities refuse the whole document rather than silently dropping rows.
2700
+ S67-T32 (D-3031): one copy. The document's dates replace every earlier date, so the table
2701
+ holds exactly one pull, the row count a fresh first load would store.
2702
  """
2703
  stamp = meta.get("dataEndTime") or meta.get("dataStartTime") or meta.get("createdTime")
2704
  if not stamp and (table == "listings" or not rows):
 
2727
  dates = sorted(counts)
2728
  marker = {"start": dates[0], "end": dates[-1], "column": "_snapshot_date",
2729
  "count": source_count, "dates": counts, "document": meta.get("reportDocumentId")}
2730
+ # Every earlier date and any undated pre-migration copy goes; AWD rows are another leg.
2731
+ predicate = "COALESCE(inventory_source, 'FBA') <> 'AWD'" if table == "inventory" else "TRUE"
 
 
 
 
 
2732
  con.execute("BEGIN TRANSACTION")
2733
  try:
2734
+ con.execute(f"DELETE FROM {mirror} WHERE {predicate}")
2735
  count = _replace(con, mirror, columns, types, rows)
2736
  _record_reconciliation(con, table, marker)
2737
  con.execute("COMMIT")
 
2818
  document = "operation:" + uuid.uuid4().hex
2819
  rows = [_origin(_flatten_row(_without_buyer_data(row)), document, i, spec["api"])
2820
  for i, row in enumerate(records, 1)]
2821
+ if table == "catalog_items":
2822
+ parents = catalog_parent_map(records, _pricing_parent_map(con),
2823
+ fields.get("marketplace_id") or cx.US_MARKETPLACE_ID,
2824
+ _economics_parent_map(con))
2825
+ for row in rows:
2826
+ asin = str(row.get("asin") or "").strip()
2827
+ row["parent_asin"], row["parent_asin_source"] = parents.get(asin, (asin or None, "self"))
2828
  column = "_snapshot_date" if spec.get("snapshot") else "_period_start"
2829
  period = datetime.now(timezone.utc).date().isoformat() if spec.get("snapshot") else start
2830
  for row in rows:
 
2841
  raise ValueError("Amazon order metrics returned an interval outside the requested period")
2842
  row[column] = _iso(day)
2843
  return _replace_period(con, table, rows, sorted({k for r in rows for k in r}),
2844
+ column, period, end if table == "order_metrics" else None, marker=marker,
2845
+ snapshot=bool(spec.get("snapshot")))
2846
  kwargs = {} if spec.get("snapshot") else {
2847
  "start": _iso(w0), "end": _iso(w1 - timedelta(seconds=1))}
2848
  options = dict(spec.get("options") or {})
 
2890
  marker = {"start": period, "end": _iso(w1) if column == "_period_start" else period,
2891
  "column": column, "count": document_row_count(
2892
  text, (spec["json_root"], *spec.get("json_extra_roots", ())) if spec.get("json_root") else ())}
2893
+ return _replace_period(con, table, rows, columns, column, period, marker=marker,
2894
+ snapshot=bool(spec.get("snapshot")))
2895
 
2896
 
2897
  def _order_metric_totals(records, *, flattened=False):
 
3126
  pending = list(dict.fromkeys([head for head, sibling in SHARED_REPORT_SIBLINGS.items()
3127
  if head in want and sibling in want] + want))
3128
  handled, noted = set(), set()
3129
+ # D-3031: a mirror that already holds two pulls of a snapshot heals here too, idempotently.
3130
  changed_tables = set()
3131
+ try:
3132
+ changed_tables.update(_collapse_snapshots(con, log))
3133
+ except Exception as exc: # noqa: BLE001
3134
+ report["problems"].append(f"Amazon snapshot collapse failed ({type(exc).__name__}); the next "
3135
+ "resync of each snapshot table replaces its earlier copies.")
3136
 
3137
  def write_window(table, cols, types, rows):
3138
  count, note = replace_window(con, table_name(table), cols, types, rows,
 
3402
  {"state": "access", "operation": "report_document"}, rt, report, log)
3403
  text, meta = cx.report_document(
3404
  fields, rtype, start=_iso(w0), end=_iso(w1), max_wait=max_wait,
3405
+ log=lambda message: log(f"{table}: {message}"),
3406
+ **({"options": dict(REPORT_OPTIONS[table])} if table in REPORT_OPTIONS else {}))
3407
  if root:
3408
  parsed_cols, rows = parse_json_report(
3409
  text, root, document_id=meta.get("reportDocumentId"), report_type=rtype)
 
3465
  cols.append("inventory_source")
3466
  if table == "pricing":
3467
  pricing_asins.extend(_pricing_asins(rows))
3468
+ if not cleared and _pricing_regrain(con, mirror, rows, log):
3469
+ cleared = True
3470
  types = _ensure(con, mirror, cols, rows, declared=declared,
3471
  preserve_rows=True) if cols else {}
3472
  # Explicit windows and first loads replace the mirror; incremental passes keep history.
 
3894
  "FROM amzn_listings").fetchone() == (2, 2))
3895
  meta["createdTime"] = "2026-09-26T11:00:00Z"
3896
  sync(rt.key, tables=[table], rt=rt, log=lambda *_a: None)
3897
+ # S67-T32 (D-3031, reversed): a second day REPLACES the first, one load's rows.
3898
+ ck("a second listing day replaces the first, leaving one copy", lambda:
3899
  con.execute("SELECT _snapshot_date, COUNT(*) FROM amzn_listings "
3900
+ "GROUP BY 1 ORDER BY 1").fetchall() == [("2026-09-26", 2)]
3901
  and len(calls) == 2 and all("start" not in c and "end" not in c for c in calls))
3902
  payload[0] = "seller-sku\tquantity\nA\t9\n"
3903
  sync(rt.key, tables=[table], since=start, rt=rt, log=lambda *_a: None)
3904
+ ck("same listing date replaces removed SKUs", lambda:
3905
  con.execute("SELECT _snapshot_date, seller_sku, quantity FROM amzn_listings "
3906
+ "ORDER BY 1, 2").fetchall() == [("2026-09-26", "A", 9)]
 
3907
  and valid()["state"] == "ok")
3908
  else:
3909
  ck("ledger keeps one row per data date, SKU, disposition and location", lambda:
 
3917
  before_awd = con.execute("SELECT * FROM amzn_inventory WHERE inventory_source='AWD'").fetchall()
3918
  payload[0] = ledger_header + "09/24/2026\tA\tFA\tAA\tSELLABLE\tUS\t9\n"
3919
  sync(rt.key, tables=[table], since=start, rt=rt, log=lambda *_a: None)
3920
+ # S67-T32 (D-3031, reversed): the next document replaces every earlier FBA date.
3921
+ ck("ledger second document replaces every earlier data date", lambda:
3922
  con.execute("SELECT _snapshot_date, ending_warehouse_balance FROM amzn_inventory "
3923
  "WHERE inventory_source='FBA' ORDER BY 1").fetchall()
3924
+ == [("2026-09-24", 9)])
3925
  ck("FBA replacement preserves AWD rows exactly", lambda:
3926
  con.execute("SELECT * FROM amzn_inventory WHERE inventory_source='AWD'").fetchall() == before_awd)
3927
  # The AWD operation's existing reconciliation still checks its own rows.
 
3950
  if table == "listings":
3951
  payload[0] = "seller-sku\tquantity\n"
3952
  sync(rt.key, tables=[table], rt=rt, log=lambda *_a: None)
3953
+ ck("empty listing restatement replaces the copy and stays unproven", lambda:
3954
+ count() == 0 and valid()["state"] == "unproven")
3955
  meta["dataEndTime"] = "2026-09-27T23:00:00Z"
3956
  payload[0] = "seller-sku\tquantity\n" + "".join(f"S{i}\t1\n" for i in range(1205))
3957
  sync(rt.key, tables=[table], rt=rt, log=lambda *_a: None)
 
3967
  "SELECT COUNT(*) FROM amzn_inventory WHERE _snapshot_date='2026-09-25' "
3968
  "AND fnsku='F-fallback'").fetchone()[0] == 1)
3969
  con.close()
3970
+ ck("S67-T32 saved mirror: one copy, content keys, kill-safe checkpoint, full purge",
3971
+ lambda: mirror_selftest(log, check) == 0)
3972
+ return len(failures)
3973
+
3974
+
3975
+ def mirror_selftest(log=print, check=None):
3976
+ """S67-T32 (D-3031 + D-3481): the saved snapshot is one copy, whole, and restorable.
3977
+
3978
+ Offline: a DuckDB :memory: mirror and a dictionary blob store. Covers the legacy (v1)
3979
+ manifest restoring exactly, the doubled-mirror collapse, content keys never overwriting a
3980
+ named key, a checkpoint dying after one table upload, purge reaching the orphan, a normal
3981
+ checkpoint round trip (NC) and a refused process never publishing over a valid snapshot.
3982
+ """
3983
+ from unittest.mock import patch
3984
+ import duckdb
3985
+ failures = []
3986
+
3987
+ def ck(name, probe):
3988
+ try:
3989
+ ok = bool(probe())
3990
+ except Exception as exc: # noqa: BLE001
3991
+ ok = False
3992
+ log(f" {name}: {type(exc).__name__}: {exc}")
3993
+ if check:
3994
+ check("[mirror] " + name, ok)
3995
+ else:
3996
+ log(f" {'ok' if ok else 'FAIL'} {name}")
3997
+ if not ok:
3998
+ failures.append(name)
3999
+
4000
+ class Store:
4001
+ key = "qa-mirror"
4002
+
4003
+ def __init__(self):
4004
+ self.blobs, self.uploads, self.hook = {}, [], None
4005
+
4006
+ def get(self, *_a, **_k):
4007
+ return None
4008
+
4009
+ def upload_bytes(self, path, data, message=None):
4010
+ if self.hook:
4011
+ self.hook("upload", path)
4012
+ self.blobs[path] = bytes(data)
4013
+ self.uploads.append(path)
4014
+
4015
+ def download_bytes(self, path):
4016
+ if self.hook:
4017
+ self.hook("download", path)
4018
+ return self.blobs.get(path)
4019
+
4020
+ def delete_path(self, path):
4021
+ self.blobs.pop(path, None)
4022
+ return True
4023
+
4024
+ rt = Store()
4025
+ manifest_path, ledger_path = MIRROR_PREFIX + _MANIFEST_KEY, MIRROR_PREFIX + _KEY_LEDGER
4026
+ con = duckdb.connect(":memory:")
4027
+ con.execute("CREATE TABLE _sync_state (entity VARCHAR PRIMARY KEY, phase VARCHAR, "
4028
+ "last_id BIGINT, cursor_wd VARCHAR, rows BIGINT, updated_at VARCHAR)")
4029
+
4030
+ def forget():
4031
+ _MIRROR_CACHE.pop(_mirror_cache_key(rt.key, rt), None)
4032
+
4033
+ def wipe():
4034
+ """A new process whose local disk was lost."""
4035
+ for name, _kind in _amazon_objects(con):
4036
+ con.execute(f"DROP TABLE {_quoted_identifier(name)}")
4037
+ con.execute("DELETE FROM _sync_state WHERE starts_with(entity, 'amzn_')")
4038
+ forget()
4039
+
4040
+ def dump():
4041
+ out = {name: sorted(con.execute(f"SELECT * FROM {_quoted_identifier(name)}").fetchall(), key=repr)
4042
+ for name, _kind in _amazon_objects(con)}
4043
+ out["_sync_state"] = sorted(r for r in _sync_state_rows(con) if r[0].startswith(PREFIX))
4044
+ return out
4045
+
4046
+ def ledger_doc():
4047
+ try:
4048
+ return json.loads(rt.blobs[ledger_path])
4049
+ except (KeyError, ValueError):
4050
+ return {"version": 1, "tenant": rt.key, "keys": {}}
4051
+
4052
+ def mirror_blobs():
4053
+ return {k for k in rt.blobs if k.startswith(MIRROR_PREFIX)}
4054
+
4055
+ def persist(tables=()):
4056
+ report = {"problems": []}
4057
+ persist_mirror(rt.key, rt, con, set(tables), report=report, log=lambda *_a: None)
4058
+ return report
4059
+
4060
+ def restore():
4061
+ return restore_mirror(rt.key, rt, log=lambda *_a: None)
4062
+
4063
+ def legacy_save():
4064
+ """Today's staging layout, byte for byte: v1, in-place keys, no ledger."""
4065
+ manifest = {"version": 1, "tenant": rt.key, "tables": {}}
4066
+ import tempfile as _tmp
4067
+ with _tmp.TemporaryDirectory(prefix="amazon-legacy-") as tmp:
4068
+ for name, _kind in _amazon_objects(con):
4069
+ path = Path(tmp) / (name + ".parquet")
4070
+ con.execute(f"COPY (SELECT * FROM {_quoted_identifier(name)}) TO ? "
4071
+ "(FORMAT PARQUET, COMPRESSION ZSTD)", [str(path)])
4072
+ data = path.read_bytes()
4073
+ rt.blobs[MIRROR_PREFIX + name + ".parquet"] = data
4074
+ manifest["tables"][name] = {**_blob_metadata(data), "written_at": "2026-09-27T00:00:00Z",
4075
+ "rows": con.execute(f"SELECT count(*) FROM {name}").fetchone()[0]}
4076
+ rows = [list(r) for r in _sync_state_rows(con) if r[0].startswith(PREFIX)]
4077
+ state = _mirror_json(rows)
4078
+ rt.blobs[MIRROR_PREFIX + "sync_state.json"] = state
4079
+ manifest.update(sync_state={**_blob_metadata(state), "rows": len(rows)}, written_at="2026-09-27T00:00:00Z")
4080
+ rt.blobs[manifest_path] = _mirror_json(manifest)
4081
+
4082
+ def seed():
4083
+ con.execute("CREATE TABLE amzn_restock_recommendations AS SELECT * FROM (VALUES "
4084
+ "('2026-09-25', 'A', 1), ('2026-09-25', 'B', 2), ('2026-09-25', 'C', 3), "
4085
+ "('2026-09-26', 'A', 4), ('2026-09-26', 'B', 5), ('2026-09-26', 'C', 6)) "
4086
+ "AS t(_snapshot_date, sku, qty)")
4087
+ con.execute("CREATE TABLE amzn_inventory AS SELECT * FROM (VALUES "
4088
+ "('2026-09-22', 'A', 'FBA', 1), ('2026-09-23', 'A', 'FBA', 2), "
4089
+ "('2026-09-24', 'A', 'FBA', 3), (NULL, 'AWD-1', 'AWD', 9)) "
4090
+ "AS t(_snapshot_date, msku, inventory_source, qty)")
4091
+ con.execute("CREATE TABLE amzn_orders AS SELECT * FROM (VALUES "
4092
+ "('2026-09-01', 'O1', 10.5), ('2026-09-02', 'O2', 11.5)) AS t(_period_start, id, amount)")
4093
+ con.execute("CREATE TABLE amzn_listings AS SELECT * FROM (VALUES ('2026-09-26', 'S1', 1)) "
4094
+ "AS t(_snapshot_date, seller_sku, quantity)")
4095
+ _record_state(con, entity_key("reconcile_inventory"), "done", detail=json.dumps(
4096
+ {"start": "2026-09-23", "end": "2026-09-24", "column": "_snapshot_date", "count": 2,
4097
+ "dates": {"2026-09-23": 1, "2026-09-24": 1}}))
4098
+ record_watermark(con, "orders", datetime(2026, 9, 26, tzinfo=timezone.utc), 2)
4099
+ _record_state(con, entity_key(FIRST_LOAD_END_KEY), "done", detail="2026-09-26T00:00:00Z")
4100
+
4101
+ try:
4102
+ with patch.object(sys.modules[__name__], "_connect_tenant_mirror",
4103
+ side_effect=lambda *_a: (con.cursor(), None)):
4104
+ # D-3031 at the write: an API snapshot pulled on a new day replaces the old day.
4105
+ for day, qty in (("2026-09-25", 1), ("2026-09-26", 2)):
4106
+ rows = [_origin({"sku": s, "qty": qty, "_snapshot_date": day}, "doc-" + day, i, "fixture")
4107
+ for i, s in enumerate(("A", "B"), 1)]
4108
+ _replace_period(con, "fba_inventory", rows, ["sku", "qty", "_snapshot_date"],
4109
+ "_snapshot_date", day, snapshot=True)
4110
+ ck("two snapshot days leave one copy of one load's rows", lambda: con.execute(
4111
+ "SELECT _snapshot_date, count(*) FROM amzn_fba_inventory GROUP BY 1").fetchall()
4112
+ == [("2026-09-26", 2)])
4113
+ ck("a period table keeps its history", lambda: _replace_period(
4114
+ con, "storage_fees", [_origin({"month": "2026-08", "fee": 1}, "d", 1, "f")], ["month", "fee"],
4115
+ "month", "2026-08") == 1 and _replace_period(
4116
+ con, "storage_fees", [_origin({"month": "2026-09", "fee": 1}, "d", 1, "f")], ["month", "fee"],
4117
+ "month", "2026-09") == 1 and con.execute(
4118
+ "SELECT count(DISTINCT month) FROM amzn_storage_fees").fetchone()[0] == 2)
4119
+ con.execute("DROP TABLE amzn_fba_inventory")
4120
+ con.execute("DROP TABLE amzn_storage_fees")
4121
+
4122
+ # The legacy manifest staging boots from, holding a doubled snapshot.
4123
+ seed()
4124
+ original = dump()
4125
+ legacy_save()
4126
+ legacy_blobs = dict(rt.blobs)
4127
+ wipe()
4128
+ result = restore()
4129
+ ck("a legacy v1 manifest with in-place keys restores every table and marker", lambda:
4130
+ result["state"] == "restored" and not result["problems"]
4131
+ and dump()["amzn_orders"] == original["amzn_orders"]
4132
+ and dump()["amzn_listings"] == original["amzn_listings"]
4133
+ and dump()["_sync_state"] == original["_sync_state"])
4134
+ ck("a doubled mirror collapses on restore to the latest pull and is marked dirty", lambda:
4135
+ con.execute("SELECT _snapshot_date, count(*) FROM amzn_restock_recommendations "
4136
+ "GROUP BY 1").fetchall() == [("2026-09-26", 3)]
4137
+ and con.execute("SELECT _snapshot_date FROM amzn_inventory WHERE inventory_source='FBA' "
4138
+ "ORDER BY 1").fetchall() == [("2026-09-23",), ("2026-09-24",)]
4139
+ and con.execute("SELECT count(*) FROM amzn_inventory WHERE inventory_source='AWD'").fetchone()[0] == 1
4140
+ and {"amzn_restock_recommendations", "amzn_inventory"} <= result["dirty"]
4141
+ and "amzn_orders" not in result["dirty"])
4142
+ ck("the collapse is idempotent", lambda: _collapse_snapshots(con) == {})
4143
+
4144
+ # First checkpoint after the legacy boot: every blob moves to a content key.
4145
+ legacy_keys = set(_manifest_keys(json.loads(legacy_blobs[manifest_path])))
4146
+ rt.uploads.clear()
4147
+ report = persist()
4148
+ saved = json.loads(rt.blobs[manifest_path])
4149
+ named = set(_manifest_keys(saved))
4150
+ ck("the first checkpoint migrates to content keys and retires the in-place blobs", lambda:
4151
+ not report["problems"] and saved["version"] == MANIFEST_VERSION
4152
+ and all(_TABLE_BLOB_RE.fullmatch(k).group(2) for k in named if k.endswith(".parquet"))
4153
+ and not any(MIRROR_PREFIX + k in rt.blobs for k in legacy_keys)
4154
+ and not any(MIRROR_PREFIX + k in rt.uploads for k in legacy_keys)
4155
+ and set(ledger_doc()["keys"]) == named
4156
+ and rt.uploads.index(ledger_path) < min(rt.uploads.index(MIRROR_PREFIX + k) for k in named)
4157
+ and rt.uploads[-2 if rt.uploads[-1] == ledger_path else -1] == manifest_path)
4158
+ healed = dump()
4159
+ wipe()
4160
+ ck("NC a normal checkpoint restores exactly, one copy each", lambda:
4161
+ restore()["state"] == "restored" and dump() == healed
4162
+ and con.execute("SELECT count(*) FROM amzn_restock_recommendations").fetchone()[0] == 3)
4163
+ rt.uploads.clear()
4164
+ before = dict(rt.blobs)
4165
+ persist(set(original))
4166
+ ck("an unchanged checkpoint uploads nothing", lambda: rt.uploads == [] and rt.blobs == before)
4167
+
4168
+ # A changed table never overwrites a key the published manifest names.
4169
+ con.execute("UPDATE amzn_orders SET amount = amount + 1")
4170
+ rt.uploads.clear()
4171
+ persist({"amzn_orders"})
4172
+ ck("content keys never overwrite a named key", lambda:
4173
+ not any(path[len(MIRROR_PREFIX):] in named for path in rt.uploads)
4174
+ and _manifest_keys(json.loads(rt.blobs[manifest_path]))
4175
+ and not (MIRROR_PREFIX + saved["tables"]["amzn_orders"]["key"]) in rt.blobs)
4176
+
4177
+ # A checkpoint that dies after its first table blob lands.
4178
+ published = rt.blobs[manifest_path]
4179
+ good = dump()
4180
+ con.execute("UPDATE amzn_orders SET amount = amount + 1")
4181
+ con.execute("UPDATE amzn_listings SET quantity = quantity + 1")
4182
+ parquet = []
4183
+
4184
+ def die_on_second(kind, path):
4185
+ if kind == "upload" and path.endswith(".parquet"):
4186
+ parquet.append(path)
4187
+ if len(parquet) == 2:
4188
+ raise OSError("fixture: the process died mid-checkpoint")
4189
+
4190
+ rt.hook = die_on_second
4191
+ report = persist({"amzn_orders", "amzn_listings"})
4192
+ rt.hook = None
4193
+ orphan = parquet[0][len(MIRROR_PREFIX):] if parquet else "absent"
4194
+ ck("a checkpoint that dies after one table upload leaves the manifest untouched", lambda:
4195
+ any("persistence failed" in p for p in report["problems"])
4196
+ and rt.blobs[manifest_path] == published and MIRROR_PREFIX + orphan in rt.blobs)
4197
+ ck("the key ledger lists the unpublished orphan", lambda:
4198
+ orphan in ledger_doc()["keys"]
4199
+ and orphan not in _manifest_keys(json.loads(published)))
4200
+ wipe()
4201
+ ck("the next process restores the previous snapshot whole", lambda:
4202
+ restore()["state"] == "restored" and dump() == good)
4203
+
4204
+ # An aged orphan is retired by the next successful publish; a fresh one is not.
4205
+ ledger = ledger_doc()
4206
+ ledger["keys"][orphan] = "2026-01-01T00:00:00Z"
4207
+ rt.blobs[ledger_path] = _mirror_json(ledger)
4208
+ con.execute("UPDATE amzn_orders SET amount = amount + 5")
4209
+ persist({"amzn_orders"})
4210
+ ck("an aged ledger orphan is retired after the next publish", lambda:
4211
+ MIRROR_PREFIX + orphan not in rt.blobs
4212
+ and orphan not in ledger_doc()["keys"]
4213
+ and set(ledger_doc()["keys"]) >= set(
4214
+ _manifest_keys(json.loads(rt.blobs[manifest_path]))))
4215
+
4216
+ # A refused restore (store unreachable at boot) must not publish its rebuild.
4217
+ valid_manifest = rt.blobs[manifest_path]
4218
+ wipe()
4219
+
4220
+ def unreachable(kind, path):
4221
+ if kind == "download" and path == manifest_path:
4222
+ raise OSError("fixture: store unreachable at boot")
4223
+
4224
+ rt.hook = unreachable
4225
+ refused = restore()
4226
+ rt.hook = None
4227
+ con.execute("CREATE TABLE amzn_orders AS SELECT '2026-09-02' AS _period_start, 'O2' AS id, 1.0 AS amount")
4228
+ _record_state(con, entity_key(FIRST_LOAD_END_KEY), "partial", detail="2026-09-26T00:00:00Z")
4229
+ rt.uploads.clear()
4230
+ report = persist({"amzn_orders"})
4231
+ ck("a refused restore does not publish a partial rebuild over the valid manifest", lambda:
4232
+ refused["state"] == "refused" and rt.blobs[manifest_path] == valid_manifest
4233
+ and rt.uploads == [] and any("checkpoint held" in p for p in report["problems"]))
4234
+ _record_state(con, entity_key(FIRST_LOAD_END_KEY), "done", detail="2026-09-26T00:00:00Z")
4235
+ report = persist({"amzn_orders"})
4236
+ ck("the refused process publishes once its own first load completes", lambda:
4237
+ not report["problems"] and rt.blobs[manifest_path] != valid_manifest
4238
+ and set(json.loads(rt.blobs[manifest_path])["tables"]) == {"amzn_orders"})
4239
+
4240
+ # A stored snapshot that is itself unrestorable names nothing valid; the rebuild may publish.
4241
+ wipe()
4242
+ corrupt = json.loads(rt.blobs[manifest_path])
4243
+ corrupt["tables"]["amzn_orders"]["rows"] += 1
4244
+ rt.blobs[manifest_path] = _mirror_json(corrupt)
4245
+ refused = restore()
4246
+ con.execute("CREATE TABLE amzn_orders AS SELECT '2026-09-03' AS _period_start, 'O3' AS id, 2.0 AS amount")
4247
+ _record_state(con, entity_key(FIRST_LOAD_END_KEY), "partial", detail="2026-09-26T00:00:00Z")
4248
+ report = persist({"amzn_orders"})
4249
+ ck("a corrupt stored snapshot refuses whole and the rebuild may publish over it", lambda:
4250
+ refused["state"] == "refused" and not report["problems"]
4251
+ and json.loads(rt.blobs[manifest_path])["tables"]["amzn_orders"]["rows"] == 1)
4252
+
4253
+ # Purge reaches every version: legacy keys, named keys and a killed checkpoint's orphan.
4254
+ for path, data in legacy_blobs.items():
4255
+ if path != manifest_path:
4256
+ rt.blobs[path] = data
4257
+ con.execute("UPDATE amzn_orders SET amount = 7")
4258
+ parquet.clear()
4259
+ rt.hook = lambda kind, path: (_ for _ in ()).throw(OSError("fixture death")) if (
4260
+ kind == "upload" and path == manifest_path) else None
4261
+ persist({"amzn_orders"})
4262
+ rt.hook = None
4263
+ rt.blobs["unrelated/keep.bin"] = b"keep"
4264
+ orphans = set(ledger_doc()["keys"]) - set(
4265
+ _manifest_keys(json.loads(rt.blobs[manifest_path])))
4266
+ _purge_saved_mirror(rt.key, rt, [name for name, _kind in _amazon_objects(con)])
4267
+ ck("purge deletes every stored version including the orphan", lambda:
4268
+ orphans and not mirror_blobs() and rt.blobs == {"unrelated/keep.bin": b"keep"})
4269
+ finally:
4270
+ forget()
4271
+ con.close()
4272
  return len(failures)
4273
 
4274
 
 
4499
  "sku\tasin\nS1\tA1\n", {"reportDocumentId": "next-snapshot", "dataEndTime": "2026-09-03T00:00:00Z"})):
4500
  _sync_margin_window(con, "referral_fees", {}, None, None, max_wait=1, log=log)
4501
  _sync_margin_window(con, "referral_fees", {}, None, None, max_wait=1, log=log)
4502
+ # S67-T32 (D-3031, reversed): a new day REPLACES the earlier one; one copy, one load's rows.
4503
+ ck("margin a second snapshot day replaces the first and same-date replay stays idempotent",
4504
+ con.execute("SELECT COUNT(*), COUNT(DISTINCT _snapshot_date), MAX(_snapshot_date) "
4505
+ "FROM amzn_referral_fees").fetchone() == (1, 1, "2026-09-03")
4506
+ and _validate_margin(con, "referral_fees")["state"] == "ok")
4507
+ kept = con.execute("SELECT * FROM amzn_referral_fees").fetchall()
4508
+ with patch.object(cx, "report_document", side_effect=RuntimeError("fixture vendor failure")):
4509
+ try:
4510
+ _sync_margin_window(con, "referral_fees", {}, None, None, max_wait=1, log=log)
4511
+ except RuntimeError:
4512
+ pass
4513
+ ck("margin a failed snapshot pull keeps the stored copy",
4514
+ con.execute("SELECT * FROM amzn_referral_fees").fetchall() == kept and len(kept) == 1)
4515
  _replace_period(con, "economics", [], [c[1] for c in con.execute("PRAGMA table_info('amzn_economics')").fetchall()],
4516
  "start_date", "2026-09-01", "2026-09-03")
4517
  ck("margin empty economics restatement deletes stale detail and stays unproven",
 
5032
  sent = [a for _, params in requests[::3] for a in params["identifiers"].split(",")]
5033
  ck("catalog search covers all forty-one own ASINs in batches of twenty",
5034
  sent == args["asins"] and all(len(p["identifiers"].split(",")) <= 20 for _, p in requests))
5035
+ ck("catalog search asks for relationships and nothing beyond the approved includes",
5036
+ all(p["includedData"].split(",") == ["summaries", "salesRanks", "dimensions", "attributes",
5037
+ "relationships"] for _, p in requests))
5038
  if operation == "getInventorySummaries":
5039
  ck("FBA inventory requests detailed inventory on every page",
5040
  all(p["details"] == "true" for _, p in requests))
 
5051
  return len(requests) == 3 and len(rows) == 2 and requests[1]["createdBefore"] == requests[2]["createdAfter"]
5052
  ck("Listings search splits date ranges at the real thousand-SKU ceiling",
5053
  not partition_probe(False) and partition_probe(True))
5054
+ ck("catalog Parent ASIN map fixtures and red-first controls", catalog_parent_selftest(log, check) == 0)
5055
+ return 1 if failures else 0
5056
+
5057
+
5058
+ def catalog_parent_selftest(log=print, check=None):
5059
+ """S67-T29 (O23) offline fixtures: the catalog Parent ASIN map covers every own ASIN.
5060
+
5061
+ `python -c "import sys; sys.path[:0]=['platform','platform/harness']; import amazon_store as s;
5062
+ sys.exit(s.catalog_parent_selftest())"` from the repo root; no credentials, no network.
5063
+ """
5064
+ from unittest.mock import patch
5065
+ import duckdb
5066
+ cx = _client()
5067
+ failures = []
5068
+
5069
+ def ck(name, ok):
5070
+ if check:
5071
+ check("[catalog parent] " + name, bool(ok))
5072
+ else:
5073
+ log(f" {'ok' if ok else 'FAIL'} catalog parent {name}")
5074
+ if not ok:
5075
+ failures.append(name)
5076
+
5077
+ mkt = cx.US_MARKETPLACE_ID
5078
+ child, parent, standalone, lonely, broken = ("B0CHILD001", "B0PARENT01", "B0STAND001",
5079
+ "B0LONELY01", "B0BROKEN01")
5080
+ items = [
5081
+ {"asin": child, "relationships": [
5082
+ {"marketplaceId": "A1F83G8C2ARO7P", "relationships": [
5083
+ {"type": "VARIATION", "parentAsins": ["B0WRONGMKT"]}]},
5084
+ {"marketplaceId": mkt, "relationships": [
5085
+ {"type": "PACKAGE_HIERARCHY", "parentAsins": ["B0PACKAGE1"]},
5086
+ {"type": "VARIATION", "parentAsins": [parent],
5087
+ "variationTheme": {"attributes": ["color"], "theme": "COLOR"}}]}]},
5088
+ {"asin": parent, "relationships": [{"marketplaceId": mkt, "relationships": [
5089
+ {"type": "VARIATION", "childAsins": [child, "B0SIBLING1"]}]}]},
5090
+ {"asin": standalone, "relationships": [{"marketplaceId": mkt, "relationships": []}]},
5091
+ {"asin": lonely},
5092
+ {"asin": broken, "relationships": "not-a-list"},
5093
+ {"asin": "B0BROKEN02", "relationships": [None, {"marketplaceId": mkt, "relationships": {"x": 1}},
5094
+ {"marketplaceId": mkt, "relationships": [
5095
+ {"type": "VARIATION", "parentAsins": "B0NOTALIST"},
5096
+ {"type": "VARIATION", "parentAsins": [None, "bad"]}]}]},
5097
+ ]
5098
+ eco_only = "B0ECONLY01"
5099
+ items.append({"asin": eco_only, "relationships": [{"marketplaceId": mkt, "relationships": []}]})
5100
+ pricing = {standalone: "B0PRICEPAR", broken: "not an asin"}
5101
+ economics = {eco_only: "B0ECOPARNT", standalone: "B0ECOLOSER", child: "B0ECOWRONG", broken: "junk"}
5102
+ got = catalog_parent_map(items, pricing, mkt, economics)
5103
+ ck("variation child maps to its parent from relationships", got.get(child) == (parent, "relationships"))
5104
+ ck("variation parent maps to itself", got.get(parent) == (parent, "relationships"))
5105
+ ck("standalone falls back to pricing parent", got.get(standalone) == ("B0PRICEPAR", "pricing"))
5106
+ ck("no relationships and no pricing maps to itself", got.get(lonely) == (lonely, "self"))
5107
+ ck("malformed relationships degrade to itself, never an error",
5108
+ got.get(broken) == (broken, "self") and got.get("B0BROKEN02") == ("B0BROKEN02", "self"))
5109
+ ck("economics child to parent is the next fallback after pricing",
5110
+ got.get(eco_only) == ("B0ECOPARNT", "economics"))
5111
+ ck("every item gets a parent", set(got) == {i["asin"] for i in items})
5112
+ # Red-first: economics never beats relationships or pricing, and is absent without its map.
5113
+ ck("economics never outranks relationships or pricing, and needs its map",
5114
+ got.get(child) == (parent, "relationships") and got.get(standalone) == ("B0PRICEPAR", "pricing")
5115
+ and catalog_parent_map(items, pricing, mkt).get(eco_only) == (eco_only, "self"))
5116
+ # Red-first: another marketplace or a PACKAGE_HIERARCHY parent must never win.
5117
+ solo_other = catalog_parent_map([dict(items[0], relationships=items[0]["relationships"][:1])], {}, mkt)
5118
+ pack_only = catalog_parent_map([{"asin": child, "relationships": [{"marketplaceId": mkt, "relationships": [
5119
+ {"type": "PACKAGE_HIERARCHY", "parentAsins": ["B0PACKAGE1"]}]}]}], {}, mkt)
5120
+ ck("another marketplace and a package parent are ignored",
5121
+ solo_other.get(child) == (child, "self") and pack_only.get(child) == (child, "self"))
5122
+ ck("empty and junk inputs never raise", catalog_parent_map(None) == {}
5123
+ and catalog_parent_map([None, "x", {"asin": ""}]) == {})
5124
+
5125
+ con = duckdb.connect(":memory:")
5126
+ try:
5127
+ con.execute("CREATE TABLE _sync_state (entity VARCHAR PRIMARY KEY, phase VARCHAR, last_id BIGINT, "
5128
+ "cursor_wd VARCHAR, rows BIGINT, updated_at VARCHAR)")
5129
+ # Resolver before any table exists: no own-ASIN source means None, never an error.
5130
+ ck("resolver with no listings or catalog is None and an empty map",
5131
+ asin_parents_sql(con) is None and asin_parents(con) == {})
5132
+ own = [child, parent, standalone, lonely, broken, eco_only]
5133
+ # Listed ASINs Amazon's catalog returns no item for (the live 5 of 1164).
5134
+ eco_listed, nothing = "B0ECOLIST1", "B0NOTHING1"
5135
+ listed = own + [eco_listed, nothing, child]
5136
+ con.execute("CREATE TABLE amzn_listings (asin1 VARCHAR)")
5137
+ con.executemany("INSERT INTO amzn_listings VALUES (?)", [[a] for a in listed])
5138
+ only_listings = asin_parents(con)
5139
+ ck("resolver with listings only maps every listed ASIN to itself",
5140
+ set(only_listings) == set(listed) and all(v == (k, "self") for k, v in only_listings.items()))
5141
+ con.execute("CREATE TABLE amzn_economics (child_asin VARCHAR, parent_asin VARCHAR, start_date VARCHAR)")
5142
+ con.executemany("INSERT INTO amzn_economics VALUES (?, ?, ?)", [
5143
+ [eco_only, "B0ECOOLDPR", "2026-08-01"], [eco_only, "B0ECOPARNT", "2026-09-01"],
5144
+ [eco_listed, "B0ECOLDPAR", "2026-07-01"], [eco_listed, "B0ECOLSTPR", "2026-09-10"],
5145
+ [eco_listed, None, "2026-09-20"]])
5146
+ con.execute("CREATE TABLE amzn_pricing (child_asin VARCHAR, parent_asin VARCHAR, _period_start VARCHAR)")
5147
+ con.executemany("INSERT INTO amzn_pricing VALUES (?, ?, ?)", [
5148
+ [standalone, "B0OLDPARNT", "2026-08-01T00:00:00Z"],
5149
+ [standalone, "B0PRICEPAR", "2026-09-01T00:00:00Z"]])
5150
+ asked = []
5151
+
5152
+ def records(_fields, operation, **kwargs):
5153
+ asked.append(list(kwargs.get("asins") or ()))
5154
+ return [i for i in items if i["asin"] in kwargs.get("asins", ())]
5155
+
5156
+ # An older snapshot day with a different parent: the readback must use the LATEST day.
5157
+ with patch.object(cx, "access_token", side_effect=AssertionError("No LWA in fixtures")), \
5158
+ patch.object(cx.urllib.request, "urlopen", side_effect=AssertionError("No network in fixtures")), \
5159
+ patch.object(cx, "group_a_records", side_effect=records):
5160
+ count = _sync_margin_window(con, "catalog_items", {}, None, None, max_wait=1, log=lambda *_: None)
5161
+ con.execute("INSERT INTO amzn_catalog_items (asin, parent_asin, parent_asin_source, _snapshot_date) "
5162
+ "VALUES (?, 'B0STALEPAR', 'relationships', '2000-01-01')", [child])
5163
+ latest = con.execute("SELECT MAX(_snapshot_date) FROM amzn_catalog_items").fetchone()[0]
5164
+ mapped = dict((a, (p, s)) for a, p, s in con.execute(
5165
+ "SELECT asin, parent_asin, parent_asin_source FROM amzn_catalog_items WHERE _snapshot_date=?",
5166
+ [latest]).fetchall())
5167
+ columns = {r[1] for r in con.execute("PRAGMA table_info('amzn_catalog_items')").fetchall()}
5168
+ state = _read_state(con, entity_key("reconcile_catalog_items")) or {}
5169
+ marker = json.loads(state.get("detail") or "{}")
5170
+ ck("store readback shows the parent of a known child ASIN on the latest snapshot",
5171
+ mapped.get(child) == (parent, "relationships"))
5172
+ ck("catalog asks for every listed ASIN and maps every item it returns",
5173
+ asked == [sorted(set(listed))] and set(mapped) == set(own)
5174
+ and all(p for p, _ in mapped.values()))
5175
+ ck("catalog sync stamps the economics fallback", mapped.get(eco_only) == ("B0ECOPARNT", "economics"))
5176
+ # Resolver: two catalog snapshot days, an old-day-only ASIN, a latest-day catalog-only ASIN.
5177
+ con.execute("INSERT INTO amzn_catalog_items (asin, parent_asin, parent_asin_source, _snapshot_date) "
5178
+ "VALUES ('B0OLDONLY1', 'B0OLDONLY1', 'self', '2000-01-01')")
5179
+ con.execute("INSERT INTO amzn_catalog_items (asin, parent_asin, parent_asin_source, _snapshot_date) "
5180
+ "VALUES ('B0CATONLY1', 'B0CATPARNT', 'relationships', ?)", [latest])
5181
+ resolved = asin_parents(con)
5182
+ rows = con.execute(asin_parents_sql(con)).fetchall()
5183
+ ck("resolver covers every own ASIN exactly once, latest catalog day only",
5184
+ set(resolved) == set(listed) | {"B0CATONLY1"} and len(rows) == len(resolved)
5185
+ and "B0OLDONLY1" not in resolved and all(p for p, _ in resolved.values()))
5186
+ ck("resolver readback shows the latest parent of a known child",
5187
+ resolved.get(child) == (parent, "relationships") and resolved.get("B0CATONLY1")
5188
+ == ("B0CATPARNT", "relationships"))
5189
+ ck("resolver falls back to the newest economics parent, then to itself",
5190
+ resolved.get(eco_listed) == ("B0ECOLSTPR", "economics") and resolved.get(nothing) == (nothing, "self"))
5191
+ # A catalog mirror synced before S67-T29 has no parent_asin column: economics and self carry it.
5192
+ old = duckdb.connect(":memory:")
5193
+ try:
5194
+ old.execute("CREATE TABLE amzn_catalog_items (asin VARCHAR, _snapshot_date VARCHAR)")
5195
+ old.execute(f"INSERT INTO amzn_catalog_items VALUES ('{child}', '2026-09-01'), ('{eco_listed}', '2026-09-01')")
5196
+ old.execute("CREATE TABLE amzn_economics (child_asin VARCHAR, parent_asin VARCHAR)")
5197
+ old.execute(f"INSERT INTO amzn_economics VALUES ('{eco_listed}', 'B0ECOLSTPR')")
5198
+ ck("resolver degrades on a pre-T29 catalog with no listings table",
5199
+ asin_parents(old) == {child: (child, "self"), eco_listed: ("B0ECOLSTPR", "economics")})
5200
+ finally:
5201
+ old.close()
5202
+ # O23 order in the READ-TIME resolver: catalog, then pricing, then economics, then self.
5203
+ pri = duckdb.connect(":memory:")
5204
+ try:
5205
+ pri.execute("CREATE TABLE amzn_listings (asin1 VARCHAR)")
5206
+ pri.execute(f"INSERT INTO amzn_listings VALUES ('{eco_listed}'), ('{nothing}')")
5207
+ pri.execute("CREATE TABLE amzn_economics (child_asin VARCHAR, parent_asin VARCHAR)")
5208
+ pri.execute(f"INSERT INTO amzn_economics VALUES ('{eco_listed}', 'B0ECOLSTPR'), "
5209
+ f"('{nothing}', 'B0ECONOTHG')")
5210
+ pri.execute("CREATE TABLE amzn_pricing (child_asin VARCHAR, parent_asin VARCHAR)")
5211
+ pri.execute(f"INSERT INTO amzn_pricing VALUES ('{eco_listed}', 'B0PRICEPA2')")
5212
+ got = asin_parents(pri)
5213
+ ck("resolver: a pricing parent wins over economics, economics still answers the rest",
5214
+ got.get(eco_listed) == ("B0PRICEPA2", "pricing")
5215
+ and got.get(nothing) == ("B0ECONOTHG", "economics"))
5216
+ pri.execute("CREATE OR REPLACE TABLE amzn_pricing (parent_asin VARCHAR)")
5217
+ ck("NC: a pricing mirror with no child_asin (the live mirror today) adds no pricing step",
5218
+ asin_parents(pri).get(eco_listed) == ("B0ECOLSTPR", "economics"))
5219
+ finally:
5220
+ pri.close()
5221
+ # SKU grain (S67-T29 finding): the request asks for it, and the first SKU-grain pull
5222
+ # replaces a parent-grain mirror instead of sitting beside it.
5223
+ grain = duckdb.connect(":memory:")
5224
+ try:
5225
+ quiet = lambda *_a, **_k: None # noqa: E731
5226
+ sku_rows = [{"parent_asin": "B0PARENT01", "child_asin": "B0CHILD001", "sku": "RI-1"}]
5227
+ ck("regrain: an absent mirror is left alone", _pricing_regrain(grain, "amzn_pricing", sku_rows, quiet) is False)
5228
+ grain.execute("CREATE TABLE amzn_pricing (parent_asin VARCHAR, report_date VARCHAR)")
5229
+ grain.execute("INSERT INTO amzn_pricing VALUES ('B0PARENT01', '2026-09-01'), ('B0PARENT02', '2026-09-02')")
5230
+ ck("regrain: parent-grain rows WITHOUT child_asin never clear the mirror",
5231
+ _pricing_regrain(grain, "amzn_pricing", [{"parent_asin": "B0PARENT03"}], quiet) is False
5232
+ and grain.execute("SELECT COUNT(*) FROM amzn_pricing").fetchone()[0] == 2)
5233
+ ck("regrain: the first SKU-grain pull clears the parent-grain mirror (one grain per table)",
5234
+ _pricing_regrain(grain, "amzn_pricing", sku_rows, quiet) is True
5235
+ and grain.execute("SELECT COUNT(*) FROM amzn_pricing").fetchone()[0] == 0)
5236
+ grain.execute("ALTER TABLE amzn_pricing ADD COLUMN child_asin VARCHAR")
5237
+ grain.execute("INSERT INTO amzn_pricing VALUES ('B0PARENT01', '2026-09-03', 'B0CHILD001')")
5238
+ ck("regrain: an already SKU-grain mirror keeps its history",
5239
+ _pricing_regrain(grain, "amzn_pricing", sku_rows, quiet) is False
5240
+ and grain.execute("SELECT COUNT(*) FROM amzn_pricing").fetchone()[0] == 1)
5241
+ finally:
5242
+ grain.close()
5243
+ with open(__file__, encoding="utf-8") as _src:
5244
+ passes_options = _src.read().count('REPORT_OPTIONS[table]') >= 2
5245
+ ck("the Sales and Traffic request asks for SKU grain, the same report and role",
5246
+ REPORT_OPTIONS.get("pricing") == {"asinGranularity": "SKU"} and passes_options)
5247
+ ck("pricing fallback reads the newest pricing period", mapped.get(standalone) == ("B0PRICEPAR", "pricing"))
5248
+ ck("raw relationships JSON is kept beside the derived columns",
5249
+ {"relationships", "parent_asin", "parent_asin_source"} <= columns)
5250
+ ck("row count stays Amazon's record count", count == len(own) and marker.get("count") == len(own))
5251
+ finally:
5252
+ con.close()
5253
  return 1 if failures else 0
5254
 
5255
 
platform/modules/sheet.py CHANGED
@@ -682,6 +682,24 @@ def clean_binding(raw):
682
  return out
683
 
684
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
685
  def filter_cell_nodes(nodes):
686
  """Cell value slots live on leaves at any depth, never on a fixed object path."""
687
  for node in nodes or ():
 
682
  return out
683
 
684
 
685
+ def date_formatted_cell(cell):
686
+ """S67-T10 (QI4, D-767): a cell is a date when its number format says so.
687
+
688
+ A Date format set by hand, the format the engine infers for DATE() / TODAY() / NOW() (written
689
+ into ``style.format``), or an imported Excel code carrying day or year tokens. Mirrors
690
+ ``aios-web/web/src/sheet/bindingRefs.ts::isDateFormattedCell``.
691
+ """
692
+ import re as _re
693
+ fmt = ((cell or {}).get("style") or {}).get("format") if isinstance(cell, dict) else None
694
+ if not isinstance(fmt, dict):
695
+ return False
696
+ if fmt.get("kind") == "date":
697
+ return True
698
+ code = fmt.get("code")
699
+ return (fmt.get("kind") == "code" and isinstance(code, str)
700
+ and _re.search(r"[dy]", _re.sub(r'"[^"]*"|\\.', "", code), _re.I) is not None)
701
+
702
+
703
  def filter_cell_nodes(nodes):
704
  """Cell value slots live on leaves at any depth, never on a fixed object path."""
705
  for node in nodes or ():
web/public/AIOS_DEPLOY_RECEIPT CHANGED
@@ -1 +1 @@
1
- 4bddbdac0a66f19f85828e1077bbbc16266db0d5f1e63fa1448e0a2b41a57313
 
1
+ eb084c3f9d52c9da87adb2168567d2ecf4bb936d483cfea8bcdcfe15160dedde
web/src/apps/contentStudio/ContentStudioApp.tsx ADDED
@@ -0,0 +1,271 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { Suspense, lazy, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
2
+ import { API_V1, CREDENTIALS } from "../../apiContract";
3
+ import { BodyPortal, useOverlayLayer } from "../../customer-grid/OverlaySurface";
4
+ import { dataPathHash } from "../../customer-grid/dataPath";
5
+ import type { Field, Row } from "../../customer-grid/types";
6
+ import { CalendarView, KanbanView } from "../../customer-grid/viewModes";
7
+ import "../../styles/wave50/grid.css";
8
+
9
+ /** Drafting is its own drawer (S67-T41/T42); it loads only when the owner asks to draft. */
10
+ const DraftPanel = lazy(() => import("./DraftPanel"));
11
+
12
+ interface StudioPost { pid: number; caption?: string | null; channel?: string | null; scheduled?: string | null;
13
+ status?: string | null; attribution?: string | null; campaign?: string | null }
14
+ interface Studio {
15
+ app: { id: string; name: string };
16
+ posts: { database: string; label: string; fields: Field[]; rows: StudioPost[] };
17
+ references: { database: string; label: string; count: number };
18
+ statuses: string[];
19
+ }
20
+ type Load = { phase: "loading" } | { phase: "error"; message: string } | { phase: "ready"; studio: Studio };
21
+ type Mode = "calendar" | "board";
22
+
23
+ /** The server's own sentence first (top-level `error.message`), then the legacy nesting. */
24
+ const sentence = (body: unknown, fallback: string): string => {
25
+ const row = body as { error?: { message?: string }; detail?: { error?: { message?: string } } } | null;
26
+ return row?.error?.message || row?.detail?.error?.message || fallback;
27
+ };
28
+
29
+ const plural = (n: number, one: string, many: string) => `${n} ${n === 1 ? one : many}`;
30
+
31
+ /** A post's one-line name on a calendar chip or a board card: its channel, then its opening words. */
32
+ const titleOf = (post: StudioPost): string => {
33
+ const words = String(post.caption ?? "").replace(/\s+/g, " ").trim();
34
+ const head = words.length > 70 ? `${words.slice(0, 70).trimEnd()}…` : words || "Untitled post";
35
+ return post.channel ? `${post.channel}: ${head}` : head;
36
+ };
37
+
38
+ const TITLE_FIELD: Field = { key: "title", label: "Post", type: "text", source: "overlay" };
39
+
40
+ /**
41
+ * S67-T41 OWNER CORRECTION (Telegram update 437342853, 2026-09-28): "Content studio should be an
42
+ * App ... it should act like Catalog / Route where it just uses the data module as what its
43
+ * building on top." So this is the App: it opens in the App module on its own surface and works
44
+ * the Posts and References databases underneath, which stay in Data. A calendar of posts by
45
+ * Scheduled beside the posts not yet scheduled, a board of posts by Status (a drag moves one),
46
+ * a post drawer to schedule it, and the Draft door. Plan-only (round 1 R5): nothing publishes.
47
+ * The calendar and the board are the grid's own `CalendarView` and `KanbanView`, unchanged.
48
+ */
49
+ export default function ContentStudioApp({ appId }: { appId: string }) {
50
+ const [load, setLoad] = useState<Load>({ phase: "loading" });
51
+ const [epoch, setEpoch] = useState(0);
52
+ const [mode, setMode] = useState<Mode>("calendar");
53
+ const [draftOpen, setDraftOpen] = useState(false);
54
+ const [openPid, setOpenPid] = useState<number | null>(null);
55
+ const [notice, setNotice] = useState("");
56
+ const [moved, setMoved] = useState<Record<number, string>>({});
57
+
58
+ useEffect(() => {
59
+ const controller = new AbortController();
60
+ void fetch(`${API_V1}/content-studio/studio?app=${encodeURIComponent(appId)}`,
61
+ { credentials: CREDENTIALS, signal: controller.signal })
62
+ .then(async (response) => {
63
+ const body = await response.json().catch(() => null);
64
+ if (!response.ok) throw new Error(sentence(body, "This Content Studio could not be loaded. Reload to retry."));
65
+ setLoad({ phase: "ready", studio: body as Studio });
66
+ setMoved({});
67
+ })
68
+ .catch((failure: unknown) => {
69
+ if (controller.signal.aborted) return;
70
+ setLoad({ phase: "error",
71
+ message: failure instanceof Error ? failure.message : "This Content Studio could not be loaded. Reload to retry." });
72
+ });
73
+ return () => controller.abort();
74
+ }, [appId, epoch]);
75
+
76
+ // A draft written from the drawer lands in Posts; read the App again so it appears here.
77
+ useEffect(() => {
78
+ const reload = () => setEpoch((value) => value + 1);
79
+ window.addEventListener("aios:grid-refresh", reload);
80
+ return () => window.removeEventListener("aios:grid-refresh", reload);
81
+ }, []);
82
+
83
+ const studio = load.phase === "ready" ? load.studio : null;
84
+ const fieldByKey = useMemo(() => {
85
+ const map = new Map<string, Field>((studio?.posts.fields ?? []).map((field) => [field.key, field]));
86
+ map.set(TITLE_FIELD.key, TITLE_FIELD);
87
+ return map;
88
+ }, [studio]);
89
+ const rows: Row[] = useMemo(() => (studio?.posts.rows ?? []).map((post) => ({
90
+ ...post, status: moved[post.pid] ?? post.status ?? null, title: titleOf(post),
91
+ }) as Row), [studio, moved]);
92
+ const scheduledField = fieldByKey.get("scheduled");
93
+ const statusField = fieldByKey.get("status");
94
+ const unscheduled = rows.filter((row) => !String(row.scheduled ?? "").trim());
95
+ const openPost = studio?.posts.rows.find((post) => post.pid === openPid) ?? null;
96
+
97
+ const postsDatabase = studio?.posts.database ?? "";
98
+ // KanbanView is memo'd and keeps its props stable on purpose, so both handlers are too.
99
+ const openCard = useCallback((pid: number) => setOpenPid(pid), []);
100
+ const move = useCallback((pid: number, value: string) => {
101
+ if (!postsDatabase) return;
102
+ setNotice("");
103
+ setMoved((current) => ({ ...current, [pid]: value }));
104
+ void fetch(`${API_V1}/tables/${encodeURIComponent(postsDatabase)}/rows/${pid}`, {
105
+ method: "PATCH", credentials: CREDENTIALS, headers: { "Content-Type": "application/json" },
106
+ body: JSON.stringify({ status: value }),
107
+ }).then(async (response) => {
108
+ if (!response.ok) throw new Error(sentence(await response.json().catch(() => null), "The post could not be moved. Try again."));
109
+ setEpoch((current) => current + 1);
110
+ }).catch((failure: unknown) => {
111
+ setMoved((current) => { const next = { ...current }; delete next[pid]; return next; });
112
+ setNotice(failure instanceof Error ? failure.message : "The post could not be moved. Try again.");
113
+ });
114
+ }, [postsDatabase]);
115
+
116
+ if (load.phase === "loading") {
117
+ return <div className="shell-home" data-content-studio-app={appId} aria-busy="true">
118
+ <div className="home-page-head"><h1 className="home-title">Content Studio</h1></div>
119
+ <div className="sheet-template-list" role="status" aria-label="Loading Content Studio">
120
+ {[0, 1, 2].map((row) => <div key={row} className="sheet-template-skeleton" aria-hidden="true">
121
+ <span className="sheet-template-skeleton-title" /><span className="sheet-template-skeleton-answer" />
122
+ </div>)}
123
+ </div>
124
+ </div>;
125
+ }
126
+ if (load.phase === "error" || !studio) {
127
+ return <div className="shell-home" data-content-studio-app={appId}>
128
+ <div className="home-page-head"><h1 className="home-title">Content Studio</h1></div>
129
+ <p className="shell-newdb-err" role="alert">{load.phase === "error" ? load.message : ""}</p>
130
+ </div>;
131
+ }
132
+
133
+ return <div className="shell-home" data-content-studio-app={appId}>
134
+ <div className="home-page-head" style={{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: 16, flexWrap: "wrap" }}>
135
+ <div>
136
+ <h1 className="home-title">{studio.app.name}</h1>
137
+ <p className="home-empty" style={{ margin: "4px 0 0" }} data-content-studio-counts="">
138
+ {plural(studio.posts.rows.length, "post", "posts")} · {plural(studio.references.count, "reference", "references")}
139
+ </p>
140
+ </div>
141
+ <div style={{ display: "flex", gap: 8, alignItems: "center" }}>
142
+ <a className="lp-dialog-btn lp-dialog-btn-quiet" style={{ textDecoration: "none" }}
143
+ href={dataPathHash({ database: studio.references.database })}
144
+ title={`Open the ${studio.references.label} database this App drafts from`}>{studio.references.label}</a>
145
+ <a className="lp-dialog-btn lp-dialog-btn-quiet" style={{ textDecoration: "none" }}
146
+ href={dataPathHash({ database: studio.posts.database })}
147
+ title={`Open the ${studio.posts.label} database this App plans`}>{studio.posts.label}</a>
148
+ <button type="button" className="lp-dialog-btn lp-dialog-btn-primary" data-content-studio-draft-door=""
149
+ onClick={() => setDraftOpen(true)}>Draft posts</button>
150
+ </div>
151
+ </div>
152
+
153
+ {/* The same worded toggle the Templates picker uses (`home-layout-btn`, sized to its words). */}
154
+ <div className="home-layout-toggle" role="group" aria-label="Show posts as" style={{ margin: "4px 0 12px" }}>
155
+ {(["calendar", "board"] as const).map((value) => <button key={value} type="button"
156
+ className={"home-layout-btn" + (mode === value ? " is-on" : "")} aria-pressed={mode === value}
157
+ style={{ width: "auto", paddingInline: 12 }}
158
+ data-content-studio-mode={value} onClick={() => setMode(value)}>
159
+ {value === "calendar" ? "Calendar" : "Board"}
160
+ </button>)}
161
+ </div>
162
+ {notice ? <p className="shell-newdb-err" role="alert">{notice}</p> : null}
163
+
164
+ {mode === "calendar" ? <div style={{ display: "grid", gridTemplateColumns: "minmax(0, 1fr) 300px", gap: 20, alignItems: "start" }}>
165
+ <div data-content-studio-calendar="" style={{ minWidth: 0 }}>
166
+ {!scheduledField ? <p className="home-empty">Posts has no Scheduled date field, so there is no calendar.</p>
167
+ : rows.length === 0 ? <p className="home-empty" data-content-studio-calendar-empty="">
168
+ No posts yet. Use Draft posts to write some from your references.</p>
169
+ : rows.length === unscheduled.length ? <p className="home-empty" data-content-studio-calendar-empty="">
170
+ No post is scheduled yet. Open one under Not scheduled to give it a date.</p>
171
+ : <CalendarView rows={rows} field={scheduledField} titleKey="title"
172
+ fieldByKey={fieldByKey} onOpen={openCard} />}
173
+ </div>
174
+ <section aria-label="Not scheduled" data-content-studio-unscheduled="" style={{ minWidth: 0, overflow: "hidden" }}>
175
+ <h2 className="home-section-title">Not scheduled</h2>
176
+ {unscheduled.length === 0 ? <p className="home-empty">
177
+ {rows.length === 0 ? "Nothing is waiting for a date." : "Every post has a date."}</p>
178
+ : <ul style={{ listStyle: "none", margin: 0, padding: 0, display: "grid", gap: 8,
179
+ gridTemplateColumns: "minmax(0, 1fr)" }}>
180
+ {unscheduled.map((row) => <li key={row.pid} style={{ minWidth: 0 }}>
181
+ <button type="button" className="home-tile"
182
+ style={{ width: "100%", maxWidth: "100%", boxSizing: "border-box", minWidth: 0, textAlign: "left" }}
183
+ onClick={() => setOpenPid(row.pid)}>
184
+ <span className="home-tile-text" style={{ minWidth: 0, overflow: "hidden" }}>
185
+ <span className="home-tile-name">{String(row.title ?? "")}</span>
186
+ <span className="home-tile-ago">{String(row.status ?? "Idea")}</span>
187
+ </span>
188
+ </button>
189
+ </li>)}
190
+ </ul>}
191
+ </section>
192
+ </div> : statusField ? <div data-content-studio-board="">
193
+ <KanbanView rows={rows} field={statusField} fieldByKey={fieldByKey} cardKeys={["scheduled"]}
194
+ titleKey="title" canMove readOnlyReason={null} onMove={move} onOpen={openCard}
195
+ onAddOption={null} />
196
+ </div> : <p className="home-empty">Posts has no Status field, so there is no board.</p>}
197
+
198
+ {openPost ? <PostDrawer post={openPost} database={studio.posts.database} statuses={studio.statuses}
199
+ onClose={() => setOpenPid(null)} onSaved={() => { setOpenPid(null); setEpoch((value) => value + 1); }} /> : null}
200
+ {draftOpen ? <Suspense fallback={null}>
201
+ <DraftPanel appId={appId} onClose={() => setDraftOpen(false)} />
202
+ </Suspense> : null}
203
+ </div>;
204
+ }
205
+
206
+ /** One post: read its caption and credit, set its date and status. Saved through Posts' own row door. */
207
+ function PostDrawer({ post, database, statuses, onClose, onSaved }: {
208
+ post: StudioPost; database: string; statuses: string[]; onClose: () => void; onSaved: () => void;
209
+ }) {
210
+ const panelRef = useRef<HTMLDivElement>(null);
211
+ const titleId = useId();
212
+ const dateId = useId();
213
+ const statusId = useId();
214
+ const [scheduled, setScheduled] = useState(String(post.scheduled ?? "").slice(0, 10));
215
+ const [status, setStatus] = useState(String(post.status ?? "") || statuses[0] || "");
216
+ const [busy, setBusy] = useState(false);
217
+ const [error, setError] = useState("");
218
+ const dismiss = () => { if (!busy) onClose(); };
219
+ useOverlayLayer({ panelRef, onDismiss: dismiss, dismissOnOutside: false,
220
+ initialFocus: "[data-overlay-autofocus]", restoreFocus: true, trapFocus: true });
221
+
222
+ const save = async () => {
223
+ setBusy(true);
224
+ setError("");
225
+ try {
226
+ const response = await fetch(`${API_V1}/tables/${encodeURIComponent(database)}/rows/${post.pid}`, {
227
+ method: "PATCH", credentials: CREDENTIALS, headers: { "Content-Type": "application/json" },
228
+ body: JSON.stringify({ scheduled, status }),
229
+ });
230
+ if (!response.ok) throw new Error(sentence(await response.json().catch(() => null), "The post could not be saved. Try again."));
231
+ onSaved();
232
+ } catch (failure) {
233
+ setError(failure instanceof Error ? failure.message : "The post could not be saved. Try again.");
234
+ setBusy(false);
235
+ }
236
+ };
237
+
238
+ return <BodyPortal>
239
+ <div ref={panelRef} className="lp-dialog" role="dialog" aria-modal="true" aria-labelledby={titleId}
240
+ data-content-studio-post={post.pid} aria-busy={busy}
241
+ style={{ position: "fixed", top: 0, right: 0, bottom: 0, width: "min(420px, 100vw)", maxHeight: "100dvh",
242
+ borderRadius: 0, overflowY: "auto", zIndex: 60, boxShadow: "-12px 0 30px rgb(34 25 74 / 12%)" }}>
243
+ <div className="lp-dialog-head">
244
+ <h2 className="lp-dialog-title" id={titleId}>{post.channel ? `${post.channel} post` : "Post"}</h2>
245
+ <button type="button" className="lp-dialog-x" aria-label="Close" disabled={busy} onClick={dismiss}>
246
+ <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true" focusable="false">
247
+ <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.5" />
248
+ </svg>
249
+ </button>
250
+ </div>
251
+ <div className="lp-dialog-body">
252
+ <p style={{ whiteSpace: "pre-wrap", margin: 0 }}>{post.caption || "No caption yet."}</p>
253
+ {post.attribution ? <p className="home-empty" style={{ marginTop: 10 }}>{post.attribution}</p> : null}
254
+ <label htmlFor={dateId} style={{ display: "block", marginTop: 16, fontWeight: 600 }}>Scheduled</label>
255
+ <input id={dateId} className="cg-input" type="date" value={scheduled} disabled={busy} data-overlay-autofocus=""
256
+ onChange={(event) => setScheduled(event.target.value)} />
257
+ <label htmlFor={statusId} style={{ display: "block", marginTop: 12, fontWeight: 600 }}>Status</label>
258
+ <select id={statusId} className="cg-input" value={status} disabled={busy}
259
+ onChange={(event) => setStatus(event.target.value)}>
260
+ {statuses.map((value) => <option key={value} value={value}>{value}</option>)}
261
+ </select>
262
+ {error ? <p className="shell-newdb-err" role="alert">{error}</p> : null}
263
+ </div>
264
+ <div className="lp-dialog-actions">
265
+ <button type="button" className="lp-dialog-btn lp-dialog-btn-quiet" disabled={busy} onClick={dismiss}>Close</button>
266
+ <button type="button" className="lp-dialog-btn lp-dialog-btn-primary" disabled={busy}
267
+ data-content-studio-post-save="" onClick={() => void save()}>{busy ? "Saving…" : "Save"}</button>
268
+ </div>
269
+ </div>
270
+ </BodyPortal>;
271
+ }
web/src/apps/contentStudio/ContentStudioSetup.tsx ADDED
@@ -0,0 +1,83 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { useId, useRef, useState } from "react";
2
+ import { API_V1, CREDENTIALS } from "../../apiContract";
3
+ import { BodyPortal, useOverlayLayer } from "../../customer-grid/OverlaySurface";
4
+
5
+ /** The Templates catalogue key this dialog answers for (`content_studio.TEMPLATE_KEY`). */
6
+ export const CONTENT_STUDIO_TEMPLATE_KEY = "content_studio";
7
+
8
+ /**
9
+ * S67-T40 (R21, O2): Content Studio's create-for-me step, IN PLACE of "Choose a database". The
10
+ * template makes its own tenant-owned References and Posts databases, so there is nothing to
11
+ * choose; this dialog names what will be created and hands back the App's address.
12
+ */
13
+ export default function ContentStudioSetup({ onCancel, onCreated }: {
14
+ onCancel: () => void;
15
+ onCreated: (address: string) => void;
16
+ }) {
17
+ const panelRef = useRef<HTMLDivElement>(null);
18
+ const titleId = useId();
19
+ const nameId = useId();
20
+ const [name, setName] = useState("Content Studio");
21
+ const [busy, setBusy] = useState(false);
22
+ const [error, setError] = useState("");
23
+ const dismiss = () => { if (!busy) onCancel(); };
24
+ useOverlayLayer({ panelRef, onDismiss: dismiss, dismissOnOutside: false,
25
+ initialFocus: "[data-overlay-autofocus]", restoreFocus: true, trapFocus: true });
26
+
27
+ const create = async () => {
28
+ if (busy) return;
29
+ setBusy(true);
30
+ setError("");
31
+ try {
32
+ const response = await fetch(`${API_V1}/templates/app/${CONTENT_STUDIO_TEMPLATE_KEY}`, {
33
+ method: "POST", credentials: CREDENTIALS, headers: { "Content-Type": "application/json" },
34
+ body: JSON.stringify({ name }),
35
+ });
36
+ const body = await response.json().catch(() => null);
37
+ if (!response.ok || typeof body?.address !== "string") {
38
+ throw new Error(body?.error?.message || body?.detail?.error?.message
39
+ || "Content Studio could not be created. Nothing was changed. Try again.");
40
+ }
41
+ window.dispatchEvent(new Event("aios:applications-changed"));
42
+ onCreated(body.address);
43
+ } catch (failure) {
44
+ setError(failure instanceof Error ? failure.message : "Content Studio could not be created. Try again.");
45
+ setBusy(false);
46
+ }
47
+ };
48
+
49
+ return <BodyPortal>
50
+ <div className="lp-dialog-scrim">
51
+ <div ref={panelRef} className="lp-dialog" role="dialog" aria-modal="true" aria-labelledby={titleId}
52
+ aria-busy={busy} style={{ width: "min(520px, calc(100vw - 32px))" }}>
53
+ <div className="lp-dialog-head">
54
+ <h2 className="lp-dialog-title" id={titleId}>Content Studio</h2>
55
+ <button type="button" className="lp-dialog-x" aria-label="Close" disabled={busy} onClick={dismiss}>
56
+ <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true" focusable="false">
57
+ <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.5" />
58
+ </svg>
59
+ </button>
60
+ </div>
61
+ <div className="lp-dialog-body">
62
+ <p>This creates two databases in this workspace, then opens a calendar of your posts.</p>
63
+ <ul data-content-studio-databases="">
64
+ <li><strong>References</strong>: URL, network, author, pasted text, tags, hook, structure and angle.</li>
65
+ <li><strong>Posts</strong>: caption, channel, scheduled date, status, media, campaign, post URL, references and attribution.</li>
66
+ </ul>
67
+ <label htmlFor={nameId}>App name</label>
68
+ <input id={nameId} className="cg-input" type="text" value={name} maxLength={120}
69
+ disabled={busy} onChange={(event) => setName(event.target.value)} />
70
+ {error ? <p className="shell-newdb-err" role="alert">{error}</p> : null}
71
+ </div>
72
+ <div className="lp-dialog-actions">
73
+ <button type="button" className="lp-dialog-btn lp-dialog-btn-quiet" data-overlay-autofocus=""
74
+ disabled={busy} onClick={dismiss}>Cancel</button>
75
+ <button type="button" className="lp-dialog-btn lp-dialog-btn-primary"
76
+ disabled={busy || !name.trim()} onClick={() => void create()}>
77
+ {busy ? "Creating…" : "Create"}
78
+ </button>
79
+ </div>
80
+ </div>
81
+ </div>
82
+ </BodyPortal>;
83
+ }
web/src/apps/contentStudio/DraftPanel.tsx ADDED
@@ -0,0 +1,179 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { useEffect, useId, useRef, useState } from "react";
2
+ import { API_V1, CREDENTIALS } from "../../apiContract";
3
+ import { BodyPortal, useOverlayLayer } from "../../customer-grid/OverlaySurface";
4
+
5
+ interface StudioReference { id: string; title: string; author: string; network: string; extracted: boolean }
6
+ interface Drafted { channel: string; caption: string }
7
+ /** S67-T42 (R35): this workspace's monthly drafting allowance, as the server counts it. */
8
+ interface Allowance { used: number; limit: number; remaining: number; resetsOn: string; paused: boolean; message: string }
9
+
10
+ /** The server's own sentence first (top-level `error.message`), then the legacy nesting. */
11
+ const sentence = (body: unknown, fallback: string): string => {
12
+ const row = body as { error?: { message?: string }; detail?: { error?: { message?: string } } } | null;
13
+ return row?.error?.message || row?.detail?.error?.message || fallback;
14
+ };
15
+
16
+ const listed = (names: string[]): string =>
17
+ names.length <= 1 ? names.join("") : `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
18
+
19
+ /**
20
+ * S67-T41 (R13-R15, R19, R20, R5, O4): Content Studio's drafting drawer. Several References plus
21
+ * a one-line topic become one Draft row per chosen channel in Posts, written from the references'
22
+ * extracted structure and crediting their authors. Plan-only: nothing is published.
23
+ */
24
+ export default function DraftPanel({ appId, onClose }: { appId: string; onClose: () => void }) {
25
+ const panelRef = useRef<HTMLDivElement>(null);
26
+ const titleId = useId();
27
+ const topicId = useId();
28
+ const [phase, setPhase] = useState<"loading" | "ready" | "error">("loading");
29
+ const [loadError, setLoadError] = useState("");
30
+ const [references, setReferences] = useState<StudioReference[]>([]);
31
+ const [channels, setChannels] = useState<string[]>([]);
32
+ const [advice, setAdvice] = useState<Record<string, string>>({});
33
+ const [selected, setSelected] = useState<string[]>([]);
34
+ const [chosen, setChosen] = useState<string[]>([]);
35
+ const [topic, setTopic] = useState("");
36
+ const [busy, setBusy] = useState(false);
37
+ const [error, setError] = useState("");
38
+ const [drafted, setDrafted] = useState<Drafted[]>([]);
39
+ const [allowance, setAllowance] = useState<Allowance | null>(null);
40
+ const dismiss = () => { if (!busy) onClose(); };
41
+ useOverlayLayer({ panelRef, onDismiss: dismiss, dismissOnOutside: false,
42
+ initialFocus: "[data-overlay-autofocus]", restoreFocus: true, trapFocus: true });
43
+
44
+ useEffect(() => {
45
+ const controller = new AbortController();
46
+ void fetch(`${API_V1}/content-studio/references?app=${encodeURIComponent(appId)}`,
47
+ { credentials: CREDENTIALS, signal: controller.signal })
48
+ .then(async (response) => {
49
+ const body = await response.json().catch(() => null);
50
+ if (!response.ok) throw new Error(sentence(body, "References could not be loaded. Try again."));
51
+ setReferences(Array.isArray(body?.references) ? body.references : []);
52
+ setChannels(Array.isArray(body?.channels) ? body.channels : []);
53
+ setAdvice(body?.advice && typeof body.advice === "object" ? body.advice : {});
54
+ setAllowance(body?.allowance && typeof body.allowance === "object" ? body.allowance : null);
55
+ setPhase("ready");
56
+ })
57
+ .catch((failure: unknown) => {
58
+ if (controller.signal.aborted) return;
59
+ setLoadError(failure instanceof Error ? failure.message : "References could not be loaded. Try again.");
60
+ setPhase("error");
61
+ });
62
+ return () => controller.abort();
63
+ }, [appId]);
64
+
65
+ const toggle = (list: string[], value: string) =>
66
+ list.includes(value) ? list.filter((item) => item !== value) : [...list, value];
67
+ // NC: Draft stays disabled, WITH the reason, until every input it needs is there.
68
+ // R35: a used allowance pauses Draft and says when it resets, ahead of every other reason.
69
+ const reason = allowance?.paused ? allowance.message
70
+ : selected.length === 0 ? "Select at least one reference to draft from."
71
+ : !topic.trim() ? "Type a one-line topic for the draft."
72
+ : chosen.length === 0 ? "Choose at least one channel." : "";
73
+
74
+ const draft = async () => {
75
+ if (busy || reason) return;
76
+ setBusy(true);
77
+ setError("");
78
+ setDrafted([]);
79
+ try {
80
+ const response = await fetch(`${API_V1}/content-studio/draft`, {
81
+ method: "POST", credentials: CREDENTIALS, headers: { "Content-Type": "application/json" },
82
+ body: JSON.stringify({ app: appId, references: selected, topic, channels: chosen }),
83
+ });
84
+ const body = await response.json().catch(() => null);
85
+ if (response.status === 429 && body?.error?.code === "drafting_allowance_used") {
86
+ const message = sentence(body, "This workspace has used this month's drafting allowance.");
87
+ setAllowance((current) => current ? { ...current, remaining: 0, paused: true, message }
88
+ : { used: 0, limit: 0, remaining: 0, resetsOn: "", paused: true, message });
89
+ }
90
+ if (!response.ok) throw new Error(sentence(body, "The drafts could not be written. Nothing was saved."));
91
+ const made: Drafted[] = Array.isArray(body?.drafts) ? body.drafts : [];
92
+ setDrafted(made);
93
+ // The server owns the count and its sentence: re-read it rather than guess it here.
94
+ void fetch(`${API_V1}/content-studio/references?app=${encodeURIComponent(appId)}`, { credentials: CREDENTIALS })
95
+ .then((reply) => reply.ok ? reply.json() : null)
96
+ .then((fresh) => { if (fresh?.allowance && typeof fresh.allowance === "object") setAllowance(fresh.allowance); })
97
+ .catch(() => undefined);
98
+ window.dispatchEvent(new Event("aios:grid-refresh"));
99
+ } catch (failure) {
100
+ setError(failure instanceof Error ? failure.message : "The drafts could not be written. Nothing was saved.");
101
+ } finally {
102
+ setBusy(false);
103
+ }
104
+ };
105
+
106
+ return <BodyPortal>
107
+ <div ref={panelRef} className="lp-dialog" role="dialog" aria-modal="true" aria-labelledby={titleId}
108
+ data-content-studio-draft="" aria-busy={busy}
109
+ style={{ position: "fixed", top: 0, right: 0, bottom: 0, width: "min(420px, 100vw)", maxHeight: "100dvh",
110
+ borderRadius: 0, overflowY: "auto", zIndex: 60, boxShadow: "-12px 0 30px rgb(34 25 74 / 12%)" }}>
111
+ <div className="lp-dialog-head">
112
+ <h2 className="lp-dialog-title" id={titleId}>Draft posts</h2>
113
+ <button type="button" className="lp-dialog-x" aria-label="Close" disabled={busy} onClick={dismiss}>
114
+ <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true" focusable="false">
115
+ <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.5" />
116
+ </svg>
117
+ </button>
118
+ </div>
119
+ <div className="lp-dialog-body">
120
+ <h3 className="home-section-title">References</h3>
121
+ {phase === "loading" ? <div className="sheet-template-list" role="status" aria-label="Loading references">
122
+ {[0, 1, 2].map((row) => <div key={row} className="sheet-template-skeleton" aria-hidden="true">
123
+ <span className="sheet-template-skeleton-title" /><span className="sheet-template-skeleton-answer" />
124
+ </div>)}
125
+ </div> : phase === "error" ? <p className="shell-newdb-err" role="alert">{loadError}</p>
126
+ : references.length === 0 ? <p className="home-empty">No references yet. Add one to References, then paste its text.</p>
127
+ : <ul style={{ listStyle: "none", padding: 0, margin: 0, display: "grid", gap: 6 }}>
128
+ {references.map((row) => <li key={row.id}>
129
+ <label style={{ display: "flex", gap: 8, alignItems: "flex-start" }}>
130
+ <input type="checkbox" checked={selected.includes(row.id)} disabled={busy}
131
+ onChange={() => setSelected((list) => toggle(list, row.id))} />
132
+ <span>
133
+ <span style={{ display: "block", fontWeight: 600 }}>{row.title}</span>
134
+ <span style={{ display: "block", color: "var(--lp-ink-2, inherit)" }}>
135
+ {[row.author, row.network].filter(Boolean).join(" · ")}
136
+ {row.extracted ? "" : " · structure not extracted yet"}
137
+ </span>
138
+ </span>
139
+ </label>
140
+ </li>)}
141
+ </ul>}
142
+ <label htmlFor={topicId} style={{ display: "block", marginTop: 14, fontWeight: 600 }}>Topic</label>
143
+ <input id={topicId} className="cg-input" type="text" maxLength={200} value={topic} disabled={busy}
144
+ data-overlay-autofocus="" placeholder="One line: what the post is about"
145
+ style={{ width: "100%", boxSizing: "border-box" }} onChange={(event) => setTopic(event.target.value)} />
146
+ <fieldset style={{ border: 0, padding: 0, margin: "14px 0 0" }}>
147
+ <legend style={{ fontWeight: 600 }}>Channels</legend>
148
+ <div style={{ display: "flex", flexWrap: "wrap", gap: 10 }}>
149
+ {channels.map((channel) => <label key={channel} style={{ display: "flex", gap: 6, alignItems: "center" }}>
150
+ <input type="checkbox" checked={chosen.includes(channel)} disabled={busy}
151
+ onChange={() => setChosen((list) => toggle(list, channel))} />{channel}
152
+ </label>)}
153
+ </div>
154
+ </fieldset>
155
+ {chosen.length ? <ul style={{ margin: "8px 0 0", paddingLeft: 18 }} aria-label="Channel guidance">
156
+ {chosen.map((channel) => <li key={channel}>{advice[channel] || channel}</li>)}
157
+ </ul> : null}
158
+ {reason ? <p className="home-empty" data-draft-reason="">{reason}</p> : null}
159
+ {busy ? <p role="status" aria-live="polite">Drafting {listed(chosen)}…</p> : null}
160
+ {error ? <p className="shell-newdb-err" role="alert">{error}</p> : null}
161
+ {drafted.length ? <div data-drafted="" aria-live="polite">
162
+ <p><strong>{drafted.length === 1 ? "1 draft" : `${drafted.length} drafts`} added to Posts as Draft.</strong></p>
163
+ <ul style={{ paddingLeft: 18 }}>
164
+ {drafted.map((row) => <li key={row.channel}><strong>{row.channel}</strong>: {row.caption.slice(0, 160)}{row.caption.length > 160 ? "…" : ""}</li>)}
165
+ </ul>
166
+ </div> : null}
167
+ </div>
168
+ <div className="lp-dialog-actions">
169
+ <button type="button" className="lp-dialog-btn lp-dialog-btn-quiet" disabled={busy} onClick={dismiss}>Close</button>
170
+ <button type="button" className="lp-dialog-btn lp-dialog-btn-primary" disabled={busy || !!reason}
171
+ title={reason || undefined} onClick={() => void draft()}>{busy ? "Drafting…" : "Draft"}</button>
172
+ </div>
173
+ {allowance && !allowance.paused ? <p className="home-empty" data-draft-allowance=""
174
+ style={{ marginTop: 8, textAlign: "right" }}>
175
+ {allowance.used} of {allowance.limit} drafts used this month
176
+ </p> : null}
177
+ </div>
178
+ </BodyPortal>;
179
+ }
web/src/connectors/ConnectorModal.tsx CHANGED
@@ -890,6 +890,17 @@ const CONNECTOR_DETAIL_DEADLINE_MS = 20_000;
890
  // Closing the modal unmounts it; keep the last successful read for the next open.
891
  const connectorDetailCache = new Map<string, { detail: ConnectorDetail; at: number }>();
892
 
 
 
 
 
 
 
 
 
 
 
 
893
  // Shell.tsx::signOut emits SIGNED_OUT_EVENT; an unloaded module has no cache to clear.
894
  export function clearConnectorDetailCache(): void {
895
  connectorDetailCache.clear();
@@ -1120,9 +1131,7 @@ export default function ConnectorModal({
1120
  if (dead) throw new Error("closed");
1121
  if (timedOut) throw new Error(timeoutMessage);
1122
  if (!res.ok) {
1123
- throw new Error(
1124
- body?.error?.message || body?.detail?.error?.message || `The server answered ${res.status}.`
1125
- );
1126
  }
1127
  const page = parseConnectorDetail(body, connectorKey);
1128
  if (!page) {
@@ -1230,9 +1239,7 @@ export default function ConnectorModal({
1230
  | null;
1231
  if (controller.signal.aborted) return;
1232
  if (!res.ok) {
1233
- throw new Error(
1234
- body?.error?.message || body?.detail?.error?.message || `The server answered ${res.status}.`
1235
- );
1236
  }
1237
  // The same reader, and the same selected-key guard, as the inline graph on a full read.
1238
  setGraphRead({ reads: forReads, graph: parseRelationshipGraph(body, connectorKey) });
 
890
  // Closing the modal unmounts it; keep the last successful read for the next open.
891
  const connectorDetailCache = new Map<string, { detail: ConnectorDetail; at: number }>();
892
 
893
+ // S67-T31: a refused read shows the server's own plain cause, or this component's sentence when
894
+ // the server sent none (a bare 500 has no JSON body). A status code never reaches the screen:
895
+ // "The server answered 500." was the owner's whole report, and it told him nothing he could act on.
896
+ function plainReadFailure(
897
+ body: { error?: { message?: string }; detail?: { error?: { message?: string } } } | null,
898
+ fallback: string,
899
+ ): string {
900
+ const said = (body?.error?.message || body?.detail?.error?.message || "").trim();
901
+ return said || fallback;
902
+ }
903
+
904
  // Shell.tsx::signOut emits SIGNED_OUT_EVENT; an unloaded module has no cache to clear.
905
  export function clearConnectorDetailCache(): void {
906
  connectorDetailCache.clear();
 
1131
  if (dead) throw new Error("closed");
1132
  if (timedOut) throw new Error(timeoutMessage);
1133
  if (!res.ok) {
1134
+ throw new Error(plainReadFailure(body, `The details for ${row.label} could not be read.`));
 
 
1135
  }
1136
  const page = parseConnectorDetail(body, connectorKey);
1137
  if (!page) {
 
1239
  | null;
1240
  if (controller.signal.aborted) return;
1241
  if (!res.ok) {
1242
+ throw new Error(plainReadFailure(body, "The relationships for this connection could not be read."));
 
 
1243
  }
1244
  // The same reader, and the same selected-key guard, as the inline graph on a full read.
1245
  setGraphRead({ reads: forReads, graph: parseRelationshipGraph(body, connectorKey) });
web/src/connectors/ConnectorsPage.tsx CHANGED
@@ -67,6 +67,15 @@ import {
67
  type OdooSchema,
68
  type OdooStatus,
69
  } from "../automation/automationApi";
 
 
 
 
 
 
 
 
 
70
  import "../styles/wave45/agent-operator.css";
71
  // ⭐ W49-T12 — the card's own open control and the relationship canvas rules live here now. The
72
  // `CONNECTOR_GRAPH_CSS` string this file used to inject through `<style>` is DELETED: a rules
@@ -699,6 +708,25 @@ export default function ConnectorsPage({
699
  load.phase === "ready" &&
700
  load.rows.some((row) => row.action === AMAZON_REVIEWS_ACTION);
701
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
702
  /**
703
  * ⛔⛔ THE ADMIN ANSWER, AND IT IS KEPT OUT OF `load` ON PURPOSE. Folding a failed meta read
704
  * into the page's load state would turn a missing Monid key, or a 401 on one free endpoint,
@@ -842,6 +870,7 @@ export default function ConnectorsPage({
842
  onKeychain={onKeychain}
843
  onOpen={() => setOpenKey(row.key)}
844
  onPullReviews={pullHandler(row)}
 
845
  />
846
  ))}
847
  </div>
@@ -860,6 +889,7 @@ export default function ConnectorsPage({
860
  onKeychain={onKeychain}
861
  onOpen={() => setOpenKey(row.key)}
862
  onPullReviews={pullHandler(row)}
 
863
  />
864
  ))}
865
  </div>
@@ -972,8 +1002,13 @@ export function OdooSyncStatus({ onOpenDatabases }: { onOpenDatabases?: () => vo
972
  key: string; label: string; health: DatabaseSyncHealth;
973
  }>>([]);
974
  const [problem, setProblem] = useState("");
 
 
975
  useEffect(() => {
976
  const controller = new AbortController();
 
 
 
977
  const healthRead = fetch(`${API_V1}/connectors/odoo/detail`, {
978
  credentials: CREDENTIALS, signal: controller.signal,
979
  }).then(async (response) => {
@@ -1006,10 +1041,17 @@ export function OdooSyncStatus({ onOpenDatabases }: { onOpenDatabases?: () => vo
1006
  return (
1007
  <section className="w45-contract-card" aria-labelledby="odoo-sync-heading">
1008
  <h4 id="odoo-sync-heading">Sync</h4>
 
1009
  <dl className="voice-agent-details">
1010
  <div><dt>Schedule</dt><dd>{status.schedule || "Not scheduled"}</dd></div>
1011
  <div><dt>Health</dt><dd>{status.health}</dd></div>
1012
  <div><dt>Last run</dt><dd>{status.lastRun || "No run reported"}</dd></div>
 
 
 
 
 
 
1013
  <div><dt>Errors</dt><dd>{status.errors.length ? status.errors.map(String).join(", ") : "None reported"}</dd></div>
1014
  </dl>
1015
  <h4>Databases</h4>
@@ -1187,9 +1229,17 @@ export function ConnectorCard({
1187
  onKeychain,
1188
  onOpen,
1189
  onPullReviews,
 
1190
  }: {
1191
  row: ConnectorRow;
1192
  onKeychain: () => void;
 
 
 
 
 
 
 
1193
  /**
1194
  * ⭐⭐ W49-T12 · R26 — OPEN THE CONNECTOR MODAL. Optional for the same reason `onSelectGraph`
1195
  * was: the static proof sheets (`_conn_shot.tsx` and friends) paint this card without a door,
@@ -1318,6 +1368,7 @@ export function ConnectorCard({
1318
  {connected && row.connectedAs ? (
1319
  <p className="conn-card-meta">Connected as {row.connectedAs}</p>
1320
  ) : null}
 
1321
  {/* ⭐ WAVE 32 · R4 — whose connection this is, said on the card where the fact
1322
  matters. Empty for everything else, so nothing new appears on the cards a
1323
  workspace has not connected. */}
 
67
  type OdooSchema,
68
  type OdooStatus,
69
  } from "../automation/automationApi";
70
+ // ⭐ S67-T20 / C4: the freshness READER and its words, never the settings panel. The tombstone
71
+ // above still holds: `OdooConfigPanel` stays out of this file.
72
+ import {
73
+ freshnessWarnings,
74
+ getOdooFreshness,
75
+ OdooFreshnessNote,
76
+ syncDate,
77
+ type OdooFreshness,
78
+ } from "./OdooConfig";
79
  import "../styles/wave45/agent-operator.css";
80
  // ⭐ W49-T12 — the card's own open control and the relationship canvas rules live here now. The
81
  // `CONNECTOR_GRAPH_CSS` string this file used to inject through `<style>` is DELETED: a rules
 
708
  load.phase === "ready" &&
709
  load.rows.some((row) => row.action === AMAZON_REVIEWS_ACTION);
710
 
711
+ /**
712
+ * ⭐⭐ S67-T20 / C4 — THE ODOO CARD SAYS WHEN ITS DATA IS OLD. Staging's sync was dead for three
713
+ * weeks and the card looked exactly like a healthy one. Read only when a connected Odoo card is
714
+ * on the page, and kept out of `load` for the reason the admin answer below is: a warning that
715
+ * cannot be read must never turn the directory into an error banner.
716
+ */
717
+ const hasOdooCard =
718
+ load.phase === "ready" &&
719
+ load.rows.some((row) => row.key === "odoo" && row.state === "connected");
720
+ const [odooWarnings, setOdooWarnings] = useState<string[]>([]);
721
+ useEffect(() => {
722
+ if (!hasOdooCard) return;
723
+ const controller = new AbortController();
724
+ void getOdooFreshness(controller.signal).then((freshness) => {
725
+ if (!controller.signal.aborted) setOdooWarnings(freshnessWarnings(freshness));
726
+ });
727
+ return () => controller.abort();
728
+ }, [hasOdooCard]);
729
+
730
  /**
731
  * ⛔⛔ THE ADMIN ANSWER, AND IT IS KEPT OUT OF `load` ON PURPOSE. Folding a failed meta read
732
  * into the page's load state would turn a missing Monid key, or a 401 on one free endpoint,
 
870
  onKeychain={onKeychain}
871
  onOpen={() => setOpenKey(row.key)}
872
  onPullReviews={pullHandler(row)}
873
+ syncWarnings={row.key === "odoo" ? odooWarnings : undefined}
874
  />
875
  ))}
876
  </div>
 
889
  onKeychain={onKeychain}
890
  onOpen={() => setOpenKey(row.key)}
891
  onPullReviews={pullHandler(row)}
892
+ syncWarnings={row.key === "odoo" ? odooWarnings : undefined}
893
  />
894
  ))}
895
  </div>
 
1002
  key: string; label: string; health: DatabaseSyncHealth;
1003
  }>>([]);
1004
  const [problem, setProblem] = useState("");
1005
+ // S67-T20 / C4: read beside the status, never blocking it; `null` shows no warning.
1006
+ const [freshness, setFreshness] = useState<OdooFreshness | null>(null);
1007
  useEffect(() => {
1008
  const controller = new AbortController();
1009
+ void getOdooFreshness(controller.signal).then((next) => {
1010
+ if (!controller.signal.aborted) setFreshness(next);
1011
+ });
1012
  const healthRead = fetch(`${API_V1}/connectors/odoo/detail`, {
1013
  credentials: CREDENTIALS, signal: controller.signal,
1014
  }).then(async (response) => {
 
1041
  return (
1042
  <section className="w45-contract-card" aria-labelledby="odoo-sync-heading">
1043
  <h4 id="odoo-sync-heading">Sync</h4>
1044
+ <OdooFreshnessNote lines={freshnessWarnings(freshness)} />
1045
  <dl className="voice-agent-details">
1046
  <div><dt>Schedule</dt><dd>{status.schedule || "Not scheduled"}</dd></div>
1047
  <div><dt>Health</dt><dd>{status.health}</dd></div>
1048
  <div><dt>Last run</dt><dd>{status.lastRun || "No run reported"}</dd></div>
1049
+ {freshness ? (
1050
+ <div>
1051
+ <dt>Last good sync</dt>
1052
+ <dd>{freshness.lastGoodSyncAt ? syncDate(freshness.lastGoodSyncAt) : "None recorded"}</dd>
1053
+ </div>
1054
+ ) : null}
1055
  <div><dt>Errors</dt><dd>{status.errors.length ? status.errors.map(String).join(", ") : "None reported"}</dd></div>
1056
  </dl>
1057
  <h4>Databases</h4>
 
1229
  onKeychain,
1230
  onOpen,
1231
  onPullReviews,
1232
+ syncWarnings,
1233
  }: {
1234
  row: ConnectorRow;
1235
  onKeychain: () => void;
1236
+ /**
1237
+ * ⭐⭐ S67-T20 / C4 — THIS CONNECTOR'S SYNC WARNINGS, already worded by `freshnessWarnings`
1238
+ * ("Odoo data is stale: last synced ...", the last run's failure). Read-only text, never a
1239
+ * control: the card keeps its one Settings door. Empty or absent renders nothing, which is how
1240
+ * a fresh sync clears it.
1241
+ */
1242
+ syncWarnings?: string[];
1243
  /**
1244
  * ⭐⭐ W49-T12 · R26 — OPEN THE CONNECTOR MODAL. Optional for the same reason `onSelectGraph`
1245
  * was: the static proof sheets (`_conn_shot.tsx` and friends) paint this card without a door,
 
1368
  {connected && row.connectedAs ? (
1369
  <p className="conn-card-meta">Connected as {row.connectedAs}</p>
1370
  ) : null}
1371
+ {connected ? <OdooFreshnessNote lines={syncWarnings ?? []} /> : null}
1372
  {/* ⭐ WAVE 32 · R4 — whose connection this is, said on the card where the fact
1373
  matters. Empty for everything else, so nothing new appears on the cards a
1374
  workspace has not connected. */}
web/src/connectors/OdooConfig.tsx CHANGED
@@ -68,6 +68,88 @@ export interface OdooConfig {
68
  notes?: string[];
69
  }
70
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
71
  /**
72
  * The cadence words, in the two places a person reads them. ⚠ The MAP is presentation; the
73
  * OPTIONS come from the server (`syncOptions`), so a preset we have no phrase for still renders
 
68
  notes?: string[];
69
  }
70
 
71
+ /**
72
+ * ⭐⭐ S67-T20 / C4 — THE SYNC FRESHNESS, exactly as `GET /connectors/odoo/freshness` sends it.
73
+ *
74
+ * Staging's Odoo sync sat dead for three weeks and nothing on screen said so: the Daily Sales
75
+ * YTD simply stopped moving. `stale` is the server's reading (the last good sync is older than the
76
+ * cadence plus two hours, 26 hours for a daily sync) and `failure` is the last run's own reason;
77
+ * this file only words them. Every field is optional: an older server says nothing, and nothing
78
+ * is shown.
79
+ */
80
+ export interface OdooFreshness {
81
+ stale?: boolean;
82
+ lastGoodSyncAt?: string | null;
83
+ schedule?: string;
84
+ staleAfterSeconds?: number | null;
85
+ lastRunAt?: string | null;
86
+ phase?: string;
87
+ failure?: { code?: string; message?: string; at?: string | null } | null;
88
+ }
89
+
90
+ /** A sync time the way a person reads it: "Sep 27, 2026, 6:25 AM". An unreadable value is shown
91
+ * as sent rather than as nothing. */
92
+ export function syncDate(iso: string): string {
93
+ const at = new Date(iso);
94
+ if (Number.isNaN(at.getTime())) return iso;
95
+ return at.toLocaleString("en-US", {
96
+ month: "short", day: "numeric", year: "numeric", hour: "numeric", minute: "2-digit",
97
+ });
98
+ }
99
+
100
+ /** The warning lines for a freshness reading, PURE: none when the data is fresh and the last run
101
+ * did not fail, which is the whole of "a fresh sync clears it". */
102
+ export function freshnessWarnings(f: OdooFreshness | null | undefined): string[] {
103
+ if (!f) return [];
104
+ const lines: string[] = [];
105
+ if (f.stale) {
106
+ lines.push(
107
+ f.lastGoodSyncAt
108
+ ? `Odoo data is stale: last synced ${syncDate(f.lastGoodSyncAt)}`
109
+ : "Odoo data is stale: no sync has finished yet"
110
+ );
111
+ }
112
+ const reason = (f.failure?.message ?? "").trim();
113
+ if (reason) lines.push(`The last Odoo sync failed. ${reason}`);
114
+ return lines;
115
+ }
116
+
117
+ /** One read of the freshness route. Any failure is `null`, never a thrown error: a warning that
118
+ * cannot be read must not take the card or the Sync section down with it. */
119
+ export async function getOdooFreshness(signal?: AbortSignal): Promise<OdooFreshness | null> {
120
+ try {
121
+ const res = await fetch(`${API_V1}/connectors/odoo/freshness`, {
122
+ credentials: CREDENTIALS,
123
+ signal,
124
+ });
125
+ if (!res.ok) return null;
126
+ const body: unknown = await res.json().catch(() => null);
127
+ return body && typeof body === "object" ? (body as OdooFreshness) : null;
128
+ } catch {
129
+ return null;
130
+ }
131
+ }
132
+
133
+ /** The warning box, in the amber the directory's own "some cards are missing" note uses: the
134
+ * data is old or a run failed, nothing the reader did is wrong. Renders nothing when fresh. */
135
+ export function OdooFreshnessNote({ lines }: { lines: string[] }) {
136
+ if (!lines.length) return null;
137
+ // One line reads as a sentence; two use the list rule `.conn-note.is-warn ul` already carries.
138
+ return (
139
+ <div className="conn-note is-warn odoo-freshness" role="status">
140
+ {lines.length === 1 ? (
141
+ lines[0]
142
+ ) : (
143
+ <ul>
144
+ {lines.map((line) => (
145
+ <li key={line}>{line}</li>
146
+ ))}
147
+ </ul>
148
+ )}
149
+ </div>
150
+ );
151
+ }
152
+
153
  /**
154
  * The cadence words, in the two places a person reads them. ⚠ The MAP is presentation; the
155
  * OPTIONS come from the server (`syncOptions`), so a preset we have no phrase for still renders
web/src/customer-grid/CustomerGrid.tsx CHANGED
@@ -87,6 +87,7 @@ import { SUMMARY_BAR_PX, SummaryBar } from "./summary/SummaryBar";
87
  import type { CohortSets } from "./useVisibleRows";
88
  import type { MeasureSets } from "./useVisibleRows";
89
  import { useGetCellContent } from "./useGetCellContent";
 
90
  import { useGridSelection } from "./useGridSelection";
91
  import Toolbar from "./Toolbar";
92
  import { DatePicker } from "./DatePicker";
@@ -355,6 +356,10 @@ const PULSE_MAX_TICKS = Math.round(60_000 / PULSE_MS);
355
  /** Referentially stable, so the fallback does not change `getCellContent`'s identity per render
356
  * and repaint the canvas forever. */
357
  const NO_PENDING_KEYS: ReadonlySet<string> = new Set<string>();
 
 
 
 
358
 
359
  /**
360
  * I2 — measure a cell's text in GLIDE'S OWN font, so "is this cut off?" is a fact rather than
@@ -656,8 +661,54 @@ function pivotCellText(value: string | number | null | undefined): string {
656
  return value === null || value === undefined ? "" : String(value);
657
  }
658
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
659
  function normalizeConfig(config: Partial<ViewConfig> | undefined, fields: Field[]): ViewConfig {
660
  const base = defaultViewConfig(fields);
 
 
 
 
 
661
  return {
662
  ...base,
663
  ...config,
@@ -666,11 +717,8 @@ function normalizeConfig(config: Partial<ViewConfig> | undefined, fields: Field[
666
  // other than an explicit "or" normalizes to "and", so old views are unchanged.
667
  filterConj: config?.filterConj === "or" ? "or" : "and",
668
  sorts: Array.isArray(config?.sorts) ? config.sorts : [],
669
- order: Array.isArray(config?.order) && config.order.length ? config.order : base.order,
670
- visible:
671
- Array.isArray(config?.visible) && config.visible.length
672
- ? config.visible
673
- : base.visible,
674
  widths: config?.widths && typeof config.widths === "object" ? config.widths : {},
675
  memberPids: Array.isArray(config?.memberPids) ? config.memberPids : [],
676
  // Wave-6 items 10/11. Both normalize junk to ABSENT (grid / 1 frozen), so
@@ -4378,8 +4426,10 @@ function CustomerGridSurface({
4378
  }
4379
  return m;
4380
  }, [serverAggs]);
 
 
4381
  const [groupPages, setGroupPages] = useState<
4382
- ReadonlyMap<string, { offset: number; rows: Row[]; pending: boolean }>
4383
  >(() => new Map());
4384
  const groupPageSeq = useRef(0);
4385
  useEffect(() => {
@@ -4395,11 +4445,15 @@ function CustomerGridSurface({
4395
  next.set(key, { offset, rows: prev.get(key)?.rows ?? [], pending: true });
4396
  return next;
4397
  });
 
 
 
 
4398
  void fetchTableWindow(scope, {
4399
  ...windowRequest(offset),
4400
  related: relatedPin,
4401
  group: { by, key: groupKeyRaw.get(key) ?? null },
4402
- }).then((page) => page, () => null).then((page) => {
4403
  // HOTFIX 2026-09-28: a REJECTED fetch settles too. Without the rejection handler above a
4404
  // network failure left `pending` true forever and the group's pager stayed disabled.
4405
  if (seq !== groupPageSeq.current) return;
@@ -4407,7 +4461,11 @@ function CustomerGridSurface({
4407
  const cur = prev.get(key);
4408
  if (cur && cur.offset !== offset) return prev;
4409
  const next = new Map(prev);
4410
- next.set(key, { offset, rows: page?.rows ?? cur?.rows ?? [], pending: false });
 
 
 
 
4411
  return next;
4412
  });
4413
  });
@@ -4419,15 +4477,26 @@ function CustomerGridSurface({
4419
  }
4420
  }, [serverWindowed, config.groupBy, groupSummaryOn, expanded, groupKeyRaw, groupPages,
4421
  loadGroupPage]);
4422
- const serverGroupRows = useMemo(() => {
 
 
 
 
 
 
 
 
 
4423
  if (!serverWindowed || !config.groupBy) return null;
4424
  const groups = serverAggs?.groups;
4425
  if (!groups || !groups.length) return null;
4426
  const heads = serverGroupHeaders(
4427
  groups, fields, summaryMap, serverAggs.aggregates, serverAggs.totalRows
4428
  );
4429
- if (groupSummaryOn) return heads;
 
4430
  const out: VisibleRow[] = [];
 
4431
  for (const h of heads) {
4432
  if (h.kind !== "group-header") continue;
4433
  const raw = h.groupKey as unknown as string | number | null;
@@ -4436,7 +4505,21 @@ function CustomerGridSurface({
4436
  out.push({ ...h, groupKey: key, collapsed: !open });
4437
  if (!open) continue;
4438
  const page = groupPages.get(key);
4439
- for (const record of page?.rows ?? []) out.push({ kind: "data", record });
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4440
  out.push({
4441
  kind: "group-footer",
4442
  groupKey: key,
@@ -4448,9 +4531,12 @@ function CustomerGridSurface({
4448
  : {}),
4449
  });
4450
  }
4451
- return out;
4452
  }, [serverWindowed, config.groupBy, serverAggs, fields, summaryMap, groupSummaryOn, expanded,
4453
  groupPages, pageSize]);
 
 
 
4454
  /* HOTFIX 2026-09-24 — a WHOLE-BOOK table's open groups page too, one offset per group. */
4455
  const [clientGroupOffsets, setClientGroupOffsets] = useState<ReadonlyMap<string, number>>(
4456
  () => new Map());
@@ -4577,28 +4663,61 @@ function CustomerGridSurface({
4577
  { key: string; top: number; left: number; height: number;
4578
  page: { offset: number; total: number; size: number; pending?: boolean } }[]
4579
  >([]);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4580
  useLayoutEffect(() => {
 
 
 
 
 
 
 
 
 
 
 
 
4581
  const box = gridBoxRef.current?.getBoundingClientRect();
4582
  const grid = gridRef.current;
4583
  if (!box || !grid || !config.groupBy) {
4584
- setGroupPagers((prev) => (prev.length ? [] : prev));
4585
  return;
4586
  }
4587
- const first = visibleRange ? Math.max(0, visibleRange.y - 1) : 0;
4588
- const last = visibleRange ? visibleRange.y + visibleRange.height + 1 : displayRows.length;
4589
  const next: typeof groupPagers = [];
 
4590
  for (let i = first; i < Math.min(last, displayRows.length); i++) {
4591
  const vr = displayRows[i];
4592
- if (vr?.kind !== "group-footer" || !vr.page) continue;
 
 
4593
  const b = grid.getBounds(0, i);
4594
  if (!b) continue;
4595
  const top = b.y - box.top;
4596
  if (top < HEADER_PX || top + b.height > box.height) continue;
4597
- next.push({ key: vr.groupKey, top, left: Math.max(0, b.x - box.left), height: b.height,
4598
- page: vr.page });
 
 
4599
  }
4600
- setGroupPagers((prev) => (JSON.stringify(prev) === JSON.stringify(next) ? prev : next));
4601
- }, [displayRows, visibleRange, canvasX, config.groupBy]);
4602
  /* ⭐⭐ W50-T02 — `displayPidToIndex` IS BACK, and the reason is narrower than the one W50-T01
4603
  retired it for. Selection, detail navigation and the new-row cursor are all POSITIONAL
4604
  against what is on screen, and a folded group shifts every row under it. When nothing is
@@ -4700,7 +4819,8 @@ function CustomerGridSurface({
4700
  const [pendingGaveUp, setPendingGaveUp] = useState(false);
4701
  useEffect(() => {
4702
  setPendingGaveUp(false);
4703
- if (pendingMeasureKeys.size === 0) return;
 
4704
  let n = 0;
4705
  const id = window.setInterval(() => {
4706
  n += 1;
@@ -4712,7 +4832,7 @@ function CustomerGridSurface({
4712
  setPulse((p) => p + 1);
4713
  }, PULSE_MS);
4714
  return () => window.clearInterval(id);
4715
- }, [pendingMeasureKeys]);
4716
  const activePendingKeys = pendingGaveUp ? NO_PENDING_KEYS : pendingMeasureKeys;
4717
  const rawGetCellContent = useGetCellContent(
4718
  displayRows,
@@ -4725,7 +4845,8 @@ function CustomerGridSurface({
4725
  groupLabelSpace,
4726
  measureGroupText,
4727
  activePendingKeys,
4728
- pulse
 
4729
  );
4730
  /**
4731
  * ⭐⭐ WAVE 50 · W50-T05 / OWNER RULING R4 — **THE DENOMINATOR EVERY CELL SHARE DIVIDES BY, AND
@@ -6442,6 +6563,23 @@ function CustomerGridSurface({
6442
  return;
6443
  }
6444
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
6445
  // ⭐ Wave-23 C7 — a JSON cell opens the big viewer. It is the ONLY door: the cell carries
6446
  // `allowOverlay:false`, because glide's overlay is a one-line box and one keystroke in the
6447
  // wrong place inside a 32 KB document turns a well-formed payload into an unparseable one,
@@ -11941,6 +12079,22 @@ function CustomerGridSurface({
11941
  </button>
11942
  </div>
11943
  ))}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
11944
  {/* ⭐⭐ W50-T03 (instruction 1, R2) — THE SUMMARY BAR, INSIDE THE BOX AND PINNED TO ITS
11945
  BOTTOM EDGE. Last child of `.cg-grid-box` so it paints over the void rectangles
11946
  rather than under them, and inside it rather than beside it so it cannot drift away
 
87
  import type { CohortSets } from "./useVisibleRows";
88
  import type { MeasureSets } from "./useVisibleRows";
89
  import { useGetCellContent } from "./useGetCellContent";
90
+ import type { GroupRowPlaceholder } from "./useGetCellContent";
91
  import { useGridSelection } from "./useGridSelection";
92
  import Toolbar from "./Toolbar";
93
  import { DatePicker } from "./DatePicker";
 
356
  /** Referentially stable, so the fallback does not change `getCellContent`'s identity per render
357
  * and repaint the canvas forever. */
358
  const NO_PENDING_KEYS: ReadonlySet<string> = new Set<string>();
359
+ /** S67-T27 — likewise for the open groups' stand-in rows, when nothing is grouped on the server. */
360
+ const NO_GROUP_PLACEHOLDERS: ReadonlyMap<VisibleRow, GroupRowPlaceholder> = new Map();
361
+ /** S67-T27 (R38) — the sentence a group whose page failed shows in place of its records. */
362
+ const GROUP_PAGE_FAILED = "These records could not be loaded.";
363
 
364
  /**
365
  * I2 — measure a cell's text in GLIDE'S OWN font, so "is this cut off?" is a fact rather than
 
661
  return value === null || value === undefined ? "" : String(value);
662
  }
663
 
664
+ /**
665
+ * S67-T30 — a SERVER LOOKUP field (one carrying `opens.via`: an Amazon "Parent ASIN", "SKU" or
666
+ * "ASIN") that a saved view has never seen joins that view beside its source column. Only such a
667
+ * field, and only when it is ABSENT from the saved `order`: a lookup already in `order` stays
668
+ * exactly as saved, so a person who hid it keeps it hidden. It lands right after the nearest
669
+ * preceding field (declaration order) the saved `order` holds, and joins a saved non-empty
670
+ * `visible` when the database shows it by default (`defaultVisible`, i.e. `defaultViewConfig`'s
671
+ * own answer). Every other field, and every view without a saved `order`, is untouched: seeded
672
+ * views carry curated partial orders that must not start showing other fields.
673
+ */
674
+ export function placeUnseenLookups(
675
+ order: string[],
676
+ visible: string[] | null,
677
+ fields: Field[],
678
+ defaultVisible: ReadonlySet<string>
679
+ ): { order: string[]; visible: string[] | null } {
680
+ const isLookup = (field: Field) =>
681
+ typeof (field as Field & { opens?: { via?: unknown } }).opens?.via === "string";
682
+ if (!fields.some((field) => isLookup(field) && !order.includes(field.key))) {
683
+ return { order, visible };
684
+ }
685
+ const nextOrder = [...order];
686
+ const nextVisible = visible ? [...visible] : null;
687
+ let anchor: string | null = null;
688
+ for (const field of fields) {
689
+ if (nextOrder.includes(field.key)) {
690
+ anchor = field.key;
691
+ continue;
692
+ }
693
+ if (!isLookup(field)) continue;
694
+ // No preceding field in the saved order: append, where `reconcileOrder` would put it today.
695
+ const at = anchor === null ? nextOrder.length : nextOrder.indexOf(anchor) + 1;
696
+ nextOrder.splice(at, 0, field.key);
697
+ if (nextVisible && defaultVisible.has(field.key) && !nextVisible.includes(field.key)) {
698
+ nextVisible.push(field.key);
699
+ }
700
+ anchor = field.key;
701
+ }
702
+ return { order: nextOrder, visible: nextVisible };
703
+ }
704
+
705
  function normalizeConfig(config: Partial<ViewConfig> | undefined, fields: Field[]): ViewConfig {
706
  const base = defaultViewConfig(fields);
707
+ const savedOrder = Array.isArray(config?.order) && config.order.length ? config.order : null;
708
+ const savedVisible = Array.isArray(config?.visible) && config.visible.length ? config.visible : null;
709
+ const placed = savedOrder
710
+ ? placeUnseenLookups(savedOrder, savedVisible, fields, new Set(base.visible))
711
+ : null;
712
  return {
713
  ...base,
714
  ...config,
 
717
  // other than an explicit "or" normalizes to "and", so old views are unchanged.
718
  filterConj: config?.filterConj === "or" ? "or" : "and",
719
  sorts: Array.isArray(config?.sorts) ? config.sorts : [],
720
+ order: placed ? placed.order : base.order,
721
+ visible: placed?.visible ?? savedVisible ?? base.visible,
 
 
 
722
  widths: config?.widths && typeof config.widths === "object" ? config.widths : {},
723
  memberPids: Array.isArray(config?.memberPids) ? config.memberPids : [],
724
  // Wave-6 items 10/11. Both normalize junk to ABSENT (grid / 1 frozen), so
 
4426
  }
4427
  return m;
4428
  }, [serverAggs]);
4429
+ /* S67-T27 (R38): `failed` is the page that did not arrive. It used to settle as `rows: []`,
4430
+ which painted a failure as an empty group; now the group shows the sentence and "Try again". */
4431
  const [groupPages, setGroupPages] = useState<
4432
+ ReadonlyMap<string, { offset: number; rows: Row[]; pending: boolean; failed?: string }>
4433
  >(() => new Map());
4434
  const groupPageSeq = useRef(0);
4435
  useEffect(() => {
 
4445
  next.set(key, { offset, rows: prev.get(key)?.rows ?? [], pending: true });
4446
  return next;
4447
  });
4448
+ /* S67-T27: the group's OWN failure handler. The default one raises the page-wide data
4449
+ error, which replaced the whole grid with "Cannot reach the server." for one group's page;
4450
+ the failure belongs to the group that asked, so its cause stays with that group. */
4451
+ let failure = "";
4452
  void fetchTableWindow(scope, {
4453
  ...windowRequest(offset),
4454
  related: relatedPin,
4455
  group: { by, key: groupKeyRaw.get(key) ?? null },
4456
+ }, (reason) => { failure = reason; }).then((page) => page, () => null).then((page) => {
4457
  // HOTFIX 2026-09-28: a REJECTED fetch settles too. Without the rejection handler above a
4458
  // network failure left `pending` true forever and the group's pager stayed disabled.
4459
  if (seq !== groupPageSeq.current) return;
 
4461
  const cur = prev.get(key);
4462
  if (cur && cur.offset !== offset) return prev;
4463
  const next = new Map(prev);
4464
+ // S67-T27: `fetchTableWindow` answers null for every failure (a refusal, an unreadable
4465
+ // payload, no network), never an empty page, so null is `failed` and never `rows: []`.
4466
+ next.set(key, page
4467
+ ? { offset, rows: page.rows, pending: false }
4468
+ : { offset, rows: [], pending: false, failed: failure || GROUP_PAGE_FAILED });
4469
  return next;
4470
  });
4471
  });
 
4477
  }
4478
  }, [serverWindowed, config.groupBy, groupSummaryOn, expanded, groupKeyRaw, groupPages,
4479
  loadGroupPage]);
4480
+ /* ⭐ S67-T27 (R38) — AN OPEN GROUP IS NEVER EMPTY WHILE ITS PAGE IS NOT IN HAND. From the
4481
+ render that opens it (the page is not even requested yet) until the page lands, the group
4482
+ paints one skeleton row per record that page will hold, min(count left, page size), so the
4483
+ click answers in its own frame and the rows replace the skeletons in place; a page that
4484
+ failed paints one row carrying "These records could not be loaded." and "Try again".
4485
+ ⛔ The stand-ins are `group-footer`-shaped on purpose, for `TOTAL_GROUP_KEY`'s reason in
4486
+ `types.ts`: every consumer of the painted list already treats a footer as structure
4487
+ (selection, hover, the drawer, keyboard moves and the list view skip it), where a fake
4488
+ `data` row would reach each of them as a record. `placeholders` names them by identity. */
4489
+ const serverGroupView = useMemo(() => {
4490
  if (!serverWindowed || !config.groupBy) return null;
4491
  const groups = serverAggs?.groups;
4492
  if (!groups || !groups.length) return null;
4493
  const heads = serverGroupHeaders(
4494
  groups, fields, summaryMap, serverAggs.aggregates, serverAggs.totalRows
4495
  );
4496
+ const placeholders = new Map<VisibleRow, GroupRowPlaceholder>();
4497
+ if (groupSummaryOn) return { rows: heads, placeholders, loading: false };
4498
  const out: VisibleRow[] = [];
4499
+ let loading = false;
4500
  for (const h of heads) {
4501
  if (h.kind !== "group-header") continue;
4502
  const raw = h.groupKey as unknown as string | number | null;
 
4505
  out.push({ ...h, groupKey: key, collapsed: !open });
4506
  if (!open) continue;
4507
  const page = groupPages.get(key);
4508
+ if (!page || page.pending) {
4509
+ const stand = Math.max(0, Math.min(h.count - (page?.offset ?? 0), pageSize));
4510
+ for (let i = 0; i < stand; i += 1) {
4511
+ const skeleton: VisibleRow = { kind: "group-footer", groupKey: key, aggs: {} };
4512
+ placeholders.set(skeleton, "loading");
4513
+ out.push(skeleton);
4514
+ }
4515
+ loading ||= stand > 0;
4516
+ } else if (page.failed) {
4517
+ const failedRow: VisibleRow = { kind: "group-footer", groupKey: key, aggs: {} };
4518
+ placeholders.set(failedRow, "failed");
4519
+ out.push(failedRow);
4520
+ } else {
4521
+ for (const record of page.rows) out.push({ kind: "data", record });
4522
+ }
4523
  out.push({
4524
  kind: "group-footer",
4525
  groupKey: key,
 
4531
  : {}),
4532
  });
4533
  }
4534
+ return { rows: out, placeholders, loading };
4535
  }, [serverWindowed, config.groupBy, serverAggs, fields, summaryMap, groupSummaryOn, expanded,
4536
  groupPages, pageSize]);
4537
+ const serverGroupRows = serverGroupView?.rows ?? null;
4538
+ const groupPlaceholders = serverGroupView?.placeholders ?? NO_GROUP_PLACEHOLDERS;
4539
+ const groupPageLoading = serverGroupView?.loading ?? false;
4540
  /* HOTFIX 2026-09-24 — a WHOLE-BOOK table's open groups page too, one offset per group. */
4541
  const [clientGroupOffsets, setClientGroupOffsets] = useState<ReadonlyMap<string, number>>(
4542
  () => new Map());
 
4663
  { key: string; top: number; left: number; height: number;
4664
  page: { offset: number; total: number; size: number; pending?: boolean } }[]
4665
  >([]);
4666
+ /* S67-T27 (R38) — a group whose page failed carries its sentence and "Try again" on the same
4667
+ kind of overlay, placed by the same method, over the stand-in row inside that group. */
4668
+ const [groupFailures, setGroupFailures] = useState<
4669
+ { key: string; top: number; left: number; height: number; cause: string }[]
4670
+ >([]);
4671
+ /* S67-T27 — ⛔ THIS EFFECT SETS STATE ONLY WHEN A PLACEMENT CHANGED, AND READS THE RANGE AS TWO
4672
+ NUMBERS. It used to call both setters with an updater on every run and depend on the
4673
+ `visibleRange` OBJECT. While a scroll-range update was still pending React re-applied it on
4674
+ each synchronous re-render, minting an equal but new object, so the effect re-ran, set state,
4675
+ re-rendered, and hit "Maximum update depth exceeded" (#185): measured on Try again, where the
4676
+ failed row, its overlay and 100 skeleton rows swap in one frame. The refs hold what was last
4677
+ placed, so an unchanged placement is no update at all. */
4678
+ const placedPagers = useRef("[]");
4679
+ const placedFailures = useRef("[]");
4680
+ const rangeY = visibleRange?.y ?? null;
4681
+ const rangeH = visibleRange?.height ?? null;
4682
  useLayoutEffect(() => {
4683
+ const place = (pagers: typeof groupPagers, failures: typeof groupFailures) => {
4684
+ const pagersKey = JSON.stringify(pagers);
4685
+ if (pagersKey !== placedPagers.current) {
4686
+ placedPagers.current = pagersKey;
4687
+ setGroupPagers(pagers);
4688
+ }
4689
+ const failuresKey = JSON.stringify(failures);
4690
+ if (failuresKey !== placedFailures.current) {
4691
+ placedFailures.current = failuresKey;
4692
+ setGroupFailures(failures);
4693
+ }
4694
+ };
4695
  const box = gridBoxRef.current?.getBoundingClientRect();
4696
  const grid = gridRef.current;
4697
  if (!box || !grid || !config.groupBy) {
4698
+ place([], []);
4699
  return;
4700
  }
4701
+ const first = rangeY !== null ? Math.max(0, rangeY - 1) : 0;
4702
+ const last = rangeY !== null && rangeH !== null ? rangeY + rangeH + 1 : displayRows.length;
4703
  const next: typeof groupPagers = [];
4704
+ const failures: typeof groupFailures = [];
4705
  for (let i = first; i < Math.min(last, displayRows.length); i++) {
4706
  const vr = displayRows[i];
4707
+ if (vr?.kind !== "group-footer") continue;
4708
+ const failed = groupPlaceholders.get(vr) === "failed";
4709
+ if (!failed && !vr.page) continue;
4710
  const b = grid.getBounds(0, i);
4711
  if (!b) continue;
4712
  const top = b.y - box.top;
4713
  if (top < HEADER_PX || top + b.height > box.height) continue;
4714
+ const left = Math.max(0, b.x - box.left);
4715
+ if (failed) failures.push({ key: vr.groupKey, top, left, height: b.height,
4716
+ cause: groupPages.get(vr.groupKey)?.failed ?? "" });
4717
+ else if (vr.page) next.push({ key: vr.groupKey, top, left, height: b.height, page: vr.page });
4718
  }
4719
+ place(next, failures);
4720
+ }, [displayRows, rangeY, rangeH, canvasX, config.groupBy, groupPlaceholders, groupPages]);
4721
  /* ⭐⭐ W50-T02 — `displayPidToIndex` IS BACK, and the reason is narrower than the one W50-T01
4722
  retired it for. Selection, detail navigation and the new-row cursor are all POSITIONAL
4723
  against what is on screen, and a folded group shifts every row under it. When nothing is
 
4819
  const [pendingGaveUp, setPendingGaveUp] = useState(false);
4820
  useEffect(() => {
4821
  setPendingGaveUp(false);
4822
+ // S67-T27: an open group's skeleton rows pulse on the same tick, for as long as one loads.
4823
+ if (pendingMeasureKeys.size === 0 && !groupPageLoading) return;
4824
  let n = 0;
4825
  const id = window.setInterval(() => {
4826
  n += 1;
 
4832
  setPulse((p) => p + 1);
4833
  }, PULSE_MS);
4834
  return () => window.clearInterval(id);
4835
+ }, [pendingMeasureKeys, groupPageLoading]);
4836
  const activePendingKeys = pendingGaveUp ? NO_PENDING_KEYS : pendingMeasureKeys;
4837
  const rawGetCellContent = useGetCellContent(
4838
  displayRows,
 
4845
  groupLabelSpace,
4846
  measureGroupText,
4847
  activePendingKeys,
4848
+ pulse,
4849
+ groupPlaceholders
4850
  );
4851
  /**
4852
  * ⭐⭐ WAVE 50 · W50-T05 / OWNER RULING R4 — **THE DENOMINATOR EVERY CELL SHARE DIVIDES BY, AND
 
6563
  return;
6564
  }
6565
  }
6566
+ // S67-T30 — a server-derived value (an Amazon "Parent ASIN", "SKU" or "ASIN") names the
6567
+ // grid's own link field it opens through (`opens.via`); a click opens exactly that link's
6568
+ // records, the listing. The value stays plain text so it groups, filters and sorts; the link
6569
+ // keeps its pids as before. A blank cell, or one whose link matched nothing, does nothing.
6570
+ const opensVia = (field as (Field & { opens?: { via?: unknown } }) | undefined)?.opens?.via;
6571
+ if (row.kind === "data" && field && typeof opensVia === "string") {
6572
+ const via = fieldByKey.get(opensVia);
6573
+ const value = String(row.record[field.key] ?? "").trim();
6574
+ const linked = String(row.record[opensVia] ?? "").trim();
6575
+ if (value && linked && via?.type === "link" && via.link?.table
6576
+ && isLinkableTarget(via.link.table)) {
6577
+ event.preventDefault();
6578
+ setActiveCell(cell[0], cell[1]);
6579
+ setLinkAt({ pid: row.record.pid, fieldKey: opensVia });
6580
+ return;
6581
+ }
6582
+ }
6583
  // ⭐ Wave-23 C7 — a JSON cell opens the big viewer. It is the ONLY door: the cell carries
6584
  // `allowOverlay:false`, because glide's overlay is a one-line box and one keystroke in the
6585
  // wrong place inside a 32 KB document turns a well-formed payload into an unparseable one,
 
12079
  </button>
12080
  </div>
12081
  ))}
12082
+ {groupFailures.map((gf) => (
12083
+ /* S67-T27 (R38): the page this open group asked for did not arrive. The group says
12084
+ so where its records would be, and "Try again" asks for the same page again. */
12085
+ <div key={`failed:${gf.key}`} className="cg-group-pager cg-group-failed" role="alert"
12086
+ data-group-failed={gf.key}
12087
+ style={{ top: gf.top, left: gf.left, height: gf.height }}>
12088
+ <span className="cg-pager-label"
12089
+ title={gf.cause && gf.cause !== GROUP_PAGE_FAILED ? gf.cause : undefined}>
12090
+ {GROUP_PAGE_FAILED}
12091
+ </span>
12092
+ <button type="button" className="cg-pager-btn"
12093
+ onClick={() => loadGroupPage(gf.key, groupPages.get(gf.key)?.offset ?? 0)}>
12094
+ Try again
12095
+ </button>
12096
+ </div>
12097
+ ))}
12098
  {/* ⭐⭐ W50-T03 (instruction 1, R2) — THE SUMMARY BAR, INSIDE THE BOX AND PINNED TO ITS
12099
  BOTTOM EDGE. Last child of `.cg-grid-box` so it paints over the void rectangles
12100
  rather than under them, and inside it rather than beside it so it cannot drift away
web/src/customer-grid/useGetCellContent.ts CHANGED
@@ -33,6 +33,15 @@ const EMPTY_CELL: GridCell = {
33
  * per render would change this hook's dep array every frame and repaint the canvas forever. */
34
  const EMPTY_KEYS: ReadonlySet<string> = new Set<string>();
35
 
 
 
 
 
 
 
 
 
 
36
  type GroupHeaderRow = Extract<VisibleRow, { kind: "group-header" }>;
37
  type GroupFooterRow = Extract<VisibleRow, { kind: "group-footer" }>;
38
 
@@ -256,7 +265,14 @@ export function useGetCellContent(
256
  * of the skeleton's pulse. CustomerGrid bumps it on a timer for as long as `pendingKeys` is
257
  * non-empty and then stops, so a settled grid repaints on nothing.
258
  */
259
- pulse = 0
 
 
 
 
 
 
 
260
  ) {
261
  /**
262
  * ⭐⭐ W41-T40 — WHERE THE GROUP BAR'S LABEL STOPS AND ITS NUMBERS START.
@@ -303,6 +319,12 @@ export function useGetCellContent(
303
  const colDef = visibleCols[col];
304
  const field = colDef ? fieldByKey.get(colDef.id!) : undefined;
305
 
 
 
 
 
 
 
306
  // Synthetic grouping rows branch BEFORE the data path.
307
  if (vr.kind === "group-header")
308
  return groupHeaderCell(vr, col, labelEnd, groupBarSpace, measureText, field);
@@ -333,6 +355,6 @@ export function useGetCellContent(
333
  // unnecessary; removing it would silently strand every photo behind its initials.
334
  // eslint-disable-next-line react-hooks/exhaustive-deps
335
  [visibleRows, visibleCols, fieldByKey, overlayEdits, canEdit, userAvatars, avatarTick,
336
- labelEnd, groupBarSpace, measureText, pendingKeys, pulse]
337
  );
338
  }
 
33
  * per render would change this hook's dep array every frame and repaint the canvas forever. */
34
  const EMPTY_KEYS: ReadonlySet<string> = new Set<string>();
35
 
36
+ /**
37
+ * S67-T27 (R38) — what a STRUCTURAL row inside an open server group stands in for while that
38
+ * group's page is not in hand: `loading` is one skeleton row per record the page will hold,
39
+ * `failed` is the one row the inline "Try again" overlay rides on. Keyed by the row OBJECT, so a
40
+ * real footer is never mistaken for one and nothing about the row's shape has to change.
41
+ */
42
+ export type GroupRowPlaceholder = "loading" | "failed";
43
+ const NO_PLACEHOLDERS: ReadonlyMap<VisibleRow, GroupRowPlaceholder> = new Map();
44
+
45
  type GroupHeaderRow = Extract<VisibleRow, { kind: "group-header" }>;
46
  type GroupFooterRow = Extract<VisibleRow, { kind: "group-footer" }>;
47
 
 
265
  * of the skeleton's pulse. CustomerGrid bumps it on a timer for as long as `pendingKeys` is
266
  * non-empty and then stops, so a settled grid repaints on nothing.
267
  */
268
+ pulse = 0,
269
+ /**
270
+ * S67-T27 (R38) — the open groups' stand-in rows (see `GroupRowPlaceholder`). A `loading` row
271
+ * paints a skeleton in every column; a `failed` row paints a blank strip under the DOM overlay
272
+ * that carries the sentence and "Try again". Empty by default, so every other caller is
273
+ * unaffected.
274
+ */
275
+ placeholders: ReadonlyMap<VisibleRow, GroupRowPlaceholder> = NO_PLACEHOLDERS
276
  ) {
277
  /**
278
  * ⭐⭐ W41-T40 — WHERE THE GROUP BAR'S LABEL STOPS AND ITS NUMBERS START.
 
319
  const colDef = visibleCols[col];
320
  const field = colDef ? fieldByKey.get(colDef.id!) : undefined;
321
 
322
+ // S67-T27 — a group's stand-in rows branch before the footer painter they are shaped like.
323
+ const placeholder = placeholders.get(vr);
324
+ if (placeholder === "loading")
325
+ return loadingCell((colDef as { width?: number } | undefined)?.width, row, pulse);
326
+ if (placeholder === "failed") return EMPTY_CELL;
327
+
328
  // Synthetic grouping rows branch BEFORE the data path.
329
  if (vr.kind === "group-header")
330
  return groupHeaderCell(vr, col, labelEnd, groupBarSpace, measureText, field);
 
355
  // unnecessary; removing it would silently strand every photo behind its initials.
356
  // eslint-disable-next-line react-hooks/exhaustive-deps
357
  [visibleRows, visibleCols, fieldByKey, overlayEdits, canEdit, userAvatars, avatarTick,
358
+ labelEnd, groupBarSpace, measureText, pendingKeys, pulse, placeholders]
359
  );
360
  }
web/src/home/HomePage.tsx CHANGED
@@ -41,7 +41,7 @@ import { AGENTS_MODULE_LABEL } from "../inbox/inboxModel";
41
  import { AgentIcon } from "../shell/icons";
42
  import { agentAddressHash, commitRoute, dataAddressHash, readDataAddress } from "../shell/nav";
43
  import type { DatabaseEntry, Recent } from "../shell/nav";
44
- import { API_V1, CREDENTIALS } from "../apiContract";
45
  // ⭐ WAVE 35 · W35-T15 (R4, C2) — ONE STAR CONTROL, drawn in the module that owns the concept and
46
  // worn by both surfaces. R4 makes star and "mark important" one idea and one flag; a second star
47
  // component here would be the "one mark, one meaning" failure DESIGN.md 4 names, and `useStarred`
@@ -58,6 +58,7 @@ import {
58
  applyHomeFilter,
59
  allDatabases,
60
  dataHomeLevel,
 
61
  parseHomeFilter,
62
  parseLayout,
63
  deleteModuleFolder,
@@ -68,11 +69,31 @@ import {
68
  parseModuleFolderIndex,
69
  saveModuleFolder,
70
  } from "./homeModel";
71
- import type { AutomationTile, HomeFilter, HomeLayout, HomeFolderTile, ModuleFolder, ModuleFolderIndex } from "./homeModel";
72
 
73
  // Twin in SheetPage.tsx; this ticket's file fence keeps the timeout local to each chunk.
74
  const FOLDER_WRITE_TIMEOUT_MS = 20000;
75
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
76
  function homeFolderHref(href: string, folder: string | undefined): string {
77
  if (!folder || folder === "__root__") return href;
78
  if (href.startsWith("#/data?") && readDataAddress(href).database) {
@@ -215,6 +236,46 @@ interface SheetTile {
215
  name: string;
216
  }
217
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
218
  /** Typed-name disclosure using the shared dialog kit and modal focus/Escape contract. */
219
  function AppDeleteDialog({ application, onDelete, onCancel }: {
220
  application: ApplicationTile;
@@ -229,8 +290,16 @@ function AppDeleteDialog({ application, onDelete, onCancel }: {
229
  const [confirmName, setConfirmName] = useState("");
230
  const [busy, setBusy] = useState(false);
231
  const [error, setError] = useState("");
 
232
  const submitting = useRef(false);
233
  const dismiss = () => { if (!submitting.current) onCancel(); };
 
 
 
 
 
 
 
234
  useOverlayLayer({
235
  panelRef,
236
  onDismiss: dismiss,
@@ -267,7 +336,10 @@ function AppDeleteDialog({ application, onDelete, onCancel }: {
267
  </button>
268
  </div>
269
  <div className="lp-dialog-body home-app-delete-body">
270
- <p id={descriptionId}>This removes the App and its stars. Source databases, Views and data stay.</p>
 
 
 
271
  <label htmlFor={inputId}>Type <strong>{application.name}</strong> to confirm.</label>
272
  <input id={inputId} className="home-app-delete-input" type="text" value={confirmName}
273
  aria-label="App name" aria-describedby={error ? errorId : descriptionId}
@@ -341,6 +413,9 @@ export interface HomeProps {
341
  mode?: "home" | "app" | "data" | "sheet" | "agents";
342
  /** Shell-selected registry cards; other galleries can omit them. */
343
  financeApplications?: ApplicationTile[];
 
 
 
344
  /** Compatibility entry for a retired `#/starred` bookmark. */
345
  initialStarredOnly?: boolean;
346
  /**
@@ -448,9 +523,12 @@ export function HomeSurface({
448
  agentsKnown = true,
449
  moduleIndex: suppliedModuleIndex = null,
450
  moduleIndexBusy = false,
451
- moduleIndexError = "",
452
  onSaveModuleIndex = async () => false,
453
- onReloadModuleIndex = () => undefined,
 
 
 
454
  starLoad,
455
  starred,
456
  busy,
@@ -475,6 +553,11 @@ export function HomeSurface({
475
  moduleIndexError?: string;
476
  onSaveModuleIndex?: (index: ModuleFolderIndex) => Promise<boolean>;
477
  onReloadModuleIndex?: () => void;
 
 
 
 
 
478
  starLoad: StarredLoad;
479
  starred: Starred;
480
  busy: boolean;
@@ -483,6 +566,9 @@ export function HomeSurface({
483
  toggle: (kind: StarKind, id: string, on: boolean, database?: string) => void;
484
  }) {
485
  const moduleName = mode === "agents" ? AGENTS_MODULE_LABEL : mode === "sheet" ? "Sheet" : mode === "app" ? "App" : mode === "data" ? "Data" : "Home";
 
 
 
486
  const [layout, setLayout] = useState<HomeLayout>(() => {
487
  try {
488
  return parseLayout(localStorage.getItem(HOME_LAYOUT_KEY));
@@ -613,14 +699,26 @@ export function HomeSurface({
613
  const appLevel = moduleFolderLevel(visibleApplications, moduleIndex ?? emptyIndex, folderAt);
614
  const agentLevel = moduleFolderLevel(galleryAgents, moduleIndex ?? emptyIndex, folderAt);
615
  const sheetLevel = moduleFolderLevel(visibleSheets, moduleIndex ?? emptyIndex, folderAt);
616
- const dataLevel = dataHomeLevel(visibleDatabases, moduleIndex ?? emptyIndex,
617
- originAt !== null ? { kind: "origin", label: originAt }
618
- : folderAt ? { kind: "folder", id: folderAt } : { kind: "root" }, entries.map((entry) => entry.key));
619
- const level = mode === "agents" ? agentLevel : mode === "sheet" ? sheetLevel : mode === "data" ? dataLevel : appLevel;
620
- const origin = mode === "data" ? dataLevel.origin : null;
 
 
 
 
 
 
 
 
 
 
 
 
621
  const moduleItems = mode === "agents" ? galleryAgents : mode === "sheet" ? visibleSheets
622
  : mode === "data" ? visibleDatabases : visibleApplications;
623
- const folderTiles: HomeFolderTile[] = mode === "data" ? dataLevel.tiles : level.folders.map((folder) => ({
624
  ...folder, kind: "folder", count: moduleItems.filter((row) => moduleIndex?.itemFolders[moduleTileId(row)] === folder.id).length,
625
  }));
626
  // R40 (wave 62): inside a folder the head is a Back arrow and the plain folder name, never a
@@ -630,7 +728,7 @@ export function HomeSurface({
630
  const selection = useRailSelection(levelTileIds);
631
  const levelApplications = mode === "app" ? appLevel.items : visibleApplications;
632
  const levelSheets = mode === "sheet" ? sheetLevel.items : visibleSheets;
633
- const levelDatabases = mode === "data" ? dataLevel.items : visibleDatabases;
634
  useEffect(() => {
635
  setFolderAt(mode === "data" ? new URLSearchParams(window.location.hash.split("?")[1]).get("folder") : null);
636
  setOriginAt(null);
@@ -657,12 +755,16 @@ export function HomeSurface({
657
  if (saved) { selection.clear(); setMovePicker(false); setFolderEdit(null); }
658
  return saved;
659
  };
660
- const moveTiles = (ids: readonly string[], target: string | null) => {
 
 
 
 
661
  if (!folderWritable || !moduleIndex || ids.length === 0) return;
662
  void saveFolders(moveModuleItems(moduleIndex, ids, target));
663
  };
664
  const moduleTileEvents = (id: string) => moduleHome ? {
665
- draggable: folderWritable,
666
  onClick: (event: MouseEvent<HTMLElement>) => {
667
  if (!(event.target instanceof Element) || !event.target.closest("a.home-tile")) return;
668
  selection.onRowClick(id, event);
@@ -670,7 +772,8 @@ export function HomeSurface({
670
  },
671
  onDragStart: (event: DragEvent<HTMLElement>) => {
672
  if (!folderWritable) { event.preventDefault(); return; }
673
- const ids = selection.selected.includes(id) ? selection.selected : [id];
 
674
  setDraggedIds(ids);
675
  event.dataTransfer.effectAllowed = "move";
676
  event.dataTransfer.setData("text/plain", JSON.stringify(ids));
@@ -730,16 +833,16 @@ export function HomeSurface({
730
  {moduleIndexError ? <p className="home-app-note" role="alert">{moduleIndexError}
731
  <button type="button" className="cg-btn" onClick={onReloadModuleIndex}>Reload folders</button>
732
  </p> : null}
733
- {(!indexKnown && !moduleIndexError) || (mode === "app" && !applicationsKnown && !applicationsError) ? (
734
  <div className="shell-rail-skeleton" role="status"
735
- aria-label={!indexKnown && !moduleIndexError ? "Loading folders" : "Loading applications"}>
736
  <div className="shell-rail-skeleton-row" aria-hidden="true">
737
  <span className="shell-rail-skeleton-mark" />
738
  <span className="shell-rail-skeleton-bar" />
739
  </div>
740
  </div>
741
  ) : null}
742
- {indexKnown ? <>
743
  {level.current || origin !== null ? <div className="home-section-head">
744
  <button type="button" className="cg-btn" aria-label="Back" title="Back"
745
  onClick={() => enterFolder(level.breadcrumb[level.breadcrumb.length - 2]?.id ?? null)}
@@ -1052,6 +1155,10 @@ export function HomeSurface({
1052
  </div>
1053
 
1054
  {moduleHome ? renderModuleFolders() : null}
 
 
 
 
1055
  {mode !== "app" && mode !== "sheet" && mode !== "agents" && !starredOnly && databases.length === 0
1056
  && (mode !== "data" || (!level.current && origin === null && folderTiles.length === 0)) ? (
1057
  // ⛔ ONE LINE, AND IT NAMES THE DOOR THAT FILLS IT (DESIGN.md 4 / R13). This is also
@@ -1068,7 +1175,7 @@ export function HomeSurface({
1068
  </p>
1069
  ) : mode !== "app" && mode !== "sheet" && mode !== "agents" && levelDatabases.length ? (
1070
  <section className="home-section">
1071
- <h2 className="home-section-title">Databases</h2>
1072
  <div className={"home-tiles is-" + layout}>
1073
  {levelDatabases.map((tile) => (
1074
  <div key={tile.key} className={"home-data-tile" + (mode === "data" ? " cg-view-row" + (selection.isSelected(tile.key) ? " is-railsel" : "") : "")}
@@ -1086,7 +1193,7 @@ export function HomeSurface({
1086
  </div>
1087
  </section>
1088
  ) : null}
1089
- {mode === "home" && !starredOnly && folders.some((folder) => !folder.parent) && <section className="home-section"><h2 className="home-section-title">Folders</h2><div className={"home-tiles is-" + layout}>{folders.filter((folder) => !folder.parent).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>}
1090
  {mode !== "data" && mode !== "sheet" && mode !== "agents" && applicationsError ? (
1091
  <p className="home-app-note" role="alert">{applicationsError}</p>
1092
  ) : null}
@@ -1098,7 +1205,8 @@ export function HomeSurface({
1098
  const database = application.openTarget?.database
1099
  ?? application.compatibleDatabases?.[0]
1100
  ?? "";
1101
- const kind = application.templateKind === "finance" ? "Finance" : application.templateKind === "catalog"
 
1102
  ? "Catalog"
1103
  : application.templateKind === "route"
1104
  ? "Routing"
@@ -1343,12 +1451,8 @@ function useModuleFolders(mode: HomeProps["mode"]) {
1343
  setSaving(false);
1344
  setState({ module, index: null, error: "" });
1345
  if (module) {
1346
- void fetch(`${API_V1}/module-index/${module}`, { credentials: CREDENTIALS, signal: controller.signal })
1347
- .then(async (response) => {
1348
- const body = await response.json();
1349
- if (!response.ok) throw new Error(body?.detail?.error?.message || "Folders could not be loaded. Reload folders to retry.");
1350
- const loaded = parseModuleFolderIndex(body?.index);
1351
- if (!loaded) throw new Error("Folders could not be loaded. Reload folders to retry.");
1352
  if (!controller.signal.aborted && epoch === generation.current) setState({ module, index: loaded, error: "" });
1353
  }).catch((error: unknown) => {
1354
  if (!controller.signal.aborted && epoch === generation.current) setState({ module, index: null,
@@ -1361,8 +1465,12 @@ function useModuleFolders(mode: HomeProps["mode"]) {
1361
  // W61-T19's unloaded wholesale PUT erased a real tree. A read and its revision are mandatory.
1362
  if (!module || !index || writePending.current || next.rev !== index.rev) return false;
1363
  const epoch = generation.current;
 
1364
  writePending.current = true;
1365
  setSaving(true);
 
 
 
1366
  let timeout: ReturnType<typeof setTimeout> | undefined;
1367
  try {
1368
  const landed = await Promise.race([
@@ -1372,8 +1480,9 @@ function useModuleFolders(mode: HomeProps["mode"]) {
1372
  body: JSON.stringify({ folders: next.folders, itemFolders: next.itemFolders, rev: index.rev,
1373
  ...(index.collapsedGroups !== undefined ? { collapsedGroups: index.collapsedGroups } : {}) }),
1374
  });
1375
- const body = await response.json();
1376
- if (!response.ok) throw new Error(body?.detail?.error?.message || "Folders could not be saved. Reload folders to retry.");
 
1377
  const loaded = parseModuleFolderIndex(body?.index);
1378
  if (!loaded) throw new Error("The folder save could not be confirmed. Reload folders to check.");
1379
  return loaded;
@@ -1382,12 +1491,27 @@ function useModuleFolders(mode: HomeProps["mode"]) {
1382
  timeout = setTimeout(() => reject(new Error("The folder move timed out. Reload folders to retry.")), FOLDER_WRITE_TIMEOUT_MS);
1383
  }),
1384
  ]);
1385
- if (epoch !== generation.current || activeModule.current !== module) return false;
1386
  setState({ module, index: landed, error: "" });
1387
  window.dispatchEvent(new CustomEvent("aios:module-index-changed", { detail: { module } }));
1388
  return true;
1389
  } catch (error) {
1390
- if (epoch === generation.current && activeModule.current === module) setState({ module, index,
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1391
  error: error instanceof Error ? error.message : "Folders could not be saved. Reload folders to retry." });
1392
  return false;
1393
  } finally {
@@ -1597,12 +1721,17 @@ export default function HomePage(props: HomeProps) {
1597
  return () => controller.abort();
1598
  }, [props.mode, applicationsEpoch]);
1599
 
 
 
 
 
 
1600
  const toggleApplication = (application: ApplicationTile, on: boolean) => {
1601
  if (applicationWrites.current.has(application.id) || deletedApplications.current.has(application.id)) return;
1602
  applicationWrites.current.add(application.id);
1603
  setApplicationsError("");
1604
  setApplicationBusy((current) => new Set(current).add(application.id));
1605
- void fetch(`${API_V1}/applications/${encodeURIComponent(application.id)}`, {
1606
  method: "PATCH",
1607
  credentials: CREDENTIALS,
1608
  headers: { "Content-Type": "application/json" },
@@ -1616,6 +1745,8 @@ export default function HomePage(props: HomeProps) {
1616
  .then((landed) => {
1617
  if (!landed || deletedApplications.current.has(application.id)) return;
1618
  setApplications((current) => current.map((row) => row.id === landed.id ? landed : row));
 
 
1619
  })
1620
  .catch(() => {
1621
  if (!deletedApplications.current.has(application.id)) {
@@ -1635,7 +1766,7 @@ export default function HomePage(props: HomeProps) {
1635
  if (application.capabilities?.delete !== true || confirmName !== application.name) {
1636
  throw new Error("Enter the exact App name to confirm.");
1637
  }
1638
- const response = await fetch(`${API_V1}/applications/${encodeURIComponent(application.id)}`, {
1639
  method: "DELETE",
1640
  credentials: CREDENTIALS,
1641
  headers: { "Content-Type": "application/json" },
@@ -1657,7 +1788,17 @@ export default function HomePage(props: HomeProps) {
1657
  };
1658
  const financeApplications = props.mode === "app"
1659
  ? props.financeApplications ?? NO_FINANCE_APPLICATIONS : NO_FINANCE_APPLICATIONS;
1660
- const merged = new Map([...tenantApplications, ...financeApplications].map((row) => [row.id, row]));
 
 
 
 
 
 
 
 
 
 
1661
  const applications = [...merged.values()].filter((row) => !deletedApplications.current.has(row.id)
1662
  && (props.mode === "app" || row.templateKind !== "finance"));
1663
  return (
@@ -1675,6 +1816,10 @@ export default function HomePage(props: HomeProps) {
1675
  setSheetIndexBusy(false);
1676
  setSheetIndexEpoch((value) => value + 1);
1677
  } : moduleFolders.refresh}
 
 
 
 
1678
  starLoad={starLoad}
1679
  starred={starred}
1680
  busy={busy}
 
41
  import { AgentIcon } from "../shell/icons";
42
  import { agentAddressHash, commitRoute, dataAddressHash, readDataAddress } from "../shell/nav";
43
  import type { DatabaseEntry, Recent } from "../shell/nav";
44
+ import { API_V1, CREDENTIALS, TOAST_EVENT, signal } from "../apiContract";
45
  // ⭐ WAVE 35 · W35-T15 (R4, C2) — ONE STAR CONTROL, drawn in the module that owns the concept and
46
  // worn by both surfaces. R4 makes star and "mark important" one idea and one flag; a second star
47
  // component here would be the "one mark, one meaning" failure DESIGN.md 4 names, and `useStarred`
 
58
  applyHomeFilter,
59
  allDatabases,
60
  dataHomeLevel,
61
+ homeDataFolds,
62
  parseHomeFilter,
63
  parseLayout,
64
  deleteModuleFolder,
 
69
  parseModuleFolderIndex,
70
  saveModuleFolder,
71
  } from "./homeModel";
72
+ import type { AutomationTile, DataHomeLocation, HomeFilter, HomeLayout, HomeFolderTile, ModuleFolder, ModuleFolderIndex } from "./homeModel";
73
 
74
  // Twin in SheetPage.tsx; this ticket's file fence keeps the timeout local to each chunk.
75
  const FOLDER_WRITE_TIMEOUT_MS = 20000;
76
 
77
+ // S67-T38: the API answers a refusal as a TOP-LEVEL `{error: {code, message}}` (main.py
78
+ // `_error_shape`). Reading only `detail.error` hid every real reason behind the fallback line.
79
+ function refusalSentence(body: unknown, fallback: string): string {
80
+ const shaped = body as { error?: { message?: unknown }; detail?: { error?: { message?: unknown } } } | null;
81
+ const message = shaped?.error?.message ?? shaped?.detail?.error?.message;
82
+ return typeof message === "string" && message.trim() ? message : fallback;
83
+ }
84
+
85
+ /** A 409 from the folder writer: someone else saved first, so the hook re-reads, never retries. */
86
+ class StaleFolderIndex extends Error {}
87
+
88
+ async function readModuleFolderIndex(module: "app" | "agents", abort: AbortSignal): Promise<ModuleFolderIndex> {
89
+ const response = await fetch(`${API_V1}/module-index/${module}`, { credentials: CREDENTIALS, signal: abort });
90
+ const body = await response.json().catch(() => null);
91
+ if (!response.ok) throw new Error(refusalSentence(body, "Folders could not be loaded. Reload folders to retry."));
92
+ const loaded = parseModuleFolderIndex(body?.index);
93
+ if (!loaded) throw new Error("Folders could not be loaded. Reload folders to retry.");
94
+ return loaded;
95
+ }
96
+
97
  function homeFolderHref(href: string, folder: string | undefined): string {
98
  if (!folder || folder === "__root__") return href;
99
  if (href.startsWith("#/data?") && readDataAddress(href).database) {
 
236
  name: string;
237
  }
238
 
239
+ /**
240
+ * S67-T39 / R36: how many saved Views, across every user, are bound to this App. The server
241
+ * counts per database on a database-filtered `/applications` read (`dependentViews`), so the
242
+ * dialog asks once per compatible database and sums. `null` means the count is unknown.
243
+ */
244
+ async function countDependentViews(application: ApplicationTile, abort: AbortSignal): Promise<number | null> {
245
+ // S67-T41 owner correction: a Content Studio is bound to user tables, which this topic-only read
246
+ // refuses (403). No View binds to it, and "unknown" is the honest answer, never a guessed 0.
247
+ if (application.templateKind === "content_studio") return null;
248
+ const databases = [...new Set([
249
+ ...(application.compatibleDatabases ?? []),
250
+ ...(application.openTarget?.database ? [application.openTarget.database] : []),
251
+ ])];
252
+ let total = 0;
253
+ for (const count of await Promise.all(databases.map(async (database) => {
254
+ const response = await fetch(
255
+ `${API_V1}/applications?database=${encodeURIComponent(database)}` +
256
+ `&type=${encodeURIComponent(application.type)}`,
257
+ { credentials: CREDENTIALS, signal: abort });
258
+ if (!response.ok) return null;
259
+ const body = await response.json().catch(() => null);
260
+ const rows = Array.isArray(body?.applications) ? body.applications : [];
261
+ const row = rows.find((candidate: { id?: string }) => candidate?.id === application.id);
262
+ return row && typeof row.dependentViews === "number" ? row.dependentViews as number : null;
263
+ }))) {
264
+ if (count === null) return null;
265
+ total += count;
266
+ }
267
+ return total;
268
+ }
269
+
270
+ /** The dialog's consequence sentence for a known, unknown or pending dependent-View count. */
271
+ function dependentViewsSentence(count: number | null | "counting"): string {
272
+ if (count === "counting") return "Counting the Views that use it.";
273
+ if (count === null) return "Views that use it stay and open as plain views of their database.";
274
+ if (count === 0) return "Source databases, Views and data stay.";
275
+ if (count === 1) return "1 View uses this App. It stays and opens as a plain view of its database.";
276
+ return `${count.toLocaleString()} Views use this App. They stay and open as plain views of their database.`;
277
+ }
278
+
279
  /** Typed-name disclosure using the shared dialog kit and modal focus/Escape contract. */
280
  function AppDeleteDialog({ application, onDelete, onCancel }: {
281
  application: ApplicationTile;
 
290
  const [confirmName, setConfirmName] = useState("");
291
  const [busy, setBusy] = useState(false);
292
  const [error, setError] = useState("");
293
+ const [dependentViews, setDependentViews] = useState<number | null | "counting">("counting");
294
  const submitting = useRef(false);
295
  const dismiss = () => { if (!submitting.current) onCancel(); };
296
+ useEffect(() => {
297
+ const controller = new AbortController();
298
+ countDependentViews(application, controller.signal)
299
+ .then((count) => { if (!controller.signal.aborted) setDependentViews(count); })
300
+ .catch(() => { if (!controller.signal.aborted) setDependentViews(null); });
301
+ return () => controller.abort();
302
+ }, [application]);
303
  useOverlayLayer({
304
  panelRef,
305
  onDismiss: dismiss,
 
336
  </button>
337
  </div>
338
  <div className="lp-dialog-body home-app-delete-body">
339
+ <p id={descriptionId} aria-live="polite" aria-busy={dependentViews === "counting"}
340
+ data-dependent-views={typeof dependentViews === "number" ? dependentViews : undefined}>
341
+ This removes the App and its stars. {dependentViewsSentence(dependentViews)}
342
+ </p>
343
  <label htmlFor={inputId}>Type <strong>{application.name}</strong> to confirm.</label>
344
  <input id={inputId} className="home-app-delete-input" type="text" value={confirmName}
345
  aria-label="App name" aria-describedby={error ? errorId : descriptionId}
 
413
  mode?: "home" | "app" | "data" | "sheet" | "agents";
414
  /** Shell-selected registry cards; other galleries can omit them. */
415
  financeApplications?: ApplicationTile[];
416
+ /** S67-T41 owner correction: Content Studio Apps (bound to user tables, so absent from the
417
+ * `/applications` read), from the Shell's grant-filtered `/nav/applications` read. */
418
+ studioApplications?: ApplicationTile[];
419
  /** Compatibility entry for a retired `#/starred` bookmark. */
420
  initialStarredOnly?: boolean;
421
  /**
 
523
  agentsKnown = true,
524
  moduleIndex: suppliedModuleIndex = null,
525
  moduleIndexBusy = false,
526
+ moduleIndexError: suppliedModuleIndexError = "",
527
  onSaveModuleIndex = async () => false,
528
+ onReloadModuleIndex: suppliedReloadModuleIndex = () => undefined,
529
+ dataIndex: suppliedDataIndex,
530
+ dataIndexError = "",
531
+ onReloadDataIndex = () => undefined,
532
  starLoad,
533
  starred,
534
  busy,
 
553
  moduleIndexError?: string;
554
  onSaveModuleIndex?: (index: ModuleFolderIndex) => Promise<boolean>;
555
  onReloadModuleIndex?: () => void;
556
+ /** S67-T37: Home's read of Data's shared folder index (`null` while it loads). Absent means
557
+ * the caller's `folders`/`folderPlacement` are the index, already known. Home never writes it. */
558
+ dataIndex?: ModuleFolderIndex | null;
559
+ dataIndexError?: string;
560
+ onReloadDataIndex?: () => void;
561
  starLoad: StarredLoad;
562
  starred: Starred;
563
  busy: boolean;
 
566
  toggle: (kind: StarKind, id: string, on: boolean, database?: string) => void;
567
  }) {
568
  const moduleName = mode === "agents" ? AGENTS_MODULE_LABEL : mode === "sheet" ? "Sheet" : mode === "app" ? "App" : mode === "data" ? "Data" : "Home";
569
+ // S67-T37: on Home the folder head reports Data's shared index, the one its Databases fold.
570
+ const moduleIndexError = mode === "home" ? dataIndexError : suppliedModuleIndexError;
571
+ const onReloadModuleIndex = mode === "home" ? onReloadDataIndex : suppliedReloadModuleIndex;
572
  const [layout, setLayout] = useState<HomeLayout>(() => {
573
  try {
574
  return parseLayout(localStorage.getItem(HOME_LAYOUT_KEY));
 
699
  const appLevel = moduleFolderLevel(visibleApplications, moduleIndex ?? emptyIndex, folderAt);
700
  const agentLevel = moduleFolderLevel(galleryAgents, moduleIndex ?? emptyIndex, folderAt);
701
  const sheetLevel = moduleFolderLevel(visibleSheets, moduleIndex ?? emptyIndex, folderAt);
702
+ const dataAt: DataHomeLocation = originAt !== null ? { kind: "origin", label: originAt }
703
+ : folderAt ? { kind: "folder", id: folderAt } : { kind: "root" };
704
+ const navOrder = entries.map((entry) => entry.key);
705
+ const dataLevel = dataHomeLevel(visibleDatabases, moduleIndex ?? emptyIndex, dataAt, navOrder);
706
+ // S67-T37 (R29: O17 fold Databases only, O18 enter-only): Home's Databases section folds through
707
+ // the Data home's own level over Data's shared index. `moduleIndex` on Home is the Sheet index,
708
+ // so the Data one arrives separately. Home is not a module home: nothing here drags, selects,
709
+ // renames, moves or creates a folder, because `folderWritable` stays false.
710
+ const homeDataIndex: ModuleFolderIndex | null = mode !== "home" ? null
711
+ : suppliedDataIndex !== undefined ? suppliedDataIndex : { folders, itemFolders: folderPlacement, rev: 0 };
712
+ const homeFolds = mode === "home" && homeDataFolds(visibleDatabases);
713
+ const homeLevel = homeFolds ? dataHomeLevel(visibleDatabases, homeDataIndex ?? emptyIndex, dataAt, navOrder) : dataLevel;
714
+ const level = mode === "agents" ? agentLevel : mode === "sheet" ? sheetLevel : mode === "data" ? dataLevel
715
+ : homeFolds ? homeLevel : appLevel;
716
+ const origin = mode === "data" ? dataLevel.origin : homeFolds ? homeLevel.origin : null;
717
+ // The fold's own readiness: a module home's index, or on Home the Data index it folds.
718
+ const foldKnown = indexKnown || (homeFolds && homeDataIndex !== null);
719
  const moduleItems = mode === "agents" ? galleryAgents : mode === "sheet" ? visibleSheets
720
  : mode === "data" ? visibleDatabases : visibleApplications;
721
+ const folderTiles: HomeFolderTile[] = mode === "data" ? dataLevel.tiles : homeFolds ? homeLevel.tiles : level.folders.map((folder) => ({
722
  ...folder, kind: "folder", count: moduleItems.filter((row) => moduleIndex?.itemFolders[moduleTileId(row)] === folder.id).length,
723
  }));
724
  // R40 (wave 62): inside a folder the head is a Back arrow and the plain folder name, never a
 
728
  const selection = useRailSelection(levelTileIds);
729
  const levelApplications = mode === "app" ? appLevel.items : visibleApplications;
730
  const levelSheets = mode === "sheet" ? sheetLevel.items : visibleSheets;
731
+ const levelDatabases = mode === "data" ? dataLevel.items : homeFolds ? homeLevel.items : visibleDatabases;
732
  useEffect(() => {
733
  setFolderAt(mode === "data" ? new URLSearchParams(window.location.hash.split("?")[1]).get("folder") : null);
734
  setOriginAt(null);
 
755
  if (saved) { selection.clear(); setMovePicker(false); setFolderEdit(null); }
756
  return saved;
757
  };
758
+ // S67-T38 NC: a tile is placeable only if this module renders it from its grant-filtered read
759
+ // (the same ids the server's placement wall admits); anything else neither drags nor moves.
760
+ const placeableIds = new Set(moduleItems.map(moduleTileId));
761
+ const moveTiles = (picked: readonly string[], target: string | null) => {
762
+ const ids = picked.filter((id) => placeableIds.has(id));
763
  if (!folderWritable || !moduleIndex || ids.length === 0) return;
764
  void saveFolders(moveModuleItems(moduleIndex, ids, target));
765
  };
766
  const moduleTileEvents = (id: string) => moduleHome ? {
767
+ draggable: folderWritable && placeableIds.has(id),
768
  onClick: (event: MouseEvent<HTMLElement>) => {
769
  if (!(event.target instanceof Element) || !event.target.closest("a.home-tile")) return;
770
  selection.onRowClick(id, event);
 
772
  },
773
  onDragStart: (event: DragEvent<HTMLElement>) => {
774
  if (!folderWritable) { event.preventDefault(); return; }
775
+ if (!placeableIds.has(id)) { event.preventDefault(); return; }
776
+ const ids = (selection.selected.includes(id) ? selection.selected : [id]).filter((item) => placeableIds.has(item));
777
  setDraggedIds(ids);
778
  event.dataTransfer.effectAllowed = "move";
779
  event.dataTransfer.setData("text/plain", JSON.stringify(ids));
 
833
  {moduleIndexError ? <p className="home-app-note" role="alert">{moduleIndexError}
834
  <button type="button" className="cg-btn" onClick={onReloadModuleIndex}>Reload folders</button>
835
  </p> : null}
836
+ {(!foldKnown && !moduleIndexError) || (mode === "app" && !applicationsKnown && !applicationsError) ? (
837
  <div className="shell-rail-skeleton" role="status"
838
+ aria-label={!foldKnown && !moduleIndexError ? "Loading folders" : "Loading applications"}>
839
  <div className="shell-rail-skeleton-row" aria-hidden="true">
840
  <span className="shell-rail-skeleton-mark" />
841
  <span className="shell-rail-skeleton-bar" />
842
  </div>
843
  </div>
844
  ) : null}
845
+ {foldKnown ? <>
846
  {level.current || origin !== null ? <div className="home-section-head">
847
  <button type="button" className="cg-btn" aria-label="Back" title="Back"
848
  onClick={() => enterFolder(level.breadcrumb[level.breadcrumb.length - 2]?.id ?? null)}
 
1155
  </div>
1156
 
1157
  {moduleHome ? renderModuleFolders() : null}
1158
+ {/* S67-T37: Home folds its Databases through the Data home's folder and origin tiles, Back
1159
+ arrow and title, under the one "Databases" heading; entering is all it does (O18). */}
1160
+ {homeFolds ? <h2 className="home-section-title">Databases</h2> : null}
1161
+ {homeFolds ? renderModuleFolders() : null}
1162
  {mode !== "app" && mode !== "sheet" && mode !== "agents" && !starredOnly && databases.length === 0
1163
  && (mode !== "data" || (!level.current && origin === null && folderTiles.length === 0)) ? (
1164
  // ⛔ ONE LINE, AND IT NAMES THE DOOR THAT FILLS IT (DESIGN.md 4 / R13). This is also
 
1175
  </p>
1176
  ) : mode !== "app" && mode !== "sheet" && mode !== "agents" && levelDatabases.length ? (
1177
  <section className="home-section">
1178
+ {homeFolds ? null : <h2 className="home-section-title">Databases</h2>}
1179
  <div className={"home-tiles is-" + layout}>
1180
  {levelDatabases.map((tile) => (
1181
  <div key={tile.key} className={"home-data-tile" + (mode === "data" ? " cg-view-row" + (selection.isSelected(tile.key) ? " is-railsel" : "") : "")}
 
1193
  </div>
1194
  </section>
1195
  ) : null}
1196
+ {mode === "home" && !homeFolds && !starredOnly && folders.some((folder) => !folder.parent) && <section className="home-section"><h2 className="home-section-title">Folders</h2><div className={"home-tiles is-" + layout}>{folders.filter((folder) => !folder.parent).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>}
1197
  {mode !== "data" && mode !== "sheet" && mode !== "agents" && applicationsError ? (
1198
  <p className="home-app-note" role="alert">{applicationsError}</p>
1199
  ) : null}
 
1205
  const database = application.openTarget?.database
1206
  ?? application.compatibleDatabases?.[0]
1207
  ?? "";
1208
+ const kind = application.templateKind === "finance" ? "Finance" : application.templateKind === "content_studio"
1209
+ ? "Content Studio" : application.templateKind === "catalog"
1210
  ? "Catalog"
1211
  : application.templateKind === "route"
1212
  ? "Routing"
 
1451
  setSaving(false);
1452
  setState({ module, index: null, error: "" });
1453
  if (module) {
1454
+ void readModuleFolderIndex(module, controller.signal)
1455
+ .then((loaded) => {
 
 
 
 
1456
  if (!controller.signal.aborted && epoch === generation.current) setState({ module, index: loaded, error: "" });
1457
  }).catch((error: unknown) => {
1458
  if (!controller.signal.aborted && epoch === generation.current) setState({ module, index: null,
 
1465
  // W61-T19's unloaded wholesale PUT erased a real tree. A read and its revision are mandatory.
1466
  if (!module || !index || writePending.current || next.rev !== index.rev) return false;
1467
  const epoch = generation.current;
1468
+ const active = () => epoch === generation.current && activeModule.current === module;
1469
  writePending.current = true;
1470
  setSaving(true);
1471
+ // S67-T38: optimistic like the Data home's writer (Shell.tsx `useDataFolderIndex`): the tile
1472
+ // lands in its folder now, and `index` (captured above) is what a refusal puts back.
1473
+ setState({ module, index: next, error: "" });
1474
  let timeout: ReturnType<typeof setTimeout> | undefined;
1475
  try {
1476
  const landed = await Promise.race([
 
1480
  body: JSON.stringify({ folders: next.folders, itemFolders: next.itemFolders, rev: index.rev,
1481
  ...(index.collapsedGroups !== undefined ? { collapsedGroups: index.collapsedGroups } : {}) }),
1482
  });
1483
+ const body = await response.json().catch(() => null);
1484
+ if (response.status === 409) throw new StaleFolderIndex(refusalSentence(body, "Folders changed somewhere else."));
1485
+ if (!response.ok) throw new Error(refusalSentence(body, "Folders could not be saved. Reload folders to retry."));
1486
  const loaded = parseModuleFolderIndex(body?.index);
1487
  if (!loaded) throw new Error("The folder save could not be confirmed. Reload folders to check.");
1488
  return loaded;
 
1491
  timeout = setTimeout(() => reject(new Error("The folder move timed out. Reload folders to retry.")), FOLDER_WRITE_TIMEOUT_MS);
1492
  }),
1493
  ]);
1494
+ if (!active()) return false;
1495
  setState({ module, index: landed, error: "" });
1496
  window.dispatchEvent(new CustomEvent("aios:module-index-changed", { detail: { module } }));
1497
  return true;
1498
  } catch (error) {
1499
+ if (!active()) return false;
1500
+ if (error instanceof StaleFolderIndex) {
1501
+ // A stale write recovers itself exactly as on Data: re-read, show the fresh tree, say so.
1502
+ const controller = new AbortController();
1503
+ const abort = setTimeout(() => controller.abort(), FOLDER_WRITE_TIMEOUT_MS);
1504
+ const fresh = await readModuleFolderIndex(module, controller.signal)
1505
+ .catch(() => null).finally(() => clearTimeout(abort));
1506
+ if (!active()) return false;
1507
+ if (fresh) {
1508
+ setState({ module, index: fresh, error: "" });
1509
+ signal(TOAST_EVENT, "Folders changed somewhere else. Reloaded folders; try again.");
1510
+ return false;
1511
+ }
1512
+ }
1513
+ // Put the tile back and name the server's own reason; Reload folders stays beside it.
1514
+ setState({ module, index,
1515
  error: error instanceof Error ? error.message : "Folders could not be saved. Reload folders to retry." });
1516
  return false;
1517
  } finally {
 
1721
  return () => controller.abort();
1722
  }, [props.mode, applicationsEpoch]);
1723
 
1724
+ // S67-T41 owner correction: the shared `/applications` doors refuse an App bound to a user
1725
+ // table, so a Content Studio's star and delete go to its own module's doors (same writers).
1726
+ const applicationDoor = (application: ApplicationTile) => application.templateKind === "content_studio"
1727
+ ? `${API_V1}/content-studio/apps/${encodeURIComponent(application.id)}`
1728
+ : `${API_V1}/applications/${encodeURIComponent(application.id)}`;
1729
  const toggleApplication = (application: ApplicationTile, on: boolean) => {
1730
  if (applicationWrites.current.has(application.id) || deletedApplications.current.has(application.id)) return;
1731
  applicationWrites.current.add(application.id);
1732
  setApplicationsError("");
1733
  setApplicationBusy((current) => new Set(current).add(application.id));
1734
+ void fetch(applicationDoor(application), {
1735
  method: "PATCH",
1736
  credentials: CREDENTIALS,
1737
  headers: { "Content-Type": "application/json" },
 
1745
  .then((landed) => {
1746
  if (!landed || deletedApplications.current.has(application.id)) return;
1747
  setApplications((current) => current.map((row) => row.id === landed.id ? landed : row));
1748
+ // A Content Studio tile is the Shell's (`/nav/applications`): ask it to read again.
1749
+ if (application.templateKind === "content_studio") window.dispatchEvent(new CustomEvent("aios:applications-changed"));
1750
  })
1751
  .catch(() => {
1752
  if (!deletedApplications.current.has(application.id)) {
 
1766
  if (application.capabilities?.delete !== true || confirmName !== application.name) {
1767
  throw new Error("Enter the exact App name to confirm.");
1768
  }
1769
+ const response = await fetch(applicationDoor(application), {
1770
  method: "DELETE",
1771
  credentials: CREDENTIALS,
1772
  headers: { "Content-Type": "application/json" },
 
1788
  };
1789
  const financeApplications = props.mode === "app"
1790
  ? props.financeApplications ?? NO_FINANCE_APPLICATIONS : NO_FINANCE_APPLICATIONS;
1791
+ const studioApplications = props.mode === "app" || props.mode === "home"
1792
+ ? props.studioApplications ?? NO_FINANCE_APPLICATIONS : NO_FINANCE_APPLICATIONS;
1793
+ // S67-T38: a Finance projection arrives from /nav/applications carrying its registry `key`, and
1794
+ // `moduleTileId` reads `key` first, so the fold filed "ar-collections" while the drag and the
1795
+ // server wall use the Application id "finance_ar-collections". An App tile is its `id`, always.
1796
+ const asTile = (row: ApplicationTile): ApplicationTile => {
1797
+ const { key: _registryKey, ...tile } = row as ApplicationTile & { key?: unknown };
1798
+ return tile;
1799
+ };
1800
+ const merged = new Map([...tenantApplications, ...financeApplications].concat(studioApplications)
1801
+ .map((row) => [row.id, asTile(row)]));
1802
  const applications = [...merged.values()].filter((row) => !deletedApplications.current.has(row.id)
1803
  && (props.mode === "app" || row.templateKind !== "finance"));
1804
  return (
 
1816
  setSheetIndexBusy(false);
1817
  setSheetIndexEpoch((value) => value + 1);
1818
  } : moduleFolders.refresh}
1819
+ /* S67-T37: the frame's Data index reaches Home for reading only; its Sheet index stays above. */
1820
+ dataIndex={props.mode === "home" ? props.moduleIndex ?? null : undefined}
1821
+ dataIndexError={props.mode === "home" ? props.moduleIndexError ?? "" : ""}
1822
+ onReloadDataIndex={props.onReloadModuleIndex}
1823
  starLoad={starLoad}
1824
  starred={starred}
1825
  busy={busy}
web/src/home/TemplatePicker.tsx CHANGED
@@ -4,6 +4,7 @@ import { AGENTS_CHANGED } from "../apiContract";
4
  import { CONNECTORS_ROUTE } from "../shell/nav";
5
  import { createPickerTemplate, fetchTemplateSections, OPEN_APP_TEMPLATE_EVENT } from "../sheet/templates/templatesApi";
6
  import type { PickerTemplate, TemplateModule, TemplateSection } from "../sheet/templates/templatesApi";
 
7
  import "../styles/wave59/templates.css";
8
 
9
  const labels: Record<TemplateModule, string> = { sheet: "Sheet", data: "Data", app: "App", agents: "Agents" };
@@ -30,6 +31,8 @@ export default function TemplatePicker({ initialModule = "sheet", onClose, onCre
30
  const [error, setError] = useState("");
31
  const [reload, setReload] = useState(0);
32
  const [busy, setBusy] = useState("");
 
 
33
  const panelRef = useRef<HTMLDivElement>(null);
34
  const applying = useRef(false);
35
  const alive = useRef(true);
@@ -75,6 +78,10 @@ export default function TemplatePicker({ initialModule = "sheet", onClose, onCre
75
 
76
  const create = async (template: PickerTemplate) => {
77
  if (!template.creatable || applying.current) return;
 
 
 
 
78
  if (module === "app" && usesApplicationWizard(template)) {
79
  if (onApplication) onApplication(template.key);
80
  else {
@@ -158,5 +165,7 @@ export default function TemplatePicker({ initialModule = "sheet", onClose, onCre
158
  </div>
159
  </div>
160
  </div>
 
 
161
  </BodyPortal>;
162
  }
 
4
  import { CONNECTORS_ROUTE } from "../shell/nav";
5
  import { createPickerTemplate, fetchTemplateSections, OPEN_APP_TEMPLATE_EVENT } from "../sheet/templates/templatesApi";
6
  import type { PickerTemplate, TemplateModule, TemplateSection } from "../sheet/templates/templatesApi";
7
+ import ContentStudioSetup, { CONTENT_STUDIO_TEMPLATE_KEY } from "../apps/contentStudio/ContentStudioSetup";
8
  import "../styles/wave59/templates.css";
9
 
10
  const labels: Record<TemplateModule, string> = { sheet: "Sheet", data: "Data", app: "App", agents: "Agents" };
 
31
  const [error, setError] = useState("");
32
  const [reload, setReload] = useState(0);
33
  const [busy, setBusy] = useState("");
34
+ // S67-T40 (O2): Content Studio creates its own databases, so its step replaces "Choose a database".
35
+ const [studioSetup, setStudioSetup] = useState(false);
36
  const panelRef = useRef<HTMLDivElement>(null);
37
  const applying = useRef(false);
38
  const alive = useRef(true);
 
78
 
79
  const create = async (template: PickerTemplate) => {
80
  if (!template.creatable || applying.current) return;
81
+ if (module === "app" && template.key === CONTENT_STUDIO_TEMPLATE_KEY) {
82
+ setStudioSetup(true);
83
+ return;
84
+ }
85
  if (module === "app" && usesApplicationWizard(template)) {
86
  if (onApplication) onApplication(template.key);
87
  else {
 
165
  </div>
166
  </div>
167
  </div>
168
+ {studioSetup ? <ContentStudioSetup onCancel={() => setStudioSetup(false)}
169
+ onCreated={(address) => { setStudioSetup(false); onCreated(address); }} /> : null}
170
  </BodyPortal>;
171
  }
web/src/home/homeModel.ts CHANGED
@@ -377,6 +377,14 @@ export function dataHomeLevel<T extends DataHomeRow>(
377
  }))] };
378
  }
379
 
 
 
 
 
 
 
 
 
380
  export function moveModuleItems(index: ModuleFolderIndex, ids: readonly string[], folder: string | null): ModuleFolderIndex {
381
  if (folder !== null && !index.folders.some((row) => row.id === folder)) return index;
382
  // Preserve untouched placements, including Sheet's explicit top-level marker.
 
377
  }))] };
378
  }
379
 
380
+ /** S67-T37 (O17): Home folds its Databases through `dataHomeLevel` whenever a connector database
381
+ * is granted, so the two homes cannot disagree about the root. With none, Home keeps its flat
382
+ * list (the NC). Same origin rule as the Data home, applied to every row, filed or not. */
383
+ export function homeDataFolds<T extends DataHomeRow>(rows: readonly T[]): boolean {
384
+ return groupDataDatabases(rows.map((row) => ({ ...row, source: row.sourceGroup ?? row.source })))
385
+ .some((group) => group.label !== "Loopable");
386
+ }
387
+
388
  export function moveModuleItems(index: ModuleFolderIndex, ids: readonly string[], folder: string | null): ModuleFolderIndex {
389
  if (folder !== null && !index.folders.some((row) => row.id === folder)) return index;
390
  // Preserve untouched placements, including Sheet's explicit top-level marker.
web/src/sheet/CellContextMenu.tsx ADDED
@@ -0,0 +1,412 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // sheet/CellContextMenu.tsx — S67-T07 (QI19, R31, 2026-09-28): right-clicking a CELL shows Excel
3
+ // desktop's cell menu, with its mini toolbar above it.
4
+ //
5
+ // ⭐⭐ R31: the labels are Excel's own, Title Case with Excel's ellipses ("Clear Contents",
6
+ // "Format Cells..."), an exception to DESIGN.md §2 for these menus only. Order and separators
7
+ // follow Excel desktop: Cut, Copy, Paste Options, Paste Special... | Insert..., Delete..., Clear
8
+ // Contents | Filter >, Sort > | New Comment, New Note | Format Cells..., Pick From Drop-down
9
+ // List..., Link. Smart Lookup, Translate, Get Data from Table/Range..., Quick Analysis and Define
10
+ // Name... have no Loopable backend and are left out (R31).
11
+ //
12
+ // ⛔ EVERY ITEM RUNS A DOOR THAT ALREADY EXISTS. This file decides nothing about the document: it
13
+ // reports `onAct(<act>)` and `SheetGrid.tsx` routes each act to the clipboard, structure, style,
14
+ // sort, filter, note, link or validation door the ribbon already uses. A second write path here
15
+ // would be two answers to one act.
16
+ //
17
+ // ⚠ A read-only sheet DISABLES the edit items rather than hiding them (the done-when's NC), and an
18
+ // empty clipboard disables Paste; both say why in the item's title.
19
+ // ---------------------------------------------------------------------------
20
+
21
+ import { useEffect, useLayoutEffect, useRef, useState } from "react";
22
+ import type { ComponentProps, KeyboardEvent as ReactKeyboardEvent, ReactNode } from "react";
23
+ import { AnchoredOverlay } from "../customer-grid/OverlaySurface";
24
+ import {
25
+ IconAccounting, IconAlignCenter, IconBorderBottom, IconCellFormat, IconClear, IconCommaStyle,
26
+ IconCopy, IconCut, IconDecimalLess, IconDecimalMore, IconDelete, IconFillColor, IconFontColor,
27
+ IconFormatPainter, IconGrowFont, IconInsert, IconMenuFilter, IconMenuLink, IconMenuSort,
28
+ IconMergeCenter, IconNewComment, IconNewNote, IconPaste, IconPasteFormatting, IconPasteFormulas,
29
+ IconPasteLink, IconPasteSpecial, IconPasteTranspose, IconPasteValues, IconPercentStyle,
30
+ IconPickList, IconRowGroup, IconShrinkFont, IconRowHeight, IconColumnWidth, IconHideBand, IconUnhideBand,
31
+ } from "./ribbonIcons";
32
+ import "../styles/wave67/cell-menu.css";
33
+
34
+ /** Every act the menu can report. `SheetGrid.tsx::onCellMenuAct` owns what each one does. */
35
+ export type CellMenuAct =
36
+ | "cut" | "copy" | "paste" | "paste-values" | "paste-formulas" | "paste-formatting"
37
+ | "paste-special"
38
+ | "insert-right" | "insert-down" | "insert-row" | "insert-col"
39
+ | "delete-left" | "delete-up" | "delete-row" | "delete-col"
40
+ | "clear-contents"
41
+ | "filter-reapply" | "filter-clear" | "filter-value"
42
+ | "sort-asc" | "sort-desc"
43
+ | "new-comment" | "new-note" | "format-cells" | "pick-list" | "link"
44
+ | "bold" | "italic" | "center" | "accounting" | "percent" | "comma"
45
+ | "decimal-more" | "decimal-less" | "grow-font" | "shrink-font" | "format-painter"
46
+ | "fill" | "font-color" | "borders" | "merge-center"
47
+ // S67-T08: the row and column header menus' own acts.
48
+ | "row-height" | "col-width" | "hide-rows" | "hide-cols" | "unhide" | "group-rows" | "ungroup-rows";
49
+
50
+ /** Excel's font size ladder, which Increase and Decrease Font Size step along. */
51
+ export const FONT_SIZE_LADDER = [8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 26, 28, 36, 48, 72] as const;
52
+
53
+ export interface CellContextMenuProps {
54
+ anchor: ComponentProps<typeof AnchoredOverlay>["anchor"];
55
+ /**
56
+ * S67-T08: which surface was right clicked. A cell gets Excel's cell menu; a row or column
57
+ * header gets Excel's row or column menu (Insert, Delete, Row Height... or Column Width...,
58
+ * Hide, Unhide), and the frozen band's headers the same.
59
+ */
60
+ kind?: "cell" | "row" | "column";
61
+ /** Row menu only: the sheet can group rows here, and some rows are grouped already. */
62
+ canGroup?: boolean;
63
+ canUngroup?: boolean;
64
+ /** The workbook is read only for this reader: edit items are shown, disabled. */
65
+ readOnly: boolean;
66
+ /** Nothing has been copied yet, so Paste has nothing to paste. */
67
+ clipboardEmpty: boolean;
68
+ /** A sheet filter is on, so Reapply and Clear Filter have something to act on. */
69
+ filterActive: boolean;
70
+ /** The selection's anchor font and size, shown in the mini toolbar. */
71
+ fontName: string;
72
+ fontSize: number;
73
+ fonts: readonly string[];
74
+ onFont: (name: string) => void;
75
+ onSize: (size: number) => void;
76
+ onAct: (act: CellMenuAct) => void;
77
+ onClose: () => void;
78
+ }
79
+
80
+ type Sub = "filter" | "sort" | null;
81
+ type Ask = "insert" | "delete" | "paste" | null;
82
+
83
+ const READ_ONLY_WHY = "You can view this workbook but not change it.";
84
+
85
+ /** The accessible name of each menu, which is also how a person's screen reader tells them apart. */
86
+ const MENU_LABEL = { cell: "Cell", row: "Row", column: "Column" } as const;
87
+
88
+ /** Excel's Insert, Delete and Paste Special dialogs, each reduced to the choices with a door. */
89
+ const ASK_TITLE: Record<Exclude<Ask, null>, string> = {
90
+ insert: "Insert", delete: "Delete", paste: "Paste Special",
91
+ };
92
+ const SIDEWAYS_WHY = "Cells shift down or up in Loopable today; a sideways shift is not there yet.";
93
+ const ASK_OPTIONS: Record<Exclude<Ask, null>, [string, string, string?][]> = {
94
+ insert: [["right", "Shift cells right", SIDEWAYS_WHY], ["down", "Shift cells down"],
95
+ ["row", "Entire row"], ["col", "Entire column"]],
96
+ delete: [["left", "Shift cells left", SIDEWAYS_WHY], ["up", "Shift cells up"],
97
+ ["row", "Entire row"], ["col", "Entire column"]],
98
+ // The acts themselves, so OK reports the chosen paste directly.
99
+ paste: [["paste", "All"], ["paste-formulas", "Formulas"], ["paste-values", "Values"],
100
+ ["paste-formatting", "Formats"]],
101
+ };
102
+
103
+ export default function CellContextMenu({
104
+ anchor, kind = "cell", canGroup = false, canUngroup = false, readOnly, clipboardEmpty, filterActive,
105
+ fontName, fontSize, fonts, onFont, onSize, onAct, onClose,
106
+ }: CellContextMenuProps) {
107
+ const [sub, setSub] = useState<Sub>(null);
108
+ const [ask, setAsk] = useState<Ask>(null);
109
+ const [shift, setShift] = useState<string>("");
110
+ const listRef = useRef<HTMLDivElement | null>(null);
111
+ const subRef = useRef<HTMLDivElement | null>(null);
112
+ const hoverTimer = useRef(0);
113
+ useEffect(() => () => window.clearTimeout(hoverTimer.current), []);
114
+
115
+ const act = (a: CellMenuAct) => { onClose(); onAct(a); };
116
+
117
+ // Submenu hover intent: open after a short dwell, so a pointer crossing the list does not
118
+ // flicker every submenu it passes (Interaction layer).
119
+ const hoverOpen = (next: Sub) => {
120
+ window.clearTimeout(hoverTimer.current);
121
+ hoverTimer.current = window.setTimeout(() => setSub(next), next ? 160 : 220);
122
+ };
123
+
124
+ // Keyboard: Up and Down walk the enabled items, Right opens a submenu, Left or Escape closes
125
+ // it, Home and End jump. Escape on the main list is the overlay's own dismiss.
126
+ const items = (root: HTMLElement | null) => {
127
+ if (!root) return [];
128
+ const home = root.classList.contains("sheet-cell-submenu") ? root : null;
129
+ return [...root.querySelectorAll<HTMLButtonElement>("[role=menuitem]:not([disabled])")]
130
+ .filter((el) => el.closest(".sheet-cell-submenu") === home);
131
+ };
132
+ const walk = (root: HTMLElement | null, e: ReactKeyboardEvent<HTMLElement>) => {
133
+ const list = items(root);
134
+ const at = list.indexOf(document.activeElement as HTMLButtonElement);
135
+ const go = (i: number) => { e.preventDefault(); list[(i + list.length) % list.length]?.focus(); };
136
+ if (e.key === "ArrowDown") return go(at + 1);
137
+ if (e.key === "ArrowUp") return go(at < 0 ? list.length - 1 : at - 1);
138
+ if (e.key === "Home") return go(0);
139
+ if (e.key === "End") return go(list.length - 1);
140
+ };
141
+ const onListKey = (e: ReactKeyboardEvent<HTMLElement>) => {
142
+ if (ask) return;
143
+ if (sub && subRef.current?.contains(document.activeElement)) {
144
+ if (e.key === "ArrowLeft" || e.key === "Escape") {
145
+ e.preventDefault(); e.stopPropagation();
146
+ const owner = listRef.current?.querySelector<HTMLButtonElement>(`[data-sub="${sub}"]`);
147
+ setSub(null);
148
+ owner?.focus();
149
+ return;
150
+ }
151
+ walk(subRef.current, e);
152
+ return;
153
+ }
154
+ const owner = (document.activeElement as HTMLElement | null)?.dataset?.sub as Sub | undefined;
155
+ if (owner && (e.key === "ArrowRight" || e.key === "Enter" || e.key === " ")) {
156
+ e.preventDefault();
157
+ setSub(owner);
158
+ return;
159
+ }
160
+ walk(listRef.current, e);
161
+ };
162
+ useLayoutEffect(() => {
163
+ if (sub) items(subRef.current)[0]?.focus();
164
+ }, [sub]);
165
+ useLayoutEffect(() => {
166
+ if (!ask) return;
167
+ setShift(ask === "insert" ? "down" : ask === "delete" ? "up" : "paste");
168
+ }, [ask]);
169
+
170
+ const item = (
171
+ label: string, icon: ReactNode, a: CellMenuAct | null,
172
+ opts: { disabled?: boolean; why?: string; sub?: Sub; shortcut?: string } = {},
173
+ ) => (
174
+ <button
175
+ type="button" role="menuitem" className="sheet-cell-menu-item"
176
+ disabled={opts.disabled}
177
+ title={opts.disabled ? opts.why : undefined}
178
+ aria-haspopup={opts.sub ? "menu" : undefined}
179
+ aria-expanded={opts.sub ? sub === opts.sub : undefined}
180
+ data-sub={opts.sub ?? undefined}
181
+ onMouseEnter={() => hoverOpen(opts.sub ?? null)}
182
+ onClick={() => {
183
+ if (opts.sub) { setSub(sub === opts.sub ? null : opts.sub); return; }
184
+ if (a) act(a);
185
+ }}
186
+ >
187
+ <span className="sheet-cell-menu-icon-slot">{icon}</span>
188
+ <span className="sheet-cell-menu-label">{label}</span>
189
+ {opts.shortcut && <span className="sheet-cell-menu-shortcut">{opts.shortcut}</span>}
190
+ {opts.sub && (
191
+ <svg className="sheet-cell-menu-chevron" viewBox="0 0 16 16" aria-hidden="true">
192
+ <path d="M6 3.5l4.5 4.5L6 12.5" />
193
+ </svg>
194
+ )}
195
+ </button>
196
+ );
197
+ const sep = (key: string) => <div key={key} className="sheet-cell-menu-sep" role="separator" />;
198
+ const edit = { disabled: readOnly, why: READ_ONLY_WHY };
199
+ const pasteGate = readOnly
200
+ ? { disabled: true, why: READ_ONLY_WHY }
201
+ : clipboardEmpty
202
+ ? { disabled: true, why: "There is nothing on the clipboard to paste." }
203
+ : { disabled: false };
204
+ const pasteOption = (label: string, icon: ReactNode, a: CellMenuAct | null, why?: string) => (
205
+ <button
206
+ type="button" role="menuitem" className="sheet-cell-menu-paste"
207
+ aria-label={label} title={why ?? label}
208
+ disabled={pasteGate.disabled || a === null}
209
+ onMouseEnter={() => hoverOpen(null)}
210
+ onClick={() => a && act(a)}
211
+ >
212
+ {icon}
213
+ </button>
214
+ );
215
+ const mini = (label: string, icon: ReactNode, a: CellMenuAct) => (
216
+ <button
217
+ type="button" className="sheet-cell-mini-btn" aria-label={label} title={label}
218
+ disabled={readOnly} onClick={() => act(a)}
219
+ >
220
+ {icon}
221
+ </button>
222
+ );
223
+
224
+ return (
225
+ <AnchoredOverlay
226
+ anchor={anchor}
227
+ className="cg-pop sheet-cell-menu-pop"
228
+ placement="bottom-start"
229
+ role="menu"
230
+ ariaLabel={MENU_LABEL[kind]}
231
+ onDismiss={onClose}
232
+ onKeyDown={onListKey}
233
+ >
234
+ {/* ⭐ EXCEL'S MINI TOOLBAR, ABOVE THE MENU: font, size, grow and shrink, Accounting,
235
+ Percent, Comma, Format Painter on the first row; Bold, Italic, Center, Borders, Fill,
236
+ Font Color, the two decimals and Merge and Center on the second. */}
237
+ <div className="sheet-cell-mini" role="toolbar" aria-label="Formatting">
238
+ <div className="sheet-cell-mini-row">
239
+ <select className="sheet-cell-mini-font" aria-label="Font" value={fontName}
240
+ disabled={readOnly} onChange={(e) => { onClose(); onFont(e.currentTarget.value); }}>
241
+ {fonts.map((f) => <option key={f} value={f}>{f}</option>)}
242
+ </select>
243
+ <select className="sheet-cell-mini-size" aria-label="Font Size" value={String(fontSize)}
244
+ disabled={readOnly} onChange={(e) => { onClose(); onSize(Number(e.currentTarget.value)); }}>
245
+ {[...new Set([...FONT_SIZE_LADDER, fontSize])].sort((a, b) => a - b)
246
+ .map((s) => <option key={s} value={String(s)}>{s}</option>)}
247
+ </select>
248
+ {mini("Increase Font Size", <IconGrowFont />, "grow-font")}
249
+ {mini("Decrease Font Size", <IconShrinkFont />, "shrink-font")}
250
+ {mini("Accounting Number Format", <IconAccounting />, "accounting")}
251
+ {mini("Percent Style", <IconPercentStyle />, "percent")}
252
+ {mini("Comma Style", <IconCommaStyle />, "comma")}
253
+ {mini("Format Painter", <IconFormatPainter />, "format-painter")}
254
+ </div>
255
+ <div className="sheet-cell-mini-row">
256
+ <button type="button" className="sheet-cell-mini-btn sheet-cell-mini-b" aria-label="Bold"
257
+ title="Bold" disabled={readOnly} onClick={() => act("bold")}>B</button>
258
+ <button type="button" className="sheet-cell-mini-btn sheet-cell-mini-i" aria-label="Italic"
259
+ title="Italic" disabled={readOnly} onClick={() => act("italic")}>I</button>
260
+ {mini("Center", <IconAlignCenter />, "center")}
261
+ {mini("Borders", <IconBorderBottom />, "borders")}
262
+ {mini("Fill Color", <IconFillColor />, "fill")}
263
+ {mini("Font Color", <IconFontColor />, "font-color")}
264
+ {mini("Increase Decimal", <IconDecimalMore />, "decimal-more")}
265
+ {mini("Decrease Decimal", <IconDecimalLess />, "decimal-less")}
266
+ {mini("Merge and Center", <IconMergeCenter />, "merge-center")}
267
+ </div>
268
+ </div>
269
+
270
+ {ask ? (
271
+ <div className="sheet-cell-menu-ask" role="dialog" aria-label={ASK_TITLE[ask]}>
272
+ <div className="sheet-cell-menu-ask-title">{ASK_TITLE[ask]}</div>
273
+ {ASK_OPTIONS[ask].map(([value, label, why]) => (
274
+ <label key={value} className="sheet-cell-menu-ask-option" title={why}>
275
+ <input type="radio" name="sheet-cell-shift" value={value} checked={shift === value}
276
+ disabled={Boolean(why)} onChange={() => setShift(value)} />
277
+ <span>{label}</span>
278
+ </label>
279
+ ))}
280
+ <div className="sheet-cell-menu-ask-actions">
281
+ <button type="button" className="sheet-cell-menu-ask-ok" onClick={() => {
282
+ act((ask === "paste" ? shift : `${ask}-${shift}`) as CellMenuAct);
283
+ }}>OK</button>
284
+ <button type="button" className="sheet-cell-menu-ask-cancel" onClick={onClose}>Cancel</button>
285
+ </div>
286
+ </div>
287
+ ) : kind !== "cell" ? (
288
+ <div className="sheet-cell-menu" ref={listRef}>
289
+ {item("Cut", <IconCut />, "cut", edit)}
290
+ {item("Copy", <IconCopy />, "copy")}
291
+ <div className="sheet-cell-menu-heading">
292
+ <span className="sheet-cell-menu-icon-slot"><IconPaste /></span>
293
+ <span className="sheet-cell-menu-label">Paste Options:</span>
294
+ </div>
295
+ <div className="sheet-cell-menu-paste-row" role="group" aria-label="Paste Options">
296
+ {pasteOption("Paste", <IconPaste />, "paste")}
297
+ {pasteOption("Values", <IconPasteValues />, "paste-values")}
298
+ {pasteOption("Formulas", <IconPasteFormulas />, "paste-formulas")}
299
+ {pasteOption("Transpose", <IconPasteTranspose />, null,
300
+ "Transpose is not available in Loopable yet.")}
301
+ {pasteOption("Formatting", <IconPasteFormatting />, "paste-formatting")}
302
+ {pasteOption("Paste Link", <IconPasteLink />, null,
303
+ "Paste Link is not available in Loopable yet.")}
304
+ </div>
305
+ <button
306
+ type="button" role="menuitem" className="sheet-cell-menu-item"
307
+ disabled={pasteGate.disabled} title={pasteGate.disabled ? pasteGate.why : undefined}
308
+ onClick={() => setAsk("paste")}
309
+ >
310
+ <span className="sheet-cell-menu-icon-slot"><IconPasteSpecial /></span>
311
+ <span className="sheet-cell-menu-label">Paste Special...</span>
312
+ </button>
313
+ {sep("h1")}
314
+ {item("Insert", <IconInsert />, kind === "row" ? "insert-row" : "insert-col", edit)}
315
+ {item("Delete", <IconDelete />, kind === "row" ? "delete-row" : "delete-col", edit)}
316
+ {item("Clear Contents", <IconClear />, "clear-contents", edit)}
317
+ {sep("h2")}
318
+ {item("Format Cells...", <IconCellFormat />, "format-cells", { ...edit, shortcut: "Ctrl+1" })}
319
+ {kind === "row"
320
+ ? item("Row Height...", <IconRowHeight />, "row-height", edit)
321
+ : item("Column Width...", <IconColumnWidth />, "col-width", edit)}
322
+ {item("Hide", <IconHideBand column={kind === "column"} />, kind === "row" ? "hide-rows" : "hide-cols", edit)}
323
+ {item("Unhide", <IconUnhideBand column={kind === "column"} />, "unhide", edit)}
324
+ {kind === "row" && (canGroup || canUngroup) && sep("h3")}
325
+ {/* ⚠ NOT IN EXCEL'S ROW MENU. Kept because this tree's Data ribbon has no Group
326
+ control (its Outline group holds Hide and Unhide only), so this is the only mouse
327
+ door to row grouping; S67-T08's record names it. */}
328
+ {kind === "row" && canGroup && item("Group rows", <IconRowGroup collapsed={false} />, "group-rows", edit)}
329
+ {kind === "row" && canUngroup && item("Ungroup rows", <IconRowGroup collapsed />, "ungroup-rows", edit)}
330
+ </div>
331
+ ) : (
332
+ <div className="sheet-cell-menu" ref={listRef} onMouseLeave={() => window.clearTimeout(hoverTimer.current)}>
333
+ {item("Cut", <IconCut />, "cut", edit)}
334
+ {item("Copy", <IconCopy />, "copy")}
335
+ <div className="sheet-cell-menu-heading" onMouseEnter={() => hoverOpen(null)}>
336
+ <span className="sheet-cell-menu-icon-slot">
337
+ <IconPaste />
338
+ </span>
339
+ <span className="sheet-cell-menu-label">Paste Options:</span>
340
+ </div>
341
+ <div className="sheet-cell-menu-paste-row" role="group" aria-label="Paste Options">
342
+ {pasteOption("Paste", <IconPaste />, "paste")}
343
+ {pasteOption("Values", <IconPasteValues />, "paste-values")}
344
+ {pasteOption("Formulas", <IconPasteFormulas />, "paste-formulas")}
345
+ {pasteOption("Transpose", <IconPasteTranspose />, null,
346
+ "Transpose is not available in Loopable yet.")}
347
+ {pasteOption("Formatting", <IconPasteFormatting />, "paste-formatting")}
348
+ {pasteOption("Paste Link", <IconPasteLink />, null,
349
+ "Paste Link is not available in Loopable yet.")}
350
+ </div>
351
+ <button
352
+ type="button" role="menuitem" className="sheet-cell-menu-item"
353
+ disabled={pasteGate.disabled} title={pasteGate.disabled ? pasteGate.why : undefined}
354
+ onMouseEnter={() => hoverOpen(null)} onClick={() => setAsk("paste")}
355
+ >
356
+ <span className="sheet-cell-menu-icon-slot"><IconPasteSpecial /></span>
357
+ <span className="sheet-cell-menu-label">Paste Special...</span>
358
+ </button>
359
+ {sep("s1")}
360
+ <button
361
+ type="button" role="menuitem" className="sheet-cell-menu-item" disabled={readOnly}
362
+ title={readOnly ? READ_ONLY_WHY : undefined}
363
+ onMouseEnter={() => hoverOpen(null)} onClick={() => setAsk("insert")}
364
+ >
365
+ <span className="sheet-cell-menu-icon-slot"><IconInsert /></span>
366
+ <span className="sheet-cell-menu-label">Insert...</span>
367
+ </button>
368
+ <button
369
+ type="button" role="menuitem" className="sheet-cell-menu-item" disabled={readOnly}
370
+ title={readOnly ? READ_ONLY_WHY : undefined}
371
+ onMouseEnter={() => hoverOpen(null)} onClick={() => setAsk("delete")}
372
+ >
373
+ <span className="sheet-cell-menu-icon-slot"><IconDelete /></span>
374
+ <span className="sheet-cell-menu-label">Delete...</span>
375
+ </button>
376
+ {item("Clear Contents", <IconClear />, "clear-contents", edit)}
377
+ {sep("s2")}
378
+ <div className="sheet-cell-menu-subwrap">
379
+ {item("Filter", <IconMenuFilter />, null, { sub: "filter" })}
380
+ {sub === "filter" && (
381
+ <div className="sheet-cell-submenu" role="menu" aria-label="Filter" ref={subRef}
382
+ onMouseEnter={() => window.clearTimeout(hoverTimer.current)}>
383
+ {item("Reapply", <IconMenuFilter />, "filter-reapply",
384
+ { disabled: !filterActive, why: "No filter is on in this sheet." })}
385
+ {item("Clear Filter", <IconClear />, "filter-clear",
386
+ { disabled: !filterActive, why: "No filter is on in this sheet." })}
387
+ {item("Filter by Selected Cell's Value", <IconMenuFilter />, "filter-value")}
388
+ </div>
389
+ )}
390
+ </div>
391
+ <div className="sheet-cell-menu-subwrap">
392
+ {item("Sort", <IconMenuSort />, null, { sub: "sort" })}
393
+ {sub === "sort" && (
394
+ <div className="sheet-cell-submenu" role="menu" aria-label="Sort" ref={subRef}
395
+ onMouseEnter={() => window.clearTimeout(hoverTimer.current)}>
396
+ {item("Sort A to Z", <IconMenuSort />, "sort-asc", edit)}
397
+ {item("Sort Z to A", <IconMenuSort />, "sort-desc", edit)}
398
+ </div>
399
+ )}
400
+ </div>
401
+ {sep("s3")}
402
+ {item("New Comment", <IconNewComment />, "new-comment", edit)}
403
+ {item("New Note", <IconNewNote />, "new-note", edit)}
404
+ {sep("s4")}
405
+ {item("Format Cells...", <IconCellFormat />, "format-cells", { ...edit, shortcut: "Ctrl+1" })}
406
+ {item("Pick From Drop-down List...", <IconPickList />, "pick-list", edit)}
407
+ {item("Link", <IconMenuLink />, "link", edit)}
408
+ </div>
409
+ )}
410
+ </AnchoredOverlay>
411
+ );
412
+ }
web/src/sheet/FormatCellsDialog.tsx ADDED
@@ -0,0 +1,582 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // sheet/FormatCellsDialog.tsx — Excel's Format Cells dialog, Number and Border tabs (S67-T16,
2
+ // instruction 16, J16, contract C3).
3
+ //
4
+ // ⭐ WHO OPENS IT. "More Borders..." in the Borders gallery, and lane A's right-click "Format
5
+ // Cells...", both raise `aios:sheet-format-cells` `{detail: {tab}}` (C3). `ribbonHome.tsx` owns the
6
+ // one listener and MOUNTS this component; this file only draws the dialog and hands back ONE
7
+ // patch. It holds no document state: the draft lives here until OK, and Cancel drops it whole.
8
+ //
9
+ // ⭐⭐ ONE RANGE EDIT, NAMING ONLY WHAT THE PERSON TOUCHED. The Border tab keeps a draft of
10
+ // S67-T14's `CellBorderEdit["edges"]`: an edge the person SET carries a line, an edge they
11
+ // CLEARED carries `null`, and an edge they never touched is simply ABSENT, so
12
+ // `cellStyleOps.ts::styleCells` leaves it exactly as it is. OK sends that draft once, beside the
13
+ // Number tab's `format` when that tab was changed too, so the whole dialog is one commit and one
14
+ // undo step.
15
+ //
16
+ // ⚠ THE SHELL IS THE KIT'S `ui/ConfirmDialog.tsx`, which registers through `useOverlayLayer`:
17
+ // Escape and the close button cancel, focus is trapped and returns to the opener, and a stray
18
+ // press on the scrim never discards the draft. No keydown listener for Escape lives here.
19
+ //
20
+ // ⚠ DESIGN CONTRACT (DESIGN.md 2 through 4): chrome in sentence case except Excel's own names
21
+ // ("Format Cells", the tab names, the preset names), inline SVG on `currentColor`, tokens for
22
+ // every chrome colour. The line colours are the person's DATA (DESIGN.md 3) and are painted as
23
+ // the hex they are. No em dash or en dash in any string that reaches a screen.
24
+
25
+ import { useId, useState } from "react";
26
+ import type { KeyboardEvent as ReactKeyboardEvent, ReactNode } from "react";
27
+ import { ConfirmDialog } from "../ui/ConfirmDialog";
28
+ import {
29
+ IconBorderBottom, IconBorderLeft, IconBorderNone, IconBorderOutside, IconBorderRight,
30
+ IconBorderTop, LineStyleSample,
31
+ } from "./borderIcons";
32
+ import { CELL_BORDER_STYLES, DEFAULT_BORDER_LINE, formatCellText } from "./types";
33
+ import type {
34
+ Cell, CellBorderEdge, CellBorderEdit, CellBorderLine, CellBorderStyle, CellFormat,
35
+ CellFormatKind, CellStyle, CellStylePatch,
36
+ } from "./types";
37
+ import "../styles/wave67/format-cells.css";
38
+
39
+ export type FormatCellsTab = "number" | "border";
40
+
41
+ export interface FormatCellsDialogProps {
42
+ /** The tab the request named. */
43
+ tab: FormatCellsTab;
44
+ /** The ANCHOR cell's style, as the ribbon reads it. */
45
+ style: CellStyle | null;
46
+ /** The line the dialog starts with: the ribbon's session pen. */
47
+ line: CellBorderLine;
48
+ /** T15's Standard Colors row, handed in so there is one list, not two. */
49
+ lineColors: readonly { hex: string; label: string }[];
50
+ lineStyleLabel: Record<CellBorderStyle, string>;
51
+ /** ONE patch for the selection. Called only when something changed. */
52
+ onApply: (patch: CellStylePatch) => void;
53
+ onClose: () => void;
54
+ }
55
+
56
+ type EdgeDraft = CellBorderEdit["edges"];
57
+
58
+ const LINE_HEX = /^#[0-9a-f]{6}$/;
59
+
60
+ /** Excel's dialog order and names for the five kinds the document carries. */
61
+ const CATEGORIES: { kind: CellFormatKind; label: string }[] = [
62
+ { kind: "general", label: "General" },
63
+ { kind: "number", label: "Number" },
64
+ { kind: "currency", label: "Currency" },
65
+ { kind: "date", label: "Date" },
66
+ { kind: "percent", label: "Percentage" },
67
+ ];
68
+
69
+ /** The ribbon's own defaults when a kind is chosen (`ribbonHome.tsx`, Number Format menu). */
70
+ const defaultDecimals = (kind: CellFormatKind): number | undefined =>
71
+ kind === "currency" ? 2 : kind === "date" || kind === "general" ? undefined : 0;
72
+
73
+ const hasDecimals = (kind: CellFormatKind) =>
74
+ kind === "number" || kind === "currency" || kind === "percent";
75
+
76
+ const EDGE_LABEL: Record<CellBorderEdge, string> = {
77
+ top: "Top border",
78
+ insideH: "Inside horizontal border",
79
+ bottom: "Bottom border",
80
+ left: "Left border",
81
+ insideV: "Inside vertical border",
82
+ right: "Right border",
83
+ };
84
+
85
+ const OUTER: CellBorderEdge[] = ["top", "bottom", "left", "right"];
86
+ const INSIDE: CellBorderEdge[] = ["insideH", "insideV"];
87
+ const ALL_EDGES: CellBorderEdge[] = [...OUTER, ...INSIDE];
88
+
89
+ const sameLine = (a: CellBorderLine, b: CellBorderLine) =>
90
+ a.style === b.style && a.color === b.color;
91
+
92
+ /**
93
+ * The anchor cell's value, for the Number tab's sample. The ribbon context carries the anchor's
94
+ * STYLE and not its value, so the sample reads what the formula bar shows for the anchor. A
95
+ * formula (its text starts with "=") or a blank cell falls back to a stated sample figure.
96
+ */
97
+ const anchorSample = (): { text: string; fromCell: boolean } => {
98
+ const bar = document.querySelector<HTMLTextAreaElement | HTMLInputElement>(
99
+ 'textarea[aria-label="Formula"], input[aria-label="Formula"]',
100
+ );
101
+ const text = bar?.value?.trim() ?? "";
102
+ if (!text || text.startsWith("=")) return { text: "", fromCell: false };
103
+ return { text, fromCell: true };
104
+ };
105
+
106
+ const sampleText = (raw: string, format: CellFormat | null): string => {
107
+ const numeric = raw !== "" && Number.isFinite(Number(raw.replace(/,/g, "")));
108
+ const text = raw || (format?.kind === "date" ? new Date().toISOString().slice(0, 10) : "1234.5");
109
+ const value: unknown = numeric ? Number(raw.replace(/,/g, "")) : raw ? raw : text;
110
+ const cell: Cell = {
111
+ kind: "literal",
112
+ state: "fresh",
113
+ text,
114
+ value,
115
+ style: format ? { format } : undefined,
116
+ };
117
+ return formatCellText(cell, text);
118
+ };
119
+
120
+ // ── icons the gallery file does not carry, drawn in its house style ─────────────────────────────
121
+ // `borderIcons.tsx` is S67-T15's file and has no Inside icon; these follow its cell exactly:
122
+ // an 11 by 11 box split in four, faint dotted grid, solid where the control writes.
123
+ const GRID = "M2.5 2.5H13.5M2.5 13.5H13.5M2.5 2.5V13.5M13.5 2.5V13.5M2.5 8H13.5M8 2.5V13.5";
124
+
125
+ function InsideIcon({ h, v }: { h: boolean; v: boolean }) {
126
+ return (
127
+ <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon sheet-border-icon">
128
+ <path d={GRID} strokeWidth="1" strokeDasharray="0.6 1.6" opacity="0.5" />
129
+ {h && <path d="M2.5 8H13.5" />}
130
+ {v && <path d="M8 2.5V13.5" />}
131
+ </svg>
132
+ );
133
+ }
134
+
135
+ const EDGE_ICON: Record<CellBorderEdge, () => ReactNode> = {
136
+ top: () => <IconBorderTop />,
137
+ insideH: () => <InsideIcon h v={false} />,
138
+ bottom: () => <IconBorderBottom />,
139
+ left: () => <IconBorderLeft />,
140
+ insideV: () => <InsideIcon h={false} v />,
141
+ right: () => <IconBorderRight />,
142
+ };
143
+
144
+ // ── the preview: a 2 by 2 block, so both inside edges exist ─────────────────────────────────────
145
+ const PX0 = 16;
146
+ const PX1 = 144;
147
+ const PY0 = 12;
148
+ const PY1 = 92;
149
+ const PXM = (PX0 + PX1) / 2;
150
+ const PYM = (PY0 + PY1) / 2;
151
+
152
+ const EDGE_SEGMENT: Record<CellBorderEdge, [number, number, number, number]> = {
153
+ top: [PX0, PY0, PX1, PY0],
154
+ bottom: [PX0, PY1, PX1, PY1],
155
+ left: [PX0, PY0, PX0, PY1],
156
+ right: [PX1, PY0, PX1, PY1],
157
+ insideH: [PX0, PYM, PX1, PYM],
158
+ insideV: [PXM, PY0, PXM, PY1],
159
+ };
160
+
161
+ /** One edge in its line, drawn the way `cellBorders.ts::paintCellBorders` paints it. */
162
+ function PreviewLine({ edge, line }: { edge: CellBorderEdge; line: CellBorderLine }) {
163
+ const [x1, y1, x2, y2] = EDGE_SEGMENT[edge];
164
+ const common = { stroke: line.color, fill: "none", strokeLinecap: "butt" as const };
165
+ if (line.style === "double") {
166
+ const horizontal = y1 === y2;
167
+ const dx = horizontal ? 0 : 1.6;
168
+ const dy = horizontal ? 1.6 : 0;
169
+ return (
170
+ <path
171
+ d={`M${x1 - dx} ${y1 - dy}L${x2 - dx} ${y2 - dy}M${x1 + dx} ${y1 + dy}L${x2 + dx} ${y2 + dy}`}
172
+ strokeWidth="1"
173
+ {...common}
174
+ />
175
+ );
176
+ }
177
+ const width = line.style === "medium" ? 2 : line.style === "thick" ? 3 : 1;
178
+ const dash = line.style === "dashed" ? "5 3"
179
+ : line.style === "dotted" ? "1 2"
180
+ : line.style === "hair" ? "1 1" : undefined;
181
+ return (
182
+ <path
183
+ d={`M${x1} ${y1}L${x2} ${y2}`}
184
+ strokeWidth={width}
185
+ strokeDasharray={dash}
186
+ opacity={line.style === "hair" ? 0.7 : undefined}
187
+ {...common}
188
+ />
189
+ );
190
+ }
191
+
192
+ /** A roving arrow-key handler for a row of radios or tabs: moves the choice and the focus. */
193
+ const rovingKeys = <T,>(
194
+ values: readonly T[],
195
+ current: T,
196
+ choose: (next: T) => void,
197
+ ) => (e: ReactKeyboardEvent<HTMLElement>) => {
198
+ const forward = e.key === "ArrowRight" || e.key === "ArrowDown";
199
+ const back = e.key === "ArrowLeft" || e.key === "ArrowUp";
200
+ if (!forward && !back && e.key !== "Home" && e.key !== "End") return;
201
+ e.preventDefault();
202
+ e.stopPropagation();
203
+ const at = Math.max(0, values.indexOf(current));
204
+ const next = e.key === "Home" ? 0
205
+ : e.key === "End" ? values.length - 1
206
+ : (at + (forward ? 1 : -1) + values.length) % values.length;
207
+ choose(values[next]);
208
+ const group = e.currentTarget;
209
+ window.requestAnimationFrame(() => {
210
+ group.querySelector<HTMLElement>('[aria-checked="true"], [aria-selected="true"]')?.focus();
211
+ });
212
+ };
213
+
214
+ export function FormatCellsDialog({
215
+ tab, style, line: startLine, lineColors, lineStyleLabel, onApply, onClose,
216
+ }: FormatCellsDialogProps) {
217
+ const ids = useId();
218
+ const [active, setActive] = useState<FormatCellsTab>(tab);
219
+
220
+ // ── Number tab draft ──
221
+ const startFormat = style?.format ?? null;
222
+ const [kind, setKind] = useState<CellFormatKind>(startFormat?.kind ?? "general");
223
+ const [decimals, setDecimals] = useState<number>(
224
+ startFormat?.decimals ?? defaultDecimals(startFormat?.kind ?? "general") ?? 0,
225
+ );
226
+ const [thousands, setThousands] = useState<boolean>(startFormat?.thousands === true);
227
+ const [numberTouched, setNumberTouched] = useState(false);
228
+ const [sample] = useState(anchorSample);
229
+
230
+ // ── Border tab draft ──
231
+ const [line, setLine] = useState<CellBorderLine>(
232
+ LINE_HEX.test(startLine.color) ? startLine : { ...DEFAULT_BORDER_LINE },
233
+ );
234
+ const [edges, setEdges] = useState<EdgeDraft>({});
235
+
236
+ const chooseKind = (next: CellFormatKind) => {
237
+ setKind(next);
238
+ setDecimals(defaultDecimals(next) ?? 0);
239
+ setNumberTouched(true);
240
+ };
241
+
242
+ const draftFormat = (): CellFormat | null => {
243
+ if (kind === "general") return null;
244
+ const next: CellFormat = { kind };
245
+ if (hasDecimals(kind)) next.decimals = decimals;
246
+ if (kind === "number") next.thousands = thousands;
247
+ if (kind === "currency" && startFormat?.kind === "currency" && startFormat.currency) {
248
+ next.currency = startFormat.currency;
249
+ }
250
+ return next;
251
+ };
252
+
253
+ const toggleEdge = (edge: CellBorderEdge) => {
254
+ setEdges((was) => {
255
+ const current = was[edge];
256
+ return { ...was, [edge]: current && sameLine(current, line) ? null : { ...line } };
257
+ });
258
+ };
259
+
260
+ const preset = (which: "none" | "outline" | "inside") => {
261
+ setEdges((was) => {
262
+ const next: EdgeDraft = { ...was };
263
+ if (which === "none") for (const edge of ALL_EDGES) next[edge] = null;
264
+ else for (const edge of which === "outline" ? OUTER : INSIDE) next[edge] = { ...line };
265
+ return next;
266
+ });
267
+ };
268
+
269
+ const confirm = () => {
270
+ const patch: CellStylePatch = {};
271
+ if (numberTouched) patch.format = draftFormat();
272
+ if (Object.keys(edges).length > 0) patch.border = { edges: { ...edges } };
273
+ if (Object.keys(patch).length === 0) onClose();
274
+ else onApply(patch);
275
+ };
276
+
277
+ const edgeState = (edge: CellBorderEdge) =>
278
+ edges[edge] === undefined ? "unchanged" : edges[edge] === null ? "cleared" : "set";
279
+
280
+ const edgeButton = (edge: CellBorderEdge) => {
281
+ const state = edgeState(edge);
282
+ return (
283
+ <button
284
+ key={edge}
285
+ type="button"
286
+ className={"sheet-format-cells-edge is-" + state}
287
+ aria-pressed={state === "set"}
288
+ aria-label={`${EDGE_LABEL[edge]}, ${state}`}
289
+ title={EDGE_LABEL[edge]}
290
+ data-edge={edge}
291
+ onClick={() => toggleEdge(edge)}
292
+ >
293
+ {EDGE_ICON[edge]()}
294
+ </button>
295
+ );
296
+ };
297
+
298
+ const tabs: { id: FormatCellsTab; label: string }[] = [
299
+ { id: "number", label: "Number" },
300
+ { id: "border", label: "Border" },
301
+ ];
302
+ const tabId = (id: FormatCellsTab) => `${ids}-tab-${id}`;
303
+ const panelId = (id: FormatCellsTab) => `${ids}-panel-${id}`;
304
+
305
+ const numberPanel = (
306
+ <div className="sheet-format-cells-number">
307
+ <div className="sheet-format-cells-col">
308
+ <span className="sheet-format-cells-heading" id={`${ids}-category`}>Category</span>
309
+ <div
310
+ role="radiogroup"
311
+ aria-labelledby={`${ids}-category`}
312
+ className="sheet-format-cells-list"
313
+ onKeyDown={rovingKeys(CATEGORIES.map((c) => c.kind), kind, chooseKind)}
314
+ >
315
+ {CATEGORIES.map((entry) => (
316
+ <button
317
+ key={entry.kind}
318
+ type="button"
319
+ role="radio"
320
+ aria-checked={entry.kind === kind}
321
+ tabIndex={entry.kind === kind ? 0 : -1}
322
+ className={"sheet-format-cells-option" + (entry.kind === kind ? " is-on" : "")}
323
+ onClick={() => chooseKind(entry.kind)}
324
+ >
325
+ {entry.label}
326
+ </button>
327
+ ))}
328
+ </div>
329
+ </div>
330
+ <div className="sheet-format-cells-col sheet-format-cells-detail">
331
+ <span className="sheet-format-cells-heading">Sample</span>
332
+ <output className="sheet-format-cells-sample" aria-live="polite">
333
+ {sampleText(sample.text, draftFormat())}
334
+ </output>
335
+ {!sample.fromCell && (
336
+ <p className="sheet-format-cells-note">A sample figure: the active cell holds no typed value.</p>
337
+ )}
338
+ {hasDecimals(kind) && (
339
+ <label className="sheet-format-cells-field">
340
+ <span>Decimal places</span>
341
+ <input
342
+ type="number"
343
+ min={0}
344
+ max={10}
345
+ step={1}
346
+ value={decimals}
347
+ className="sheet-format-cells-input"
348
+ onChange={(e) => {
349
+ const n = Math.round(Number(e.currentTarget.value));
350
+ setDecimals(Number.isFinite(n) ? Math.min(10, Math.max(0, n)) : 0);
351
+ setNumberTouched(true);
352
+ }}
353
+ />
354
+ </label>
355
+ )}
356
+ {kind === "number" && (
357
+ <label className="sheet-format-cells-check">
358
+ <input
359
+ type="checkbox"
360
+ checked={thousands}
361
+ onChange={(e) => {
362
+ setThousands(e.currentTarget.checked);
363
+ setNumberTouched(true);
364
+ }}
365
+ />
366
+ <span>Use 1000 separator (,)</span>
367
+ </label>
368
+ )}
369
+ {kind === "general" && (
370
+ <p className="sheet-format-cells-note">General cells show the value as it was typed.</p>
371
+ )}
372
+ </div>
373
+ </div>
374
+ );
375
+
376
+ const colorChoices = [{ hex: DEFAULT_BORDER_LINE.color, label: "Automatic" }, ...lineColors];
377
+
378
+ const borderPanel = (
379
+ <div className="sheet-format-cells-border">
380
+ <div className="sheet-format-cells-col">
381
+ <span className="sheet-format-cells-heading">Line</span>
382
+ <span className="sheet-format-cells-sub" id={`${ids}-style`}>Style</span>
383
+ <div
384
+ role="radiogroup"
385
+ aria-labelledby={`${ids}-style`}
386
+ className="sheet-format-cells-list sheet-format-cells-styles"
387
+ onKeyDown={rovingKeys(CELL_BORDER_STYLES, line.style, (s) => setLine((l) => ({ ...l, style: s })))}
388
+ >
389
+ {CELL_BORDER_STYLES.map((s) => (
390
+ <button
391
+ key={s}
392
+ type="button"
393
+ role="radio"
394
+ aria-checked={line.style === s}
395
+ aria-label={lineStyleLabel[s]}
396
+ title={lineStyleLabel[s]}
397
+ tabIndex={line.style === s ? 0 : -1}
398
+ className={"sheet-format-cells-option sheet-format-cells-style"
399
+ + (line.style === s ? " is-on" : "")}
400
+ onClick={() => setLine((l) => ({ ...l, style: s }))}
401
+ >
402
+ <LineStyleSample style={s} />
403
+ </button>
404
+ ))}
405
+ </div>
406
+ <span className="sheet-format-cells-sub" id={`${ids}-color`}>Color</span>
407
+ <div
408
+ role="radiogroup"
409
+ aria-labelledby={`${ids}-color`}
410
+ className="sheet-format-cells-swatches"
411
+ onKeyDown={rovingKeys(
412
+ colorChoices.map((c) => c.hex),
413
+ line.color,
414
+ (hex) => setLine((l) => ({ ...l, color: hex })),
415
+ )}
416
+ >
417
+ {colorChoices.map((entry, at) => {
418
+ const on = line.color === entry.hex;
419
+ const roving = on || (at === 0 && !colorChoices.some((c) => c.hex === line.color));
420
+ return (
421
+ <button
422
+ key={entry.label}
423
+ type="button"
424
+ role="radio"
425
+ aria-checked={on}
426
+ aria-label={entry.label}
427
+ title={entry.label}
428
+ tabIndex={roving ? 0 : -1}
429
+ className={"sheet-format-cells-swatch" + (on ? " is-on" : "")}
430
+ onClick={() => setLine((l) => ({ ...l, color: entry.hex }))}
431
+ >
432
+ <span className="sheet-format-cells-chip" style={{ background: entry.hex }} />
433
+ </button>
434
+ );
435
+ })}
436
+ </div>
437
+ <label className="sheet-format-cells-field sheet-format-cells-custom">
438
+ <input
439
+ type="color"
440
+ aria-label="More colors"
441
+ className="sheet-format-cells-color"
442
+ value={line.color}
443
+ onChange={(e) => {
444
+ const hex = e.currentTarget.value.toLowerCase();
445
+ if (LINE_HEX.test(hex)) setLine((l) => ({ ...l, color: hex }));
446
+ }}
447
+ />
448
+ <span>More colors...</span>
449
+ </label>
450
+ </div>
451
+ <div className="sheet-format-cells-col">
452
+ <span className="sheet-format-cells-heading" id={`${ids}-presets`}>Presets</span>
453
+ <div className="sheet-format-cells-presets" role="group" aria-labelledby={`${ids}-presets`}>
454
+ <button type="button" className="sheet-format-cells-preset" onClick={() => preset("none")}>
455
+ <IconBorderNone />
456
+ <span>None</span>
457
+ </button>
458
+ <button type="button" className="sheet-format-cells-preset" onClick={() => preset("outline")}>
459
+ <IconBorderOutside />
460
+ <span>Outline</span>
461
+ </button>
462
+ <button type="button" className="sheet-format-cells-preset" onClick={() => preset("inside")}>
463
+ <InsideIcon h v />
464
+ <span>Inside</span>
465
+ </button>
466
+ </div>
467
+ <span className="sheet-format-cells-heading" id={`${ids}-border`}>Border</span>
468
+ <div className="sheet-format-cells-board" role="group" aria-labelledby={`${ids}-border`}>
469
+ <div className="sheet-format-cells-edges is-rows">
470
+ {edgeButton("top")}
471
+ {edgeButton("insideH")}
472
+ {edgeButton("bottom")}
473
+ </div>
474
+ <svg
475
+ viewBox={`0 0 ${PX1 + PX0} ${PY1 + PY0}`}
476
+ className="sheet-format-cells-preview"
477
+ aria-hidden="true"
478
+ >
479
+ {/* Excel's corner ticks: where each edge would run, drawn faint. */}
480
+ {ALL_EDGES.map((edge) => {
481
+ if (edges[edge]) return null;
482
+ const [x1, y1, x2, y2] = EDGE_SEGMENT[edge];
483
+ return (
484
+ <path
485
+ key={`guide-${edge}`}
486
+ d={`M${x1} ${y1}L${x2} ${y2}`}
487
+ className={"sheet-format-cells-guide" + (edges[edge] === null ? " is-cleared" : "")}
488
+ />
489
+ );
490
+ })}
491
+ {ALL_EDGES.map((edge) => {
492
+ const set = edges[edge];
493
+ return set ? <PreviewLine key={`line-${edge}`} edge={edge} line={set} /> : null;
494
+ })}
495
+ {ALL_EDGES.map((edge) => {
496
+ const [x1, y1, x2, y2] = EDGE_SEGMENT[edge];
497
+ // The hit strip stops short of the corners, so a press near one is unambiguous.
498
+ const inset = 8;
499
+ const horizontal = y1 === y2;
500
+ const d = horizontal
501
+ ? `M${x1 + inset} ${y1}L${x2 - inset} ${y2}`
502
+ : `M${x1} ${y1 + inset}L${x2} ${y2 - inset}`;
503
+ return (
504
+ <path
505
+ key={`hit-${edge}`}
506
+ d={d}
507
+ className="sheet-format-cells-hit"
508
+ data-edge={edge}
509
+ onClick={() => toggleEdge(edge)}
510
+ />
511
+ );
512
+ })}
513
+ </svg>
514
+ <div className="sheet-format-cells-edges is-cols">
515
+ {edgeButton("left")}
516
+ {edgeButton("insideV")}
517
+ {edgeButton("right")}
518
+ </div>
519
+ </div>
520
+ <p className="sheet-format-cells-note">
521
+ Choose a line, then click a preset, the preview or the buttons beside it. Sides you
522
+ leave alone stay as they are.
523
+ </p>
524
+ </div>
525
+ </div>
526
+ );
527
+
528
+ const body = (
529
+ <div className="sheet-format-cells">
530
+ <div
531
+ role="tablist"
532
+ aria-label="Format Cells"
533
+ className="sheet-format-cells-tabs"
534
+ onKeyDown={rovingKeys(tabs.map((t) => t.id), active, setActive)}
535
+ >
536
+ {tabs.map((t) => (
537
+ <button
538
+ key={t.id}
539
+ type="button"
540
+ role="tab"
541
+ id={tabId(t.id)}
542
+ aria-selected={active === t.id}
543
+ aria-controls={panelId(t.id)}
544
+ tabIndex={active === t.id ? 0 : -1}
545
+ data-format-tab={t.id}
546
+ className={"sheet-format-cells-tab" + (active === t.id ? " is-on" : "")}
547
+ onClick={() => setActive(t.id)}
548
+ >
549
+ {t.label}
550
+ </button>
551
+ ))}
552
+ </div>
553
+ <div className="sheet-format-cells-panels">
554
+ {tabs.map((t) => (
555
+ <div
556
+ key={t.id}
557
+ role="tabpanel"
558
+ id={panelId(t.id)}
559
+ aria-labelledby={tabId(t.id)}
560
+ hidden={active !== t.id}
561
+ className="sheet-format-cells-panel"
562
+ >
563
+ {t.id === "number" ? numberPanel : borderPanel}
564
+ </div>
565
+ ))}
566
+ </div>
567
+ </div>
568
+ );
569
+
570
+ return (
571
+ <ConfirmDialog
572
+ open
573
+ title="Format Cells"
574
+ body={body}
575
+ confirmLabel="OK"
576
+ cancelLabel="Cancel"
577
+ tone="primary"
578
+ onConfirm={confirm}
579
+ onCancel={onClose}
580
+ />
581
+ );
582
+ }
web/src/sheet/FormulaBar.tsx CHANGED
@@ -46,6 +46,14 @@
46
  // the page owns that confirmation, so the bar shows a bound cell read only and names why. A bar
47
  // that silently converted would be a second, unconfirmed door onto the same act.
48
  //
 
 
 
 
 
 
 
 
49
  // ⚠ DESIGN CONTRACT: sentence case, quiet buttons, token only colour and type, no emoji, and no
50
  // em dash or en dash in any string that reaches a screen (aria labels included).
51
  // ---------------------------------------------------------------------------
@@ -88,12 +96,30 @@ export interface FormulaBarProps {
88
  onAddrChange: (addr: string) => void;
89
  /** The page's one commit door, so a bar edit takes one history step and one save. */
90
  onCommit: (edits: Record<string, Cell | null>) => void;
 
 
 
 
 
91
  }
92
 
 
 
 
 
 
 
93
  export default function FormulaBar({
94
- addr, cell, disabled = false, onAddrChange, onCommit,
95
  }: FormulaBarProps) {
96
  const [draft, setDraft] = useState<string>("");
 
 
 
 
 
 
 
97
  const [addrDraft, setAddrDraft] = useState<string>(addr);
98
  /** FA-16's highlighted row. The caller (this file) owns cycling it; `FormulaAssist` only reads it. */
99
  const [activeIndex, setActiveIndex] = useState(0);
@@ -127,16 +153,16 @@ export default function FormulaBar({
127
  // this is read only to decide what Tab and the arrow keys do, `FormulaAssist` renders the same
128
  // call's result.
129
  const suggestions = useMemo(
130
- () => (isFormulaText(draft) ? suggest(draft, caret) : []),
131
- [draft, caret],
132
  );
133
  const dropdownOpen = !dismissed && suggestions.length > 0;
134
  /** CR-1: at least one live reference, which is what turns the input's own text transparent so
135
  * the coloured backdrop underneath is what is actually seen (a plain input cannot itself paint
136
  * more than one colour). */
137
  const refCount = useMemo(
138
- () => (isFormulaText(draft) ? refsIn(draft).length : 0),
139
- [draft],
140
  );
141
 
142
  const syncBackdropScroll = useCallback(() => {
@@ -150,6 +176,9 @@ export default function FormulaBar({
150
 
151
  // W61-T10 / R12: grow with the wrapped draft, up to five lines. Beyond that, both the
152
  // real text and its coloured mirror scroll together instead of pushing the grid away.
 
 
 
153
  useLayoutEffect(() => {
154
  const input = inputRef.current;
155
  if (!input) return;
@@ -158,16 +187,53 @@ export default function FormulaBar({
158
  const lineHeight = Number.parseFloat(metrics.lineHeight);
159
  const padding = Number.parseFloat(metrics.paddingTop) + Number.parseFloat(metrics.paddingBottom);
160
  const border = Number.parseFloat(metrics.borderTopWidth) + Number.parseFloat(metrics.borderBottomWidth);
 
161
  input.style.height = "auto";
162
- input.style.height = `${Math.min(input.scrollHeight + border, lineHeight * 5 + padding + border)}px`;
 
 
 
 
 
163
  if (backdropRef.current) backdropRef.current.style.height = input.style.height;
 
 
 
 
 
 
 
 
 
 
164
  syncBackdropScroll();
165
  };
166
  measure();
167
  const observer = new ResizeObserver(measure);
168
  if (input.parentElement) observer.observe(input.parentElement);
169
  return () => observer.disconnect();
170
- }, [draft, syncBackdropScroll]);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
171
 
172
  const sync = useCallback((el: HTMLTextAreaElement) => {
173
  setCaret(el.selectionStart ?? el.value.length);
@@ -247,8 +313,9 @@ export default function FormulaBar({
247
  setDismissed(false);
248
  }, [text]);
249
 
250
- /** True while there is nothing to confirm or revert, so both controls read as unavailable. */
251
- const idle = disabled || !addr || bound;
 
252
 
253
  const goToAddr = useCallback(() => {
254
  const next = withinGrid(addrDraft);
@@ -260,7 +327,9 @@ export default function FormulaBar({
260
  }, [addr, addrDraft, onAddrChange]);
261
 
262
  return (
263
- <div className="sheet-fx" role="group" aria-label="Formula bar">
 
 
264
  <label className="sheet-fx-addr">
265
  <span className="sheet-fx-addr-label">Cell</span>
266
  <input
@@ -336,7 +405,7 @@ export default function FormulaBar({
336
  reference actually exists, so a formula with none yet paints exactly as it always did. */}
337
  {refCount > 0 && (
338
  <div ref={backdropRef} className="formula-assist-backdrop-bar" aria-hidden="true">
339
- <ColoredFormulaText text={draft} theme="light" />
340
  </div>
341
  )}
342
  {/* W61-T10: wrapping needs a textarea; onKeyDown already prevents Enter before commit. */}
@@ -344,8 +413,8 @@ export default function FormulaBar({
344
  ref={inputRef}
345
  rows={1}
346
  className={"sheet-fx-input" + (refCount > 0 ? " formula-assist-input-bar--colored" : "")}
347
- value={draft}
348
- readOnly={bound}
349
  disabled={disabled || !addr}
350
  aria-label={bound ? "This cell reads from a database" : "Formula or value"}
351
  placeholder={bound ? "" : "Type a value, or = to start a formula"}
@@ -373,12 +442,36 @@ export default function FormulaBar({
373
  text={draft}
374
  caret={caret}
375
  activeIndex={activeIndex}
376
- dismissed={dismissed}
377
  onAccept={accept}
378
  onHoverIndex={setActiveIndex}
379
  />
380
  </div>
381
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
382
  {/* ⛔ R20 SAID IN THE BAR, NOT ENFORCED TWICE. The input is already read only; this states
383
  WHY, because a field that refuses a keystroke without a reason reads as broken. */}
384
  {bound && (
 
46
  // the page owns that confirmation, so the bar shows a bound cell read only and names why. A bar
47
  // that silently converted would be a second, unconfirmed door onto the same act.
48
  //
49
+ // ⭐⭐ S67-T03 / CONTRACT C1 (R28, QI27, 2026-09-28) — THE BAR MIRRORS THE CELL'S DRAFT LIVE AND
50
+ // EXPANDS LIKE EXCEL'S. `SheetGrid` reports its in-cell draft through `onDraftChange`, the page
51
+ // passes it here as `draft`, and while it is a string the bar shows it character for character
52
+ // (read only: one edit has one home, the cell's editor). `null` hands the bar back its own text,
53
+ // which after a commit is the stored formula. The chevron at the bar's right end and Ctrl+Shift+U
54
+ // toggle the expanded height; both live in THIS file, never in `shortcuts.ts` (lane B's), and the
55
+ // chevron stays live on a read-only sheet, because reading a long formula is not an edit.
56
+ //
57
  // ⚠ DESIGN CONTRACT: sentence case, quiet buttons, token only colour and type, no emoji, and no
58
  // em dash or en dash in any string that reaches a screen (aria labels included).
59
  // ---------------------------------------------------------------------------
 
96
  onAddrChange: (addr: string) => void;
97
  /** The page's one commit door, so a bar edit takes one history step and one save. */
98
  onCommit: (edits: Record<string, Cell | null>) => void;
99
+ /**
100
+ * C1: the in-cell editor's live draft, or null when no cell editor is open. While it is a
101
+ * string the bar shows it instead of its own text and does not take typing.
102
+ */
103
+ draft?: string | null;
104
  }
105
 
106
+ /** C1: the lines the expanded bar opens to at least, and grows to at most, before it scrolls. */
107
+ const EXPANDED_MIN_LINES = 6;
108
+ const EXPANDED_MAX_LINES = 12;
109
+ /** DESIGN.md §4 motion: 100-200 ms ease-out for the expand and collapse. */
110
+ const EXPAND_MS = 150;
111
+
112
  export default function FormulaBar({
113
+ addr, cell, disabled = false, onAddrChange, onCommit, draft: cellDraft = null,
114
  }: FormulaBarProps) {
115
  const [draft, setDraft] = useState<string>("");
116
+ /** C1: the expanded height is this bar's own state, toggled by the chevron and Ctrl+Shift+U. */
117
+ const [expanded, setExpanded] = useState(false);
118
+ /** True for the one measure that follows a toggle, so only that change is animated. */
119
+ const animateNext = useRef(false);
120
+ /** C1: a cell editor is open and its draft is what the bar shows. */
121
+ const mirroring = typeof cellDraft === "string";
122
+ const shown = mirroring ? cellDraft : draft;
123
  const [addrDraft, setAddrDraft] = useState<string>(addr);
124
  /** FA-16's highlighted row. The caller (this file) owns cycling it; `FormulaAssist` only reads it. */
125
  const [activeIndex, setActiveIndex] = useState(0);
 
153
  // this is read only to decide what Tab and the arrow keys do, `FormulaAssist` renders the same
154
  // call's result.
155
  const suggestions = useMemo(
156
+ () => (!mirroring && isFormulaText(draft) ? suggest(draft, caret) : []),
157
+ [draft, caret, mirroring],
158
  );
159
  const dropdownOpen = !dismissed && suggestions.length > 0;
160
  /** CR-1: at least one live reference, which is what turns the input's own text transparent so
161
  * the coloured backdrop underneath is what is actually seen (a plain input cannot itself paint
162
  * more than one colour). */
163
  const refCount = useMemo(
164
+ () => (isFormulaText(shown) ? refsIn(shown).length : 0),
165
+ [shown],
166
  );
167
 
168
  const syncBackdropScroll = useCallback(() => {
 
176
 
177
  // W61-T10 / R12: grow with the wrapped draft, up to five lines. Beyond that, both the
178
  // real text and its coloured mirror scroll together instead of pushing the grid away.
179
+ // S67-T03 / C1: expanded, the bar opens to at least six lines and grows to twelve; the toggle
180
+ // animates from the old height to the new one (Web Animations, because the auto-height measure
181
+ // below would defeat a CSS height transition), and not at all under reduced motion.
182
  useLayoutEffect(() => {
183
  const input = inputRef.current;
184
  if (!input) return;
 
187
  const lineHeight = Number.parseFloat(metrics.lineHeight);
188
  const padding = Number.parseFloat(metrics.paddingTop) + Number.parseFloat(metrics.paddingBottom);
189
  const border = Number.parseFloat(metrics.borderTopWidth) + Number.parseFloat(metrics.borderBottomWidth);
190
+ const before = input.getBoundingClientRect().height;
191
  input.style.height = "auto";
192
+ const natural = input.scrollHeight + border;
193
+ const lines = (n: number) => lineHeight * n + padding + border;
194
+ const next = expanded
195
+ ? Math.max(lines(EXPANDED_MIN_LINES), Math.min(natural, lines(EXPANDED_MAX_LINES)))
196
+ : Math.min(natural, lineHeight * 5 + padding + border);
197
+ input.style.height = `${next}px`;
198
  if (backdropRef.current) backdropRef.current.style.height = input.style.height;
199
+ if (animateNext.current) {
200
+ animateNext.current = false;
201
+ const still = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
202
+ if (!still && Math.abs(before - next) > 1 && typeof input.animate === "function") {
203
+ const frames = [{ height: `${before}px` }, { height: `${next}px` }];
204
+ const timing = { duration: EXPAND_MS, easing: "ease-out" };
205
+ input.animate(frames, timing);
206
+ backdropRef.current?.animate(frames, timing);
207
+ }
208
+ }
209
  syncBackdropScroll();
210
  };
211
  measure();
212
  const observer = new ResizeObserver(measure);
213
  if (input.parentElement) observer.observe(input.parentElement);
214
  return () => observer.disconnect();
215
+ }, [expanded, shown, syncBackdropScroll]);
216
+
217
+ /** C1: the chevron and Ctrl+Shift+U share this one toggle. */
218
+ const toggleExpanded = useCallback(() => {
219
+ animateNext.current = true;
220
+ setExpanded((open) => !open);
221
+ }, []);
222
+
223
+ // ⛔ C1: Ctrl+Shift+U IS THIS FILE'S, NEVER `shortcuts.ts`'s (whose Ctrl+Shift branch has no
224
+ // "u", so plain Ctrl+U stays underline). Capture phase, so the grid and the cell editor, which
225
+ // hold focus while a formula is typed, never see the chord.
226
+ useEffect(() => {
227
+ const onKey = (e: KeyboardEvent) => {
228
+ if (!(e.ctrlKey || e.metaKey) || !e.shiftKey || e.altKey) return;
229
+ if (e.key.toLowerCase() !== "u") return;
230
+ e.preventDefault();
231
+ e.stopPropagation();
232
+ toggleExpanded();
233
+ };
234
+ window.addEventListener("keydown", onKey, true);
235
+ return () => window.removeEventListener("keydown", onKey, true);
236
+ }, [toggleExpanded]);
237
 
238
  const sync = useCallback((el: HTMLTextAreaElement) => {
239
  setCaret(el.selectionStart ?? el.value.length);
 
313
  setDismissed(false);
314
  }, [text]);
315
 
316
+ /** True while there is nothing to confirm or revert, so both controls read as unavailable. A
317
+ * mirrored draft belongs to the cell's editor, whose own Enter and Escape commit or revert it. */
318
+ const idle = disabled || !addr || bound || mirroring;
319
 
320
  const goToAddr = useCallback(() => {
321
  const next = withinGrid(addrDraft);
 
327
  }, [addr, addrDraft, onAddrChange]);
328
 
329
  return (
330
+ <div className="sheet-fx" role="group" aria-label="Formula bar"
331
+ // S67-T03: expanded, the name box and the controls stay on the first line, as in Excel.
332
+ style={expanded ? { alignItems: "flex-start" } : undefined}>
333
  <label className="sheet-fx-addr">
334
  <span className="sheet-fx-addr-label">Cell</span>
335
  <input
 
405
  reference actually exists, so a formula with none yet paints exactly as it always did. */}
406
  {refCount > 0 && (
407
  <div ref={backdropRef} className="formula-assist-backdrop-bar" aria-hidden="true">
408
+ <ColoredFormulaText text={shown} theme="light" />
409
  </div>
410
  )}
411
  {/* W61-T10: wrapping needs a textarea; onKeyDown already prevents Enter before commit. */}
 
413
  ref={inputRef}
414
  rows={1}
415
  className={"sheet-fx-input" + (refCount > 0 ? " formula-assist-input-bar--colored" : "")}
416
+ value={shown}
417
+ readOnly={bound || mirroring}
418
  disabled={disabled || !addr}
419
  aria-label={bound ? "This cell reads from a database" : "Formula or value"}
420
  placeholder={bound ? "" : "Type a value, or = to start a formula"}
 
442
  text={draft}
443
  caret={caret}
444
  activeIndex={activeIndex}
445
+ dismissed={dismissed || mirroring}
446
  onAccept={accept}
447
  onHoverIndex={setActiveIndex}
448
  />
449
  </div>
450
 
451
+ {/* ⭐⭐ S67-T03 / C1 — EXCEL'S EXPAND CHEVRON, AT THE BAR'S RIGHT END. Never disabled: a
452
+ read-only sheet still expands, because reading a long formula is not an edit. */}
453
+ <button
454
+ type="button"
455
+ className="sheet-fx-btn sheet-fx-expand"
456
+ aria-label={expanded ? "Collapse formula bar" : "Expand formula bar"}
457
+ title={expanded ? "Collapse formula bar (Ctrl+Shift+U)" : "Expand formula bar (Ctrl+Shift+U)"}
458
+ aria-expanded={expanded}
459
+ onMouseDown={(e) => e.preventDefault()}
460
+ onClick={toggleExpanded}
461
+ >
462
+ <svg width="13" height="13" viewBox="0 0 16 16" fill="none" aria-hidden
463
+ style={{ transform: expanded ? "rotate(180deg)" : undefined,
464
+ transition: `transform ${EXPAND_MS}ms ease-out` }}>
465
+ <path
466
+ d="M4 6.2l4 4 4-4"
467
+ stroke="currentColor"
468
+ strokeWidth="1.3"
469
+ strokeLinecap="round"
470
+ strokeLinejoin="round"
471
+ />
472
+ </svg>
473
+ </button>
474
+
475
  {/* ⛔ R20 SAID IN THE BAR, NOT ENFORCED TWICE. The input is already read only; this states
476
  WHY, because a field that refuses a keystroke without a reason reads as broken. */}
477
  {bound && (
web/src/sheet/KeyTips.tsx CHANGED
@@ -32,7 +32,8 @@
32
  // ⚠ SCOPE, STATED HONESTLY (the ticket's own "best effort" clause for the third level). The first
33
  // two levels show the tab strip's badges, then ONLY the chosen tab's group controls, with prefix
34
  // match, Left/Right and Enter nav, and Escape/Alt exit. Strip actions use their own gallery/leaf
35
- // path. Wave 55 gives Up/Down back to the grid immediately. The gallery level is
 
36
  // exercised to full fidelity for Borders only (`Ribbon.tsx`'s `BORDERS` array now carries its own
37
  // one-letter `data-kt` per entry, plus "No border"). Every OTHER gallery (Insert, Delete, Format,
38
  // Clear, Fill/Text colour, Font size, Number format) still gets Escape-to-close and generic
@@ -41,7 +42,7 @@
41
  // no letter badges yet. That gap is booked in the ticket's HANDOFF, not hidden here.
42
  import { useCallback, useEffect, useReducer, useRef } from "react";
43
  import type { RefObject } from "react";
44
- import { KEY_TIP_GRID_ARROW_EVENT, keyTipGridArrow } from "./shortcuts";
45
 
46
  type Depth = "tabs" | "home" | "gallery";
47
 
@@ -126,20 +127,44 @@ function getTargets(container: HTMLElement | null, depth: Depth): Target[] {
126
  return collect(container.querySelectorAll<KeyTipElement>(".sheet-ribbon-tabs [data-kt]"));
127
  }
128
  if (depth === "gallery") {
129
- const openPop = (container.querySelector<HTMLElement>(".sheet-ribbon-pop")
130
- // ⭐⭐ W53-T07 (instruction 25) — THE OPEN POPOVER IS A CHILD OF `<body>` NOW. Every
131
- // ribbon menu renders through `AnchoredOverlay`, which portals, so it is no longer a
132
- // descendant of `Ribbon.tsx`'s `rootRef` and this container query returns null. Without
133
- // this fallback the THIRD key-tip depth (Alt, then the group letter, then the letters
134
- // inside the open gallery) dies silently: no error, no gate, just badges that stop
135
- // appearing. ⚠ `document` is safe as the wider scope because exactly one popover is ever
136
- // open - `Ribbon.tsx::open` is a single `Popover` value, not a set.
137
- ?? document.querySelector<HTMLElement>(".sheet-ribbon-pop"));
138
- return openPop ? collect(openPop.querySelectorAll<HTMLButtonElement>("[data-kt]")) : [];
139
  }
140
  return collect(container.querySelectorAll<HTMLButtonElement>(".sheet-ribbon-scroll [data-kt]"));
141
  }
142
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
143
  function collect(list: NodeListOf<KeyTipElement>): Target[] {
144
  const out: Target[] = [];
145
  list.forEach((el) => {
@@ -160,16 +185,8 @@ function pickTargets(container: HTMLElement | null, depth: Depth, prefix: string
160
  * generic arrow/Enter navigation among its own menu items. */
161
  function navFallback(container: HTMLElement | null, depth: Depth): HTMLButtonElement[] {
162
  if (!container || depth !== "gallery") return [];
163
- const openPop = (container.querySelector<HTMLElement>(".sheet-ribbon-pop")
164
- // ⭐⭐ W53-T07 (instruction 25) — THE OPEN POPOVER IS A CHILD OF `<body>` NOW. Every
165
- // ribbon menu renders through `AnchoredOverlay`, which portals, so it is no longer a
166
- // descendant of `Ribbon.tsx`'s `rootRef` and this container query returns null. Without
167
- // this fallback the THIRD key-tip depth (Alt, then the group letter, then the letters
168
- // inside the open gallery) dies silently: no error, no gate, just badges that stop
169
- // appearing. ⚠ `document` is safe as the wider scope because exactly one popover is ever
170
- // open - `Ribbon.tsx::open` is a single `Popover` value, not a set.
171
- ?? document.querySelector<HTMLElement>(".sheet-ribbon-pop"));
172
- return openPop ? Array.from(openPop.querySelectorAll<HTMLButtonElement>("button:not(:disabled)")) : [];
173
  }
174
 
175
  function navElements(container: HTMLElement | null, depth: Depth, prefix: string): KeyTipElement[] {
@@ -225,9 +242,39 @@ export default function KeyTips({ containerRef }: KeyTipsProps) {
225
  });
226
  }, [setKt, containerRef]);
227
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
228
  /** KT-14/15/16's ladder: one step back per Escape, never a full exit until the first level. */
229
  const stepBack = useCallback(() => {
230
  const st = stateRef.current;
 
 
 
 
 
 
 
 
 
 
 
 
231
  if (st.depth === "gallery") {
232
  const opener = containerRef.current?.querySelector<HTMLButtonElement>(
233
  '[data-kt-opens="gallery"][aria-expanded="true"]',
@@ -251,7 +298,7 @@ export default function KeyTips({ containerRef }: KeyTipsProps) {
251
  return;
252
  }
253
  deactivateAll();
254
- }, [containerRef, deactivateAll, setKt]);
255
 
256
  /** A first-level tab reveals its own group controls (KT-8/KT-9); strip actions follow the
257
  * same gallery/leaf handling as group controls.
@@ -286,6 +333,29 @@ export default function KeyTips({ containerRef }: KeyTipsProps) {
286
  requestAnimationFrame(() => navElements(containerRef.current, "gallery", "")[0]?.focus());
287
  return;
288
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
289
  // A leaf action or a gallery item: it fires, and per real Excel the whole KeyTip layer closes
290
  // and the keyboard returns to wherever it was before Alt was first pressed.
291
  el.click();
@@ -363,6 +433,31 @@ export default function KeyTips({ containerRef }: KeyTipsProps) {
363
  stepBack();
364
  return;
365
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
366
  // W55-T05 / R4: Up and Down leave the Alt path instead of walking its badges. The original
367
  // document-capture key cannot reach Glide because focus currently belongs to the ribbon, so
368
  // consume it once, close synchronously, and hand one semantic arrow to this ribbon's own
@@ -417,8 +512,8 @@ export default function KeyTips({ containerRef }: KeyTipsProps) {
417
  // no flash, since KT-17's soft signal is for an unmatched CHARACTER, not for every
418
  // non-actionable key a person might happen to touch.
419
  e.preventDefault(); e.stopPropagation();
420
- }, [activate, activateFirstLevel, containerRef, deactivateAll, flash, handleCharacter,
421
- stepBack, setKt]);
422
 
423
  const onDocKeyUp = useCallback((e: KeyboardEvent) => {
424
  if (e.key !== "Alt") return;
 
32
  // ⚠ SCOPE, STATED HONESTLY (the ticket's own "best effort" clause for the third level). The first
33
  // two levels show the tab strip's badges, then ONLY the chosen tab's group controls, with prefix
34
  // match, Left/Right and Enter nav, and Escape/Alt exit. Strip actions use their own gallery/leaf
35
+ // path. Wave 55 gives Up/Down back to the grid immediately, except inside a colour gallery,
36
+ // where S67-T17 lets all four arrows walk the swatch grid (`swatchWalk`). The gallery level is
37
  // exercised to full fidelity for Borders only (`Ribbon.tsx`'s `BORDERS` array now carries its own
38
  // one-letter `data-kt` per entry, plus "No border"). Every OTHER gallery (Insert, Delete, Format,
39
  // Clear, Fill/Text colour, Font size, Number format) still gets Escape-to-close and generic
 
42
  // no letter badges yet. That gap is booked in the ticket's HANDOFF, not hidden here.
43
  import { useCallback, useEffect, useReducer, useRef } from "react";
44
  import type { RefObject } from "react";
45
+ import { KEY_TIP_GRID_ARROW_EVENT, isArrowKey, keyTipGridArrow, swatchGridStep } from "./shortcuts";
46
 
47
  type Depth = "tabs" | "home" | "gallery";
48
 
 
127
  return collect(container.querySelectorAll<KeyTipElement>(".sheet-ribbon-tabs [data-kt]"));
128
  }
129
  if (depth === "gallery") {
130
+ const panel = openPanel(container);
131
+ return panel ? collect(panel.querySelectorAll<HTMLButtonElement>("[data-kt]")) : [];
 
 
 
 
 
 
 
 
132
  }
133
  return collect(container.querySelectorAll<HTMLButtonElement>(".sheet-ribbon-scroll [data-kt]"));
134
  }
135
 
136
+ /** The open gallery panel the keyboard is inside: the ribbon popover, or, while one of its own
137
+ * flyouts is open (S67-T15's Line Color and Line Style, DOM children of the Borders panel that
138
+ * carry `sheet-ribbon-pop-portal` themselves), that innermost flyout. */
139
+ function openPanel(container: HTMLElement): HTMLElement | null {
140
+ const openPop = (container.querySelector<HTMLElement>(".sheet-ribbon-pop")
141
+ // ⭐⭐ W53-T07 (instruction 25) — THE OPEN POPOVER IS A CHILD OF `<body>` NOW. Every
142
+ // ribbon menu renders through `AnchoredOverlay`, which portals, so it is no longer a
143
+ // descendant of `Ribbon.tsx`'s `rootRef` and this container query returns null. Without
144
+ // this fallback the THIRD key-tip depth (Alt, then the group letter, then the letters
145
+ // inside the open gallery) dies silently: no error, no gate, just badges that stop
146
+ // appearing. ⚠ `document` is safe as the wider scope because exactly one popover is ever
147
+ // open - `Ribbon.tsx::open` is a single `Popover` value, not a set.
148
+ ?? document.querySelector<HTMLElement>(".sheet-ribbon-pop"));
149
+ if (!openPop) return null;
150
+ // S67-T17: while a flyout is open, its items are the gallery the keys walk, not the panel's.
151
+ const nested = openPop.querySelectorAll<HTMLElement>(".sheet-ribbon-pop-portal");
152
+ return nested.length ? nested[nested.length - 1] : openPop;
153
+ }
154
+
155
+ /** ⭐⭐ S67-T17 (instruction 18, O28) — THE COLOUR GALLERY'S WALK LIST, OR NULL FOR EVERY OTHER
156
+ * GALLERY. A panel is a colour gallery when it holds a `.sheet-ribbon-swatches` grid: Fill Color,
157
+ * Font Color, and the Borders gallery's Line Color flyout. Asked by CLASS, never by role, because
158
+ * Line Color's swatches are `menuitemradio` where Fill's are `menuitem`. The walk list is every
159
+ * enabled button in the panel in reading order, so the arrows reach "No fill", "Reset the text
160
+ * colour" and "Automatic" around the palette as well as the swatches in it. A gallery WITHOUT a
161
+ * swatch grid answers null and keeps W55-T05's behaviour exactly. */
162
+ function swatchWalk(container: HTMLElement | null): HTMLButtonElement[] | null {
163
+ const panel = container ? openPanel(container) : null;
164
+ if (!panel?.querySelector(".sheet-ribbon-swatches .sheet-ribbon-swatch")) return null;
165
+ return Array.from(panel.querySelectorAll<HTMLButtonElement>("button:not(:disabled)"));
166
+ }
167
+
168
  function collect(list: NodeListOf<KeyTipElement>): Target[] {
169
  const out: Target[] = [];
170
  list.forEach((el) => {
 
185
  * generic arrow/Enter navigation among its own menu items. */
186
  function navFallback(container: HTMLElement | null, depth: Depth): HTMLButtonElement[] {
187
  if (!container || depth !== "gallery") return [];
188
+ const panel = openPanel(container);
189
+ return panel ? Array.from(panel.querySelectorAll<HTMLButtonElement>("button:not(:disabled)")) : [];
 
 
 
 
 
 
 
 
190
  }
191
 
192
  function navElements(container: HTMLElement | null, depth: Depth, prefix: string): KeyTipElement[] {
 
242
  });
243
  }, [setKt, containerRef]);
244
 
245
+ /** S67-T17: close a flyout open inside the gallery (Line Color, Line Style) through the opener
246
+ * that toggles it, and hand focus back to that opener. False when no flyout is open. */
247
+ const flyoutOpener = useCallback((): HTMLButtonElement | null => {
248
+ const panel = containerRef.current ? openPanel(containerRef.current) : null;
249
+ if (!panel || panel.classList.contains("sheet-ribbon-pop")) return null;
250
+ return panel.parentElement?.closest(".sheet-ribbon-pop")
251
+ ?.querySelector<HTMLButtonElement>('[aria-haspopup="menu"][aria-expanded="true"]') ?? null;
252
+ }, [containerRef]);
253
+
254
+ const closeFlyout = useCallback((): boolean => {
255
+ const opener = flyoutOpener();
256
+ if (!opener) return false;
257
+ opener.click();
258
+ setKt({ prefix: "", focusedIdx: 0 });
259
+ requestAnimationFrame(() => opener.focus());
260
+ return true;
261
+ }, [flyoutOpener, setKt]);
262
+
263
  /** KT-14/15/16's ladder: one step back per Escape, never a full exit until the first level. */
264
  const stepBack = useCallback(() => {
265
  const st = stateRef.current;
266
+ // S67-T17: a flyout inside the gallery is its own rung, and on ESCAPE the shared overlay
267
+ // arbiter (`ui/useEscapeClose`) is the one that closes it: the flyout is the topmost layer and
268
+ // the arbiter hears this same keydown. Closing it here as well (clicking its opener) unmounts it
269
+ // synchronously, which promotes the gallery to topmost before the arbiter runs, so the arbiter
270
+ // then closed the GALLERY too and left its 19 badges over the grid (measured on the snapshot:
271
+ // both panels gone inside the same keydown). So key tips only re-anchor on the gallery.
272
+ const opener = st.depth === "gallery" ? flyoutOpener() : null;
273
+ if (opener) {
274
+ setKt({ prefix: "", focusedIdx: 0 });
275
+ requestAnimationFrame(() => opener.focus());
276
+ return;
277
+ }
278
  if (st.depth === "gallery") {
279
  const opener = containerRef.current?.querySelector<HTMLButtonElement>(
280
  '[data-kt-opens="gallery"][aria-expanded="true"]',
 
298
  return;
299
  }
300
  deactivateAll();
301
+ }, [containerRef, deactivateAll, flyoutOpener, setKt]);
302
 
303
  /** A first-level tab reveals its own group controls (KT-8/KT-9); strip actions follow the
304
  * same gallery/leaf handling as group controls.
 
333
  requestAnimationFrame(() => navElements(containerRef.current, "gallery", "")[0]?.focus());
334
  return;
335
  }
336
+ // ⭐ S67-T17 (O28): an item inside the gallery that opens a flyout of its own (S67-T15's Line
337
+ // Color and Line Style). Line Color is a colour gallery, so the key tips stay on and the
338
+ // arrows walk its swatches. Two frames: the flyout mounts in the first and its own overlay
339
+ // layer focuses its first item there, so the swatch focus has to land after that. A flyout
340
+ // with no swatch grid (Line Style) ends the key tips exactly as a leaf always did, leaving
341
+ // focus where the flyout put it.
342
+ if (st.depth === "gallery" && el.getAttribute("aria-haspopup") === "menu") {
343
+ el.click();
344
+ setKt({ prefix: "", focusedIdx: 0 });
345
+ requestAnimationFrame(() => requestAnimationFrame(() => {
346
+ if (!stateRef.current.active || stateRef.current.depth !== "gallery") return;
347
+ const walk = swatchWalk(containerRef.current);
348
+ if (!walk) {
349
+ deactivateAll(false);
350
+ return;
351
+ }
352
+ const start = walk.findIndex((b) => b.matches(".sheet-ribbon-swatch.is-on"));
353
+ const idx = start >= 0 ? start : walk.findIndex((b) => b.matches(".sheet-ribbon-swatch"));
354
+ walk[idx]?.focus();
355
+ setKt({ focusedIdx: Math.max(idx, 0) });
356
+ }));
357
+ return;
358
+ }
359
  // A leaf action or a gallery item: it fires, and per real Excel the whole KeyTip layer closes
360
  // and the keyboard returns to wherever it was before Alt was first pressed.
361
  el.click();
 
433
  stepBack();
434
  return;
435
  }
436
+ // ⭐⭐ S67-T17 (instruction 18, ruling R29 / O28) — INSIDE A COLOUR GALLERY THE ARROWS WALK
437
+ // THE PALETTE. Fill Color, Font Color and the Line Color flyout are grids, so all four arrows
438
+ // move the focus ring through them in two dimensions (`swatchGridStep`) and none of them
439
+ // reaches the grid: the selection stays where it is. This NARROWS W55-T05 / R4 for swatch
440
+ // grids only; every other gallery falls through to it unchanged. Enter applies the focused
441
+ // colour through `activate`, which closes the key tips and returns focus to the grid.
442
+ const walk = st.depth === "gallery" ? swatchWalk(containerRef.current) : null;
443
+ if (walk && isArrowKey(e.key)) {
444
+ e.preventDefault(); e.stopPropagation();
445
+ const from = walk.indexOf(document.activeElement as HTMLButtonElement);
446
+ const next = swatchGridStep(walk.map((b) => b.getBoundingClientRect()), from, e.key);
447
+ // Left at the flyout's first item closes it, as the flyout's own ArrowLeft does.
448
+ if (e.key === "ArrowLeft" && from >= 0 && next === from && closeFlyout()) return;
449
+ if (next >= 0) {
450
+ setKt({ focusedIdx: next });
451
+ walk[next].focus();
452
+ }
453
+ return;
454
+ }
455
+ if (walk && (e.key === "Enter" || e.key === " ")) {
456
+ e.preventDefault(); e.stopPropagation();
457
+ const el = walk.find((b) => b === document.activeElement) ?? walk[st.focusedIdx];
458
+ if (el) activate(el);
459
+ return;
460
+ }
461
  // W55-T05 / R4: Up and Down leave the Alt path instead of walking its badges. The original
462
  // document-capture key cannot reach Glide because focus currently belongs to the ribbon, so
463
  // consume it once, close synchronously, and hand one semantic arrow to this ribbon's own
 
512
  // no flash, since KT-17's soft signal is for an unmatched CHARACTER, not for every
513
  // non-actionable key a person might happen to touch.
514
  e.preventDefault(); e.stopPropagation();
515
+ }, [activate, activateFirstLevel, closeFlyout, containerRef, deactivateAll, flash,
516
+ handleCharacter, stepBack, setKt]);
517
 
518
  const onDocKeyUp = useCallback((e: KeyboardEvent) => {
519
  if (e.key !== "Alt") return;
web/src/sheet/RulesDialog.tsx CHANGED
@@ -16,28 +16,34 @@
16
  // this file would race it and win or lose on registration order.
17
  //
18
  // ⚠ THE SHELL GENUINELY CARRIES A LIST EDITOR, so no second dialog shape was built. Its `body` is
19
- // a `ReactNode` and its panel scrolls, which is what a hundred rules need; what it does not offer
20
- // is a wider panel, so each rule is a stacked CARD rather than a wide row. That is the same
21
- // anatomy the field rail uses for a stacked editor and it joins that rhythm rather than inventing
22
- // a new one (DESIGN.md 4).
 
 
 
 
 
23
  //
24
  // ⚠ DESIGN CONTRACT: sentence case, no ALL CAPS chrome, scale tokens only and no literal
25
  // font-size, colour tokens never hues, inline SVG on `currentColor` and no emoji, 150 ms ease-out
26
  // on opacity and transform, and no em dash or en dash in any string that reaches a screen.
27
  // ---------------------------------------------------------------------------------------------
28
 
29
- import { useCallback, useEffect, useId, useState } from "react";
30
  import { ConfirmDialog } from "../ui/ConfirmDialog";
31
  import { useCellRefHighlight } from "./refHighlight";
32
  import {
33
  DEFAULT_BAR_FILL, DEFAULT_RULE_SCALE,
34
  RULE_FILLS, RULE_INKS, RULE_KIND_LABEL, RULE_OPS, RULE_OP_LABEL, RULE_SCALES,
35
- addRule, blankRule, moveRule, rampBackground, rangeText, removeRule, ruleArity, ruleKind,
36
- rulesRefusal, updateRule,
 
37
  } from "./rules";
38
  import { listText, parseList } from "./validation";
39
  import { CELL_COLOUR_PATTERN, MAX_SHEET_RULES, MAX_VALIDATION_LIST, SHEET_RULE_KINDS } from "./types";
40
- import type { SheetRule, SheetRuleKind, SheetRuleOp } from "./types";
41
 
42
  export interface RulesDialogProps {
43
  open: boolean;
@@ -84,9 +90,28 @@ function RulesSurface({
84
  rules, range, onCancel, onSave,
85
  }: Omit<RulesDialogProps, "open">) {
86
  const [draft, setDraft] = useState<SheetRule[]>(() => (rules ?? []).map((r) => ({ ...r })));
 
 
 
 
 
 
 
 
 
87
  /** The cap's own refusal, which is raised by an ACT rather than by the draft's shape. */
88
  const [notice, setNotice] = useState("");
89
  const [colourRefusals, setColourRefusals] = useState<Record<string, string>>({});
 
 
 
 
 
 
 
 
 
 
90
  const colourRefusal = useCallback((id: string, reason: string) => {
91
  setColourRefusals((current) => {
92
  if ((current[id] ?? "") === reason) return current;
@@ -97,23 +122,70 @@ function RulesSurface({
97
  });
98
  }, []);
99
 
100
- const add = useCallback(() => {
101
- setDraft((current) => {
102
- const out = addRule(current, blankRule(range));
103
- setNotice(out.refusal ?? "");
104
- return out.rules;
 
105
  });
106
- }, [range]);
 
 
 
 
 
 
 
 
 
 
107
 
108
  const patch = useCallback((id: string, next: Partial<SheetRule>) => {
109
  setNotice("");
 
110
  setDraft((current) => updateRule(current, id, next));
111
- }, []);
 
 
112
 
113
- // ⛔ THE DRAFT'S OWN REFUSAL IS COMPUTED, NEVER STORED. A rule that cannot match is refused at
114
- // save time from the list itself, so editing a bad rule clears its own complaint rather than
115
- // leaving a stale sentence on the screen.
116
- const refusal = notice || rulesRefusal(draft) || "";
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
117
 
118
  return (
119
  <ConfirmDialog
@@ -121,17 +193,9 @@ function RulesSurface({
121
  title="Conditional formatting"
122
  tone="primary"
123
  cancelLabel="Cancel"
124
- confirmLabel="Save rules"
125
  onCancel={onCancel}
126
- onConfirm={() => {
127
- if (Object.values(colourRefusals).some(Boolean)) return;
128
- const why = rulesRefusal(draft);
129
- if (why) {
130
- setNotice(why);
131
- return;
132
- }
133
- onSave(draft);
134
- }}
135
  body={(
136
  <div className="sheet-rules">
137
  {/* ⭐⭐ THE ORDER RULE, SAID ON THE SURFACE THAT OWNS IT. Two rules matching one cell is
@@ -146,26 +210,46 @@ function RulesSurface({
146
  {draft.length === 0 ? (
147
  <p className="sheet-rules-empty">No rules yet.</p>
148
  ) : (
149
- <ol className="sheet-rules-list">
150
- {draft.map((rule, index) => (
151
- <RuleCard
152
- key={rule.id}
153
- rule={rule}
154
- index={index}
155
- count={draft.length}
156
- onPatch={patch}
157
- onColourRefusal={colourRefusal}
158
- onMove={(delta) => {
159
- setNotice("");
160
- setDraft((current) => moveRule(current, rule.id, delta));
161
- }}
162
- onRemove={() => {
163
- setNotice("");
164
- setDraft((current) => removeRule(current, rule.id));
165
- }}
166
- />
167
- ))}
168
- </ol>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
169
  )}
170
 
171
  <div className="sheet-rules-foot">
@@ -177,8 +261,8 @@ function RulesSurface({
177
  </span>
178
  </div>
179
 
180
- {refusal ? (
181
- <p className="sheet-rules-refusal" role="alert">{refusal}</p>
182
  ) : null}
183
  </div>
184
  )}
@@ -186,21 +270,144 @@ function RulesSurface({
186
  );
187
  }
188
 
189
- interface RuleCardProps {
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
190
  rule: SheetRule;
191
  index: number;
192
  count: number;
 
 
 
 
 
 
 
193
  onPatch: (id: string, next: Partial<SheetRule>) => void;
194
  onColourRefusal: (id: string, reason: string) => void;
195
  onMove: (delta: number) => void;
196
  onRemove: () => void;
197
  }
198
 
199
- function RuleCard({ rule, index, count, onPatch, onColourRefusal, onMove, onRemove }: RuleCardProps) {
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
200
  const ids = useId();
201
  const kind = ruleKind(rule);
202
  const arity = ruleArity(rule.op);
203
- // The rule's range and any cell its formula names are outlined on the grid (refHighlight.ts).
 
204
  useCellRefHighlight([rangeText(rule.range), kind === "formula" ? String(rule.value ?? "") : ""]);
205
 
206
  /**
@@ -225,22 +432,35 @@ function RuleCard({ rule, index, count, onPatch, onColourRefusal, onMove, onRemo
225
  onPatch(rule.id, { kind: next, op: "eq", value: "", value2: undefined, scale: undefined });
226
  return;
227
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
228
  onPatch(rule.id, {
229
  kind: next,
230
  op: "between",
231
- scale: next === "scale"
232
- ? (rule.scale ?? { low: DEFAULT_RULE_SCALE.low, high: DEFAULT_RULE_SCALE.high })
233
- : rule.scale,
234
  style: next === "bar" ? { fill: rule.style?.fill || DEFAULT_BAR_FILL } : rule.style,
235
  });
236
  };
237
 
238
  return (
239
- <li className="sheet-rules-card">
240
  <div className="sheet-rules-row">
241
- <span className="sheet-rules-order" aria-hidden="true">{index + 1}</span>
242
  <label className="sheet-rules-field">
243
- <span className="sheet-rules-label" id={`${ids}-range`}>Range</span>
244
  <input
245
  className="sheet-rules-input"
246
  type="text"
@@ -250,37 +470,6 @@ function RuleCard({ rule, index, count, onPatch, onColourRefusal, onMove, onRemo
250
  onChange={(e) => onPatch(rule.id, { range: e.target.value })}
251
  />
252
  </label>
253
- <div className="sheet-rules-moves">
254
- <button
255
- type="button"
256
- className="sheet-rules-move"
257
- aria-label={`Move rule ${index + 1} up`}
258
- title="Move up"
259
- disabled={index === 0}
260
- onClick={() => onMove(-1)}
261
- >
262
- <IconChevron />
263
- </button>
264
- <button
265
- type="button"
266
- className="sheet-rules-move is-down"
267
- aria-label={`Move rule ${index + 1} down`}
268
- title="Move down"
269
- disabled={index === count - 1}
270
- onClick={() => onMove(1)}
271
- >
272
- <IconChevron />
273
- </button>
274
- <button
275
- type="button"
276
- className="sheet-rules-remove"
277
- aria-label={`Delete rule ${index + 1}`}
278
- title="Delete this rule"
279
- onClick={onRemove}
280
- >
281
- <IconRemove />
282
- </button>
283
- </div>
284
  </div>
285
 
286
  <div className="sheet-rules-row">
@@ -288,7 +477,9 @@ function RuleCard({ rule, index, count, onPatch, onColourRefusal, onMove, onRemo
288
  colour scale and a data bar are created from the ribbon's Conditional formatting
289
  gallery, and an editor that could not represent them would have listed a rule it
290
  could not describe, or worse, quietly rewritten it into a condition nobody chose. */}
291
- <label className="sheet-rules-field">
 
 
292
  <span className="sheet-rules-label" id={`${ids}-kind`}>Rule</span>
293
  <select
294
  className="sheet-rules-select"
@@ -302,7 +493,7 @@ function RuleCard({ rule, index, count, onPatch, onColourRefusal, onMove, onRemo
302
  </select>
303
  </label>
304
  {kind === "cell" ? (
305
- <label className="sheet-rules-field">
306
  <span className="sheet-rules-label" id={`${ids}-op`}>Condition</span>
307
  <select
308
  className="sheet-rules-select"
@@ -329,7 +520,13 @@ function RuleCard({ rule, index, count, onPatch, onColourRefusal, onMove, onRemo
329
  />
330
  </label>
331
  ) : null}
332
- {kind !== "formula" && arity >= 1 ? (
 
 
 
 
 
 
333
  <label className="sheet-rules-field">
334
  <span className="sheet-rules-label" id={`${ids}-value`}>
335
  {arity === 2 ? "From" : "Value"}
@@ -343,7 +540,7 @@ function RuleCard({ rule, index, count, onPatch, onColourRefusal, onMove, onRemo
343
  />
344
  </label>
345
  ) : null}
346
- {kind !== "formula" && arity === 2 ? (
347
  <label className="sheet-rules-field">
348
  <span className="sheet-rules-label" id={`${ids}-value2`}>To</span>
349
  <input
@@ -379,7 +576,9 @@ function RuleCard({ rule, index, count, onPatch, onColourRefusal, onMove, onRemo
379
  aria-label={ramp.label}
380
  aria-pressed={on}
381
  title={ramp.label}
382
- onClick={() => onPatch(rule.id, { scale: { low: ramp.low, high: ramp.high } })}
 
 
383
  />
384
  );
385
  })}
@@ -439,7 +638,79 @@ function RuleCard({ rule, index, count, onPatch, onColourRefusal, onMove, onRemo
439
  palette={RULE_FILLS} onPatch={onPatch} onRefusal={onColourRefusal} />
440
  </div>
441
  ) : null}
442
- </li>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
443
  );
444
  }
445
 
@@ -460,8 +731,8 @@ function RuleColourControl({ rule, which, label, palette, onPatch, onRefusal }:
460
  which: "color" | "fill";
461
  label: string;
462
  palette: readonly { token: string; label: string }[];
463
- onPatch: RuleCardProps["onPatch"];
464
- onRefusal: RuleCardProps["onColourRefusal"];
465
  }) {
466
  const id = useId();
467
  const chosen = rule.style?.[which];
 
16
  // this file would race it and win or lose on registration order.
17
  //
18
  // ⚠ THE SHELL GENUINELY CARRIES A LIST EDITOR, so no second dialog shape was built. Its `body` is
19
+ // a `ReactNode` and its panel scrolls, which is what a hundred rules need.
20
+ //
21
+ // ⭐⭐ S67-T12 (instruction 9, journey J9): EXCEL'S RULES MANAGER, LIST THEN DETAIL. Every rule
22
+ // used to be a fully expanded card, so fifty stored rules were fifty forms with no separation and
23
+ // a refusal computed from the whole list on open. Now each rule is ONE summary row (what it tests,
24
+ // its format preview, where it applies), clicking a row opens that rule's editor under it and
25
+ // closes any other, and a refusal is raised only by Save and only on the row it belongs to. The
26
+ // wider panel is `.lp-dialog:has(.sheet-rules)` in sheet-engine.css, the `:has()` precedent of
27
+ // `wave59/templates.css`, so the kit's own markup is untouched.
28
  //
29
  // ⚠ DESIGN CONTRACT: sentence case, no ALL CAPS chrome, scale tokens only and no literal
30
  // font-size, colour tokens never hues, inline SVG on `currentColor` and no emoji, 150 ms ease-out
31
  // on opacity and transform, and no em dash or en dash in any string that reaches a screen.
32
  // ---------------------------------------------------------------------------------------------
33
 
34
+ import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
35
  import { ConfirmDialog } from "../ui/ConfirmDialog";
36
  import { useCellRefHighlight } from "./refHighlight";
37
  import {
38
  DEFAULT_BAR_FILL, DEFAULT_RULE_SCALE,
39
  RULE_FILLS, RULE_INKS, RULE_KIND_LABEL, RULE_OPS, RULE_OP_LABEL, RULE_SCALES,
40
+ RULE_SCALE_MAX_TYPES, RULE_SCALE_MIN_TYPES, RULE_SCALE_TYPE_LABEL,
41
+ addRule, blankRule, moveRule, rampBackground, rangeText, removeRule, ruleArity, ruleCondition,
42
+ ruleKind, rulePaint, ruleRefusal, ruleSummary, scaleBackground, scaleEnds, updateRule,
43
  } from "./rules";
44
  import { listText, parseList } from "./validation";
45
  import { CELL_COLOUR_PATTERN, MAX_SHEET_RULES, MAX_VALIDATION_LIST, SHEET_RULE_KINDS } from "./types";
46
+ import type { SheetRule, SheetRuleKind, SheetRuleOp, SheetRuleScaleType } from "./types";
47
 
48
  export interface RulesDialogProps {
49
  open: boolean;
 
90
  rules, range, onCancel, onSave,
91
  }: Omit<RulesDialogProps, "open">) {
92
  const [draft, setDraft] = useState<SheetRule[]>(() => (rules ?? []).map((r) => ({ ...r })));
93
+ /** ⭐ S67-T12: ONE rule is edited at a time, as in Excel's Rules Manager. `null` = list only. */
94
+ const [openId, setOpenId] = useState<string | null>(null);
95
+ /**
96
+ * ⛔⛔ S67-T12: A RULE'S REFUSAL IS RAISED BY SAVE AND WORN BY ITS OWN ROW. The dialog used to
97
+ * compute `rulesRefusal(draft)` on every render, so a stored rule the editor could not represent
98
+ * put a red sentence on the screen the moment the dialog opened, before anybody did anything,
99
+ * and Save then stopped at that first rule and saved nothing. Nothing is judged on open now.
100
+ */
101
+ const [flags, setFlags] = useState<Record<string, string>>({});
102
  /** The cap's own refusal, which is raised by an ACT rather than by the draft's shape. */
103
  const [notice, setNotice] = useState("");
104
  const [colourRefusals, setColourRefusals] = useState<Record<string, string>>({});
105
+ const [reveal, setReveal] = useState<string | null>(null);
106
+ const rows = useRef(new Map<string, HTMLLIElement>());
107
+ const stored = useMemo(() => new Map((rules ?? []).map((r) => [r.id, r] as const)), [rules]);
108
+
109
+ useEffect(() => {
110
+ if (!reveal) return;
111
+ rows.current.get(reveal)?.scrollIntoView({ block: "nearest" });
112
+ setReveal(null);
113
+ }, [reveal]);
114
+
115
  const colourRefusal = useCallback((id: string, reason: string) => {
116
  setColourRefusals((current) => {
117
  if ((current[id] ?? "") === reason) return current;
 
122
  });
123
  }, []);
124
 
125
+ const clearFlag = useCallback((id: string) => {
126
+ setFlags((current) => {
127
+ if (!(id in current)) return current;
128
+ const next = { ...current };
129
+ delete next[id];
130
+ return next;
131
  });
132
+ }, []);
133
+
134
+ const add = useCallback(() => {
135
+ const out = addRule(draft, blankRule(range));
136
+ setNotice(out.refusal ?? "");
137
+ if (out.refusal) return;
138
+ const id = out.rules[out.rules.length - 1].id;
139
+ setDraft(out.rules);
140
+ setOpenId(id);
141
+ setReveal(id);
142
+ }, [draft, range]);
143
 
144
  const patch = useCallback((id: string, next: Partial<SheetRule>) => {
145
  setNotice("");
146
+ clearFlag(id);
147
  setDraft((current) => updateRule(current, id, next));
148
+ }, [clearFlag]);
149
+
150
+ const flagged = Object.keys(flags).length > 0;
151
 
152
+ /**
153
+ * ⭐⭐ S67-T12: SAVE JUDGES EACH RULE ON ITS OWN, AND A BROKEN ONE NEVER HOLDS THE REST HOSTAGE.
154
+ *
155
+ * Only a rule ADDED or CHANGED in this dialog is judged: a rule the tab already stored and
156
+ * nobody touched is saved exactly as it was stored, because the server accepted it and the
157
+ * owner's complaint was a refusal about a rule he "didn't even do anything" to. The first press
158
+ * flags every incomplete edited rule on its own row and saves nothing, so a person sees which
159
+ * rules and why. A press while every incomplete rule is already flagged saves the others: a
160
+ * flagged rule the tab already stored is kept as it was stored (this editor never deletes it),
161
+ * and a flagged rule added in this dialog is left out. A rule that breaks after its row was
162
+ * judged is flagged again rather than dropped unseen.
163
+ */
164
+ const confirm = () => {
165
+ if (Object.values(colourRefusals).some(Boolean)) return;
166
+ const found: Record<string, string> = {};
167
+ for (const rule of draft) {
168
+ const was = stored.get(rule.id);
169
+ if (was && JSON.stringify(was) === JSON.stringify(rule)) continue;
170
+ const why = ruleRefusal(rule);
171
+ if (why) found[rule.id] = why;
172
+ }
173
+ const ids = Object.keys(found);
174
+ if (ids.length === 0) {
175
+ onSave(draft);
176
+ return;
177
+ }
178
+ if (ids.some((id) => flags[id] !== found[id])) {
179
+ setFlags(found);
180
+ setReveal(ids[0]);
181
+ return;
182
+ }
183
+ onSave(draft.flatMap((rule) => {
184
+ if (!found[rule.id]) return [rule];
185
+ const kept = stored.get(rule.id);
186
+ return kept ? [kept] : [];
187
+ }));
188
+ };
189
 
190
  return (
191
  <ConfirmDialog
 
193
  title="Conditional formatting"
194
  tone="primary"
195
  cancelLabel="Cancel"
196
+ confirmLabel={flagged ? "Save the other rules" : "Save rules"}
197
  onCancel={onCancel}
198
+ onConfirm={confirm}
 
 
 
 
 
 
 
 
199
  body={(
200
  <div className="sheet-rules">
201
  {/* ⭐⭐ THE ORDER RULE, SAID ON THE SURFACE THAT OWNS IT. Two rules matching one cell is
 
210
  {draft.length === 0 ? (
211
  <p className="sheet-rules-empty">No rules yet.</p>
212
  ) : (
213
+ <div className="sheet-rules-table">
214
+ {/* ⭐ S67-T12: EXCEL'S RULES MANAGER COLUMNS, in sentence case (DESIGN.md 2). */}
215
+ <div className="sheet-rules-head" aria-hidden="true">
216
+ <span />
217
+ <span>Rule</span>
218
+ <span>Format</span>
219
+ <span>Applies to</span>
220
+ <span />
221
+ </div>
222
+ <ol className="sheet-rules-list" aria-label="Rules, in the order they apply">
223
+ {draft.map((rule, index) => (
224
+ <RuleRow
225
+ key={rule.id}
226
+ rule={rule}
227
+ index={index}
228
+ count={draft.length}
229
+ open={openId === rule.id}
230
+ flag={flags[rule.id] ?? ""}
231
+ stored={stored.has(rule.id)}
232
+ rowRef={(el) => {
233
+ if (el) rows.current.set(rule.id, el);
234
+ else rows.current.delete(rule.id);
235
+ }}
236
+ onToggle={() => setOpenId((current) => (current === rule.id ? null : rule.id))}
237
+ onPatch={patch}
238
+ onColourRefusal={colourRefusal}
239
+ onMove={(delta) => {
240
+ setNotice("");
241
+ setDraft((current) => moveRule(current, rule.id, delta));
242
+ }}
243
+ onRemove={() => {
244
+ setNotice("");
245
+ clearFlag(rule.id);
246
+ setOpenId((current) => (current === rule.id ? null : current));
247
+ setDraft((current) => removeRule(current, rule.id));
248
+ }}
249
+ />
250
+ ))}
251
+ </ol>
252
+ </div>
253
  )}
254
 
255
  <div className="sheet-rules-foot">
 
261
  </span>
262
  </div>
263
 
264
+ {notice ? (
265
+ <p className="sheet-rules-refusal" role="alert">{notice}</p>
266
  ) : null}
267
  </div>
268
  )}
 
270
  );
271
  }
272
 
273
+ /**
274
+ * ⭐ S67-T12: THE FORMAT COLUMN. The paint a rule lays on a matching cell, drawn small: the fill,
275
+ * the ink and the weight on sample text for a flat rule, the ramp for a colour scale, the bar for a
276
+ * data bar. It reads the DRAFT, so changing a colour in the open editor repaints this at once.
277
+ */
278
+ function RulePreview({ rule }: { rule: SheetRule }) {
279
+ const kind = ruleKind(rule);
280
+ if (kind === "scale") {
281
+ return (
282
+ <span className="sheet-rules-preview is-ramp" role="img" aria-label="Colour scale"
283
+ style={{ background: scaleBackground(rule) }} />
284
+ );
285
+ }
286
+ if (kind === "bar") {
287
+ return (
288
+ <span className="sheet-rules-preview is-bar" role="img" aria-label="Data bar">
289
+ <span className="sheet-rules-preview-bar" style={{ background: rulePaint(rule.style?.fill) }} />
290
+ </span>
291
+ );
292
+ }
293
+ const style = rule.style ?? {};
294
+ if (!style.fill && !style.color && style.bold !== true) {
295
+ return <span className="sheet-rules-preview is-none">No format</span>;
296
+ }
297
+ return (
298
+ <span className={"sheet-rules-preview" + (style.bold ? " is-bold" : "")}
299
+ style={{ background: rulePaint(style.fill), color: rulePaint(style.color) }}>
300
+ AaBbCc
301
+ </span>
302
+ );
303
+ }
304
+
305
+ interface RuleRowProps {
306
  rule: SheetRule;
307
  index: number;
308
  count: number;
309
+ open: boolean;
310
+ /** The refusal Save raised for this rule, or `""`. */
311
+ flag: string;
312
+ /** Whether the tab already stored this rule, which decides what saving the others does to it. */
313
+ stored: boolean;
314
+ rowRef: (el: HTMLLIElement | null) => void;
315
+ onToggle: () => void;
316
  onPatch: (id: string, next: Partial<SheetRule>) => void;
317
  onColourRefusal: (id: string, reason: string) => void;
318
  onMove: (delta: number) => void;
319
  onRemove: () => void;
320
  }
321
 
322
+ /**
323
+ * ⭐⭐ S67-T12: ONE SUMMARY ROW PER RULE, and the rule's editor opens UNDER its own row only when
324
+ * that row is clicked. The row is a real button (`aria-expanded`), so Enter and Space open it too.
325
+ */
326
+ function RuleRow({
327
+ rule, index, count, open, flag, stored, rowRef, onToggle, onPatch, onColourRefusal, onMove,
328
+ onRemove,
329
+ }: RuleRowProps) {
330
+ const ids = useId();
331
+ const where = rangeText(rule.range);
332
+ const condition = ruleCondition(rule);
333
+ return (
334
+ <li ref={rowRef}
335
+ className={"sheet-rules-card" + (open ? " is-open" : "") + (flag ? " is-flagged" : "")}>
336
+ <div className="sheet-rules-line">
337
+ <span className="sheet-rules-order" aria-hidden="true">{index + 1}</span>
338
+ <button
339
+ type="button"
340
+ className="sheet-rules-pick"
341
+ aria-expanded={open}
342
+ aria-controls={open ? `${ids}-editor` : undefined}
343
+ aria-describedby={flag ? `${ids}-flag` : undefined}
344
+ aria-label={`Rule ${index + 1}: ${ruleSummary(rule)}`}
345
+ onClick={onToggle}
346
+ >
347
+ <span className="sheet-rules-summary" title={condition}>{condition}</span>
348
+ <RulePreview rule={rule} />
349
+ <span className="sheet-rules-where" title={where}>{where}</span>
350
+ </button>
351
+ <div className="sheet-rules-moves">
352
+ <button
353
+ type="button"
354
+ className="sheet-rules-move"
355
+ aria-label={`Move rule ${index + 1} up`}
356
+ title="Move up"
357
+ disabled={index === 0}
358
+ onClick={() => onMove(-1)}
359
+ >
360
+ <IconChevron />
361
+ </button>
362
+ <button
363
+ type="button"
364
+ className="sheet-rules-move is-down"
365
+ aria-label={`Move rule ${index + 1} down`}
366
+ title="Move down"
367
+ disabled={index === count - 1}
368
+ onClick={() => onMove(1)}
369
+ >
370
+ <IconChevron />
371
+ </button>
372
+ <button
373
+ type="button"
374
+ className="sheet-rules-remove"
375
+ aria-label={`Delete rule ${index + 1}`}
376
+ title="Delete this rule"
377
+ onClick={onRemove}
378
+ >
379
+ <IconRemove />
380
+ </button>
381
+ </div>
382
+ </div>
383
+ {flag ? (
384
+ <p className="sheet-rules-flag" id={`${ids}-flag`}>
385
+ {flag} {stored
386
+ ? "Saving the other rules keeps this one as it was."
387
+ : "Saving the other rules leaves this one out."}
388
+ </p>
389
+ ) : null}
390
+ {open ? (
391
+ <RuleEditor rule={rule} editorId={`${ids}-editor`} onPatch={onPatch}
392
+ onColourRefusal={onColourRefusal} />
393
+ ) : null}
394
+ </li>
395
+ );
396
+ }
397
+
398
+ interface RuleEditorProps {
399
+ rule: SheetRule;
400
+ editorId: string;
401
+ onPatch: (id: string, next: Partial<SheetRule>) => void;
402
+ onColourRefusal: (id: string, reason: string) => void;
403
+ }
404
+
405
+ function RuleEditor({ rule, editorId, onPatch, onColourRefusal }: RuleEditorProps) {
406
  const ids = useId();
407
  const kind = ruleKind(rule);
408
  const arity = ruleArity(rule.op);
409
+ // The OPEN rule's range and any cell its formula names are outlined on the grid
410
+ // (refHighlight.ts). S67-T12: only the open rule, so fifty stored rules no longer outline at once.
411
  useCellRefHighlight([rangeText(rule.range), kind === "formula" ? String(rule.value ?? "") : ""]);
412
 
413
  /**
 
432
  onPatch(rule.id, { kind: next, op: "eq", value: "", value2: undefined, scale: undefined });
433
  return;
434
  }
435
+ // ⭐ S67-T13: a new colour scale spreads from the lowest to the highest value, Excel's
436
+ // default, and carries no stale bound from the kind it was switched from.
437
+ if (next === "scale") {
438
+ onPatch(rule.id, {
439
+ kind: next,
440
+ op: "between",
441
+ value: undefined,
442
+ value2: undefined,
443
+ scale: {
444
+ ...(rule.scale ?? { low: DEFAULT_RULE_SCALE.low, high: DEFAULT_RULE_SCALE.high }),
445
+ minType: "lowest",
446
+ maxType: "highest",
447
+ },
448
+ });
449
+ return;
450
+ }
451
  onPatch(rule.id, {
452
  kind: next,
453
  op: "between",
454
+ scale: rule.scale,
 
 
455
  style: next === "bar" ? { fill: rule.style?.fill || DEFAULT_BAR_FILL } : rule.style,
456
  });
457
  };
458
 
459
  return (
460
+ <div className="sheet-rules-editor" id={editorId}>
461
  <div className="sheet-rules-row">
 
462
  <label className="sheet-rules-field">
463
+ <span className="sheet-rules-label" id={`${ids}-range`}>Applies to</span>
464
  <input
465
  className="sheet-rules-input"
466
  type="text"
 
470
  onChange={(e) => onPatch(rule.id, { range: e.target.value })}
471
  />
472
  </label>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
473
  </div>
474
 
475
  <div className="sheet-rules-row">
 
477
  colour scale and a data bar are created from the ribbon's Conditional formatting
478
  gallery, and an editor that could not represent them would have listed a rule it
479
  could not describe, or worse, quietly rewritten it into a condition nobody chose. */}
480
+ {/* ⚠ S66-T12: a select field sizes to its longest label (`is-select`), so "Highlight
481
+ cells" and "Is not empty" are never clipped by a shared flex row. */}
482
+ <label className="sheet-rules-field is-select">
483
  <span className="sheet-rules-label" id={`${ids}-kind`}>Rule</span>
484
  <select
485
  className="sheet-rules-select"
 
493
  </select>
494
  </label>
495
  {kind === "cell" ? (
496
+ <label className="sheet-rules-field is-select">
497
  <span className="sheet-rules-label" id={`${ids}-op`}>Condition</span>
498
  <select
499
  className="sheet-rules-select"
 
520
  />
521
  </label>
522
  ) : null}
523
+ {kind === "scale" ? (
524
+ <>
525
+ <ScaleEndFields rule={rule} which="min" onPatch={onPatch} />
526
+ <ScaleEndFields rule={rule} which="max" onPatch={onPatch} />
527
+ </>
528
+ ) : null}
529
+ {kind !== "formula" && kind !== "scale" && arity >= 1 ? (
530
  <label className="sheet-rules-field">
531
  <span className="sheet-rules-label" id={`${ids}-value`}>
532
  {arity === 2 ? "From" : "Value"}
 
540
  />
541
  </label>
542
  ) : null}
543
+ {kind !== "formula" && kind !== "scale" && arity === 2 ? (
544
  <label className="sheet-rules-field">
545
  <span className="sheet-rules-label" id={`${ids}-value2`}>To</span>
546
  <input
 
576
  aria-label={ramp.label}
577
  aria-pressed={on}
578
  title={ramp.label}
579
+ onClick={() => onPatch(rule.id, {
580
+ scale: { ...rule.scale, low: ramp.low, high: ramp.high },
581
+ })}
582
  />
583
  );
584
  })}
 
638
  palette={RULE_FILLS} onPatch={onPatch} onRefusal={onColourRefusal} />
639
  </div>
640
  ) : null}
641
+ </div>
642
+ );
643
+ }
644
+
645
+ /**
646
+ * ⭐⭐ S67-T13: ONE END OF A COLOUR SCALE, AS EXCEL'S RULES MANAGER EDITS IT. A type picker
647
+ * (Lowest value / Highest value, Number, Percent, Percentile) and, unless the end is measured
648
+ * from the data, the number that type needs. It reads through `rules.ts::scaleEnds`, so an
649
+ * imported boundless scale opens as lowest to highest with nothing to fix.
650
+ *
651
+ * ⚠ TYPING PINS THE TYPE. A legacy scale's `number` end is read from its stored number, so
652
+ * clearing that box without pinning would flip the end back to lowest under the cursor and hide
653
+ * the box being typed in.
654
+ */
655
+ function ScaleEndFields({ rule, which, onPatch }: {
656
+ rule: SheetRule;
657
+ which: "min" | "max";
658
+ onPatch: RuleEditorProps["onPatch"];
659
+ }) {
660
+ const ids = useId();
661
+ const ends = scaleEnds(rule);
662
+ const end = which === "min" ? ends.min : ends.max;
663
+ const measured: SheetRuleScaleType = which === "min" ? "lowest" : "highest";
664
+ const offered = which === "min" ? RULE_SCALE_MIN_TYPES : RULE_SCALE_MAX_TYPES;
665
+ const options = offered.includes(end.type) ? offered : [...offered, end.type];
666
+ const name = which === "min" ? "Minimum" : "Maximum";
667
+ const raw = which === "min" ? rule.value : rule.value2;
668
+ const scale = rule.scale ?? { low: DEFAULT_RULE_SCALE.low, high: DEFAULT_RULE_SCALE.high };
669
+ const withType = (type: SheetRuleScaleType) => (
670
+ which === "min" ? { ...scale, minType: type } : { ...scale, maxType: type }
671
+ );
672
+ const withValue = (value: string | undefined): Partial<SheetRule> => (
673
+ which === "min" ? { value } : { value2: value }
674
+ );
675
+ return (
676
+ <>
677
+ <label className="sheet-rules-field is-select">
678
+ <span className="sheet-rules-label" id={`${ids}-type`}>{name}</span>
679
+ <select
680
+ className="sheet-rules-select"
681
+ value={end.type}
682
+ aria-labelledby={`${ids}-type`}
683
+ onChange={(e) => {
684
+ const type = e.target.value as SheetRuleScaleType;
685
+ onPatch(rule.id, {
686
+ scale: withType(type),
687
+ ...(type === measured ? withValue(undefined) : {}),
688
+ });
689
+ }}
690
+ >
691
+ {options.map((type) => (
692
+ <option key={type} value={type}>{RULE_SCALE_TYPE_LABEL[type]}</option>
693
+ ))}
694
+ </select>
695
+ </label>
696
+ {end.type !== "lowest" && end.type !== "highest" ? (
697
+ <label className="sheet-rules-field">
698
+ <span className="sheet-rules-label" id={`${ids}-value`}>Value</span>
699
+ <input
700
+ className="sheet-rules-input"
701
+ type="text"
702
+ inputMode="decimal"
703
+ value={String(raw ?? "")}
704
+ aria-label={`${name} value`}
705
+ placeholder={end.type === "number" ? "" : "0 to 100"}
706
+ onChange={(e) => onPatch(rule.id, {
707
+ scale: withType(end.type),
708
+ ...withValue(e.target.value),
709
+ })}
710
+ />
711
+ </label>
712
+ ) : null}
713
+ </>
714
  );
715
  }
716
 
 
731
  which: "color" | "fill";
732
  label: string;
733
  palette: readonly { token: string; label: string }[];
734
+ onPatch: RuleEditorProps["onPatch"];
735
+ onRefusal: RuleEditorProps["onColourRefusal"];
736
  }) {
737
  const id = useId();
738
  const chosen = rule.style?.[which];
web/src/sheet/SheetGrid.tsx CHANGED
@@ -183,13 +183,16 @@ import { drawSparkline } from "./sparkline";
183
  // ⭐ W54-T14 / LANE B — A CELL'S ATTACHMENTS: the canvas marks, the hover bubble and the door that
184
  // follows a link. `LinkDialog.tsx` owns all three beside the surface that authors them; this file
185
  // owns only the wiring, which is one call in the paint and one in each grid's click and hover.
186
- import { NoteBubble, followLink, paintCellMarks } from "./LinkDialog";
 
 
 
187
  import type { FollowContext } from "./LinkDialog";
188
  import {
189
  canonicalEntry, checkEntry, filterList, refusalLabel, screenEdits, validationEdits, validationOf,
190
  } from "./validation";
191
  import {
192
- fontPx, fontStack, formatCellText, stylePaints, sheetExtent,
193
  DEFAULT_COL_WIDTH, DEFAULT_FONT_PT, DEFAULT_SHEET_COLS, DEFAULT_SHEET_ROWS,
194
  MAX_CELL_INDENT, MAX_COL_WIDTH, MIN_COL_WIDTH,
195
  } from "./types";
@@ -209,7 +212,7 @@ import {
209
  visibleIndices, withHidden, outlineHiddenRows, rowGroupRefusal, rowOutlineItems,
210
  } from "./sheetState";
211
  import type {
212
- CellRange, DragContext, FillEdit, OptionCatalogue, StructureOp,
213
  } from "./sheetState";
214
  import type { SavedViewShadow } from "./bindingRefs";
215
  // ⛔⛔ W51-T17 — ONE TABLE, TWO CONSUMERS. `shortcuts.ts` is the key map AND the panel's rows, and
@@ -316,6 +319,18 @@ const SHEET_ROW_MARKER_WIDTH = 44;
316
  const SHEET_HEADER_HEIGHT = 36;
317
  const MIN_ROW_HEIGHT = 18;
318
  const MAX_ROW_HEIGHT = 200;
 
 
 
 
 
 
 
 
 
 
 
 
319
 
320
  /**
321
  * Whether one visible row/column heading belongs to the document selection's paint projection.
@@ -709,7 +724,11 @@ export interface SheetGridProps {
709
  * One or many cells, committed and SAVED AS ONE STEP. `null` clears a cell. A paste, a fill and
710
  * a range delete each arrive here once, so they take one history step and one PUT.
711
  */
712
- onCommit: (edits: Record<string, Cell | null>) => void;
 
 
 
 
713
  /** The one cell selected when this workbook and tab are adopted. */
714
  openAt: { workbookId: string; tabId: string; addr: string };
715
  onUndo: () => void;
@@ -821,6 +840,20 @@ export interface SheetGridProps {
821
  options?: OptionCatalogue;
822
  /** Canonical saved-View filters loaded before a copy, for R5's local shadow materialisation. */
823
  viewShadows?: readonly SavedViewShadow[];
 
 
 
 
 
 
 
 
 
 
 
 
 
 
824
  }
825
 
826
  /** The copied cells that must take the same save-then-compute path as Binding editor Save. */
@@ -1103,7 +1136,7 @@ export default function SheetGrid({
1103
  onSelect, onStructure, onGrow, onFreeze, onColumnWidth, onRowHeight, onHideBands, onRules, onCharts,
1104
  onTabView, onTabVisibility, onRowGroups,
1105
  onSelectTab,
1106
- options, viewShadows,
1107
  }: SheetGridProps) {
1108
  /**
1109
  * ⭐ THE CLIENT VIEW IS RECALCULATED FROM THE WHOLE WORKBOOK. This is a projection, not an
@@ -1371,6 +1404,9 @@ export default function SheetGrid({
1371
  useEscapeClose(find !== null, () => setFind(null));
1372
  const [anchor, setAnchor] = useState<Rectangle | null>(null);
1373
  const [menu, setMenu] = useState<SheetMenu | null>(null);
 
 
 
1374
  const [viewMenu, setViewMenu] = useState<ViewHeaderMenu | null>(null);
1375
  const viewMenuRef = useRef<ViewHeaderMenu | null>(null);
1376
  const [filterState, setFilterState] = useState<SheetFilter | null>(null);
@@ -1483,6 +1519,8 @@ export default function SheetGrid({
1483
  const formulaCaretSizerRef = useRef<HTMLSpanElement | null>(null);
1484
  const formulaCaretPrefixRef = useRef<HTMLSpanElement | null>(null);
1485
  const [formulaBox, setFormulaBox] = useState<{ width: number; height: number } | null>(null);
 
 
1486
  const [formulaCaretOffset, setFormulaCaretOffset] = useState<{ x: number; y: number }>();
1487
  /**
1488
  * ⭐⭐ W54-T21 / INSTRUCTION 18 — THE ONE FLAG THAT STOPS ESCAPE COMMITTING WHAT IT CANCELLED.
@@ -1544,6 +1582,17 @@ export default function SheetGrid({
1544
  (formulaGridWasBand.current ? bandGridRef : gridRef).current?.focus();
1545
  }, [formulaEdit]);
1546
 
 
 
 
 
 
 
 
 
 
 
 
1547
  const extent = sheetExtent(tab);
1548
  const widths = tab.colWidths ?? {};
1549
 
@@ -1922,9 +1971,17 @@ export default function SheetGrid({
1922
  * format looks like, and the two would drift the first time either was touched. The band grid
1923
  * asks the main one, having said which row it means.
1924
  */
 
 
 
 
 
 
1925
  const getFrozenContent = useCallback(
1926
  (item: Item): GridCell => getCellContent(fromBand(item)),
1927
- [fromBand, getCellContent],
 
 
1928
  );
1929
 
1930
  const selected = useMemo(() => {
@@ -2264,7 +2321,7 @@ export default function SheetGrid({
2264
  }
2265
  }, [applyViewAnswer]);
2266
 
2267
- const commitWithRecalc = useCallback((edits: Record<string, Cell | null>) => {
2268
  const entries = Object.entries(edits);
2269
  const reserved = entries.some(([addr, value]) => value && isViewReserved(addr));
2270
  if (reserved) { onNotice("Resize or remove this view before editing its reserved cells."); return; }
@@ -2278,7 +2335,8 @@ export default function SheetGrid({
2278
  void commitViewRecord(addr, editableText(cell));
2279
  return;
2280
  }
2281
- onCommit({ ...edits, ...recalcDependents(tab, edits, workbook.sheets, workbook, calculationSession.current) });
 
2282
  }, [commitViewRecord, isViewReserved, onCommit, onNotice, tab, workbook]);
2283
 
2284
  /** ONE typed commit. `commitTyped` picks literal or formula and drops a binding on its own. */
@@ -2800,20 +2858,19 @@ export default function SheetGrid({
2800
  * edges whose neighbour belongs to a different reference or none. Reference ordinals keep
2801
  * touching ranges separate even when their slot colours repeat; no interior fill is added.
2802
  *
2803
- * ⭐⭐ W53-T02 / INSTRUCTION 18 — RANGE FINDER ALSO FIRES ON A BARE SELECTION. Microsoft's own
2804
- * page documents only the edit-mode trigger ("double-click the cell ... Excel highlights each
2805
- * cell or range of cells referenced by the formula with a different color"), and instruction 18
2806
- * widens it in this app's own words: "Excel highlights EVERY cell a formula references when you
2807
- * click a formula cell". So when no editor is open, the SELECTED cell's stored formula lends
2808
- * its text to this same engine. One source string, one border map, one paint path
2809
- * (`paintRefBorder` further down) - there is no second outline mechanism to keep in step.
 
2810
  */
2811
  const externalRefs = useHighlightedCellRefs();
2812
  const formulaRefCells = useMemo(() => {
2813
  const out = new Map<string, { color: string; ref: number }>();
2814
- const source = formulaEdit
2815
- ? formulaEdit.draft
2816
- : (selected?.cell?.kind === "formula" ? (selected.cell.formula ?? "") : "");
2817
  // Hotfix 2026-09-24 (owner: "ANYWHERE in the app ... the cell must be highlighted"): every
2818
  // reference a mounted panel is asking about (`refHighlight.ts`) joins the SAME map, after the
2819
  // formula's own, so it gets the outline and the repaint this map already has. A reference
@@ -2847,7 +2904,7 @@ export default function SheetGrid({
2847
  }
2848
  }
2849
  return out;
2850
- }, [externalRefs, formulaEdit, selected, tab.name]);
2851
 
2852
  // A reference a person just TYPED is scrolled to, so a cell far off screen (R9997) is seen being
2853
  // outlined rather than outlined out of sight. Opening a panel scrolls nowhere (refHighlight.ts).
@@ -2956,6 +3013,7 @@ export default function SheetGrid({
2956
  const paintedRefCells = useRef<string[]>([]);
2957
  useEffect(() => {
2958
  const now = refPaintKey ? refPaintKey.split("|").map((p) => p.slice(0, p.indexOf(":"))) : [];
 
2959
  const union = new Set([...paintedRefCells.current, ...now]);
2960
  paintedRefCells.current = now;
2961
  if (union.size === 0) return;
@@ -2973,6 +3031,8 @@ export default function SheetGrid({
2973
  }
2974
  if (main.length > 0) gridRef.current?.updateCells(main);
2975
  if (band.length > 0) bandGridRef.current?.updateCells(band);
 
 
2976
  }, [bandRows, refPaintKey, viewRowOf, visCols]);
2977
 
2978
  /** The selected rectangle in glide's own VIEW coordinates, or `null` when nothing is selected. */
@@ -3210,7 +3270,7 @@ export default function SheetGrid({
3210
  // ⭐ W53-T01: a fill or a paste can change a cell some OTHER formula reads, so the landing
3211
  // door recalculates its dependents in the same commit every typed edit does.
3212
  if (Object.keys(edits).length > 0) {
3213
- commitWithRecalc(edits);
3214
  // C5: schedule only the bound cells that ACTUALLY landed. The page owns save ordering and
3215
  // revisions, so this seam carries identities instead of calling Refresh or a second writer.
3216
  const pending: Record<string, Cell> = {};
@@ -3389,6 +3449,116 @@ export default function SheetGrid({
3389
  onCommit(out.edits);
3390
  }, [onCommit, onNotice, selectedAddrs, tab]);
3391
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3392
  /**
3393
  * ⭐ W51-T15: CLEARING THE SELECTION, SAID ONCE. The Delete key and the ribbon's Clear contents
3394
  * are the SAME act, so the two cannot disagree about R5: a bound cell in the selection clears
@@ -3762,6 +3932,29 @@ export default function SheetGrid({
3762
  return () => host.removeEventListener(KEY_TIP_GRID_ARROW_EVENT, moveFromKeyTips);
3763
  }, [applySelection, bandRows, selection, visRows.length]);
3764
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3765
  /**
3766
  * Ctrl+PgUp and Ctrl+PgDn. See `onSelectTab` in the props above for why there are two paths.
3767
  *
@@ -4635,6 +4828,139 @@ export default function SheetGrid({
4635
  setListAsk({ addrs, list: [...(validationOf(cellAt(tab, addrs[0]))?.list ?? [])] });
4636
  }, [onNotice, selectedAddrs, tab]);
4637
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4638
  /**
4639
  * Write the list onto every selected cell, as ONE commit.
4640
  *
@@ -4942,6 +5268,24 @@ export default function SheetGrid({
4942
  // to the reader's key for this event only; a later data-identity reconciliation has no key.
4943
  keyboardSelectingRef.current = true;
4944
  queueMicrotask(() => { keyboardSelectingRef.current = false; });
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4945
  // A canvas button also has a keyboard door, without another key listener.
4946
  if (event.altKey && !event.ctrlKey && !event.metaKey && event.key === "ArrowDown") {
4947
  const item = selectionRef.current?.current?.cell;
@@ -5527,6 +5871,7 @@ export default function SheetGrid({
5527
  useLayoutEffect(() => {
5528
  if (!formulaEdit) {
5529
  setFormulaBox(null);
 
5530
  setFormulaCaretOffset(undefined);
5531
  return;
5532
  }
@@ -5539,12 +5884,33 @@ export default function SheetGrid({
5539
  const boundsRef = formulaEdit.inBand ? bandGridRef : gridRef;
5540
  const bounds = boundsRef.current?.getBounds(formulaEdit.viewCell[0], formulaEdit.viewCell[1]);
5541
  if (!bounds) return;
5542
- const maxWidth = Math.max(bounds.width,
 
 
 
 
 
 
 
 
 
5543
  (canvas?.getBoundingClientRect().right ?? window.innerWidth) - bounds.x - 4);
 
 
 
 
 
5544
  sizer.style.maxWidth = `${maxWidth}px`;
5545
  const width = Math.max(bounds.width, Math.ceil(sizer.offsetWidth));
5546
  const height = Math.max(bounds.height, Math.ceil(sizer.offsetHeight));
5547
  setFormulaBox({ width, height });
 
 
 
 
 
 
 
5548
 
5549
  // The prefix ends at the caret, but the suffix stays in the same inline flow: dropping
5550
  // it would measure a different wrap when the caret sits in the middle of a word.
@@ -5758,7 +6124,9 @@ export default function SheetGrid({
5758
  const currentRect = { ...borderRect,
5759
  x: borderRect.x + (col < frozenCols ? 0 : latest.x - originX),
5760
  y: borderRect.y + latest.y - originY };
5761
- const paneRight = col < frozenCols ? columnX(frozenCols) + 1
 
 
5762
  : ctx.canvas.width / latest.transform.a;
5763
  const paneBottom = ctx.canvas.height / latest.transform.d;
5764
  if (currentRect.x + currentRect.width < paneLeft || currentRect.x >= paneRight
@@ -5997,13 +6365,34 @@ export default function SheetGrid({
5997
  // UNSCALED space: at any browser zoom but 100% the run landed shrunk and offset, a ghost of
5998
  // the label. The border paint above already carries the transform; this run now does too.
5999
  const spillTransform = ctx.getTransform();
 
 
 
 
 
 
 
 
 
 
6000
  // Glide paints gridlines after drawCell. Deduplicate every participating cell into one
6001
  // owner run, then mask only its interior separators and redraw the text in the next frame.
6002
  queueSpillPaint(`${row}:${ownerCol}`, () => {
 
 
 
 
 
 
 
 
 
6003
  ctx.save();
6004
- ctx.setTransform(spillTransform);
 
 
6005
  ctx.beginPath();
6006
- ctx.rect(runLeft + 1, rowTop + 1, Math.max(0, runRight - runLeft - 2), rowHeight - 2);
6007
  ctx.clip();
6008
  ctx.fillStyle = cellFillColor;
6009
  let separatorX = runLeft;
@@ -6985,141 +7374,108 @@ export default function SheetGrid({
6985
  </div>
6986
  </AnchoredOverlay>
6987
  )}
6988
- {menu && (
6989
- <AnchoredOverlay
 
 
6990
  anchor={menu.anchor}
6991
- className="cg-pop"
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
6992
  placement="bottom-start"
6993
- role="menu"
6994
- ariaLabel="Rows and columns"
6995
- onDismiss={() => setMenu(null)}
6996
  >
6997
- {/* ⭐⭐ W51-T17 / R14 — THE SHEET GETS EXCEL'S HEADER MENU: Insert above or below, left
6998
- or right, Delete, Clear, Hide, Resize and Format. It is the SAME menu the grid
6999
- already opened rather than a second one, and which items it offers follows the
7000
- surface that was right clicked: a column header has no row to insert above.
7001
- ⚠ Every item routes to a door that already exists, so no act here opens a second
7002
- save path and none of them re-decides a refusal the page owns. */}
7003
- <div className="cg-type-list">
7004
- {menu.on !== "column" && onRowGroups && <>
7005
- <button type="button" role="menuitem" className="cg-type-row" disabled={busy}
7006
- onClick={() => { setMenu(null); groupRows(); }}>
7007
- <span className="cg-type-label">Group rows</span>
7008
- </button>
7009
- {rowGroups.length > 0 && <button type="button" role="menuitem" className="cg-type-row" disabled={busy}
7010
- onClick={() => { setMenu(null); ungroupRows(); }}>
7011
- <span className="cg-type-label">Ungroup rows</span>
7012
- </button>}
7013
- </>}
7014
- {menu.on !== "column" && (
7015
- <>
7016
- <button
7017
- type="button" role="menuitem" className="cg-type-row"
7018
- onClick={() => structure("row", 1, menu.row)}
7019
- >
7020
- <span className="cg-type-label">Insert row above</span>
7021
- </button>
7022
- <button
7023
- type="button" role="menuitem" className="cg-type-row"
7024
- onClick={() => structure("row", 1, menu.row + 1)}
7025
- >
7026
- <span className="cg-type-label">Insert row below</span>
7027
- </button>
7028
- <button
7029
- type="button" role="menuitem" className="cg-type-row"
7030
- onClick={() => structure("row", -1, menu.row)}
7031
- >
7032
- <span className="cg-type-label">Delete row {menu.row}</span>
7033
- </button>
7034
- </>
7035
- )}
7036
- {menu.on !== "row" && (
7037
- <>
7038
- <button
7039
- type="button" role="menuitem" className="cg-type-row"
7040
- onClick={() => structure("col", 1, menu.col)}
7041
- >
7042
- <span className="cg-type-label">Insert column left</span>
7043
- </button>
7044
- <button
7045
- type="button" role="menuitem" className="cg-type-row"
7046
- onClick={() => structure("col", 1, menu.col + 1)}
7047
- >
7048
- <span className="cg-type-label">Insert column right</span>
7049
- </button>
7050
- <button
7051
- type="button" role="menuitem" className="cg-type-row"
7052
- onClick={() => structure("col", -1, menu.col)}
7053
- >
7054
- <span className="cg-type-label">
7055
- Delete column {indexToCol(menu.col)}
7056
- </span>
7057
- </button>
7058
- </>
7059
- )}
7060
- <button
7061
- type="button" role="menuitem" className="cg-type-row"
7062
- onClick={() => { setMenu(null); clearSelection(); }}
7063
- >
7064
- <span className="cg-type-label">Clear contents</span>
7065
- </button>
7066
- {menu.on !== "column" && (
7067
- <button
7068
- type="button" role="menuitem" className="cg-type-row"
7069
- onClick={() => { setMenu(null); hideBand("row"); }}
7070
- >
7071
- <span className="cg-type-label">Hide rows</span>
7072
- </button>
7073
- )}
7074
- {menu.on !== "row" && (
7075
- <button
7076
- type="button" role="menuitem" className="cg-type-row"
7077
- onClick={() => { setMenu(null); hideBand("col"); }}
7078
- >
7079
- <span className="cg-type-label">Hide columns</span>
7080
- </button>
7081
- )}
7082
- <button
7083
- type="button" role="menuitem" className="cg-type-row"
7084
- onClick={() => { setMenu(null); unhideAll(); }}
7085
- >
7086
- <span className="cg-type-label">Unhide</span>
7087
- </button>
7088
- <button
7089
- type="button" role="menuitem" className="cg-type-row"
7090
- onClick={() => {
7091
- setMenu(null);
7092
- setAsk(menu.on === "column"
7093
- ? { kind: "column-width", value: COL_WIDTH }
7094
- : { kind: "row-height", value: rowHeight });
7095
- }}
7096
- >
7097
- <span className="cg-type-label">
7098
- {menu.on === "column" ? "Resize the column" : "Resize the rows"}
7099
- </span>
7100
- </button>
7101
- {/* ⛔ FORMAT OPENS THE RIBBON'S OWN NUMBER MENU, not a second format surface. Same
7102
- door Ctrl+1 takes, for the same contract C1 reason. */}
7103
- <button
7104
- type="button" role="menuitem" className="cg-type-row"
7105
- onClick={() => { setMenu(null); openNumberFormat(); }}
7106
- >
7107
- <span className="cg-type-label">Format</span>
7108
- </button>
7109
- {/* ⭐⭐ W51-T18 / C2 — THE VALIDATION LIST'S ONLY DOOR, and the done-when names it:
7110
- a cell or a range gets its list from the CELL context menu. A column header has
7111
- no cells selected to write to, so it is not offered there. */}
7112
- {menu.on !== "column" && (
7113
- <button
7114
- type="button" role="menuitem" className="cg-type-row"
7115
- onClick={() => { setMenu(null); openValidation(); }}
7116
- >
7117
- <span className="cg-type-label">Values this cell accepts</span>
7118
  </button>
7119
- )}
7120
  </div>
7121
  </AnchoredOverlay>
7122
  )}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7123
 
7124
  {/* ⭐⭐ THE ROW HEIGHT AND COLUMN WIDTH ASK, RENDERED INSIDE THE SHEET'S OWN CONTENT BOX
7125
  RATHER THAN PORTALLED. A portal drops every descendant-scoped rule it was styled by, and
@@ -7432,7 +7788,11 @@ export default function SheetGrid({
7432
  className="sheet-formula-editor"
7433
  style={{ left: bounds.x, top: bounds.y,
7434
  width: formulaBox?.width ?? bounds.width, height: formulaBox?.height ?? bounds.height,
7435
- lineHeight: `${Math.max(1, bounds.height - 2)}px` }}
 
 
 
 
7436
  >
7437
  <div className="sheet-formula-editor-input-wrap">
7438
  {/* CR-1/CR-5: the coloured backdrop, mounted only once a reference exists (a plain
 
183
  // ⭐ W54-T14 / LANE B — A CELL'S ATTACHMENTS: the canvas marks, the hover bubble and the door that
184
  // follows a link. `LinkDialog.tsx` owns all three beside the surface that authors them; this file
185
  // owns only the wiring, which is one call in the paint and one in each grid's click and hover.
186
+ import LinkDialog, { NoteBubble, followLink, paintCellMarks } from "./LinkDialog";
187
+ import type { CellLink } from "./LinkDialog";
188
+ import CellContextMenu, { FONT_SIZE_LADDER } from "./CellContextMenu";
189
+ import type { CellMenuAct } from "./CellContextMenu";
190
  import type { FollowContext } from "./LinkDialog";
191
  import {
192
  canonicalEntry, checkEntry, filterList, refusalLabel, screenEdits, validationEdits, validationOf,
193
  } from "./validation";
194
  import {
195
+ fontPt, fontPx, fontStack, formatCellText, stylePaints, sheetExtent, CELL_FONTS, DEFAULT_CELL_FONT,
196
  DEFAULT_COL_WIDTH, DEFAULT_FONT_PT, DEFAULT_SHEET_COLS, DEFAULT_SHEET_ROWS,
197
  MAX_CELL_INDENT, MAX_COL_WIDTH, MIN_COL_WIDTH,
198
  } from "./types";
 
212
  visibleIndices, withHidden, outlineHiddenRows, rowGroupRefusal, rowOutlineItems,
213
  } from "./sheetState";
214
  import type {
215
+ CellRange, DragContext, FillEdit, MovedBlock, OptionCatalogue, StructureOp,
216
  } from "./sheetState";
217
  import type { SavedViewShadow } from "./bindingRefs";
218
  // ⛔⛔ W51-T17 — ONE TABLE, TWO CONSUMERS. `shortcuts.ts` is the key map AND the panel's rows, and
 
319
  const SHEET_HEADER_HEIGHT = 36;
320
  const MIN_ROW_HEIGHT = 18;
321
  const MAX_ROW_HEIGHT = 200;
322
+ /** S67-T02: the narrowest the in-cell formula editor wraps at when a cell sits by the pane's
323
+ * right edge (about 50 characters), and the room kept under it, inside the window, for the
324
+ * Enter/Point label. */
325
+ const FORMULA_EDITOR_READABLE_WIDTH = 360;
326
+ const FORMULA_MODE_RESERVE = 22;
327
+
328
+ /** S67-T11 / C2: one border side exactly as lane B's contract shapes it, `{style, color}`. */
329
+ interface BorderPenLine { style: string; color: string }
330
+ /** S67-T11: Excel's three Draw Border pens, raised by `aios:sheet-border-draw`. */
331
+ type BorderPen = BorderPenLine & { mode: "draw" | "grid" | "erase" };
332
+ type BorderPenSide = "top" | "right" | "bottom" | "left";
333
+ const BORDER_PEN_STYLES = ["thin", "medium", "thick", "dashed", "dotted", "double", "hair"];
334
 
335
  /**
336
  * Whether one visible row/column heading belongs to the document selection's paint projection.
 
724
  * One or many cells, committed and SAVED AS ONE STEP. `null` clears a cell. A paste, a fill and
725
  * a range delete each arrive here once, so they take one history step and one PUT.
726
  */
727
+ /**
728
+ * S67-T09: `move` rides along when these edits MOVE a block (a completed cut), so the page can
729
+ * re-anchor every reference to it on every tab in the SAME history step.
730
+ */
731
+ onCommit: (edits: Record<string, Cell | null>, move?: MovedBlock) => void;
732
  /** The one cell selected when this workbook and tab are adopted. */
733
  openAt: { workbookId: string; tabId: string; addr: string };
734
  onUndo: () => void;
 
840
  options?: OptionCatalogue;
841
  /** Canonical saved-View filters loaded before a copy, for R5's local shadow materialisation. */
842
  viewShadows?: readonly SavedViewShadow[];
843
+
844
+ // ── S67-T02, contract C1 ───────────────────────────────────────────────────────────────────
845
+ /**
846
+ * The in-cell formula draft, for the formula bar to mirror while it is typed. Called with the
847
+ * draft whenever this component's own editor opens or its draft changes (typing, a pointed
848
+ * reference, an accepted suggestion, F4), and with `null` whenever that editor closes (commit,
849
+ * Escape, unmount). Optional so a page that has not wired it compiles unchanged.
850
+ */
851
+ onDraftChange?: (draft: string | null) => void;
852
+ /**
853
+ * S67-T07: the reader may view this workbook but not change it, so the cell menu SHOWS its edit
854
+ * items disabled rather than hiding them. Absent reads as editable (the server still refuses).
855
+ */
856
+ readOnly?: boolean;
857
  }
858
 
859
  /** The copied cells that must take the same save-then-compute path as Binding editor Save. */
 
1136
  onSelect, onStructure, onGrow, onFreeze, onColumnWidth, onRowHeight, onHideBands, onRules, onCharts,
1137
  onTabView, onTabVisibility, onRowGroups,
1138
  onSelectTab,
1139
+ options, viewShadows, onDraftChange, readOnly = false,
1140
  }: SheetGridProps) {
1141
  /**
1142
  * ⭐ THE CLIENT VIEW IS RECALCULATED FROM THE WHOLE WORKBOOK. This is a projection, not an
 
1404
  useEscapeClose(find !== null, () => setFind(null));
1405
  const [anchor, setAnchor] = useState<Rectangle | null>(null);
1406
  const [menu, setMenu] = useState<SheetMenu | null>(null);
1407
+ // S67-T07: the cell menu's New Comment / New Note and Link open these, over the anchor cell.
1408
+ const [noteAsk, setNoteAsk] = useState<{ addr: string; text: string } | null>(null);
1409
+ const [linkAsk, setLinkAsk] = useState<string | null>(null);
1410
  const [viewMenu, setViewMenu] = useState<ViewHeaderMenu | null>(null);
1411
  const viewMenuRef = useRef<ViewHeaderMenu | null>(null);
1412
  const [filterState, setFilterState] = useState<SheetFilter | null>(null);
 
1519
  const formulaCaretSizerRef = useRef<HTMLSpanElement | null>(null);
1520
  const formulaCaretPrefixRef = useRef<HTMLSpanElement | null>(null);
1521
  const [formulaBox, setFormulaBox] = useState<{ width: number; height: number } | null>(null);
1522
+ /** S67-T02: how far the grown editor is moved to stay inside the pane (never positive). */
1523
+ const [formulaShift, setFormulaShift] = useState<{ dx: number; dy: number } | null>(null);
1524
  const [formulaCaretOffset, setFormulaCaretOffset] = useState<{ x: number; y: number }>();
1525
  /**
1526
  * ⭐⭐ W54-T21 / INSTRUCTION 18 — THE ONE FLAG THAT STOPS ESCAPE COMMITTING WHAT IT CANCELLED.
 
1582
  (formulaGridWasBand.current ? bandGridRef : gridRef).current?.focus();
1583
  }, [formulaEdit]);
1584
 
1585
+ // S67-T02 / C1: ONE effect keyed on the draft reports every path that changes it, and every
1586
+ // exit (each ends in `setFormulaEdit(null)`) reports `null`. The ref keeps a new callback
1587
+ // identity from re-firing an unchanged draft; the unmount cleanup covers a closed tab.
1588
+ const onDraftChangeRef = useRef(onDraftChange);
1589
+ onDraftChangeRef.current = onDraftChange;
1590
+ const formulaDraft = formulaEdit ? formulaEdit.draft : null;
1591
+ useEffect(() => {
1592
+ onDraftChangeRef.current?.(formulaDraft);
1593
+ }, [formulaDraft]);
1594
+ useEffect(() => () => onDraftChangeRef.current?.(null), []);
1595
+
1596
  const extent = sheetExtent(tab);
1597
  const widths = tab.colWidths ?? {};
1598
 
 
1971
  * format looks like, and the two would drift the first time either was touched. The band grid
1972
  * asks the main one, having said which row it means.
1973
  */
1974
+ // S67-T01: glide's damage repaint wipes a cell from its x+1, y+1 and never repaints the grid-line
1975
+ // pixels, which is where an outline's outer pixel sits, and its blit check skips a redraw whose
1976
+ // `getCellContent` is unchanged. The main grid's content changes when the editor closes; the
1977
+ // frozen-rows band's does not, so an outline leaving the band bumps this, `getFrozenContent`
1978
+ // gets a new identity, and glide redraws the band whole (grid lines included).
1979
+ const [bandRepaint, setBandRepaint] = useState(0);
1980
  const getFrozenContent = useCallback(
1981
  (item: Item): GridCell => getCellContent(fromBand(item)),
1982
+ // `bandRepaint` is read by no line above on purpose: see its declaration.
1983
+ // eslint-disable-next-line react-hooks/exhaustive-deps
1984
+ [fromBand, getCellContent, bandRepaint],
1985
  );
1986
 
1987
  const selected = useMemo(() => {
 
2321
  }
2322
  }, [applyViewAnswer]);
2323
 
2324
+ const commitWithRecalc = useCallback((edits: Record<string, Cell | null>, move?: MovedBlock) => {
2325
  const entries = Object.entries(edits);
2326
  const reserved = entries.some(([addr, value]) => value && isViewReserved(addr));
2327
  if (reserved) { onNotice("Resize or remove this view before editing its reserved cells."); return; }
 
2335
  void commitViewRecord(addr, editableText(cell));
2336
  return;
2337
  }
2338
+ onCommit({ ...edits, ...recalcDependents(tab, edits, workbook.sheets, workbook, calculationSession.current) },
2339
+ move);
2340
  }, [commitViewRecord, isViewReserved, onCommit, onNotice, tab, workbook]);
2341
 
2342
  /** ONE typed commit. `commitTyped` picks literal or formula and drops a binding on its own. */
 
2858
  * edges whose neighbour belongs to a different reference or none. Reference ordinals keep
2859
  * touching ranges separate even when their slot colours repeat; no interior fill is added.
2860
  *
2861
+ * ⭐⭐ QI27 / S67-T01 (2026-09-28) — A FORMULA'S REFERENCES ARE OUTLINED ONLY WHILE IT IS
2862
+ * EDITED. The owner revoked W53-T02 / instruction 18 (outlines on a bare selection): arrowing or
2863
+ * clicking onto a formula cell outlines nothing; F2, a double-click or typing opens the editor,
2864
+ * and only the editor's draft lends its text to this engine. That matches Microsoft's own page
2865
+ * ("double-click the cell ... Excel highlights each cell or range of cells referenced by the
2866
+ * formula with a different color"). References a mounted panel asks about (`externalRefs`,
2867
+ * e.g. Filter's "a cell") still outline with or without an editor (O39). One border map, one
2868
+ * paint path (`paintRefBorder` further down) - there is no second outline mechanism.
2869
  */
2870
  const externalRefs = useHighlightedCellRefs();
2871
  const formulaRefCells = useMemo(() => {
2872
  const out = new Map<string, { color: string; ref: number }>();
2873
+ const source = formulaEdit ? formulaEdit.draft : "";
 
 
2874
  // Hotfix 2026-09-24 (owner: "ANYWHERE in the app ... the cell must be highlighted"): every
2875
  // reference a mounted panel is asking about (`refHighlight.ts`) joins the SAME map, after the
2876
  // formula's own, so it gets the outline and the repaint this map already has. A reference
 
2904
  }
2905
  }
2906
  return out;
2907
+ }, [externalRefs, formulaEdit, tab.name]);
2908
 
2909
  // A reference a person just TYPED is scrolled to, so a cell far off screen (R9997) is seen being
2910
  // outlined rather than outlined out of sight. Opening a panel scrolls nowhere (refHighlight.ts).
 
3013
  const paintedRefCells = useRef<string[]>([]);
3014
  useEffect(() => {
3015
  const now = refPaintKey ? refPaintKey.split("|").map((p) => p.slice(0, p.indexOf(":"))) : [];
3016
+ const leaving = paintedRefCells.current.filter((key) => !now.includes(key));
3017
  const union = new Set([...paintedRefCells.current, ...now]);
3018
  paintedRefCells.current = now;
3019
  if (union.size === 0) return;
 
3031
  }
3032
  if (main.length > 0) gridRef.current?.updateCells(main);
3033
  if (band.length > 0) bandGridRef.current?.updateCells(band);
3034
+ const leftBand = leaving.some((key) => viewRowOf(Number(key.slice(key.indexOf(",") + 1)) - 1) < 0);
3035
+ if (leftBand) setBandRepaint((n) => n + 1);
3036
  }, [bandRows, refPaintKey, viewRowOf, visCols]);
3037
 
3038
  /** The selected rectangle in glide's own VIEW coordinates, or `null` when nothing is selected. */
 
3270
  // ⭐ W53-T01: a fill or a paste can change a cell some OTHER formula reads, so the landing
3271
  // door recalculates its dependents in the same commit every typed edit does.
3272
  if (Object.keys(edits).length > 0) {
3273
+ commitWithRecalc(edits, out.move);
3274
  // C5: schedule only the bound cells that ACTUALLY landed. The page owns save ordering and
3275
  // revisions, so this seam carries identities instead of calling Refresh or a second writer.
3276
  const pending: Record<string, Cell> = {};
 
3449
  onCommit(out.edits);
3450
  }, [onCommit, onNotice, selectedAddrs, tab]);
3451
 
3452
+ /**
3453
+ * ⭐⭐ S67-T11 (QI16, J16, C2) — EXCEL'S DRAW BORDER PENS. Lane B's Borders menu raises
3454
+ * `aios:sheet-border-draw` with `{mode: "draw" | "grid" | "erase", style, color}`; any other
3455
+ * mode (or a null detail) puts the pen down. While a pen is up, the range a drag covers takes
3456
+ * it when the pointer is released: `draw` the range's outline, `grid` every edge of every cell,
3457
+ * `erase` every side drawn along or inside the range, including an outside neighbour's side on
3458
+ * the same line. Sides are written in C2's shape only. Escape puts the pen down (a claim on the
3459
+ * shared arbiter), and with no pen a click selects exactly as before.
3460
+ */
3461
+ const [borderPen, setBorderPen] = useState<BorderPen | null>(null);
3462
+ const borderPenRef = useRef<BorderPen | null>(null);
3463
+ borderPenRef.current = borderPen;
3464
+ // Escape puts the pen down, through the sheet's one Escape arbiter like every other surface.
3465
+ useEscapeClose(borderPen !== null, () => setBorderPen(null));
3466
+ useEffect(() => {
3467
+ const onPen = (event: Event) => {
3468
+ const detail = (event as CustomEvent<Partial<BorderPen> | null>).detail;
3469
+ const mode = detail?.mode;
3470
+ if (mode !== "draw" && mode !== "grid" && mode !== "erase") {
3471
+ setBorderPen(null);
3472
+ return;
3473
+ }
3474
+ const style = String(detail?.style ?? "");
3475
+ const color = String(detail?.color ?? "");
3476
+ setBorderPen({
3477
+ mode,
3478
+ style: BORDER_PEN_STYLES.includes(style) ? style : "thin",
3479
+ color: /^#[0-9a-fA-F]{6}$/.test(color) ? color : "#000000",
3480
+ });
3481
+ // The pen is picked from a menu; the grid takes focus so the drag and Escape reach it.
3482
+ gridRef.current?.focus();
3483
+ };
3484
+ window.addEventListener("aios:sheet-border-draw", onPen);
3485
+ return () => window.removeEventListener("aios:sheet-border-draw", onPen);
3486
+ }, []);
3487
+
3488
+ const applyBorderPen = useCallback((pen: BorderPen) => {
3489
+ const selected = selectionRef.current;
3490
+ // A header press selects whole rows or columns; the pen draws on cells only.
3491
+ if (!selected || selected.columns.length > 0 || selected.rows.length > 0) return;
3492
+ const r = selected.current?.range;
3493
+ if (!r) return;
3494
+ const col0 = r.x, row0 = r.y, col1 = r.x + r.width - 1, row1 = r.y + r.height - 1;
3495
+ const line: BorderPenLine = { style: pen.style, color: pen.color };
3496
+ const borders = new Map<string, Partial<Record<BorderPenSide, unknown>>>();
3497
+ const own = (addr: string) => {
3498
+ if (!borders.has(addr)) borders.set(addr, { ...(cellAt(tab, addr)?.style?.border ?? {}) });
3499
+ return borders.get(addr)!;
3500
+ };
3501
+ const set = (addr: string, side: BorderPenSide, value: BorderPenLine | null) => {
3502
+ const border = own(addr);
3503
+ if (value) border[side] = { ...value };
3504
+ else delete border[side];
3505
+ };
3506
+ for (let row = row0; row <= row1; row += 1) {
3507
+ for (let col = col0; col <= col1; col += 1) {
3508
+ const addr = addrAt(col, row);
3509
+ if (pen.mode === "grid") {
3510
+ for (const side of ["top", "right", "bottom", "left"] as const) set(addr, side, line);
3511
+ } else if (pen.mode === "draw") {
3512
+ if (row === row0) set(addr, "top", line);
3513
+ if (row === row1) set(addr, "bottom", line);
3514
+ if (col === col0) set(addr, "left", line);
3515
+ if (col === col1) set(addr, "right", line);
3516
+ } else {
3517
+ for (const side of ["top", "right", "bottom", "left"] as const) set(addr, side, null);
3518
+ // The same line drawn from outside the range is erased with it, as in Excel.
3519
+ if (row === row0 && row - 1 >= -bandRows) set(addrAt(col, row - 1), "bottom", null);
3520
+ if (row === row1 && row + 1 < visRows.length) set(addrAt(col, row + 1), "top", null);
3521
+ if (col === col0 && col > 0) set(addrAt(col - 1, row), "right", null);
3522
+ if (col === col1 && col + 1 < columns.length) set(addrAt(col + 1, row), "left", null);
3523
+ }
3524
+ }
3525
+ }
3526
+ const edits: Record<string, Cell | null> = {};
3527
+ for (const [addr, border] of borders) {
3528
+ const before = cellAt(tab, addr)?.style?.border ?? {};
3529
+ if (JSON.stringify(before) === JSON.stringify(border)) continue;
3530
+ // C2's side shape is lane B's to type; until its `CellBorder` lands here the cast carries it.
3531
+ Object.assign(edits, styleCells(tab, [addr],
3532
+ { border: border as unknown as CellStylePatch["border"] }).edits);
3533
+ }
3534
+ if (Object.keys(edits).length > 0) onCommit(edits);
3535
+ }, [addrAt, bandRows, columns.length, onCommit, tab, visRows.length]);
3536
+
3537
+ // The pen lands when a drag that began on the cells ends; a drag's last selection is glide's.
3538
+ useEffect(() => {
3539
+ const wrap = wrapRef.current;
3540
+ if (!wrap || !borderPen) return;
3541
+ let down = false;
3542
+ // glide's scroller overlays its canvas, so a press on the cells lands on `.dvn-scroller`.
3543
+ const onDown = (event: PointerEvent) => {
3544
+ down = event.button === 0 && !!(event.target as Element | null)?.closest?.(".dvn-scroller");
3545
+ };
3546
+ const onUp = () => {
3547
+ if (!down) return;
3548
+ down = false;
3549
+ window.setTimeout(() => {
3550
+ const pen = borderPenRef.current;
3551
+ if (pen) applyBorderPen(pen);
3552
+ }, 0);
3553
+ };
3554
+ wrap.addEventListener("pointerdown", onDown, true);
3555
+ window.addEventListener("pointerup", onUp, true);
3556
+ return () => {
3557
+ wrap.removeEventListener("pointerdown", onDown, true);
3558
+ window.removeEventListener("pointerup", onUp, true);
3559
+ };
3560
+ }, [applyBorderPen, borderPen]);
3561
+
3562
  /**
3563
  * ⭐ W51-T15: CLEARING THE SELECTION, SAID ONCE. The Delete key and the ribbon's Clear contents
3564
  * are the SAME act, so the two cannot disagree about R5: a bound cell in the selection clears
 
3932
  return () => host.removeEventListener(KEY_TIP_GRID_ARROW_EVENT, moveFromKeyTips);
3933
  }, [applySelection, bandRows, selection, visRows.length]);
3934
 
3935
+ // S67-T04: the page asks the grid to take focus back (a tab switch closed the Cell Database
3936
+ // panel). glide's own `focus()` focuses the grid AND its current cell; focusing the canvas
3937
+ // element from outside leaves glide's accessibility cell painted in the corner. The name is a
3938
+ // literal on both sides so `SheetPage` never has to import this chunk for it.
3939
+ useEffect(() => {
3940
+ // ⚠ Focused in the same frames as a freshly mounted tab's first paints, glide intermittently
3941
+ // left its row-marker "1" drawn in the header corner (measured 4 px); a short settle before
3942
+ // taking focus does not.
3943
+ let timer = 0;
3944
+ const takeFocus = () => {
3945
+ window.clearTimeout(timer);
3946
+ timer = window.setTimeout(() => {
3947
+ const current = selection?.current?.cell;
3948
+ (current && current[1] < 0 ? bandGridRef : gridRef).current?.focus();
3949
+ }, 180);
3950
+ };
3951
+ document.addEventListener("aios:sheet-focus-grid", takeFocus);
3952
+ return () => {
3953
+ window.clearTimeout(timer);
3954
+ document.removeEventListener("aios:sheet-focus-grid", takeFocus);
3955
+ };
3956
+ }, [selection]);
3957
+
3958
  /**
3959
  * Ctrl+PgUp and Ctrl+PgDn. See `onSelectTab` in the props above for why there are two paths.
3960
  *
 
4828
  setListAsk({ addrs, list: [...(validationOf(cellAt(tab, addrs[0]))?.list ?? [])] });
4829
  }, [onNotice, selectedAddrs, tab]);
4830
 
4831
+ /**
4832
+ * ⭐⭐ S67-T07 (QI19, R31) — THE CELL MENU'S ACTS, EACH ROUTED TO THE DOOR THE RIBBON ALREADY USES:
4833
+ * the clipboard (`copySelection` / `pasteFromClipboard`), structure (`structure` and
4834
+ * `structureForSelection`), `clearSelection`, `applyStyle`, the sheet filter state, the note and
4835
+ * link writers' cell shape, validation and number format. Format Cells... raises contract C3's
4836
+ * `aios:sheet-format-cells`, which lane B's FormatCellsDialog mounts on.
4837
+ * ⚠ Sort A to Z / Z to A are the one local implementation: the Data ribbon's row sort is private
4838
+ * to `ribbonData.tsx`, outside every fence this wave; this is the same stable, blanks-last,
4839
+ * numbers-before-text order, committed as one step (COMBINE note in S67-T07's record).
4840
+ */
4841
+ const onCellMenuAct = useCallback((act: CellMenuAct) => {
4842
+ const range = viewRange();
4843
+ const col0 = range ? realCol(Math.min(range.col0, range.col1)) : 0;
4844
+ const col1 = range ? realCol(Math.max(range.col0, range.col1)) : 0;
4845
+ const row0 = range ? realRow(Math.min(range.row0, range.row1)) : 0;
4846
+ const row1 = range ? realRow(Math.max(range.row0, range.row1)) : 0;
4847
+ const style = anchorStyle;
4848
+ const anchorAddr = addressOf(col0, row0);
4849
+ const sortRowsBy = (direction: 1 | -1) => {
4850
+ if (!range || row1 <= row0) {
4851
+ onNotice("Select two or more rows to sort.");
4852
+ return;
4853
+ }
4854
+ const keyOf = (cell: Cell | null | undefined): [number, number | string] => {
4855
+ const v = cell ? cellToValue(cell) : null;
4856
+ if (!v || v.kind === "empty" || !("value" in v) || v.value === "") return [2, ""];
4857
+ if (v.kind === "number") return [0, v.value];
4858
+ return [1, String(v.value)];
4859
+ };
4860
+ const rows = [];
4861
+ for (let r = row0; r <= row1; r += 1) {
4862
+ const cellsOfRow = [];
4863
+ for (let c = col0; c <= col1; c += 1) cellsOfRow.push(cellAt(tab, addressOf(c, r)));
4864
+ rows.push({ cellsOfRow, index: r - row0, key: keyOf(cellsOfRow[0]) });
4865
+ }
4866
+ rows.sort((a, b) => {
4867
+ if (a.key[0] !== b.key[0]) return a.key[0] - b.key[0];
4868
+ if (a.key[0] === 2) return a.index - b.index;
4869
+ const cmp = a.key[0] === 0 ? (a.key[1] as number) - (b.key[1] as number)
4870
+ : String(a.key[1]).localeCompare(String(b.key[1]), undefined, { numeric: true });
4871
+ return cmp * direction || a.index - b.index;
4872
+ });
4873
+ const edits: Record<string, Cell | null> = {};
4874
+ rows.forEach((row, i) => row.cellsOfRow.forEach((cell, j) => {
4875
+ edits[addressOf(col0 + j, row0 + i)] = cell ?? null;
4876
+ }));
4877
+ commitWithRecalc(edits);
4878
+ };
4879
+ switch (act) {
4880
+ case "cut": copySelection(true); return;
4881
+ case "copy": copySelection(false); return;
4882
+ case "paste": pasteFromClipboard("normal"); return;
4883
+ // Excel's Formulas: formulas and values without the source's formatting. The payload
4884
+ // carries formulas already; the normal door is the nearest one this app has.
4885
+ case "paste-formulas": pasteFromClipboard("normal"); return;
4886
+ case "paste-values": pasteFromClipboard("values"); return;
4887
+ case "paste-formatting": pasteFromClipboard("formatting"); return;
4888
+ case "paste-special": return;
4889
+ case "insert-down": structureForSelection(true); return;
4890
+ case "delete-up": structureForSelection(false); return;
4891
+ case "insert-right": case "delete-left": return;
4892
+ case "insert-row": structure("row", row1 - row0 + 1, row0 + 1); return;
4893
+ case "insert-col": structure("col", col1 - col0 + 1, col0 + 1); return;
4894
+ case "delete-row": structure("row", -(row1 - row0 + 1), row0 + 1); return;
4895
+ case "delete-col": structure("col", -(col1 - col0 + 1), col0 + 1); return;
4896
+ case "clear-contents": clearSelection(); return;
4897
+ case "filter-reapply": setFilterState((was) => (was ? { ...was } : was)); return;
4898
+ case "filter-clear": setFilterState((was) => (was ? { ...was, values: {} } : was)); return;
4899
+ case "filter-value": {
4900
+ if (!range) return;
4901
+ const value = sheetFilterValue(cellAt(tab, anchorAddr));
4902
+ if (sheetFilter && col0 >= sheetFilter.col0 && col0 <= sheetFilter.col1
4903
+ && row0 > sheetFilter.headerRow) {
4904
+ setFilterState((was) => (was ? { ...was, values: { ...was.values, [col0]: new Set([value]) } } : was));
4905
+ return;
4906
+ }
4907
+ // The current region's top row is its header, as Excel reads it.
4908
+ let header = row0;
4909
+ while (header > 0 && isFilled(tab, col0, header - 1)) header -= 1;
4910
+ const region = header < row0
4911
+ ? sheetFilterRegion(tab, { col0, col1: col0, row0: header, row1: header })
4912
+ : null;
4913
+ if (!region) {
4914
+ onNotice("This cell has no header above it to filter under.");
4915
+ return;
4916
+ }
4917
+ setFilterState({ ...region, scope: renderedWorkbookKey, values: { [col0]: new Set([value]) } });
4918
+ return;
4919
+ }
4920
+ case "sort-asc": sortRowsBy(1); return;
4921
+ case "sort-desc": sortRowsBy(-1); return;
4922
+ case "new-comment": case "new-note":
4923
+ setNoteAsk({ addr: anchorAddr, text: cellAt(tab, anchorAddr)?.note ?? "" });
4924
+ return;
4925
+ case "format-cells":
4926
+ window.dispatchEvent(new CustomEvent("aios:sheet-format-cells", { detail: { tab: "number" } }));
4927
+ return;
4928
+ case "pick-list": openValidation(); return;
4929
+ case "link": setLinkAsk(anchorAddr); return;
4930
+ case "bold": applyStyle({ bold: style?.bold ? null : true }); return;
4931
+ case "italic": applyStyle({ italic: style?.italic ? null : true }); return;
4932
+ case "center": applyStyle({ align: style?.align === "center" ? null : "center" }); return;
4933
+ case "accounting": onNotice(NOT_YET_FORMAT_CODE); return;
4934
+ case "percent": applyStyle({ format: { kind: "percent", decimals: 0 } }); return;
4935
+ case "comma": applyStyle({ format: { kind: "number", decimals: 2, thousands: true } }); return;
4936
+ case "decimal-more": case "decimal-less": {
4937
+ const held = style?.format;
4938
+ const was = held && !held.code
4939
+ ? held : { kind: "number" as const, decimals: 0 };
4940
+ const decimals = Math.max(0, Math.min(10, (was.decimals ?? 0) + (act === "decimal-more" ? 1 : -1)));
4941
+ applyStyle({ format: { ...was, decimals } });
4942
+ return;
4943
+ }
4944
+ case "grow-font": case "shrink-font": {
4945
+ const now = fontPt(style?.size ?? null);
4946
+ const ladder = [...FONT_SIZE_LADDER];
4947
+ const next = act === "grow-font"
4948
+ ? ladder.find((pt) => pt > now) ?? ladder[ladder.length - 1]
4949
+ : [...ladder].reverse().find((pt) => pt < now) ?? ladder[0];
4950
+ applyStyle({ size: next });
4951
+ return;
4952
+ }
4953
+ case "format-painter": toggleFormatPainter(); return;
4954
+ // Excel's mini toolbar buttons apply their last colour; the first use is Excel's default.
4955
+ case "fill": applyStyle({ fill: "#FFFF00" }); return;
4956
+ case "font-color": applyStyle({ color: "#FF0000" }); return;
4957
+ case "borders": applyStyle({ border: { ...(style?.border ?? {}), bottom: true } }); return;
4958
+ case "merge-center": return;
4959
+ }
4960
+ }, [anchorStyle, applyStyle, clearSelection, commitWithRecalc, copySelection, onNotice,
4961
+ openValidation, pasteFromClipboard, realCol, realRow, renderedWorkbookKey, sheetFilter,
4962
+ structure, structureForSelection, tab, toggleFormatPainter, viewRange]);
4963
+
4964
  /**
4965
  * Write the list onto every selected cell, as ONE commit.
4966
  *
 
5268
  // to the reader's key for this event only; a later data-identity reconciliation has no key.
5269
  keyboardSelectingRef.current = true;
5270
  queueMicrotask(() => { keyboardSelectingRef.current = false; });
5271
+ // S67-T07: Shift+F10 and the Menu key open Excel's cell menu at the current cell.
5272
+ if ((event.shiftKey && event.key === "F10") || event.key === "ContextMenu") {
5273
+ const item = selectionRef.current?.current?.cell;
5274
+ const bounds = item && (item[1] < 0 ? bandGridRef : gridRef).current
5275
+ ?.getBounds(item[0], item[1] < 0 ? item[1] + bandRows : item[1]);
5276
+ if (item && bounds) {
5277
+ event.cancel();
5278
+ event.preventDefault();
5279
+ setAnchor(null);
5280
+ setMenu({
5281
+ anchor: rectAnchor(bounds),
5282
+ col: realCol(item[0]) + 1,
5283
+ row: realRow(item[1] < 0 ? item[1] : item[1]) + 1,
5284
+ on: "cell",
5285
+ });
5286
+ return;
5287
+ }
5288
+ }
5289
  // A canvas button also has a keyboard door, without another key listener.
5290
  if (event.altKey && !event.ctrlKey && !event.metaKey && event.key === "ArrowDown") {
5291
  const item = selectionRef.current?.current?.cell;
 
5871
  useLayoutEffect(() => {
5872
  if (!formulaEdit) {
5873
  setFormulaBox(null);
5874
+ setFormulaShift(null);
5875
  setFormulaCaretOffset(undefined);
5876
  return;
5877
  }
 
5884
  const boundsRef = formulaEdit.inBand ? bandGridRef : gridRef;
5885
  const bounds = boundsRef.current?.getBounds(formulaEdit.viewCell[0], formulaEdit.viewCell[1]);
5886
  if (!bounds) return;
5887
+ // S67-T02: the draft grows right from the cell over its neighbours (and across the frozen
5888
+ // divider) to the pane edge, then wraps. A cell too close to that edge would leave a box
5889
+ // one cell wide, so the box widens LEFT to a readable width instead, its right edge on the
5890
+ // pane edge the way Excel grows a right-aligned cell. It never leaves the pane.
5891
+ const pane = canvas?.getBoundingClientRect();
5892
+ const paneLeft = Math.max(0, pane?.left ?? 0);
5893
+ const paneTop = Math.max(0, pane?.top ?? 0);
5894
+ const paneBottom = Math.min(window.innerHeight - FORMULA_MODE_RESERVE,
5895
+ pane?.bottom ?? window.innerHeight);
5896
+ const roomRight = Math.max(bounds.width,
5897
  (canvas?.getBoundingClientRect().right ?? window.innerWidth) - bounds.x - 4);
5898
+ sizer.style.maxWidth = "none";
5899
+ const natural = Math.ceil(sizer.offsetWidth);
5900
+ const readable = Math.max(bounds.width,
5901
+ Math.min(FORMULA_EDITOR_READABLE_WIDTH, (pane?.width ?? window.innerWidth) - 8));
5902
+ const maxWidth = roomRight >= Math.min(natural, readable) ? roomRight : Math.min(natural, readable);
5903
  sizer.style.maxWidth = `${maxWidth}px`;
5904
  const width = Math.max(bounds.width, Math.ceil(sizer.offsetWidth));
5905
  const height = Math.max(bounds.height, Math.ceil(sizer.offsetHeight));
5906
  setFormulaBox({ width, height });
5907
+ // Wrapped lines grow down; past the pane bottom the box moves up so the last line stays
5908
+ // on screen rather than falling off the bottom edge. The Enter/Point label under the box
5909
+ // may hang past the pane, never past the window.
5910
+ const roomBelow = paneBottom - 4 - bounds.y;
5911
+ const dx = Math.min(0, Math.max(paneLeft + 4 - bounds.x, roomRight - width));
5912
+ const dy = height <= roomBelow ? 0 : Math.min(0, Math.max(paneTop + 4 - bounds.y, roomBelow - height));
5913
+ setFormulaShift((prev) => (prev && prev.dx === dx && prev.dy === dy ? prev : { dx, dy }));
5914
 
5915
  // The prefix ends at the caret, but the suffix stays in the same inline flow: dropping
5916
  // it would measure a different wrap when the caret sits in the middle of a word.
 
6124
  const currentRect = { ...borderRect,
6125
  x: borderRect.x + (col < frozenCols ? 0 : latest.x - originX),
6126
  y: borderRect.y + latest.y - originY };
6127
+ // S67-T05 / D-3280: the frozen side stops AT the divider too, so neither pane's late
6128
+ // paint ever owns the divider's pixel column and every scroll path shows glide's line.
6129
+ const paneRight = col < frozenCols ? columnX(frozenCols)
6130
  : ctx.canvas.width / latest.transform.a;
6131
  const paneBottom = ctx.canvas.height / latest.transform.d;
6132
  if (currentRect.x + currentRect.width < paneLeft || currentRect.x >= paneRight
 
6365
  // UNSCALED space: at any browser zoom but 100% the run landed shrunk and offset, a ghost of
6366
  // the label. The border paint above already carries the transform; this run now does too.
6367
  const spillTransform = ctx.getTransform();
6368
+ // S67-T05 (QI8, ERROR 27): the run is painted a FRAME LATER, and a wheel scroll in that
6369
+ // frame moves the canvas under it; painted at the draw-time x it landed over the frozen
6370
+ // columns and stayed there. It now follows the viewport glide last drew at, exactly like the
6371
+ // border repair above, and clips to its owner's pane, so a label spilling left out of the
6372
+ // scrolling pane stops at the freeze divider instead of writing over A:E.
6373
+ const spillOriginX = viewport.x;
6374
+ const spillOriginY = viewport.y;
6375
+ const ownerFrozen = ownerCol < frozenCols;
6376
+ const spillPaneLeft = ownerFrozen ? ROW_MARKER_WIDTH
6377
+ : columnX(frozenCols) + (frozenCols > 0 ? 1 : 0);
6378
  // Glide paints gridlines after drawCell. Deduplicate every participating cell into one
6379
  // owner run, then mask only its interior separators and redraw the text in the next frame.
6380
  queueSpillPaint(`${row}:${ownerCol}`, () => {
6381
+ const latest = borderPaintViewports.current.get(ctx);
6382
+ const dx = latest && !ownerFrozen ? latest.x - spillOriginX : 0;
6383
+ const dy = latest ? latest.y - spillOriginY : 0;
6384
+ const transform = latest?.transform ?? spillTransform;
6385
+ const spillPaneRight = ownerFrozen ? columnX(frozenCols)
6386
+ : ctx.canvas.width / transform.a;
6387
+ const left = Math.max(runLeft + dx + 1, spillPaneLeft);
6388
+ const right = Math.min(runRight + dx - 1, spillPaneRight);
6389
+ if (right <= left) return;
6390
  ctx.save();
6391
+ ctx.setTransform(transform);
6392
+ // The scroll since the draw, applied once; the clip is the pane-bounded run.
6393
+ ctx.translate(dx, dy);
6394
  ctx.beginPath();
6395
+ ctx.rect(left - dx, rowTop + 1, right - left, rowHeight - 2);
6396
  ctx.clip();
6397
  ctx.fillStyle = cellFillColor;
6398
  let separatorX = runLeft;
 
7374
  </div>
7375
  </AnchoredOverlay>
7376
  )}
7377
+ {/* ⭐⭐ S67-T07 (QI19, R31) — A CELL gets Excel desktop's cell menu and mini toolbar; the
7378
+ row and column headers keep the header menu below (S67-T08 turns those into Excel's). */}
7379
+ {menu && menu.on === "cell" && (
7380
+ <CellContextMenu
7381
  anchor={menu.anchor}
7382
+ readOnly={readOnly}
7383
+ clipboardEmpty={copiedRef.current === null}
7384
+ filterActive={sheetFilter !== null}
7385
+ fontName={anchorStyle?.font ?? DEFAULT_CELL_FONT}
7386
+ fontSize={fontPt(anchorStyle?.size ?? null)}
7387
+ fonts={CELL_FONTS}
7388
+ onFont={(font) => applyStyle({ font: font === DEFAULT_CELL_FONT ? null : font })}
7389
+ onSize={(size) => applyStyle({ size })}
7390
+ onAct={onCellMenuAct}
7391
+ onClose={() => setMenu(null)}
7392
+ />
7393
+ )}
7394
+ {noteAsk && (
7395
+ <AnchoredOverlay
7396
+ anchor={menu?.anchor ?? wrapRef.current}
7397
+ className="cg-pop sheet-cell-menu-pop"
7398
  placement="bottom-start"
7399
+ role="dialog"
7400
+ ariaLabel="New Note"
7401
+ onDismiss={() => setNoteAsk(null)}
7402
  >
7403
+ <div className="sheet-cell-menu-ask">
7404
+ <div className="sheet-cell-menu-ask-title">{`Note on ${noteAsk.addr}`}</div>
7405
+ <textarea
7406
+ className="sheet-cell-note-input" rows={4} value={noteAsk.text} autoFocus
7407
+ aria-label={`Note on ${noteAsk.addr}`}
7408
+ onChange={(e) => { const text = e.currentTarget.value; setNoteAsk((was) => (was ? { ...was, text } : was)); }}
7409
+ />
7410
+ <div className="sheet-cell-menu-ask-actions">
7411
+ <button type="button" className="sheet-cell-menu-ask-ok" onClick={() => {
7412
+ // The ribbon's note writer's own shape: amend the anchor cell, never replace it.
7413
+ const held = cellAt(tab, noteAsk.addr);
7414
+ const text = noteAsk.text.trim();
7415
+ const next: Cell = held
7416
+ ? { ...held, note: text || undefined }
7417
+ : { kind: "empty", state: "typed", note: text };
7418
+ onCommit({ [noteAsk.addr]: next });
7419
+ setNoteAsk(null);
7420
+ }}>Save</button>
7421
+ <button type="button" className="sheet-cell-menu-ask-cancel" onClick={() => setNoteAsk(null)}>
7422
+ Cancel
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7423
  </button>
7424
+ </div>
7425
  </div>
7426
  </AnchoredOverlay>
7427
  )}
7428
+ {linkAsk && (
7429
+ <LinkDialog
7430
+ anchor={wrapRef.current}
7431
+ held={cellAt(tab, linkAsk)?.link as CellLink | undefined}
7432
+ onClose={() => setLinkAsk(null)}
7433
+ onSubmit={(link: CellLink) => {
7434
+ // The ribbon's link writer's own shape: amend the anchor cell's `link` only.
7435
+ const held = cellAt(tab, linkAsk);
7436
+ onCommit({ [linkAsk]: held ? { ...held, link } : { kind: "empty", state: "typed", link } });
7437
+ setLinkAsk(null);
7438
+ }}
7439
+ />
7440
+ )}
7441
+ {/* ⭐⭐ S67-T08 (QI19, R31) — ROW AND COLUMN HEADERS GET EXCEL'S ROW AND COLUMN MENUS, the
7442
+ same component as the cell menu in its header shape; the frozen band's headers report
7443
+ into the same `menu` state and so get the same menus. Insert and Delete act on the
7444
+ header that was right clicked, as the header menu always did. */}
7445
+ {menu && menu.on !== "cell" && (
7446
+ <CellContextMenu
7447
+ anchor={menu.anchor}
7448
+ kind={menu.on === "column" ? "column" : "row"}
7449
+ canGroup={Boolean(onRowGroups)}
7450
+ canUngroup={Boolean(onRowGroups) && rowGroups.length > 0}
7451
+ readOnly={readOnly}
7452
+ clipboardEmpty={copiedRef.current === null}
7453
+ filterActive={sheetFilter !== null}
7454
+ fontName={anchorStyle?.font ?? DEFAULT_CELL_FONT}
7455
+ fontSize={fontPt(anchorStyle?.size ?? null)}
7456
+ fonts={CELL_FONTS}
7457
+ onFont={(font) => applyStyle({ font: font === DEFAULT_CELL_FONT ? null : font })}
7458
+ onSize={(size) => applyStyle({ size })}
7459
+ onAct={(act) => {
7460
+ const m = menu;
7461
+ switch (act) {
7462
+ case "insert-row": structure("row", 1, m.row); return;
7463
+ case "delete-row": structure("row", -1, m.row); return;
7464
+ case "insert-col": structure("col", 1, m.col); return;
7465
+ case "delete-col": structure("col", -1, m.col); return;
7466
+ case "row-height": setAsk({ kind: "row-height", value: rowHeight }); return;
7467
+ case "col-width": setAsk({ kind: "column-width", value: COL_WIDTH }); return;
7468
+ case "hide-rows": hideBand("row"); return;
7469
+ case "hide-cols": hideBand("col"); return;
7470
+ case "unhide": unhideAll(); return;
7471
+ case "group-rows": groupRows(); return;
7472
+ case "ungroup-rows": ungroupRows(); return;
7473
+ default: onCellMenuAct(act);
7474
+ }
7475
+ }}
7476
+ onClose={() => setMenu(null)}
7477
+ />
7478
+ )}
7479
 
7480
  {/* ⭐⭐ THE ROW HEIGHT AND COLUMN WIDTH ASK, RENDERED INSIDE THE SHEET'S OWN CONTENT BOX
7481
  RATHER THAN PORTALLED. A portal drops every descendant-scoped rule it was styled by, and
 
7788
  className="sheet-formula-editor"
7789
  style={{ left: bounds.x, top: bounds.y,
7790
  width: formulaBox?.width ?? bounds.width, height: formulaBox?.height ?? bounds.height,
7791
+ lineHeight: `${Math.max(1, bounds.height - 2)}px`,
7792
+ // S67-T02: the cell stays the layout origin; this only pulls a box that would cross
7793
+ // the pane's right or bottom edge back inside it (see the measure effect).
7794
+ transform: formulaShift && (formulaShift.dx || formulaShift.dy)
7795
+ ? `translate(${formulaShift.dx}px, ${formulaShift.dy}px)` : undefined }}
7796
  >
7797
  <div className="sheet-formula-editor-input-wrap">
7798
  {/* CR-1/CR-5: the coloured backdrop, mounted only once a reference exists (a plain
web/src/sheet/SheetPage.tsx CHANGED
@@ -89,9 +89,10 @@ import {
89
  addTab, applyStructureWorkbook, bandBoundLabel, boundCellsInBand, cellAt,
90
  drillAffordance, emptyHistory, growSheet, moveTab, pushHistory, redoHistory, removeTab,
91
  removeTabRefusal, renameTab, renameTabRefusal, setColumnWidth, setFreeze, setTabView,
92
- setTabVisibility, splitAddress, structureRefusal, tabCellCount, undoHistory, withCells, withRowGroupsTab,
 
93
  } from "./sheetState";
94
- import type { SheetHistory, StructureOp } from "./sheetState";
95
  import { bindingDisplay, emptyIndex, ROOT_FOLDER_ID, sheetExtent, withBindingDisplay } from "./types";
96
  import type { BindingDisplay, Cell, IndexRepair, SheetChartSpec, SheetPrintSettings, SheetRule, SheetRowGroup, SheetTab, SheetTabView, Workbook } from "./types";
97
  import { ChartWorkbookContext } from "./ChartDialog";
@@ -464,6 +465,9 @@ export default function SheetPage() {
464
  * makes the bar reachable from the keyboard alone. NOTHING IN `FormulaBar.tsx` CHANGED.
465
  */
466
  const [barAddr, setBarAddr] = useState("A1");
 
 
 
467
  /** R18 / R20: a delete that would drop a bound cell asks first. Null when nothing is pending. */
468
  const [bandAt, setBandAt] = useState<{
469
  op: StructureOp; message: string; workbookId: string; tabId: string;
@@ -747,6 +751,56 @@ export default function SheetPage() {
747
 
748
  useEffect(() => { tabIdRef.current = tabId; }, [tabId]);
749
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
750
  const markDirty = useCallback((tabId2: string, addr: string) => {
751
  const held = dirtyRef.current.get(tabId2) ?? new Set<string>();
752
  held.add(addr);
@@ -778,6 +832,10 @@ export default function SheetPage() {
778
  const mergeTab = useCallback((workbookId: string, next: SheetTab) => {
779
  const live = bookRef.current;
780
  if (!live || live.id !== workbookId) return;
 
 
 
 
781
  tabLoadedRef.current.add(tabKeyOf(workbookId, next.id));
782
  if (tabHoldsCells(next)) historyRef.current = emptyHistory();
783
  editSeqRef.current += 1;
@@ -1181,6 +1239,7 @@ export default function SheetPage() {
1181
  // described; a typed value now commits directly, through `SheetGrid.tsx::onKeyDown`.
1182
  const onEdit = useCallback((addr: string, _cell: Cell | null) => {
1183
  setNotice("");
 
1184
  setEditAt(addr);
1185
  }, []);
1186
 
@@ -1188,6 +1247,7 @@ export default function SheetPage() {
1188
  const openCellData = () => {
1189
  if (!barAddr) return;
1190
  setNotice("");
 
1191
  setEditAt(barAddr);
1192
  };
1193
  document.addEventListener(OPEN_CELL_DATA_EVENT, openCellData);
@@ -1591,13 +1651,42 @@ export default function SheetPage() {
1591
  * through `sheetState.ts::withCells` and queues ONE save, which is what makes an undo of a
1592
  * paste undo the whole paste rather than its last cell.
1593
  */
1594
- const commitCells = useCallback((edits: Record<string, Cell | null>) => {
 
 
1595
  const base = bookRef.current;
1596
  if (!base || Object.keys(edits).length === 0) return;
1597
  const target = base.sheets.find((t) => t.id === tabIdRef.current)?.id
1598
  ?? base.sheets[0]?.id ?? "";
1599
  if (!target) return;
 
 
 
 
 
 
 
 
 
 
1600
  historyRef.current = pushHistory(historyRef.current, base.sheets, { namedRanges: base.namedRanges });
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1601
  editSeqRef.current += 1;
1602
  setNotice("");
1603
  // ⭐⭐ W51-T11 / R4 — THE DIRTY SET, AND `edits` IS ALREADY EXACTLY IT. The changed addresses
@@ -1607,7 +1696,8 @@ export default function SheetPage() {
1607
  for (const addr of Object.keys(edits)) markDirty(target, addr);
1608
  applyLocal(withCells(base, target, edits));
1609
  queueSave();
1610
- }, [applyLocal, markDirty, queueSave]);
 
1611
 
1612
  // ═══════════════════════════════════════════════════════════════════════════════════════════
1613
  // ⭐⭐ W50-T20 — STRUCTURE, THROUGH THE SAME DOOR AS A KEYSTROKE.
@@ -2181,6 +2271,11 @@ export default function SheetPage() {
2181
  const onSaveBinding = useCallback((binding: Record<string, unknown>) => {
2182
  const addr = editAt;
2183
  if (!addr) return;
 
 
 
 
 
2184
  setEditAt("");
2185
  void saveBindingAt(addr, binding);
2186
  }, [editAt, saveBindingAt]);
@@ -2239,6 +2334,7 @@ export default function SheetPage() {
2239
  // ⭐ W54-T34: the busy state goes on in the SAME act as the open, so the control changes in the
2240
  // same frame the surface appears. `DrillModal` takes it off again through `onSettled`.
2241
  setDrillLoading(true);
 
2242
  setDrillAt(addr);
2243
  }, []);
2244
 
@@ -3025,6 +3121,10 @@ export default function SheetPage() {
3025
  // `onCommit={commitCells}`, with no self-closing tag in between, or `verify_wiring`'s
3026
  // W50-T17 row reds a ticket this does not own.
3027
  onRules={onRules}
 
 
 
 
3028
  onHideBands={onHideBands}
3029
  onRowGroups={canEditOutline ? onRowGroups : undefined}
3030
  // ⭐⭐ W51-T08 / CONTRACT C1 — THE FOUR SEAM PROPS THE RIBBON IS FED THROUGH.
@@ -3043,6 +3143,7 @@ export default function SheetPage() {
3043
  disabled={busy}
3044
  onAddrChange={setBarAddr}
3045
  onCommit={commitCells}
 
3046
  />}
3047
  onSaveNow={onSaveNow}
3048
  onOpenImport={onOpenImport}
@@ -3273,7 +3374,7 @@ export default function SheetPage() {
3273
  </div>
3274
  )}
3275
 
3276
- {book && editAt && (
3277
  /*
3278
  * ⛔⛔ `key={editAt}` REMOUNTS THE PANEL, AND WITHOUT IT THE SECOND CELL SHOWS THE FIRST
3279
  * CELL'S PERIOD. `BindingEditor` seeds its period, lock and drag state from `initial`
@@ -3316,7 +3417,7 @@ export default function SheetPage() {
3316
  selection; removing the dialog outright removes the only surface that could ever steal
3317
  that focus. */}
3318
 
3319
- {book && drillAt && (
3320
  <DrillModal
3321
  workbookId={book.id}
3322
  addr={drillAt}
 
89
  addTab, applyStructureWorkbook, bandBoundLabel, boundCellsInBand, cellAt,
90
  drillAffordance, emptyHistory, growSheet, moveTab, pushHistory, redoHistory, removeTab,
91
  removeTabRefusal, renameTab, renameTabRefusal, setColumnWidth, setFreeze, setTabView,
92
+ reanchorWorkbookForMove, setTabVisibility, splitAddress, structureRefusal, tabCellCount, undoHistory,
93
+ withCells, withRowGroupsTab,
94
  } from "./sheetState";
95
+ import type { MovedBlock, SheetHistory, StructureOp } from "./sheetState";
96
  import { bindingDisplay, emptyIndex, ROOT_FOLDER_ID, sheetExtent, withBindingDisplay } from "./types";
97
  import type { BindingDisplay, Cell, IndexRepair, SheetChartSpec, SheetPrintSettings, SheetRule, SheetRowGroup, SheetTab, SheetTabView, Workbook } from "./types";
98
  import { ChartWorkbookContext } from "./ChartDialog";
 
465
  * makes the bar reachable from the keyboard alone. NOTHING IN `FormulaBar.tsx` CHANGED.
466
  */
467
  const [barAddr, setBarAddr] = useState("A1");
468
+ // S67-T03 / C1: the in-cell editor's live draft, from `SheetGrid`'s `onDraftChange`, which the
469
+ // formula bar shows while it is a string. null whenever no cell editor is open.
470
+ const [cellDraft, setCellDraft] = useState<string | null>(null);
471
  /** R18 / R20: a delete that would drop a bound cell asks first. Null when nothing is pending. */
472
  const [bandAt, setBandAt] = useState<{
473
  op: StructureOp; message: string; workbookId: string; tabId: string;
 
751
 
752
  useEffect(() => { tabIdRef.current = tabId; }, [tabId]);
753
 
754
+ // ⭐⭐ S67-T04 (QI7, 2026-09-28) — THE CELL DATABASE PANEL AND THE VIEW DATA WINDOW BELONG TO
755
+ // THE TAB THEY WERE OPENED ON. Both are keyed by an ADDRESS only, so left open across a tab
756
+ // switch they read the NEW tab's cell at that address, and Save wrote the binding onto the
757
+ // other tab (`saveBindingAt` targets the open tab). Whatever moves the page to another tab (the
758
+ // tab bar, Ctrl+PageDown, an address, a chart's destination, a deleted tab) closes both, and
759
+ // unsaved panel edits are discarded exactly like Cancel (O13). Focus goes back to the grid.
760
+ const panelTabRef = useRef("");
761
+ const refocusGridRef = useRef(false);
762
+ useEffect(() => {
763
+ if (!editAt && !drillAt) return;
764
+ if (!panelTabRef.current || panelTabRef.current === tabId) return;
765
+ // ⛔ The ref is NOT cleared here: a render can land between this effect and the state update
766
+ // below, and with the ref empty the mount guards would let the stale address render against
767
+ // the NEW tab for that one render (measured: one `/drill?tab=<new tab>` request). The ref only
768
+ // moves when a panel opens, and every door sets it.
769
+ refocusGridRef.current = true;
770
+ setEditAt("");
771
+ setDrillAt("");
772
+ setDrillLoading(false);
773
+ }, [drillAt, editAt, tabId]);
774
+ // Focus returns once the new tab's grid exists: a tab not loaded yet has none until its cells
775
+ // arrive (which a busy store can stretch past half a minute), so this keys on the pending load
776
+ // rather than on a clock, then waits a few frames for the grid's canvas to exist before asking
777
+ // the grid to focus itself. Focus the person has already moved anywhere but the page body or
778
+ // the Sheets tab strip is left where it is.
779
+ useEffect(() => {
780
+ if (!refocusGridRef.current || pendingTab) return;
781
+ const deadline = performance.now() + 3000;
782
+ let frame = 0;
783
+ const refocus = () => {
784
+ const now = document.activeElement;
785
+ if (now && now !== document.body && !now.closest('[aria-label="Sheets"]')) {
786
+ refocusGridRef.current = false;
787
+ return;
788
+ }
789
+ const canvases = [...document.querySelectorAll<HTMLElement>(
790
+ '.sheet-grid-canvas canvas[data-testid="data-grid-canvas"]')];
791
+ const main = canvases.find((c) => !c.closest(".sheet-frozen-rows")) ?? canvases[0];
792
+ if (main) {
793
+ refocusGridRef.current = false;
794
+ // SheetGrid focuses itself through glide (the literal is its listener's name too).
795
+ document.dispatchEvent(new CustomEvent("aios:sheet-focus-grid"));
796
+ } else if (performance.now() < deadline) {
797
+ frame = window.requestAnimationFrame(refocus);
798
+ }
799
+ };
800
+ frame = window.requestAnimationFrame(refocus);
801
+ return () => window.cancelAnimationFrame(frame);
802
+ }, [pendingTab, tabId]);
803
+
804
  const markDirty = useCallback((tabId2: string, addr: string) => {
805
  const held = dirtyRef.current.get(tabId2) ?? new Set<string>();
806
  held.add(addr);
 
832
  const mergeTab = useCallback((workbookId: string, next: SheetTab) => {
833
  const live = bookRef.current;
834
  if (!live || live.id !== workbookId) return;
835
+ // S67-T09: two `ensureTabs` calls can both see a tab unloaded and both read it. The read that
836
+ // lands SECOND must not overwrite the first one's tab, or it wipes whatever was written onto
837
+ // that tab in between (a moved block's re-anchored references) and empties the undo history.
838
+ if (tabLoadedRef.current.has(tabKeyOf(workbookId, next.id))) return;
839
  tabLoadedRef.current.add(tabKeyOf(workbookId, next.id));
840
  if (tabHoldsCells(next)) historyRef.current = emptyHistory();
841
  editSeqRef.current += 1;
 
1239
  // described; a typed value now commits directly, through `SheetGrid.tsx::onKeyDown`.
1240
  const onEdit = useCallback((addr: string, _cell: Cell | null) => {
1241
  setNotice("");
1242
+ panelTabRef.current = tabIdRef.current;
1243
  setEditAt(addr);
1244
  }, []);
1245
 
 
1247
  const openCellData = () => {
1248
  if (!barAddr) return;
1249
  setNotice("");
1250
+ panelTabRef.current = tabIdRef.current;
1251
  setEditAt(barAddr);
1252
  };
1253
  document.addEventListener(OPEN_CELL_DATA_EVENT, openCellData);
 
1651
  * through `sheetState.ts::withCells` and queues ONE save, which is what makes an undo of a
1652
  * paste undo the whole paste rather than its last cell.
1653
  */
1654
+ const commitCellsRef = useRef<(edits: Record<string, Cell | null>, move?: MovedBlock) => void>(
1655
+ () => undefined);
1656
+ const commitCells = useCallback((edits: Record<string, Cell | null>, move?: MovedBlock) => {
1657
  const base = bookRef.current;
1658
  if (!base || Object.keys(edits).length === 0) return;
1659
  const target = base.sheets.find((t) => t.id === tabIdRef.current)?.id
1660
  ?? base.sheets[0]?.id ?? "";
1661
  if (!target) return;
1662
+ // S67-T09: re-anchoring reads every tab (the rule `structureBase` keeps for structure), and a
1663
+ // tab never opened has no cells here yet. Load them all, then land the move in ONE step; if
1664
+ // they cannot load, the move still lands and says nothing it cannot back up.
1665
+ if (move) {
1666
+ const all = base.sheets.map((t) => t.id);
1667
+ if (all.some((id) => !tabLoadedRef.current.has(tabKeyOf(base.id, id)))) {
1668
+ void ensureTabs(base.id, all).then((ok) => commitCellsRef.current(edits, ok ? move : undefined));
1669
+ return;
1670
+ }
1671
+ }
1672
  historyRef.current = pushHistory(historyRef.current, base.sheets, { namedRanges: base.namedRanges });
1673
+ // ⭐⭐ S67-T09 (QI5, D-3285) — A MOVED BLOCK TAKES ITS REFERENCES ALONG, ON EVERY TAB, IN THIS
1674
+ // SAME HISTORY STEP, so one Undo puts the block AND every reference back. References live on
1675
+ // other tabs and in the workbook's named ranges, which a cell PATCH cannot carry, so a move
1676
+ // that re-points anything saves through the whole-workbook PUT, as structure does.
1677
+ if (move) {
1678
+ const landed = withCells(base, target, edits);
1679
+ const movedOn = landed.sheets.find((t) => t.id === target)?.name ?? "";
1680
+ const out = reanchorWorkbookForMove(landed.sheets, landed.namedRanges, movedOn, move);
1681
+ if (out.changed > 0) {
1682
+ editSeqRef.current += 1;
1683
+ setNotice("");
1684
+ structureDirtyRef.current = true;
1685
+ applyLocal({ ...landed, sheets: out.sheets, namedRanges: out.namedRanges });
1686
+ queueSave();
1687
+ return;
1688
+ }
1689
+ }
1690
  editSeqRef.current += 1;
1691
  setNotice("");
1692
  // ⭐⭐ W51-T11 / R4 — THE DIRTY SET, AND `edits` IS ALREADY EXACTLY IT. The changed addresses
 
1696
  for (const addr of Object.keys(edits)) markDirty(target, addr);
1697
  applyLocal(withCells(base, target, edits));
1698
  queueSave();
1699
+ }, [applyLocal, ensureTabs, markDirty, queueSave]);
1700
+ commitCellsRef.current = commitCells;
1701
 
1702
  // ═══════════════════════════════════════════════════════════════════════════════════════════
1703
  // ⭐⭐ W50-T20 — STRUCTURE, THROUGH THE SAME DOOR AS A KEYSTROKE.
 
2271
  const onSaveBinding = useCallback((binding: Record<string, unknown>) => {
2272
  const addr = editAt;
2273
  if (!addr) return;
2274
+ // S67-T04: a panel opened on another tab never saves here (the close above normally wins).
2275
+ if (panelTabRef.current && panelTabRef.current !== tabIdRef.current) {
2276
+ setEditAt("");
2277
+ return;
2278
+ }
2279
  setEditAt("");
2280
  void saveBindingAt(addr, binding);
2281
  }, [editAt, saveBindingAt]);
 
2334
  // ⭐ W54-T34: the busy state goes on in the SAME act as the open, so the control changes in the
2335
  // same frame the surface appears. `DrillModal` takes it off again through `onSettled`.
2336
  setDrillLoading(true);
2337
+ panelTabRef.current = tabIdRef.current;
2338
  setDrillAt(addr);
2339
  }, []);
2340
 
 
3121
  // `onCommit={commitCells}`, with no self-closing tag in between, or `verify_wiring`'s
3122
  // W50-T17 row reds a ticket this does not own.
3123
  onRules={onRules}
3124
+ // S67-T03 / C1: the in-cell draft channel. After `onCommit` for the same W50-T17 reason.
3125
+ onDraftChange={setCellDraft}
3126
+ // S67-T07: a viewer's cell menu shows its edit items disabled, not hidden.
3127
+ readOnly={Boolean(outlineRole) && !canEditOutline}
3128
  onHideBands={onHideBands}
3129
  onRowGroups={canEditOutline ? onRowGroups : undefined}
3130
  // ⭐⭐ W51-T08 / CONTRACT C1 — THE FOUR SEAM PROPS THE RIBBON IS FED THROUGH.
 
3143
  disabled={busy}
3144
  onAddrChange={setBarAddr}
3145
  onCommit={commitCells}
3146
+ draft={cellDraft}
3147
  />}
3148
  onSaveNow={onSaveNow}
3149
  onOpenImport={onOpenImport}
 
3374
  </div>
3375
  )}
3376
 
3377
+ {book && editAt && (!panelTabRef.current || panelTabRef.current === tabId) && (
3378
  /*
3379
  * ⛔⛔ `key={editAt}` REMOUNTS THE PANEL, AND WITHOUT IT THE SECOND CELL SHOWS THE FIRST
3380
  * CELL'S PERIOD. `BindingEditor` seeds its period, lock and drag state from `initial`
 
3417
  selection; removing the dialog outright removes the only surface that could ever steal
3418
  that focus. */}
3419
 
3420
+ {book && drillAt && (!panelTabRef.current || panelTabRef.current === tabId) && (
3421
  <DrillModal
3422
  workbookId={book.id}
3423
  addr={drillAt}
web/src/sheet/a1.ts CHANGED
@@ -302,6 +302,48 @@ export const shiftForStructure = (
302
  return rewriteRefs(String(formula || ""), rewrite, shift.delta < 0 ? rewriteRange : undefined);
303
  };
304
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
305
  /**
306
  * R5's other half: a cross-tab reference FOLLOWS a rename.
307
  *
 
302
  return rewriteRefs(String(formula || ""), rewrite, shift.delta < 0 ? rewriteRange : undefined);
303
  };
304
 
305
+ /**
306
+ * ⭐⭐ S67-T09 (QI5, D-3285) — A CUT CELL TAKES EVERY REFERENCE TO IT ALONG, AS EXCEL DOES.
307
+ *
308
+ * A move relocates the block `col0:col1 x row0:row1` (1-based, inclusive) on `sheet` by `dRow` /
309
+ * `dCol`. A reference that points INTO the block follows it, `$` or not (Excel re-points absolute
310
+ * references on a cut too); a range follows only when BOTH ends lie inside the block, so a range
311
+ * the block merely overlaps is left as it was. Any other reference is untouched.
312
+ */
313
+ export interface CellMove {
314
+ /** The NAME of the tab the block moved on. */
315
+ sheet: string;
316
+ col0: number;
317
+ row0: number;
318
+ col1: number;
319
+ row1: number;
320
+ dRow: number;
321
+ dCol: number;
322
+ }
323
+
324
+ export const shiftForMove = (formula: string, move: CellMove, ownSheet: string): string => {
325
+ const src = String(formula || "");
326
+ if (!move.dRow && !move.dCol) return src;
327
+ const inside = (ref: CellRef, sheet: string): boolean => {
328
+ if (!sameName(ref.sheet || sheet, move.sheet)) return false;
329
+ const col = colToIndex(ref.col);
330
+ return ref.row >= move.row0 && ref.row <= move.row1 && col >= move.col0 && col <= move.col1;
331
+ };
332
+ const moved = (ref: CellRef): CellRef => ({
333
+ ...ref, row: ref.row + move.dRow, col: indexToCol(colToIndex(ref.col) + move.dCol),
334
+ });
335
+ const rewrite = (ref: CellRef): CellRef => (inside(ref, ownSheet) ? moved(ref) : ref);
336
+ const rewriteRange = (from: CellRef, to: CellRef, separator: string): string => {
337
+ const sheet = from.sheet || ownSheet;
338
+ // A bare right endpoint inherits the left endpoint's sheet, not the formula's tab.
339
+ if (inside(from, ownSheet) && inside(to, to.sheet ? ownSheet : sheet)) {
340
+ return formatRef(moved(from)) + separator + formatRef(moved(to));
341
+ }
342
+ return formatRef(from) + separator + formatRef(to);
343
+ };
344
+ return rewriteRefs(src, rewrite, rewriteRange);
345
+ };
346
+
347
  /**
348
  * R5's other half: a cross-tab reference FOLLOWS a rename.
349
  *
web/src/sheet/bindingRefs.ts CHANGED
@@ -481,6 +481,16 @@ export const shiftBindingRefs = (
481
  /** W61-T01 / C1: structure follows each referenced cell's position through the same registry. */
482
  export const structureBindingRefs = (
483
  binding: Record<string, unknown>, shift: StructuralShift, ownSheet: string,
 
 
 
 
 
 
 
 
 
 
484
  ): BindingRefShift => {
485
  let out = binding;
486
  const moved: string[] = [];
@@ -492,7 +502,7 @@ export const structureBindingRefs = (
492
  slot.refKey ?? FILTER_REF_KEYS[0], "ref"];
493
  registered.add(path.join("."));
494
  // R9 locks COPY only; even pinned slots follow cells moved by a structural operation.
495
- const next = shiftForStructure(slot.text, shift, ownSheet);
496
  if (next === slot.text) continue;
497
  if (slot.kind === "filter") {
498
  const scope = asRecord(out.scope)!;
@@ -519,7 +529,7 @@ export const structureBindingRefs = (
519
  const location = [...path, key];
520
  if (BINDING_REF_KEYS.has(key) && typeof child === "string" && parseRef(child)
521
  && !registered.has(location.join("."))) {
522
- const value = shiftForStructure(child, shift, ownSheet);
523
  if (value !== child) {
524
  next = { ...next, [key]: value };
525
  moved.push(location.join("."));
@@ -566,6 +576,31 @@ export const resolveEndingCell = (book: Workbook, text: string, home?: string):
566
  return date;
567
  };
568
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
569
  export const resolveFilterCell = (book: Workbook, text: string, home?: string): string => {
570
  const fail = (reason: string): never => {
571
  throw new Error(`Filter value from cell ${text || "(blank)"} cannot be read because ${reason} `
@@ -575,6 +610,14 @@ export const resolveFilterCell = (book: Workbook, text: string, home?: string):
575
  if (!["string", "number", "boolean"].includes(typeof value) || String(value).trim() === ""
576
  || typeof value === "number" && !Number.isFinite(value))
577
  return fail("its value is blank or is not a single usable value.");
 
 
 
 
 
 
 
 
578
  return String(value);
579
  };
580
 
 
481
  /** W61-T01 / C1: structure follows each referenced cell's position through the same registry. */
482
  export const structureBindingRefs = (
483
  binding: Record<string, unknown>, shift: StructuralShift, ownSheet: string,
484
+ ): BindingRefShift => mapBindingRefs(binding, (text) => shiftForStructure(text, shift, ownSheet));
485
+
486
+ /**
487
+ * ⭐ S67-T09: the ONE walk over every reference a binding carries (period, filter leaves with
488
+ * their `valueRef` / `value2Ref`, related leaves, and the legacy keys in `BINDING_REF_KEYS`),
489
+ * with the rewrite handed in. A structural insert/delete and a cell MOVE (`a1.ts::shiftForMove`)
490
+ * both pass through it, so neither can miss a slot the other reaches.
491
+ */
492
+ export const mapBindingRefs = (
493
+ binding: Record<string, unknown>, rewrite: (text: string) => string,
494
  ): BindingRefShift => {
495
  let out = binding;
496
  const moved: string[] = [];
 
502
  slot.refKey ?? FILTER_REF_KEYS[0], "ref"];
503
  registered.add(path.join("."));
504
  // R9 locks COPY only; even pinned slots follow cells moved by a structural operation.
505
+ const next = rewrite(slot.text);
506
  if (next === slot.text) continue;
507
  if (slot.kind === "filter") {
508
  const scope = asRecord(out.scope)!;
 
529
  const location = [...path, key];
530
  if (BINDING_REF_KEYS.has(key) && typeof child === "string" && parseRef(child)
531
  && !registered.has(location.join("."))) {
532
+ const value = rewrite(child);
533
  if (value !== child) {
534
  next = { ...next, [key]: value };
535
  moved.push(location.join("."));
 
576
  return date;
577
  };
578
 
579
+ /**
580
+ * ⭐⭐ S67-T10 (QI4, D-767) — A CELL IS A DATE WHEN ITS NUMBER FORMAT SAYS SO: a Date format set by
581
+ * hand, the format the engine infers for DATE() / TODAY() / NOW() (written into `style.format`),
582
+ * or an imported Excel code carrying day or year tokens. Mirrored by
583
+ * `platform/modules/sheet.py::date_formatted_cell`, so the panel, a refresh and the server read
584
+ * the same cell the same way.
585
+ */
586
+ export const isDateFormattedCell = (cell: unknown): boolean => {
587
+ const style = asRecord(asRecord(cell)?.style);
588
+ const format = asRecord(style?.format);
589
+ if (!format) return false;
590
+ if (format.kind === "date") return true;
591
+ return format.kind === "code" && typeof format.code === "string"
592
+ && /[dy]/i.test(format.code.replace(/"[^"]*"|\\./g, ""));
593
+ };
594
+
595
+ /** The referenced cell itself, for the questions its VALUE alone cannot answer (its format). */
596
+ const bindingCellAt = (book: Workbook, text: string, home?: string): unknown => {
597
+ const ref = parseRef(text);
598
+ if (!ref) return null;
599
+ const name = ref.sheet || home;
600
+ const tab = name ? book.sheets.find((t) => t.id === name || t.name === name) : book.sheets[0];
601
+ return tab?.cells[`${ref.col}${ref.row}`] ?? null;
602
+ };
603
+
604
  export const resolveFilterCell = (book: Workbook, text: string, home?: string): string => {
605
  const fail = (reason: string): never => {
606
  throw new Error(`Filter value from cell ${text || "(blank)"} cannot be read because ${reason} `
 
610
  if (!["string", "number", "boolean"].includes(typeof value) || String(value).trim() === ""
611
  || typeof value === "number" && !Number.isFinite(value))
612
  return fail("its value is blank or is not a single usable value.");
613
+ // S67-T10: a date-formatted serial (typed, or a formula's result such as 46293) IS that date,
614
+ // for every operator, so it leaves as the ISO day the filter compares. A plain number with no
615
+ // date format stays a number and the panel refuses it by name (O9).
616
+ if (typeof value === "number" && isDateFormattedCell(bindingCellAt(book, text, home))) {
617
+ const day = endingCellDate(value, book.dateSystem);
618
+ if (!day) return fail("its value is not a real date.");
619
+ return day;
620
+ }
621
  return String(value);
622
  };
623
 
web/src/sheet/borderIcons.tsx ADDED
@@ -0,0 +1,148 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // sheet/borderIcons.tsx — the icons of the Borders gallery (S67-T15, instruction 16, J16).
2
+ //
3
+ // ⭐ ONE COMPONENT PER ENTRY, IN EXCEL'S OWN READING OF IT. Every preset icon is the same 16 by 16
4
+ // cell of four quarters: the edges the preset WRITES are drawn solid (thick or double where the
5
+ // preset's name says so), and every other line of the cell is a faint dotted grid, so the eye
6
+ // reads which sides change at a glance, exactly as Excel's menu does.
7
+ //
8
+ // ⚠ DESIGN CONTRACT (DESIGN.md 2 and 4): inline SVG on `currentColor`, the house `sheet-ribbon-icon`
9
+ // class, no icon pack, no emoji, no `<text>`, and no colour literal. The one colour an icon here
10
+ // may paint is the person's chosen LINE colour, which is data (DESIGN.md 3) and arrives as a prop.
11
+
12
+ import type { ReactNode } from "react";
13
+ import type { CellBorderStyle } from "./types";
14
+
15
+ /** The cell the icons draw on: an 11 by 11 box split into four quarters. */
16
+ const LO = 2.5;
17
+ const MID = 8;
18
+ const HI = 13.5;
19
+
20
+ type Edge = "top" | "bottom" | "left" | "right" | "insideH" | "insideV";
21
+
22
+ const EDGE_PATH: Record<Edge, string> = {
23
+ top: `M${LO} ${LO}H${HI}`,
24
+ bottom: `M${LO} ${HI}H${HI}`,
25
+ left: `M${LO} ${LO}V${HI}`,
26
+ right: `M${HI} ${LO}V${HI}`,
27
+ insideH: `M${LO} ${MID}H${HI}`,
28
+ insideV: `M${MID} ${LO}V${HI}`,
29
+ };
30
+
31
+ /** Every line of the cell, faint and dotted: what a preset leaves alone. */
32
+ const GRID = Object.values(EDGE_PATH).join("");
33
+
34
+ function Cell({ children, faint = true }: { children?: ReactNode; faint?: boolean }) {
35
+ return (
36
+ <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon sheet-border-icon">
37
+ {faint && <path d={GRID} strokeWidth="1" strokeDasharray="0.6 1.6" opacity="0.5" />}
38
+ {children}
39
+ </svg>
40
+ );
41
+ }
42
+
43
+ /** Solid edges at the house weight. */
44
+ const solid = (...edges: Edge[]) => <path d={edges.map((e) => EDGE_PATH[e]).join("")} />;
45
+
46
+ /** A thick edge, drawn at nearly twice the house weight. */
47
+ const thick = (...edges: Edge[]) => (
48
+ <path d={edges.map((e) => EDGE_PATH[e]).join("")} strokeWidth="2.6" strokeLinecap="square" />
49
+ );
50
+
51
+ /** The bottom edge as two thin rules, which is what Excel's double line is. */
52
+ const doubleBottom = () => (
53
+ <path d={`M${LO} ${HI - 1.6}H${HI}M${LO} ${HI}H${HI}`} strokeWidth="1" />
54
+ );
55
+
56
+ export const IconBorderBottom = () => <Cell>{solid("bottom")}</Cell>;
57
+ export const IconBorderTop = () => <Cell>{solid("top")}</Cell>;
58
+ export const IconBorderLeft = () => <Cell>{solid("left")}</Cell>;
59
+ export const IconBorderRight = () => <Cell>{solid("right")}</Cell>;
60
+ export const IconBorderNone = () => <Cell />;
61
+ export const IconBorderAll = () => (
62
+ <Cell faint={false}>{solid("top", "bottom", "left", "right", "insideH", "insideV")}</Cell>
63
+ );
64
+ export const IconBorderOutside = () => <Cell>{solid("top", "bottom", "left", "right")}</Cell>;
65
+ export const IconBorderThickOutside = () => (
66
+ <Cell>{thick("top", "bottom", "left", "right")}</Cell>
67
+ );
68
+ export const IconBorderBottomDouble = () => <Cell>{doubleBottom()}</Cell>;
69
+ export const IconBorderThickBottom = () => <Cell>{thick("bottom")}</Cell>;
70
+ export const IconBorderTopBottom = () => <Cell>{solid("top", "bottom")}</Cell>;
71
+ export const IconBorderTopThickBottom = () => <Cell>{solid("top")}{thick("bottom")}</Cell>;
72
+ export const IconBorderTopDoubleBottom = () => <Cell>{solid("top")}{doubleBottom()}</Cell>;
73
+
74
+ /** A pencil laid across the cell's corner: the shared mark of the three draw tools. */
75
+ const PENCIL = "M9.2 10.8l4.6-4.6 1.4 1.4-4.6 4.6-2 .6.6-2Z";
76
+
77
+ export const IconDrawBorder = () => (
78
+ <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon sheet-border-icon">
79
+ <path d={`M${LO} ${HI}H8M${LO} ${LO}V${HI}`} />
80
+ <path d={PENCIL} />
81
+ </svg>
82
+ );
83
+
84
+ export const IconDrawBorderGrid = () => (
85
+ <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon sheet-border-icon">
86
+ <path d={`M${LO} ${LO}H11M${LO} ${LO}V${HI}H8M${LO} ${MID}H8M${MID} ${LO}V8`} />
87
+ <path d={PENCIL} />
88
+ </svg>
89
+ );
90
+
91
+ export const IconEraseBorder = () => (
92
+ <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon sheet-border-icon">
93
+ <path d={`M${LO} ${HI}H${HI}`} strokeDasharray="0.6 1.6" opacity="0.5" />
94
+ <path d="M3.6 9.6l5.6-5.6 3.4 3.4-5.6 5.6H5.6Z" />
95
+ <path d="M6.4 6.8l3.4 3.4" />
96
+ </svg>
97
+ );
98
+
99
+ /** A pencil over a bar in the chosen line colour, which is data and so arrives as a prop. */
100
+ export function IconLineColor({ colour }: { colour: string }) {
101
+ return (
102
+ <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon sheet-border-icon">
103
+ <path d="M4.2 9.4l5.6-5.6 1.8 1.8-5.6 5.6-2.4.6.6-2.4Z" />
104
+ <rect x="1.5" y="13" width="13" height="2.5" fill={colour} stroke="currentColor" strokeWidth="0.8" />
105
+ </svg>
106
+ );
107
+ }
108
+
109
+ /** Three rules of three weights and patterns: the choice the flyout offers. */
110
+ export const IconLineStyle = () => (
111
+ <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon sheet-border-icon">
112
+ <path d="M2 4h12" strokeWidth="1" />
113
+ <path d="M2 8h12" strokeWidth="2.2" strokeLinecap="butt" />
114
+ <path d="M2 12.2h12" strokeWidth="1" strokeDasharray="2.4 1.6" strokeLinecap="butt" />
115
+ </svg>
116
+ );
117
+
118
+ /** The whole grid drawn, with a small ellipsis mark: the dialog that holds every option. */
119
+ export const IconMoreBorders = () => (
120
+ <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon sheet-border-icon">
121
+ <path d={`M${LO} ${LO}H${HI}V${MID}M${LO} ${LO}V${HI}H${MID}M${LO} ${MID}H${MID}M${MID} ${LO}V${HI}`} />
122
+ <path d="M10.4 12.4h.01M12.2 12.4h.01M14 12.4h.01" strokeWidth="1.6" />
123
+ </svg>
124
+ );
125
+
126
+ /**
127
+ * ⭐ ONE SAMPLE PER LINE STYLE, DRAWN AS THE PAINTER DRAWS IT (`cellBorders.ts::paintCellBorders`):
128
+ * thin 1px, medium 2px, thick 3px, dashed, dotted, double, hair. The Line Style flyout shows the
129
+ * line itself rather than a word, because the word is what a person has to translate.
130
+ */
131
+ export function LineStyleSample({ style }: { style: CellBorderStyle }) {
132
+ const common = { fill: "none", stroke: "currentColor", strokeLinecap: "butt" as const };
133
+ let body: ReactNode;
134
+ switch (style) {
135
+ case "medium": body = <path d="M1 5h54" strokeWidth="2" {...common} />; break;
136
+ case "thick": body = <path d="M1 5h54" strokeWidth="3" {...common} />; break;
137
+ case "dashed": body = <path d="M1 5h54" strokeWidth="1" strokeDasharray="4 2" {...common} />; break;
138
+ case "dotted": body = <path d="M1 5h54" strokeWidth="1" strokeDasharray="1 2" {...common} />; break;
139
+ case "double": body = <path d="M1 3.5h54M1 6.5h54" strokeWidth="1" {...common} />; break;
140
+ case "hair": body = <path d="M1 5h54" strokeWidth="1" strokeDasharray="1 1" opacity="0.7" {...common} />; break;
141
+ default: body = <path d="M1 5h54" strokeWidth="1" {...common} />;
142
+ }
143
+ return (
144
+ <svg viewBox="0 0 56 10" aria-hidden="true" className="sheet-border-sample">
145
+ {body}
146
+ </svg>
147
+ );
148
+ }