fsanyoto commited on
Commit
c920df3
·
verified ·
1 Parent(s): 867c93c

Deploy AIOS web (React glide grid + FastAPI slice)

Browse files
Files changed (45) hide show
  1. RELEASES.json +1 -1
  2. VERSION +1 -1
  3. api/application_registry.py +49 -5
  4. api/main.py +67 -23
  5. api/routes_activity.py +392 -0
  6. api/routes_applications.py +115 -2
  7. api/routes_odoo_tables.py +73 -16
  8. api/routes_sheet.py +463 -214
  9. api/routes_templates.py +36 -1
  10. platform/core/daily_sales_repair.py +509 -15
  11. platform/core/registry.py +47 -0
  12. platform/core/sheet_binding.py +186 -4
  13. platform/core/sheets.py +28 -1
  14. platform/modules/collections_send.py +41 -4
  15. platform/modules/finance_apps.py +12 -0
  16. platform/modules/sheet.py +148 -7
  17. web/public/AIOS_DEPLOY_RECEIPT +1 -1
  18. web/src/app/FinanceWorkspace.tsx +18 -8
  19. web/src/apps/CollectionPage.tsx +395 -0
  20. web/src/apps/collection.css +152 -0
  21. web/src/customer-grid/CustomerGrid.tsx +9 -2
  22. web/src/customer-grid/apiBridge.ts +12 -4
  23. web/src/customer-grid/useCustomerData.ts +8 -1
  24. web/src/home/HomePage.tsx +60 -53
  25. web/src/home/TemplatePicker.tsx +11 -4
  26. web/src/home/homeModel.ts +5 -5
  27. web/src/main.tsx +2 -0
  28. web/src/settings/ActivityLogPage.tsx +231 -0
  29. web/src/settings/ExternalAccessPane.tsx +347 -199
  30. web/src/settings/SettingsModal.tsx +10 -0
  31. web/src/settings/activityLog.css +58 -0
  32. web/src/settings/activityLog.ts +392 -0
  33. web/src/settings/permsModel.ts +1 -0
  34. web/src/sheet/BindingEditor.tsx +195 -9
  35. web/src/sheet/SheetGrid.tsx +194 -28
  36. web/src/sheet/SheetPage.tsx +15 -2
  37. web/src/sheet/cellBorders.ts +17 -10
  38. web/src/sheet/cellStyleOps.ts +4 -0
  39. web/src/sheet/ribbonIcons.tsx +8 -0
  40. web/src/sheet/rowOutline.css +46 -0
  41. web/src/sheet/sheetState.ts +222 -19
  42. web/src/sheet/types.ts +24 -0
  43. web/src/shell/Shell.tsx +61 -70
  44. web/src/shell/nav.ts +7 -0
  45. web/src/shell/navExtras.css +43 -0
RELEASES.json CHANGED
@@ -1,4 +1,4 @@
1
  {
2
- "current": "e77240f",
3
  "releases": []
4
  }
 
1
  {
2
+ "current": "83f42be",
3
  "releases": []
4
  }
VERSION CHANGED
@@ -1 +1 @@
1
- e77240f
 
1
+ 83f42be
api/application_registry.py CHANGED
@@ -11,7 +11,11 @@ from modules.finance_spine import fact_specs as _finance_fact_specs
11
 
12
 
13
  APPLICATION_TYPES = ("chart", "route", "map", "timeseries")
14
- APPLICATION_TEMPLATE_KINDS = ("route", "catalog")
 
 
 
 
15
  _KEY = "applications_v1"
16
  _MAX = 500
17
 
@@ -52,6 +56,15 @@ _TEMPLATE_CONTRACTS = {
52
  ],
53
  "defaultPlacement": {"section": "app", "order": 0},
54
  },
 
 
 
 
 
 
 
 
 
55
  }
56
 
57
 
@@ -61,7 +74,7 @@ class ApplicationError(ValueError):
61
 
62
  def template_contracts():
63
  """The trusted renderer contracts offered by the Application creation flow."""
64
- return [copy.deepcopy(_TEMPLATE_CONTRACTS[kind]) for kind in APPLICATION_TEMPLATE_KINDS]
65
 
66
 
67
  def finance_group():
@@ -77,6 +90,8 @@ def finance_applications(may_open=None):
77
  # R6: Finance records are read-only projections of finance_apps.py, never validated, created,
78
  # mutated, or persisted. Adding "finance" to APPLICATION_TYPES buys nothing and weakens
79
  # validate_application's governed type vocabulary.
 
 
80
  def finance_application_records(may_open=None):
81
  """Project the grant-filtered Finance catalogue as seeded Application records."""
82
  return [
@@ -330,6 +345,24 @@ def _template_definition(kind, payload, *, semantic_records=None, field_contract
330
  template_kind = str(payload.get("templateKind") or "").strip().lower()
331
  if template_kind != kind:
332
  raise ApplicationError(f"{kind} applications require templateKind {kind!r}")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
333
  source = str(payload.get("sourceDatabase") or "").strip()[:120]
334
  if not source:
335
  raise ApplicationError("sourceDatabase is required")
@@ -430,6 +463,13 @@ def _public(app, user, is_admin=False, *, allowed_databases=None, target_databas
430
  "default":bool(is_admin)}
431
  row["starred"] = user in (app.get("starredBy") or ())
432
  row["isDefault"] = bool(is_default)
 
 
 
 
 
 
 
433
  target_database = target_database if target_database in compatible else (compatible[0] if compatible else None)
434
  row["openTarget"]={"kind":"application","id":row["id"],"type":row["type"],
435
  "database":target_database}
@@ -443,7 +483,8 @@ def list_apps(runtime, user, is_admin=False, *, database=None, kind=None, starre
443
  for app in doc["applications"].values():
444
  if not may_read(app,user,is_admin): continue
445
  if database and database not in (app.get("compatibleDatabases") or ()): continue
446
- if not _allowed(app.get("compatibleDatabases"), allowed_databases): continue
 
447
  if kind and app.get("type") != kind: continue
448
  if starred is not None and bool(user in (app.get("starredBy") or ())) != bool(starred): continue
449
  default_key = f"{database}::{app.get('type')}" if database else ""
@@ -457,6 +498,7 @@ def nav_applications(runtime, user, is_admin=False, *, may_open=None, allowed_da
457
  """The ONE generic navigation read for stored and seeded Application records (R6)."""
458
  rows = [{"id": app["id"], "name": app.get("name"),
459
  "type": app.get("type"), "templateKind": app.get("templateKind"),
 
460
  "origin": "tenant",
461
  "compatibleDatabases": app.get("compatibleDatabases") or [],
462
  "openTarget": app.get("openTarget"),
@@ -480,7 +522,8 @@ def create(runtime, tenant, user, payload, *, semantic_records=None, field_contr
480
  name=" ".join(str(payload.get("name") or "").split())[:120]
481
  if not name: raise ApplicationError("application name is required")
482
  app_id=f"app_{write_execution.new_id()[:16]}"; now=write_execution.utcnow().isoformat()
483
- compatible = ([definition["sourceDatabase"]] if definition
 
484
  else _compat(payload.get("compatibleDatabases")))
485
  if _allowed(compatible, allowed_databases) != set(compatible):
486
  raise PermissionError("an Application cannot bind a database you cannot open")
@@ -508,7 +551,8 @@ def mutate(runtime, app_id, user, is_admin, patch, *, semantic_records=None,
508
  allowed_databases=None, target_database=None):
509
  patch=patch if isinstance(patch,dict) else {}; landed={}
510
  immutable = sorted(set(patch) & {
511
- "id", "tenant", "type", "templateKind", "sourceDatabase", "fieldMap", "navPlacement"
 
512
  })
513
  if immutable:
514
  raise ApplicationError("Application identity and template definition are immutable: "
 
11
 
12
 
13
  APPLICATION_TYPES = ("chart", "route", "map", "timeseries")
14
+ # The wizard binds a database and fields. Finance templates use the catalogue POST instead;
15
+ # validation accepts both creation doors without offering Finance to the five-step wizard.
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
 
 
56
  ],
57
  "defaultPlacement": {"section": "app", "order": 0},
58
  },
59
+ "finance": {
60
+ "kind": "finance",
61
+ "label": "Finance",
62
+ # Like Catalog, templateKind selects a trusted surface without growing APPLICATION_TYPES.
63
+ "applicationType": "chart",
64
+ "displayMode": "chart",
65
+ "fieldRoles": [],
66
+ "defaultPlacement": {"section": "app", "order": 0},
67
+ },
68
  }
69
 
70
 
 
74
 
75
  def template_contracts():
76
  """The trusted renderer contracts offered by the Application creation flow."""
77
+ return [copy.deepcopy(_TEMPLATE_CONTRACTS[kind]) for kind in APPLICATION_WIZARD_TEMPLATE_KINDS]
78
 
79
 
80
  def finance_group():
 
90
  # R6: Finance records are read-only projections of finance_apps.py, never validated, created,
91
  # mutated, or persisted. Adding "finance" to APPLICATION_TYPES buys nothing and weakens
92
  # validate_application's governed type vocabulary.
93
+ # This remains true for the SEEDED six. Users may now persist their own Finance applications
94
+ # through templateKind, pointing to the same trusted surface without modifying those projections.
95
  def finance_application_records(may_open=None):
96
  """Project the grant-filtered Finance catalogue as seeded Application records."""
97
  return [
 
345
  template_kind = str(payload.get("templateKind") or "").strip().lower()
346
  if template_kind != kind:
347
  raise ApplicationError(f"{kind} applications require templateKind {kind!r}")
348
+ if kind == FINANCE_TEMPLATE_KIND:
349
+ finance_key = str(payload.get("financeKey") or "").strip()
350
+ try:
351
+ app = _finance_application(finance_key)
352
+ except KeyError:
353
+ raise ApplicationError(f"Finance application {finance_key!r} does not exist.")
354
+ if payload.get("sourceDatabase") or payload.get("fieldMap") or payload.get("compatibleDatabases"):
355
+ raise ApplicationError("Finance applications do not bind a database or fields.")
356
+ raw_placement = payload.get("navPlacement")
357
+ if not isinstance(raw_placement, dict) or set(raw_placement) != {"section", "order"}:
358
+ raise ApplicationError("navPlacement must contain section and order")
359
+ if raw_placement.get("section") != "app":
360
+ raise ApplicationError("Finance applications must be placed in App.")
361
+ order = raw_placement.get("order")
362
+ if type(order) is not int or not 0 <= order <= 999:
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")
 
463
  "default":bool(is_admin)}
464
  row["starred"] = user in (app.get("starredBy") or ())
465
  row["isDefault"] = bool(is_default)
466
+ if row.get("templateKind") == FINANCE_TEMPLATE_KIND:
467
+ # The database-bound mutation doors cannot edit Finance definitions. Honour that in
468
+ # every card rather than displaying controls that can only refuse.
469
+ row["capabilities"].update({key: False for key in (
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}
 
483
  for app in doc["applications"].values():
484
  if not may_read(app,user,is_admin): continue
485
  if database and database not in (app.get("compatibleDatabases") or ()): continue
486
+ if (app.get("templateKind") != FINANCE_TEMPLATE_KIND
487
+ and not _allowed(app.get("compatibleDatabases"), allowed_databases)): continue
488
  if kind and app.get("type") != kind: continue
489
  if starred is not None and bool(user in (app.get("starredBy") or ())) != bool(starred): continue
490
  default_key = f"{database}::{app.get('type')}" if database else ""
 
498
  """The ONE generic navigation read for stored and seeded Application records (R6)."""
499
  rows = [{"id": app["id"], "name": app.get("name"),
500
  "type": app.get("type"), "templateKind": app.get("templateKind"),
501
+ "deepLink": app.get("deepLink"),
502
  "origin": "tenant",
503
  "compatibleDatabases": app.get("compatibleDatabases") or [],
504
  "openTarget": app.get("openTarget"),
 
522
  name=" ".join(str(payload.get("name") or "").split())[:120]
523
  if not name: raise ApplicationError("application name is required")
524
  app_id=f"app_{write_execution.new_id()[:16]}"; now=write_execution.utcnow().isoformat()
525
+ compatible = ([] if template_kind == FINANCE_TEMPLATE_KIND
526
+ else [definition["sourceDatabase"]] if definition
527
  else _compat(payload.get("compatibleDatabases")))
528
  if _allowed(compatible, allowed_databases) != set(compatible):
529
  raise PermissionError("an Application cannot bind a database you cannot open")
 
551
  allowed_databases=None, target_database=None):
552
  patch=patch if isinstance(patch,dict) else {}; landed={}
553
  immutable = sorted(set(patch) & {
554
+ "id", "tenant", "type", "templateKind", "sourceDatabase", "fieldMap", "navPlacement",
555
+ "financeKey", "deepLink"
556
  })
557
  if immutable:
558
  raise ApplicationError("Application identity and template definition are immutable: "
api/main.py CHANGED
@@ -771,49 +771,93 @@ class _SyncNowRefused(Exception):
771
  """An application-authored, credential-free sentence for a Sync now receipt."""
772
 
773
 
774
- def _sync_now_failure(cause):
775
  """Classify actual provider failures without returning vendor text or exception reprs."""
776
  import re
777
- text = str(cause).lower()
 
778
  causes = (
779
- (("reduce the amount of data", "response too large"),
780
  "The provider refused the pull because the response contains too much data."),
781
- (("no ad accounts",), "The Meta token cannot access any ad accounts."),
782
- (("max_pages", "page cap"), "The pull stopped at the provider page limit."),
783
- (("sandbox",), "Amazon sync requires a production credential; this credential is for the sandbox."),
784
- (("deletion", "retention"), "Amazon sync is blocked by an outstanding data deletion requirement."),
785
- (("no stored", "no odoo credentials", "access_token is not set"),
 
 
786
  "This tenant has no usable credential for the connector."),
787
- (("enablement document", "capability unavailable"),
788
  "The connector database settings could not be read."),
789
- (("throttl", "rate limit", "too many requests"),
790
  "The provider rate limit stopped the sync. Retry after the provider delay."),
791
- (("timed out", "timeout"), "The sync failed because the provider request timed out."),
792
- (("permission", "access denied", "unauthorized", "invalid oauth", "invalid token",
793
  "expired", "authentication"), "The provider refused the connector credential or its permissions."),
794
- (("duplicate key", "primary key", "constraint"),
795
  "The mirror rejected rows because they violate a database constraint."),
796
- (("connection", "network", "name resolution"),
797
  "The sync could not connect to the provider or tenant database."),
798
  # A-META / D-201: a Meta pull on a container whose mirror never held `meta_*` raises
799
  # DuckDB's CatalogException. Standing rule 1 wants the CAUSE, not "unexpected error":
800
  # "the loader is broken" and "this server has never held these tables" are different
801
  # operator actions, and only the second one is true here.
802
- (("does not exist", "no such table", "catalog error"),
803
  "This server's mirror does not hold this connector's tables yet, so there was nothing "
804
  "to update. Run the connector's first load on the server that owns this tenant."),
805
  )
806
- for needles, sentence in causes:
807
  if any(needle in text for needle in needles):
808
- return sentence
809
  status = re.search(r"\bhttp\s+(\d{3})\b", text)
810
  if status:
811
- return f"The provider refused the sync request with HTTP status {status.group(1)}."
812
  if isinstance(cause, TypeError):
813
- return "The connector failed because its provider call used incompatible arguments."
814
  if isinstance(cause, (KeyError, ValueError)):
815
- return "The connector could not read an expected value in the sync response."
816
- return "The connector encountered an unexpected error while processing the sync response."
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
817
 
818
 
819
  def _run_sync_requests():
@@ -919,13 +963,13 @@ def _run_sync_requests():
919
  if problems:
920
  detail += " " + _sync_now_failure(problems[0])
921
  elif problems:
922
- detail = _sync_now_failure(problems[0])
923
  else:
924
  ok, detail = True, "Sync finished."
925
  except _SyncNowRefused as exc:
926
  detail = str(exc)
927
  except Exception as exc: # noqa: BLE001
928
- detail = _sync_now_failure(exc)
929
  if first_load_progress is not None:
930
  connector_sync.finish_sync_request(provider, tenant, ok=ok, detail=detail,
931
  first_load=first_load_progress)
 
771
  """An application-authored, credential-free sentence for a Sync now receipt."""
772
 
773
 
774
+ def _sync_now_cause(cause):
775
  """Classify actual provider failures without returning vendor text or exception reprs."""
776
  import re
777
+ raw = str(cause)
778
+ text = raw.lower()
779
  causes = (
780
+ ("response_too_large", ("reduce the amount of data", "response too large"),
781
  "The provider refused the pull because the response contains too much data."),
782
+ ("meta_no_ad_accounts", ("no ad accounts",), "The Meta token cannot access any ad accounts."),
783
+ ("page_cap", ("max_pages", "page cap"), "The pull stopped at the provider page limit."),
784
+ ("sandbox_credential", ("sandbox",),
785
+ "Amazon sync requires a production credential; this credential is for the sandbox."),
786
+ ("deletion_outstanding", ("deletion", "retention"),
787
+ "Amazon sync is blocked by an outstanding data deletion requirement."),
788
+ ("no_credential", ("no stored", "no odoo credentials", "access_token is not set"),
789
  "This tenant has no usable credential for the connector."),
790
+ ("enablement_unreadable", ("enablement document", "capability unavailable"),
791
  "The connector database settings could not be read."),
792
+ ("rate_limited", ("throttl", "rate limit", "too many requests"),
793
  "The provider rate limit stopped the sync. Retry after the provider delay."),
794
+ ("timeout", ("timed out", "timeout"), "The sync failed because the provider request timed out."),
795
+ ("credential_refused", ("permission", "access denied", "unauthorized", "invalid oauth", "invalid token",
796
  "expired", "authentication"), "The provider refused the connector credential or its permissions."),
797
+ ("mirror_constraint", ("duplicate key", "primary key", "constraint"),
798
  "The mirror rejected rows because they violate a database constraint."),
799
+ ("connect_failed", ("connection", "network", "name resolution"),
800
  "The sync could not connect to the provider or tenant database."),
801
  # A-META / D-201: a Meta pull on a container whose mirror never held `meta_*` raises
802
  # DuckDB's CatalogException. Standing rule 1 wants the CAUSE, not "unexpected error":
803
  # "the loader is broken" and "this server has never held these tables" are different
804
  # operator actions, and only the second one is true here.
805
+ ("mirror_missing_tables", ("does not exist", "no such table", "catalog error"),
806
  "This server's mirror does not hold this connector's tables yet, so there was nothing "
807
  "to update. Run the connector's first load on the server that owns this tenant."),
808
  )
809
+ for classifier, needles, sentence in causes:
810
  if any(needle in text for needle in needles):
811
+ return classifier, sentence
812
  status = re.search(r"\bhttp\s+(\d{3})\b", text)
813
  if status:
814
+ return "http_status", f"The provider refused the sync request with HTTP status {status.group(1)}."
815
  if isinstance(cause, TypeError):
816
+ return "bad_arguments", "The connector failed because its provider call used incompatible arguments."
817
  if isinstance(cause, (KeyError, ValueError)):
818
+ return "unreadable_value", "The connector could not read an expected value in the sync response."
819
+ if isinstance(cause, str):
820
+ # amazon_store._sync_problem appends the application-authored fix LAST. The
821
+ # exception message may itself contain delimiters; none of it is display text.
822
+ problem, separator, fix = raw.rpartition("; fix: ")
823
+ header = re.match(
824
+ r"(?P<table>[A-Za-z_][A-Za-z0-9_.-]*): "
825
+ r"(?P<operation>[A-Za-z_][A-Za-z0-9_.-]*) (?P<state>[A-Z]+): "
826
+ r"(?P<exception>[A-Za-z_][A-Za-z0-9_]*): ", problem)
827
+ if separator and header and fix.strip():
828
+ # Keep the authored action, with sentence punctuation suitable for the UI.
829
+ action = fix.strip().replace("\u2014", ". ").replace("\u2013", " to ")
830
+ sentence = (
831
+ f"The Amazon table {header['table']} could not be read. "
832
+ f"The {header['operation']} call was {header['state'].lower()} "
833
+ f"with {header['exception']}. What to do: {action}"
834
+ )
835
+ return "connector_reported", sentence if sentence.endswith(".") else sentence + "."
836
+ return "unclassified", (
837
+ "The connector reported an unclassified plain-text failure. "
838
+ "Ask an administrator to inspect the connector's sync report and retry.")
839
+ return "unclassified", (
840
+ f"The connector failed with an unclassified {type(cause).__name__}. "
841
+ "Ask an administrator to inspect the connector's sync report and retry.")
842
+
843
+
844
+ def _sync_now_failure(cause):
845
+ """Classify actual provider failures without returning vendor text or exception reprs."""
846
+ return _sync_now_cause(cause)[1]
847
+
848
+
849
+ def _sync_now_detail(provider, tenant, *, ok, detail="", cause=None):
850
+ """Record one classified failure; leave successful receipt text untouched."""
851
+ if ok:
852
+ return detail
853
+ classifier, sentence = _sync_now_cause(cause)
854
+ print(f"[aios-api] sync FAILED provider={provider} tenant={tenant} classifier={classifier}")
855
+ suffix = f" (cause code: {classifier})"
856
+ # finish_sync_request stores only 300 characters. Reserve the suffix before it clips.
857
+ budget = 300 - len(suffix)
858
+ if len(sentence) > budget:
859
+ sentence = sentence[:budget - 3].rstrip() + "..."
860
+ return sentence + suffix
861
 
862
 
863
  def _run_sync_requests():
 
963
  if problems:
964
  detail += " " + _sync_now_failure(problems[0])
965
  elif problems:
966
+ detail = _sync_now_detail(provider, tenant, ok=False, cause=problems[0])
967
  else:
968
  ok, detail = True, "Sync finished."
969
  except _SyncNowRefused as exc:
970
  detail = str(exc)
971
  except Exception as exc: # noqa: BLE001
972
+ detail = _sync_now_detail(provider, tenant, ok=False, cause=exc)
973
  if first_load_progress is not None:
974
  connector_sync.finish_sync_request(provider, tenant, ok=ok, detail=detail,
975
  first_load=first_load_progress)
api/routes_activity.py ADDED
@@ -0,0 +1,392 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Value-free activity history, persisted only through the tenant store (S65-T16)."""
2
+ import json
3
+ import math
4
+ import re
5
+ import time
6
+ import uuid
7
+ from urllib.parse import urlsplit
8
+
9
+ from fastapi import APIRouter, Depends, Query, Request
10
+ from starlette.concurrency import run_in_threadpool
11
+
12
+ from deps import Session, err, require_session
13
+
14
+
15
+ RETENTION_DAYS = 30
16
+ MAX_SESSIONS = 200
17
+ MAX_EVENTS_PER_SESSION = 2000
18
+ MAX_MOVEMENT_SAMPLES = 500
19
+ MOVEMENT_WINDOW_MS = 30_000
20
+ MAX_BATCH_EVENTS = 100
21
+ MAX_PAYLOAD_BYTES = 512 * 1024
22
+ MAX_STRING_LENGTH = 256
23
+ MAX_CLASS_LENGTH = 128
24
+ MAX_DATA_ATTRIBUTES = 16
25
+ MAX_PAGE_EVENTS = 100
26
+ BUCKET = "activity_log"
27
+
28
+ # The entire client field vocabulary, including nested objects, is here. Each
29
+ # shape below selects only its own subset; no arbitrary recursive object survives.
30
+ ACTIVITY_ALLOWED_KEYS = frozenset({
31
+ "sessionId", "events", "dropped", "kind", "ts", "route", "from", "to", "ms",
32
+ "target", "method", "url", "status", "message", "source", "line", "name",
33
+ "movement", "movementDropped", "x", "y", "key", "tagName", "role", "type",
34
+ "id", "data", "className", "aria-label", "path",
35
+ })
36
+ SECRET_KEYS = frozenset({
37
+ "value", "defaultvalue", "textcontent", "innertext", "innerhtml", "placeholder",
38
+ "password", "token", "apikey", "authorization", "cookie", "secret", "credential",
39
+ "accesstoken", "refreshtoken", "clientsecret", "clipboard", "body", "query",
40
+ "cellvalue", "celldata", "text", "content", "payload",
41
+ })
42
+ _BEARER = re.compile(r"\bbearer\s+\S+", re.I)
43
+ _JWT = re.compile(r"\beyJ[A-Za-z0-9_-]*\.")
44
+ _CREDENTIAL = re.compile(r"\blp[bcor]1\.[A-Za-z0-9._~-]+")
45
+ _TOKEN = re.compile(r"^[a-zA-Z][a-zA-Z0-9_-]{0,79}$")
46
+ _CLASS = re.compile(r"^(?:set|shell|sheet|cg|pg|activity|lp|is)-[a-z][a-z0-9-]*$")
47
+ _SID = re.compile(r"^[a-f0-9-]{32,36}$")
48
+ _TAGS = set("a button input textarea select option div span svg path rect circle canvas td th tr table body html main section nav header footer label form ul ol li h1 h2 h3 h4 p img dialog details summary video audio".split())
49
+ _ROLES = set("button link textbox checkbox radio switch combobox listbox option grid gridcell cell row columnheader rowheader dialog tab tabpanel menu menuitem navigation region slider spinbutton searchbox".split())
50
+ _TYPES = set("button submit reset text password email number search tel url date time checkbox radio range file hidden color".split())
51
+ _ERROR_NAMES = {"Error", "TypeError", "ReferenceError", "SyntaxError", "RangeError", "URIError", "EvalError", "AggregateError", "NetworkError", "HttpError", "ResourceError"}
52
+ _MESSAGES = {"Application error.", "Unhandled rejection.", "Script error.", "A request failed.", "A network request failed.", "A resource failed to load."}
53
+ _LABELS = {"Open", "Close", "Save", "Cancel", "Delete", "Edit", "Search", "Settings", "Close settings", "Activity log", "Refresh", "Previous", "Next", "Add", "Remove", "Menu", "More", "Retry"}
54
+ # Attribute values may hold tenant data even when their names look harmless.
55
+ # Retain only structural enums; all other safe data-* names record presence.
56
+ _DATA_ENUMS = {
57
+ "data-section": {"account", "scope", "security", "shortcuts", "activity", "users", "database", "keychains", "connectors", "padmin"},
58
+ "data-state": {"open", "closed", "active", "inactive", "loading", "ready"},
59
+ "data-view-kind": {"sheet", "grid", "table", "chart", "timeline"},
60
+ }
61
+ # Routes describe the surface, not record ids, searches, or cell text embedded in
62
+ # a URL. Unknown segments become :item on BOTH sides of the wire.
63
+ _ROUTE_SEGMENTS = set("api v1 auth me login logout refresh nav workspace settings account scope security shortcuts activity sessions users database databases grid sheet sheets view views table tables records rows columns fields cells query sort filter data applications finance facts orders inventory customers products sales collections procurement agents agent automation automations connectors keychains external oauth connections admin operator subscriptions billing health status run runs events logs actions export import search schema preferences folders pages charts catalog reports reconciliation permissions detail assets".split())
64
+
65
+ # ⛔ NO `prefix=` HERE, AND THAT IS DELIBERATE. This router is included INSIDE
66
+ # `routes_applications.router` (main.py belongs to another session this wave), and a child
67
+ # router that carries its own `prefix=` has that prefix baked into its own `.routes` at
68
+ # DECLARATION time. `verify_api.py::_mounted_paths` then adds `nested.prefix` a SECOND time
69
+ # while walking the nested include, so `/api/v1/activity` is derived as
70
+ # `/api/v1/api/v1/activity` and D-48 reports a client call with no route -- a false RED over a
71
+ # route the app genuinely serves (`app.openapi()` proves it). Spelling the full path on each
72
+ # decorator makes the declared path the served path, which is the honest reading either way.
73
+ router = APIRouter(tags=["activity"])
74
+
75
+
76
+ class ActivityRefused(ValueError):
77
+ """Never put a refused value into an exception, traceback, or response."""
78
+
79
+ def __init__(self, code, message):
80
+ self.code = code
81
+ self.message = message
82
+ super().__init__(message)
83
+
84
+
85
+ def _text(value, maximum=MAX_STRING_LENGTH):
86
+ if not isinstance(value, str):
87
+ return ""
88
+ if (_BEARER.search(value) or _JWT.search(value) or _CREDENTIAL.search(value)
89
+ or value.startswith("Atzr|")):
90
+ return ""
91
+ return re.sub(r"[\x00-\x1f\x7f\u2013\u2014]", " ", value)[:maximum]
92
+
93
+
94
+ def _shape(value):
95
+ if not isinstance(value, dict):
96
+ return {}
97
+ return {key: val for key, val in value.items() if key in ACTIVITY_ALLOWED_KEYS}
98
+
99
+
100
+ def _number(value, default=0, maximum=10**15):
101
+ if type(value) not in (int, float) or (isinstance(value, float) and not math.isfinite(value)):
102
+ return default
103
+ return min(maximum, max(0, round(value)))
104
+
105
+
106
+ def _path(value):
107
+ value = _text(value)
108
+ if not value:
109
+ return ""
110
+ try:
111
+ # Hash routes are paths too, but hash query parameters never survive.
112
+ raw = value[1:] if value.startswith("#") else urlsplit(value).path
113
+ raw = raw.split("?", 1)[0].split("#", 1)[0]
114
+ segments = raw.strip("/").split("/")
115
+ clean = [part if part in _ROUTE_SEGMENTS or re.fullmatch(r"[a-zA-Z0-9_-]+\.(?:js|css|tsx|ts)", part) else ":item" for part in segments if part]
116
+ return ("/" + "/".join(clean))[:MAX_STRING_LENGTH]
117
+ except ValueError:
118
+ return ""
119
+
120
+
121
+ def _classes(value):
122
+ return " ".join(part for part in _text(value).split() if _CLASS.fullmatch(part))[:MAX_CLASS_LENGTH]
123
+
124
+
125
+ def _element(raw):
126
+ raw = _shape(raw)
127
+ tag = _text(raw.get("tagName")).lower()
128
+ role = _text(raw.get("role"))
129
+ result = {"tagName": tag if tag in _TAGS else "element"}
130
+ if role in _ROLES:
131
+ result["role"] = role
132
+ element_type = _text(raw.get("type"), 32)
133
+ if element_type in _TYPES:
134
+ result["type"] = element_type
135
+ # The collector marks descendants of a grid/editor with role=gridcell/textbox.
136
+ # Defend direct forged input too; never accept rich metadata on these shapes.
137
+ protected = (tag in {"input", "textarea", "option", "select", "canvas", "td", "th"}
138
+ or role in {"grid", "gridcell", "cell", "textbox", "searchbox", "option"}
139
+ or "sheet-cell" in str(raw.get("className", ""))
140
+ or "cg-cell" in str(raw.get("className", "")))
141
+ hops = raw.get("path", [])
142
+ if isinstance(hops, list):
143
+ protected = protected or any(
144
+ _text(hop).split(".")[0] in {"td", "th", "input", "textarea", "option", "canvas"}
145
+ or re.search(r"\.(?:sheet|cg)-cell(?:\.|$)", _text(hop))
146
+ for hop in hops[:5])
147
+ path = []
148
+ for hop in hops[:5]:
149
+ parts = _text(hop).split(".")
150
+ if parts[0] in _TAGS:
151
+ classes = _classes(" ".join(parts[1:])) if not protected else ""
152
+ path.append(parts[0] + ("." + classes.replace(" ", ".") if classes else ""))
153
+ result["path"] = path
154
+ if protected:
155
+ return result
156
+ classes = _classes(raw.get("className"))
157
+ if classes:
158
+ result["className"] = classes
159
+ for key in ("id", "name"):
160
+ val = _text(raw.get(key), 80)
161
+ if val == "root" or (_TOKEN.fullmatch(val) and _CLASS.fullmatch(val)):
162
+ result[key] = val
163
+ label = _text(raw.get("aria-label"))
164
+ if label in _LABELS:
165
+ result["aria-label"] = label
166
+ data = raw.get("data")
167
+ if isinstance(data, dict):
168
+ safe = {}
169
+ for key, val in list(data.items())[:MAX_DATA_ATTRIBUTES]:
170
+ if not isinstance(key, str) or not re.fullmatch(r"data-[a-z][a-z-]{0,47}", key):
171
+ continue
172
+ normalized = re.sub(r"[^a-z]", "", key[5:])
173
+ if any(word in normalized for word in SECRET_KEYS):
174
+ continue
175
+ val = _text(val)
176
+ if not val:
177
+ continue
178
+ safe[key] = val if val in _DATA_ENUMS.get(key, set()) else "present"
179
+ if safe:
180
+ result["data"] = safe
181
+ return result
182
+
183
+
184
+ def _key(value, target):
185
+ value = _text(value, 64)
186
+ parts = value.split("+")
187
+ key = parts[-1]
188
+ if any(part not in {"Control", "Alt", "Shift", "Meta"} for part in parts[:-1]):
189
+ return "Key"
190
+ named = {"Enter", "Escape", "Tab", "Backspace", "Delete", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown", "Control", "Alt", "Shift", "Meta", "CapsLock", "Space", "Character"}
191
+ if key not in named and not re.fullmatch(r"(?:[a-zA-Z0-9]|F(?:[1-9]|1[0-2]))", key):
192
+ return "Key"
193
+ editable = target.get("tagName") in {"input", "textarea", "option", "select"} or target.get("role") in {"textbox", "searchbox", "gridcell", "cell", "grid"}
194
+ shortcut = any(part in {"Control", "Meta"} for part in parts[:-1]) and "Alt" not in parts[:-1]
195
+ if editable and (len(key) == 1 or key == "Space") and not shortcut:
196
+ return "Character"
197
+ return value
198
+
199
+
200
+ def project_event(raw, now_ms, *, movement=False):
201
+ raw = _shape(raw)
202
+ kind = raw.get("kind")
203
+ allowed = {"hover", "scroll", "focus", "keypress", "pointer"} if movement else {"route", "click", "api", "error"}
204
+ if not isinstance(kind, str) or kind not in allowed:
205
+ return None
206
+ ts = _number(raw.get("ts"), now_ms, now_ms)
207
+ if ts < now_ms - RETENTION_DAYS * 86400_000:
208
+ return None
209
+ event = {"kind": kind, "ts": ts}
210
+ if movement or kind == "click":
211
+ event["target"] = _element(raw.get("target"))
212
+ if movement:
213
+ if kind in {"pointer", "scroll"}:
214
+ event.update({key: _number(raw.get(key), maximum=10**7) for key in ("x", "y")})
215
+ if kind == "keypress":
216
+ event["key"] = _key(raw.get("key"), event["target"])
217
+ return event
218
+ event["route"] = _path(raw.get("route"))
219
+ if kind == "route":
220
+ event.update({"from": _path(raw.get("from")), "to": _path(raw.get("to")), "ms": _number(raw.get("ms"))})
221
+ elif kind == "api":
222
+ method = _text(raw.get("method"), 16).upper()
223
+ event.update({"method": method if method in {"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"} else "OTHER",
224
+ "url": _path(raw.get("url")), "status": _number(raw.get("status"), maximum=599), "ms": _number(raw.get("ms"))})
225
+ elif kind == "error":
226
+ name = _text(raw.get("name"), 64)
227
+ message = _text(raw.get("message"))
228
+ event.update({"name": name if name in _ERROR_NAMES else "Error",
229
+ # Raw exception text often interpolates the offending cell.
230
+ "message": message if message in _MESSAGES else "Application error.",
231
+ "source": _path(raw.get("source")), "line": _number(raw.get("line"), maximum=10**7)})
232
+ samples = raw.get("movement")
233
+ samples = samples if isinstance(samples, list) else []
234
+ trail = [project_event(sample, now_ms, movement=True) for sample in samples[-MAX_MOVEMENT_SAMPLES:]]
235
+ event["movement"] = sorted([sample for sample in trail if sample and ts - MOVEMENT_WINDOW_MS <= sample["ts"] <= ts], key=lambda sample: sample["ts"])
236
+ event["movementDropped"] = _number(raw.get("movementDropped")) + len(samples) - len(event["movement"])
237
+ return event
238
+
239
+
240
+ def _limits():
241
+ return {"retentionDays": RETENTION_DAYS, "maxSessions": MAX_SESSIONS,
242
+ "maxEventsPerSession": MAX_EVENTS_PER_SESSION, "maxMovementSamples": MAX_MOVEMENT_SAMPLES,
243
+ "movementWindowSeconds": MOVEMENT_WINDOW_MS // 1000, "pageSize": MAX_PAGE_EVENTS}
244
+
245
+
246
+ def _retained(doc, tenant, now_ms):
247
+ if not isinstance(doc, dict) or not isinstance(doc.get("sessions"), list):
248
+ return []
249
+ cutoff = now_ms - RETENTION_DAYS * 86400_000
250
+ rows = [row for row in doc["sessions"] if isinstance(row, dict) and row.get("tenant") == tenant
251
+ and isinstance(row.get("events"), list) and _number(row.get("endedAt")) >= cutoff]
252
+ retained = []
253
+ for row in rows:
254
+ events = [event for event in row["events"] if isinstance(event, dict) and _number(event.get("ts")) >= cutoff]
255
+ if events:
256
+ retained.append({**row, "events": events[-MAX_EVENTS_PER_SESSION:]})
257
+ return sorted(retained, key=lambda row: row["endedAt"])[-MAX_SESSIONS:]
258
+
259
+
260
+ def _record(session, session_id, events, dropped, now_ms):
261
+ from harness import runtime
262
+
263
+ def _append(doc):
264
+ rows = _retained(doc, session.tenant, now_ms)
265
+ row = next((item for item in rows if item["sessionId"] == session_id and item["user"] == session.uname), None)
266
+ if row is None:
267
+ row = {"sessionId": session_id, "user": session.uname, "tenant": session.tenant,
268
+ "startedAt": min(event["ts"] for event in events), "endedAt": now_ms,
269
+ "route": next((event.get("to") or event.get("route") for event in events if event.get("to") or event.get("route")), "/"),
270
+ "events": [], "dropped": 0, "prunedEvents": 0}
271
+ rows.append(row)
272
+ merged = sorted(row["events"] + events, key=lambda event: event["ts"])
273
+ if merged[0]["ts"] < row["startedAt"]:
274
+ row["route"] = merged[0].get("to") or merged[0].get("route") or "/"
275
+ row["startedAt"] = min(row["startedAt"], merged[0]["ts"])
276
+ row["endedAt"] = merged[-1]["ts"]
277
+ row["prunedEvents"] += max(0, len(merged) - MAX_EVENTS_PER_SESSION)
278
+ row["dropped"] += dropped
279
+ row["events"] = merged[-MAX_EVENTS_PER_SESSION:]
280
+ return {"sessions": sorted(rows, key=lambda item: item["endedAt"])[-MAX_SESSIONS:]}
281
+
282
+ # Async coalescing avoids blocking uploads and one HF commit per batch.
283
+ # A container loss before the worker flushes may lose cached telemetry.
284
+ runtime.get_runtime(str(session.tenant)).update(BUCKET, _append, flush="async")
285
+ # platform/ is available after session resolution, not necessarily at import.
286
+ try:
287
+ from harness.telemetry import error as telemetry_error
288
+ except ImportError:
289
+ return
290
+ for event in events:
291
+ if event["kind"] == "error":
292
+ try:
293
+ # This is the existing diagnostic sink, not a second activity store.
294
+ # Never forward exc, the incoming payload, or the movement snapshot.
295
+ telemetry_error("activity", name=event["name"], message=event["message"],
296
+ source=event["source"], line=event["line"])
297
+ except Exception:
298
+ pass
299
+
300
+
301
+ def _batch(body):
302
+ events = body.get("events")
303
+ session_id = _text(body.get("sessionId"), 80)
304
+ if not _SID.fullmatch(session_id) or not isinstance(events, list):
305
+ raise ActivityRefused("activity_invalid", "Activity requires a tab session and an event list.")
306
+ if len(events) > MAX_BATCH_EVENTS:
307
+ raise ActivityRefused("activity_batch_too_large", f"Activity batches must contain at most {MAX_BATCH_EVENTS} events.")
308
+ return session_id, events
309
+
310
+
311
+ @router.post("/api/v1/activity")
312
+ async def ingest_activity(request: Request, session: Session = Depends(require_session)):
313
+ data = bytearray()
314
+ async for chunk in request.stream():
315
+ if len(data) + len(chunk) > MAX_PAYLOAD_BYTES:
316
+ raise err(400, "activity_payload_too_large", f"Activity batches must be at most {MAX_PAYLOAD_BYTES} bytes.")
317
+ data.extend(chunk)
318
+ try:
319
+ body = _shape(json.loads(data))
320
+ except (ValueError, UnicodeError, RecursionError):
321
+ raise err(400, "activity_invalid", "Activity requires a valid JSON object.") from None
322
+ try:
323
+ session_id, events = _batch(body)
324
+ except ActivityRefused as exc:
325
+ raise err(400, exc.code, exc.message) from None
326
+ now_ms = round(time.time() * 1000)
327
+ clean = []
328
+ for raw in events:
329
+ event = project_event(raw, now_ms)
330
+ if event is not None:
331
+ clean.append({**event, "eventId": uuid.uuid4().hex})
332
+ dropped = len(events) - len(clean)
333
+ clean.sort(key=lambda event: event["ts"])
334
+ if clean:
335
+ try:
336
+ await run_in_threadpool(_record, session, session_id, clean,
337
+ _number(body.get("dropped")) + dropped, now_ms)
338
+ except Exception:
339
+ raise err(503, "activity_unavailable", "Activity could not be saved.") from None
340
+ return {"accepted": len(clean), "dropped": dropped}
341
+
342
+
343
+ def _user(session, requested):
344
+ if requested is not None and requested != session.uname and not session.admin:
345
+ raise err(403, "activity_forbidden", "You can only view your own activity.")
346
+ return session.uname if requested is None else requested
347
+
348
+
349
+ def _read(session):
350
+ from harness import runtime
351
+ try:
352
+ return _retained(runtime.get_runtime(str(session.tenant)).get(BUCKET), session.tenant, round(time.time() * 1000))
353
+ except Exception:
354
+ raise err(503, "activity_unavailable", "Activity could not be loaded.") from None
355
+
356
+
357
+ @router.get("/api/v1/activity/sessions")
358
+ def activity_sessions(user: str | None = None, session: Session = Depends(require_session)):
359
+ owner = _user(session, user)
360
+ rows = []
361
+ for row in reversed(_read(session)):
362
+ if row["user"] == owner:
363
+ rows.append({key: row[key] for key in ("sessionId", "startedAt", "endedAt", "route", "dropped", "prunedEvents")})
364
+ rows[-1].update(events=len(row["events"]), errors=sum(event["kind"] == "error" for event in row["events"]))
365
+ return {"sessions": rows, "limits": _limits()}
366
+
367
+
368
+ @router.get("/api/v1/activity/sessions/{session_id}")
369
+ def activity_session(session_id: str, user: str | None = None,
370
+ limit: int = Query(MAX_PAGE_EVENTS, ge=1, le=MAX_PAGE_EVENTS),
371
+ offset: int = Query(0, ge=0), session: Session = Depends(require_session)):
372
+ owner = _user(session, user)
373
+ row = next((item for item in _read(session) if item["user"] == owner and item["sessionId"] == session_id), None)
374
+ if row is None:
375
+ raise err(404, "activity_session_missing", "This activity session is no longer available.")
376
+ # Re-project the displayed slice as defense against a legacy or corrupt document.
377
+ now_ms = round(time.time() * 1000)
378
+ events = []
379
+ for raw in row["events"][offset:offset + limit]:
380
+ clean = project_event(raw, now_ms)
381
+ if clean:
382
+ events.append({**clean, "eventId": _text(raw.get("eventId"), 36)})
383
+ return {"sessionId": session_id, "events": events, "total": len(row["events"]),
384
+ "offset": offset, "limit": limit, "dropped": row["dropped"],
385
+ "prunedEvents": row["prunedEvents"], "limits": _limits()}
386
+
387
+
388
+ @router.get("/api/v1/activity/users")
389
+ def activity_users(session: Session = Depends(require_session)):
390
+ if not session.admin:
391
+ raise err(403, "activity_forbidden", "Only administrators can view other users' activity.")
392
+ return {"users": sorted({row["user"] for row in _read(session)})}
api/routes_applications.py CHANGED
@@ -1,15 +1,23 @@
1
  """Permissioned, directly addressable Finance application contracts (S63-T16)."""
2
- from fastapi import APIRouter, Depends, Query
3
 
4
  import application_registry
5
  from deps import Session, err, require_session
6
  from harness import runtime as mirror_runtime
7
  from modules import finance_spine
8
  from pages import resolve_bu
 
 
9
 
10
 
11
  finance_router = APIRouter(prefix="/api/v1/finance", tags=["finance"])
12
  nav_router = APIRouter(prefix="/api/v1", tags=["applications"])
 
 
 
 
 
 
13
 
14
 
15
  def _may_open(session, permission_key):
@@ -138,8 +146,113 @@ def list_nav_applications(session: Session = Depends(require_session)):
138
  may_open=lambda permission: _may_open(session, permission))}
139
 
140
 
141
- # main.py includes exactly one object named router. These two sub-routers keep
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
142
  # /nav/applications outside the Finance prefix while every Finance URL stays unchanged.
143
  router = APIRouter()
144
  router.include_router(finance_router)
145
  router.include_router(nav_router)
 
 
 
 
1
  """Permissioned, directly addressable Finance application contracts (S63-T16)."""
2
+ from fastapi import APIRouter, Body, Depends, Query
3
 
4
  import application_registry
5
  from deps import Session, err, require_session
6
  from harness import runtime as mirror_runtime
7
  from modules import finance_spine
8
  from pages import resolve_bu
9
+ from routes_activity import router as activity_router
10
+ from routes_statements import _gate as statement_gate
11
 
12
 
13
  finance_router = APIRouter(prefix="/api/v1/finance", tags=["finance"])
14
  nav_router = APIRouter(prefix="/api/v1", tags=["applications"])
15
+ # ⛔ NO `prefix=` HERE, for the same reason S65-T16 spelled full paths on `routes_activity`:
16
+ # this router is included INSIDE this module's own `router`, and a child router carrying
17
+ # `prefix=` has that prefix baked into its `.routes` at DECLARATION time, so
18
+ # `verify_api.py::_mounted_paths` adds it a SECOND time and D-48 reads a route the app really
19
+ # serves as one it does not. The full path on each decorator is also the honest reading.
20
+ collection_router = APIRouter(tags=["collection"], dependencies=[Depends(require_session)])
21
 
22
 
23
  def _may_open(session, permission_key):
 
146
  may_open=lambda permission: _may_open(session, permission))}
147
 
148
 
149
+ def _collection_ids(body, *, confirm=False):
150
+ body = body or {}
151
+ if confirm and body.get("confirm") is not True:
152
+ raise err(400, "collection_confirmation_required", "Confirm the whole batch before sending.")
153
+ allowed = {"partnerIds", "confirm"} if confirm else {"partnerIds"}
154
+ if set(body) - allowed:
155
+ raise err(400, "collection_request_invalid", "Only customer identifiers are accepted.")
156
+ ids = body.get("partnerIds")
157
+ if not isinstance(ids, list) or not ids:
158
+ raise err(400, "collection_selection_required", "Select at least one customer.")
159
+ if any(type(pid) is not int or pid <= 0 for pid in ids):
160
+ raise err(400, "collection_selection_invalid", "Customer identifiers must be positive integers.")
161
+ return list(dict.fromkeys(ids))
162
+
163
+
164
+ def _collection_source(cs):
165
+ try:
166
+ odoo = cs.Odoo()
167
+ return odoo, cs.load_collection_list(odoo)
168
+ except Exception:
169
+ raise err(502, "collection_odoo_unavailable", "The Collection worklist could not be read from Odoo.")
170
+
171
+
172
+ def _collection_selection(rows, ids):
173
+ by_id = {row["partner_id"]: row for row in rows}
174
+ selected = [by_id[pid] for pid in ids if pid in by_id]
175
+ refused = [{"customer": f"Customer {pid}", "partnerId": pid,
176
+ "reason": "This customer is no longer on the Collection worklist."}
177
+ for pid in ids if pid not in by_id]
178
+ return selected, refused
179
+
180
+
181
+ def _collection_refusal(cs, row):
182
+ """Preview the existing data-layer guard; the sender still enforces it independently."""
183
+ if not row.get("Email"):
184
+ return "No email address is saved for this customer."
185
+ if not cs.safe_recipient_ok(row["Email"]):
186
+ return "Safe mode does not allow this recipient address."
187
+ return None
188
+
189
+
190
+ @collection_router.get("/api/v1/apps/collection/worklist")
191
+ def collection_worklist(session: Session = Depends(statement_gate)):
192
+ import modules.collections_send as cs
193
+ _, rows = _collection_source(cs)
194
+ public = []
195
+ for row in rows:
196
+ docs = row.get("_docs") or []
197
+ public.append({**{key: value for key, value in row.items() if key != "_docs"},
198
+ "_docs": len(docs),
199
+ "documents": [{"name": doc["name"],
200
+ "date": doc.get("invoice_date") or None,
201
+ "dueDate": doc.get("invoice_date_due") or None,
202
+ "daysOverdue": doc["days_overdue"],
203
+ "openBalance": doc["open_signed"]} for doc in docs],
204
+ "sendRefusal": _collection_refusal(cs, row)})
205
+ return {"rows": public, "safeMode": bool(cs.SAFE_MODE),
206
+ "safeRecipients": sorted(cs.SAFE_RECIPIENTS),
207
+ "sender": {"name": cs.SENDER_NAME, "email": cs.SENDER_EMAIL, "replyTo": cs.REPLY_TO}}
208
+
209
+
210
+ @collection_router.post("/api/v1/apps/collection/preview")
211
+ def collection_preview(body: dict = Body(default=None), session: Session = Depends(statement_gate)):
212
+ """Read-only rendered statements, using the same defaults the batch will queue."""
213
+ import datetime as dt
214
+ import modules.collections_send as cs
215
+ ids = _collection_ids(body)
216
+ _, rows = _collection_source(cs)
217
+ selected, refused = _collection_selection(rows, ids)
218
+ statements = []
219
+ for row in selected:
220
+ reason = _collection_refusal(cs, row)
221
+ if reason:
222
+ refused.append({"customer": row["Customer"], "reason": reason})
223
+ statements.append({"partnerId": row["partner_id"], "customer": row["Customer"],
224
+ "to": row["Email"], "refusal": reason,
225
+ "subject": cs.DEFAULT_SUBJECT.format(
226
+ customer=row["Customer"], company=cs.COMPANY,
227
+ month=dt.date.today().strftime("%B %Y")),
228
+ "html": cs.render_statement_html(row)})
229
+ return {"statements": statements, "refused": refused, "requested": len(ids),
230
+ "safeMode": bool(cs.SAFE_MODE), "safeRecipients": sorted(cs.SAFE_RECIPIENTS),
231
+ "sender": {"name": cs.SENDER_NAME, "email": cs.SENDER_EMAIL, "replyTo": cs.REPLY_TO}}
232
+
233
+
234
+ @collection_router.post("/api/v1/apps/collection/send")
235
+ def collection_send(body: dict = Body(default=None), session: Session = Depends(statement_gate)):
236
+ import modules.collections_send as cs
237
+ ids = _collection_ids(body, confirm=True)
238
+ odoo, rows = _collection_source(cs)
239
+ selected, refused = _collection_selection(rows, ids)
240
+ try:
241
+ result = cs.queue_statement_batch(odoo, selected)
242
+ except Exception:
243
+ # An interrupted response may follow a successful create. Never invite a blind retry.
244
+ raise err(502, "collection_send_unconfirmed",
245
+ "Odoo did not confirm the batch result. Some statements may already be in the "
246
+ "outbox. Check Odoo before trying again.")
247
+ return {"created": len(result["created"]), "refused": refused + result["refused"],
248
+ "safeMode": result["safe_mode"]}
249
+
250
+
251
+ # main.py includes exactly one object named router. These sub-routers keep
252
  # /nav/applications outside the Finance prefix while every Finance URL stays unchanged.
253
  router = APIRouter()
254
  router.include_router(finance_router)
255
  router.include_router(nav_router)
256
+ # main.py belongs to another session this wave; this router is already mounted there.
257
+ router.include_router(activity_router)
258
+ router.include_router(collection_router)
api/routes_odoo_tables.py CHANGED
@@ -592,6 +592,7 @@ GRID_SOURCES = {}
592
  #: ⚠ A provider registers a CALLABLE, not a dict, so its module is not imported until the first
593
  #: read — the same lazy rule `_sources` already follows for `odoo_relational`.
594
  _SOURCE_PROVIDERS = []
 
595
 
596
 
597
  def register_source_provider(fn):
@@ -605,6 +606,25 @@ def register_source_provider(fn):
605
  return len(_SOURCE_PROVIDERS)
606
 
607
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
608
  def _sources():
609
  """Build `GRID_SOURCES` lazily by asking EVERY registered provider — Odoo is one of them.
610
 
@@ -976,10 +996,24 @@ def _odoo_sources():
976
  return GRID_SOURCES
977
 
978
 
 
 
 
 
 
 
 
 
 
 
 
 
 
979
  #: Odoo registers itself, at import, exactly as any other connector does. ⚠ The order providers
980
  #: are registered in is the order their specs land; keys are namespaced by connector (`ut_odoo_`,
981
  #: `ut_meta_`), so a later provider cannot shadow an earlier one's grid.
982
  register_source_provider(_odoo_sources)
 
983
 
984
 
985
  def sync_read_through(cur=None):
@@ -989,7 +1023,7 @@ def sync_read_through(cur=None):
989
  registration is additive and `strip_materialised` is a no-op once a table is empty.
990
 
991
  ⛔ IT IS ALSO THE ONLY PLACE THAT MAY CALL `register_read_through`, because the eligibility
992
- question needs BOTH halves — `odoo_relational`'s field declarations (for the fold matrix) and
993
  the mirror (for the size) — and `core` may import neither.
994
  """
995
  eligible, reasons = _unmaterialisable(cur)
@@ -1081,7 +1115,7 @@ def _unmaterialisable(cur=None):
1081
 
1082
  ⛔ SIZE FORCES READ-THROUGH; IT NEVER BLOCKS IT — and getting that backwards was a real bug in
1083
  the first cut of this function. A table too big for the tenant document has NO materialised
1084
- option at all, so making it ineligible would have handed `odoo_relational.plan` a `row_limit`
1085
  of None and invited it to build 963,783 python dicts. The window ceiling is a different, much
1086
  softer thing: it only limits what the whole-table CLIENT door can serve today.
1087
 
@@ -1093,19 +1127,42 @@ def _unmaterialisable(cur=None):
1093
  ⚠ Without a mirror cursor the size questions cannot be asked, so only a grid that was never
1094
  part of the materialised spawn is eligible — a table is never freed by a question we skipped.
1095
  """
1096
- rel = _rel()
1097
- folds, eligible, reasons = _fold_reasons(rel), {}, {}
1098
- # ⛔ "WAS THIS PART OF THE MATERIALISED SPAWN?", and being in `TABLES` STOPPED ANSWERING IT.
1099
- # W30-T35 declared the two line grains, which have no python row builder anywhere — their
1100
- # absence from `_READERS` IS that statement — so a table the spawn could never materialise
1101
- # started reading as spawned, and on a mirror-less deployment fell through to "its size could
1102
- # not be read" and came back INELIGIBLE. That inverts this function's own first law (size
1103
- # forces read-through; it never blocks it). Ask the question through the reader map, which is
1104
- # what actually decides whether a row could ever have been built.
1105
- spawned = {key for _b, key, _l, _f in rel.TABLES if _b in getattr(rel, "_READERS", {})}
1106
  from harness import datastore
1107
  ut = _ut()
1108
- for key, spec in _sources().items():
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1109
  total = None
1110
  if cur is not None:
1111
  try:
@@ -1115,7 +1172,7 @@ def _unmaterialisable(cur=None):
1115
  order_by=spec["id"], limit=1, cur=cur, **frm)["total"]
1116
  except Exception: # noqa: BLE001
1117
  total = None
1118
- if total is not None and total > ut.MAX_ROWS:
1119
  eligible[key] = True # no other home exists; this is not a choice
1120
  continue
1121
  if total is None and key not in spawned:
@@ -1126,8 +1183,8 @@ def _unmaterialisable(cur=None):
1126
  why.append("its size could not be read from the mirror on this deployment")
1127
  if key in folds:
1128
  why.append(folds[key])
1129
- if total is not None and total > datastore.WINDOW_MAX:
1130
- why.append(f"its {total:,} rows exceed the {datastore.WINDOW_MAX:,}-row window and "
1131
  f"the grid client still asks for whole tables, so un-materialising it "
1132
  f"today could only truncate")
1133
  eligible[key] = not why
 
592
  #: ⚠ A provider registers a CALLABLE, not a dict, so its module is not imported until the first
593
  #: read — the same lazy rule `_sources` already follows for `odoo_relational`.
594
  _SOURCE_PROVIDERS = []
595
+ _SOURCE_ANALYSES = {}
596
 
597
 
598
  def register_source_provider(fn):
 
606
  return len(_SOURCE_PROVIDERS)
607
 
608
 
609
+ def register_source_analysis(source_key, *, folds, spawned):
610
+ """Register lazy `() -> {table_key: reason}` and `() -> set[table_key]` analyses.
611
+
612
+ Source ids come from core.registry's policies. Re-registering replaces that source's pair
613
+ without adding another entry. Returns the number of sources whose analysis is now known.
614
+ """
615
+ if callable(folds) and callable(spawned):
616
+ _SOURCE_ANALYSES[source_key] = {"folds": folds, "spawned": spawned}
617
+ return len(_SOURCE_ANALYSES)
618
+
619
+
620
+ def _source_analysis(source_key):
621
+ """Resolve one source's analysis lazily; an unregistered source has two empty results."""
622
+ analysis = _SOURCE_ANALYSES.get(source_key)
623
+ if analysis is None:
624
+ return {}, set()
625
+ return analysis["folds"](), analysis["spawned"]()
626
+
627
+
628
  def _sources():
629
  """Build `GRID_SOURCES` lazily by asking EVERY registered provider — Odoo is one of them.
630
 
 
996
  return GRID_SOURCES
997
 
998
 
999
+ def _odoo_spawned():
1000
+ """The Odoo grains that have a materialised row builder."""
1001
+ rel = _rel()
1002
+ # ⛔ "WAS THIS PART OF THE MATERIALISED SPAWN?", and being in `TABLES` STOPPED ANSWERING IT.
1003
+ # W30-T35 declared the two line grains, which have no python row builder anywhere — their
1004
+ # absence from `_READERS` IS that statement — so a table the spawn could never materialise
1005
+ # started reading as spawned, and on a mirror-less deployment fell through to "its size could
1006
+ # not be read" and came back INELIGIBLE. That inverts eligibility's first law (size
1007
+ # forces read-through; it never blocks it). Ask the question through the reader map, which is
1008
+ # what actually decides whether a row could ever have been built.
1009
+ return {key for _b, key, _l, _f in rel.TABLES if _b in getattr(rel, "_READERS", {})}
1010
+
1011
+
1012
  #: Odoo registers itself, at import, exactly as any other connector does. ⚠ The order providers
1013
  #: are registered in is the order their specs land; keys are namespaced by connector (`ut_odoo_`,
1014
  #: `ut_meta_`), so a later provider cannot shadow an earlier one's grid.
1015
  register_source_provider(_odoo_sources)
1016
+ register_source_analysis("odoo", folds=lambda: _fold_reasons(_rel()), spawned=_odoo_spawned)
1017
 
1018
 
1019
  def sync_read_through(cur=None):
 
1023
  registration is additive and `strip_materialised` is a no-op once a table is empty.
1024
 
1025
  ⛔ IT IS ALSO THE ONLY PLACE THAT MAY CALL `register_read_through`, because the eligibility
1026
+ question needs BOTH halves — the source's registered analysis (for the fold matrix) and
1027
  the mirror (for the size) — and `core` may import neither.
1028
  """
1029
  eligible, reasons = _unmaterialisable(cur)
 
1115
 
1116
  ⛔ SIZE FORCES READ-THROUGH; IT NEVER BLOCKS IT — and getting that backwards was a real bug in
1117
  the first cut of this function. A table too big for the tenant document has NO materialised
1118
+ option at all, so making it ineligible would have handed the materialisation plan a `row_limit`
1119
  of None and invited it to build 963,783 python dicts. The window ceiling is a different, much
1120
  softer thing: it only limits what the whole-table CLIENT door can serve today.
1121
 
 
1127
  ⚠ Without a mirror cursor the size questions cannot be asked, so only a grid that was never
1128
  part of the materialised spawn is eligible — a table is never freed by a question we skipped.
1129
  """
1130
+ from core import registry
 
 
 
 
 
 
 
 
 
1131
  from harness import datastore
1132
  ut = _ut()
1133
+ analyses, eligible, reasons = {}, {}, {}
1134
+ candidates = dict(_sources())
1135
+ if any(policy["candidates"] == "prefix" for policy in registry.source_policies()):
1136
+ # ⚠ Every declared policy is "declared" today, so this walk does not run. It is here so a
1137
+ # source CAN opt in without editing this branch, which is the ticket. The store read is
1138
+ # guarded because a policy is a declaration and a missing store is not its problem.
1139
+ try:
1140
+ owned = list(ut.all_defs() or {})
1141
+ except Exception: # noqa: BLE001
1142
+ owned = []
1143
+ for key in owned:
1144
+ if registry.source_policy(key)["candidates"] == "prefix":
1145
+ candidates.setdefault(key, {})
1146
+ for key, spec in candidates.items():
1147
+ policy = registry.source_policy(key)
1148
+ max_rows = policy["max_rows"] if policy["max_rows"] is not None else ut.MAX_ROWS
1149
+ window_max = (policy["window_max"] if policy["window_max"] is not None
1150
+ else datastore.WINDOW_MAX)
1151
+ source_key = policy["key"]
1152
+ if source_key not in analyses:
1153
+ analyses[source_key] = _source_analysis(source_key)
1154
+ folds, spawned = analyses[source_key]
1155
+ # ⛔ A CANDIDATE WITH NO SPEC CANNOT BE JUDGED, AND MUST THEREFORE BE REFUSED, NOT FREED.
1156
+ # A `candidates: "prefix"` source contributes keys its provider never described, so the
1157
+ # size question below has nothing to ask. Falling through would reach the `total is None
1158
+ # and key not in spawned` arm and hand back ELIGIBLE, un-materialising a database whose
1159
+ # size was never read - the exact inversion of this function's first law, arrived at by
1160
+ # an absence rather than a decision. [S65-T13]
1161
+ if not (spec.get("table") or spec.get("from_sql")):
1162
+ eligible[key] = False
1163
+ reasons[key] = ("its source declares no read-through binding, so its size cannot be "
1164
+ "read and un-materialising it would be a guess")
1165
+ continue
1166
  total = None
1167
  if cur is not None:
1168
  try:
 
1172
  order_by=spec["id"], limit=1, cur=cur, **frm)["total"]
1173
  except Exception: # noqa: BLE001
1174
  total = None
1175
+ if total is not None and total > max_rows:
1176
  eligible[key] = True # no other home exists; this is not a choice
1177
  continue
1178
  if total is None and key not in spawned:
 
1183
  why.append("its size could not be read from the mirror on this deployment")
1184
  if key in folds:
1185
  why.append(folds[key])
1186
+ if total is not None and total > window_max:
1187
+ why.append(f"its {total:,} rows exceed the {window_max:,}-row window and "
1188
  f"the grid client still asks for whole tables, so un-materialising it "
1189
  f"today could only truncate")
1190
  eligible[key] = not why
api/routes_sheet.py CHANGED
@@ -975,7 +975,36 @@ def _binding_scope_key(session: Session, database: str, binding: dict) -> str:
975
  import core.perm_scope as perm_scope
976
  wall_tree = ((perm_scope.entry(session.user, database) or {}).get("filter")
977
  if perm_scope.row_scope_applies(session.user, database) else None)
978
- return sheets.scope_hash(database, wall_tree, (binding or {}).get("scope") or {})
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
979
 
980
 
981
  def _has_ending(binding):
@@ -989,128 +1018,92 @@ def _has_cell_inputs(binding):
989
  return True
990
  scope = binding.get("scope") if isinstance(binding, dict) else None
991
  nodes, _ = _fe_parts(scope.get("filter") if isinstance(scope, dict) else None)
 
 
 
992
  # Linked values and related-table grants can change independently of the orders' cache key.
993
  if sheet_mod.linked_filter_ids(nodes):
994
  return True
995
  return any(sheet_mod.filter_cell_nodes(nodes))
996
 
997
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
998
  def _reresolved_for_reader(session: Session, book, *, endings_only=False):
999
- """A COPY of `book` whose every bound cell was recomputed under THIS reader's scope (C5).
1000
-
1001
- ⛔⛔ IN MEMORY, AND IT MUST NEVER PERSIST. `refresh_sheet` runs the same loop and ends with
1002
- `put_workbook`, and a read path that copied that body would write the READER's numbers into
1003
- the OWNER's document: the same leak as serving stale owner values, in the opposite direction,
1004
- caused by a GET, and therefore reachable by anybody the workbook was shared with. So this
1005
- works on a `copy.deepcopy` and returns it without saving the reader's workbook values.
1006
- R10 may create a missing Metric field through the database's ordinary field writer.
1007
-
1008
- ⭐ THE WALL RUNS ONCE PER DISTINCT DATABASE, exactly as `refresh_sheet` does (R16): a reader
1009
- who has lost access to a bound database is refused on every cell of it rather than shown the
1010
- owner's cached number.
1011
-
1012
- ⚠ `refreshedFor` IS STAMPED ONLY WHEN A BOUND CELL WAS ACTUALLY RECOMPUTED. A workbook of
1013
- literals has nothing to re-resolve, and a stamp there would be a claim with nothing behind it.
1014
-
1015
- ⭐⭐ W52-T12 / R3: A CACHE HIT SKIPS `_resolve_binding` ENTIRELY, AND A MISS FILLS ONLY THE
1016
- CALLER'S OWN SLOT. The cache lives in a document `core.sheets` owns and keys by
1017
- `(database, wall, binding scope)` (`_binding_scope_key`), never by user id or role name, so
1018
- two readers who share a row restriction share an answer and a reader whose restriction differs
1019
- never reads the other's slot. Only `refresh_sheet` may ever clear it; a GET here only ever
1020
- fills the ONE slot the caller themselves is entitled to.
1021
- """
1022
- from core import sheets
1023
- import copy as _copy
1024
- fresh = _copy.deepcopy(book)
1025
- stamp = _now_iso()
1026
- seen_db = {}
1027
- # ⭐ The same per-request memo as `refresh_sheet`, for the same reason and with the same
1028
- # lifetime: this loop resolves cell by cell too, and a reader's GET must not rebuild one
1029
- # database's workspace assembly once per bound cell.
1030
- view_memo = {}
1031
- touched = 0
1032
- store = _store(session)
1033
- wid = book.get("id") or ""
1034
- for tab in fresh.get("sheets") or ():
1035
- tab_ref = str(tab.get("id") or tab.get("name") or "")
1036
  for addr, cell in (tab.get("cells") or {}).items():
1037
- if not isinstance(cell, dict) or cell.get("kind") != "bound":
1038
  continue
1039
- if endings_only and not _has_cell_inputs(cell.get("binding")):
1040
  continue
1041
- touched += 1
1042
  binding = cell.get("binding") or {}
1043
  db = str(binding.get("database") or "")
1044
- if db not in seen_db:
1045
  try:
1046
  _require_database(session, db)
1047
- seen_db[db] = None
1048
- except Exception as exc: # noqa: BLE001
1049
- seen_db[db] = exc
1050
- failure = seen_db.get(db)
1051
- if failure is not None:
1052
- cell.update(_binding_refusal("database_unreadable", f"You cannot read {db}."))
1053
- cell.pop("limits", None)
1054
- continue
1055
-
1056
- cell_key = tab_ref + "!" + addr
1057
- scope_key = _binding_scope_key(session, db, binding)
1058
- hit = None
1059
- if wid and scope_key and not _has_cell_inputs(binding):
1060
- try:
1061
- hit = sheets.cached_scope_value(store, wid, cell_key, scope_key)
1062
- except Exception: # noqa: BLE001
1063
- hit = None
1064
- if hit is not None:
1065
- cell["state"] = "fresh"
1066
- cell["value"] = hit.get("value")
1067
- cell["display"] = "" if hit.get("value") is None else str(hit.get("value"))
1068
- cell["refreshed_at"] = hit.get("refreshedAt")
1069
- cell.pop("refusal", None)
1070
- #: ⚠ NOT CLAIMED ON A CACHE HIT: `limits` describes THIS resolve's own truncation,
1071
- #: and a cached slot never recorded one, so a prior (possibly stale) value on the
1072
- #: cell is dropped rather than shown as if it described the answer just served.
1073
- cell.pop("limits", None)
1074
- continue
1075
-
1076
- try:
1077
- out = _resolve_cell_binding(session, binding, fresh, tab_ref, view_memo=view_memo)
1078
- except HTTPException as exc:
1079
- detail = getattr(exc, "detail", None) or {}
1080
- info = detail.get("error") if isinstance(detail, dict) else None
1081
- cell.update(_binding_refusal(
1082
- (info or {}).get("code", "sheet_unresolved"),
1083
- (info or {}).get("message", "This cell could not be refreshed."),
1084
- ))
1085
- cell.pop("limits", None)
1086
- continue
1087
- cell["state"] = "fresh"
1088
- cell["value"] = out["value"]
1089
- cell["display"] = "" if out["value"] is None else str(out["value"])
1090
- cell["refreshed_at"] = stamp
1091
- cell.pop("refusal", None)
1092
- if out["limits"]:
1093
- cell["limits"] = out["limits"]
1094
  else:
1095
- cell.pop("limits", None)
1096
- #: ⚠ FILLED AFTER THE CELL ABOVE IS DONE READING `out`, and best effort: a cache-write
1097
- #: failure only costs a future recompute, never a wrong number, so it never raises past
1098
- #: here.
1099
- if wid and scope_key:
1100
- try:
1101
- sheets.fill_scope_cache(store, wid, cell_key, scope_key, out["value"], stamp,
1102
- out["database"])
1103
- except Exception: # noqa: BLE001
1104
- pass
1105
- if not touched:
1106
- return fresh
1107
- # ⭐ EVERY FORMULA IS RE-EVALUATED TOO, over the numbers this reader is entitled to. Leaving
1108
- # them alone would serve the owner's totals sitting on top of the reader's inputs, which is
1109
- # the leak this whole function exists to close, one layer up.
1110
- from modules import sheet as sheet_mod
1111
- import formula_runtime as fr
1112
- _recompute_formulas(fresh, fr, sheet_mod)
1113
- fresh["refreshedFor"] = str(session.uname or "")
1114
  return fresh
1115
 
1116
 
@@ -1122,17 +1115,12 @@ def _response_workbook(book):
1122
 
1123
 
1124
  def _read_for(session: Session, book):
1125
- """The workbook this session is entitled to see: stored for the owner, re-resolved otherwise.
1126
 
1127
  W60-T09, 2026-09-14: R28 checks visibility before this projection. Admitted legacy readers
1128
- and grantees still receive their own scoped numbers, never the owner's cached numbers.
1129
  """
1130
  book = _response_workbook(book)
1131
- if _role_on_workbook(session, book) == "owner":
1132
- if any(_has_cell_inputs(cell.get("binding"))
1133
- for tab in book.get("sheets") or [] for cell in (tab.get("cells") or {}).values()):
1134
- return _reresolved_for_reader(session, book, endings_only=True)
1135
- return book
1136
  return _reresolved_for_reader(session, book)
1137
 
1138
 
@@ -1743,6 +1731,8 @@ def _recomputed_tab_cells(session: Session, workbook_id: str, tab_ref: str, *, c
1743
  cache_key=(session.tenant, session.uname, workbook_id), changes=edits)
1744
  # Date and filter-cell edits also change database totals. Recompute all readers, then formulas.
1745
  ending_cells = set()
 
 
1746
  for source in book.get("sheets") or []:
1747
  for addr, cell in (source.get("cells") or {}).items():
1748
  binding = cell.get("binding") or {}
@@ -1751,6 +1741,11 @@ def _recomputed_tab_cells(session: Session, workbook_id: str, tab_ref: str, *, c
1751
  try:
1752
  result = _resolve_cell_binding(session, binding, book, source.get("id"))
1753
  cell.update(value=result["value"], display="" if result["value"] is None else str(result["value"]), state="fresh")
 
 
 
 
 
1754
  cell.pop("refusal", None)
1755
  except HTTPException as exc:
1756
  info = ((exc.detail or {}).get("error") or {})
@@ -1759,7 +1754,16 @@ def _recomputed_tab_cells(session: Session, workbook_id: str, tab_ref: str, *, c
1759
  info.get("message", "The Ending date could not be read. Choose a valid date."),
1760
  ))
1761
  ending_cells.add((source.get("id"), addr))
 
 
 
 
 
1762
  if ending_cells:
 
 
 
 
1763
  _recompute_formulas(book, fr, sheet_mod)
1764
  found = sheets.find_tab(book, tab_ref)
1765
  out = {}
@@ -1935,112 +1939,212 @@ def unshare_sheet(workbook_id: str, who: str, session: Session = Depends(require
1935
 
1936
  @router.post("/sheets/{workbook_id}/refresh")
1937
  def refresh_sheet(workbook_id: str, session: Session = Depends(require_session)):
1938
- """R10: recompute every bound cell, then every formula, and restamp `refreshed_at`.
1939
-
1940
- ⭐ THE WALL RUNS PER DISTINCT DATABASE, ON OPEN, NOT ONLY PER CELL (R16). A workbook that binds
1941
- forty cells to one database asks once; a reader who has lost access to that database gets a
1942
- refusal on every one of its cells rather than a stale number quietly repainting.
1943
-
1944
- ⚠ Each distinct `view_id` is resolved ONCE, and as of the wave-53 follow-up to W53-T12 that
1945
- sentence is finally TRUE OF THE CODE. It was written of `seen_db`, which deduplicates the
1946
- DATABASE WALL and nothing else: the resolve underneath it ran per cell, so a forty-cell
1947
- workbook did forty `table_store.find_view` calls and forty legacy migrations with them.
1948
- `view_memo` below is the dedupe this sentence describes.
1949
-
1950
- ⛔⛔ C5 — THIS IS A WRITE DOOR, BECAUSE IT ENDS IN `put_workbook`, AND A VIEWER IS REFUSED
1951
- HERE FOR A REASON THAT IS NOT ABOUT PERMISSION TO SEE. A viewer whose refresh were allowed
1952
- would compute every bound cell under THEIR scope and then SAVE those numbers into the owner's
1953
- document, so a narrowly walled reader pressing Refresh would silently shrink the owner's
1954
- workbook. The reader's own re-resolve happens on the READ path, in memory, and never lands.
1955
- ⚠ An EDITOR still writes their own numbers here, which is what an edit grant means and is
1956
- booked as a residual rather than widened away.
1957
  """
1958
- from core import sheets
 
1959
  from modules import sheet as sheet_mod
1960
  import formula_runtime as fr
 
1961
 
 
 
1962
  try:
1963
- book = sheets.get_workbook(_store(session), workbook_id)
1964
- _require_editor(session, book)
1965
  except sheets.SheetRefusal as exc:
1966
  raise _refuse(exc)
1967
-
 
 
 
 
1968
  stamp = _now_iso()
1969
- seen_db = {}
1970
- # ⭐ ONE MEMO FOR THE WHOLE REFRESH, keyed `(database, view_id)`. `seen_db` deduplicates the
1971
- # WALL and never the scope, so forty cells on one saved view used to resolve that view forty
1972
- # times. See `_view_filter`: the second lookup behind it builds a workspace assembly, which is
1973
- # work no workbook should pay for per cell. Per REQUEST, never on the runtime: a view's filter
1974
- # may be edited between two refreshes and a longer lived cache would serve the old rows.
1975
- view_memo = {}
1976
- for tab in book.get("sheets") or ():
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1977
  for addr, cell in (tab.get("cells") or {}).items():
1978
- if not isinstance(cell, dict) or cell.get("kind") != "bound":
1979
  continue
1980
- if _is_view_binding(cell):
1981
- continue # C2: a placed view refreshes through its own door
1982
  binding = cell.get("binding") or {}
1983
  db = str(binding.get("database") or "")
1984
- if db not in seen_db:
1985
- try:
1986
- _require_database(session, db)
1987
- seen_db[db] = None
1988
- except Exception as exc: # noqa: BLE001
1989
- seen_db[db] = exc
1990
- failure = seen_db.get(db)
1991
- if failure is not None:
1992
- cell.update(_binding_refusal("database_unreadable", f"You cannot read {db}."))
1993
- cell.pop("limits", None)
1994
- continue
1995
  try:
1996
- out = _resolve_cell_binding(session, binding, book, tab.get("id"), view_memo=view_memo)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1997
  except HTTPException as exc:
1998
- detail = getattr(exc, "detail", None) or {}
1999
- info = detail.get("error") if isinstance(detail, dict) else None
2000
- cell.update(_binding_refusal(
2001
- (info or {}).get("code", "sheet_unresolved"),
2002
- (info or {}).get("message", "This cell could not be refreshed."),
2003
- ))
2004
- cell.pop("limits", None)
2005
- continue
2006
- cell["state"] = "fresh"
2007
- cell["value"] = out["value"]
2008
- cell["display"] = "" if out["value"] is None else str(out["value"])
2009
- cell["refreshed_at"] = stamp
2010
- cell.pop("refusal", None)
2011
- if out["limits"]:
2012
- cell["limits"] = out["limits"]
2013
- else:
2014
- cell.pop("limits", None)
 
 
 
 
 
 
 
 
 
 
 
 
 
2015
 
2016
- # ⭐⭐ R4 / A1: THE RECALC IS TIMED AND THE TIME IS SHOWN. The prototype measured 2.9 s as the
2017
- # FLOOR for the owner's 11,300 formulas (2.9 to 6.2 s observed), so a refresh is a wait a
2018
- # person notices, and a wait nobody explains reads as a hang. `recalc_ms` is what the client
2019
- # renders as "Recalculated in N.N s".
2020
- #
2021
- # ⚠ IT TIMES THE RECALC, NOT THE ROUTE. The bound-cell loop above is database work whose
2022
- # duration says nothing about the formula engine, and the save below is store work; folding
2023
- # either into this number would make the figure on the screen unable to answer the question it
2024
- # exists for, which is whether the ENGINE is inside A1's 5 s target.
2025
- from time import perf_counter
2026
  started = perf_counter()
2027
  _recompute_formulas(book, fr, sheet_mod)
2028
  recalc_ms = round((perf_counter() - started) * 1000.0, 1)
2029
- try:
2030
- # R19: book came from get_workbook; clamping on refresh would destroy imported widths.
2031
- saved = sheets.put_workbook(_store(session), workbook_id,
2032
- {"name": book.get("name"), "sheets": book.get("sheets"),
2033
- "refreshed_at": stamp, "rev": book.get("rev")},
2034
- actor=session.uname,
2035
- actor_name=session.user.get("name") or session.uname,
2036
- lossless=True)
2037
- except sheets.SheetRefusal as exc:
2038
- raise _refuse(exc)
2039
- # ⭐⭐ R3 / W52-T12: REFRESH IS THE ONE EVENT ALLOWED TO INVALIDATE A READER'S CACHED SCOPE
2040
- # VALUE, so it is the one door that clears the whole per-scope cache. Every reader's next GET
2041
- # recomputes once, under their own scope, and fills its own slot again from there.
2042
- sheets.clear_scope_cache(_store(session), workbook_id)
2043
- return {"workbook": _response_workbook(saved), "recalc_ms": recalc_ms}
 
2044
 
2045
 
2046
  def _now_iso():
@@ -2336,8 +2440,11 @@ def _read_binding_cell(session, ref, *, book=None, tab=None, today=None, seen=()
2336
  refuse("the cell or its sheet is missing or blank.")
2337
  if cell.get("kind") == "bound":
2338
  try:
2339
- value = _resolve_binding(session, cell.get("binding"), today=today,
2340
- book=book, tab=key.rpartition("!")[0], ending_seen=(*seen, key))["value"]
 
 
 
2341
  except HTTPException as exc:
2342
  reason = ((exc.detail or {}).get("error") or {}).get("message", "its source is refused.")
2343
  refuse(reason)
@@ -2365,8 +2472,11 @@ def _read_binding_cell(session, ref, *, book=None, tab=None, today=None, seen=()
2365
  for dependency in needed:
2366
  attempted.add(dependency)
2367
  try:
2368
- result = _resolve_binding(session, bound[dependency].get("binding"), today=today,
2369
- book=book, tab=dependency.rpartition("!")[0], ending_seen=(*seen, key, dependency))
 
 
 
2370
  changes[dependency] = {"value": result["value"]}
2371
  except HTTPException as exc:
2372
  info = ((exc.detail or {}).get("error") or {})
@@ -2437,6 +2547,116 @@ def _resolve_cell_binding(session, binding, book, tab, **kwargs):
2437
  return _resolve_binding(session, binding, **kwargs)
2438
 
2439
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2440
  def _resolve_binding(session: Session, raw_binding, *, today=None, view_memo=None,
2441
  book=None, tab=None, ending_seen=()):
2442
  """Evaluate ONE C2 binding and return `{value, limits, sql_columns}`.
@@ -2498,6 +2718,9 @@ def _resolve_binding(session: Session, raw_binding, *, today=None, view_memo=Non
2498
  if binding["aggregate"].get("field"):
2499
  needed.add(str(binding["aggregate"]["field"]))
2500
 
 
 
 
2501
  cur, spec, cols = _mirror(session)(database, metric_window=window, needed=needed)
2502
  cols = dict(cols)
2503
  scope_nodes = _linked_filter_scope(session, database, scope_nodes, cur, spec, cols, today=today)
@@ -2539,9 +2762,12 @@ def _resolve_binding(session: Session, raw_binding, *, today=None, view_memo=Non
2539
  # spec's column expressions; applying it a second time would double-count the exclusion and
2540
  # break every joined spec, whose partner column is `sol.order_partner_id` or `aml.partner_id`.
2541
  try:
 
 
 
2542
  sql, params, limits = sheet_mod.build_aggregate_query(
2543
  spec, binding, cols, scope_nodes=scope_nodes, scope_conj=scope_conj,
2544
- wall_nodes=wall_nodes, wall_conj=wall_conj, today=today)
2545
  except sheet_mod.SheetRefusal as exc:
2546
  raise err(400, exc.code, exc.message)
2547
  except ValueError:
@@ -2808,6 +3034,11 @@ def compute_cell(workbook_id: str, addr: str, body: dict = Body(default=None),
2808
  saved["refreshed_at"] = stamp
2809
  saved.pop("refusal", None)
2810
 
 
 
 
 
 
2811
  try:
2812
  landed = sheets.patch_cells(_store(session), workbook_id, tab_ref, {key: saved},
2813
  actor=session.uname,
@@ -2827,6 +3058,13 @@ def compute_cell(workbook_id: str, addr: str, body: dict = Body(default=None),
2827
  except Exception: # noqa: BLE001
2828
  pass
2829
 
 
 
 
 
 
 
 
2830
  wire = dict(saved)
2831
  #: ⚠ `limits` RIDES THE ANSWER AND IS NOT STORED, because `core.sheets.clean_cell` carries no
2832
  #: such key: it describes THIS resolve's truncation, not the cell.
@@ -3008,24 +3246,35 @@ def drill_cell(workbook_id: str, addr: str, session: Session = Depends(require_s
3008
  window = _ending_window(session, binding, book=book, tab=tab.get("id"))
3009
  except sheet_mod.SheetRefusal as exc:
3010
  raise err(400, exc.code, exc.message)
 
 
 
 
 
3011
  cur, spec, cols = _mirror(session)(
3012
  database, metric_window=window,
3013
- needed=(sheet_mod.filter_columns_named(scope_nodes)
3014
- | sheet_mod.filter_columns_named(wall_nodes)))
3015
  cols = dict(cols)
3016
  scope_nodes = _linked_filter_scope(session, database, scope_nodes, cur, spec, cols)
3017
 
3018
  try:
 
 
 
3019
  count_sql, count_params, limits = sheet_mod.build_aggregate_query(
3020
  spec, {"aggregate": {"fn": "count"}}, cols, scope_nodes=scope_nodes,
3021
- scope_conj=scope_conj, wall_nodes=wall_nodes, wall_conj=wall_conj)
 
 
 
3022
  except sheet_mod.SheetRefusal as exc:
3023
  raise err(400, exc.code, exc.message)
 
 
 
 
3024
  total = (cur.execute(count_sql, count_params).fetchone() or [0])[0]
3025
 
3026
- ids_sql, ids_params, _ = sheet_mod.build_ids_query(
3027
- spec, cols, scope_nodes=scope_nodes, scope_conj=scope_conj,
3028
- wall_nodes=wall_nodes, wall_conj=wall_conj)
3029
  record_ids = [int(r[0]) for r in cur.execute(ids_sql, ids_params).fetchall() if r and r[0]]
3030
 
3031
  out = {"database": database, "record_ids": record_ids, "count": int(total or 0),
 
975
  import core.perm_scope as perm_scope
976
  wall_tree = ((perm_scope.entry(session.user, database) or {}).get("filter")
977
  if perm_scope.row_scope_applies(session.user, database) else None)
978
+ from core.sheet_binding import fingerprint
979
+ # Compare effective access, including field grants. Equivalent callers may share a
980
+ # snapshot unless a personal workspace makes their database values caller-specific.
981
+ memo = getattr(session, "_sheet_scope_context", None)
982
+ if memo is None:
983
+ memo = session._sheet_scope_context = {}
984
+ if database not in memo:
985
+ from core import shared_overlay, shares, user_tables, view_templates
986
+ st = _store(session)
987
+ try:
988
+ if "_definitions" not in memo:
989
+ memo["_definitions"] = st.get_projection(user_tables.STORE_KEY, drop=("rows",)) or {}
990
+ memo["_grants"] = fingerprint((st.get(shares.SHARES_KEY, fresh=True) or {}).get("field"))
991
+ definition = memo["_definitions"].get(database) or {}
992
+ workspace = view_templates.workspace_key(database)
993
+ personal = (st.get_projection(workspace, drop=("overlays",)) or {}).get(session.uname) or {}
994
+ shared_key = database if database.startswith("ut_") else workspace
995
+ fields = {f["key"]: f for f in definition.get("fields", []) if f.get("key")}
996
+ fields.update(shared_overlay.fields(shared_key, st=st))
997
+ fields.update(personal.get("fields") or {})
998
+ memo[database] = [sorted(perm_scope.hidden_keys(session.user, database,
999
+ list(fields.values()), st=st)), session.uname if personal else None]
1000
+ except Exception:
1001
+ # An unprovable wall cannot read a previous slot.
1002
+ memo[database] = uuid.uuid4().hex
1003
+ policy = {key: value for key, value in session.user.items()
1004
+ if key not in ("username", "name", "email", "password", "password_hash", "epoch",
1005
+ "created_at", "updated_at", "last_login")}
1006
+ return fingerprint([sheets.scope_hash(database, wall_tree, (binding or {}).get("scope") or {}),
1007
+ binding, policy, memo[database], memo.get("_grants")])
1008
 
1009
 
1010
  def _has_ending(binding):
 
1018
  return True
1019
  scope = binding.get("scope") if isinstance(binding, dict) else None
1020
  nodes, _ = _fe_parts(scope.get("filter") if isinstance(scope, dict) else None)
1021
+ related = binding.get("related") if isinstance(binding, dict) else None
1022
+ related_nodes, _ = _fe_parts(related.get("filter") if isinstance(related, dict) else None)
1023
+ nodes = [*nodes, *related_nodes]
1024
  # Linked values and related-table grants can change independently of the orders' cache key.
1025
  if sheet_mod.linked_filter_ids(nodes):
1026
  return True
1027
  return any(sheet_mod.filter_cell_nodes(nodes))
1028
 
1029
 
1030
+ def _refresh_context(book, binding, memo=None):
1031
+ """Authored inputs and relative dates invalidate refresh, but never an open's snapshot."""
1032
+ from core.sheet_binding import fingerprint
1033
+ from datetime import date
1034
+ payload = {}
1035
+ if _has_cell_inputs(binding):
1036
+ if memo is None:
1037
+ memo = {}
1038
+ if "inputs" not in memo:
1039
+ memo["inputs"] = fingerprint([[tab.get("id"), tab.get("name"), {
1040
+ addr: {key: cell.get(key) for key in ("kind", "text", "formula", "binding", "value")
1041
+ if key != "value" or cell.get("kind") in ("literal", "empty")}
1042
+ for addr, cell in (tab.get("cells") or {}).items()}]
1043
+ for tab in book.get("sheets") or []])
1044
+ payload["inputs"] = memo["inputs"]
1045
+ # Relative filters and measure windows can change their answer at midnight without a write.
1046
+ encoded = json.dumps(binding, sort_keys=True)
1047
+ if any(word in encoded for word in ('"window"', '"within"', '"ending"', '"view_id"')):
1048
+ payload["today"] = date.today().isoformat()
1049
+ return fingerprint(payload)
1050
+
1051
+
1052
+ def _snapshot_cell(cell, snapshot):
1053
+ from copy import deepcopy
1054
+ for key in ("value", "display", "state", "refreshed_at", "refusal", "limits"):
1055
+ cell.pop(key, None)
1056
+ cell.update(deepcopy(snapshot))
1057
+
1058
+
1059
  def _reresolved_for_reader(session: Session, book, *, endings_only=False):
1060
+ """C2/R4: project last resolved values only. This GET path never resolves a binding."""
1061
+ from copy import deepcopy
1062
+ from core import sheet_binding
1063
+ session._sheet_scope_context = {}
1064
+ fresh = deepcopy(book)
1065
+ owner = _role_on_workbook(session, book) == "owner"
1066
+ try:
1067
+ cache = sheet_binding.read_refresh_cache(_store(session), book["id"])
1068
+ except Exception:
1069
+ cache = {}
1070
+ seen = {}
1071
+ changed_values = False
1072
+ for tab in fresh.get("sheets") or []:
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1073
  for addr, cell in (tab.get("cells") or {}).items():
1074
+ if cell.get("kind") != "bound":
1075
  continue
1076
+ if _is_view_binding(cell):
1077
  continue
1078
+ before = (cell.get("value"), cell.get("state"))
1079
  binding = cell.get("binding") or {}
1080
  db = str(binding.get("database") or "")
1081
+ if db not in seen:
1082
  try:
1083
  _require_database(session, db)
1084
+ seen[db] = True
1085
+ except HTTPException:
1086
+ seen[db] = False
1087
+ slot = _binding_scope_key(session, db, binding)
1088
+ hit = (cache.get("refreshCells", {}).get(str(tab.get("id")) + "!" + addr, {})
1089
+ .get(slot)) if seen[db] else None
1090
+ if hit:
1091
+ _snapshot_cell(cell, hit["cell"])
1092
+ elif not seen[db]:
1093
+ _snapshot_cell(cell, _binding_refusal("database_unreadable", f"You cannot read {db}."))
1094
+ elif owner and not cache.get("refreshCells") and session.user.get("role") == "admin":
1095
+ # Existing workbooks keep their pre-C2 last result until the first Refresh.
1096
+ pass
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1097
  else:
1098
+ _snapshot_cell(cell, _binding_refusal("sheet_refresh_required",
1099
+ "Refresh this workbook to resolve this cell under your current access."))
1100
+ changed_values |= before != (cell.get("value"), cell.get("state"))
1101
+ if changed_values:
1102
+ from modules import sheet as sheet_mod
1103
+ import formula_runtime as fr
1104
+ _recompute_formulas(fresh, fr, sheet_mod)
1105
+ if not owner:
1106
+ fresh["refreshedFor"] = str(session.uname or "")
 
 
 
 
 
 
 
 
 
 
1107
  return fresh
1108
 
1109
 
 
1115
 
1116
 
1117
  def _read_for(session: Session, book):
1118
+ """Project saved results under the current access wall without resolving any binding.
1119
 
1120
  W60-T09, 2026-09-14: R28 checks visibility before this projection. Admitted legacy readers
1121
+ and grantees receive a proven scoped snapshot or a request to Refresh.
1122
  """
1123
  book = _response_workbook(book)
 
 
 
 
 
1124
  return _reresolved_for_reader(session, book)
1125
 
1126
 
 
1731
  cache_key=(session.tenant, session.uname, workbook_id), changes=edits)
1732
  # Date and filter-cell edits also change database totals. Recompute all readers, then formulas.
1733
  ending_cells = set()
1734
+ refreshed_entries = []
1735
+ context_memo = {}
1736
  for source in book.get("sheets") or []:
1737
  for addr, cell in (source.get("cells") or {}).items():
1738
  binding = cell.get("binding") or {}
 
1741
  try:
1742
  result = _resolve_cell_binding(session, binding, book, source.get("id"))
1743
  cell.update(value=result["value"], display="" if result["value"] is None else str(result["value"]), state="fresh")
1744
+ cell["refreshed_at"] = _now_iso()
1745
+ if result.get("limits"):
1746
+ cell["limits"] = result["limits"]
1747
+ else:
1748
+ cell.pop("limits", None)
1749
  cell.pop("refusal", None)
1750
  except HTTPException as exc:
1751
  info = ((exc.detail or {}).get("error") or {})
 
1754
  info.get("message", "The Ending date could not be read. Choose a valid date."),
1755
  ))
1756
  ending_cells.add((source.get("id"), addr))
1757
+ refreshed_entries.append((str(source.get("id")) + "!" + addr,
1758
+ _binding_scope_key(session, str(binding.get("database") or ""), binding),
1759
+ {"tokens": {}, "context": _refresh_context(book, binding, context_memo),
1760
+ "cell": {k: cell[k] for k in ("value", "display", "state", "refreshed_at", "limits", "refusal")
1761
+ if k in cell}}))
1762
  if ending_cells:
1763
+ from core.sheet_binding import save_refresh_cache
1764
+ save_refresh_cache(_store(session), workbook_id, refreshed_entries,
1765
+ {c.get("binding", {}).get("database") for t in book.get("sheets", [])
1766
+ for c in t.get("cells", {}).values() if c.get("kind") == "bound"})
1767
  _recompute_formulas(book, fr, sheet_mod)
1768
  found = sheets.find_tab(book, tab_ref)
1769
  out = {}
 
1939
 
1940
  @router.post("/sheets/{workbook_id}/refresh")
1941
  def refresh_sheet(workbook_id: str, session: Session = Depends(require_session)):
1942
+ """C2/R4: Refresh resolves only databases whose token or binding inputs changed.
1943
+
1944
+ Viewers refresh their own server cache. Only editors save the workbook document.
1945
+ One token is read per distinct database on the unchanged path, regardless of cell count.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1946
  """
1947
+ from copy import deepcopy
1948
+ from core import sheets, sheet_binding
1949
  from modules import sheet as sheet_mod
1950
  import formula_runtime as fr
1951
+ from time import perf_counter
1952
 
1953
+ store = _store(session)
1954
+ session._sheet_scope_context = {}
1955
  try:
1956
+ book = sheets.get_workbook(store, workbook_id)
1957
+ _require_reader(session, book)
1958
  except sheets.SheetRefusal as exc:
1959
  raise _refuse(exc)
1960
+ editable = _role_on_workbook(session, book) in ("owner", "edit")
1961
+ try:
1962
+ cache = sheet_binding.read_refresh_cache(store, workbook_id)
1963
+ except Exception:
1964
+ cache = {}
1965
  stamp = _now_iso()
1966
+ seen_db, tokens, entries, status = {}, {}, [], {}
1967
+ view_memo, related_memo = {}, {}
1968
+ context_memo = {}
1969
+ token_reads = 0
1970
+ input_graph = None
1971
+
1972
+ def input_databases(binding, tab_ref):
1973
+ nonlocal input_graph
1974
+ nodes, _ = _fe_parts((binding.get("scope") or {}).get("filter"))
1975
+ related_nodes, _ = _fe_parts((binding.get("related") or {}).get("filter"))
1976
+ refs = [str((node.get("valueRef") or {}).get("ref") or "")
1977
+ for node in sheet_mod.filter_cell_nodes([*nodes, *related_nodes])]
1978
+ period = binding.get("period") or {}
1979
+ if period.get("ref"):
1980
+ refs.append(period["ref"])
1981
+ if not refs:
1982
+ return set()
1983
+ tabs = book.get("sheets") or []
1984
+ names = _tab_scope_names(tabs)
1985
+ if input_graph is None:
1986
+ documents = {fr.a1_key(addr, name): cell for tab, name in zip(tabs, names)
1987
+ for addr, cell in (tab.get("cells") or {}).items()}
1988
+ engine = fr.SheetCalculation({key: fr._document_spec(cell, key.rpartition("!")[0])
1989
+ for key, cell in documents.items()}, sheets=names,
1990
+ named_ranges=book.get("namedRanges"), date_system=book.get("dateSystem", "1900"))
1991
+ input_graph = documents, engine
1992
+ documents, engine = input_graph
1993
+ home = _resolve_home_tab(book, tabs, names, tab_ref)
1994
+ pending, visited, deps = [_asked_key(ref, home, fr) for ref in refs], set(), set()
1995
+ while pending:
1996
+ key = pending.pop()
1997
+ if key in visited:
1998
+ continue
1999
+ visited.add(key)
2000
+ cell = documents.get(key) or {}
2001
+ if cell.get("kind") == "bound":
2002
+ deps.add(str((cell.get("binding") or {}).get("database") or ""))
2003
+ pending.extend(engine.consumed.get(key, ()))
2004
+ return deps
2005
+
2006
+ def token(db):
2007
+ nonlocal token_reads
2008
+ if db not in tokens:
2009
+ token_reads += 1
2010
+ try:
2011
+ tokens[db] = sheet_binding.database_change_token(store, db)
2012
+ except Exception:
2013
+ # Failure to prove unchanged means resolve, never silently reuse a value.
2014
+ tokens[db] = None
2015
+ return tokens[db]
2016
+
2017
+ def dependencies(db, binding, tab_ref):
2018
+ deps = {db}
2019
+ if binding.get("related"):
2020
+ key = (db, binding["related"].get("via"))
2021
+ if key not in related_memo:
2022
+ related_memo[key] = _binding_related_entry(session, db, binding)
2023
+ deps.add(related_memo[key]["target"])
2024
+ nodes, _ = _fe_parts((binding.get("scope") or {}).get("filter"))
2025
+ linked = sheet_mod.linked_filter_ids(nodes)
2026
+ if linked:
2027
+ names = {sheet_mod.linked_field_parts(key)[0] for key in linked}
2028
+ deps.update(b["source"] for b in _linked_customer_bridges(db) if b["key"] in names)
2029
+ deps.update(input_databases(binding, tab_ref))
2030
+ return deps
2031
+
2032
+ bound_inputs = {fr.a1_key(addr, name): (tab.get("id"), addr, cell)
2033
+ for tab, name in zip(book.get("sheets") or [], _tab_scope_names(book.get("sheets") or []))
2034
+ for addr, cell in (tab.get("cells") or {}).items() if cell.get("kind") == "bound"}
2035
+
2036
+ def cached_input(key):
2037
+ item = bound_inputs.get(key)
2038
+ if item is None:
2039
+ return None
2040
+ tab_ref, addr, cell = item
2041
+ binding = cell.get("binding") or {}
2042
+ db = str(binding.get("database") or "")
2043
+ _require_database(session, db)
2044
+ scope_key = _binding_scope_key(session, db, binding)
2045
+ hit = cache.get("refreshCells", {}).get(str(tab_ref) + "!" + addr, {}).get(scope_key)
2046
+ sources = {db: token(db) for db in dependencies(db, binding, tab_ref)}
2047
+ if (hit and all(sources.values()) and hit.get("tokens") == sources
2048
+ and hit.get("context") == _refresh_context(book, binding, context_memo)
2049
+ and hit["cell"].get("state") == "fresh"):
2050
+ return hit["cell"]
2051
+ return None
2052
+
2053
+ for tab in book.get("sheets") or []:
2054
  for addr, cell in (tab.get("cells") or {}).items():
2055
+ if cell.get("kind") != "bound" or _is_view_binding(cell):
2056
  continue
 
 
2057
  binding = cell.get("binding") or {}
2058
  db = str(binding.get("database") or "")
2059
+ cell_key = str(tab.get("id")) + "!" + addr
2060
+ scope_key = _binding_scope_key(session, db, binding)
2061
+ context = _refresh_context(book, binding, context_memo)
2062
+ hit = cache.get("refreshCells", {}).get(cell_key, {}).get(scope_key)
2063
+ source_tokens = {}
 
 
 
 
 
 
2064
  try:
2065
+ if db not in seen_db:
2066
+ try:
2067
+ _require_database(session, db)
2068
+ seen_db[db] = None
2069
+ except HTTPException as exc:
2070
+ seen_db[db] = exc
2071
+ if seen_db[db] is not None:
2072
+ raise seen_db[db]
2073
+ source_tokens = {key: token(key) for key in sorted(dependencies(db, binding, tab.get("id")))}
2074
+ if (hit and all(source_tokens.values()) and hit.get("tokens") == source_tokens
2075
+ and hit.get("context") == context
2076
+ and hit["cell"].get("state") == "fresh"):
2077
+ _snapshot_cell(cell, hit["cell"])
2078
+ status.setdefault(db, "skipped")
2079
+ continue
2080
+ status[db] = "resolved"
2081
+ previous = getattr(session, "_sheet_refresh_input", None)
2082
+ session._sheet_refresh_input = cached_input
2083
+ try:
2084
+ out = _resolve_cell_binding(session, binding, book, tab.get("id"), view_memo=view_memo)
2085
+ finally:
2086
+ session._sheet_refresh_input = previous
2087
+ limits = list(out.get("limits") or [])
2088
+ if not all(source_tokens.values()):
2089
+ limits.append({"code": "change_token_unavailable",
2090
+ "cause": "The database change token could not be read. This Refresh resolved the cell.",
2091
+ "recommendation": "Restore the database store and connector sync receipts to enable skipping."})
2092
+ snapshot = {"state": "fresh", "value": out["value"],
2093
+ "display": "" if out["value"] is None else str(out["value"]),
2094
+ "refreshed_at": stamp}
2095
+ if limits:
2096
+ snapshot["limits"] = limits
2097
  except HTTPException as exc:
2098
+ info = ((exc.detail or {}).get("error") or {})
2099
+ snapshot = _binding_refusal(info.get("code", "sheet_unresolved"),
2100
+ info.get("message", "This cell could not be refreshed."))
2101
+ status[db] = "refused"
2102
+ _snapshot_cell(cell, snapshot)
2103
+ entries.append((cell_key, scope_key, {"tokens": source_tokens,
2104
+ "context": context, "cell": deepcopy(snapshot)}))
2105
+
2106
+ # Read again only after resolving. A concurrent write must not certify a mixed result
2107
+ # as reusable. The unchanged path still costs exactly one token read per database.
2108
+ resolved_sources = {db for _, _, entry in entries for db in entry["tokens"]}
2109
+ changed = set()
2110
+ for db in resolved_sources:
2111
+ if tokens[db] is None:
2112
+ continue # Already disclosed as unverified and never eligible for a hit.
2113
+ token_reads += 1
2114
+ try:
2115
+ if sheet_binding.database_change_token(store, db) != tokens[db]:
2116
+ changed.add(db)
2117
+ except Exception:
2118
+ changed.add(db)
2119
+ for cell_key, _, entry in entries:
2120
+ if changed.intersection(entry["tokens"]):
2121
+ entry["tokens"] = {} # no next-refresh hit, even if the writer rolls back
2122
+ if entry["cell"].get("state") == "fresh":
2123
+ entry["cell"].setdefault("limits", []).append({"code": "change_during_refresh",
2124
+ "cause": "This database could not be confirmed unchanged while the cell was being resolved.",
2125
+ "recommendation": "Refresh again to resolve the cell from the updated database."})
2126
+ tab_ref, addr = cell_key.split("!", 1)
2127
+ _snapshot_cell(sheets.find_tab(book, tab_ref)["cells"][addr], entry["cell"])
2128
 
 
 
 
 
 
 
 
 
 
 
2129
  started = perf_counter()
2130
  _recompute_formulas(book, fr, sheet_mod)
2131
  recalc_ms = round((perf_counter() - started) * 1000.0, 1)
2132
+ if editable:
2133
+ try:
2134
+ saved = sheets.put_workbook(store, workbook_id,
2135
+ {"name": book.get("name"), "sheets": book.get("sheets"),
2136
+ "refreshed_at": stamp, "rev": book.get("rev")},
2137
+ actor=session.uname, actor_name=session.user.get("name") or session.uname,
2138
+ lossless=True)
2139
+ except sheets.SheetRefusal as exc:
2140
+ raise _refuse(exc)
2141
+ else:
2142
+ saved = book
2143
+ saved["refreshedFor"] = str(session.uname or "")
2144
+ if entries:
2145
+ sheet_binding.save_refresh_cache(store, workbook_id, entries, status)
2146
+ return {"workbook": _response_workbook(saved), "recalc_ms": recalc_ms,
2147
+ "binding_refresh": {"databases": status, "token_reads": token_reads}}
2148
 
2149
 
2150
  def _now_iso():
 
2440
  refuse("the cell or its sheet is missing or blank.")
2441
  if cell.get("kind") == "bound":
2442
  try:
2443
+ lookup = getattr(session, "_sheet_refresh_input", None)
2444
+ cached = lookup(key) if lookup is not None else None
2445
+ value = (cached["value"] if cached is not None else _resolve_binding(
2446
+ session, cell.get("binding"), today=today, book=book,
2447
+ tab=key.rpartition("!")[0], ending_seen=(*seen, key))["value"])
2448
  except HTTPException as exc:
2449
  reason = ((exc.detail or {}).get("error") or {}).get("message", "its source is refused.")
2450
  refuse(reason)
 
2472
  for dependency in needed:
2473
  attempted.add(dependency)
2474
  try:
2475
+ lookup = getattr(session, "_sheet_refresh_input", None)
2476
+ result = lookup(dependency) if lookup is not None else None
2477
+ if result is None:
2478
+ result = _resolve_binding(session, bound[dependency].get("binding"), today=today,
2479
+ book=book, tab=dependency.rpartition("!")[0], ending_seen=(*seen, key, dependency))
2480
  changes[dependency] = {"value": result["value"]}
2481
  except HTTPException as exc:
2482
  info = ((exc.detail or {}).get("error") or {})
 
2547
  return _resolve_binding(session, binding, **kwargs)
2548
 
2549
 
2550
+ def _binding_related_entry(session, database, binding):
2551
+ """Resolve one authored edge key against the permission-scoped declarations."""
2552
+ if "related" not in binding:
2553
+ return None
2554
+ from core import perm_scope, relations, user_tables
2555
+ from routes_grid import _source_fields
2556
+
2557
+ fields = _source_fields(session, database)
2558
+ defs = {}
2559
+ for key, definition in (user_tables.all_defs(st=session.runtime) or {}).items():
2560
+ if perm_scope.nav_may_open(session.user, key, st=session.runtime):
2561
+ declared = definition.get("fields") or []
2562
+ hidden = perm_scope.hidden_keys(session.user, key, declared, st=session.runtime)
2563
+ defs[key] = {**definition, "fields": [f for f in declared if f.get("key") not in hidden]}
2564
+ entries = relations.related(database, fields=fields, defs=defs)
2565
+ name = binding["related"]["via"]
2566
+ matches = [entry for entry in entries if entry["key"] == name]
2567
+ via = matches[0]["via"] if len(matches) == 1 else {"key": name}
2568
+ entry = relations.find(database, via, fields=fields, defs=defs)
2569
+ if entry is None:
2570
+ candidates = [item["key"] for item in relations.via_candidates(entries, via)
2571
+ if perm_scope.nav_may_open(session.user, item["target"], st=session.runtime)]
2572
+ offered = (" Available relationships: " + ", ".join(candidates) + ".") if candidates else ""
2573
+ # Write our own sentence: the shared pin refusal does not name via.key.
2574
+ raise err(409, "unknown_relation",
2575
+ f"Relationship '{name}' cannot be resolved on '{database}'."
2576
+ + offered + " Choose a declared relationship for this database.")
2577
+ target = _require_database(session, entry["target"])
2578
+ if not entry.get("served"):
2579
+ raise err(409, "relation_target_unavailable",
2580
+ f"Relationship '{name}' cannot read '{target}' because it has no read-through "
2581
+ "binding. Choose a relationship to a database with a live connection.")
2582
+ # A through/manual link cannot be represented by this one declared column pair.
2583
+ declaration = next((f for f in fields if f.get("key") == entry["via"].get("field")), {})
2584
+ if entry["via"]["direction"] == "reverse":
2585
+ declaration = next((f for f in defs.get(target, {}).get("fields", [])
2586
+ if f.get("key") == entry["via"].get("field")), {})
2587
+ link = declaration.get("link") or {}
2588
+ if link.get("through") or link.get("selectionMode") == "manual":
2589
+ raise err(409, "relation_source_unresolvable",
2590
+ f"Relationship '{name}' does not declare a direct column join. "
2591
+ "Choose a relationship with one readable column on each database.")
2592
+ return entry
2593
+
2594
+
2595
+ def _binding_related_query(session, binding, entry, cur, spec, columns, *, window=None,
2596
+ today=None, book=None, tab=None, ending_seen=()):
2597
+ """Materialise the far side on the near cursor, then hand metadata to the compiler."""
2598
+ if entry is None:
2599
+ return None
2600
+ from core import perm_scope, relations
2601
+ from modules import sheet as sheet_mod
2602
+
2603
+ database, target = binding["database"], entry["target"]
2604
+ name = binding["related"]["via"]
2605
+ local_key, remote_key = entry["via"].get("from"), entry["via"].get("on")
2606
+
2607
+ def map_join(key, table, source_spec, cols, side):
2608
+ hidden = perm_scope.hidden_keys(session.user, table, source_spec.get("fields") or [],
2609
+ st=session.runtime)
2610
+ if key and key not in hidden:
2611
+ expr = (cols.get(key) or {}).get("sql")
2612
+ if not expr:
2613
+ # Identity and join columns can be absent from the visible field list.
2614
+ # Only the trusted mirror map may supply their expressions.
2615
+ mapped = (source_spec.get("cols") or {}).get(key)
2616
+ expr = (source_spec.get("id") if key == relations.IDENTITY_COL else
2617
+ mapped[0] if mapped else None)
2618
+ if expr and str(expr).strip().upper() != "NULL":
2619
+ cols[key] = {**cols.get(key, {}), "sql": expr}
2620
+ return
2621
+ code = "relation_source_unresolvable" if side == "source" else "relation_target_unavailable"
2622
+ raise err(409, code,
2623
+ f"Relationship '{name}' cannot read its {side} column '{key}' on '{table}'. "
2624
+ "Choose a relationship whose join columns are available on the live connection.")
2625
+
2626
+ map_join(local_key, database, spec, columns, "source")
2627
+ wall = ((perm_scope.entry(session.user, target) or {}).get("filter")
2628
+ if perm_scope.row_scope_applies(session.user, target) else None)
2629
+ wall_nodes, wall_conj = _fe_parts(wall)
2630
+ scope_nodes, scope_conj = _fe_parts(binding["related"]["filter"])
2631
+ scope_nodes = _filter_cell_values(session, scope_nodes, book=book, tab=tab,
2632
+ today=today, seen=ending_seen)
2633
+ needed = (sheet_mod.filter_columns_named(scope_nodes)
2634
+ | sheet_mod.filter_columns_named(wall_nodes) | {remote_key})
2635
+ try:
2636
+ rcur, rspec, rcols = _mirror(session)(target, metric_window=window, needed=needed)
2637
+ except HTTPException as exc:
2638
+ detail = exc.detail if isinstance(exc.detail, dict) else {}
2639
+ if exc.status_code == 404 or (detail.get("error") or {}).get("code") == "not_read_through":
2640
+ raise err(409, "relation_target_unavailable",
2641
+ f"Relationship '{name}' cannot read '{target}' on this live connection. "
2642
+ "Choose a relationship to an available database.") from exc
2643
+ raise
2644
+ if rcur is not cur:
2645
+ raise err(409, "relation_cursor_mismatch",
2646
+ f"Relationship '{name}' cannot be queried on the same live connection as "
2647
+ f"'{database}'. Retry after both databases share a connection.")
2648
+ hidden = perm_scope.hidden_keys(session.user, target, rspec.get("fields") or [],
2649
+ st=session.runtime)
2650
+ rcols = {key: value for key, value in rcols.items() if key not in hidden}
2651
+ map_join(remote_key, target, rspec, rcols, "target")
2652
+ depends = sheet_mod.filter_columns_named(scope_nodes)
2653
+ return {"via": name, "database": target, "local_key": local_key, "remote_key": remote_key,
2654
+ "spec": rspec, "columns": rcols, "where": entry.get("where"),
2655
+ "scope_nodes": scope_nodes, "scope_conj": scope_conj,
2656
+ "wall_nodes": wall_nodes, "wall_conj": wall_conj,
2657
+ "limits": [row for key, row in (rspec.get("unbounded") or {}).items() if key in depends]}
2658
+
2659
+
2660
  def _resolve_binding(session: Session, raw_binding, *, today=None, view_memo=None,
2661
  book=None, tab=None, ending_seen=()):
2662
  """Evaluate ONE C2 binding and return `{value, limits, sql_columns}`.
 
2718
  if binding["aggregate"].get("field"):
2719
  needed.add(str(binding["aggregate"]["field"]))
2720
 
2721
+ related_entry = _binding_related_entry(session, database, binding)
2722
+ if related_entry:
2723
+ needed.add(related_entry["via"].get("from"))
2724
  cur, spec, cols = _mirror(session)(database, metric_window=window, needed=needed)
2725
  cols = dict(cols)
2726
  scope_nodes = _linked_filter_scope(session, database, scope_nodes, cur, spec, cols, today=today)
 
2762
  # spec's column expressions; applying it a second time would double-count the exclusion and
2763
  # break every joined spec, whose partner column is `sol.order_partner_id` or `aml.partner_id`.
2764
  try:
2765
+ related = _binding_related_query(
2766
+ session, binding, related_entry, cur, spec, cols, window=window, today=today,
2767
+ book=book, tab=tab, ending_seen=ending_seen)
2768
  sql, params, limits = sheet_mod.build_aggregate_query(
2769
  spec, binding, cols, scope_nodes=scope_nodes, scope_conj=scope_conj,
2770
+ wall_nodes=wall_nodes, wall_conj=wall_conj, today=today, related=related)
2771
  except sheet_mod.SheetRefusal as exc:
2772
  raise err(400, exc.code, exc.message)
2773
  except ValueError:
 
3034
  saved["refreshed_at"] = stamp
3035
  saved.pop("refusal", None)
3036
 
3037
+ if limits:
3038
+ saved["limits"] = limits
3039
+ else:
3040
+ saved.pop("limits", None)
3041
+
3042
  try:
3043
  landed = sheets.patch_cells(_store(session), workbook_id, tab_ref, {key: saved},
3044
  actor=session.uname,
 
3058
  except Exception: # noqa: BLE001
3059
  pass
3060
 
3061
+ from core.sheet_binding import save_refresh_cache
3062
+ save_refresh_cache(_store(session), workbook_id, [(tab_ref + "!" + key,
3063
+ _binding_scope_key(session, str(binding.get("database") or ""), binding),
3064
+ {"tokens": {}, "context": _refresh_context(book, binding),
3065
+ "cell": {k: saved[k] for k in ("value", "display", "state", "refreshed_at", "limits", "refusal")
3066
+ if k in saved}})], [binding.get("database")])
3067
+
3068
  wire = dict(saved)
3069
  #: ⚠ `limits` RIDES THE ANSWER AND IS NOT STORED, because `core.sheets.clean_cell` carries no
3070
  #: such key: it describes THIS resolve's truncation, not the cell.
 
3246
  window = _ending_window(session, binding, book=book, tab=tab.get("id"))
3247
  except sheet_mod.SheetRefusal as exc:
3248
  raise err(400, exc.code, exc.message)
3249
+ related_entry = _binding_related_entry(session, database, binding)
3250
+ needed = (sheet_mod.filter_columns_named(scope_nodes)
3251
+ | sheet_mod.filter_columns_named(wall_nodes))
3252
+ if related_entry:
3253
+ needed.add(related_entry["via"].get("from"))
3254
  cur, spec, cols = _mirror(session)(
3255
  database, metric_window=window,
3256
+ needed=needed)
 
3257
  cols = dict(cols)
3258
  scope_nodes = _linked_filter_scope(session, database, scope_nodes, cur, spec, cols)
3259
 
3260
  try:
3261
+ related = _binding_related_query(
3262
+ session, binding, related_entry, cur, spec, cols, window=window,
3263
+ book=book, tab=tab.get("id"))
3264
  count_sql, count_params, limits = sheet_mod.build_aggregate_query(
3265
  spec, {"aggregate": {"fn": "count"}}, cols, scope_nodes=scope_nodes,
3266
+ scope_conj=scope_conj, wall_nodes=wall_nodes, wall_conj=wall_conj, related=related)
3267
+ ids_sql, ids_params, _ = sheet_mod.build_ids_query(
3268
+ spec, cols, scope_nodes=scope_nodes, scope_conj=scope_conj,
3269
+ wall_nodes=wall_nodes, wall_conj=wall_conj, related=related)
3270
  except sheet_mod.SheetRefusal as exc:
3271
  raise err(400, exc.code, exc.message)
3272
+ except ValueError:
3273
+ raise err(409, "scope_not_applicable",
3274
+ "This cell's scope uses a restriction that cannot be applied on its live "
3275
+ "connection. Edit the scope or ask an administrator to update the restriction.")
3276
  total = (cur.execute(count_sql, count_params).fetchone() or [0])[0]
3277
 
 
 
 
3278
  record_ids = [int(r[0]) for r in cur.execute(ids_sql, ids_params).fetchall() if r and r[0]]
3279
 
3280
  out = {"database": database, "record_ids": record_ids, "count": int(total or 0),
api/routes_templates.py CHANGED
@@ -239,13 +239,14 @@ def _requirement(database, definitions, have, database_states, connector=""):
239
  else "ready" if switched_on else "off"}
240
 
241
 
242
- def _catalog_row(key, name, description, requires):
243
  # Prefer the missing connection even when an earlier database is merely off.
244
  blocked = next((row for row in requires if row["state"] == "disconnected"), None)
245
  blocked = blocked or next((row for row in requires if row["state"] != "ready"), None)
246
  return {"key": key, "name": str(name).replace(chr(0x2014), "-").replace(chr(0x2013), "-"),
247
  "description": str(description).replace(chr(0x2014), "-").replace(chr(0x2013), "-"),
248
  "requires": requires, "creatable": all(row["state"] == "ready" for row in requires),
 
249
  "action": None if blocked is None else {
250
  "kind": "connect" if blocked["state"] == "disconnected" else "switch_on",
251
  "connector": blocked["connector"], "database": blocked["database"]}}
@@ -269,6 +270,8 @@ def _module_templates(session):
269
  from routes_connectors import _entry_types
270
  from routes_keychain import env_odoo_available
271
  from routes_nav import application_templates
 
 
272
 
273
  definitions = user_tables.all_defs(session.runtime)
274
  have, _scopes, _failure = _entry_types(session.runtime, session.uname)
@@ -299,6 +302,9 @@ def _module_templates(session):
299
  # These App contracts map fields in the existing wizard and require no fixed connector.
300
  app = [_catalog_row(row["kind"], row["label"], "Choose a database and map its fields.", [])
301
  for row in application_templates(session=session)["templates"]]
 
 
 
302
  return {"sections": [{"module": "sheet", "templates": sheet},
303
  {"module": "data", "templates": data},
304
  {"module": "app", "templates": app}]}
@@ -406,6 +412,35 @@ def create_module_template(module: str, key: str, body: dict = Body(default=None
406
  from urllib.parse import quote
407
 
408
  body = body if isinstance(body, dict) else {}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
409
  section = next((row for row in _module_templates(session)["sections"] if row["module"] == module), None)
410
  template = next((row for row in section["templates"] if row["key"] == key), None) if section else None
411
  if template is None:
 
239
  else "ready" if switched_on else "off"}
240
 
241
 
242
+ def _catalog_row(key, name, description, requires, *, creation_mode="wizard"):
243
  # Prefer the missing connection even when an earlier database is merely off.
244
  blocked = next((row for row in requires if row["state"] == "disconnected"), None)
245
  blocked = blocked or next((row for row in requires if row["state"] != "ready"), None)
246
  return {"key": key, "name": str(name).replace(chr(0x2014), "-").replace(chr(0x2013), "-"),
247
  "description": str(description).replace(chr(0x2014), "-").replace(chr(0x2013), "-"),
248
  "requires": requires, "creatable": all(row["state"] == "ready" for row in requires),
249
+ "creationMode": creation_mode,
250
  "action": None if blocked is None else {
251
  "kind": "connect" if blocked["state"] == "disconnected" else "switch_on",
252
  "connector": blocked["connector"], "database": blocked["database"]}}
 
270
  from routes_connectors import _entry_types
271
  from routes_keychain import env_odoo_available
272
  from routes_nav import application_templates
273
+ from routes_applications import _may_open
274
+ from modules.finance_apps import finance_templates
275
 
276
  definitions = user_tables.all_defs(session.runtime)
277
  have, _scopes, _failure = _entry_types(session.runtime, session.uname)
 
302
  # These App contracts map fields in the existing wizard and require no fixed connector.
303
  app = [_catalog_row(row["kind"], row["label"], "Choose a database and map its fields.", [])
304
  for row in application_templates(session=session)["templates"]]
305
+ app.extend(_catalog_row("finance:" + row["key"], row["label"], row["description"], [],
306
+ creation_mode="post")
307
+ for row in finance_templates(may_open=lambda permission: _may_open(session, permission)))
308
  return {"sections": [{"module": "sheet", "templates": sheet},
309
  {"module": "data", "templates": data},
310
  {"module": "app", "templates": app}]}
 
412
  from urllib.parse import quote
413
 
414
  body = body if isinstance(body, dict) else {}
415
+ if module == "app" and key.startswith("finance:"):
416
+ import application_registry
417
+ from modules.finance_apps import finance_application
418
+ from routes_applications import _may_open
419
+
420
+ finance_key = key.removeprefix("finance:")
421
+ try:
422
+ descriptor = finance_application(
423
+ finance_key, may_open=lambda permission: _may_open(session, permission))
424
+ except KeyError:
425
+ raise err(404, "unknown_template", "That template does not exist.")
426
+ except PermissionError:
427
+ raise err(403, "finance_forbidden", f"Access to Finance template {finance_key!r} is not granted.")
428
+ if not session.runtime.available():
429
+ raise err(503, "store_unavailable", "The tenant store is unavailable. Nothing was saved.")
430
+ try:
431
+ application = application_registry.create(
432
+ session.runtime, session.tenant, session.uname,
433
+ {"templateKind": application_registry.FINANCE_TEMPLATE_KIND,
434
+ "financeKey": finance_key, "name": body.get("name") or descriptor["label"],
435
+ "navPlacement": {"section": "app", "order": 0}},
436
+ allowed_databases=set())
437
+ except application_registry.ApplicationError as exc:
438
+ raise err(400, "bad_application", str(exc))
439
+ except PermissionError as exc:
440
+ raise err(403, "forbidden", str(exc))
441
+ except Exception:
442
+ raise err(503, "store_unavailable", "The Finance application was not saved.")
443
+ return {"address": "#" + application["deepLink"], "application": application}
444
  section = next((row for row in _module_templates(session)["sections"] if row["module"] == module), None)
445
  template = next((row for row in section["templates"] if row["key"] == key), None) if section else None
446
  if template is None:
platform/core/daily_sales_repair.py CHANGED
@@ -1,10 +1,9 @@
1
  """A refusal-first, exact-snapshot repair for a Daily Sales workbook the caller names.
2
 
3
- The core target is required so no default can point a repair at the owner's data. Every binding
4
- window uses core.windows.normalize, the arbiter used by core.sheet_binding.clean_period (C2, S64-T20).
5
-
6
- This module does not discover source values and does not contain tenant numbers. An authorized
7
- caller supplies a one-to-one source oracle and scoped database bindings, including both YTDs.
8
  The module validates the complete projected document, writes and verifies a backup, then delegates
9
  one atomic, preconditioned cell mutation to :mod:`core.sheets`.
10
  """
@@ -13,6 +12,7 @@ from __future__ import annotations
13
 
14
  import copy
15
  import json
 
16
  import re
17
  from datetime import date
18
 
@@ -22,6 +22,23 @@ from core import windows as W
22
 
23
  TARGET_WORKBOOK_ID = "b8edba3d3f47"
24
  TARGET_TENANT = "royal-imports"
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
25
 
26
 
27
  def operation_for(workbook_id):
@@ -112,12 +129,45 @@ def _validate_binding(name, binding, *, window_kind=None):
112
  if not isinstance(aggregate, dict) or not (
113
  aggregate.get("metric_key") or aggregate.get("fn")):
114
  raise RepairRefusal("repair_binding_invalid", name + " must name a real aggregate.")
 
 
 
 
115
  scope = binding.get("scope")
116
- if not isinstance(scope, dict) or not str(scope.get("view_id") or "").strip():
 
 
 
 
 
 
 
 
 
 
 
117
  raise RepairRefusal(
118
  "repair_binding_scope_required",
119
- name + " must use an existing saved View so linked dimensions retain their join.")
 
 
 
 
 
 
120
  period = binding.get("period")
 
 
 
 
 
 
 
 
 
 
 
 
121
  window = W.normalize(copy.deepcopy(period.get("window") if isinstance(period, dict) else None))
122
  if window is None or (window_kind is not None and window["kind"] != window_kind):
123
  expected_window = "the " + window_kind if window_kind is not None else "a valid"
@@ -173,6 +223,92 @@ def formula_error_census(book):
173
  return sorted(errors, key=lambda row: (str(row["sheet"]), row["address"]))
174
 
175
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
176
  def _project(book, edits):
177
  projected = copy.deepcopy(book)
178
  for edit in edits:
@@ -205,11 +341,39 @@ def _checked_projection(projected, edits, formula_check):
205
  errors = list(result or ())
206
  before, after = _cell_map(projected), _cell_map(checked)
207
  planned = {(row["sheet"].casefold(), row["address"]): row for row in edits}
 
 
208
  for slot in sorted(before.keys() | after.keys()):
209
  if before.get(slot) == after.get(slot):
210
  continue
211
  row = planned.get(slot)
212
- if row is None or row["kind"] != "source" \
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
213
  or not isinstance(row.get("after"), dict) \
214
  or row["after"].get("kind") != "formula":
215
  raise RepairRefusal(
@@ -217,7 +381,8 @@ def _checked_projection(projected, edits, formula_check):
217
  "Formula validation would change a cell outside the supplied source diff.")
218
  recalculated = after.get(slot)
219
  if not isinstance(recalculated, dict) \
220
- or recalculated.get("value") != row.get("cached_value"):
 
221
  raise RepairRefusal(
222
  "repair_formula_cache_mismatch",
223
  row["name"] + " does not recalculate to its supplied cached Excel value.")
@@ -229,6 +394,304 @@ def _checked_projection(projected, edits, formula_check):
229
  ]), errors
230
 
231
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
232
  def _build_plan(current, request, resolve_binding):
233
  if not isinstance(request.get("source_cells"), list) or not request["source_cells"]:
234
  raise RepairRefusal(
@@ -421,14 +884,24 @@ def execute(st, backup_store, request, *, target_workbook_id=TARGET_WORKBOOK_ID,
421
  raise RepairRefusal("repair_revision_mismatch",
422
  "The named workbook is not at the expected repair revision.")
423
  digest = sheets.workbook_digest(current)
424
- edits = _build_plan(current, request, resolve_binding)
 
 
 
 
 
 
425
  projected = _project(current, edits)
426
  projected, projected_errors = _checked_projection(projected, edits, formula_check)
427
- if projected_errors:
 
 
 
 
428
  raise RepairRefusal(
429
  "repair_formula_errors",
430
- "The projected workbook still has " + str(len(projected_errors))
431
- + " formula error(s), so no repair was applied.")
432
  visual_before = visual_metadata(current)
433
  if visual_metadata(projected) != visual_before:
434
  raise RepairRefusal("repair_visual_metadata_changed",
@@ -454,12 +927,29 @@ def execute(st, backup_store, request, *, target_workbook_id=TARGET_WORKBOOK_ID,
454
  raise RepairRefusal("repair_readback_cell",
455
  row["sheet"] + "!" + row["address"] + " did not read back exactly.")
456
  checked_readback, readback_errors = _checked_projection(readback, copy.deepcopy(edits), formula_check)
457
- if readback_errors or _cell_map(checked_readback) != _cell_map(readback):
 
 
 
 
 
458
  raise RepairRefusal("repair_readback_formula_state",
459
  "The repaired workbook did not read back calculation-current.")
460
  if visual_metadata(readback) != visual_before:
461
  raise RepairRefusal("repair_readback_visual_metadata",
462
  "Daily Sales visual metadata changed during repair.")
 
 
 
 
 
 
 
 
 
 
 
 
463
 
464
  source_readback = {row["name"]: copy.deepcopy(
465
  (_tab(readback, row["sheet"]).get("cells") or {}).get(row["address"]))
@@ -467,7 +957,7 @@ def execute(st, backup_store, request, *, target_workbook_id=TARGET_WORKBOOK_ID,
467
  bindings = {row["name"]: copy.deepcopy(
468
  ((_tab(readback, row["sheet"]).get("cells") or {}).get(row["address"]) or {}).get("binding"))
469
  for row in edits if row["kind"] == "binding"}
470
- return {
471
  "workbook_id": target_workbook_id,
472
  "revision_before": revision,
473
  "revision_after": readback["rev"],
@@ -479,5 +969,9 @@ def execute(st, backup_store, request, *, target_workbook_id=TARGET_WORKBOOK_ID,
479
  "source_cells": source_readback,
480
  "bindings": bindings,
481
  "formula_errors": formula_error_census(readback),
 
482
  "visual_metadata_preserved": True,
483
  }
 
 
 
 
1
  """A refusal-first, exact-snapshot repair for a Daily Sales workbook the caller names.
2
 
3
+ The legacy source-oracle plan and the workbook-derived invoice summary plan share the same
4
+ backup, exact-write and readback guards. Canonical periods use core.windows.normalize; the
5
+ summary uses the workbook's own filter valueRefs instead of freezing its calendar in a period.
6
+ The authorized operator injects the independent invoice validator and the full joined partner set.
 
7
  The module validates the complete projected document, writes and verifies a backup, then delegates
8
  one atomic, preconditioned cell mutation to :mod:`core.sheets`.
9
  """
 
12
 
13
  import copy
14
  import json
15
+ import math
16
  import re
17
  from datetime import date
18
 
 
22
 
23
  TARGET_WORKBOOK_ID = "b8edba3d3f47"
24
  TARGET_TENANT = "royal-imports"
25
+ SUMMARY_TAB = "Summary (All)"
26
+ SUMMARY_TAB_ID = "c2545d26c42c"
27
+ SUMMARY_COLUMNS = tuple(chr(column) for column in range(ord("F"), ord("R") + 1))
28
+ TICKET_FORMULA_ERROR_CODES = frozenset({"#VALUE!", "#DIV/0!", "#REF!", "#N/A", "#NAME?"})
29
+ _EXCEL_ERROR_ALIASES = {
30
+ "bad_value": "#VALUE!", "div_zero": "#DIV/0!", "invalid_reference": "#REF!",
31
+ "external_reference": "#REF!", "no_match": "#N/A", "unknown_name": "#NAME?",
32
+ }
33
+ _SUMMARY_RATIO_ROOTS = {
34
+ "F69": "=(F75/F64) * (365 / (F$7 - DATE(YEAR(F$7),1,1) + 1))",
35
+ "F70": "=(F76/F67) * (365 / (F$7 - DATE(YEAR(F$7),1,1) + 1))",
36
+ "R70": "=(R76/R67) * (365 / (R$7 - DATE(YEAR(R$7),1,1) + 1))",
37
+ }
38
+ _SUMMARY_RATIO_CASCADES = {
39
+ "F71": "=F69-F70", "F72": "=F71/F70", "F73": "=G72-F72",
40
+ "R71": "=R69-R70", "R72": "=R71/R70", "R73": "=R72-Q72",
41
+ }
42
 
43
 
44
  def operation_for(workbook_id):
 
129
  if not isinstance(aggregate, dict) or not (
130
  aggregate.get("metric_key") or aggregate.get("fn")):
131
  raise RepairRefusal("repair_binding_invalid", name + " must name a real aggregate.")
132
+ if not aggregate.get("metric_key") and (
133
+ aggregate.get("fn") not in {"sum", "count", "avg", "min", "max"}
134
+ or (aggregate["fn"] != "count" and not aggregate.get("field"))):
135
+ raise RepairRefusal("repair_binding_invalid", name + " must name a real column aggregate.")
136
  scope = binding.get("scope")
137
+ if not isinstance(scope, dict):
138
+ scope = {}
139
+ has_view = bool(str(scope.get("view_id") or "").strip())
140
+ tree = scope.get("filter")
141
+ # Accept the same explicit, nonempty conjunction used by rows 108-113. Requiring
142
+ # both referenced date bounds keeps a missing period from becoming an unbounded sum.
143
+ nodes = tree.get("nodes") if isinstance(tree, dict) else None
144
+ has_filter = (isinstance(nodes, list) and bool(nodes) and tree.get("conj") == "and"
145
+ and all(isinstance(n, dict) and n.get("colId") and n.get("op")
146
+ and ("value" in n or isinstance(n.get("valueRef"), dict))
147
+ for n in nodes))
148
+ if not has_view and not has_filter:
149
  raise RepairRefusal(
150
  "repair_binding_scope_required",
151
+ name + " must use a saved View or an explicit nonempty filter scope.")
152
+ if "related" in binding:
153
+ from core.sheet_binding import BindingMetadataRefusal, clean_related
154
+ try:
155
+ clean_related(binding["related"])
156
+ except BindingMetadataRefusal as exc:
157
+ raise RepairRefusal(exc.code, exc.message) from exc
158
  period = binding.get("period")
159
+ if period is None and has_filter and not has_view:
160
+ bounds = {}
161
+ for node in nodes:
162
+ slot = node.get("valueRef")
163
+ if slot is not None:
164
+ if not isinstance(slot, dict) or set(slot) != {"ref"}:
165
+ raise RepairRefusal("repair_binding_invalid", name + " has an invalid cell reference.")
166
+ _addr(slot["ref"])
167
+ if node["op"] in {"gte", "lte"}:
168
+ bounds.setdefault(node["colId"], set()).add(node["op"])
169
+ if any(ops == {"gte", "lte"} for ops in bounds.values()):
170
+ return
171
  window = W.normalize(copy.deepcopy(period.get("window") if isinstance(period, dict) else None))
172
  if window is None or (window_kind is not None and window["kind"] != window_kind):
173
  expected_window = "the " + window_kind if window_kind is not None else "a valid"
 
223
  return sorted(errors, key=lambda row: (str(row["sheet"]), row["address"]))
224
 
225
 
226
+ def excel_formula_error_census(book, *, sheet=SUMMARY_TAB):
227
+ """The ticket's five Excel codes, separate from the unchanged full error census."""
228
+ errors = []
229
+ for tab in book.get("sheets") or ():
230
+ if sheet is not None and tab.get("name") != sheet:
231
+ continue
232
+ for address, cell in (tab.get("cells") or {}).items():
233
+ if not isinstance(cell, dict) or cell.get("kind") != "formula":
234
+ continue
235
+ error = cell.get("error") or (cell.get("refusal") if cell.get("state") == "refused" else None)
236
+ if not error:
237
+ continue
238
+ code = error.get("code") if isinstance(error, dict) else str(error)
239
+ excel_code = error.get("excelCode") if isinstance(error, dict) else None
240
+ excel_code = excel_code or _EXCEL_ERROR_ALIASES.get(code, code)
241
+ if excel_code in TICKET_FORMULA_ERROR_CODES:
242
+ errors.append({"sheet": tab.get("name"), "address": address,
243
+ "code": code, "excelCode": excel_code})
244
+ return sorted(errors, key=lambda row: (str(row["sheet"]), row["address"]))
245
+
246
+
247
+ def check_summary_formula_errors(book):
248
+ """Count the real tab only after proving this same census finds planted errors.
249
+
250
+ The negative control is an isolated in-memory document, never a tenant edit. Exercise
251
+ both code spellings, excelCode precedence, and the refused-cell fallback on every call.
252
+ """
253
+ _tab(book, SUMMARY_TAB)
254
+ planted, expected = {}, {}
255
+ for internal, excel in (("bad_value", "#VALUE!"), ("div_zero", "#DIV/0!"),
256
+ ("invalid_reference", "#REF!"), ("no_match", "#N/A"),
257
+ ("unknown_name", "#NAME?")):
258
+ for field in ("error", "refusal"):
259
+ for payload in ({"code": internal, "excelCode": excel}, {"code": excel},
260
+ {"code": internal}, {"code": "probe", "excelCode": excel}):
261
+ address = "A" + str(len(planted) + 1)
262
+ planted[address] = {"kind": "formula", "state": "refused",
263
+ "formula": "=1/0", field: payload}
264
+ expected[address] = excel
265
+ for index, code in enumerate(("circular_reference", "blank", "#NUM!"), 1):
266
+ planted["B" + str(index)] = {"kind": "formula", "state": "refused",
267
+ "formula": "=1/0", "error": {"code": code}}
268
+ probe = {"sheets": [{"name": SUMMARY_TAB, "cells": planted},
269
+ {"name": "Summary (SR)", "cells": {"A1": planted["A1"]}}]}
270
+ found = excel_formula_error_census(probe)
271
+ if len(found) != len(expected) or {row["address"]: row["excelCode"] for row in found} != expected:
272
+ raise RepairRefusal("repair_formula_census_blind",
273
+ "The formula error census failed to find its planted errors.")
274
+ errors = excel_formula_error_census(book)
275
+ return {"sheet": SUMMARY_TAB, "codes": sorted(TICKET_FORMULA_ERROR_CODES),
276
+ "count": len(errors), "errors": errors,
277
+ "negative_control": {"planted": len(expected), "found": len(found)}}
278
+
279
+
280
+ def _formula_error_comparison(before, after, edits, reported_errors=()):
281
+ """Reject new errors anywhere and every residual error in explicitly planned cells.
282
+
283
+ Compare identities, not totals: fixing one cell cannot pay for breaking another. Code
284
+ aliases denote the same failure; unplanned cell changes still have their separate guard.
285
+ Opaque engine diagnostics cannot be matched to a pre-existing error and fail closed.
286
+ """
287
+ def identity(row):
288
+ if not isinstance(row, dict) or not row.get("sheet") or not row.get("address"):
289
+ return None
290
+ code = row.get("excelCode") or row.get("code")
291
+ return (str(row["sheet"]).casefold(), str(row["address"]).upper(),
292
+ _EXCEL_ERROR_ALIASES.get(code, code))
293
+
294
+ baseline = {identity(row) for row in formula_error_census(before)}
295
+ repaired = {(row["sheet"].casefold(), row["address"]) for row in edits}
296
+ introduced, remaining, unchanged, seen = [], [], [], set()
297
+ for row in [*formula_error_census(after), *reported_errors]:
298
+ key = identity(row)
299
+ if key is not None and key in seen:
300
+ continue
301
+ seen.add(key)
302
+ if key is None or key not in baseline:
303
+ introduced.append(copy.deepcopy(row))
304
+ if key is not None and key[:2] in repaired:
305
+ remaining.append(copy.deepcopy(row))
306
+ elif key is not None and key in baseline:
307
+ unchanged.append(copy.deepcopy(row))
308
+ return {"introduced": introduced, "remaining_in_repair": remaining,
309
+ "preexisting_elsewhere": unchanged}
310
+
311
+
312
  def _project(book, edits):
313
  projected = copy.deepcopy(book)
314
  for edit in edits:
 
341
  errors = list(result or ())
342
  before, after = _cell_map(projected), _cell_map(checked)
343
  planned = {(row["sheet"].casefold(), row["address"]): row for row in edits}
344
+ sheet_names = {str(tab.get("name") or "").casefold(): tab.get("name")
345
+ for tab in projected.get("sheets") or () if isinstance(tab, dict)}
346
  for slot in sorted(before.keys() | after.keys()):
347
  if before.get(slot) == after.get(slot):
348
  continue
349
  row = planned.get(slot)
350
+ if row is None or row["kind"] == "recalculated":
351
+ previous, recalculated = before.get(slot), after.get(slot)
352
+ # Recalculation may refresh a healthy formula's result, but may not repair
353
+ # an unrelated refused formula or change authored content or presentation.
354
+ if not all(isinstance(cell, dict) and cell.get("kind") == "formula"
355
+ and isinstance(cell.get("formula"), str)
356
+ and not cell.get("error") and not cell.get("refusal")
357
+ and cell.get("state") != "refused"
358
+ for cell in (previous, recalculated)) \
359
+ or previous.get("formula") != recalculated.get("formula") \
360
+ or {key: previous[key] for key in _VISUAL_CELL_KEYS if key in previous} \
361
+ != {key: recalculated[key] for key in _VISUAL_CELL_KEYS if key in recalculated}:
362
+ raise RepairRefusal(
363
+ "repair_unplanned_formula_change",
364
+ "Formula validation would change a cell outside the supplied source diff.")
365
+ desired = sheets.clean_cell(_preserve_visual(previous, recalculated), slot[1])
366
+ if row is None:
367
+ sheet = sheet_names[slot[0]]
368
+ row = {"kind": "recalculated", "name": sheet + "!" + slot[1],
369
+ "sheet": sheet, "address": slot[1],
370
+ "before": copy.deepcopy(previous), "after": desired}
371
+ edits.append(row)
372
+ planned[slot] = row
373
+ else:
374
+ row["after"] = desired
375
+ continue
376
+ if row is None or row["kind"] not in {"source", "derived"} \
377
  or not isinstance(row.get("after"), dict) \
378
  or row["after"].get("kind") != "formula":
379
  raise RepairRefusal(
 
381
  "Formula validation would change a cell outside the supplied source diff.")
382
  recalculated = after.get(slot)
383
  if not isinstance(recalculated, dict) \
384
+ or (row["kind"] == "source"
385
+ and recalculated.get("value") != row.get("cached_value")):
386
  raise RepairRefusal(
387
  "repair_formula_cache_mismatch",
388
  row["name"] + " does not recalculate to its supplied cached Excel value.")
 
394
  ]), errors
395
 
396
 
397
+ def summary_block_snapshot(book):
398
+ """Read-only QI3 pin. The lead saves this as proto/before/QI3-summary-block.json.
399
+
400
+ This is the measured F31:R35 extent, not a search for a plausible summary. Labels and
401
+ units are included in the evidence but are never proposed as edits.
402
+ """
403
+ tab = _tab(book, SUMMARY_TAB)
404
+ cells = tab.get("cells") or {}
405
+ labels = {28: ("C", "Invoice Data Metrics"), 30: ("D", "Total Sales"),
406
+ 31: ("D", "Current YTD"), 32: ("D", "Previous YTD"),
407
+ 33: ("D", "YTD Growth"), 34: ("D", "YTD Growth"),
408
+ 35: ("D", "YTD improvement")}
409
+ if book.get("id") != TARGET_WORKBOOK_ID or tab.get("id") != SUMMARY_TAB_ID or any(
410
+ str((cells.get(col + str(row)) or {}).get("value") or "").strip() != label
411
+ for row, (col, label) in labels.items()):
412
+ raise RepairRefusal("repair_summary_extent_mismatch",
413
+ "The workbook does not match the pinned Invoice Data Metrics block.")
414
+ addresses = {col + str(row) for col in ("D", "E", *SUMMARY_COLUMNS)
415
+ for row in range(31, 36)} | {"C28", "D30", "D10"}
416
+ addresses |= {col + str(row) for col in SUMMARY_COLUMNS for row in (5, 6, 7)}
417
+ addresses |= {addr for addr in cells if re.fullmatch(r"[A-Z]+2", addr)}
418
+ return {"workbook_id": book["id"], "revision": book.get("rev"),
419
+ "workbook_digest": sheets.workbook_digest(book), "sheet": SUMMARY_TAB,
420
+ "sheet_id": tab["id"], "figure_extent": "F31:R35", "figure_count": 65,
421
+ "cells": {addr: copy.deepcopy(cells.get(addr)) for addr in sorted(addresses)}}
422
+
423
+
424
+ def _summary_value(book, address):
425
+ cell = (_tab(book, SUMMARY_TAB).get("cells") or {}).get(address) or {}
426
+ if cell.get("error") or cell.get("state") == "refused":
427
+ raise RepairRefusal("repair_summary_input_unreadable",
428
+ "Summary input " + address + " has a calculation error.")
429
+ return cell.get("value")
430
+
431
+
432
+ def _summary_date(value):
433
+ try:
434
+ return date.fromisoformat(str(value))
435
+ except ValueError as exc:
436
+ raise RepairRefusal("repair_summary_date_invalid",
437
+ "Every summary date must be a real ISO date from the sheet or mirror.") from exc
438
+
439
+
440
+ def _resolved(binding, book, resolve_binding):
441
+ if not callable(resolve_binding):
442
+ raise RepairRefusal("repair_binding_resolver_required", "The summary needs its scoped source resolver.")
443
+ result = resolve_binding(copy.deepcopy(binding), book, _tab(book, SUMMARY_TAB))
444
+ if not isinstance(result, dict) or "value" not in result or result.get("value") is None:
445
+ raise RepairRefusal("repair_binding_unreadable", "A summary source did not return a value.")
446
+ if result.get("limits"):
447
+ # The route wraps this exception, retaining its message but not custom attributes.
448
+ # Include each cause and fix there too; upstream clause separators become sentences.
449
+ details = []
450
+ for limit in result["limits"]:
451
+ if isinstance(limit, dict):
452
+ cause = str(limit.get("cause") or "The source reported an incomplete answer.")
453
+ fix = str(limit.get("recommendation") or "Repair the source scope and retry.")
454
+ details.append("Cause: " + cause + " Recommended fix: " + fix)
455
+ detail = " ".join(details).replace(chr(8212), ". ").replace(chr(8211), " to ")
456
+ exc = RepairRefusal("repair_binding_limited",
457
+ "A summary source could not apply its complete scope. " + detail)
458
+ exc.limits = copy.deepcopy(result["limits"])
459
+ raise exc
460
+ return result["value"]
461
+
462
+
463
+ def _summary_formula_projection(book, edits, formula_check):
464
+ if not callable(formula_check):
465
+ raise RepairRefusal("repair_formula_engine_required",
466
+ "The summary requires the real document formula engine.")
467
+ result = formula_check(copy.deepcopy(book))
468
+ if not isinstance(result, dict) or not isinstance(result.get("book"), dict):
469
+ raise RepairRefusal("repair_formula_engine_required",
470
+ "Formula validation must return the calculated document.")
471
+ # Only adopt planned formulas here. The final whole-document projection records healthy
472
+ # downstream recalculations as exact edits and refuses every other unplanned change.
473
+ for row in edits:
474
+ if row["kind"] == "derived":
475
+ cell = (_tab(result["book"], row["sheet"]).get("cells") or {}).get(row["address"])
476
+ if not isinstance(cell, dict) or cell.get("kind") != "formula" or cell.get("error") \
477
+ or cell.get("state") != "fresh":
478
+ raise RepairRefusal("repair_formula_errors",
479
+ "Summary formula " + row["address"] + " could not calculate.")
480
+ row["after"] = sheets.clean_cell(cell, row["address"])
481
+ return _project(book, edits)
482
+
483
+
484
+ def _append_summary_ratio_plan(current, edits, formula_check):
485
+ """Plan the measured roots and let the real engine decide cascade blank handling."""
486
+ if not callable(formula_check):
487
+ raise RepairRefusal("repair_formula_engine_required",
488
+ "The ratio repair requires the real document formula engine.")
489
+ cells = _tab(current, SUMMARY_TAB).get("cells") or {}
490
+ planned = {(row["sheet"].casefold(), row["address"]) for row in edits}
491
+ ratios = {}
492
+ for address, authored in {**_SUMMARY_RATIO_ROOTS, **_SUMMARY_RATIO_CASCADES}.items():
493
+ before = copy.deepcopy(cells.get(address))
494
+ guarded = '=IFERROR(' + authored[1:] + ',"")'
495
+ if not isinstance(before, dict) or before.get("kind") != "formula" \
496
+ or before.get("formula") not in (authored, guarded):
497
+ raise RepairRefusal("repair_ratio_formula_mismatch",
498
+ "The measured ratio formula has changed at " + address + ".")
499
+ if (SUMMARY_TAB.casefold(), address) in planned:
500
+ raise RepairRefusal("repair_edit_duplicate", "A repair cell may be named only once.")
501
+ desired = copy.deepcopy(before)
502
+ for key in ("value", "display", "error", "refusal"):
503
+ desired.pop(key, None)
504
+ desired.update(state="stale", formula=(guarded if address in _SUMMARY_RATIO_ROOTS
505
+ else before["formula"]))
506
+ row = {"kind": "derived", "name": SUMMARY_TAB + "!" + address,
507
+ "sheet": SUMMARY_TAB, "address": address, "before": before,
508
+ "after": sheets.clean_cell(_preserve_visual(before, desired), address)}
509
+ edits.append(row)
510
+ ratios[address] = row
511
+ result = formula_check(_project(current, edits))
512
+ if not isinstance(result, dict) or not isinstance(result.get("book"), dict):
513
+ raise RepairRefusal("repair_formula_engine_required",
514
+ "Formula validation must return the calculated document.")
515
+ calculated = _tab(result["book"], SUMMARY_TAB).get("cells") or {}
516
+ guarded_cascades = []
517
+ for address, authored in _SUMMARY_RATIO_CASCADES.items():
518
+ cell = calculated.get(address) or {}
519
+ error = cell.get("error") or (cell.get("refusal") if cell.get("state") == "refused" else None)
520
+ # The current engine refuses arithmetic over IFERROR's empty string as `blank`.
521
+ # Only that observed refusal authorizes wrapping a cascade; other failures remain
522
+ # visible to the existing projection refusal. Never replace a formula with a value.
523
+ if isinstance(error, dict) and error.get("code") == "blank":
524
+ ratios[address]["after"]["formula"] = '=IFERROR(' + authored[1:] + ',"")'
525
+ guarded_cascades.append(address)
526
+ return {"roots": list(_SUMMARY_RATIO_ROOTS), "guarded_cascades": guarded_cascades}
527
+
528
+
529
+ def _build_summary_plan(current, request, resolve_binding, formula_check):
530
+ """Build all 65 figures, date/scope helpers and guarded ratios, without tenant writes.
531
+
532
+ summary_block carries before=summary_block_snapshot(current), pricelist, the complete
533
+ partner_ids behind customer_link, and validate_invoice=modules.sheet.validate. The last
534
+ is a callable injected by the trusted operator (this workflow has no HTTP route).
535
+ No core-to-modules/API import or second source-query door is needed.
536
+ """
537
+ summary = request["summary_block"]
538
+ if not isinstance(summary, dict) or summary.get("before") != summary_block_snapshot(current):
539
+ raise RepairRefusal("repair_summary_pin_required",
540
+ "The summary requires the exact before snapshot recorded by the lane lead.")
541
+ if request.get("source_cells") or request.get("binding_cells"):
542
+ raise RepairRefusal("repair_summary_plan_conflict",
543
+ "Run the workbook-derived summary separately from an Excel source-oracle repair.")
544
+ if not str(request.get("refreshed_at") or "").strip():
545
+ raise RepairRefusal("repair_timestamp_required", "The summary needs an explicit refresh timestamp.")
546
+ cells = _tab(current, SUMMARY_TAB).get("cells") or {}
547
+ # Allocate four fully empty rows inside the existing sheet dimensions. Never overwrite
548
+ # authored content, add a tab, resize the sheet, or change hidden/print/visual metadata.
549
+ tab_rows = int(_tab(current, SUMMARY_TAB).get("rows") or 0)
550
+ helper_row = next((row for row in range(tab_rows - 3, 35, -1)
551
+ if all((cells.get(col + str(r)) or {}).get("kind", "empty") == "empty"
552
+ for r in range(row, row + 4) for col in SUMMARY_COLUMNS)), None)
553
+ if helper_row is None:
554
+ raise RepairRefusal("repair_summary_helper_space",
555
+ "The summary needs four empty rows in its existing sheet for date and scope formulas.")
556
+ edits = []
557
+
558
+ def add(address, desired, kind):
559
+ before = copy.deepcopy(cells.get(address))
560
+ edits.append({"kind": kind, "name": SUMMARY_TAB + "!" + address,
561
+ "sheet": SUMMARY_TAB, "address": address, "before": before,
562
+ "after": sheets.clean_cell(_preserve_visual(before, desired), address)})
563
+
564
+ def formula(address, text):
565
+ add(address, {"kind": "formula", "state": "stale", "formula": text}, "derived")
566
+
567
+ scope_ref = "F" + str(helper_row + 3)
568
+ formula(scope_ref, '=IF($D$10="RI","Royal 1 (USD)",IF($D$10="FFS","Fisch (USD)",NA()))')
569
+ windows = {}
570
+ for col in SUMMARY_COLUMNS:
571
+ end = _summary_date(_summary_value(current, col + "7"))
572
+ year_refs = [addr for addr, cell in cells.items() if re.fullmatch(r"[A-Z]+2", addr)
573
+ and str((cell or {}).get("value")) in {str(end.year), str(float(end.year))}]
574
+ # The year can be one merged/shared header. Prefer this column, otherwise require
575
+ # an unambiguous year cell; never guess between two independent calendar headers.
576
+ year_ref = col + "2" if col + "2" in year_refs else year_refs[0] if len(year_refs) == 1 else None
577
+ if not year_ref:
578
+ raise RepairRefusal("repair_summary_year_ambiguous",
579
+ "The summary needs an unambiguous year on row 2 for column " + col + ".")
580
+ first, previous_first, previous_end = (col + str(helper_row + offset) for offset in range(3))
581
+ # DATE/EDATE already return ISO dates. String concatenation preserves that value
582
+ # without introducing an inferred date style on a previously blank helper cell.
583
+ formula(first, '=DATE(' + year_ref + ',1,1)&""')
584
+ formula(previous_first, '=DATE(' + year_ref + '-1,1,1)&""')
585
+ formula(previous_end, '=EDATE(' + col + '7,-12)&""')
586
+ windows[col] = ((first, col + "7"), (previous_first, previous_end))
587
+ projected = _summary_formula_projection(_project(current, edits), edits, formula_check)
588
+ if _summary_value(projected, scope_ref) != summary.get("pricelist"):
589
+ raise RepairRefusal("repair_summary_partner_scope",
590
+ "The supplied partner set must use the pricelist computed from D10.")
591
+ partners = summary.get("partner_ids")
592
+ if not isinstance(partners, list) or any(type(pid) is not int or pid <= 0 for pid in partners) \
593
+ or len(set(partners)) != len(partners):
594
+ raise RepairRefusal("repair_summary_partner_scope",
595
+ "Supply every joined partner ID once, with no source row limit.")
596
+ if not callable(summary.get("validate_invoice")):
597
+ raise RepairRefusal("repair_summary_validator_required",
598
+ "Inject modules.sheet.validate for independent invoice reconciliation.")
599
+ as_of = _summary_date(_resolved({"database": "ut_odoo_invoices",
600
+ "aggregate": {"kind": "column", "fn": "max", "field": "invoice_date"},
601
+ "scope": {"filter": {"conj": "and", "nodes": []}}},
602
+ projected, resolve_binding))
603
+ for col, ranges in windows.items():
604
+ for row_number, (first, last) in zip((31, 32), ranges):
605
+ binding = {"database": "ut_odoo_invoices",
606
+ "aggregate": {"field": "amount_untaxed", "fn": "sum", "kind": "column"},
607
+ "scope": {"filter": {"conj": "and", "nodes": [
608
+ {"colId": "invoice_date", "op": "gte", "valueRef": {"ref": first}},
609
+ {"colId": "invoice_date", "op": "lte", "valueRef": {"ref": last}},
610
+ {"colId": "move_type", "op": "eq", "value": "out_invoice"}]}},
611
+ "related": {"via": "customer_link", "filter": {"conj": "and", "nodes": [
612
+ {"colId": "pricelist", "op": "eq", "valueRef": {"ref": scope_ref}}]}}}
613
+ _validate_binding(col + str(row_number), binding)
614
+ value = _resolved(binding, projected, resolve_binding)
615
+ if type(value) not in (int, float) or not math.isfinite(value):
616
+ raise RepairRefusal("repair_binding_unreadable", "An invoice total must be a finite number.")
617
+ add(col + str(row_number), {"kind": "bound", "state": "fresh", "binding": binding,
618
+ "value": value, "display": str(value),
619
+ "refreshed_at": request["refreshed_at"]}, "binding")
620
+ from openpyxl.formula.translate import Translator
621
+ for row_number in range(33, 36):
622
+ origin = "F" + str(row_number)
623
+ source = cells.get(origin) or {}
624
+ if source.get("kind") != "formula" or not str(source.get("formula") or "").startswith("="):
625
+ raise RepairRefusal("repair_summary_formula_missing",
626
+ "The summary requires its authored formula at " + origin + ".")
627
+ for col in SUMMARY_COLUMNS:
628
+ address = col + str(row_number)
629
+ try:
630
+ text = Translator(source["formula"], origin=origin).translate_formula(address)
631
+ except Exception as exc:
632
+ raise RepairRefusal("repair_summary_formula_translate",
633
+ "The authored summary formula could not be filled across.") from exc
634
+ formula(address, text)
635
+ ratio_evidence = _append_summary_ratio_plan(current, edits, formula_check)
636
+ projected = _summary_formula_projection(_project(current, edits), edits, formula_check)
637
+ checks = validate(projected, windows=windows, mirror_as_of=as_of.isoformat(),
638
+ partner_ids=partners, invoice_validate=summary["validate_invoice"],
639
+ formula_check=formula_check)
640
+ return edits, {"before": summary["before"], "helper_rows": list(range(helper_row, helper_row + 4)),
641
+ "pricelist_cell": scope_ref, "mirror_as_of": as_of.isoformat(),
642
+ "partner_count": len(partners), "checks": checks,
643
+ "ratio_repair": ratio_evidence}
644
+
645
+
646
+ def validate(book, *, windows, mirror_as_of, partner_ids, invoice_validate, formula_check):
647
+ """Reconcile 26 invoice figures and 39 formulas against independent Odoo results.
648
+
649
+ Windows are read from the planned sheet, with each upper bound capped at the mirror's
650
+ max(invoice_date). Re-evaluate the authored formulas over the independent amounts too.
651
+ Invoice-date bounding is not a historical snapshot; preserve validate()'s limitation rows.
652
+ """
653
+ proof, checks = copy.deepcopy(book), []
654
+ as_of = _summary_date(mirror_as_of)
655
+ for col in SUMMARY_COLUMNS:
656
+ for row_number, (first_ref, last_ref) in zip((31, 32), windows[col]):
657
+ first = _summary_date(_summary_value(book, first_ref))
658
+ last = min(_summary_date(_summary_value(book, last_ref)), as_of)
659
+ if first > last:
660
+ raise RepairRefusal("repair_summary_asof_before_window",
661
+ "The invoice mirror ends before a summary window begins. Refresh it first.")
662
+ address = col + str(row_number)
663
+ observed = _summary_value(book, address)
664
+ rows = invoice_validate(first.isoformat(), last.isoformat(), {"invoiced_sales": observed},
665
+ team_id=None, partner_ids=list(partner_ids),
666
+ basis="invoice", include_refunds=False)
667
+ if not isinstance(rows, list) or len(rows) != 1 or rows[0].get("check") != "invoiced_sales" \
668
+ or rows[0].get("ok") is not True or rows[0].get("a") != observed \
669
+ or type(rows[0].get("b")) not in (int, float) or not math.isfinite(rows[0]["b"]) \
670
+ or abs(observed - rows[0]["b"]) > 0.01:
671
+ exc = RepairRefusal("repair_summary_reconciliation",
672
+ "Independent Odoo reconciliation failed for " + address + ".")
673
+ exc.checks = copy.deepcopy(rows)
674
+ raise exc
675
+ checks.append({**copy.deepcopy(rows[0]), "address": address,
676
+ "date_from": first.isoformat(), "date_to": last.isoformat()})
677
+ _tab(proof, SUMMARY_TAB)["cells"][address]["value"] = rows[0]["b"]
678
+ result = formula_check(proof)
679
+ proof = result["book"]
680
+ for col in SUMMARY_COLUMNS:
681
+ for row_number in range(33, 36):
682
+ address = col + str(row_number)
683
+ actual, expected = _summary_value(book, address), _summary_value(proof, address)
684
+ ok = (type(actual) in (int, float) and type(expected) in (int, float)
685
+ and math.isfinite(actual) and math.isfinite(expected)
686
+ and abs(actual - expected) <= (0.01 if row_number == 33 else 1e-9))
687
+ checks.append({"check": "invoice_derived", "address": address, "a": actual,
688
+ "b": expected, "gap": actual - expected if ok else None, "ok": ok})
689
+ if not ok:
690
+ raise RepairRefusal("repair_summary_reconciliation",
691
+ "The summary formula did not reconcile for " + address + ".")
692
+ return checks
693
+
694
+
695
  def _build_plan(current, request, resolve_binding):
696
  if not isinstance(request.get("source_cells"), list) or not request["source_cells"]:
697
  raise RepairRefusal(
 
884
  raise RepairRefusal("repair_revision_mismatch",
885
  "The named workbook is not at the expected repair revision.")
886
  digest = sheets.workbook_digest(current)
887
+ summary_evidence = None
888
+ summary_errors_before = None
889
+ if "summary_block" in request:
890
+ summary_errors_before = check_summary_formula_errors(current)
891
+ edits, summary_evidence = _build_summary_plan(current, request, resolve_binding, formula_check)
892
+ else:
893
+ edits = _build_plan(current, request, resolve_binding)
894
  projected = _project(current, edits)
895
  projected, projected_errors = _checked_projection(projected, edits, formula_check)
896
+ comparison = _formula_error_comparison(current, projected, edits, projected_errors)
897
+ summary_errors_after = (check_summary_formula_errors(projected)
898
+ if summary_evidence is not None else None)
899
+ if comparison["introduced"] or comparison["remaining_in_repair"] \
900
+ or (summary_errors_after is not None and summary_errors_after["count"]):
901
  raise RepairRefusal(
902
  "repair_formula_errors",
903
+ "The projected repair introduces a formula error or leaves one in its repair scope, "
904
+ "so no repair was applied.")
905
  visual_before = visual_metadata(current)
906
  if visual_metadata(projected) != visual_before:
907
  raise RepairRefusal("repair_visual_metadata_changed",
 
927
  raise RepairRefusal("repair_readback_cell",
928
  row["sheet"] + "!" + row["address"] + " did not read back exactly.")
929
  checked_readback, readback_errors = _checked_projection(readback, copy.deepcopy(edits), formula_check)
930
+ readback_comparison = _formula_error_comparison(current, checked_readback, edits, readback_errors)
931
+ summary_errors_readback = (check_summary_formula_errors(checked_readback)
932
+ if summary_evidence is not None else None)
933
+ if readback_comparison["introduced"] or readback_comparison["remaining_in_repair"] \
934
+ or (summary_errors_readback is not None and summary_errors_readback["count"]) \
935
+ or _cell_map(checked_readback) != _cell_map(readback):
936
  raise RepairRefusal("repair_readback_formula_state",
937
  "The repaired workbook did not read back calculation-current.")
938
  if visual_metadata(readback) != visual_before:
939
  raise RepairRefusal("repair_readback_visual_metadata",
940
  "Daily Sales visual metadata changed during repair.")
941
+ if summary_evidence is not None:
942
+ tab = _tab(readback, SUMMARY_TAB)
943
+ if any((tab.get("cells", {}).get(col + str(row)) or {}).get("kind")
944
+ != ("bound" if row in (31, 32) else "formula")
945
+ for col in SUMMARY_COLUMNS for row in range(31, 36)):
946
+ raise RepairRefusal("repair_summary_readback_kind",
947
+ "Every summary figure must read back as its planned binding or formula.")
948
+ summary_evidence["readback"] = summary_block_snapshot(readback)
949
+ summary_evidence["formula_error_check"] = {
950
+ "before": summary_errors_before, "projected": summary_errors_after,
951
+ "readback": summary_errors_readback,
952
+ }
953
 
954
  source_readback = {row["name"]: copy.deepcopy(
955
  (_tab(readback, row["sheet"]).get("cells") or {}).get(row["address"]))
 
957
  bindings = {row["name"]: copy.deepcopy(
958
  ((_tab(readback, row["sheet"]).get("cells") or {}).get(row["address"]) or {}).get("binding"))
959
  for row in edits if row["kind"] == "binding"}
960
+ result = {
961
  "workbook_id": target_workbook_id,
962
  "revision_before": revision,
963
  "revision_after": readback["rev"],
 
969
  "source_cells": source_readback,
970
  "bindings": bindings,
971
  "formula_errors": formula_error_census(readback),
972
+ "formula_error_comparison": readback_comparison,
973
  "visual_metadata_preserved": True,
974
  }
975
+ if summary_evidence is not None:
976
+ result["summary_block"] = summary_evidence
977
+ return result
platform/core/registry.py CHANGED
@@ -229,6 +229,53 @@ REGISTRY = [
229
  BY_KEY = {m['key']: m for m in REGISTRY}
230
 
231
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
232
  def brand_filterable(key) -> bool:
233
  return bool(BY_KEY.get(key, {}).get('brand'))
234
 
 
229
  BY_KEY = {m['key']: m for m in REGISTRY}
230
 
231
 
232
+ # Source policies - the single source of truth for connector database set-up.
233
+ #
234
+ # The API resolves eligibility from these rows and each source's registered analysis. Adding a
235
+ # source = add one row here + its provider and analysis in the connector's app layer. This is
236
+ # DATA ONLY: core knows neither the mirror nor the API, and imports neither to answer a policy.
237
+ #
238
+ # Fields:
239
+ # key stable source id (matches its registered analysis)
240
+ # label human name
241
+ # prefixes tuple of owned table-key prefixes; the longest matching prefix wins
242
+ # max_rows materialised-home ceiling, or None to use the store default; never an ingest cap
243
+ # window_max whole-table window ceiling, or None to use the datastore default
244
+ # rank_ops "client" or "server": where set-level rank operators are evaluated
245
+ # candidates "declared": only provider-returned grains; "prefix": every owned database
246
+ #
247
+ # None preserves the existing ceilings. Declared candidates preserve the existing grain set;
248
+ # a prefix identifies the policy owner without making an undeclared database read-through.
249
+ SOURCE_POLICIES = [
250
+ {'key': 'odoo', 'label': 'Odoo', 'prefixes': ('ut_odoo_',),
251
+ 'max_rows': None, 'window_max': None, 'rank_ops': 'client', 'candidates': 'declared'},
252
+ {'key': 'amazon', 'label': 'Amazon', 'prefixes': ('ut_amazon_',),
253
+ 'max_rows': None, 'window_max': None, 'rank_ops': 'client', 'candidates': 'declared'},
254
+ {'key': 'meta_ads', 'label': 'Meta Ads', 'prefixes': ('ut_meta_',),
255
+ 'max_rows': None, 'window_max': None, 'rank_ops': 'client', 'candidates': 'declared'},
256
+ ]
257
+ DEFAULT_SOURCE_POLICY = {
258
+ 'key': 'default', 'label': 'Default', 'prefixes': (),
259
+ 'max_rows': None, 'window_max': None, 'rank_ops': 'client', 'candidates': 'declared',
260
+ }
261
+
262
+
263
+ def source_policy(table_key):
264
+ """The source row owning this key, or DEFAULT_SOURCE_POLICY when no prefix matches."""
265
+ key = str(table_key or '')
266
+ match, longest = DEFAULT_SOURCE_POLICY, -1
267
+ for row in SOURCE_POLICIES:
268
+ for prefix in row['prefixes']:
269
+ if key.startswith(prefix) and len(prefix) > longest:
270
+ match, longest = row, len(prefix)
271
+ return match
272
+
273
+
274
+ def source_policies():
275
+ """The declared source rows, in declaration order; the fallback row is separate."""
276
+ return tuple(SOURCE_POLICIES)
277
+
278
+
279
  def brand_filterable(key) -> bool:
280
  return bool(BY_KEY.get(key, {}).get('brand'))
281
 
platform/core/sheet_binding.py CHANGED
@@ -1,18 +1,147 @@
1
- """Pure document cleaners shared by Sheet storage and Sheet query resolution.
2
 
3
- These functions decide only what binding metadata may be stored. They do not resolve data,
4
- permissions, or SQL. Keeping them in core lets the workbook document validate view bindings
5
- without importing the higher ``modules.sheet`` layer.
6
  """
7
 
8
  from __future__ import annotations
9
 
10
  import datetime
 
 
11
  import re
 
12
 
13
  from core import windows as W
14
 
15
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
16
  PERIOD_UNITS = ("day", "week", "month", "quarter", "year")
17
  PERIOD_START = re.compile(r"^\d{4}-(0[1-9]|1[0-2])$")
18
  PERIOD_DAY = re.compile(r"^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$")
@@ -21,6 +150,7 @@ DRAG_ACROSS = ("period", "none")
21
  DRAG_DOWN_NONE = "none"
22
 
23
  _MESSAGES = {
 
24
  "period_invalid": "{subject} is not a period this cell can use. Choose a valid start for the selected period unit.",
25
  "period_window_invalid": "This cell's lookback window is invalid. Choose a valid window in the period control.",
26
  "ending_invalid": "Ending {subject} cannot be used. Choose a valid ending date.",
@@ -45,6 +175,58 @@ class BindingMetadataRefusal(Exception):
45
  f"cannot be {verb}.", f"cannot be {verb} because {self.detail}")
46
 
47
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
48
  def clean_period(raw):
49
  """Return one canonical Sheet period, or ``None`` when no window was named."""
50
  if not isinstance(raw, dict):
 
1
+ """Binding metadata and server-owned Refresh snapshots shared by Sheet storage and routes.
2
 
3
+ Cleaners remain independent of query resolution. Change-token readers fingerprint source
4
+ state without assembling a database or evaluating an individual cell binding.
 
5
  """
6
 
7
  from __future__ import annotations
8
 
9
  import datetime
10
+ import hashlib
11
+ import json
12
  import re
13
+ from copy import deepcopy
14
 
15
  from core import windows as W
16
 
17
 
18
+ def fingerprint(value):
19
+ return hashlib.sha256(json.dumps(value, sort_keys=True, default=str,
20
+ separators=(",", ":")).encode()).hexdigest()
21
+
22
+
23
+ def database_change_token(st, database):
24
+ """Read a database fingerprint, without assembling rows or resolving a binding.
25
+
26
+ Authored databases share one JSON document. Its bucket revision cannot distinguish
27
+ siblings, so Postgres hashes the selected member IN the database and returns only a
28
+ token and row-free definition. This also sees connector writers which bypass the
29
+ ordinary row/field API. The HF adapter hashes the same documents locally.
30
+ """
31
+ from core import connector_sync, schema_overlay, store_pg, user_tables
32
+ workspace = {"customer_data": "customer_table_workspace",
33
+ "product_data": "product_table_workspace"}.get(
34
+ database, database + "_table_workspace")
35
+ shared = database if database.startswith("ut_") else workspace
36
+ buckets = [workspace, shared + "__shared"]
37
+ handle = st._store() if callable(getattr(st, "_store", None)) else st
38
+ if isinstance(handle, store_pg.PgStore):
39
+ key = getattr(st, "store_key", str)
40
+ # Values stay on the server. No row JSON crosses the connection on this path.
41
+ with store_pg._pool().connection() as con:
42
+ row = con.execute(store_pg._q(
43
+ "WITH source AS (SELECT value -> %s AS d FROM {tbl} WHERE key = %s) "
44
+ "SELECT md5(COALESCE((SELECT d::text FROM source), 'null') || "
45
+ "COALESCE((SELECT jsonb_object_agg(key, rev ORDER BY key)::text "
46
+ "FROM {tbl} WHERE key = ANY(%s)), 'null') || "
47
+ "COALESCE((SELECT (value -> %s)::text FROM {tbl} WHERE key = %s), 'null') || "
48
+ "COALESCE((SELECT (value -> %s)::text FROM {tbl} WHERE key = %s), 'null') || "
49
+ "COALESCE((SELECT jsonb_object_agg(e.key, e.value ORDER BY e.key)::text "
50
+ "FROM {tbl} kv, jsonb_each(kv.value) e WHERE kv.key = %s "
51
+ "AND e.value ->> 'databaseKey' = %s), 'null') || "
52
+ "COALESCE((SELECT jsonb_path_query_array(value, "
53
+ "'$.*.* ? (@.databases[*] == $db)', jsonb_build_object('db', %s::text))::text "
54
+ "FROM {tbl} WHERE key = %s), 'null')), "
55
+ "(SELECT d - 'rows' FROM source)", "store_kv", handle.tenant_slug),
56
+ (database, key(user_tables.STORE_KEY), [key(b) for b in buckets],
57
+ database, key(user_tables.ZONE_STORE_KEY), database, key(schema_overlay.STORE_KEY),
58
+ key(connector_sync.JOBS_KEY), database,
59
+ database, key(connector_sync.STATE_KEY))).fetchone()
60
+ token, definition = row[0], row[1] or {}
61
+ else:
62
+ definition = (st.get(user_tables.STORE_KEY, fresh=True) or {}).get(database) or {}
63
+ jobs = st.get(connector_sync.JOBS_KEY, fresh=True) or {}
64
+ states = st.get(connector_sync.STATE_KEY, fresh=True) or {}
65
+ token = fingerprint([definition, *(st.get(b, fresh=True) for b in buckets),
66
+ (st.get(user_tables.ZONE_STORE_KEY, fresh=True) or {}).get(database),
67
+ (st.get(schema_overlay.STORE_KEY, fresh=True) or {}).get(database),
68
+ {k: v for k, v in jobs.items() if v.get("databaseKey") == database},
69
+ [v for provider in sorted(states) for _, v in sorted(states[provider].items())
70
+ if database in (v.get("databases") or [])]])
71
+ # Registry topics and read-through connectors live in the observation plane. Sync
72
+ # receipts have second precision, so also fingerprint source content. A file-wide
73
+ # mtime would invalidate every database when just one source changed.
74
+ mirror = not definition or not user_tables.materialises(database, defn=definition)
75
+ if mirror:
76
+ token = fingerprint([token, mirror_change_token(st, database)])
77
+ return token
78
+
79
+
80
+ def mirror_change_token(st, database):
81
+ """One SQL token read over source tables, not N binding queries or Python row copies.
82
+
83
+ The current mirror has no per-table monotonic revision. Content fingerprints close
84
+ that gap without changing its writer or adding a row cap. Count, xor and sum include
85
+ entire records; schema and sync receipts cover field changes and no-op syncs too.
86
+ Registry metrics depend on the Odoo observation set, so their token includes it.
87
+ """
88
+ from core import connector_spec
89
+ from harness import datastore
90
+ from harness.runtime import mirror_cursor
91
+ spec = connector_spec.spec_for(database)
92
+ if database in ("customer_data", "product_data"):
93
+ sources = set(datastore.ENTITIES)
94
+ elif spec:
95
+ sources = {spec.source}
96
+ # A connector grid also reads joined label/identity columns declared by its spec.
97
+ sources.update(target.source for _, key, _, _ in spec.links
98
+ if (target := connector_spec.spec_for(key)) is not None)
99
+ else:
100
+ raise RuntimeError("The connector has no declared source for its change token.")
101
+ if not sources or any(not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", s) for s in sources):
102
+ raise RuntimeError("The connector source identity is invalid.")
103
+ sources = sorted(sources)
104
+ receipt_sources = sorted(set(sources) | ({"meta"} if any(s.startswith("meta_") for s in sources) else set()))
105
+ clauses = [f"SELECT '{source}' AS source, CAST(count(*) AS VARCHAR) AS n, "
106
+ f"CAST(bit_xor(hash(t)) AS VARCHAR) AS x, "
107
+ f"CAST(sum(CAST(hash(t) AS HUGEINT)) AS VARCHAR) AS s FROM \"{source}\" t"
108
+ for source in sources]
109
+ placeholders = ",".join("?" for _ in sources)
110
+ clauses.append("SELECT 'schema', table_name, column_name, data_type FROM duckdb_columns() "
111
+ f"WHERE table_name IN ({placeholders})")
112
+ # _sync_state is the resident mirror writer's receipt, not the app's status cache.
113
+ clauses.append("SELECT 'sync', entity, phase, concat_ws('|', last_id, cursor_wd, rows, updated_at) "
114
+ "FROM _sync_state WHERE split_part(entity, '.', 1) IN ("
115
+ + ",".join("?" for _ in receipt_sources) + ")")
116
+ rows = mirror_cursor(st).execute(" UNION ALL ".join(clauses) + " ORDER BY 1,2,3,4",
117
+ [*sources, *receipt_sources]).fetchall()
118
+ if not any(row[0] == "sync" for row in rows):
119
+ raise RuntimeError("The connector has no sync receipt.")
120
+ return fingerprint(rows)
121
+
122
+
123
+ def read_refresh_cache(st, workbook_id):
124
+ from core import sheets
125
+ return st.get(sheets._scope_cache_key(workbook_id), fresh=True) or {}
126
+
127
+
128
+ def save_refresh_cache(st, workbook_id, entries, databases):
129
+ """Server-only snapshots; ordinary workbook PUT/PATCH cannot manufacture these slots."""
130
+ from core import sheets
131
+
132
+ def apply(doc):
133
+ cells = doc.setdefault("refreshCells", {})
134
+ for cell_key, scope_key, entry in entries:
135
+ slots = cells.setdefault(cell_key, {})
136
+ if scope_key not in slots and len(slots) >= sheets._MAX_SCOPE_ENTRIES_PER_CELL:
137
+ slots.pop(next(iter(slots)))
138
+ slots[scope_key] = deepcopy(entry)
139
+ sheets._merge_data_origins(doc, databases=databases)
140
+ return doc, None
141
+
142
+ sheets._persist(st, sheets._scope_cache_key(workbook_id), apply)
143
+
144
+
145
  PERIOD_UNITS = ("day", "week", "month", "quarter", "year")
146
  PERIOD_START = re.compile(r"^\d{4}-(0[1-9]|1[0-2])$")
147
  PERIOD_DAY = re.compile(r"^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$")
 
150
  DRAG_DOWN_NONE = "none"
151
 
152
  _MESSAGES = {
153
+ "related_invalid": "Choose one declared relationship and a valid filter tree for this cell.",
154
  "period_invalid": "{subject} is not a period this cell can use. Choose a valid start for the selected period unit.",
155
  "period_window_invalid": "This cell's lookback window is invalid. Choose a valid window in the period control.",
156
  "ending_invalid": "Ending {subject} cannot be used. Choose a valid ending date.",
 
175
  f"cannot be {verb}.", f"cannot be {verb} because {self.detail}")
176
 
177
 
178
+ def clean_related(raw):
179
+ """One declared edge key and a structurally valid, losslessly copied filter tree.
180
+
181
+ Absence is handled by the caller. An explicitly supplied null is malformed, as are
182
+ extra relationship bags and nested relationships. Operator support belongs to the
183
+ query compiler, which reports unpushable conditions rather than dropping metadata.
184
+ """
185
+ def refuse():
186
+ raise BindingMetadataRefusal("related_invalid")
187
+
188
+ if not isinstance(raw, dict) or set(raw) != {"via", "filter"}:
189
+ refuse()
190
+ via = raw["via"]
191
+ if not isinstance(via, str) or not via.strip():
192
+ refuse()
193
+
194
+ def reject_nested(value):
195
+ if isinstance(value, dict):
196
+ if "related" in value:
197
+ refuse()
198
+ for child in value.values():
199
+ reject_nested(child)
200
+ elif isinstance(value, list):
201
+ for child in value:
202
+ reject_nested(child)
203
+
204
+ reject_nested(raw["filter"])
205
+
206
+ def nodes_ok(nodes):
207
+ if not isinstance(nodes, list):
208
+ refuse()
209
+ for node in nodes:
210
+ if not isinstance(node, dict) or "related" in node:
211
+ refuse()
212
+ if "children" in node:
213
+ if ("colId" in node or node.get("conj", "and") not in ("and", "or")):
214
+ refuse()
215
+ nodes_ok(node["children"])
216
+ elif (not isinstance(node.get("colId"), str) or not node["colId"].strip()
217
+ or not isinstance(node.get("op"), str) or not node["op"].strip()):
218
+ refuse()
219
+
220
+ tree = raw["filter"]
221
+ if isinstance(tree, dict):
222
+ if set(tree) - {"nodes", "conj"} or tree.get("conj", "and") not in ("and", "or"):
223
+ refuse()
224
+ nodes_ok(tree.get("nodes"))
225
+ else:
226
+ nodes_ok(tree)
227
+ return {"via": via.strip(), "filter": deepcopy(tree)}
228
+
229
+
230
  def clean_period(raw):
231
  """Return one canonical Sheet period, or ``None`` when no window was named."""
232
  if not isinstance(raw, dict):
platform/core/sheets.py CHANGED
@@ -246,7 +246,7 @@ SHEET_CHART_STACKING = ("clustered", "stacked", "percent")
246
  #:
247
  #: The order is the order a cleaned tab reads in: identity, then A2's geometry, then C2's strata.
248
  SHEET_TAB_KEYS = ("id", "name", "cols", "rows", "cells", "usedExtent", "colWidths", "freeze",
249
- "rules", "hiddenRows", "hiddenCols", "charts", "imported", "rowHeight", "rowHeights",
250
  "visibility", "view", "print", "excel")
251
 
252
  #: The keys above that `_clean_sheet` writes UNCONDITIONALLY. Every other member of
@@ -1403,6 +1403,32 @@ def _clean_imported(raw):
1403
  return out if (out["at"] or out["source"] or notes) else None
1404
 
1405
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1406
  def _clean_sheet(raw, index=0, *, lossless=False):
1407
  """Normalize a tab's known strata and retain additive JSON metadata without interpretation.
1408
 
@@ -1442,6 +1468,7 @@ def _clean_sheet(raw, index=0, *, lossless=False):
1442
  "colWidths": _clean_col_widths(raw.get("colWidths"), cols, lossless=lossless),
1443
  "freeze": _clean_freeze(raw.get("freeze"), cols, rows, lossless=lossless),
1444
  "rules": _clean_rules(raw.get("rules"), lossless=lossless),
 
1445
  "hiddenRows": _clean_hidden(raw.get("hiddenRows"), "rows"),
1446
  "hiddenCols": _clean_hidden(raw.get("hiddenCols"), "columns"),
1447
  "charts": _clean_charts(raw.get("charts")),
 
246
  #:
247
  #: The order is the order a cleaned tab reads in: identity, then A2's geometry, then C2's strata.
248
  SHEET_TAB_KEYS = ("id", "name", "cols", "rows", "cells", "usedExtent", "colWidths", "freeze",
249
+ "rules", "rowGroups", "hiddenRows", "hiddenCols", "charts", "imported", "rowHeight", "rowHeights",
250
  "visibility", "view", "print", "excel")
251
 
252
  #: The keys above that `_clean_sheet` writes UNCONDITIONALLY. Every other member of
 
1403
  return out if (out["at"] or out["source"] or notes) else None
1404
 
1405
 
1406
+ def _clean_row_groups(raw, rows):
1407
+ """Inclusive sheet ranges, with independent nested collapse state and no empty stratum."""
1408
+ if raw is None:
1409
+ return None
1410
+ if not isinstance(raw, list):
1411
+ raise SheetRefusal("sheet_row_groups_invalid", "Row groups must be a list.")
1412
+ out, ids = [], set()
1413
+ for item in raw:
1414
+ if not isinstance(item, dict):
1415
+ raise SheetRefusal("sheet_row_groups_invalid", "A row group must be an object.")
1416
+ gid, start, end, collapsed = (item.get(key) for key in ("id", "start", "end", "collapsed"))
1417
+ if not isinstance(gid, str) or not gid.strip() or len(gid) > _MAX_ID or gid in ids \
1418
+ or any(isinstance(n, bool) or not isinstance(n, int) for n in (start, end)) \
1419
+ or not 1 <= start <= end <= rows or not isinstance(collapsed, bool):
1420
+ raise SheetRefusal("sheet_row_groups_invalid", "A row group needs an id, a valid row range and a collapse state.")
1421
+ for prior in out:
1422
+ disjoint = end < prior["start"] or start > prior["end"]
1423
+ nested = (start >= prior["start"] and end <= prior["end"]) \
1424
+ or (start <= prior["start"] and end >= prior["end"])
1425
+ if (start, end) == (prior["start"], prior["end"]) or not (disjoint or nested):
1426
+ raise SheetRefusal("sheet_row_groups_overlap", "Groups can be nested, but cannot duplicate or partially overlap.")
1427
+ ids.add(gid)
1428
+ out.append({"id": gid, "start": start, "end": end, "collapsed": collapsed})
1429
+ return out or None
1430
+
1431
+
1432
  def _clean_sheet(raw, index=0, *, lossless=False):
1433
  """Normalize a tab's known strata and retain additive JSON metadata without interpretation.
1434
 
 
1468
  "colWidths": _clean_col_widths(raw.get("colWidths"), cols, lossless=lossless),
1469
  "freeze": _clean_freeze(raw.get("freeze"), cols, rows, lossless=lossless),
1470
  "rules": _clean_rules(raw.get("rules"), lossless=lossless),
1471
+ "rowGroups": _clean_row_groups(raw.get("rowGroups"), rows),
1472
  "hiddenRows": _clean_hidden(raw.get("hiddenRows"), "rows"),
1473
  "hiddenCols": _clean_hidden(raw.get("hiddenCols"), "columns"),
1474
  "charts": _clean_charts(raw.get("charts")),
platform/modules/collections_send.py CHANGED
@@ -14,7 +14,7 @@ hard-blocking on all writes. The UI gates the section to admin users; SAFE_MODE
14
  in the data layer so the UI cannot bypass it.
15
 
16
  Env (Space secrets / .env): ODOO_URL, ODOO_DB, ODOO_USER, ODOO_API_KEY
17
- Optional: SAFE_MODE (default ON), SAFE_RECIPIENTS, SENDER_NAME, SENDER_EMAIL, REPLY_TO,
18
  COMPANY_NAME, ROYAL_MAIL_SERVER_ID, ROYAL_AUTHOR_ID
19
  """
20
  import os
@@ -59,9 +59,24 @@ class SafeModeBlocked(RuntimeError):
59
 
60
  # --- Testing guardrail -------------------------------------------------------
61
  # While SAFE_MODE is on, NO email can be queued to any address outside the allow-list — enforced
62
- # here in the data layer so the UI cannot bypass it. Default: ON. To go live for real customers,
63
- # set the Space secret SAFE_MODE=0.
64
- SAFE_MODE = os.environ.get('SAFE_MODE', '1').strip().lower() not in ('0', 'false', 'no', '')
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
65
  SAFE_RECIPIENTS = {a.strip().lower() for a in
66
  os.environ.get('SAFE_RECIPIENTS', 'farhan@teamroyalimports.com').split(',')
67
  if a.strip()}
@@ -265,3 +280,25 @@ def queue_statement(odoo, row, subject_tpl=DEFAULT_SUBJECT,
265
  'res_id': row['partner_id'],
266
  }
267
  return odoo.queue_mail(payload)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
14
  in the data layer so the UI cannot bypass it.
15
 
16
  Env (Space secrets / .env): ODOO_URL, ODOO_DB, ODOO_USER, ODOO_API_KEY
17
+ Optional: SAFE_MODE (default ON; only 0/false/no turn it off), SAFE_RECIPIENTS, SENDER_NAME, SENDER_EMAIL, REPLY_TO,
18
  COMPANY_NAME, ROYAL_MAIL_SERVER_ID, ROYAL_AUTHOR_ID
19
  """
20
  import os
 
59
 
60
  # --- Testing guardrail -------------------------------------------------------
61
  # While SAFE_MODE is on, NO email can be queued to any address outside the allow-list — enforced
62
+ # here in the data layer so the UI cannot bypass it. Default: ON; only an explicit recognised
63
+ # opt-out turns it off. An empty or blank value is NOT an opt-out.
64
+ # To go live for real customers, set the Space secret SAFE_MODE=0.
65
+ #: The ONLY values that turn the guardrail off. Anything else -- unset, empty, whitespace,
66
+ #: or a token nobody recognises -- leaves SAFE_MODE ON. [D-349]
67
+ SAFE_MODE_OPT_OUT = frozenset({'0', 'false', 'no'})
68
+
69
+
70
+ def safe_mode_from(value):
71
+ """True (guardrail ON) unless `value` is one of the recognised opt-out tokens.
72
+
73
+ Fails CLOSED on purpose: an empty or blank SAFE_MODE used to read as an opt-out, which
74
+ silently disarmed the only guard on the one path in the product allowed to write to Odoo.
75
+ """
76
+ return str(value if value is not None else '').strip().lower() not in SAFE_MODE_OPT_OUT
77
+
78
+
79
+ SAFE_MODE = safe_mode_from(os.environ.get('SAFE_MODE', '1'))
80
  SAFE_RECIPIENTS = {a.strip().lower() for a in
81
  os.environ.get('SAFE_RECIPIENTS', 'farhan@teamroyalimports.com').split(',')
82
  if a.strip()}
 
280
  'res_id': row['partner_id'],
281
  }
282
  return odoo.queue_mail(payload)
283
+
284
+
285
+ def queue_statement_batch(odoo, rows, subject_tpl=DEFAULT_SUBJECT,
286
+ intro_tpl=DEFAULT_INTRO, footer_tpl=DEFAULT_FOOTER):
287
+ """Queue one statement per row through the existing guarded statement sender.
288
+
289
+ A missing address or a safe-mode refusal does not stop the remaining rows.
290
+ """
291
+ created, refused = [], []
292
+ for row in rows:
293
+ try:
294
+ mail_id = queue_statement(odoo, row, subject_tpl, intro_tpl, footer_tpl)
295
+ except SafeModeBlocked:
296
+ refused.append({"customer": row["Customer"],
297
+ "reason": "Safe mode does not allow this recipient address."})
298
+ except ValueError:
299
+ reason = ("No email address is saved for this customer." if not row.get("Email")
300
+ else "The statement could not be prepared from the current customer details.")
301
+ refused.append({"customer": row["Customer"], "reason": reason})
302
+ else:
303
+ created.append({"customer": row["Customer"], "to": row["Email"], "mailId": mail_id})
304
+ return {"created": created, "refused": refused, "safe_mode": bool(SAFE_MODE)}
platform/modules/finance_apps.py CHANGED
@@ -44,6 +44,7 @@ FINANCE_APPLICATIONS = (
44
  "key": "ar-collections",
45
  "label": "AR & Collections",
46
  "navLabel": "AR & Collections",
 
47
  "mode": "workflow",
48
  "permissionKey": "ar",
49
  "composes": ["ar", "collections"],
@@ -75,6 +76,7 @@ FINANCE_APPLICATIONS = (
75
  "key": "ap-spend",
76
  "label": "AP & Spend",
77
  "navLabel": "AP & Spend",
 
78
  "mode": "workflow",
79
  "permissionKey": "spend",
80
  "composes": ["spend", "vendor_bills"],
@@ -104,6 +106,7 @@ FINANCE_APPLICATIONS = (
104
  "key": "cash-o2c",
105
  "label": "Cash & O2C",
106
  "navLabel": "Cash & O2C",
 
107
  "mode": "dashboard",
108
  "permissionKey": "o2c",
109
  "composes": ["o2c", "ar"],
@@ -123,6 +126,7 @@ FINANCE_APPLICATIONS = (
123
  "key": "pnl-gross-margin",
124
  "label": "Management P&L & Gross Margin",
125
  "navLabel": "P&L & Margin",
 
126
  "mode": "dashboard",
127
  "permissionKey": "financial",
128
  "composes": ["financial", "sales"],
@@ -142,6 +146,7 @@ FINANCE_APPLICATIONS = (
142
  "key": "procurement-inventory",
143
  "label": "Procurement & Inventory",
144
  "navLabel": "Procurement & Inventory",
 
145
  "mode": "workflow",
146
  "permissionKey": "procurement",
147
  "composes": ["procurement", "inventory"],
@@ -162,6 +167,7 @@ FINANCE_APPLICATIONS = (
162
  "key": "planning-data-health",
163
  "label": "Planning & Data Health",
164
  "navLabel": "Planning & Data Health",
 
165
  "mode": "dashboard",
166
  "permissionKey": "health",
167
  "composes": ["planning", "health"],
@@ -205,3 +211,9 @@ def finance_application(key, may_open=None):
205
  raise PermissionError(f"access to {key} is not granted")
206
  return deepcopy(app)
207
  raise KeyError(key)
 
 
 
 
 
 
 
44
  "key": "ar-collections",
45
  "label": "AR & Collections",
46
  "navLabel": "AR & Collections",
47
+ "description": "Prioritize customer balances that need collection action.",
48
  "mode": "workflow",
49
  "permissionKey": "ar",
50
  "composes": ["ar", "collections"],
 
76
  "key": "ap-spend",
77
  "label": "AP & Spend",
78
  "navLabel": "AP & Spend",
79
+ "description": "Review supplier obligations before payment.",
80
  "mode": "workflow",
81
  "permissionKey": "spend",
82
  "composes": ["spend", "vendor_bills"],
 
106
  "key": "cash-o2c",
107
  "label": "Cash & O2C",
108
  "navLabel": "Cash & O2C",
109
+ "description": "Track how invoiced demand converts into cash.",
110
  "mode": "dashboard",
111
  "permissionKey": "o2c",
112
  "composes": ["o2c", "ar"],
 
126
  "key": "pnl-gross-margin",
127
  "label": "Management P&L & Gross Margin",
128
  "navLabel": "P&L & Margin",
129
+ "description": "Understand what drives operating performance.",
130
  "mode": "dashboard",
131
  "permissionKey": "financial",
132
  "composes": ["financial", "sales"],
 
146
  "key": "procurement-inventory",
147
  "label": "Procurement & Inventory",
148
  "navLabel": "Procurement & Inventory",
149
+ "description": "Prioritize buying and warehouse work from stock movements.",
150
  "mode": "workflow",
151
  "permissionKey": "procurement",
152
  "composes": ["procurement", "inventory"],
 
167
  "key": "planning-data-health",
168
  "label": "Planning & Data Health",
169
  "navLabel": "Planning & Data Health",
170
+ "description": "Assess whether planning inputs are ready to use.",
171
  "mode": "dashboard",
172
  "permissionKey": "health",
173
  "composes": ["planning", "health"],
 
211
  raise PermissionError(f"access to {key} is not granted")
212
  return deepcopy(app)
213
  raise KeyError(key)
214
+
215
+
216
+ def finance_templates(may_open=None):
217
+ """Offer one concise template per Finance application the caller may open."""
218
+ return [{"key": app["key"], "label": app["label"], "description": app["description"]}
219
+ for app in finance_applications(may_open=may_open)]
platform/modules/sheet.py CHANGED
@@ -54,6 +54,9 @@ AGGREGATE_FNS = ("sum", "count", "avg", "min", "max")
54
  #: C2's refusal codes, spelled once. ⚠ Each message reaches a screen, so none carries an em dash or
55
  #: an en dash (standing rule 2) and each names both the cause and the subject.
56
  REFUSALS = {
 
 
 
57
  "database_unreadable": "You cannot read {subject}.",
58
  "view_missing": "View {subject} no longer exists.",
59
  "result_too_large": "This result does not fit in one cell.",
@@ -150,6 +153,15 @@ class SheetRefusal(Exception):
150
  super().__init__(self.message)
151
 
152
 
 
 
 
 
 
 
 
 
 
153
  def clean_period(raw):
154
  """Normalize period metadata through the core document contract."""
155
  from core.sheet_binding import BindingMetadataRefusal, clean_period as _clean
@@ -465,14 +477,34 @@ def clean_adopted_from(raw):
465
  return out or None
466
 
467
 
468
- def validate(date_from, date_to, observed, *, team_id, partner_ids=None):
469
- """Reconcile T08's four sections to live Odoo, at the exact displayed scope.
 
470
 
 
471
  sales.validate owns the broader sales-module reconciliation. Its public API
472
  takes a YTD as-of, not arbitrary weeks or customer sets. Reuse its order and
473
  line domains here for the template's narrower independent checks; never use
474
  customer_data.validate (which validates addresses).
 
 
 
 
 
 
 
 
 
 
475
  """
 
 
 
 
 
 
 
 
476
  import math
477
  from core import odoo as O
478
  from modules import sales
@@ -507,6 +539,51 @@ def validate(date_from, date_to, observed, *, team_id, partner_ids=None):
507
  return checks
508
 
509
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
510
  def sales_summary_partition(all_values, agent_values, unassigned):
511
  """Partition additive measures; AOV must be recomputed from the summed count."""
512
  import math
@@ -531,7 +608,8 @@ def clean_binding(raw):
531
  `Binding = {database, aggregate:{fn, field?} | {metric_key},
532
  scope:{view_id} | {filter} (+ adoptedFrom?),
533
  period?: {unit, start, locked?, ref?} | {unit, start, locked?, frozen: true, from, to}
534
- | {window}, onDrag?: {across, down}}`
 
535
  """
536
  if not isinstance(raw, dict):
537
  raise SheetRefusal("binding_invalid")
@@ -590,6 +668,9 @@ def clean_binding(raw):
590
  if on_drag:
591
  out["onDrag"] = on_drag
592
 
 
 
 
593
  return out
594
 
595
 
@@ -839,8 +920,58 @@ def aggregate_sql(spec, aggregate, columns):
839
  return f"{fn.upper()}({col['sql']})", key
840
 
841
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
842
  def build_aggregate_query(spec, binding, columns, *, scope_nodes, scope_conj,
843
- wall_nodes=None, wall_conj="and", today=None, cohort_sets=None):
 
844
  """`(sql, params, limits)` for one bound cell.
845
 
846
  ⛔⛔ **THE SPEC'S OWN `where` IS NOT OPTIONAL AND IT IS NOT AN OPTIMISATION.** It carries the
@@ -882,6 +1013,15 @@ def build_aggregate_query(spec, binding, columns, *, scope_nodes, scope_conj,
882
  where.append(f"({compiled.sql})")
883
  params.extend(list(compiled.params))
884
 
 
 
 
 
 
 
 
 
 
885
  source = str(spec.get("from_sql") or "").strip() or str(spec.get("table") or "").strip()
886
  if not source:
887
  raise SheetRefusal("binding_invalid")
@@ -890,7 +1030,7 @@ def build_aggregate_query(spec, binding, columns, *, scope_nodes, scope_conj,
890
  sql += " WHERE " + " AND ".join(where)
891
  # ⭐ The limits are measured against what the compiler REALLY used, so a leaf that fell out for
892
  # any reason is reported. See `widen_limits` for the measurement that made this necessary.
893
- return sql, params, widen_limits(scope_nodes, columns, scope_compiled)
894
 
895
 
896
  #: A drill hands `LinkGridModal` a list of record ids. It is capped because the popup renders them,
@@ -903,7 +1043,7 @@ MAX_DRILL_IDS = 500
903
 
904
 
905
  def build_ids_query(spec, columns, *, scope_nodes, scope_conj, wall_nodes=None, wall_conj="and",
906
- today=None, cohort_sets=None, limit=MAX_DRILL_IDS):
907
  """`(sql, params, limits)` for the ROW IDS behind a bound cell (R6, R13).
908
 
909
  Same WHERE as the aggregate, by construction: it is built by the same function so the popup
@@ -915,7 +1055,8 @@ def build_ids_query(spec, columns, *, scope_nodes, scope_conj, wall_nodes=None,
915
  probe = {"aggregate": {"fn": "count"}}
916
  sql, params, limits = build_aggregate_query(
917
  spec, probe, columns, scope_nodes=scope_nodes, scope_conj=scope_conj,
918
- wall_nodes=wall_nodes, wall_conj=wall_conj, today=today, cohort_sets=cohort_sets)
 
919
  sql = sql.replace("SELECT COUNT(*) FROM", f"SELECT {id_expr} FROM", 1)
920
  return f"{sql} LIMIT {int(limit)}", params, limits
921
 
 
54
  #: C2's refusal codes, spelled once. ⚠ Each message reaches a screen, so none carries an em dash or
55
  #: an en dash (standing rule 2) and each names both the cause and the subject.
56
  REFUSALS = {
57
+ "related_invalid": "Choose one declared relationship and a valid filter tree for this cell.",
58
+ "related_unresolved": "Relationship {subject} has no resolved SQL join. Choose a readable "
59
+ "declared relationship and try again.",
60
  "database_unreadable": "You cannot read {subject}.",
61
  "view_missing": "View {subject} no longer exists.",
62
  "result_too_large": "This result does not fit in one cell.",
 
153
  super().__init__(self.message)
154
 
155
 
156
+ def clean_related(raw):
157
+ """Normalize the optional single-relationship contract in the pure core layer."""
158
+ from core.sheet_binding import BindingMetadataRefusal, clean_related as _clean
159
+ try:
160
+ return _clean(raw)
161
+ except BindingMetadataRefusal as exc:
162
+ raise SheetRefusal(exc.code, exc.subject, exc.detail) from exc
163
+
164
+
165
  def clean_period(raw):
166
  """Normalize period metadata through the core document contract."""
167
  from core.sheet_binding import BindingMetadataRefusal, clean_period as _clean
 
477
  return out or None
478
 
479
 
480
+ def validate(date_from, date_to, observed, *, team_id, partner_ids=None,
481
+ basis="order", include_refunds=None):
482
+ """Reconcile a displayed value to live Odoo at the exact displayed scope.
483
 
484
+ The default order basis retains T08's four sections and six check rows.
485
  sales.validate owns the broader sales-module reconciliation. Its public API
486
  takes a YTD as-of, not arbitrary weeks or customer sets. Reuse its order and
487
  line domains here for the template's narrower independent checks; never use
488
  customer_data.validate (which validates addresses).
489
+
490
+ For ut_odoo_invoices.amount_untaxed, pass basis="invoice" and observed as
491
+ {"invoiced_sales": cell_value}. Explicitly choose include_refunds=True for
492
+ the mirror's posted invoices plus refunds, or False for strict R9 invoices.
493
+ Both dates are inclusive invoice_date bounds: use the SAME range on the cell,
494
+ with date_to at or before the mirror's own max(invoice_date), never today's
495
+ date merely because live Odoo is newer. Date bounds do not reconstruct a sync
496
+ snapshot; invoice rows report that limitation even when the amounts tie.
497
+ Pass team_id=None: this mirror has no order-team scope. If needed, resolve
498
+ the cell's customer/BU filter into partner_ids (None=all, []=none).
499
  """
500
+ if basis == "invoice":
501
+ return _validate_invoices(date_from, date_to, observed, team_id=team_id,
502
+ partner_ids=partner_ids, include_refunds=include_refunds)
503
+ if basis != "order":
504
+ raise ValueError("Unknown validation basis. Choose order or invoice.")
505
+ if include_refunds is not None:
506
+ raise ValueError("Refund selection applies only to invoice validation. Choose basis invoice.")
507
+
508
  import math
509
  from core import odoo as O
510
  from modules import sales
 
539
  return checks
540
 
541
 
542
+ def _validate_invoices(date_from, date_to, observed, *, team_id, partner_ids, include_refunds):
543
+ """Independent account.move sum; never read the mirror or inherit order scope."""
544
+ import math
545
+ from core import odoo as O
546
+
547
+ try:
548
+ first = datetime.date.fromisoformat(date_from)
549
+ last = datetime.date.fromisoformat(date_to)
550
+ except (TypeError, ValueError):
551
+ raise ValueError("Invoice reconciliation needs both invoice_date bounds in YYYY-MM-DD format. "
552
+ "Use the cell's start and cap its end at the mirror's as-of date.") from None
553
+ if first > last:
554
+ raise ValueError("Invoice reconciliation has a reversed date range. "
555
+ "Use the cell's start and cap its end at the mirror's as-of date.")
556
+ if not isinstance(include_refunds, bool):
557
+ raise ValueError("Invoice reconciliation needs an explicit refund choice. "
558
+ "Set include_refunds=False for R9 invoices or True for invoices plus refunds.")
559
+ if team_id is not None:
560
+ raise ValueError("The invoice mirror has no order-team scope. Set team_id=None and "
561
+ "pass the cell's resolved customer or business-unit filter in partner_ids.")
562
+
563
+ domain = [("state", "=", "posted"),
564
+ ("move_type", "in", ["out_invoice", "out_refund"] if include_refunds else ["out_invoice"]),
565
+ ("partner_id", "!=", False),
566
+ ("invoice_date", ">=", first.isoformat()), ("invoice_date", "<=", last.isoformat())]
567
+ if partner_ids is not None:
568
+ domain.append(("partner_id", "in", list(partner_ids)))
569
+ expected = O.sum_field("account.move", domain, "amount_untaxed_signed")
570
+ actual = observed.get("invoiced_sales")
571
+ valid = isinstance(actual, (float, int)) and not isinstance(actual, bool) and math.isfinite(actual)
572
+ # One cent is the monetary precision used by the existing order reconciliation;
573
+ # it absorbs float noise without a relative tolerance that grows with revenue.
574
+ return [{"check": "invoiced_sales", "a": actual, "b": expected,
575
+ "gap": actual - expected if valid else None,
576
+ "ok": valid and abs(actual - expected) <= 0.01,
577
+ "basis": "invoice", "include_refunds": include_refunds,
578
+ "date_from": first.isoformat(), "date_to": last.isoformat(),
579
+ "limits": [{"code": "invoice_date_not_snapshot",
580
+ "cause": "Live Odoo is bounded by invoice_date, not by the mirror's sync snapshot. "
581
+ "Older invoices may have changed since that sync.",
582
+ "recommendation": "Use the same date range on the cell and this check, ending "
583
+ "at or before the mirror's max(invoice_date). If a gap remains, "
584
+ "compare invoice IDs and amounts or refresh the mirror and reconcile again."}]}]
585
+
586
+
587
  def sales_summary_partition(all_values, agent_values, unassigned):
588
  """Partition additive measures; AOV must be recomputed from the summed count."""
589
  import math
 
608
  `Binding = {database, aggregate:{fn, field?} | {metric_key},
609
  scope:{view_id} | {filter} (+ adoptedFrom?),
610
  period?: {unit, start, locked?, ref?} | {unit, start, locked?, frozen: true, from, to}
611
+ | {window}, onDrag?: {across, down},
612
+ related?: {via: <declared edge key>, filter: <filter tree>}}`
613
  """
614
  if not isinstance(raw, dict):
615
  raise SheetRefusal("binding_invalid")
 
668
  if on_drag:
669
  out["onDrag"] = on_drag
670
 
671
+ if "related" in raw:
672
+ out["related"] = clean_related(raw["related"])
673
+
674
  return out
675
 
676
 
 
920
  return f"{fn.upper()}({col['sql']})", key
921
 
922
 
923
+ def _related_predicate(related, columns, *, today=None, cohort_sets=None):
924
+ """Compile a resolved declaration, including the far-side wall, into one SQL subquery.
925
+
926
+ This bag is supplied only by the API resolver. Join keys are looked up in the two
927
+ column maps here; neither the binding's via nor any record IDs enter the SQL.
928
+ """
929
+ rcols, rspec = related["columns"], related["spec"]
930
+ local = (columns.get(related["local_key"]) or {}).get("sql")
931
+ remote = (rcols.get(related["remote_key"]) or {}).get("sql")
932
+ source = rspec.get("from_sql") or rspec.get("table")
933
+ if not local or not remote or not source:
934
+ raise SheetRefusal("related_unresolved", related.get("via", "This relationship"))
935
+ where = [f"({part})" for part in (rspec.get("where"), related.get("where")) if part]
936
+ params, limits = [], []
937
+
938
+ def leaf_limits(nodes):
939
+ # Checking every leaf also catches a dropped condition on a column which a
940
+ # different, valid condition used. The legacy column-set check cannot see it.
941
+ out = []
942
+ for node in nodes or ():
943
+ if not isinstance(node, dict):
944
+ raise ValueError("malformed related filter condition")
945
+ if isinstance(node.get("children"), list):
946
+ out.extend(leaf_limits(node["children"]))
947
+ else:
948
+ if "children" in node or not node.get("colId"):
949
+ raise ValueError("malformed related filter condition")
950
+ part = compile_scope([node], "and", rcols, today=today, cohort_sets=cohort_sets)
951
+ out.extend(widen_limits([node], rcols, part))
952
+ return out
953
+
954
+ for nodes, conj, is_wall in (
955
+ (related.get("wall_nodes"), related.get("wall_conj", "and"), True),
956
+ (related["scope_nodes"], related["scope_conj"], False)):
957
+ compiled = compile_scope(nodes, conj, rcols, today=today, cohort_sets=cohort_sets)
958
+ dropped = leaf_limits(nodes)
959
+ if is_wall and dropped:
960
+ raise ValueError("unapplied related row wall")
961
+ limits.extend({**item, "subject": f"{related['database']}: {item['subject']}"}
962
+ for item in dropped)
963
+ if compiled is not None:
964
+ where.append(f"({compiled.sql})")
965
+ params.extend(compiled.params)
966
+ sql = f"{local} IN (SELECT {remote} FROM {source}"
967
+ if where:
968
+ sql += " WHERE " + " AND ".join(where)
969
+ return sql + ")", params, limits + list(related.get("limits") or ())
970
+
971
+
972
  def build_aggregate_query(spec, binding, columns, *, scope_nodes, scope_conj,
973
+ wall_nodes=None, wall_conj="and", today=None, cohort_sets=None,
974
+ related=None):
975
  """`(sql, params, limits)` for one bound cell.
976
 
977
  ⛔⛔ **THE SPEC'S OWN `where` IS NOT OPTIONAL AND IT IS NOT AN OPTIMISATION.** It carries the
 
1013
  where.append(f"({compiled.sql})")
1014
  params.extend(list(compiled.params))
1015
 
1016
+ related_limits = []
1017
+ if binding.get("related") is not None and related is None:
1018
+ raise SheetRefusal("related_unresolved", binding["related"].get("via"))
1019
+ if related is not None:
1020
+ predicate, rparams, related_limits = _related_predicate(
1021
+ related, columns, today=today, cohort_sets=cohort_sets)
1022
+ where.append(f"({predicate})")
1023
+ params.extend(rparams)
1024
+
1025
  source = str(spec.get("from_sql") or "").strip() or str(spec.get("table") or "").strip()
1026
  if not source:
1027
  raise SheetRefusal("binding_invalid")
 
1030
  sql += " WHERE " + " AND ".join(where)
1031
  # ⭐ The limits are measured against what the compiler REALLY used, so a leaf that fell out for
1032
  # any reason is reported. See `widen_limits` for the measurement that made this necessary.
1033
+ return sql, params, widen_limits(scope_nodes, columns, scope_compiled) + related_limits
1034
 
1035
 
1036
  #: A drill hands `LinkGridModal` a list of record ids. It is capped because the popup renders them,
 
1043
 
1044
 
1045
  def build_ids_query(spec, columns, *, scope_nodes, scope_conj, wall_nodes=None, wall_conj="and",
1046
+ today=None, cohort_sets=None, limit=MAX_DRILL_IDS, related=None):
1047
  """`(sql, params, limits)` for the ROW IDS behind a bound cell (R6, R13).
1048
 
1049
  Same WHERE as the aggregate, by construction: it is built by the same function so the popup
 
1055
  probe = {"aggregate": {"fn": "count"}}
1056
  sql, params, limits = build_aggregate_query(
1057
  spec, probe, columns, scope_nodes=scope_nodes, scope_conj=scope_conj,
1058
+ wall_nodes=wall_nodes, wall_conj=wall_conj, today=today, cohort_sets=cohort_sets,
1059
+ related=related)
1060
  sql = sql.replace("SELECT COUNT(*) FROM", f"SELECT {id_expr} FROM", 1)
1061
  return f"{sql} LIMIT {int(limit)}", params, limits
1062
 
web/public/AIOS_DEPLOY_RECEIPT CHANGED
@@ -1 +1 @@
1
- e5e46eb6c3c398af5ff53acb6bba35dc11ad75a42f5d4ddf69f2ff918624de22
 
1
+ 2160900aba989ac1af8a786987de16ef19780fb1b03be8a122b60997fedd2cc8
web/src/app/FinanceWorkspace.tsx CHANGED
@@ -1,5 +1,6 @@
1
  import { useEffect, useMemo, useState } from "react";
2
  import { useEscapeClose } from "../ui/useEscapeClose";
 
3
  import "./finance.css";
4
 
5
  type FactState = "ready" | "warming" | "missing" | "unavailable" | "restricted" | "requires_sku";
@@ -726,19 +727,28 @@ function DrillDrawer({ fact, payload, busy, error, onClose }: {
726
  );
727
  }
728
 
729
- export default function FinanceWorkspace({
730
- appKey,
731
- apiBase = "/api/v1",
732
- businessUnit,
733
- dateFrom,
734
- dateTo,
735
- }: {
736
  appKey?: string;
737
  apiBase?: string;
738
  businessUnit?: string;
739
  dateFrom?: string;
740
  dateTo?: string;
741
- }) {
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
742
  const resolvedKey = appKey || pathApplicationKey();
743
  const [page, setPage] = useState<PageState>({ kind: "loading" });
744
  const [drillFact, setDrillFact] = useState<FinanceFact | null>(null);
 
1
  import { useEffect, useMemo, useState } from "react";
2
  import { useEscapeClose } from "../ui/useEscapeClose";
3
+ import CollectionPage from "../apps/CollectionPage";
4
  import "./finance.css";
5
 
6
  type FactState = "ready" | "warming" | "missing" | "unavailable" | "restricted" | "requires_sku";
 
727
  );
728
  }
729
 
730
+ type FinanceWorkspaceProps = {
 
 
 
 
 
 
731
  appKey?: string;
732
  apiBase?: string;
733
  businessUnit?: string;
734
  dateFrom?: string;
735
  dateTo?: string;
736
+ };
737
+
738
+ // S65-T18: Collection is its own surface now; every other Finance app keeps this workspace.
739
+ // The branch is its own component so no hook below it is ever skipped by an early return.
740
+ export default function FinanceWorkspace(props: FinanceWorkspaceProps) {
741
+ if ((props.appKey || pathApplicationKey()) === "ar-collections") return <CollectionPage />;
742
+ return <FinanceApplication {...props} />;
743
+ }
744
+
745
+ function FinanceApplication({
746
+ appKey,
747
+ apiBase = "/api/v1",
748
+ businessUnit,
749
+ dateFrom,
750
+ dateTo,
751
+ }: FinanceWorkspaceProps) {
752
  const resolvedKey = appKey || pathApplicationKey();
753
  const [page, setPage] = useState<PageState>({ kind: "loading" });
754
  const [drillFact, setDrillFact] = useState<FinanceFact | null>(null);
web/src/apps/CollectionPage.tsx ADDED
@@ -0,0 +1,395 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { useEffect, useMemo, useRef, useState } from "react";
2
+ import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal as raiseEvent } from "../apiContract";
3
+ import { BodyPortal, useOverlayLayer } from "../customer-grid/OverlaySurface";
4
+ import "./collection.css";
5
+
6
+ type OpenDocument = {
7
+ name: string;
8
+ date: string | null;
9
+ dueDate: string | null;
10
+ daysOverdue: number;
11
+ openBalance: number;
12
+ };
13
+
14
+ type CollectionRow = {
15
+ partner_id: number;
16
+ Customer: string;
17
+ Tier: string;
18
+ Overdue: number;
19
+ Receivable: number;
20
+ "Oldest (days)": number;
21
+ "Open Docs": number;
22
+ Email: string;
23
+ Phone: string;
24
+ Status: string;
25
+ "Reconcile?": string;
26
+ _docs: number;
27
+ documents: OpenDocument[];
28
+ sendRefusal: string | null;
29
+ };
30
+
31
+ type SendPolicy = {
32
+ safeMode: boolean;
33
+ safeRecipients: string[];
34
+ sender: { name: string; email: string; replyTo: string };
35
+ };
36
+ type Worklist = SendPolicy & { rows: CollectionRow[] };
37
+ type Refusal = { customer: string; reason: string };
38
+ type Statement = {
39
+ partnerId: number;
40
+ customer: string;
41
+ to: string;
42
+ subject: string;
43
+ html: string;
44
+ refusal: string | null;
45
+ };
46
+ type Preview = SendPolicy & { requested: number; statements: Statement[]; refused: Refusal[] };
47
+ type SendResult = { created: number; refused: Refusal[]; safeMode: boolean };
48
+ type PageState =
49
+ | { kind: "loading" }
50
+ | { kind: "ready"; data: Worklist }
51
+ | { kind: "error" | "restricted"; message: string };
52
+ type BatchState =
53
+ | { kind: "loading"; ids: number[] }
54
+ | { kind: "ready"; ids: number[]; data: Preview }
55
+ | { kind: "error"; ids: number[]; message: string };
56
+
57
+ const money = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });
58
+ const count = new Intl.NumberFormat("en-US");
59
+ const columns = ["Customer", "Tier", "Overdue", "Receivable", "Oldest days", "Open docs", "Email", "Phone", "Status", "Reconcile"];
60
+
61
+ function plural(value: number, one: string, many: string): string {
62
+ return `${count.format(value)} ${value === 1 ? one : many}`;
63
+ }
64
+
65
+ function safeModeNotice(policy: SendPolicy): string {
66
+ if (!policy.safeMode) return "Statements will be queued to each customer's Odoo email address.";
67
+ if (!policy.safeRecipients.length) return "Safe mode is on; no recipient addresses can receive mail right now.";
68
+ return `Safe mode is on; only ${policy.safeRecipients.join(", ")} can receive mail right now.`;
69
+ }
70
+
71
+ //: The only two refusals above 500 that are written FOR the reader rather than about the server.
72
+ const SPOKEN_5XX = new Set(["collection_send_unconfirmed", "collection_odoo_unavailable"]);
73
+
74
+ async function responseError(response: Response): Promise<string> {
75
+ const body = await response.json().catch(() => null) as {
76
+ error?: { code?: string; message?: string }; detail?: { error?: { code?: string; message?: string } };
77
+ } | null;
78
+ const error = body?.error || body?.detail?.error;
79
+ // A 4xx message is policy and is shown; a 5xx detail is internal and is not (apiContract's rule).
80
+ if (response.status >= 500 && !SPOKEN_5XX.has(error?.code || "")) {
81
+ return "Something went wrong on our side. Try again in a moment.";
82
+ }
83
+ return error?.message || "Collection is temporarily unavailable.";
84
+ }
85
+
86
+ function Refusals({ items }: { items: Refusal[] }) {
87
+ if (!items.length) return null;
88
+ return <details className="collection-refusals" open>
89
+ <summary>{plural(items.length, "customer refused", "customers refused")}</summary>
90
+ <ul>{items.map((item, index) => <li key={`${index}-${item.customer}`}>
91
+ <strong>{item.customer}</strong>: {item.reason}
92
+ </li>)}</ul>
93
+ </details>;
94
+ }
95
+
96
+ function TableSkeleton() {
97
+ return <div className="collection-table-scroll" role="status" aria-label="Loading Collection worklist" aria-busy="true">
98
+ <table className="collection-table" aria-hidden="true">
99
+ <thead><tr><th>Select</th>{columns.map(label => <th key={label}>{label}</th>)}</tr></thead>
100
+ <tbody>{Array.from({ length: 8 }, (_, index) => <tr key={index}>
101
+ {Array.from({ length: columns.length + 1 }, (_, cell) => <td key={cell}><span className="collection-skeleton" /></td>)}
102
+ </tr>)}</tbody>
103
+ </table>
104
+ </div>;
105
+ }
106
+
107
+ function CustomerDrawer({ row, onClose }: { row: CollectionRow; onClose: () => void }) {
108
+ const panelRef = useRef<HTMLElement>(null);
109
+ useOverlayLayer({ panelRef, onDismiss: onClose, dismissOnOutside: false, trapFocus: true });
110
+ return <BodyPortal><div className="collection-overlay collection-overlay--drawer">
111
+ <aside ref={panelRef} className="collection-drawer" role="dialog" aria-modal="true" aria-labelledby="collection-customer-title" tabIndex={-1}>
112
+ <header className="collection-dialog-header">
113
+ <h2 id="collection-customer-title">{row.Customer}</h2>
114
+ <button type="button" className="collection-button" onClick={onClose}>Close</button>
115
+ </header>
116
+ <div className="collection-dialog-body">
117
+ <dl className="collection-details">
118
+ <div><dt>Email</dt><dd>{row.Email || "No email address"}</dd></div>
119
+ <div><dt>Phone</dt><dd>{row.Phone || "Not recorded"}</dd></div>
120
+ <div><dt>Status</dt><dd>{row.Status || "Not recorded"}</dd></div>
121
+ <div><dt>Overdue</dt><dd className="collection-number collection-overdue">{money.format(row.Overdue)}</dd></div>
122
+ <div><dt>Receivable</dt><dd className="collection-number">{money.format(row.Receivable)}</dd></div>
123
+ </dl>
124
+ <h3>Open documents</h3>
125
+ {row.documents.length ? <div className="collection-document-scroll" tabIndex={0} aria-label="Open documents">
126
+ <table className="collection-table">
127
+ <thead><tr><th scope="col">Document</th><th scope="col">Date</th><th scope="col">Due</th><th scope="col" className="collection-number">Days overdue</th><th scope="col" className="collection-number">Open balance</th></tr></thead>
128
+ <tbody>{row.documents.map((doc, index) => <tr key={`${doc.name}-${index}`}>
129
+ <td>{doc.name}</td><td>{doc.date || "Not recorded"}</td><td>{doc.dueDate || "Not recorded"}</td>
130
+ <td className="collection-number">{count.format(doc.daysOverdue)}</td>
131
+ <td className="collection-number">{money.format(doc.openBalance)}</td>
132
+ </tr>)}</tbody>
133
+ </table>
134
+ </div> : <p>No open documents for this customer.</p>}
135
+ </div>
136
+ </aside>
137
+ </div></BodyPortal>;
138
+ }
139
+
140
+ function BatchDialog({ batch, sending, onClose, onSend }: {
141
+ batch: BatchState; sending: boolean; onClose: () => void; onSend: (ids: number[]) => void;
142
+ }) {
143
+ const panelRef = useRef<HTMLElement>(null);
144
+ const confirmRef = useRef<HTMLButtonElement>(null);
145
+ const sendRef = useRef<HTMLButtonElement>(null);
146
+ const [confirming, setConfirming] = useState(false);
147
+ const [statementIndex, setStatementIndex] = useState(0);
148
+ useOverlayLayer({ panelRef, onDismiss: onClose, dismissOnOutside: false, trapFocus: true });
149
+ useEffect(() => { (confirming ? confirmRef : sendRef).current?.focus(); }, [confirming]);
150
+ const data = batch.kind === "ready" ? batch.data : null;
151
+ const statement = data?.statements[statementIndex];
152
+ const expected = data ? data.requested - data.refused.length : 0;
153
+ return <BodyPortal><div className="collection-overlay">
154
+ <section ref={panelRef} className="collection-modal" role="dialog" aria-modal="true" aria-labelledby="collection-batch-title" tabIndex={-1}>
155
+ <header className="collection-dialog-header">
156
+ <h2 id="collection-batch-title">{confirming ? "Confirm batch" : "Batch preview"}</h2>
157
+ <button type="button" className="collection-button" onClick={onClose}>{sending ? "Close" : "Cancel"}</button>
158
+ </header>
159
+ <div className="collection-dialog-body">
160
+ {batch.kind === "loading" && <div role="status" aria-busy="true" aria-label="Preparing statement previews"><span className="collection-preview-skeleton" /></div>}
161
+ {batch.kind === "error" && <p role="alert">{batch.message}</p>}
162
+ {data && <>
163
+ <p className="collection-batch-count">{plural(data.requested, "customer", "customers")} selected. {plural(expected, "statement", "statements")} can be queued; {count.format(data.refused.length)} will be refused.</p>
164
+ {confirming ? <>
165
+ <p>Queue one statement per eligible customer in Odoo's outbox?</p>
166
+ <p className="collection-muted">Balances and recipients are read again when you confirm.</p>
167
+ <Refusals items={data.refused} />
168
+ </> : <>
169
+ <p className="collection-muted">From {data.sender.name} ({data.sender.email}). Replies go to {data.sender.replyTo}.</p>
170
+ {statement && <>
171
+ <label className="collection-field">Customer
172
+ <select value={statementIndex} onChange={event => setStatementIndex(Number(event.target.value))}>
173
+ {data.statements.map((item, index) => <option key={item.partnerId} value={index}>{item.customer}{item.refusal ? " (will be refused)" : ""}</option>)}
174
+ </select>
175
+ </label>
176
+ <dl className="collection-preview-details">
177
+ <div><dt>To</dt><dd>{statement.to || "No email address"}</dd></div>
178
+ <div><dt>Subject</dt><dd>{statement.subject}</dd></div>
179
+ </dl>
180
+ {statement.refusal && <p className="collection-notice">{statement.refusal}</p>}
181
+ <div className="collection-preview-scroll" tabIndex={0} role="region" aria-label="Rendered statement">
182
+ {/* Scripts and remote resources are blocked. The frame is read-only and sized to
183
+ its content, so scrolling and Escape stay in the parent overlay. */}
184
+ <iframe key={statement.partnerId} className="collection-statement" title={`Statement for ${statement.customer}`}
185
+ sandbox="allow-same-origin" tabIndex={-1} referrerPolicy="no-referrer"
186
+ onLoad={event => {
187
+ const frame = event.currentTarget;
188
+ const content = frame.contentDocument?.documentElement;
189
+ if (!content) return;
190
+ frame.style.width = `${Math.max(frame.clientWidth, content.scrollWidth)}px`;
191
+ frame.style.height = `${Math.max(240, content.scrollHeight)}px`;
192
+ }}
193
+ srcDoc={`<!doctype html><html><head><meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'"></head><body>${statement.html}</body></html>`} />
194
+ </div>
195
+ </>}
196
+ {!statement && <Refusals items={data.refused} />}
197
+ </>}
198
+ </>}
199
+ </div>
200
+ {data && <footer className="collection-dialog-footer">
201
+ <p id="collection-send-policy" className={data.safeMode ? "collection-notice" : "collection-muted"}>{safeModeNotice(data)}</p>
202
+ {sending && <p role="status">Queueing continues if you close this dialog.</p>}
203
+ <div className="collection-dialog-actions">
204
+ {confirming && !sending && <button type="button" className="collection-button" onClick={() => setConfirming(false)}>Back</button>}
205
+ {confirming ? <button ref={confirmRef} type="button" className="collection-button collection-button--send" disabled={sending || !expected}
206
+ aria-describedby="collection-send-policy" onClick={() => onSend(batch.ids)}>{sending ? "Queueing statements" : "Confirm send"}</button>
207
+ : <button ref={sendRef} type="button" className="collection-button collection-button--primary" disabled={!expected}
208
+ aria-describedby="collection-send-policy" onClick={() => setConfirming(true)}>Send</button>}
209
+ </div>
210
+ </footer>}
211
+ </section>
212
+ </div></BodyPortal>;
213
+ }
214
+
215
+ export default function CollectionPage() {
216
+ const [page, setPage] = useState<PageState>({ kind: "loading" });
217
+ const [reload, setReload] = useState(0);
218
+ const [query, setQuery] = useState("");
219
+ const [tier, setTier] = useState("");
220
+ const [selected, setSelected] = useState<Set<number>>(new Set());
221
+ const [customer, setCustomer] = useState<CollectionRow | null>(null);
222
+ const [batch, setBatch] = useState<BatchState | null>(null);
223
+ const [sending, setSending] = useState(false);
224
+ const [result, setResult] = useState<SendResult | null>(null);
225
+ const [sendError, setSendError] = useState("");
226
+ const [sendUnconfirmed, setSendUnconfirmed] = useState(false);
227
+ const sendLock = useRef(false);
228
+ const selectAllRef = useRef<HTMLInputElement>(null);
229
+ const previewRequest = useRef<AbortController | null>(null);
230
+ const refreshRef = useRef<HTMLButtonElement>(null);
231
+
232
+ useEffect(() => {
233
+ const controller = new AbortController();
234
+ setPage({ kind: "loading" });
235
+ setSelected(new Set());
236
+ void fetch(`${API_V1}/apps/collection/worklist`, { credentials: CREDENTIALS, signal: controller.signal }).then(async response => {
237
+ if (checkTenant(response)) return;
238
+ if (response.status === 401) raiseEvent(UNAUTHORIZED_EVENT);
239
+ if (!response.ok) {
240
+ const message = await responseError(response);
241
+ setPage({ kind: [401, 403, 404].includes(response.status) ? "restricted" : "error", message });
242
+ return;
243
+ }
244
+ const data = await response.json() as Worklist;
245
+ if (!controller.signal.aborted) setPage({ kind: "ready", data });
246
+ }).catch(() => {
247
+ if (!controller.signal.aborted) setPage({ kind: "error", message: "The Collection worklist could not be loaded." });
248
+ });
249
+ return () => controller.abort();
250
+ }, [reload]);
251
+ useEffect(() => () => previewRequest.current?.abort(), []);
252
+
253
+ const data = page.kind === "ready" ? page.data : null;
254
+ const rows = useMemo(() => data?.rows ?? [], [data]);
255
+ const tiers = useMemo(() => Array.from(new Set(rows.map(row => row.Tier))), [rows]);
256
+ const visible = useMemo(() => {
257
+ const search = query.trim().toLocaleLowerCase();
258
+ return rows.filter(row => (!tier || row.Tier === tier) &&
259
+ (!search || `${row.Customer} ${row.Email} ${row.Phone}`.toLocaleLowerCase().includes(search)));
260
+ }, [rows, query, tier]);
261
+ const selectedVisible = visible.filter(row => selected.has(row.partner_id)).length;
262
+ const allVisible = visible.length > 0 && selectedVisible === visible.length;
263
+ useEffect(() => {
264
+ if (selectAllRef.current) selectAllRef.current.indeterminate = selectedVisible > 0 && !allVisible;
265
+ }, [selectedVisible, allVisible]);
266
+
267
+ function toggleVisible() {
268
+ setSelected(previous => {
269
+ const next = new Set(previous);
270
+ visible.forEach(row => { if (allVisible) next.delete(row.partner_id); else next.add(row.partner_id); });
271
+ return next;
272
+ });
273
+ }
274
+
275
+ function closeBatch() {
276
+ previewRequest.current?.abort();
277
+ setBatch(null);
278
+ }
279
+
280
+ async function previewBatch() {
281
+ if (!selected.size || sendLock.current || sendUnconfirmed) return;
282
+ const ids = [...selected];
283
+ const controller = new AbortController();
284
+ previewRequest.current?.abort();
285
+ previewRequest.current = controller;
286
+ setBatch({ kind: "loading", ids });
287
+ setSendError("");
288
+ try {
289
+ const response = await fetch(`${API_V1}/apps/collection/preview`, { method: "POST", credentials: CREDENTIALS,
290
+ signal: controller.signal, headers: { "Content-Type": "application/json" },
291
+ body: JSON.stringify({ partnerIds: ids }) });
292
+ if (checkTenant(response)) return;
293
+ if (response.status === 401) raiseEvent(UNAUTHORIZED_EVENT);
294
+ if (!response.ok) throw new Error(await responseError(response));
295
+ const preview = await response.json() as Preview;
296
+ if (!controller.signal.aborted) setBatch({ kind: "ready", ids, data: preview });
297
+ } catch (error) {
298
+ if (!controller.signal.aborted) setBatch({ kind: "error", ids, message: error instanceof Error ? error.message : "Statement previews could not be loaded." });
299
+ }
300
+ }
301
+
302
+ async function sendBatch(ids: number[]) {
303
+ if (sendLock.current) return;
304
+ sendLock.current = true;
305
+ setSending(true);
306
+ setResult(null);
307
+ setSendError("");
308
+ // Never retry a write automatically: a lost response can follow successful mail creation.
309
+ let uncertain = true;
310
+ try {
311
+ const response = await fetch(`${API_V1}/apps/collection/send`, { method: "POST", credentials: CREDENTIALS,
312
+ headers: { "Content-Type": "application/json" }, body: JSON.stringify({ partnerIds: ids, confirm: true }) });
313
+ if (checkTenant(response)) return;
314
+ if (response.status === 401) raiseEvent(UNAUTHORIZED_EVENT);
315
+ if (!response.ok) {
316
+ uncertain = response.status >= 500;
317
+ throw new Error(await responseError(response));
318
+ }
319
+ const sent = await response.json() as SendResult;
320
+ setResult(sent);
321
+ setSelected(new Set());
322
+ } catch (error) {
323
+ setSendUnconfirmed(uncertain);
324
+ setSendError(uncertain
325
+ ? "The batch result is unconfirmed. Some statements may already be in Odoo's outbox. Check Odoo before starting another batch."
326
+ : error instanceof Error ? error.message : "The batch was refused.");
327
+ } finally {
328
+ sendLock.current = false;
329
+ setSending(false);
330
+ setBatch(null);
331
+ window.requestAnimationFrame(() => refreshRef.current?.focus());
332
+ }
333
+ }
334
+
335
+ return <section className="collection-page" aria-label="Collection">
336
+ <header className="collection-header">
337
+ <h1>Collection</h1>
338
+ <button ref={refreshRef} type="button" className="collection-button" disabled={page.kind === "loading" || sending}
339
+ onClick={() => setReload(value => value + 1)}>Refresh</button>
340
+ </header>
341
+ {page.kind === "loading" && <TableSkeleton />}
342
+ {page.kind === "restricted" && <div className="collection-empty" role="status"><p>{page.message}</p></div>}
343
+ {page.kind === "error" && <div className="collection-empty" role="alert"><p>{page.message}</p>
344
+ <button type="button" className="collection-button" onClick={() => setReload(value => value + 1)}>Try again</button></div>}
345
+ {data && <>
346
+ <div className="collection-toolbar">
347
+ <label className="collection-field">Search<input type="search" value={query} onChange={event => setQuery(event.target.value)} placeholder="Customer, email or phone" /></label>
348
+ <label className="collection-field">Tier<select value={tier} onChange={event => setTier(event.target.value)}>
349
+ <option value="">All tiers</option>{tiers.map(value => <option key={value} value={value}>{value}</option>)}
350
+ </select></label>
351
+ <div className="collection-selection" role="status" aria-live="polite">
352
+ <span>{count.format(visible.length)} of {count.format(rows.length)} customers</span>
353
+ <span>{count.format(selected.size)} selected{selected.size > selectedVisible ? ` (${count.format(selected.size - selectedVisible)} outside this filter)` : ""}</span>
354
+ </div>
355
+ <button type="button" className="collection-button" disabled={!selected.size || sending} onClick={() => setSelected(new Set())}>Clear selection</button>
356
+ <button type="button" className="collection-button collection-button--primary" disabled={!selected.size || sending || sendUnconfirmed}
357
+ aria-describedby="collection-worklist-policy" onClick={() => void previewBatch()}>Preview batch</button>
358
+ </div>
359
+ <p id="collection-worklist-policy" className={data.safeMode ? "collection-notice" : "collection-muted"}>{safeModeNotice(data)}</p>
360
+ {sending && <p role="status">Queueing statements in Odoo's outbox.</p>}
361
+ {sendError && <div className="collection-result" role="alert"><p>{sendError}</p>
362
+ {sendUnconfirmed && <button type="button" className="collection-button" onClick={() => { setSendUnconfirmed(false); setSendError(""); setSelected(new Set()); setReload(value => value + 1); }}>I checked Odoo's outbox</button>}
363
+ </div>}
364
+ {result && <section className="collection-result" aria-label="Batch result">
365
+ <p role="status">{plural(result.created, "mail.mail record", "mail.mail records")} created in Odoo's outbox. {plural(result.refused.length, "customer", "customers")} refused.{result.safeMode ? " Safe mode was on." : ""}</p>
366
+ <Refusals items={result.refused} />
367
+ </section>}
368
+ {!rows.length ? <div className="collection-empty"><p>No customers on the Collection worklist.</p></div>
369
+ : !visible.length ? <div className="collection-empty"><p>No customers match these filters.</p>
370
+ <button type="button" className="collection-button" onClick={() => { setQuery(""); setTier(""); }}>Clear filters</button></div>
371
+ : <div className="collection-table-scroll" tabIndex={0} role="region" aria-label="Collection worklist">
372
+ <table className="collection-table">
373
+ <thead><tr>
374
+ <th scope="col" className="collection-check"><input ref={selectAllRef} type="checkbox" checked={allVisible} disabled={sending}
375
+ onChange={toggleVisible} aria-label={`Select all ${plural(visible.length, "visible customer", "visible customers")}`} /></th>
376
+ {columns.map((label, index) => <th scope="col" key={label} className={index >= 2 && index <= 5 ? "collection-number" : undefined}>{label}</th>)}
377
+ </tr></thead>
378
+ <tbody>{visible.map(row => <tr key={row.partner_id} className={`collection-data-row${selected.has(row.partner_id) ? " collection-row--selected" : ""}`}
379
+ onClick={event => { event.currentTarget.querySelector("button")?.focus(); setCustomer(row); }}>
380
+ <td className="collection-check" onClick={event => event.stopPropagation()}><input type="checkbox" checked={selected.has(row.partner_id)} disabled={sending}
381
+ title={row.sendRefusal || undefined} aria-label={row.sendRefusal ? `Select ${row.Customer}. ${row.sendRefusal}` : `Select ${row.Customer}`}
382
+ onChange={() => setSelected(previous => { const next = new Set(previous); if (next.has(row.partner_id)) next.delete(row.partner_id); else next.add(row.partner_id); return next; })} /></td>
383
+ <td><button type="button" className="collection-button collection-customer" onClick={() => setCustomer(row)}>{row.Customer}</button></td>
384
+ <td>{row.Tier}</td><td className="collection-number collection-overdue">{money.format(row.Overdue)}</td>
385
+ <td className="collection-number">{money.format(row.Receivable)}</td><td className="collection-number">{count.format(row["Oldest (days)"])}</td>
386
+ <td className="collection-number">{count.format(row["Open Docs"])}</td><td>{row.Email || "No email address"}</td><td>{row.Phone || "Not recorded"}</td>
387
+ <td>{row.Status || "Not recorded"}</td><td>{row["Reconcile?"] ? "Review" : "Clear"}</td>
388
+ </tr>)}</tbody>
389
+ </table>
390
+ </div>}
391
+ </>}
392
+ {customer && <CustomerDrawer row={customer} onClose={() => setCustomer(null)} />}
393
+ {batch && <BatchDialog batch={batch} sending={sending} onClose={closeBatch} onSend={ids => void sendBatch(ids)} />}
394
+ </section>;
395
+ }
web/src/apps/collection.css ADDED
@@ -0,0 +1,152 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ .collection-page {
2
+ display: flex;
3
+ flex-direction: column;
4
+ gap: 16px;
5
+ width: 100%;
6
+ height: 100%;
7
+ min-height: 0;
8
+ min-width: 0;
9
+ padding: 32px;
10
+ overflow: auto;
11
+ color: var(--lp-ink);
12
+ background: var(--lp-wash);
13
+ font: 400 var(--lp-fs-sm)/var(--lp-lh) "Inter", sans-serif;
14
+ font-variant-numeric: tabular-nums;
15
+ }
16
+
17
+ .collection-page h1,
18
+ .collection-overlay h2,
19
+ .collection-overlay h3 { margin: 0; font-weight: 600; line-height: var(--lp-lh-tight); }
20
+ .collection-page h1 { font-size: var(--lp-fs-lg); }
21
+ .collection-overlay h2 { font-size: var(--lp-fs-md); }
22
+ .collection-overlay h3 { font-size: var(--lp-fs-sm); }
23
+ .collection-page p,
24
+ .collection-overlay p { margin: 0; }
25
+ .collection-muted { color: var(--lp-muted); }
26
+
27
+ .collection-header,
28
+ .collection-toolbar,
29
+ .collection-dialog-header,
30
+ .collection-dialog-actions { display: flex; align-items: center; gap: 16px; }
31
+ .collection-header,
32
+ .collection-dialog-header { justify-content: space-between; }
33
+ .collection-header,
34
+ .collection-toolbar { flex: 0 0 auto; }
35
+ .collection-toolbar { align-items: flex-end; flex-wrap: wrap; gap: 8px; }
36
+ .collection-selection { display: flex; flex-direction: column; margin-right: auto; padding: 0 8px; font-size: var(--lp-fs-2xs); color: var(--lp-muted); }
37
+ .collection-field { display: flex; flex-direction: column; gap: 4px; color: var(--lp-muted); font-size: var(--lp-fs-2xs); }
38
+ .collection-field input,
39
+ .collection-field select { height: 36px; max-width: 100%; min-width: 0; padding: 0 8px; border: 1px solid var(--lp-line-strong); border-radius: var(--lp-r-md); background: var(--lp-surface); color: var(--lp-ink); font: inherit; }
40
+
41
+ .collection-button {
42
+ border: 0;
43
+ background: transparent;
44
+ font: inherit;
45
+ color: inherit;
46
+ min-height: 36px;
47
+ padding: 8px 12px;
48
+ border-radius: var(--lp-r-md);
49
+ font-weight: 500;
50
+ cursor: pointer;
51
+ }
52
+ .collection-button--primary { background: var(--lp-primary); color: var(--lp-surface); }
53
+ .collection-button--send { background: var(--lp-red-deep); color: var(--lp-surface); }
54
+ .collection-button:disabled,
55
+ .collection-page input:disabled { opacity: 0.5; cursor: not-allowed; }
56
+ .collection-button:focus-visible,
57
+ .collection-field input:focus-visible,
58
+ .collection-field select:focus-visible,
59
+ .collection-page input[type="checkbox"]:focus-visible,
60
+ .collection-table-scroll:focus-visible,
61
+ .collection-document-scroll:focus-visible,
62
+ .collection-preview-scroll:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: 2px; }
63
+
64
+ .collection-notice { color: var(--lp-yellow-deep); font-size: var(--lp-fs-xs); }
65
+ .collection-table-scroll {
66
+ flex: 1 1 320px;
67
+ min-height: 240px;
68
+ min-width: 0;
69
+ overflow: auto;
70
+ isolation: isolate;
71
+ scrollbar-gutter: stable;
72
+ border: 1px solid var(--lp-line);
73
+ border-radius: var(--lp-r-md);
74
+ background: var(--lp-surface);
75
+ }
76
+ .collection-table { width: 100%; border-collapse: separate; border-spacing: 0; font-size: var(--lp-fs-xs); }
77
+ .collection-table th,
78
+ .collection-table td { padding: 12px; border-bottom: 1px solid var(--lp-line); text-align: left; white-space: nowrap; }
79
+ .collection-table th { position: sticky; top: 0; z-index: var(--cg-z-editor); background: var(--lp-surface-2); color: var(--lp-muted); font-weight: 500; }
80
+ .collection-table tr:last-child td { border-bottom: 0; }
81
+ .collection-table .collection-number,
82
+ .collection-number { text-align: right; font-variant-numeric: tabular-nums; }
83
+ .collection-overdue { color: var(--lp-red-deep); }
84
+ .collection-check { width: 40px; }
85
+ .collection-check input { width: 16px; height: 16px; margin: 0; vertical-align: middle; accent-color: var(--lp-blue-solid); }
86
+ .collection-customer { padding: 0; min-height: 24px; text-align: left; text-decoration: underline; text-underline-offset: 4px; }
87
+ .collection-row--selected td { background: var(--lp-blue-tint); }
88
+ .collection-data-row { cursor: pointer; }
89
+ .collection-empty { padding: 24px 0; display: flex; align-items: center; gap: 16px; color: var(--lp-muted); }
90
+ .collection-result { flex: 0 0 auto; padding: 12px 0; border-block: 1px solid var(--lp-line); }
91
+ .collection-refusals { margin-top: 8px; }
92
+ .collection-refusals summary { cursor: pointer; }
93
+ .collection-refusals ul { margin: 8px 0 0; padding-left: 24px; max-height: 160px; overflow: auto; }
94
+ .collection-refusals li { margin: 4px 0; }
95
+ .collection-refusals strong { font-weight: 500; }
96
+
97
+ .collection-overlay {
98
+ position: fixed;
99
+ inset: 0;
100
+ z-index: var(--cg-z-record);
101
+ display: flex;
102
+ align-items: center;
103
+ justify-content: center;
104
+ padding: 24px;
105
+ background: color-mix(in srgb, var(--lp-ink) 24%, transparent);
106
+ color: var(--lp-ink);
107
+ font: 400 var(--lp-fs-sm)/var(--lp-lh) "Inter", sans-serif;
108
+ font-variant-numeric: tabular-nums;
109
+ }
110
+ .collection-overlay--drawer { justify-content: flex-end; align-items: stretch; padding: 0; z-index: var(--cg-z-drawer); }
111
+ .collection-modal,
112
+ .collection-drawer { display: flex; flex-direction: column; min-height: 0; min-width: 0; background: var(--lp-surface); border: 1px solid var(--lp-line); }
113
+ .collection-modal { width: min(880px, 100%); max-height: 100%; border-radius: var(--lp-r-lg); }
114
+ .collection-drawer { width: min(760px, 100%); height: 100%; }
115
+ .collection-dialog-header { flex-shrink: 0; padding: 16px 24px; border-bottom: 1px solid var(--lp-line); }
116
+ .collection-dialog-header h2 { overflow-wrap: anywhere; }
117
+ .collection-dialog-body { min-height: 0; padding: 24px; overflow: auto; display: flex; flex-direction: column; gap: 16px; }
118
+ .collection-dialog-footer { flex-shrink: 0; padding: 16px 24px; border-top: 1px solid var(--lp-line); display: flex; flex-direction: column; gap: 12px; }
119
+ .collection-dialog-actions { justify-content: flex-end; gap: 8px; }
120
+ .collection-details,
121
+ .collection-preview-details { margin: 0; }
122
+ .collection-details > div,
123
+ .collection-preview-details > div { display: grid; grid-template-columns: 104px minmax(0, 1fr); gap: 16px; padding: 8px 0; }
124
+ .collection-details dt,
125
+ .collection-preview-details dt { color: var(--lp-muted); }
126
+ .collection-details dd,
127
+ .collection-preview-details dd { margin: 0; overflow-wrap: anywhere; }
128
+ .collection-document-scroll { overflow: auto; min-height: 160px; }
129
+ .collection-preview-scroll { overflow: auto; max-height: 400px; flex-shrink: 0; }
130
+ .collection-statement { display: block; width: 100%; height: 240px; border: 0; background: var(--lp-surface); pointer-events: none; }
131
+ .collection-skeleton,
132
+ .collection-preview-skeleton { display: block; background: var(--lp-surface-2); border-radius: var(--lp-r-md); }
133
+ .collection-skeleton { height: 16px; min-width: 48px; }
134
+ .collection-preview-skeleton { height: 320px; }
135
+
136
+ @media (hover: hover) and (pointer: fine) {
137
+ .collection-button:hover:not(:disabled) { background: var(--lp-surface-2); }
138
+ .collection-button--primary:hover:not(:disabled) { background: var(--lp-primary-hover); }
139
+ .collection-button--send:hover:not(:disabled) { background: var(--lp-red-deep); }
140
+ .collection-table tbody tr:hover td { background: var(--lp-blue-tint); }
141
+ }
142
+ @media (max-width: 720px) {
143
+ .collection-page { padding: 16px; }
144
+ .collection-header { align-items: flex-start; }
145
+ .collection-toolbar .collection-field { flex: 1; min-width: 128px; }
146
+ .collection-selection { width: 100%; padding: 4px 0; }
147
+ .collection-overlay { padding: 8px; }
148
+ .collection-overlay--drawer { padding: 0; }
149
+ .collection-dialog-header,
150
+ .collection-dialog-body,
151
+ .collection-dialog-footer { padding: 16px; }
152
+ }
web/src/customer-grid/CustomerGrid.tsx CHANGED
@@ -2223,7 +2223,9 @@ function CustomerGridSurface({
2223
  * ⚠ OFF FOR AN EMBEDDED GRID. A linked-record picker inside a modal is not a table anybody keeps
2224
  * marks on, and the read would be one request per relation cell.
2225
  */
2226
- const recordStars = useRecordStars(scope, !embedded);
 
 
2227
  const [alerted, setAlerted] = useState<string[]>([]);
2228
  useEffect(() => {
2229
  // `hostWorkspace`, not `embedded`: the alert badges paint on the SOURCE database's view rail,
@@ -4797,7 +4799,12 @@ function CustomerGridSurface({
4797
  setNotesUnread(Array.isArray(body?.subjects) ? body.subjects : []);
4798
  } catch { /* a badge is not worth an error state; it simply stays as it was */ }
4799
  }, [activeViewId, scope, embedded, embeddedPayload]);
4800
- useEffect(() => { void refreshNotesUnread(); }, [refreshNotesUnread]);
 
 
 
 
 
4801
  /**
4802
  * ⭐⭐ W47-T16 — OPENING A NOTE IS WHAT MARKS IT READ, and the version comes from the note
4803
  * the viewer is actually looking at. The server refuses to take a subject id from the body
 
2223
  * ⚠ OFF FOR AN EMBEDDED GRID. A linked-record picker inside a modal is not a table anybody keeps
2224
  * marks on, and the read would be one request per relation cell.
2225
  */
2226
+ // S65-T12: record stars are a decoration; racing the rows fetch measured 5,960 ms.
2227
+ // Serialising the five calls was 1.74x faster end to end. Ask after the first rows land.
2228
+ const recordStars = useRecordStars(scope, !embedded && !loading);
2229
  const [alerted, setAlerted] = useState<string[]>([]);
2230
  useEffect(() => {
2231
  // `hostWorkspace`, not `embedded`: the alert badges paint on the SOURCE database's view rail,
 
4799
  setNotesUnread(Array.isArray(body?.subjects) ? body.subjects : []);
4800
  } catch { /* a badge is not worth an error state; it simply stays as it was */ }
4801
  }, [activeViewId, scope, embedded, embeddedPayload]);
4802
+ // S65-T12: the unread badge is a decoration; racing the rows fetch measured 18,293 ms.
4803
+ // Serialising the five calls was 1.74x faster end to end. Ask after the first rows land.
4804
+ useEffect(() => {
4805
+ if (loading) return;
4806
+ void refreshNotesUnread();
4807
+ }, [loading, refreshNotesUnread]);
4808
  /**
4809
  * ⭐⭐ W47-T16 — OPENING A NOTE IS WHAT MARKS IT READ, and the version comes from the note
4810
  * the viewer is actually looking at. The server refuses to take a subject id from the body
web/src/customer-grid/apiBridge.ts CHANGED
@@ -1363,7 +1363,8 @@ function refreshVisibleChanges(): void {
1363
  * overnight creates no database traffic.
1364
  */
1365
  export function subscribeChanges(scope: string,
1366
- onChange: (changed: string[]) => void): () => void {
 
1367
  if (typeof window === "undefined") return () => {};
1368
  let watch = changeWatches.get(scope);
1369
  if (!watch) {
@@ -1389,9 +1390,10 @@ export function subscribeChanges(scope: string,
1389
  const w = watch;
1390
  w.listeners.add(onChange);
1391
 
1392
- // One tiny revision baseline after the necessary initial data load lets later user returns
1393
- // preserve the browser cache when nothing changed. It is never an interval.
1394
- if (w.tokens === null && !w.inFlight) void w.refresh();
 
1395
 
1396
  if (!visibilityBound) {
1397
  visibilityBound = true;
@@ -1409,6 +1411,12 @@ export function subscribeChanges(scope: string,
1409
  };
1410
  }
1411
 
 
 
 
 
 
 
1412
  /**
1413
  * X2 `PATCH /api/v1/<topic.rowsPath>/{pid}` — the overlay stratum only (Odoo is never
1414
  * written). Kept as its own route rather than folded into the events log
 
1363
  * overnight creates no database traffic.
1364
  */
1365
  export function subscribeChanges(scope: string,
1366
+ onChange: (changed: string[]) => void,
1367
+ { baseline = true }: { baseline?: boolean } = {}): () => void {
1368
  if (typeof window === "undefined") return () => {};
1369
  let watch = changeWatches.get(scope);
1370
  if (!watch) {
 
1390
  const w = watch;
1391
  w.listeners.add(onChange);
1392
 
1393
+ // S65-T12: baseline on subscribe by default; grids defer this read until their first payload
1394
+ // lands. Racing the rows fetch cost 4,857 ms; the same read alone took 5 ms. Later user returns
1395
+ // can still preserve the browser cache when nothing changed. It is never an interval.
1396
+ if (baseline) primeChangeBaseline(scope);
1397
 
1398
  if (!visibilityBound) {
1399
  visibilityBound = true;
 
1411
  };
1412
  }
1413
 
1414
+ /** Take a subscribed scope's first baseline through its ONE guarded refresh path. */
1415
+ export function primeChangeBaseline(scope: string): void {
1416
+ const w = changeWatches.get(scope);
1417
+ if (w && w.tokens === null && !w.inFlight) void w.refresh();
1418
+ }
1419
+
1420
  /**
1421
  * X2 `PATCH /api/v1/<topic.rowsPath>/{pid}` — the overlay stratum only (Odoo is never
1422
  * written). Kept as its own route rather than folded into the events log
web/src/customer-grid/useCustomerData.ts CHANGED
@@ -37,6 +37,7 @@ import {
37
  savePersonalGridLayout,
38
  mergeWindow,
39
  patchTopicRow,
 
40
  readThroughTables,
41
  usesPinnedRows,
42
  setSurfaceScope,
@@ -464,7 +465,7 @@ export function useCustomerData(
464
  coalescing = setTimeout(() => { coalescing = null; readRows(); }, wait);
465
  }
466
  if (plan.rereadWorkspace) signal(WORKSPACE_STALE_EVENT);
467
- });
468
 
469
  return () => {
470
  unsubscribe();
@@ -808,6 +809,12 @@ export function useCustomerData(
808
  // answer for one frame while an effect catches up. The supplied object remains immutable.
809
  const visibleData = suppliedPayload ? embeddedPayload : data;
810
 
 
 
 
 
 
 
811
  return {
812
  fields: visibleData?.fields ?? [],
813
  rawRows: visibleData?.rows ?? [],
 
37
  savePersonalGridLayout,
38
  mergeWindow,
39
  patchTopicRow,
40
+ primeChangeBaseline,
41
  readThroughTables,
42
  usesPinnedRows,
43
  setSurfaceScope,
 
465
  coalescing = setTimeout(() => { coalescing = null; readRows(); }, wait);
466
  }
467
  if (plan.rereadWorkspace) signal(WORKSPACE_STALE_EVENT);
468
+ }, { baseline: false });
469
 
470
  return () => {
471
  unsubscribe();
 
809
  // answer for one frame while an effect catches up. The supplied object remains immutable.
810
  const visibleData = suppliedPayload ? embeddedPayload : data;
811
 
812
+ useEffect(() => {
813
+ if (suppliedPayload || STREAMLIT_COMPONENT || readEmbed() || visibleData === null) return;
814
+ // S65-T12: the listener is already wired while loading; only its first token read waits.
815
+ primeChangeBaseline(topic.scope);
816
+ }, [scope, topic, suppliedPayload, visibleData]);
817
+
818
  return {
819
  fields: visibleData?.fields ?? [],
820
  rawRows: visibleData?.rows ?? [],
web/src/home/HomePage.tsx CHANGED
@@ -39,7 +39,7 @@ import "../styles/wave61/rails.css";
39
  import { AGENTS_MODULE_LABEL } from "../inbox/inboxModel";
40
  // AgentIcon carries the rail's shell-nav-icon class, which supplies its stroke-only paint.
41
  import { AgentIcon } from "../shell/icons";
42
- import { agentAddressHash, dataAddressHash, readDataAddress, MAX_NAV_FOLDERS } from "../shell/nav";
43
  import type { DatabaseEntry, NavFolder, 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
@@ -195,17 +195,20 @@ function SheetGlyph() {
195
  );
196
  }
197
 
198
- interface ApplicationTile {
199
  id: string;
200
  name: string;
201
  type: string;
202
  templateKind?: string;
 
203
  compatibleDatabases?: string[];
204
- openTarget?: { database?: string };
205
  starred?: boolean;
206
  capabilities?: { star?: boolean; delete?: boolean };
207
  }
208
 
 
 
209
  interface SheetTile {
210
  id: string;
211
  name: string;
@@ -335,6 +338,8 @@ function QuickCard({
335
  export interface HomeProps {
336
  /** Each gallery reuses Home's directory anatomy. */
337
  mode?: "home" | "app" | "data" | "sheet" | "agents";
 
 
338
  /** Compatibility entry for a retired `#/starred` bookmark. */
339
  initialStarredOnly?: boolean;
340
  /**
@@ -593,9 +598,6 @@ export function HomeSurface({
593
  : suppliedModuleIndex;
594
  const indexKnown = moduleHome && moduleIndex !== null;
595
  const folderWritable = indexKnown && !moduleIndexBusy && !moduleIndexError;
596
- const [folderWanted, setFolderWanted] = useState(false);
597
- const sheetFolderEarlyPaint = mode === "sheet";
598
- const folderAwaiting = folderWanted && !folderWritable && !moduleIndexError;
599
  const [folderEdit, setFolderEdit] = useState<{ id: string | null; name: string } | null>(null);
600
  const [folderAnchor, setFolderAnchor] = useState<HTMLElement | null>(null);
601
  const [movePicker, setMovePicker] = useState(false);
@@ -611,19 +613,9 @@ export function HomeSurface({
611
  const levelApplications = mode === "app" ? appLevel.items : visibleApplications;
612
  const levelSheets = mode === "sheet" ? sheetLevel.items : visibleSheets;
613
  const levelDatabases = mode === "data" ? dataLevel.items : visibleDatabases;
614
- useEffect(() => {
615
- if (!folderWanted) return;
616
- if (moduleIndexError) {
617
- setFolderWanted(false);
618
- } else if (folderWritable) {
619
- setFolderWanted(false);
620
- setFolderEdit({ id: null, name: "" });
621
- }
622
- }, [folderWanted, folderWritable, moduleIndexError]);
623
  useEffect(() => {
624
  setFolderAt(mode === "data" ? new URLSearchParams(window.location.hash.split("?")[1]).get("folder") : null);
625
  setFolderEdit(null);
626
- setFolderWanted(false);
627
  setMovePicker(false);
628
  setDraggedIds([]);
629
  selection.clear();
@@ -679,10 +671,8 @@ export function HomeSurface({
679
  if (!link || link.target === "_blank") return;
680
  event.preventDefault();
681
  const href = link.getAttribute("href") ?? "";
682
- const origin = window.location.hash;
683
- void openExistingItem({ kind, id }, () => {
684
- if (window.location.hash === origin) window.location.hash = href;
685
- }, { voice });
686
  };
687
  const folderDropEvents = (target: string | null) => ({
688
  onDragOver: (event: DragEvent<HTMLElement>) => {
@@ -697,31 +687,28 @@ export function HomeSurface({
697
  setDraggedIds([]);
698
  },
699
  });
700
- // Owner instruction 6: Sheet paints New folder in the first frame with its siblings.
701
- // sheetFolderEarlyPaint moves safety to the action: onSaveModuleIndex and moveTiles both
702
- // assume a non-null moduleIndex. App and Agents retain their current behavior because
703
- // api_home's W61-T20 render leg asserts it, and this lane does not own that gate.
704
- const newFolderControl = folderWritable || sheetFolderEarlyPaint ? (
705
  <QuickCard
706
  icon={<span className="home-card-icon" aria-hidden="true"><FolderMark size={16} /></span>}
707
  title="New folder"
708
  detail="Group items in this module into folders."
709
- holdDetail={folderAwaiting ? "Waiting for folders to load." : undefined}
710
  disabled={mode === "data" && folders.length >= MAX_NAV_FOLDERS}
711
  buttonTitle={mode === "data" && folders.length >= MAX_NAV_FOLDERS ? "Folder limit reached" : undefined}
712
- holdReason={sheetFolderEarlyPaint && !folderWritable
713
  ? moduleIndexError
714
  ? "Folders could not load. Use Reload folders to try again."
715
- : folderAwaiting ? "The dialog opens as soon as the folder list loads." : undefined
716
  : undefined}
717
- busy={folderAwaiting}
718
  onClick={(event) => {
 
719
  setFolderAnchor(event.currentTarget);
720
- if (folderWritable) { setFolderEdit({ id: null, name: "" }); return; }
721
- setFolderWanted(true);
722
  }}
723
  />
724
- ) : <span className="home-card-ghost" aria-hidden="true" />;
725
  const renderModuleFolders = () => (
726
  <section className="home-section" aria-label="Module folders">
727
  {moduleIndexError ? <p className="home-app-note" role="alert">{moduleIndexError}
@@ -942,12 +929,12 @@ export function HomeSurface({
942
  pill in the header while Home offered a card, and BOTH OPEN THE SAME DOOR: `Shell.tsx`
943
  hands `openApplicationWizard` to each of them and says so in its own comment. One door
944
  wearing two looks is the defect, so App now wears Home's card: same component, same
945
- glyph, same tokens. The folder control and remaining ghost reserve the tracks (see
946
- `styles/wave57/home-app.css` for why they cannot be `display: none`). */}
947
  <QuickCard
948
  icon={<TemplateIcon />}
949
  title="Create new"
950
- detail="Build an app over a database in this workspace."
951
  onClick={onTemplates}
952
  />
953
  <QuickCard icon={<TemplateIcon />} title="Templates"
@@ -1075,7 +1062,7 @@ export function HomeSurface({
1075
  const database = application.openTarget?.database
1076
  ?? application.compatibleDatabases?.[0]
1077
  ?? "";
1078
- const kind = application.templateKind === "catalog"
1079
  ? "Catalog"
1080
  : application.templateKind === "route"
1081
  ? "Routing"
@@ -1084,11 +1071,22 @@ export function HomeSurface({
1084
  <div className={"st-tilewrap home-app-tile" + (application.capabilities?.delete === true ? " can-delete" : "")} key={application.id}>
1085
  <a
1086
  className={"home-tile" + (mode === "app" ? " cg-view-row" + (selection.isSelected(application.id) ? " is-railsel" : "") : "")}
1087
- href={database
1088
  ? appPathHash({ database, application: application.id })
1089
  : "#/app"}
1090
  {...moduleTileEvents(application.id)}
1091
- onClick={(event) => { moduleTileEvents(application.id).onClick?.(event); openTileLink(event, "app", application.id); }}
 
 
 
 
 
 
 
 
 
 
 
1092
  >
1093
  <span className="home-tile-chip home-app-glyph" aria-hidden="true">
1094
  <ApplicationIcon />
@@ -1167,7 +1165,10 @@ export function HomeSurface({
1167
  <button
1168
  type="button"
1169
  className="home-tile home-tile-auto"
1170
- onClick={() => { void openExistingItem({ kind: "automation", id: a.id }, () => onOpenAutomation(a.id)); }}
 
 
 
1171
  >
1172
  {/* The home glyph class keeps the outline legible on the tile's tinted chip. */}
1173
  <span className="home-tile-chip shell-db-chip home-app-glyph" aria-hidden="true">
@@ -1224,8 +1225,10 @@ export function HomeSurface({
1224
  />
1225
  ) : undefined
1226
  }
1227
- onOpen={() => { void openExistingItem({ kind: "view", id: row.id, database: row.database }, () => {
1228
- onOpenView(row.database, row.id);
 
 
1229
  const href = homeFolderHref(window.location.hash, folderPlacement[row.database]);
1230
  if (href !== window.location.hash) {
1231
  window.history.replaceState(window.history.state, "", href);
@@ -1497,7 +1500,7 @@ export default function HomePage(props: HomeProps) {
1497
  setAgentBusy(false);
1498
  }
1499
  };
1500
- const [applications, setApplications] = useState<ApplicationTile[]>([]);
1501
  const [applicationsKnown, setApplicationsKnown] = useState(false);
1502
  const [applicationsError, setApplicationsError] = useState("");
1503
  const [applicationBusy, setApplicationBusy] = useState<Set<string>>(() => new Set());
@@ -1535,18 +1538,17 @@ export default function HomePage(props: HomeProps) {
1535
  const controller = new AbortController();
1536
  const requestEpoch = ++applicationRequestEpoch.current;
1537
  setApplicationsError("");
1538
- void fetch(`${API_V1}/applications`, {
1539
- credentials: CREDENTIALS,
1540
- signal: controller.signal,
1541
- })
1542
- .then(async (response) => {
1543
- if (!response.ok) throw new Error("application_list_failed");
1544
- return response.json();
1545
- })
1546
- .then((body) => {
1547
  if (!controller.signal.aborted && requestEpoch === applicationRequestEpoch.current) {
1548
- if (!Array.isArray(body?.applications)) throw new Error("application_list_invalid");
1549
- setApplications(body.applications.filter((row: ApplicationTile) => !deletedApplications.current.has(row.id)));
1550
  setApplicationsKnown(true);
1551
  }
1552
  })
@@ -1617,6 +1619,11 @@ export default function HomePage(props: HomeProps) {
1617
  itemDeleted({ kind: "app", id: application.id });
1618
  window.dispatchEvent(new CustomEvent("aios:applications-changed", { detail: { deletedId: application.id } }));
1619
  };
 
 
 
 
 
1620
  return (
1621
  <>
1622
  <HomeSurface
 
39
  import { AGENTS_MODULE_LABEL } from "../inbox/inboxModel";
40
  // AgentIcon carries the rail's shell-nav-icon class, which supplies its stroke-only paint.
41
  import { AgentIcon } from "../shell/icons";
42
+ import { agentAddressHash, commitRoute, dataAddressHash, readDataAddress, MAX_NAV_FOLDERS } from "../shell/nav";
43
  import type { DatabaseEntry, NavFolder, 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
 
195
  );
196
  }
197
 
198
+ export interface ApplicationTile {
199
  id: string;
200
  name: string;
201
  type: string;
202
  templateKind?: string;
203
+ deepLink?: string;
204
  compatibleDatabases?: string[];
205
+ openTarget?: { database?: string | null };
206
  starred?: boolean;
207
  capabilities?: { star?: boolean; delete?: boolean };
208
  }
209
 
210
+ const NO_FINANCE_APPLICATIONS: ApplicationTile[] = [];
211
+
212
  interface SheetTile {
213
  id: string;
214
  name: string;
 
338
  export interface HomeProps {
339
  /** Each gallery reuses Home's directory anatomy. */
340
  mode?: "home" | "app" | "data" | "sheet" | "agents";
341
+ /** Shell-selected registry cards; other galleries can omit them. */
342
+ financeApplications?: ApplicationTile[];
343
  /** Compatibility entry for a retired `#/starred` bookmark. */
344
  initialStarredOnly?: boolean;
345
  /**
 
598
  : suppliedModuleIndex;
599
  const indexKnown = moduleHome && moduleIndex !== null;
600
  const folderWritable = indexKnown && !moduleIndexBusy && !moduleIndexError;
 
 
 
601
  const [folderEdit, setFolderEdit] = useState<{ id: string | null; name: string } | null>(null);
602
  const [folderAnchor, setFolderAnchor] = useState<HTMLElement | null>(null);
603
  const [movePicker, setMovePicker] = useState(false);
 
613
  const levelApplications = mode === "app" ? appLevel.items : visibleApplications;
614
  const levelSheets = mode === "sheet" ? sheetLevel.items : visibleSheets;
615
  const levelDatabases = mode === "data" ? dataLevel.items : visibleDatabases;
 
 
 
 
 
 
 
 
 
616
  useEffect(() => {
617
  setFolderAt(mode === "data" ? new URLSearchParams(window.location.hash.split("?")[1]).get("folder") : null);
618
  setFolderEdit(null);
 
619
  setMovePicker(false);
620
  setDraggedIds([]);
621
  selection.clear();
 
671
  if (!link || link.target === "_blank") return;
672
  event.preventDefault();
673
  const href = link.getAttribute("href") ?? "";
674
+ commitRoute(href);
675
+ void openExistingItem({ kind, id }, () => {}, { voice });
 
 
676
  };
677
  const folderDropEvents = (target: string | null) => ({
678
  onDragOver: (event: DragEvent<HTMLElement>) => {
 
687
  setDraggedIds([]);
688
  },
689
  });
690
+ // Every module paints the same card immediately; index readiness only controls whether it can act.
691
+ const newFolderControl = (
 
 
 
692
  <QuickCard
693
  icon={<span className="home-card-icon" aria-hidden="true"><FolderMark size={16} /></span>}
694
  title="New folder"
695
  detail="Group items in this module into folders."
696
+ holdDetail={!indexKnown && !moduleIndexError ? "Unavailable while folders load." : undefined}
697
  disabled={mode === "data" && folders.length >= MAX_NAV_FOLDERS}
698
  buttonTitle={mode === "data" && folders.length >= MAX_NAV_FOLDERS ? "Folder limit reached" : undefined}
699
+ holdReason={!folderWritable
700
  ? moduleIndexError
701
  ? "Folders could not load. Use Reload folders to try again."
702
+ : "Folders are not ready yet."
703
  : undefined}
704
+ busy={!indexKnown && !moduleIndexError}
705
  onClick={(event) => {
706
+ if (!folderWritable) return;
707
  setFolderAnchor(event.currentTarget);
708
+ setFolderEdit({ id: null, name: "" });
 
709
  }}
710
  />
711
+ );
712
  const renderModuleFolders = () => (
713
  <section className="home-section" aria-label="Module folders">
714
  {moduleIndexError ? <p className="home-app-note" role="alert">{moduleIndexError}
 
929
  pill in the header while Home offered a card, and BOTH OPEN THE SAME DOOR: `Shell.tsx`
930
  hands `openApplicationWizard` to each of them and says so in its own comment. One door
931
  wearing two looks is the defect, so App now wears Home's card: same component, same
932
+ glyph, same tokens. All three cards render together while folder readiness controls
933
+ whether New folder can act. */}
934
  <QuickCard
935
  icon={<TemplateIcon />}
936
  title="Create new"
937
+ detail="Create an app from a template."
938
  onClick={onTemplates}
939
  />
940
  <QuickCard icon={<TemplateIcon />} title="Templates"
 
1062
  const database = application.openTarget?.database
1063
  ?? application.compatibleDatabases?.[0]
1064
  ?? "";
1065
+ const kind = application.templateKind === "finance" ? "Finance" : application.templateKind === "catalog"
1066
  ? "Catalog"
1067
  : application.templateKind === "route"
1068
  ? "Routing"
 
1071
  <div className={"st-tilewrap home-app-tile" + (application.capabilities?.delete === true ? " can-delete" : "")} key={application.id}>
1072
  <a
1073
  className={"home-tile" + (mode === "app" ? " cg-view-row" + (selection.isSelected(application.id) ? " is-railsel" : "") : "")}
1074
+ href={application.deepLink ? `#${application.deepLink}` : database
1075
  ? appPathHash({ database, application: application.id })
1076
  : "#/app"}
1077
  {...moduleTileEvents(application.id)}
1078
+ onClick={(event) => {
1079
+ moduleTileEvents(application.id).onClick?.(event);
1080
+ // Registry projections are absent from /applications. An existence check
1081
+ // there would falsely mark a seeded Finance card as deleted.
1082
+ if (application.deepLink) {
1083
+ if (event.defaultPrevented || event.shiftKey || event.ctrlKey || event.metaKey || event.altKey) return;
1084
+ event.preventDefault();
1085
+ commitRoute(`#${application.deepLink}`);
1086
+ return;
1087
+ }
1088
+ openTileLink(event, "app", application.id);
1089
+ }}
1090
  >
1091
  <span className="home-tile-chip home-app-glyph" aria-hidden="true">
1092
  <ApplicationIcon />
 
1165
  <button
1166
  type="button"
1167
  className="home-tile home-tile-auto"
1168
+ onClick={() => {
1169
+ onOpenAutomation(a.id);
1170
+ void openExistingItem({ kind: "automation", id: a.id }, () => {});
1171
+ }}
1172
  >
1173
  {/* The home glyph class keeps the outline legible on the tile's tinted chip. */}
1174
  <span className="home-tile-chip shell-db-chip home-app-glyph" aria-hidden="true">
 
1225
  />
1226
  ) : undefined
1227
  }
1228
+ // S65-T09 / C3: `onOpenView` is the route, and it runs FIRST, before the
1229
+ // existence read. What stays inside the opener is the folder decoration, which
1230
+ // is a `replaceState` refinement of an address the user is already standing on.
1231
+ onOpen={() => { onOpenView(row.database, row.id); void openExistingItem({ kind: "view", id: row.id, database: row.database }, () => {
1232
  const href = homeFolderHref(window.location.hash, folderPlacement[row.database]);
1233
  if (href !== window.location.hash) {
1234
  window.history.replaceState(window.history.state, "", href);
 
1500
  setAgentBusy(false);
1501
  }
1502
  };
1503
+ const [tenantApplications, setApplications] = useState<ApplicationTile[]>([]);
1504
  const [applicationsKnown, setApplicationsKnown] = useState(false);
1505
  const [applicationsError, setApplicationsError] = useState("");
1506
  const [applicationBusy, setApplicationBusy] = useState<Set<string>>(() => new Set());
 
1538
  const controller = new AbortController();
1539
  const requestEpoch = ++applicationRequestEpoch.current;
1540
  setApplicationsError("");
1541
+ const readApplications = async (response: Response): Promise<ApplicationTile[]> => {
1542
+ if (!response.ok) throw new Error("application_list_failed");
1543
+ const body = await response.json();
1544
+ if (!Array.isArray(body?.applications)) throw new Error("application_list_invalid");
1545
+ return body.applications;
1546
+ };
1547
+ const options = { credentials: CREDENTIALS, signal: controller.signal };
1548
+ void fetch(`${API_V1}/applications`, options).then(readApplications)
1549
+ .then((rows) => {
1550
  if (!controller.signal.aborted && requestEpoch === applicationRequestEpoch.current) {
1551
+ setApplications(rows.filter((row) => !deletedApplications.current.has(row.id)));
 
1552
  setApplicationsKnown(true);
1553
  }
1554
  })
 
1619
  itemDeleted({ kind: "app", id: application.id });
1620
  window.dispatchEvent(new CustomEvent("aios:applications-changed", { detail: { deletedId: application.id } }));
1621
  };
1622
+ const financeApplications = props.mode === "app"
1623
+ ? props.financeApplications ?? NO_FINANCE_APPLICATIONS : NO_FINANCE_APPLICATIONS;
1624
+ const merged = new Map([...tenantApplications, ...financeApplications].map((row) => [row.id, row]));
1625
+ const applications = [...merged.values()].filter((row) => !deletedApplications.current.has(row.id)
1626
+ && (props.mode === "app" || row.templateKind !== "finance"));
1627
  return (
1628
  <>
1629
  <HomeSurface
web/src/home/TemplatePicker.tsx CHANGED
@@ -10,6 +10,10 @@ const connectorLabels: Record<string, string> = { odoo: "Odoo", amazon_sp: "Amaz
10
  const connectorLabel = (key: string) => connectorLabels[key]
11
  ?? key.replaceAll("_", " ").replace(/^./, (letter) => letter.toUpperCase());
12
 
 
 
 
 
13
  /** One catalog and one overlay for module cards, the rail and the old gallery doors. */
14
  export default function TemplatePicker({ initialModule = "sheet", onClose, onCreated, onApplication }: {
15
  initialModule?: TemplateModule;
@@ -64,7 +68,7 @@ export default function TemplatePicker({ initialModule = "sheet", onClose, onCre
64
 
65
  const create = async (template: PickerTemplate) => {
66
  if (!template.creatable || applying.current) return;
67
- if (module === "app") {
68
  if (onApplication) onApplication(template.key);
69
  else {
70
  onClose();
@@ -79,7 +83,10 @@ export default function TemplatePicker({ initialModule = "sheet", onClose, onCre
79
  applying.current = false;
80
  if (!alive.current) return;
81
  setBusy("");
82
- if (result.ok) onCreated(result.value.address);
 
 
 
83
  else { setError(result.message); setReload((value) => value + 1); }
84
  };
85
 
@@ -126,12 +133,12 @@ export default function TemplatePicker({ initialModule = "sheet", onClose, onCre
126
  return <li className="home-tpl-row" key={template.key}>
127
  <span className="home-tpl-text">
128
  <span className="home-tpl-name" title={template.description}>{template.name}</span>
129
- <span className="home-tpl-desc">{template.requires.length
130
  ? template.requires.map((row) => row.label).join(", ") : "No connector required"}</span>
131
  </span>
132
  {template.creatable ? <button type="button" className="login-submit home-tpl-apply"
133
  disabled={!!busy} onClick={() => void create(template)}>
134
- {busy === template.key ? "Creating…" : module === "app" ? "Continue" : "Create"}
135
  </button> : action ? <button type="button" className="lp-dialog-btn lp-dialog-btn-quiet"
136
  disabled={!!busy} onClick={() => onCreated("#/" + CONNECTORS_ROUTE)}>
137
  {actionLabel}
 
10
  const connectorLabel = (key: string) => connectorLabels[key]
11
  ?? key.replaceAll("_", " ").replace(/^./, (letter) => letter.toUpperCase());
12
 
13
+ // Additive server marker; the shared picker wire type remains owned by Sheet.
14
+ const usesApplicationWizard = (template: PickerTemplate) =>
15
+ (template as PickerTemplate & { creationMode?: "wizard" | "post" }).creationMode !== "post";
16
+
17
  /** One catalog and one overlay for module cards, the rail and the old gallery doors. */
18
  export default function TemplatePicker({ initialModule = "sheet", onClose, onCreated, onApplication }: {
19
  initialModule?: TemplateModule;
 
68
 
69
  const create = async (template: PickerTemplate) => {
70
  if (!template.creatable || applying.current) return;
71
+ if (module === "app" && usesApplicationWizard(template)) {
72
  if (onApplication) onApplication(template.key);
73
  else {
74
  onClose();
 
83
  applying.current = false;
84
  if (!alive.current) return;
85
  setBusy("");
86
+ if (result.ok) {
87
+ if (module === "app") window.dispatchEvent(new Event("aios:applications-changed"));
88
+ onCreated(result.value.address);
89
+ }
90
  else { setError(result.message); setReload((value) => value + 1); }
91
  };
92
 
 
133
  return <li className="home-tpl-row" key={template.key}>
134
  <span className="home-tpl-text">
135
  <span className="home-tpl-name" title={template.description}>{template.name}</span>
136
+ <span className="home-tpl-desc">{module === "app" ? template.description : template.requires.length
137
  ? template.requires.map((row) => row.label).join(", ") : "No connector required"}</span>
138
  </span>
139
  {template.creatable ? <button type="button" className="login-submit home-tpl-apply"
140
  disabled={!!busy} onClick={() => void create(template)}>
141
+ {busy === template.key ? "Creating…" : module === "app" && usesApplicationWizard(template) ? "Continue" : "Create"}
142
  </button> : action ? <button type="button" className="lp-dialog-btn lp-dialog-btn-quiet"
143
  disabled={!!busy} onClick={() => onCreated("#/" + CONNECTORS_ROUTE)}>
144
  {actionLabel}
web/src/home/homeModel.ts CHANGED
@@ -266,9 +266,9 @@ export function parseModuleFolderIndex(raw: unknown): ModuleFolderIndex | null {
266
  return value;
267
  }
268
 
269
- // W63-T33 / C4: Finance is registry metadata projected into chrome, not a seventh hard-coded
270
- // application. Keep this selector React-free so the rail gate can prove permission omission,
271
- // ordering and de-duplication against the exact payload the shell consumes.
272
  export const FINANCE_NAV_GROUP = "finance";
273
 
274
  export type NavigationApplication = {
@@ -276,11 +276,11 @@ export type NavigationApplication = {
276
  name: string;
277
  deepLink?: string;
278
  compatibleDatabases?: string[];
279
- openTarget?: { database?: string };
280
  navPlacement?: { section?: string; order?: number };
281
  };
282
 
283
- export function financeNavigation(rows: readonly NavigationApplication[]): NavigationApplication[] {
284
  const seen = new Set<string>();
285
  return rows
286
  .filter((row) => row && typeof row.id === "string" && !!row.id
 
266
  return value;
267
  }
268
 
269
+ // Finance is registry metadata projected into App cards, not a seventh hard-coded application.
270
+ // Keep the selector React-free so the rail gate can prove permission omission, ordering and
271
+ // de-duplication against the exact payload the App home consumes.
272
  export const FINANCE_NAV_GROUP = "finance";
273
 
274
  export type NavigationApplication = {
 
276
  name: string;
277
  deepLink?: string;
278
  compatibleDatabases?: string[];
279
+ openTarget?: { database?: string | null };
280
  navPlacement?: { section?: string; order?: number };
281
  };
282
 
283
+ export function financeNavigation<T extends NavigationApplication>(rows: readonly T[]): T[] {
284
  const seen = new Set<string>();
285
  return rows
286
  .filter((row) => row && typeof row.id === "string" && !!row.id
web/src/main.tsx CHANGED
@@ -4,8 +4,10 @@ import './index.css'
4
  import App, { HOSTED } from './App.tsx'
5
  import { installStandaloneBridge } from './customer-grid/apiBridge'
6
  import { initializeHostBridge } from './customer-grid/hostBridge'
 
7
 
8
  initializeHostBridge()
 
9
 
10
  // EXIT wave 1 (X2): the standalone write path. THE ONE WIRING POINT — the embed
11
  // bundle runs this file too, and the branch below is the whole of the wave's
 
4
  import App, { HOSTED } from './App.tsx'
5
  import { installStandaloneBridge } from './customer-grid/apiBridge'
6
  import { initializeHostBridge } from './customer-grid/hostBridge'
7
+ import { installActivityLog } from './settings/activityLog'
8
 
9
  initializeHostBridge()
10
+ installActivityLog()
11
 
12
  // EXIT wave 1 (X2): the standalone write path. THE ONE WIRING POINT — the embed
13
  // bundle runs this file too, and the branch below is the whole of the wave's
web/src/settings/ActivityLogPage.tsx ADDED
@@ -0,0 +1,231 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { useEffect, useId, useState } from "react";
2
+ import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT } from "../apiContract";
3
+ import { isAdmin } from "../shell/session";
4
+ import type { SessionUser } from "../shell/session";
5
+ import type { ActivityEvent, ActivityTarget, MovementSample } from "./activityLog";
6
+ import "./activityLog.css";
7
+
8
+ interface Limits {
9
+ retentionDays: number;
10
+ maxSessions: number;
11
+ maxEventsPerSession: number;
12
+ maxMovementSamples: number;
13
+ movementWindowSeconds: number;
14
+ pageSize: number;
15
+ }
16
+ interface SessionRow {
17
+ sessionId: string;
18
+ startedAt: number;
19
+ endedAt: number;
20
+ route: string;
21
+ events: number;
22
+ errors: number;
23
+ dropped: number;
24
+ prunedEvents: number;
25
+ }
26
+ interface SessionList { sessions: SessionRow[]; limits: Limits }
27
+ interface Timeline {
28
+ sessionId: string;
29
+ events: ActivityEvent[];
30
+ total: number;
31
+ offset: number;
32
+ limit: number;
33
+ dropped: number;
34
+ prunedEvents: number;
35
+ limits: Limits;
36
+ }
37
+ type ApiResult<T> = { ok: true; data: T } | { ok: false; message: string };
38
+
39
+ async function call<T>(path: string, signal: AbortSignal): Promise<ApiResult<T>> {
40
+ try {
41
+ const response = await fetch(`${API_V1}${path}`, { credentials: CREDENTIALS, signal });
42
+ if (response.status === 401) window.dispatchEvent(new CustomEvent(UNAUTHORIZED_EVENT));
43
+ if (!response.ok) return { ok: false, message: response.status === 403
44
+ ? "You do not have access to this activity."
45
+ : response.status === 404 ? "This session is no longer available." : "Activity could not be loaded." };
46
+ return { ok: true, data: await response.json() as T };
47
+ } catch { return { ok: false, message: "The server could not be reached." }; }
48
+ }
49
+
50
+ const number = (value: number) => value.toLocaleString();
51
+ const clock = (ts: number) => new Date(ts).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", second: "2-digit" });
52
+ const stamp = (ts: number) => new Date(ts).toLocaleString([], { month: "short", day: "numeric", hour: "2-digit", minute: "2-digit" });
53
+ const duration = (ms: number) => ms < 60_000 ? `${number(Math.round(ms / 1000))} s` : `${number(Math.floor(ms / 60_000))} min ${Math.floor(ms / 1000) % 60} s`;
54
+ const elapsed = (ms?: number) => `${number(ms ?? 0)} ms`;
55
+
56
+ function targetName(target?: ActivityTarget): string {
57
+ if (!target) return "Element";
58
+ const label = target["aria-label"];
59
+ if (label) return `${target.tagName}: ${label}`;
60
+ if (target.id) return `${target.tagName}#${target.id}`;
61
+ if (target.data?.["data-section"] && target.data["data-section"] !== "present") return `${target.tagName}: ${target.data["data-section"]}`;
62
+ if (target.role) return `${target.tagName} (${target.role})`;
63
+ if (target.className) return `${target.tagName}.${target.className.split(" ").join(".")}`;
64
+ return target.tagName;
65
+ }
66
+
67
+ function movementDetail(sample: MovementSample): string {
68
+ if (sample.kind === "keypress") return sample.key ?? "Key";
69
+ if (sample.kind === "pointer" || sample.kind === "scroll") return `${number(sample.x ?? 0)}, ${number(sample.y ?? 0)}`;
70
+ return "";
71
+ }
72
+
73
+ function Skeleton() {
74
+ return <div className="activity-loading" role="status" aria-label="Loading activity" aria-busy="true">
75
+ {[0, 1, 2, 3].map(row => <div key={row} className="activity-skeleton" aria-hidden="true"><span /><span /><span /></div>)}
76
+ </div>;
77
+ }
78
+
79
+ function ErrorRow({ event, limits }: { event: ActivityEvent; limits: Limits }) {
80
+ const [expanded, setExpanded] = useState(false);
81
+ const [samplePage, setSamplePage] = useState(0);
82
+ const regionId = useId();
83
+ const buttonId = useId();
84
+ const samples = event.movement ?? [];
85
+ const sampleSize = 50;
86
+ return <li className="activity-event activity-event-error">
87
+ <button type="button" id={buttonId} className="activity-button activity-error-toggle"
88
+ aria-expanded={expanded} aria-controls={regionId} onClick={() => setExpanded(open => !open)}>
89
+ <time className="activity-number" dateTime={new Date(event.ts).toISOString()}>{clock(event.ts)}</time>
90
+ <span className="activity-event-copy"><span className="activity-kind">Error</span><span title="Dynamic error text is omitted to keep cell values private.">{event.name}: {event.message}</span>
91
+ {event.source ? <span className="activity-source">{event.source}{event.line ? `:${event.line}` : ""}</span> : null}</span>
92
+ <svg className={"activity-chevron" + (expanded ? " is-open" : "")} viewBox="0 0 16 16" aria-hidden="true"><path d="m6 3 5 5-5 5" /></svg>
93
+ </button>
94
+ {expanded ? <div id={regionId} role="region" aria-labelledby={buttonId} className="activity-trail">
95
+ <h2 className="set-h4">Before the error</h2>
96
+ <p className="set-help">Up to {number(limits.movementWindowSeconds)} seconds and {number(limits.maxMovementSamples)} movement samples.</p>
97
+ {event.movementDropped ? <p className="set-notice">{number(event.movementDropped)} samples were omitted by the capture limits.</p> : null}
98
+ {samples.length === 0 ? <p className="set-help">No movement was captured before this error.</p> : <>
99
+ <ol className="activity-movement">
100
+ {samples.slice(samplePage * sampleSize, (samplePage + 1) * sampleSize).map((sample, index) => <li key={`${sample.ts}-${index}`}>
101
+ <span className="activity-number">{Math.max(0, (event.ts - sample.ts) / 1000).toFixed(1)} s before</span>
102
+ <span className="activity-sample-kind">{sample.kind}</span>
103
+ <span className="activity-target" title={sample.target.path?.join(" > ")}>{targetName(sample.target)}</span>
104
+ <span className="activity-number">{movementDetail(sample)}</span>
105
+ </li>)}
106
+ </ol>
107
+ {samples.length > sampleSize ? <div className="activity-toolbar">
108
+ <span className="set-help">Samples {number(samplePage * sampleSize + 1)} to {number(Math.min((samplePage + 1) * sampleSize, samples.length))} of {number(samples.length)}</span>
109
+ <button type="button" className="activity-button activity-control" disabled={samplePage === 0} onClick={() => setSamplePage(page => page - 1)}>Earlier samples</button>
110
+ <button type="button" className="activity-button activity-control" disabled={(samplePage + 1) * sampleSize >= samples.length} onClick={() => setSamplePage(page => page + 1)}>Later samples</button>
111
+ </div> : null}
112
+ </>}
113
+ </div> : null}
114
+ </li>;
115
+ }
116
+
117
+ function EventRow({ event, limits }: { event: ActivityEvent; limits: Limits }) {
118
+ if (event.kind === "error") return <ErrorRow event={event} limits={limits} />;
119
+ return <li className="activity-event activity-action">
120
+ <time className="activity-number" dateTime={new Date(event.ts).toISOString()}>{clock(event.ts)}</time>
121
+ <span className="activity-event-copy">
122
+ <span className="activity-kind">{event.kind === "api" ? "Request" : event.kind === "route" ? "Route" : "Click"}</span>
123
+ {event.kind === "route" ? <span>{event.from || "Start"} to {event.to}</span> : null}
124
+ {event.kind === "click" ? <span title={event.target?.path?.join(" > ")}>{targetName(event.target)}</span> : null}
125
+ {event.kind === "api" ? <span>{event.method?.toLowerCase()} {event.url}</span> : null}
126
+ </span>
127
+ <span className="activity-number activity-metrics">
128
+ {event.kind === "api" ? <span>{event.status === 0 ? "Network failure" : `Status ${event.status}`}</span> : null}
129
+ {event.kind !== "click" ? <span>{elapsed(event.ms)}</span> : null}
130
+ </span>
131
+ </li>;
132
+ }
133
+
134
+ function ActivityPane({ user }: { user: SessionUser }) {
135
+ const admin = isAdmin(user);
136
+ const [selectedUser, setSelectedUser] = useState(user.username);
137
+ const owner = admin ? selectedUser : user.username;
138
+ const [users, setUsers] = useState<string[]>([user.username]);
139
+ const [usersError, setUsersError] = useState("");
140
+ const [list, setList] = useState<SessionList | null>(null);
141
+ const [selected, setSelected] = useState<SessionRow | null>(null);
142
+ const [timeline, setTimeline] = useState<Timeline | null>(null);
143
+ const [offset, setOffset] = useState(0);
144
+ const [revision, setRevision] = useState(0);
145
+ const [loading, setLoading] = useState(true);
146
+ const [error, setError] = useState("");
147
+
148
+ useEffect(() => {
149
+ if (!admin) return;
150
+ const controller = new AbortController();
151
+ void call<{ users: string[] }>("/activity/users", controller.signal).then(result => {
152
+ if (controller.signal.aborted) return;
153
+ setUsersError(result.ok ? "" : result.message);
154
+ if (result.ok) setUsers(Array.from(new Set([user.username, ...result.data.users])));
155
+ });
156
+ return () => controller.abort();
157
+ }, [admin, user.username, revision]);
158
+
159
+ useEffect(() => {
160
+ const controller = new AbortController();
161
+ setLoading(true);
162
+ setError("");
163
+ const query = admin ? `user=${encodeURIComponent(owner)}&` : "";
164
+ const path = selected
165
+ ? `/activity/sessions/${encodeURIComponent(selected.sessionId)}?${query}limit=100&offset=${offset}`
166
+ : `/activity/sessions?${query}`;
167
+ void call<SessionList | Timeline>(path, controller.signal).then(result => {
168
+ if (controller.signal.aborted) return;
169
+ setLoading(false);
170
+ if (!result.ok) { setError(result.message); return; }
171
+ if (selected) setTimeline(result.data as Timeline);
172
+ else setList(result.data as SessionList);
173
+ });
174
+ return () => controller.abort();
175
+ }, [admin, owner, selected, offset, revision]);
176
+
177
+ const limits = selected ? timeline?.limits ?? list?.limits : list?.limits;
178
+ const refresh = () => { setLoading(true); setError(""); setRevision(value => value + 1); };
179
+ function open(row: SessionRow | null) {
180
+ setSelected(row); setTimeline(null); setOffset(0); setLoading(true); setError("");
181
+ }
182
+
183
+ return <div className="set-pane activity-pane">
184
+ <h1 className="set-h">Activity log</h1>
185
+ <p className="set-help">Actions by session, with movement saved only before errors.</p>
186
+ <div className="activity-toolbar">
187
+ {admin ? <label className="activity-user"><span className="set-label">User</span>
188
+ <select className="pg-select" value={owner} onChange={event => { setSelectedUser(event.target.value); setList(null); open(null); }}>
189
+ {users.map(username => <option key={username} value={username}>{username}</option>)}
190
+ </select>
191
+ </label> : null}
192
+ {selected ? <button type="button" className="activity-button activity-control" onClick={() => open(null)}>Sessions</button> : null}
193
+ <button type="button" className="activity-button activity-control" onClick={refresh} disabled={loading}>Refresh</button>
194
+ </div>
195
+ {usersError ? <p className="set-error" role="alert">{usersError}</p> : null}
196
+ {limits ? <p className="set-help activity-retention">Last {number(limits.retentionDays)} days, up to {number(limits.maxSessions)} sessions per workspace and {number(limits.maxEventsPerSession)} events per session.</p> : null}
197
+ {error ? <div className="activity-empty"><p className="set-error" role="alert">{error}</p><button type="button" className="activity-button activity-control" onClick={refresh}>Retry</button></div>
198
+ : loading ? <Skeleton />
199
+ : selected && timeline ? <>
200
+ <div className="activity-heading"><h2 className="set-h4">Session timeline</h2><span className="set-help">{stamp(selected.startedAt)} · {selected.route}</span></div>
201
+ {timeline.prunedEvents > 0 ? <p className="set-notice">{number(timeline.prunedEvents)} older events were removed; the newest {number(timeline.limits.maxEventsPerSession)} are kept.</p> : null}
202
+ {timeline.dropped > 0 ? <p className="set-notice">{number(timeline.dropped)} events could not be captured or saved.</p> : null}
203
+ {timeline.events.length ? <ol className="activity-timeline" aria-label="Session actions">
204
+ {timeline.events.map((event, index) => <EventRow key={event.eventId ?? `${event.ts}-${index}`} event={event} limits={timeline.limits} />)}
205
+ </ol> : <p className="set-help">No events on this page.</p>}
206
+ <div className="activity-toolbar activity-pagination">
207
+ <span className="set-help">Events {number(timeline.total ? timeline.offset + 1 : 0)} to {number(Math.min(timeline.offset + timeline.events.length, timeline.total))} of {number(timeline.total)}; {number(timeline.limit)} per page.</span>
208
+ <button type="button" className="activity-button activity-control" disabled={offset === 0} onClick={() => { setLoading(true); setOffset(Math.max(0, offset - timeline.limit)); }}>Previous</button>
209
+ <button type="button" className="activity-button activity-control" disabled={offset + timeline.limit >= timeline.total} onClick={() => { setLoading(true); setOffset(offset + timeline.limit); }}>Next</button>
210
+ </div>
211
+ </> : list?.sessions.length ? <>
212
+ <h2 className="set-h4">Sessions</h2>
213
+ <ol className="activity-sessions" aria-label="Activity sessions">
214
+ {list.sessions.map(row => <li key={row.sessionId}>
215
+ <button type="button" className="activity-button activity-session" onClick={() => open(row)}>
216
+ <time className="activity-number" dateTime={new Date(row.startedAt).toISOString()}>{stamp(row.startedAt)}</time>
217
+ <span className="activity-session-route">{row.route}</span>
218
+ <span className="activity-number">{duration(row.endedAt - row.startedAt)}</span>
219
+ <span className="activity-number">{number(row.events)} events</span>
220
+ <span className={"activity-number" + (row.errors > 0 ? " activity-negative" : "")}>{number(row.errors)} errors</span>
221
+ </button>
222
+ </li>)}
223
+ </ol>
224
+ </> : <div className="activity-empty"><p className="set-help">No sessions yet.</p><button type="button" className="activity-button activity-control" onClick={refresh}>Refresh</button></div>}
225
+ </div>;
226
+ }
227
+
228
+ export default function ActivityLogPage({ user }: { user: SessionUser }) {
229
+ // Remount all fetched state if the signed-in identity changes without a reload.
230
+ return <ActivityPane key={`${user.tenant}:${user.username}:${user.role}`} user={user} />;
231
+ }
web/src/settings/ExternalAccessPane.tsx CHANGED
@@ -5,7 +5,7 @@
5
  // by create or rotate. All editable metadata is seeded again from the server response.
6
 
7
  import { useCallback, useEffect, useMemo, useRef, useState } from "react";
8
- import type { FormEvent, ReactNode } from "react";
9
  import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant } from "../apiContract";
10
 
11
  type Access = "read" | "readwrite";
@@ -22,8 +22,8 @@ const CLIENTS = [
22
  },
23
  {
24
  id: "chatgpt", label: "ChatGPT", connections: ["mcp"],
25
- steps: (mcpUrl: string) => `Workspace settings → Apps → Create\nAdd this MCP endpoint: ${mcpUrl}\nChoose OAuth, scan tools, and finish the Loopable sign-in.`,
26
- caveat: "Full MCP is available on Business and Enterprise/Edu; Pro is read/fetch only. Only admins and owners can publish apps.",
27
  copyLabel: "Copy ChatGPT setup", match: ["chatgpt", "chat gpt"],
28
  },
29
  {
@@ -36,8 +36,8 @@ const CLIENTS = [
36
  {
37
  id: "codex", label: "Codex", connections: ["mcp", "key"],
38
  steps: (mcpUrl: string) => `codex mcp add loopable --url ${mcpUrl}\ncodex mcp login loopable`,
39
- keySteps: (mcpUrl: string) => `In ~/.codex/config.toml, add or update this server:\n[mcp_servers.loopable]\nurl = "${mcpUrl}"\nhttp_headers = { Authorization = "Bearer <YOUR_API_KEY>" }\nReplace <YOUR_API_KEY> with your saved key locally, then restart Codex. Keep the key out of chat messages.`,
40
- caveat: "CLI, IDE, and desktop share config.toml. Project-scoped configuration loads only in trusted projects.",
41
  copyLabel: "Copy Codex commands", match: ["codex"],
42
  },
43
  {
@@ -103,7 +103,10 @@ interface KeyDraft {
103
  }
104
 
105
  type VerifyResult = { state: "ok" | "failed"; message: string };
106
- type StepState = "done" | "current" | "waiting";
 
 
 
107
 
108
  type ApiResult<T> =
109
  | { ok: true; data: T }
@@ -262,39 +265,19 @@ function connectionLabel(connection: ExternalConnection | undefined): string {
262
  return "Not connected";
263
  }
264
 
265
- function Step({ number, title, state, value, children }: {
266
- number: number; title: string; state: StepState; value?: string; children: ReactNode;
267
- }) {
268
- return (
269
- <li data-step={number} data-state={state} aria-current={state === "current" ? "step" : undefined}
270
- style={{ display: "grid", gridTemplateColumns: "32px minmax(0, 1fr)", gap: 12 }}>
271
- <span aria-hidden="true" style={{
272
- display: "grid", placeItems: "center", height: 32, borderRadius: "var(--lp-r-md)",
273
- background: state === "current" ? "var(--lp-blue-tint)" : "var(--lp-wash)",
274
- color: "var(--lp-ink)", fontWeight: 600,
275
- }}>{number}</span>
276
- <div>
277
- <div style={{ display: "flex", alignItems: "center", flexWrap: "wrap", gap: 8, minHeight: 32 }}>
278
- <h2 className="set-h4" style={{ margin: 0 }}>{title}</h2>
279
- <span className="set-help" style={{ margin: 0 }}>
280
- {state === "done" ? "Done" : state === "current" ? "Current" : "Waiting"}
281
- </span>
282
- </div>
283
- {value ? <p className="set-help" style={{ margin: "4px 0 8px" }}>{value}</p> : null}
284
- <div style={{ marginTop: 8 }}>{children}</div>
285
- </div>
286
- </li>
287
- );
288
- }
289
-
290
  export default function ExternalAccessPane() {
291
  const [clientId, setClientId] = useState<ClientId | null>(null);
292
  const [connection, setConnection] = useState<ConnectionKind | null>(null);
 
 
 
 
293
  const [readyToVerify, setReadyToVerify] = useState(false);
294
  const [verifyResult, setVerifyResult] = useState<VerifyResult | null>(null);
295
  const [verifySecret, setVerifySecret] = useState("");
296
  const verificationVersion = useRef(0);
297
  const [keys, setKeys] = useState<ExternalKeyMetadata[] | null>(null);
 
298
  const [connections, setConnections] = useState<ExternalConnection[]>([]);
299
  const [canMint, setCanMint] = useState<boolean | null>(null);
300
  const [label, setLabel] = useState("");
@@ -319,9 +302,23 @@ export default function ExternalAccessPane() {
319
 
320
  const client = CLIENTS.find((entry) => entry.id === clientId);
321
  const connectionKinds: readonly ConnectionKind[] = client?.connections ?? [];
322
- const setup = client && connection
323
- ? connection === "mcp" ? client.steps(mcpUrl) : "keySteps" in client ? client.keySteps(mcpUrl) : ""
324
- : "";
 
 
 
 
 
 
 
 
 
 
 
 
 
 
325
 
326
  function resetVerification() {
327
  verificationVersion.current += 1;
@@ -330,26 +327,39 @@ export default function ExternalAccessPane() {
330
 
331
  function chooseClient(id: ClientId) {
332
  const entry = CLIENTS.find((candidate) => candidate.id === id);
333
- setClientId(id);
334
- setConnection(entry?.connections.length === 1 ? entry.connections[0] : null);
335
- setReadyToVerify(false); resetVerification(); setCopied(""); setError(""); setNotice("");
 
 
 
336
  }
337
 
338
  function chooseConnection(kind: ConnectionKind) {
339
- setConnection(kind); setReadyToVerify(false); resetVerification(); setCopied(""); setError(""); setNotice("");
 
 
 
 
 
 
 
340
  }
341
 
342
  const load = useCallback(async () => {
 
343
  const result = await call<KeyListResponse>("/external/keys");
344
  if (!result.ok) {
345
- setKeys([]); setCanMint(null); setError(result.message); return;
346
  }
347
  if (!Array.isArray(result.data?.keys) || typeof result.data.can_mint !== "boolean") {
348
- setKeys([]); setCanMint(null); setError("The AI API returned an unreadable response."); return;
 
349
  }
350
  const parsed = result.data.keys.map(parseKey);
351
  if (parsed.some((row) => row === null)) {
352
- setKeys([]); setCanMint(null); setError("The AI API returned an unreadable response."); return;
 
353
  }
354
  setKeys(parsed as ExternalKeyMetadata[]);
355
  setCanMint(result.data.can_mint);
@@ -439,6 +449,7 @@ export default function ExternalAccessPane() {
439
  setKeys((current) => [key, ...(current ?? []).filter((row) => row.id !== key.id)]);
440
  setLabel(""); setAccess("read"); setDatabaseMode("all"); setSelectedDatabases([]); setExpiresAt("");
441
  setCopied(""); setRevealed({ key, secret: result.data.secret });
 
442
  }
443
 
444
  async function copy(value: string, name: string) {
@@ -487,6 +498,7 @@ export default function ExternalAccessPane() {
487
  setError("The API key was rotated, but its replacement secret could not be read."); void load(); return;
488
  }
489
  setKeys((current) => (current ?? []).map((row) => row.id === key.id ? replacement : row));
 
490
  setEditing(null); setEditDraft(null); setCopied("");
491
  setRevealed({ key: replacement, secret: result.data.secret });
492
  }
@@ -522,8 +534,8 @@ export default function ExternalAccessPane() {
522
  }
523
 
524
  async function verifyKey() {
525
- const secret = revealed?.secret ?? verifySecret.trim();
526
- if (!secret || !readyToVerify || connection !== "key") return;
527
  setBusy("verify:key"); setVerifyResult(null);
528
  const version = ++verificationVersion.current;
529
  const report = (state: VerifyResult["state"], message: string) => {
@@ -652,9 +664,51 @@ export default function ExternalAccessPane() {
652
  );
653
  }
654
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
655
  const revealCard = revealed ? (
656
  <section className="set-card">
657
- <h2 className="set-h4">Save this API key</h2>
658
  <p className="set-help">Copy it now. Loopable cannot show this secret again.</p>
659
  <div className="set-field"><label className="set-label" htmlFor="set-external-secret">API key</label>
660
  <input id="set-external-secret" className="set-input" type="text" value={revealed.secret}
@@ -670,194 +724,250 @@ export default function ExternalAccessPane() {
670
  ) : null;
671
 
672
  return (
673
- <div className="set-pane">
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
674
  <h1 className="set-h">AI API</h1>
675
- <p className="set-help set-pane-intro">
676
- Choose your AI client, follow its setup, then verify the connection.
677
- </p>
678
  {error ? <p className="set-error" role="alert">{error}</p> : null}
679
  {notice ? <p className="set-notice" role="status">{notice}</p> : null}
680
 
681
- <ol aria-label="Connect to Loopable" style={{ listStyle: "none", padding: 0, margin: "24px 0", display: "grid", gap: 24 }}>
682
- <Step number={1} title="Choose a client" state={client ? "done" : "current"} value={client?.label}>
683
- <div className="set-actions" style={{ marginTop: 0 }}>
 
 
 
 
 
 
 
 
 
 
 
 
684
  {CLIENTS.map((entry) => (
685
  <button key={entry.id} type="button" className="set-secondary" data-client={entry.id}
686
  aria-pressed={clientId === entry.id} disabled={busy !== ""}
687
- style={{ background: clientId === entry.id ? "var(--lp-blue-tint)" : "var(--lp-surface)" }}
688
  onClick={() => chooseClient(entry.id)}>{entry.label}</button>
689
  ))}
690
  </div>
691
- </Step>
692
 
693
- <Step number={2} title="Connection" state={!client ? "waiting" : connection ? "done" : "current"}
694
- value={connection ? connection === "mcp" ? "Loopable sign-in" : "API key" : undefined}>
695
- {!client ? <p className="set-help">Choose a client first.</p> : connectionKinds.length === 1 ? (
696
- <p className="set-help">{client.label} connects with {connection === "mcp" ? "your Loopable sign-in" : "an API key"}. There is nothing to choose here.</p>
697
- ) : (
698
- <>
699
- <p className="set-help">Use your Loopable sign-in, or an API key you manage. Both stay inside your current permissions.</p>
700
- <div className="set-actions" aria-label="AI API connection choices">
701
  {connectionKinds.includes("mcp") ? (
702
  <button type="button" className="set-secondary" data-connection="mcp"
703
- style={{ background: connection === "mcp" ? "var(--lp-blue-tint)" : "var(--lp-surface)" }}
704
  disabled={busy !== ""} aria-pressed={connection === "mcp"}
 
705
  onClick={() => chooseConnection("mcp")}>Connect an AI app</button>
706
  ) : null}
707
  {connectionKinds.includes("key") ? (
708
  <button type="button" className="set-secondary" data-connection="key"
709
- style={{ background: connection === "key" ? "var(--lp-blue-tint)" : "var(--lp-surface)" }}
710
  disabled={busy !== ""} aria-pressed={connection === "key"}
 
711
  onClick={() => chooseConnection("key")}>Create API key for code/SDK</button>
712
  ) : null}
713
  </div>
714
- </>
715
- )}
716
- </Step>
717
 
718
- <Step number={3} title="Connect" state={!connection ? "waiting" : readyToVerify ? "done" : "current"}
719
- value={readyToVerify ? `${client?.label} setup ready to check` : undefined}>
720
- {!client || !connection ? <p className="set-help">Choose the connection to see its setup.</p> : (
721
  <>
722
- {connection === "mcp" ? (
723
- <div className="set-field">
724
- <label className="set-label" htmlFor="external-mcp-url">MCP URL</label>
725
- <input id="external-mcp-url" className="set-input" value={mcpUrl} readOnly />
726
- <div className="set-actions">
727
- <button type="button" className="set-secondary" disabled={busy !== ""}
728
- onClick={() => void copy(mcpUrl, "mcp-url")}>
729
- {busy === "copy:mcp-url" ? "Copying…" : copied === "mcp-url" ? "Copied" : "Copy MCP URL"}
730
- </button>
731
- </div>
 
 
 
732
  </div>
733
- ) : (
734
- <>
735
- <p className="set-help" style={{ marginBottom: 12 }}>Use a saved API key or create one here, then add it to {client.label}.</p>
736
- {revealed ? revealCard : canMint ? (
737
- <form className="set-card" onSubmit={(event) => void create(event)}>
738
- <h2 className="set-h4">New API key</h2>
739
- <div className="set-field"><label className="set-label" htmlFor="set-external-label">Label</label>
740
- <input id="set-external-label" className="set-input" type="text" maxLength={80} value={label}
741
- autoComplete="off" placeholder="Reporting SDK" onChange={(event) => setLabel(event.currentTarget.value)} /></div>
742
- <div className="set-field"><label className="set-label" htmlFor="set-external-access">Access</label>
743
- <select id="set-external-access" className="pg-select" value={access}
744
- onChange={(event) => setAccess(event.currentTarget.value as Access)}>
745
- <option value="read">Read only</option><option value="readwrite">Read and write</option>
746
- </select></div>
747
- <div className="set-field"><label className="set-label" htmlFor="set-external-databases">Resources</label>
748
- <select id="set-external-databases" className="pg-select" value={databaseMode}
749
- onChange={(event) => setDatabaseMode(event.currentTarget.value as "all" | "subset")}>
750
- <option value="all">All databases</option><option value="subset">Selected databases</option>
751
- </select></div>
752
- {databaseMode === "subset" ? databaseChecks(selectedDatabases, setSelectedDatabases) : null}
753
- <div className="set-field"><label className="set-label" htmlFor="set-external-expiry">Expiry</label>
754
- <input id="set-external-expiry" className="set-input" type="datetime-local" value={expiresAt}
755
- onChange={(event) => setExpiresAt(event.currentTarget.value)} />
756
- <p className="set-help">Leave blank for no expiry.</p></div>
757
- <div className="set-actions"><button type="submit" className="set-primary" disabled={busy === "create"}>
758
- {busy === "create" ? "Creating…" : "Create API key"}</button></div>
759
- </form>
760
- ) : canMint === false ? (
761
- <p className="set-help set-pane-intro">Creating API keys requires the Analyst module. Ask an administrator to grant it.</p>
762
- ) : <p className="set-help">Loading API key settings…</p>}
763
- </>
764
- )}
765
-
766
- <div className="set-field">
767
- <label className="set-label" htmlFor="external-client-setup">{client.label} setup</label>
768
- <textarea id="external-client-setup" className="set-input" value={setup} readOnly
769
- rows={Math.min(12, setup.split("\n").length + 1)} />
770
- <p className="set-help">{client.caveat}</p>
771
- <div className="set-actions">
772
- <button type="button" className="set-secondary" disabled={busy !== ""}
773
- onClick={() => void copy(setup, `guide:${client.id}`)}>
774
- {busy === `copy:guide:${client.id}` ? "Copying…" : copied === `guide:${client.id}` ? "Copied" : client.copyLabel}
775
- </button>
776
  </div>
777
- </div>
 
 
 
 
 
 
 
778
 
779
- <section className="set-card">
780
- <h2 className="set-h4">SDK skill</h2>
781
- <p className="set-help">Download or copy skill.md. It describes the API but contains no API key or other secret.</p>
782
- <div className="set-actions">
783
- <button type="button" className="set-primary" disabled={canMint !== true || busy === "skill-download"}
784
- onClick={() => void downloadSkill()}>{busy === "skill-download" ? "Preparing…" : "Download skill.md"}</button>
785
- <button type="button" className="set-secondary" disabled={canMint !== true || busy === "skill-copy"}
786
- onClick={() => void copySkill()}>{busy === "skill-copy" ? "Copying…" : copied === "skill" ? "Copied" : "Copy skill.md"}</button>
787
- </div>
788
- </section>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
789
 
790
- {!readyToVerify ? (
791
- <div className="set-actions">
792
- <button type="button" className="set-primary" disabled={busy !== ""}
793
- onClick={() => setReadyToVerify(true)}>Continue to verify</button>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
794
  </div>
795
  ) : null}
 
796
  </>
797
- )}
798
- </Step>
799
 
800
- <Step number={4} title="Verify" state={!readyToVerify ? "waiting" : verifyResult?.state === "ok" ? "done" : "current"}
801
- value={verifyResult?.state === "ok" ? connection === "mcp" ? "Sign-in verified" : "API key verified" : undefined}>
802
- {!readyToVerify || !client ? <p className="set-help">Finish setup, then continue to verify.</p> : (
803
- <>
804
- {connection === "key" ? (
805
- <>
806
- {revealed ? <p className="set-help">Verify the API key just created or rotated.</p> : (
807
- <div className="set-field">
808
- <label className="set-label" htmlFor="external-verify-key">Saved API key</label>
809
- <input id="external-verify-key" className="set-input" type="password" value={verifySecret}
810
- autoComplete="off" spellCheck={false} disabled={busy !== ""}
811
- aria-describedby="external-verify-key-help"
812
- onChange={(event) => { setVerifySecret(event.currentTarget.value); setVerifyResult(null); }} />
813
- <p id="external-verify-key-help" className="set-help">Loopable cannot show an existing key again. Rotating issues a new one. This field clears after the check.</p>
814
- </div>
815
- )}
816
- <p className="set-help">This checks the key with Loopable. Use the starter prompt in {client.label} to check its setup.</p>
817
- <div className="set-actions">
818
- <button type="button" className="set-primary" data-verify="key"
819
- disabled={busy !== "" || !(revealed?.secret || verifySecret.trim())}
820
- onClick={() => void verifyKey()}>{busy === "verify:key" ? "Verifying…" : "Verify API key"}</button>
821
  </div>
822
- </>
823
- ) : (
824
- <>
825
- <p className="set-help">Check for a completed {client.label} sign-in with Loopable.</p>
826
- <div className="set-actions">
827
- <button type="button" className="set-primary" data-verify="mcp" disabled={busy !== ""}
828
- onClick={() => void verifyMcp()}>{busy === "verify:mcp" ? "Checking…" : "Verify sign-in"}</button>
829
- </div>
830
- </>
831
- )}
832
- {verifyResult ? (
833
- <p className="set-help" role="status" data-verify-result data-verify-state={verifyResult.state}
834
- style={{ padding: 12, marginTop: 12, borderRadius: "var(--lp-r-md)",
835
- color: verifyResult.state === "ok" ? "var(--lp-green-deep)" : "var(--lp-red-deep)",
836
- background: verifyResult.state === "ok" ? "var(--lp-green-tint)" : "var(--lp-red-tint)" }}>
837
- {verifyResult.message}
838
- </p>
839
- ) : null}
840
- {connection === "mcp" ? connections.map((connection) => (
841
- <div key={connection.id} style={{ marginTop: 16 }}>
842
- <div className="pg-drill-row"><span className="pg-drill-key">{connection.label || "Unnamed AI app"}</span>
843
- <span className="pg-drill-val">{connectionLabel(connection)}</span></div>
844
- <div className="pg-drill-row"><span className="pg-drill-key">Last used</span>
845
- <span className="pg-drill-val">{when(connection.last_used)}</span></div>
846
- {connection.status === "connected" ? (
847
- <div className="set-actions">
848
- <button type="button" className="set-secondary kc-danger" disabled={busy !== ""}
849
- onClick={() => void disconnect(connection)}>
850
- {busy === `disconnect:${connection.client}` ? "Disconnecting…" : "Disconnect"}
851
- </button>
852
- </div>
853
- ) : null}
854
  </div>
855
- )) : null}
856
- </>
857
- )}
858
- </Step>
859
- </ol>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
860
 
 
 
 
 
 
 
 
 
 
 
 
 
861
  <section className="set-card">
862
  <h2 className="set-h4">Safe starter prompt</h2>
863
  <label className="set-label" htmlFor="external-starter-prompt">First message</label>
@@ -870,10 +980,48 @@ export default function ExternalAccessPane() {
870
  </button></div>
871
  </section>
872
 
873
- {connection !== "key" ? revealCard : null}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
874
 
875
  <div className="set-perm-sect"><h2 className="set-h4">API keys</h2></div>
876
- {keys === null ? <p className="set-help" role="status">Loading API keys…</p>
 
 
 
877
  : keys.length === 0 ? <p className="set-help">You have no API keys yet.</p> : (
878
  <div aria-label="Active API keys">
879
  {keys.map((key) => (
 
5
  // by create or rotate. All editable metadata is seeded again from the server response.
6
 
7
  import { useCallback, useEffect, useMemo, useRef, useState } from "react";
8
+ import type { FormEvent } from "react";
9
  import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant } from "../apiContract";
10
 
11
  type Access = "read" | "readwrite";
 
22
  },
23
  {
24
  id: "chatgpt", label: "ChatGPT", connections: ["mcp"],
25
+ steps: (mcpUrl: string) => `Settings → Security and login → turn on Developer mode\nOpen ChatGPT Plugins → plus button → enter a name and description.\nUnder Connection, enter the MCP server URL: ${mcpUrl}\nChoose OAuth, create the app, and finish the Loopable sign-in. Find the created app under Drafts in app settings.`,
26
+ caveat: "Available to Pro, Plus, Business, Enterprise, and Education accounts on the web. Write actions are allowed and confirmed per action.",
27
  copyLabel: "Copy ChatGPT setup", match: ["chatgpt", "chat gpt"],
28
  },
29
  {
 
36
  {
37
  id: "codex", label: "Codex", connections: ["mcp", "key"],
38
  steps: (mcpUrl: string) => `codex mcp add loopable --url ${mcpUrl}\ncodex mcp login loopable`,
39
+ keySteps: (mcpUrl: string) => `codex mcp add loopable --url ${mcpUrl} --bearer-token-env-var LOOPABLE_API_KEY\nSet LOOPABLE_API_KEY to your saved key locally before opening Codex. Keep the key out of chat messages.`,
40
+ caveat: "Set up once for Codex CLI, the ChatGPT desktop app and the IDE extension on the same host through one ~/.codex/config.toml.",
41
  copyLabel: "Copy Codex commands", match: ["codex"],
42
  },
43
  {
 
103
  }
104
 
105
  type VerifyResult = { state: "ok" | "failed"; message: string };
106
+ type SetupStep = "client" | "connection" | "setup" | "verify";
107
+ type KeyChoice = "create" | "saved";
108
+
109
+ const SETUP_STEPS: readonly SetupStep[] = ["client", "connection", "setup", "verify"];
110
 
111
  type ApiResult<T> =
112
  | { ok: true; data: T }
 
265
  return "Not connected";
266
  }
267
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
268
  export default function ExternalAccessPane() {
269
  const [clientId, setClientId] = useState<ClientId | null>(null);
270
  const [connection, setConnection] = useState<ConnectionKind | null>(null);
271
+ const [step, setStep] = useState<SetupStep>("client");
272
+ const stepHeading = useRef<HTMLHeadingElement>(null);
273
+ const [keyChoice, setKeyChoice] = useState<KeyChoice>("create");
274
+ const [selectedKeyId, setSelectedKeyId] = useState("");
275
  const [readyToVerify, setReadyToVerify] = useState(false);
276
  const [verifyResult, setVerifyResult] = useState<VerifyResult | null>(null);
277
  const [verifySecret, setVerifySecret] = useState("");
278
  const verificationVersion = useRef(0);
279
  const [keys, setKeys] = useState<ExternalKeyMetadata[] | null>(null);
280
+ const [keysError, setKeysError] = useState("");
281
  const [connections, setConnections] = useState<ExternalConnection[]>([]);
282
  const [canMint, setCanMint] = useState<boolean | null>(null);
283
  const [label, setLabel] = useState("");
 
302
 
303
  const client = CLIENTS.find((entry) => entry.id === clientId);
304
  const connectionKinds: readonly ConnectionKind[] = client?.connections ?? [];
305
+ const steps = SETUP_STEPS.filter((entry) => entry !== "connection" || connectionKinds.length !== 1);
306
+ const stepIndex = steps.indexOf(step);
307
+ const selectedKey = keys?.find((key) => key.id === selectedKeyId);
308
+ const keyIsActive = (key: ExternalKeyMetadata) => !key.revoked_at
309
+ && (!key.expires_at || Date.parse(key.expires_at) > Date.now());
310
+ const selectedKeyIsActive = selectedKey !== undefined && keyIsActive(selectedKey);
311
+ // A reveal from a different key must never silently replace the saved key the user chose.
312
+ const verificationReveal = revealed?.key.id === selectedKeyId ? revealed : null;
313
+
314
+ // Move focus to the new card so the flow is announced, but NOT on first paint: a
315
+ // programmatic focus with no prior interaction paints the focus ring unprompted, and a
316
+ // ring around a heading nobody touched reads as stray chrome (DESIGN.md section 4).
317
+ const steppedOnce = useRef(false);
318
+ useEffect(() => {
319
+ if (steppedOnce.current) stepHeading.current?.focus();
320
+ steppedOnce.current = true;
321
+ }, [step]);
322
 
323
  function resetVerification() {
324
  verificationVersion.current += 1;
 
327
 
328
  function chooseClient(id: ClientId) {
329
  const entry = CLIENTS.find((candidate) => candidate.id === id);
330
+ if (id !== clientId) {
331
+ setClientId(id);
332
+ setConnection(entry?.connections.length === 1 ? entry.connections[0] : null);
333
+ setReadyToVerify(false); resetVerification(); setCopied(""); setError(""); setNotice("");
334
+ }
335
+ setStep(entry?.connections.length === 1 ? "setup" : "connection");
336
  }
337
 
338
  function chooseConnection(kind: ConnectionKind) {
339
+ if (kind !== connection) {
340
+ setConnection(kind); setReadyToVerify(false); resetVerification(); setCopied(""); setError(""); setNotice("");
341
+ }
342
+ setStep("setup");
343
+ }
344
+
345
+ function chooseKey(id: string) {
346
+ setSelectedKeyId(id); resetVerification();
347
  }
348
 
349
  const load = useCallback(async () => {
350
+ setKeysError("");
351
  const result = await call<KeyListResponse>("/external/keys");
352
  if (!result.ok) {
353
+ setKeys(null); setCanMint(null); setKeysError(result.message); setError(result.message); return;
354
  }
355
  if (!Array.isArray(result.data?.keys) || typeof result.data.can_mint !== "boolean") {
356
+ setKeys(null); setCanMint(null); setKeysError("The AI API returned an unreadable response.");
357
+ setError("The AI API returned an unreadable response."); return;
358
  }
359
  const parsed = result.data.keys.map(parseKey);
360
  if (parsed.some((row) => row === null)) {
361
+ setKeys(null); setCanMint(null); setKeysError("The AI API returned an unreadable response.");
362
+ setError("The AI API returned an unreadable response."); return;
363
  }
364
  setKeys(parsed as ExternalKeyMetadata[]);
365
  setCanMint(result.data.can_mint);
 
449
  setKeys((current) => [key, ...(current ?? []).filter((row) => row.id !== key.id)]);
450
  setLabel(""); setAccess("read"); setDatabaseMode("all"); setSelectedDatabases([]); setExpiresAt("");
451
  setCopied(""); setRevealed({ key, secret: result.data.secret });
452
+ setSelectedKeyId(key.id); setKeyChoice("saved");
453
  }
454
 
455
  async function copy(value: string, name: string) {
 
498
  setError("The API key was rotated, but its replacement secret could not be read."); void load(); return;
499
  }
500
  setKeys((current) => (current ?? []).map((row) => row.id === key.id ? replacement : row));
501
+ setSelectedKeyId((current) => current === key.id ? replacement.id : current);
502
  setEditing(null); setEditDraft(null); setCopied("");
503
  setRevealed({ key: replacement, secret: result.data.secret });
504
  }
 
534
  }
535
 
536
  async function verifyKey() {
537
+ const secret = verificationReveal?.secret ?? verifySecret.trim();
538
+ if (!secret || !readyToVerify || connection !== "key" || !selectedKeyIsActive) return;
539
  setBusy("verify:key"); setVerifyResult(null);
540
  const version = ++verificationVersion.current;
541
  const report = (state: VerifyResult["state"], message: string) => {
 
664
  );
665
  }
666
 
667
+ function clientGuide(kind: ConnectionKind) {
668
+ if (!client) return null;
669
+ const setup = kind === "key" && "keySteps" in client ? client.keySteps(mcpUrl) : client.steps(mcpUrl);
670
+ // Preserve the catalog's commands, including Claude Code's shell continuations, while
671
+ // presenting the terminal command on one line. No credential is interpolated here.
672
+ const lines = setup.replace(/\\\n\s*/g, " ").split("\n");
673
+ const commandIndex = client.id === "claude-code" || client.id === "codex"
674
+ ? lines.findIndex((line) => /^(claude|codex) mcp add /.test(line)) : -1;
675
+ const command = commandIndex >= 0 ? lines[commandIndex] : null;
676
+ return (
677
+ <div className="external-guide">
678
+ {command ? (
679
+ <>
680
+ <label className="set-label" htmlFor="external-client-command">Terminal command</label>
681
+ <input id="external-client-command" className="set-input external-command" value={command}
682
+ readOnly spellCheck={false} onFocus={(event) => event.currentTarget.select()} />
683
+ {lines.filter((_, index) => index !== commandIndex).map((line, index) => (
684
+ <p className="set-help" key={index}>
685
+ {line === "codex mcp login loopable" ? <>Then run <code>{line}</code>.</> : line}
686
+ </p>
687
+ ))}
688
+ </>
689
+ ) : (
690
+ <pre className="external-instructions">{setup}</pre>
691
+ )}
692
+ <p className="set-help">{client.caveat}</p>
693
+ <div className="set-actions">
694
+ <button type="button" className="set-secondary" disabled={busy !== ""}
695
+ onClick={() => void copy(command ?? setup, `guide:${client.id}`)}>
696
+ {busy === `copy:guide:${client.id}` ? "Copying…" : copied === `guide:${client.id}` ? "Copied" : client.copyLabel}
697
+ </button>
698
+ {!command && kind === "mcp" ? (
699
+ <button type="button" className="set-secondary" disabled={busy !== ""}
700
+ onClick={() => void copy(mcpUrl, "mcp-url")}>
701
+ {busy === "copy:mcp-url" ? "Copying…" : copied === "mcp-url" ? "Copied" : "Copy MCP URL"}
702
+ </button>
703
+ ) : null}
704
+ </div>
705
+ </div>
706
+ );
707
+ }
708
+
709
  const revealCard = revealed ? (
710
  <section className="set-card">
711
+ <h2 className="set-h4">API key</h2>
712
  <p className="set-help">Copy it now. Loopable cannot show this secret again.</p>
713
  <div className="set-field"><label className="set-label" htmlFor="set-external-secret">API key</label>
714
  <input id="set-external-secret" className="set-input" type="text" value={revealed.secret}
 
724
  ) : null;
725
 
726
  return (
727
+ <div className="set-pane external-access-pane">
728
+ <style>{`
729
+ .external-access-pane .set-h, .external-access-pane .set-h4 { font-weight: 600; }
730
+ .external-access-pane .set-h { margin-bottom: 16px; }
731
+ .external-access-pane .set-card { padding: 16px; }
732
+ .external-access-pane .set-help { margin-top: 4px; }
733
+ .external-access-pane .set-field { margin-bottom: 16px; }
734
+ .external-access-pane .set-label { margin-bottom: 4px; }
735
+ .external-access-pane .set-check { gap: 8px; padding: 4px 0; }
736
+ .external-access-pane .set-actions { margin-top: 16px; align-items: center; }
737
+ .external-access-pane .set-input { padding: 0 8px; }
738
+ .external-access-pane textarea.set-input { height: auto; padding: 8px; }
739
+ .external-access-pane .pg-select { height: 32px; max-width: 100%; }
740
+ .external-access-pane .set-error, .external-access-pane .set-notice { padding: 8px 12px; }
741
+ .external-access-pane button { border: 0; background: transparent; font: inherit; color: inherit; }
742
+ .external-access-pane .set-primary, .external-access-pane .set-secondary {
743
+ height: 32px; padding: 0 12px; font-size: var(--lp-fs-xs); font-weight: 600;
744
+ border-radius: var(--lp-r-sm); cursor: pointer;
745
+ }
746
+ .external-access-pane .set-primary {
747
+ border: 1px solid var(--lp-primary); background: var(--lp-primary); color: var(--lp-surface);
748
+ }
749
+ .external-access-pane .set-secondary {
750
+ border: 1px solid var(--lp-line); background: var(--lp-surface); color: var(--lp-ink);
751
+ }
752
+ .external-access-pane .set-secondary[aria-pressed="true"] {
753
+ border-color: var(--lp-blue-deep); background: var(--lp-blue-tint); color: var(--lp-blue-deep);
754
+ }
755
+ .external-access-pane .set-secondary.kc-danger { color: var(--lp-red-deep); }
756
+ .external-access-pane button:disabled { opacity: 0.5; cursor: not-allowed; }
757
+ .external-progress { margin: 24px 0 16px; }
758
+ .external-progress-track {
759
+ height: 4px; margin-top: 8px; overflow: hidden;
760
+ background: var(--lp-line); border-radius: var(--lp-r-sm);
761
+ }
762
+ .external-progress-fill { height: 100%; background: var(--lp-blue-deep); }
763
+ .external-access-pane .external-step { margin-top: 0; background: var(--lp-surface); }
764
+ .external-step h2:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: 4px; }
765
+ .external-clients { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 8px; }
766
+ .external-access-pane .external-clients button { height: 48px; text-align: left; }
767
+ .external-instructions {
768
+ margin: 0; white-space: pre-wrap; overflow-wrap: anywhere; font: inherit;
769
+ font-size: var(--lp-fs-xs); color: var(--lp-ink); line-height: var(--lp-lh);
770
+ }
771
+ .external-access-pane .external-command { height: 40px; font-weight: 500; }
772
+ .external-guide { min-width: 0; }
773
+ .external-guide code { font: inherit; color: var(--lp-ink); }
774
+ .external-divider { border-top: 1px solid var(--lp-line); margin-top: 16px; padding-top: 16px; }
775
+ .external-footer { display: flex; gap: 8px; align-items: center; margin-top: 24px; }
776
+ .external-footer .set-primary { margin-left: auto; }
777
+ .external-key-loading { height: 32px; margin-top: 8px; background: var(--lp-wash); border-radius: var(--lp-r-sm); }
778
+ @media (hover: hover) and (pointer: fine) {
779
+ .external-access-pane .set-secondary:hover:enabled { border-color: var(--lp-blue-deep); }
780
+ .external-access-pane .set-primary:hover:enabled {
781
+ background: var(--lp-primary-hover); border-color: var(--lp-primary-hover);
782
+ }
783
+ }
784
+ @media (max-width: 480px) { .external-clients { grid-template-columns: minmax(0, 1fr); } }
785
+ `}</style>
786
  <h1 className="set-h">AI API</h1>
 
 
 
787
  {error ? <p className="set-error" role="alert">{error}</p> : null}
788
  {notice ? <p className="set-notice" role="status">{notice}</p> : null}
789
 
790
+ <div className="external-progress">
791
+ <p className="set-help">Step {stepIndex + 1} of {steps.length}</p>
792
+ <div className="external-progress-track" role="progressbar" aria-label="Connection setup"
793
+ aria-valuemin={1} aria-valuemax={steps.length} aria-valuenow={stepIndex + 1}>
794
+ <div className="external-progress-fill" style={{ width: ((stepIndex + 1) / steps.length * 100) + "%" }} />
795
+ </div>
796
+ </div>
797
+ <section className="set-card external-step" data-ai-step={step} aria-labelledby="external-step-title">
798
+ <h2 id="external-step-title" className="set-h4" ref={stepHeading} tabIndex={-1}>
799
+ {step === "client" ? "AI client" : step === "verify" ? "Verification"
800
+ : step === "setup" && connection === "key" ? "API key" : client?.label + " setup"}
801
+ </h2>
802
+
803
+ {step === "client" ? (
804
+ <div className="external-clients" aria-label="Which client are you using?">
805
  {CLIENTS.map((entry) => (
806
  <button key={entry.id} type="button" className="set-secondary" data-client={entry.id}
807
  aria-pressed={clientId === entry.id} disabled={busy !== ""}
 
808
  onClick={() => chooseClient(entry.id)}>{entry.label}</button>
809
  ))}
810
  </div>
811
+ ) : null}
812
 
813
+ {step === "connection" && client ? (
814
+ <>
815
+ {clientGuide("mcp")}
816
+ <div className="external-divider">
817
+ <div className="set-actions" style={{ marginTop: 0 }} aria-label="AI API connection choices">
 
 
 
818
  {connectionKinds.includes("mcp") ? (
819
  <button type="button" className="set-secondary" data-connection="mcp"
 
820
  disabled={busy !== ""} aria-pressed={connection === "mcp"}
821
+ title="Use your Loopable sign-in."
822
  onClick={() => chooseConnection("mcp")}>Connect an AI app</button>
823
  ) : null}
824
  {connectionKinds.includes("key") ? (
825
  <button type="button" className="set-secondary" data-connection="key"
 
826
  disabled={busy !== ""} aria-pressed={connection === "key"}
827
+ title="Create a new API key or choose a saved key."
828
  onClick={() => chooseConnection("key")}>Create API key for code/SDK</button>
829
  ) : null}
830
  </div>
831
+ </div>
832
+ </>
833
+ ) : null}
834
 
835
+ {step === "setup" && client && connection ? (
836
+ connection === "mcp" ? clientGuide("mcp") : (
 
837
  <>
838
+ <div className="set-actions" style={{ marginTop: 0 }} aria-label="API key choices">
839
+ <button type="button" className="set-secondary" data-key-choice="create"
840
+ aria-pressed={keyChoice === "create"} disabled={canMint !== true || busy !== ""}
841
+ onClick={() => { setKeyChoice("create"); resetVerification(); }}>Create a new key</button>
842
+ <button type="button" className="set-secondary" data-key-choice="saved"
843
+ aria-pressed={keyChoice === "saved"} disabled={!keys?.some(keyIsActive) || busy !== ""}
844
+ onClick={() => { setKeyChoice("saved"); resetVerification(); }}>Use a saved key</button>
845
+ </div>
846
+ {keysError ? (
847
+ <div role="alert">
848
+ <p className="set-help">{keysError}</p>
849
+ <div className="set-actions"><button type="button" className="set-secondary"
850
+ disabled={busy !== ""} onClick={() => void load()}>Try again</button></div>
851
  </div>
852
+ ) : keys === null ? (
853
+ <div role="status" aria-busy="true">
854
+ <p className="set-help">Loading API key settings…</p>
855
+ <div className="external-key-loading" aria-hidden="true" />
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
856
  </div>
857
+ ) : keys.length === 0 ? (
858
+ <p className="set-help">You have no saved keys yet, so create one here.</p>
859
+ ) : !keys.some(keyIsActive) ? (
860
+ <p className="set-help">No saved key is active. Create one or update its expiry below.</p>
861
+ ) : null}
862
+ {canMint === false ? (
863
+ <p className="set-help">Creating API keys requires the Analyst module. Ask an administrator to grant it.</p>
864
+ ) : null}
865
 
866
+ {keyChoice === "create" && canMint === true ? (
867
+ <form className="external-divider" onSubmit={(event) => void create(event)}>
868
+ <div className="set-field"><label className="set-label" htmlFor="set-external-label">Label</label>
869
+ <input id="set-external-label" className="set-input" type="text" maxLength={80} value={label}
870
+ autoComplete="off" placeholder="Reporting SDK" onChange={(event) => setLabel(event.currentTarget.value)} /></div>
871
+ <div className="set-field"><label className="set-label" htmlFor="set-external-access">Access</label>
872
+ <select id="set-external-access" className="pg-select" value={access}
873
+ onChange={(event) => setAccess(event.currentTarget.value as Access)}>
874
+ <option value="read">Read only</option><option value="readwrite">Read and write</option>
875
+ </select></div>
876
+ <div className="set-field"><label className="set-label" htmlFor="set-external-databases">Resources</label>
877
+ <select id="set-external-databases" className="pg-select" value={databaseMode}
878
+ onChange={(event) => setDatabaseMode(event.currentTarget.value as "all" | "subset")}>
879
+ <option value="all">All databases</option><option value="subset">Selected databases</option>
880
+ </select></div>
881
+ {databaseMode === "subset" ? databaseChecks(selectedDatabases, setSelectedDatabases) : null}
882
+ <div className="set-field"><label className="set-label" htmlFor="set-external-expiry">Expiry</label>
883
+ <input id="set-external-expiry" className="set-input" type="datetime-local" value={expiresAt}
884
+ onChange={(event) => setExpiresAt(event.currentTarget.value)} />
885
+ <p className="set-help">Leave blank for no expiry.</p></div>
886
+ <div className="set-actions"><button type="submit" className="set-primary" disabled={busy !== ""}>
887
+ {busy === "create" ? "Creating…" : "Create API key"}</button></div>
888
+ </form>
889
+ ) : null}
890
 
891
+ {keyChoice === "saved" && keys && keys.length > 0 ? (
892
+ <div className="set-field external-divider">
893
+ <label className="set-label" htmlFor="external-saved-key">Saved key</label>
894
+ <select id="external-saved-key" className="pg-select" value={selectedKey?.id ?? ""}
895
+ disabled={busy !== ""} aria-describedby="external-saved-key-help"
896
+ onChange={(event) => chooseKey(event.currentTarget.value)}>
897
+ <option value="">Choose a key</option>
898
+ {keys.map((key) => (
899
+ <option key={key.id} value={key.id} disabled={!keyIsActive(key)}>
900
+ {key.label} · {key.access === "read" ? "Read only" : "Read and write"} · {key.expires_at ? "Expires " + when(key.expires_at) : "No expiry"}
901
+ {key.revoked_at ? " (Revoked)" : !keyIsActive(key) ? " (Expired)" : ""}
902
+ </option>
903
+ ))}
904
+ </select>
905
+ <p id="external-saved-key-help" className="set-help">
906
+ Loopable cannot show an existing key again. Paste your own saved copy into {client.label}, never into chat.
907
+ </p>
908
+ {verificationReveal ? <p className="set-help">Save the new secret below before continuing.</p> : null}
909
  </div>
910
  ) : null}
911
+ {keyChoice === "saved" && selectedKeyIsActive ? clientGuide("key") : null}
912
  </>
913
+ )
914
+ ) : null}
915
 
916
+ {step === "verify" && client ? (
917
+ <>
918
+ {connection === "key" ? (
919
+ <>
920
+ {selectedKey ? <p className="set-help">Key: {selectedKey.label}</p> : null}
921
+ {!selectedKeyIsActive ? <p className="set-help">Go back and choose an active key.</p> : null}
922
+ {verificationReveal ? <p className="set-help">Verify the API key just created or rotated.</p> : (
923
+ <div className="set-field">
924
+ <label className="set-label" htmlFor="external-verify-key">Saved API key</label>
925
+ <input id="external-verify-key" className="set-input" type="password" value={verifySecret}
926
+ autoComplete="off" spellCheck={false} disabled={busy !== "" || !selectedKeyIsActive}
927
+ aria-describedby="external-verify-key-help"
928
+ onChange={(event) => { setVerifySecret(event.currentTarget.value); setVerifyResult(null); }} />
929
+ <p id="external-verify-key-help" className="set-help">Loopable cannot show an existing key again. Rotating issues a new one. This field clears after the check.</p>
 
 
 
 
 
 
 
930
  </div>
931
+ )}
932
+ <p className="set-help">This checks the key with Loopable. Use the starter prompt in {client.label} to check its setup.</p>
933
+ <div className="set-actions">
934
+ <button type="button" className="set-primary" data-verify="key"
935
+ disabled={busy !== "" || !selectedKeyIsActive || !(verificationReveal?.secret || verifySecret.trim())}
936
+ onClick={() => void verifyKey()}>{busy === "verify:key" ? "Verifying…" : "Verify API key"}</button>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
937
  </div>
938
+ </>
939
+ ) : (
940
+ <>
941
+ <p className="set-help">Check for a completed {client.label} sign-in with Loopable.</p>
942
+ <div className="set-actions">
943
+ <button type="button" className="set-primary" data-verify="mcp" disabled={busy !== ""}
944
+ onClick={() => void verifyMcp()}>{busy === "verify:mcp" ? "Checking…" : "Verify sign-in"}</button>
945
+ </div>
946
+ </>
947
+ )}
948
+ {verifyResult ? (
949
+ <p className="set-help" role="status" data-verify-result data-verify-state={verifyResult.state}
950
+ style={{ padding: 12, marginTop: 12, borderRadius: "var(--lp-r-md)",
951
+ color: verifyResult.state === "ok" ? "var(--lp-green-deep)" : "var(--lp-red-deep)",
952
+ background: verifyResult.state === "ok" ? "var(--lp-green-tint)" : "var(--lp-red-tint)" }}>
953
+ {verifyResult.message}
954
+ </p>
955
+ ) : null}
956
+ </>
957
+ ) : null}
958
 
959
+ {step !== "client" ? (
960
+ <div className="external-footer">
961
+ <button type="button" className="set-secondary" disabled={busy !== ""}
962
+ onClick={() => { setVerifySecret(""); setStep(steps[stepIndex - 1]); }}>Back</button>
963
+ {step === "setup" ? (
964
+ <button type="button" className="set-primary"
965
+ disabled={busy !== "" || (connection === "key" && (keyChoice !== "saved" || !selectedKeyIsActive))}
966
+ onClick={() => { setReadyToVerify(true); setStep("verify"); }}>Continue to verify</button>
967
+ ) : null}
968
+ </div>
969
+ ) : null}
970
+ </section>
971
  <section className="set-card">
972
  <h2 className="set-h4">Safe starter prompt</h2>
973
  <label className="set-label" htmlFor="external-starter-prompt">First message</label>
 
980
  </button></div>
981
  </section>
982
 
983
+ {revealCard}
984
+
985
+ {client && connection ? (
986
+ <section className="set-card">
987
+ <h2 className="set-h4">SDK skill</h2>
988
+ <p className="set-help">Download or copy skill.md. It describes the API but contains no API key or other secret.</p>
989
+ <div className="set-actions">
990
+ <button type="button" className="set-secondary" disabled={canMint !== true || busy !== ""}
991
+ onClick={() => void downloadSkill()}>{busy === "skill-download" ? "Preparing…" : "Download skill.md"}</button>
992
+ <button type="button" className="set-secondary" disabled={canMint !== true || busy !== ""}
993
+ onClick={() => void copySkill()}>{busy === "skill-copy" ? "Copying…" : copied === "skill" ? "Copied" : "Copy skill.md"}</button>
994
+ </div>
995
+ </section>
996
+ ) : null}
997
+
998
+ {connections.length > 0 ? (
999
+ <section className="set-card">
1000
+ <h2 className="set-h4">AI connections</h2>
1001
+ {connections.map((connection) => (
1002
+ <div key={connection.id} style={{ marginTop: 16 }}>
1003
+ <div className="pg-drill-row"><span className="pg-drill-key">{connection.label || "Unnamed AI app"}</span>
1004
+ <span className="pg-drill-val">{connectionLabel(connection)}</span></div>
1005
+ <div className="pg-drill-row"><span className="pg-drill-key">Last used</span>
1006
+ <span className="pg-drill-val">{when(connection.last_used)}</span></div>
1007
+ {connection.status === "connected" ? (
1008
+ <div className="set-actions">
1009
+ <button type="button" className="set-secondary kc-danger" disabled={busy !== ""}
1010
+ onClick={() => void disconnect(connection)}>
1011
+ {busy === `disconnect:${connection.client}` ? "Disconnecting…" : "Disconnect"}
1012
+ </button>
1013
+ </div>
1014
+ ) : null}
1015
+ </div>
1016
+ ))}
1017
+ </section>
1018
+ ) : null}
1019
 
1020
  <div className="set-perm-sect"><h2 className="set-h4">API keys</h2></div>
1021
+ {keysError ? <><p className="set-help" role="alert">{keysError}</p>
1022
+ <div className="set-actions"><button type="button" className="set-secondary" disabled={busy !== ""}
1023
+ onClick={() => void load()}>Try again</button></div></>
1024
+ : keys === null ? <p className="set-help" role="status">Loading API keys…</p>
1025
  : keys.length === 0 ? <p className="set-help">You have no API keys yet.</p> : (
1026
  <div aria-label="Active API keys">
1027
  {keys.map((key) => (
web/src/settings/SettingsModal.tsx CHANGED
@@ -77,6 +77,7 @@ import { ManageDatabasePane } from "./ManageDatabase";
77
  // client-local preference pane, self-contained like `ManageDatabasePane`; see the mount below.
78
  import ShortcutSettings from "./ShortcutSettings";
79
  import SecurityPane from "./SecurityPane";
 
80
  import OperatorPage from "../operator/OperatorPage";
81
  /* ⛔ `StatementsPane` LEFT WITH ITS RAIL ROW (wave 35 · T38): the file is DELETED, not merely
82
  unmounted. An orphaned component with no importer is the shape this repo books as
@@ -155,6 +156,12 @@ const IconSecurity = (
155
  <path d="m5.5 7.9 1.7 1.7 3.4-3.4" />
156
  </RailIcon>
157
  );
 
 
 
 
 
 
158
  /** Sheet shortcuts — a small keyboard: a row of keys above a spacebar, not the padlock
159
  * "Your access" already wears (two authority glyphs in one rail would drift together). */
160
  const IconShortcuts = (
@@ -816,6 +823,7 @@ export function SettingsModal({
816
  // preferences, and there is nothing behind this room a member's account cannot already do to
817
  // itself (the store is client-local, keyed to nothing server-side).
818
  ["shortcuts", "Sheet shortcuts", IconShortcuts],
 
819
  ...(admin
820
  ? ([
821
  ["users", "Manage users", IconUsers],
@@ -892,6 +900,7 @@ export function SettingsModal({
892
  {rail.map(([key, label, icon]) => (
893
  <button
894
  key={key}
 
895
  type="button"
896
  className={"set-rail-item" + (active === key ? " is-active" : "")}
897
  onClick={() => onSection(key)}
@@ -924,6 +933,7 @@ export function SettingsModal({
924
  in, because a keyboard preference is not server data. */}
925
  {active === "shortcuts" ? <ShortcutSettings /> : null}
926
  {active === "security" ? <SecurityPane /> : null}
 
927
  {active === "keychains" ? <KeychainPane /> : null}
928
  {active === "connectors" ? <ConnectorsPane /> : null}
929
  {/* Wave 19 contract C2 — the wiring record, verified at the MOUNT SITE
 
77
  // client-local preference pane, self-contained like `ManageDatabasePane`; see the mount below.
78
  import ShortcutSettings from "./ShortcutSettings";
79
  import SecurityPane from "./SecurityPane";
80
+ import ActivityLogPage from "./ActivityLogPage";
81
  import OperatorPage from "../operator/OperatorPage";
82
  /* ⛔ `StatementsPane` LEFT WITH ITS RAIL ROW (wave 35 · T38): the file is DELETED, not merely
83
  unmounted. An orphaned component with no importer is the shape this repo books as
 
156
  <path d="m5.5 7.9 1.7 1.7 3.4-3.4" />
157
  </RailIcon>
158
  );
159
+ const IconActivity = (
160
+ <RailIcon>
161
+ <circle cx="8" cy="8" r="5.6" />
162
+ <path d="M8 4.5V8l2.6 1.6" />
163
+ </RailIcon>
164
+ );
165
  /** Sheet shortcuts — a small keyboard: a row of keys above a spacebar, not the padlock
166
  * "Your access" already wears (two authority glyphs in one rail would drift together). */
167
  const IconShortcuts = (
 
823
  // preferences, and there is nothing behind this room a member's account cannot already do to
824
  // itself (the store is client-local, keyed to nothing server-side).
825
  ["shortcuts", "Sheet shortcuts", IconShortcuts],
826
+ ["activity", "Activity log", IconActivity],
827
  ...(admin
828
  ? ([
829
  ["users", "Manage users", IconUsers],
 
900
  {rail.map(([key, label, icon]) => (
901
  <button
902
  key={key}
903
+ data-section={key}
904
  type="button"
905
  className={"set-rail-item" + (active === key ? " is-active" : "")}
906
  onClick={() => onSection(key)}
 
933
  in, because a keyboard preference is not server data. */}
934
  {active === "shortcuts" ? <ShortcutSettings /> : null}
935
  {active === "security" ? <SecurityPane /> : null}
936
+ {active === "activity" ? <ActivityLogPage user={user} /> : null}
937
  {active === "keychains" ? <KeychainPane /> : null}
938
  {active === "connectors" ? <ConnectorsPane /> : null}
939
  {/* Wave 19 contract C2 — the wiring record, verified at the MOUNT SITE
web/src/settings/activityLog.css ADDED
@@ -0,0 +1,58 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ .activity-pane { min-width: 0; }
2
+ .activity-pane .set-h, .activity-pane .set-h4 { font-weight: 600; margin-bottom: 12px; }
3
+ .activity-pane .set-help { margin-top: 4px; }
4
+ .activity-pane .set-notice { color: var(--lp-yellow-deep); background: var(--lp-yellow-tint); padding: 8px 12px; font-variant-numeric: tabular-nums; }
5
+ .activity-button {
6
+ border: 0;
7
+ background: transparent;
8
+ font: inherit;
9
+ color: inherit;
10
+ cursor: pointer;
11
+ border-radius: var(--lp-r-sm);
12
+ text-align: left;
13
+ }
14
+ .activity-button:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: 2px; }
15
+ .activity-button:disabled { opacity: 0.5; cursor: not-allowed; }
16
+ .activity-control { min-height: 32px; padding: 4px 12px; color: var(--lp-ink); background: var(--lp-surface-2); font-size: var(--lp-fs-xs); }
17
+ .activity-toolbar { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; margin: 16px 0; }
18
+ .activity-user { display: flex; align-items: center; gap: 8px; min-width: 0; }
19
+ .activity-user .pg-select { min-height: 32px; max-width: 100%; }
20
+ .activity-user .set-label { margin: 0; }
21
+ .activity-retention { font-variant-numeric: tabular-nums; }
22
+ .activity-heading { display: flex; align-items: baseline; gap: 8px; flex-wrap: wrap; }
23
+ .activity-sessions, .activity-timeline, .activity-movement { list-style: none; margin: 0; padding: 0; }
24
+ .activity-sessions > li, .activity-event { border-bottom: 1px solid var(--lp-line); }
25
+ .activity-session { display: grid; grid-template-columns: minmax(108px, 1.3fr) minmax(72px, 1fr) auto auto auto; align-items: center; gap: 12px; padding: 12px 4px; width: 100%; font-size: var(--lp-fs-xs); }
26
+ .activity-session-route, .activity-target { overflow-wrap: anywhere; min-width: 0; }
27
+ .activity-number { font-variant-numeric: tabular-nums; text-align: right; }
28
+ .activity-negative { color: var(--lp-red-deep); }
29
+ .activity-action, .activity-error-toggle { display: grid; grid-template-columns: 80px minmax(0, 1fr) auto; align-items: start; gap: 12px; padding: 12px 4px; font-size: var(--lp-fs-xs); }
30
+ .activity-error-toggle { width: 100%; color: var(--lp-red-deep); }
31
+ .activity-event-error { background: var(--lp-red-tint); }
32
+ .activity-event-copy { display: flex; flex-direction: column; gap: 4px; min-width: 0; overflow-wrap: anywhere; }
33
+ .activity-kind { font-weight: 500; }
34
+ .activity-metrics { display: flex; flex-direction: column; gap: 4px; color: var(--lp-muted); }
35
+ .activity-source { font-size: var(--lp-fs-2xs); }
36
+ .activity-chevron { width: 16px; height: 16px; fill: none; stroke: currentColor; stroke-width: 1.5; transition: transform 150ms ease-out; }
37
+ .activity-chevron.is-open { transform: rotate(90deg); }
38
+ .activity-trail { padding: 8px 12px 16px; background: var(--lp-surface); color: var(--lp-ink); }
39
+ .activity-movement > li { display: grid; grid-template-columns: 84px 64px minmax(0, 1fr) auto; gap: 8px; padding: 8px 0; border-bottom: 1px solid var(--lp-line); font-size: var(--lp-fs-2xs); }
40
+ .activity-sample-kind { text-transform: capitalize; }
41
+ .activity-pagination .set-help { margin-right: auto; font-variant-numeric: tabular-nums; }
42
+ .activity-empty { display: flex; align-items: center; gap: 12px; padding: 16px 0; }
43
+ .activity-empty p { margin: 0; }
44
+ .activity-skeleton { display: grid; grid-template-columns: 1fr 2fr 1fr; gap: 16px; padding: 16px 4px; border-bottom: 1px solid var(--lp-line); }
45
+ .activity-skeleton span { display: block; height: 16px; border-radius: var(--lp-r-sm); background: var(--lp-surface-2); }
46
+ @media (hover: hover) and (pointer: fine) {
47
+ .activity-button:hover:not(:disabled) { background: var(--lp-blue-tint); }
48
+ .activity-error-toggle:hover:not(:disabled) { background: var(--lp-red-tint); }
49
+ }
50
+ @media (max-width: 760px) {
51
+ .activity-session { grid-template-columns: minmax(100px, 1fr) minmax(64px, 1fr) auto; gap: 8px; }
52
+ .activity-action, .activity-error-toggle { grid-template-columns: 72px minmax(0, 1fr); gap: 8px; }
53
+ .activity-metrics { grid-column: 2; flex-direction: row; justify-content: flex-end; }
54
+ .activity-chevron { display: none; }
55
+ .activity-movement > li { grid-template-columns: 80px 64px minmax(0, 1fr); }
56
+ .activity-movement > li > :last-child { grid-column: 3; }
57
+ }
58
+ @media (prefers-reduced-motion: reduce) { .activity-chevron { transition: none; } }
web/src/settings/activityLog.ts ADDED
@@ -0,0 +1,392 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT } from "../apiContract";
2
+
3
+ export interface ActivityTarget {
4
+ tagName: string;
5
+ role?: string;
6
+ type?: string;
7
+ id?: string;
8
+ name?: string;
9
+ className?: string;
10
+ "aria-label"?: string;
11
+ data?: Record<string, string>;
12
+ path?: string[];
13
+ }
14
+
15
+ export interface MovementSample {
16
+ kind: "hover" | "scroll" | "focus" | "keypress" | "pointer";
17
+ ts: number;
18
+ target: ActivityTarget;
19
+ x?: number;
20
+ y?: number;
21
+ key?: string;
22
+ }
23
+
24
+ export interface ActivityEvent {
25
+ eventId?: string;
26
+ kind: "route" | "click" | "api" | "error";
27
+ ts: number;
28
+ route: string;
29
+ from?: string;
30
+ to?: string;
31
+ ms?: number;
32
+ target?: ActivityTarget;
33
+ method?: string;
34
+ url?: string;
35
+ status?: number;
36
+ message?: string;
37
+ source?: string;
38
+ line?: number;
39
+ name?: string;
40
+ movement?: MovementSample[];
41
+ movementDropped?: number;
42
+ }
43
+
44
+ const WINDOW_MS = 30_000;
45
+ const MAX_MOVEMENT = 500;
46
+ const MAX_ACTIONS = 200;
47
+ const MAX_BATCH = 100;
48
+ const MAX_BATCH_BYTES = 60 * 1024; // Fits the browser's shared keepalive/beacon budget.
49
+ const SESSION_KEY = "loopable.activity.session";
50
+ const ENDPOINT = `${API_V1}/activity`;
51
+ const SECRET = /\bbearer\s+\S+|\beyJ[A-Za-z0-9_-]*\.|\blp[bcor]1\.[A-Za-z0-9._~-]+|Atzr\|/i;
52
+ const CLASSES = /^(?:set|shell|sheet|cg|pg|activity|lp|is)-[a-z][a-z0-9-]*$/;
53
+ const PRIVATE_DATA = /value|text|content|html|password|token|secret|credential|cookie|authorization|payload|clipboard|body|query|cell|key/i;
54
+ const PROTECTED = 'input,textarea,select,option,[contenteditable]:not([contenteditable="false"]),[role="textbox"],[role="searchbox"],[role="gridcell"],[role="cell"],[role="grid"],td,th,canvas,.sheet-cell,.cg-cell,.gdg-input';
55
+ const LABELS = new Set(["Open", "Close", "Save", "Cancel", "Delete", "Edit", "Search", "Settings", "Close settings", "Activity log", "Refresh", "Previous", "Next", "Add", "Remove", "Menu", "More", "Retry"]);
56
+ const DATA_ENUMS: Record<string, Set<string>> = {
57
+ "data-section": new Set(["account", "scope", "security", "shortcuts", "activity", "users", "database", "keychains", "connectors", "padmin"]),
58
+ "data-state": new Set(["open", "closed", "active", "inactive", "loading", "ready"]),
59
+ "data-view-kind": new Set(["sheet", "grid", "table", "chart", "timeline"]),
60
+ };
61
+ const ROUTE_SEGMENTS = new Set("api v1 auth me login logout refresh nav workspace settings account scope security shortcuts activity sessions users database databases grid sheet sheets view views table tables records rows columns fields cells query sort filter data applications finance facts orders inventory customers products sales collections procurement agents agent automation automations connectors keychains external oauth connections admin operator subscriptions billing health status run runs events logs actions export import search schema preferences folders pages charts catalog reports reconciliation permissions detail assets src settings ActivityLogPage.tsx activityLog.ts main.tsx".split(" "));
62
+ const ERROR_NAMES = new Set(["Error", "TypeError", "ReferenceError", "SyntaxError", "RangeError", "URIError", "EvalError", "AggregateError", "NetworkError", "HttpError", "ResourceError"]);
63
+ const ERROR_MESSAGES = new Set(["Application error.", "Unhandled rejection.", "Script error.", "A request failed.", "A network request failed.", "A resource failed to load."]);
64
+
65
+ let installed = false;
66
+ let reportError: ((detail: ActivityErrorDetail) => void) | undefined;
67
+
68
+ export interface ActivityErrorDetail {
69
+ message?: string;
70
+ source?: string;
71
+ line?: number;
72
+ name?: string;
73
+ }
74
+
75
+ /** Error boundaries may use this door without passing props, state, or stacks. */
76
+ export function reportActivityError(detail: ActivityErrorDetail): void {
77
+ try { reportError?.(detail); } catch { /* Telemetry never throws into the application. */ }
78
+ }
79
+
80
+ function text(value: unknown, max = 256): string {
81
+ if (typeof value !== "string" || SECRET.test(value)) return "";
82
+ return value.replace(/[\u0000-\u001f\u007f\u2013\u2014]/g, " ").slice(0, max);
83
+ }
84
+
85
+ function routePath(value: string): string {
86
+ const safe = text(value);
87
+ if (!safe) return "";
88
+ try {
89
+ const raw = safe.startsWith("#") ? safe.slice(1).split(/[?#]/)[0] : new URL(safe, window.location.origin).pathname;
90
+ return ("/" + raw.split("/").filter(Boolean).map(part =>
91
+ ROUTE_SEGMENTS.has(part) || /^[a-zA-Z0-9_-]+\.(js|css|tsx|ts)$/.test(part) ? part : ":item",
92
+ ).join("/")).slice(0, 256);
93
+ } catch { return ""; }
94
+ }
95
+
96
+ function classes(element: Element): string {
97
+ return text(element.getAttribute("class")).split(/\s+/).filter(part => CLASSES.test(part)).join(" ").slice(0, 128);
98
+ }
99
+
100
+ function exceptionLocation(error: unknown): Pick<ActivityErrorDetail, "source" | "line"> {
101
+ if (!(error instanceof Error) || typeof error.stack !== "string") return {};
102
+ // Skip the message line. Extract only the first frame's location, never the stack.
103
+ for (const frame of error.stack.split("\n").slice(1, 7)) {
104
+ const match = frame.match(/((?:https?:\/\/|\/)[^\s)]+):(\d+):\d+\)?$/);
105
+ if (match) return { source: routePath(match[1]), line: Number(match[2]) };
106
+ }
107
+ return {};
108
+ }
109
+
110
+ /** Never read displayed text or any control/cell content, even to redact it. */
111
+ function identity(target: EventTarget | null): ActivityTarget {
112
+ const element = target instanceof Element ? target : null;
113
+ if (!element) return { tagName: "document" };
114
+ const protectedParent = element.closest(PROTECTED);
115
+ const tagName = element.tagName.toLowerCase();
116
+ const result: ActivityTarget = { tagName };
117
+ const role = text(element.getAttribute("role"), 32);
118
+ if (role) result.role = role;
119
+ if (protectedParent) {
120
+ // Preserve context on descendants, including portalled contenteditable editors.
121
+ result.role = protectedParent.matches('[role="grid"],[role="gridcell"],[role="cell"],td,th,canvas,.sheet-cell,.cg-cell') ? "gridcell" : "textbox";
122
+ }
123
+ const type = text(element.getAttribute("type"), 32);
124
+ if (type) result.type = type;
125
+ const path: string[] = [];
126
+ for (let ancestor = element.parentElement; ancestor && path.length < 5; ancestor = ancestor.parentElement) {
127
+ const className = protectedParent ? "" : classes(ancestor);
128
+ path.push(ancestor.tagName.toLowerCase() + (className ? "." + className.replace(/ /g, ".") : ""));
129
+ }
130
+ result.path = path;
131
+ if (protectedParent) return result;
132
+ const className = classes(element);
133
+ if (className) result.className = className;
134
+ for (const key of ["id", "name"] as const) {
135
+ const val = text(element.getAttribute(key), 80);
136
+ if (val === "root" || CLASSES.test(val)) result[key] = val;
137
+ }
138
+ const label = text(element.getAttribute("aria-label"));
139
+ if (LABELS.has(label)) result["aria-label"] = label;
140
+ const data: Record<string, string> = {};
141
+ for (const attr of Array.from(element.attributes)) {
142
+ if (Object.keys(data).length >= 16) break;
143
+ if (!/^data-[a-z][a-z-]{0,47}$/.test(attr.name) || PRIVATE_DATA.test(attr.name.slice(5))) continue;
144
+ // Only enum-valued chrome attributes are read. Others describe presence only.
145
+ const val = DATA_ENUMS[attr.name] ? text(element.getAttribute(attr.name)) : "present";
146
+ if (val) data[attr.name] = DATA_ENUMS[attr.name]?.has(val) ? val : "present";
147
+ }
148
+ if (Object.keys(data).length) result.data = data;
149
+ return result;
150
+ }
151
+
152
+ function tabSession(): string {
153
+ try {
154
+ const saved = window.sessionStorage.getItem(SESSION_KEY);
155
+ if (saved && /^[a-f0-9-]{32,36}$/.test(saved)) return saved;
156
+ } catch { /* Storage can be disabled; use a memory-only random tab id. */ }
157
+ const bytes = new Uint8Array(16);
158
+ window.crypto.getRandomValues(bytes);
159
+ const id = Array.from(bytes, byte => byte.toString(16).padStart(2, "0")).join("");
160
+ try { window.sessionStorage.setItem(SESSION_KEY, id); } catch { /* Keep collecting in memory. */ }
161
+ return id;
162
+ }
163
+
164
+ export function installActivityLog(): void {
165
+ if (typeof window === "undefined" || installed) return;
166
+ installed = true;
167
+ try { startCollector(); } catch { /* Startup telemetry must never block React. */ }
168
+ }
169
+
170
+ function startCollector(): void {
171
+ const sessionId = tabSession();
172
+ const nativeFetch = window.fetch.bind(window);
173
+ let actions: ActivityEvent[] = [];
174
+ let movement: MovementSample[] = [];
175
+ let evictedMovement: Array<{ second: number; count: number }> = [];
176
+ let dropped = 0;
177
+ let inFlight = false;
178
+ let generation = 0;
179
+ let lastFlush = 0;
180
+ let scheduled: number | undefined;
181
+ let previousRoute = routePath(window.location.hash || window.location.pathname);
182
+ let previousLocation = window.location.hash || window.location.pathname;
183
+ let routeSince = performance.now();
184
+ const currentRoute = () => routePath(window.location.hash || window.location.pathname);
185
+ const safely = (work: () => void) => { try { work(); } catch { dropped++; } };
186
+
187
+ function action(event: ActivityEvent): void {
188
+ if (actions.length >= MAX_ACTIONS) { actions.shift(); dropped++; }
189
+ actions.push(event);
190
+ }
191
+
192
+ function prune(now: number): void {
193
+ movement = movement.filter(sample => sample.ts >= now - WINDOW_MS);
194
+ evictedMovement = evictedMovement.filter(bucket => bucket.second >= Math.floor((now - WINDOW_MS) / 1000));
195
+ }
196
+
197
+ function move(sample: MovementSample): void {
198
+ prune(sample.ts);
199
+ if (movement.length >= MAX_MOVEMENT) {
200
+ const removed = movement.shift();
201
+ if (removed) {
202
+ const second = Math.floor(removed.ts / 1000);
203
+ const bucket = evictedMovement.at(-1);
204
+ if (bucket?.second === second) bucket.count++;
205
+ else evictedMovement.push({ second, count: 1 });
206
+ }
207
+ }
208
+ movement.push(sample);
209
+ }
210
+
211
+ function flush(unload = false): void {
212
+ if (!actions.length || (inFlight && !unload)) return;
213
+ if (!unload && Date.now() - lastFlush < 1000) {
214
+ if (scheduled === undefined) scheduled = window.setTimeout(() => { scheduled = undefined; safely(() => flush()); }, 1000);
215
+ return;
216
+ }
217
+ lastFlush = Date.now();
218
+ // Consume before sending. Failed telemetry is counted, never queued for retries.
219
+ const batch = actions.splice(0, MAX_BATCH);
220
+ const lost = dropped;
221
+ dropped = 0;
222
+ let body = "";
223
+ while (batch.length) {
224
+ body = JSON.stringify({ sessionId, events: batch, dropped: lost });
225
+ if (new Blob([body]).size <= MAX_BATCH_BYTES) break;
226
+ const largest = batch.reduce((a, b) => (a.movement?.length ?? 0) > (b.movement?.length ?? 0) ? a : b);
227
+ if (largest.movement?.length) {
228
+ // Keep the whole time interval under the byte budget by thinning samples.
229
+ const before = largest.movement.length;
230
+ largest.movement = largest.movement.filter((_, index) => index % 2 === 0);
231
+ if (before === 1) largest.movement = [];
232
+ largest.movementDropped = (largest.movementDropped ?? 0) + before - largest.movement.length;
233
+ } else { batch.shift(); dropped++; }
234
+ }
235
+ if (!batch.length) { dropped += lost; return; }
236
+ if (unload && typeof navigator.sendBeacon === "function") {
237
+ try {
238
+ if (navigator.sendBeacon(ENDPOINT, new Blob([body], { type: "application/json" }))) {
239
+ dropped += actions.length;
240
+ actions = [];
241
+ return;
242
+ }
243
+ } catch { /* Fall back once to fetch. */ }
244
+ }
245
+ const sentGeneration = generation;
246
+ inFlight = true;
247
+ void nativeFetch(ENDPOINT, { method: "POST", credentials: CREDENTIALS,
248
+ headers: { "Content-Type": "application/json" }, body, keepalive: unload,
249
+ }).then(response => {
250
+ if (!response.ok && sentGeneration === generation) dropped += batch.length + lost;
251
+ }).catch(() => { if (sentGeneration === generation) dropped += batch.length + lost; })
252
+ .finally(() => {
253
+ inFlight = false;
254
+ if (actions.some(event => event.kind === "error")) safely(() => flush());
255
+ });
256
+ }
257
+
258
+ reportError = detail => safely(() => {
259
+ const now = Date.now();
260
+ prune(now);
261
+ const name = text(detail.name, 64);
262
+ const message = text(detail.message);
263
+ action({ kind: "error", ts: now, route: currentRoute(), name: ERROR_NAMES.has(name) ? name : "Error",
264
+ // Exception messages can interpolate a cell; only fixed diagnostic copy is safe.
265
+ message: ERROR_MESSAGES.has(message) ? message : "Application error.",
266
+ source: routePath(detail.source ?? ""), line: Number.isFinite(detail.line) ? Math.max(0, Math.round(detail.line!)) : 0,
267
+ movement: movement.map(sample => ({ ...sample })), movementDropped: evictedMovement.reduce((sum, bucket) => sum + bucket.count, 0),
268
+ });
269
+ flush();
270
+ });
271
+
272
+ function boundary(): void {
273
+ generation++;
274
+ actions = [];
275
+ movement = [];
276
+ evictedMovement = [];
277
+ dropped = 0;
278
+ previousRoute = currentRoute();
279
+ previousLocation = window.location.hash || window.location.pathname;
280
+ routeSince = performance.now();
281
+ }
282
+
283
+ window.addEventListener(UNAUTHORIZED_EVENT, boundary);
284
+ window.fetch = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
285
+ let path = "";
286
+ let method = "GET";
287
+ let ownFlush = false;
288
+ safely(() => {
289
+ const rawUrl = input instanceof Request ? input.url : String(input);
290
+ const pathname = new URL(rawUrl, window.location.origin).pathname;
291
+ ownFlush = pathname.replace(/\/$/, "") === ENDPOINT;
292
+ path = routePath(rawUrl);
293
+ method = text(init?.method ?? (input instanceof Request ? input.method : "GET"), 16).toUpperCase();
294
+ if (/\/auth\/(?:login|logout)$/.test(pathname)) boundary();
295
+ });
296
+ const started = performance.now();
297
+ const requestGeneration = generation;
298
+ try {
299
+ const response = await nativeFetch(input, init);
300
+ if (!ownFlush && requestGeneration === generation) safely(() => {
301
+ action({ kind: "api", ts: Date.now(), route: currentRoute(), method, url: path,
302
+ status: response.status, ms: Math.round(performance.now() - started) });
303
+ if (response.status >= 400 && response.status !== 401) reportActivityError({ name: "HttpError", message: "A request failed.", source: path });
304
+ if (response.status === 401) boundary();
305
+ });
306
+ return response;
307
+ } catch (error) {
308
+ if (!ownFlush && requestGeneration === generation) safely(() => {
309
+ action({ kind: "api", ts: Date.now(), route: currentRoute(), method, url: path,
310
+ status: 0, ms: Math.round(performance.now() - started) });
311
+ // Aborted component reads are normal navigation, not user-visible errors.
312
+ const aborted = init?.signal?.aborted || (input instanceof Request && input.signal.aborted)
313
+ || (error instanceof Error && error.name === "AbortError");
314
+ if (!aborted) {
315
+ reportActivityError({ name: "NetworkError", message: "A network request failed.", source: path });
316
+ }
317
+ });
318
+ throw error;
319
+ }
320
+ };
321
+
322
+ function routeChanged(): void {
323
+ safely(() => {
324
+ const route = currentRoute();
325
+ const location = window.location.hash || window.location.pathname;
326
+ if (location === previousLocation) return; // popstate and hashchange may describe one move.
327
+ const now = performance.now();
328
+ action({ kind: "route", ts: Date.now(), route, from: previousRoute, to: route, ms: Math.round(now - routeSince) });
329
+ previousRoute = route;
330
+ previousLocation = location;
331
+ routeSince = now;
332
+ });
333
+ }
334
+ window.addEventListener("hashchange", routeChanged);
335
+ window.addEventListener("popstate", routeChanged);
336
+ action({ kind: "route", ts: Date.now(), route: previousRoute, from: "", to: previousRoute, ms: 0 });
337
+ document.addEventListener("click", event => safely(() => action({ kind: "click", ts: Date.now(), route: currentRoute(), target: identity(event.target) })), true);
338
+
339
+ let lastPointer = 0;
340
+ let lastHover = 0;
341
+ let hovered: EventTarget | null = null;
342
+ let cursor: ActivityTarget = { tagName: "document" };
343
+ let cursorPosition: { x: number; y: number } | undefined;
344
+ document.addEventListener("pointermove", event => safely(() => {
345
+ const now = Date.now();
346
+ if (now - lastPointer < 100) return;
347
+ lastPointer = now;
348
+ cursorPosition = { x: event.clientX, y: event.clientY };
349
+ cursor = identity(document.elementFromPoint(event.clientX, event.clientY) ?? event.target);
350
+ move({ kind: "pointer", ts: now, x: Math.round(event.clientX), y: Math.round(event.clientY), target: cursor });
351
+ if ((event.target !== hovered && now - lastHover >= 250) || now - lastHover >= 1000) {
352
+ hovered = event.target;
353
+ lastHover = now;
354
+ move({ kind: "hover", ts: now, target: cursor });
355
+ }
356
+ }), { capture: true, passive: true });
357
+ let lastScroll = 0;
358
+ document.addEventListener("scroll", event => safely(() => {
359
+ const now = Date.now();
360
+ if (now - lastScroll < 100) return;
361
+ lastScroll = now;
362
+ const element = event.target instanceof Element ? event.target : document.scrollingElement;
363
+ cursor = identity(cursorPosition ? document.elementFromPoint(cursorPosition.x, cursorPosition.y) : event.target);
364
+ move({ kind: "scroll", ts: now, x: Math.round(element?.scrollLeft ?? window.scrollX),
365
+ y: Math.round(element?.scrollTop ?? window.scrollY), target: cursor });
366
+ }), { capture: true, passive: true });
367
+ document.addEventListener("focusin", event => safely(() => move({ kind: "focus", ts: Date.now(), target: identity(event.target) })), true);
368
+ document.addEventListener("keydown", event => safely(() => {
369
+ const target = identity(event.target);
370
+ const editable = target.role === "textbox" || target.role === "gridcell";
371
+ let key = event.key === " " ? "Space" : text(event.key, 32);
372
+ // Printable edit sequences could reconstruct the entire cell. Keep the gesture only.
373
+ const shortcut = (event.ctrlKey || event.metaKey) && !event.altKey;
374
+ if (editable && (event.key.length === 1 || event.isComposing) && !shortcut) key = "Character";
375
+ else {
376
+ const modifiers = [[event.ctrlKey, "Control"], [event.altKey, "Alt"], [event.shiftKey, "Shift"], [event.metaKey, "Meta"]] as const;
377
+ key = [...modifiers.filter(([active, name]) => active && name !== key).map(([, name]) => name), key].join("+");
378
+ }
379
+ move({ kind: "keypress", ts: Date.now(), target, key });
380
+ }), true);
381
+ window.addEventListener("error", event => safely(() => {
382
+ if (event instanceof ErrorEvent) reportActivityError({ message: event.message, name: event.error instanceof Error ? event.error.name : "Error", source: event.filename, line: event.lineno });
383
+ else reportActivityError({ name: "ResourceError", message: "A resource failed to load." });
384
+ }), true);
385
+ window.addEventListener("unhandledrejection", event => safely(() => reportActivityError({
386
+ name: event.reason instanceof Error ? event.reason.name : "Error", message: "Unhandled rejection.",
387
+ ...exceptionLocation(event.reason),
388
+ })));
389
+ window.setInterval(() => safely(() => flush()), 10_000);
390
+ document.addEventListener("visibilitychange", () => { if (document.visibilityState === "hidden") safely(() => flush(true)); });
391
+ window.addEventListener("pagehide", () => safely(() => flush(true)));
392
+ }
web/src/settings/permsModel.ts CHANGED
@@ -52,6 +52,7 @@ export type SettingsSection =
52
  * store, never on this wire: there is nothing here for a server to enforce.
53
  */
54
  | "shortcuts"
 
55
  | "external"
56
  | "users"
57
  /**
 
52
  * store, never on this wire: there is nothing here for a server to enforce.
53
  */
54
  | "shortcuts"
55
+ | "activity"
56
  | "external"
57
  | "users"
58
  /**
web/src/sheet/BindingEditor.tsx CHANGED
@@ -44,8 +44,8 @@ import { dayText } from "../customer-grid/display";
44
  import { FieldSelectButton } from "../customer-grid/FieldSelect";
45
  import { FieldTypeIcon, MenuIcon } from "../customer-grid/icons";
46
  import { BodyPortal, OverlayProvider, useOverlayLayer } from "../customer-grid/OverlaySurface";
47
- import type { Field, FilterTree, GridWorkspace, Measure, Row, SavedView } from "../customer-grid/types";
48
- import { choiceVocabulary, topicForScope, MULTI_VALUE_OPS } from "../customer-grid/types";
49
  import type { WindowSpec } from "../customer-grid/windows";
50
  import { normalizeWindow, WINDOW_KINDS, ENDING_KINDS, ENDING_LABELS, ENDING_STEPS, TO_DATE_KINDS,
51
  endingBounds, endingStepDefault, MAX_N, ANCHOR_VALUE_FREE } from "../customer-grid/windows";
@@ -55,16 +55,16 @@ import type { EndingKind, EndingStep } from "../customer-grid/windows";
55
  // base kit's centred dialog so its condition rows have room, and only the Sheet mounts that
56
  // wrapper. This file therefore stops importing the panel itself.
57
  import { countConditions, isNumericType } from "../filter-kit/ops";
58
- import { SheetFilterPopup } from "../filter-kit/SheetFilterPopup";
59
  import { WindowPicker } from "../filter-kit/WindowPicker";
60
  import { useEscapeClose } from "../ui/useEscapeClose";
61
  import { previewCell, readWorkbook } from "./sheetApi";
62
  import DrillModal from "./DrillModal";
63
  import { formatRef, parseRef } from "./a1";
64
- import { bindingAggregate, bindingDisplay, bindingFilterClauses, bindingOnDrag, bindingPeriod,
65
  PERIOD_UNITS, BINDING_ENDING_STEP, BINDING_PERIOD_STEP,
66
  VIEW_BINDING_TYPES, VIEW_BINDING_LIMIT_DEFAULT, VIEW_BINDING_LIMIT_MAX } from "./types";
67
- import type { BindingAggregate, BindingDragStep, BindingOnDrag, BindingPeriod, PeriodUnit,
68
  ViewBinding, DragAcross as SharedDragAcross } from "./types";
69
  // D-687: the drag arithmetic has ONE owner, and it is the file the drag path itself calls.
70
  import { shiftPeriodStart } from "./sheetState";
@@ -77,11 +77,24 @@ import "../styles/wave59/binding.css";
77
  const BINDING_SECTIONS = [
78
  { key: "data", label: "Data", icon: <MenuIcon name="description" /> },
79
  { key: "rows", label: "Filter", icon: <MenuIcon name="filter" /> },
 
80
  { key: "period", label: "Period", icon: <FieldTypeIcon type="date" size={16} /> },
81
  { key: "copied", label: "When copied", icon: <MenuIcon name="duplicate" /> },
82
  { key: "place", label: "Place", icon: <MenuIcon name="addEnd" /> },
83
  ] as const;
84
 
 
 
 
 
 
 
 
 
 
 
 
 
85
  const clampViewLimit = (value: number): number => Number.isFinite(value)
86
  ? Math.min(VIEW_BINDING_LIMIT_MAX, Math.max(1, Math.trunc(value))) : VIEW_BINDING_LIMIT_DEFAULT;
87
 
@@ -716,6 +729,34 @@ export default function BindingEditor({
716
  const [fields, setFields] = useState<Field[]>([]);
717
  const [linkedOffer, setLinkedOffer] = useState<{ database: string; fields: Field[] }>({ database: "", fields: [] });
718
  const [linkedNotice, setLinkedNotice] = useState("");
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
719
  const filterFields = useMemo(() => [...fields,
720
  ...(linkedOffer.database === database ? linkedOffer.fields : [])], [fields, linkedOffer, database]);
721
  const catalogueDatabase = useRef("");
@@ -1048,6 +1089,61 @@ export default function BindingEditor({
1048
  return () => { live = false; };
1049
  }, [database, rowsWanted]);
1050
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1051
  // The related grid's field wall is checked on the server. Keep its labelled fields in the
1052
  // existing Filter picker only; a customer's amount is not an order aggregate column.
1053
  useEffect(() => {
@@ -1213,6 +1309,8 @@ export default function BindingEditor({
1213
  setField("");
1214
  setViewId("");
1215
  setTree({ conj: "and", nodes: [] });
 
 
1216
  updateCopySteps([]);
1217
  setPeriodOn(chosenIsMetric);
1218
  setPreview("");
@@ -1297,12 +1395,13 @@ export default function BindingEditor({
1297
  };
1298
  return viewBinding;
1299
  }
 
1300
  return out;
1301
  }, [database, sourceKind, metricKey, fn, field, scopeKind, viewId, views, tree, initial,
1302
  unit, start, locked, frozen, frozenFrom, frozenTo, refOpen, periodRef, periodOn, periodMode, windowSpec,
1303
  across, copySteps, copyStepsEdited, savedDrag, chosenIsMetric, hasEnding, ending, endingFixed,
1304
  endingN, endingUnit, endingStep, endingOffset, endingRef,
1305
- shape, viewType, viewFields, viewSort, viewLimit, selectedView, canStepPeriod]);
1306
 
1307
  // Read before either send; the server reads the stored source again independently.
1308
  const prepareBinding = async (): Promise<Record<string, unknown> | null> => {
@@ -1379,11 +1478,13 @@ export default function BindingEditor({
1379
  const periodComplete = (!chosenIsMetric || periodOn)
1380
  && (!periodOn || periodMode !== "calendar" || frozenRangeComplete);
1381
  const copiedComplete = !savedDragDriverMissing;
1382
- const ready = optionsResolved && dataComplete && filterComplete && periodComplete && copiedComplete
 
 
1383
  && (shape === "value" || activeSection === "place");
1384
 
1385
  const sectionComplete = {
1386
- data: dataComplete, rows: filterComplete, period: periodComplete, copied: copiedComplete,
1387
  place: ready,
1388
  };
1389
  const sectionGates = BINDING_SECTIONS.filter(({ key }) => shape === "view" || key !== "place")
@@ -1394,6 +1495,7 @@ export default function BindingEditor({
1394
  reachable: !blocker,
1395
  blockedHint: blocker?.key === "data" ? "Pick a source"
1396
  : blocker?.key === "rows" ? "Pick rows"
 
1397
  : blocker?.key === "period" ? "Set a period"
1398
  : blocker?.key === "copied" ? "Choose a step field" : undefined,
1399
  };
@@ -1405,7 +1507,10 @@ export default function BindingEditor({
1405
  // This shared Next replaces the Metric-only Period shortcut, keeping one forward control per step.
1406
  const renderNext = (section: typeof BINDING_SECTIONS[number]["key"]) => {
1407
  const currentIndex = sectionGates.findIndex(({ key }) => key === section);
1408
- const next = sectionGates.slice(currentIndex + 1).find(({ reachable }) => reachable);
 
 
 
1409
  return (
1410
  <button type="button" className="sheet-action" disabled={!sectionComplete[section] || !next}
1411
  onClick={() => { if (next) setActiveSection(next.key); }}>
@@ -1786,6 +1891,87 @@ export default function BindingEditor({
1786
  {renderNext("rows")}
1787
  </>
1788
  )}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1789
  {activeSection === "period" && (
1790
  <>
1791
  {/* ══ R9: THE PERIOD ══════════════════════════════════════════════════════════════════ */}
 
44
  import { FieldSelectButton } from "../customer-grid/FieldSelect";
45
  import { FieldTypeIcon, MenuIcon } from "../customer-grid/icons";
46
  import { BodyPortal, OverlayProvider, useOverlayLayer } from "../customer-grid/OverlaySurface";
47
+ import type { Field, FilterTree, GridWorkspace, Measure, RelatedEntry, Row, SavedView } from "../customer-grid/types";
48
+ import { choiceVocabulary, relatedEntries, relatedRefusals, topicForScope, MULTI_VALUE_OPS } from "../customer-grid/types";
49
  import type { WindowSpec } from "../customer-grid/windows";
50
  import { normalizeWindow, WINDOW_KINDS, ENDING_KINDS, ENDING_LABELS, ENDING_STEPS, TO_DATE_KINDS,
51
  endingBounds, endingStepDefault, MAX_N, ANCHOR_VALUE_FREE } from "../customer-grid/windows";
 
55
  // base kit's centred dialog so its condition rows have room, and only the Sheet mounts that
56
  // wrapper. This file therefore stops importing the panel itself.
57
  import { countConditions, isNumericType } from "../filter-kit/ops";
58
+ import { filterSentence, SheetFilterPopup } from "../filter-kit/SheetFilterPopup";
59
  import { WindowPicker } from "../filter-kit/WindowPicker";
60
  import { useEscapeClose } from "../ui/useEscapeClose";
61
  import { previewCell, readWorkbook } from "./sheetApi";
62
  import DrillModal from "./DrillModal";
63
  import { formatRef, parseRef } from "./a1";
64
+ import { bindingAggregate, bindingDisplay, bindingFilterClauses, bindingOnDrag, bindingPeriod, bindingRelated,
65
  PERIOD_UNITS, BINDING_ENDING_STEP, BINDING_PERIOD_STEP,
66
  VIEW_BINDING_TYPES, VIEW_BINDING_LIMIT_DEFAULT, VIEW_BINDING_LIMIT_MAX } from "./types";
67
+ import type { BindingAggregate, BindingDragStep, BindingOnDrag, BindingPeriod, BindingRelated, PeriodUnit,
68
  ViewBinding, DragAcross as SharedDragAcross } from "./types";
69
  // D-687: the drag arithmetic has ONE owner, and it is the file the drag path itself calls.
70
  import { shiftPeriodStart } from "./sheetState";
 
77
  const BINDING_SECTIONS = [
78
  { key: "data", label: "Data", icon: <MenuIcon name="description" /> },
79
  { key: "rows", label: "Filter", icon: <MenuIcon name="filter" /> },
80
+ { key: "related", label: "Relationship", icon: <FieldTypeIcon type="link" size={16} /> },
81
  { key: "period", label: "Period", icon: <FieldTypeIcon type="date" size={16} /> },
82
  { key: "copied", label: "When copied", icon: <MenuIcon name="duplicate" /> },
83
  { key: "place", label: "Place", icon: <MenuIcon name="addEnd" /> },
84
  ] as const;
85
 
86
+ /** The permission-scoped server listing is the only source of relationship choices. */
87
+ export function relationshipOffer(databaseLabel: string, body: unknown): {
88
+ entries: RelatedEntry[]; notice: string;
89
+ } {
90
+ const declared = relatedEntries(body);
91
+ const entries = declared.filter((entry) => entry.hops === 1 && entry.path.length === 1 && entry.served);
92
+ const refusal = relatedRefusals(body).find((item) => item.code !== "no_related_rows");
93
+ return { entries, notice: refusal?.message || (entries.length ? "" : declared.length
94
+ ? `${databaseLabel} has no relationship available for this cell.`
95
+ : `${databaseLabel} declares no relationship yet.`) };
96
+ }
97
+
98
  const clampViewLimit = (value: number): number => Number.isFinite(value)
99
  ? Math.min(VIEW_BINDING_LIMIT_MAX, Math.max(1, Math.trunc(value))) : VIEW_BINDING_LIMIT_DEFAULT;
100
 
 
729
  const [fields, setFields] = useState<Field[]>([]);
730
  const [linkedOffer, setLinkedOffer] = useState<{ database: string; fields: Field[] }>({ database: "", fields: [] });
731
  const [linkedNotice, setLinkedNotice] = useState("");
732
+ const [related, setRelated] = useState<BindingRelated | null>(() => bindingRelated(initial));
733
+ const [relationshipListing, setRelationshipListing] = useState<{
734
+ database: string; entries: RelatedEntry[]; notice: string; loaded: boolean; failed?: boolean;
735
+ }>({ database: "", entries: [], notice: "", loaded: false });
736
+ const [relationshipRetry, setRelationshipRetry] = useState(0);
737
+ const [relatedPopupOpen, setRelatedPopupOpen] = useState(false);
738
+ const [relatedWorkspace, setRelatedWorkspace] = useState<{
739
+ target: string; fields: Field[]; users: string[]; notice: string;
740
+ }>({ target: "", fields: [], users: [], notice: "" });
741
+ const [relatedRows, setRelatedRows] = useState<{
742
+ target: string; rows: Row[]; fields: Field[]; users: string[]; notice: string;
743
+ }>({ target: "", rows: [], fields: [], users: [], notice: "" });
744
+ const relationshipEntries = relationshipListing.database === database ? relationshipListing.entries : [];
745
+ const selectedRelationship = relationshipEntries.find((entry) => entry.key === related?.via);
746
+ const relatedTarget = selectedRelationship?.target ?? "";
747
+ const relatedTree: FilterTree = Array.isArray(related?.filter)
748
+ ? { conj: "and", nodes: related.filter as FilterTree["nodes"] }
749
+ : readScope({ filter: related?.filter }).tree;
750
+ const relatedFields = (relatedRows.target === relatedTarget ? relatedRows.fields
751
+ : relatedWorkspace.target === relatedTarget ? relatedWorkspace.fields : []).filter((f) => !isMetricField(f));
752
+ const relatedStatusValues: Record<string, string[]> = {};
753
+ for (const candidate of relatedFields) {
754
+ if (candidate.type === "user") relatedStatusValues[candidate.key] = relatedRows.target === relatedTarget
755
+ ? relatedRows.users : relatedWorkspace.users;
756
+ else if (["select", "multiselect", "status"].includes(candidate.type))
757
+ relatedStatusValues[candidate.key] = choiceVocabulary(candidate,
758
+ relatedRows.target === relatedTarget ? relatedRows.rows : []);
759
+ }
760
  const filterFields = useMemo(() => [...fields,
761
  ...(linkedOffer.database === database ? linkedOffer.fields : [])], [fields, linkedOffer, database]);
762
  const catalogueDatabase = useRef("");
 
1089
  return () => { live = false; };
1090
  }, [database, rowsWanted]);
1091
 
1092
+ // Use depth 1 explicitly: the drawer defaults to two hops, but a cell authors one edge.
1093
+ // Do not use fetchRelated here: it turns network failures into an indistinguishable empty list.
1094
+ useEffect(() => {
1095
+ if (!database || (activeSection !== "related" && !related)) return undefined;
1096
+ const controller = new AbortController();
1097
+ setRelationshipListing({ database, entries: [], notice: "", loaded: false });
1098
+ (async () => {
1099
+ try {
1100
+ const response = await fetch(`${API_V1}/grid/${encodeURIComponent(database)}/related?depth=1`, {
1101
+ credentials: CREDENTIALS, signal: controller.signal,
1102
+ });
1103
+ const body = await response.json().catch(() => null);
1104
+ if (!response.ok || body?.ok === false || !Array.isArray(body?.related))
1105
+ throw new Error(body?.error?.message || "Relationships could not be loaded. Retry to continue.");
1106
+ if (!controller.signal.aborted) setRelationshipListing({ database, loaded: true,
1107
+ ...relationshipOffer(databases.find((item) => item.key === database)?.label || database, body) });
1108
+ } catch (error) {
1109
+ if (!controller.signal.aborted) setRelationshipListing({ database, entries: [], loaded: true, failed: true,
1110
+ notice: error instanceof Error ? error.message : "Relationships could not be loaded. Retry to continue." });
1111
+ }
1112
+ })();
1113
+ return () => controller.abort();
1114
+ }, [database, activeSection === "related" || Boolean(related), relationshipRetry, databases]);
1115
+
1116
+ useEffect(() => {
1117
+ const scope = scopeOf(relatedTarget);
1118
+ if (!scope) return undefined;
1119
+ let live = true;
1120
+ setRelatedWorkspace({ target: "", fields: [], users: [], notice: "" });
1121
+ setRelatedRows({ target: "", rows: [], fields: [], users: [], notice: "" });
1122
+ void fetchWorkspace(scope).then((workspace) => {
1123
+ if (!live) return;
1124
+ const fields = (workspace?.fields ?? []).filter((f) => !isMetricField(f));
1125
+ setRelatedWorkspace({ target: relatedTarget, fields, users: workspace?.userOptions ?? [],
1126
+ notice: !workspace ? "Related fields could not be loaded. Retry to continue."
1127
+ : fields.length ? "" : "This related database has no readable fields." });
1128
+ });
1129
+ return () => { live = false; };
1130
+ }, [relatedTarget, relationshipRetry]);
1131
+
1132
+ // As in Filter, only load the value vocabulary when its dialog is opened.
1133
+ useEffect(() => {
1134
+ const scope = scopeOf(relatedTarget);
1135
+ if (!relatedPopupOpen || !scope) return undefined;
1136
+ let live = true;
1137
+ void fetchTopicRows(topicForScope(scope)).then((payload) => {
1138
+ if (!live) return;
1139
+ setRelatedRows({ target: relatedTarget, rows: payload?.rows ?? [],
1140
+ fields: payload?.fields ?? relatedWorkspace.fields,
1141
+ users: payload?.userOptions ?? relatedWorkspace.users,
1142
+ notice: payload ? "" : "Related field values could not be loaded. Retry to continue." });
1143
+ });
1144
+ return () => { live = false; };
1145
+ }, [relatedTarget, relatedPopupOpen, relatedWorkspace, relationshipRetry]);
1146
+
1147
  // The related grid's field wall is checked on the server. Keep its labelled fields in the
1148
  // existing Filter picker only; a customer's amount is not an order aggregate column.
1149
  useEffect(() => {
 
1309
  setField("");
1310
  setViewId("");
1311
  setTree({ conj: "and", nodes: [] });
1312
+ setRelated(null);
1313
+ setRelatedPopupOpen(false);
1314
  updateCopySteps([]);
1315
  setPeriodOn(chosenIsMetric);
1316
  setPreview("");
 
1395
  };
1396
  return viewBinding;
1397
  }
1398
+ if (related) out.related = related;
1399
  return out;
1400
  }, [database, sourceKind, metricKey, fn, field, scopeKind, viewId, views, tree, initial,
1401
  unit, start, locked, frozen, frozenFrom, frozenTo, refOpen, periodRef, periodOn, periodMode, windowSpec,
1402
  across, copySteps, copyStepsEdited, savedDrag, chosenIsMetric, hasEnding, ending, endingFixed,
1403
  endingN, endingUnit, endingStep, endingOffset, endingRef,
1404
+ shape, viewType, viewFields, viewSort, viewLimit, selectedView, canStepPeriod, related]);
1405
 
1406
  // Read before either send; the server reads the stored source again independently.
1407
  const prepareBinding = async (): Promise<Record<string, unknown> | null> => {
 
1478
  const periodComplete = (!chosenIsMetric || periodOn)
1479
  && (!periodOn || periodMode !== "calendar" || frozenRangeComplete);
1480
  const copiedComplete = !savedDragDriverMissing;
1481
+ // The placed-view cleaner does not carry joins. Require an explicit removal on a shape change.
1482
+ const relatedComplete = shape === "value" || !related;
1483
+ const ready = optionsResolved && dataComplete && filterComplete && relatedComplete && periodComplete && copiedComplete
1484
  && (shape === "value" || activeSection === "place");
1485
 
1486
  const sectionComplete = {
1487
+ data: dataComplete, rows: filterComplete, related: relatedComplete, period: periodComplete, copied: copiedComplete,
1488
  place: ready,
1489
  };
1490
  const sectionGates = BINDING_SECTIONS.filter(({ key }) => shape === "view" || key !== "place")
 
1495
  reachable: !blocker,
1496
  blockedHint: blocker?.key === "data" ? "Pick a source"
1497
  : blocker?.key === "rows" ? "Pick rows"
1498
+ : blocker?.key === "related" ? "Remove the relationship"
1499
  : blocker?.key === "period" ? "Set a period"
1500
  : blocker?.key === "copied" ? "Choose a step field" : undefined,
1501
  };
 
1507
  // This shared Next replaces the Metric-only Period shortcut, keeping one forward control per step.
1508
  const renderNext = (section: typeof BINDING_SECTIONS[number]["key"]) => {
1509
  const currentIndex = sectionGates.findIndex(({ key }) => key === section);
1510
+ // One eligible successor controls both the affordance and the action, including the last step.
1511
+ const next = sectionComplete[section]
1512
+ ? sectionGates.slice(currentIndex + 1).find(({ reachable }) => reachable)
1513
+ : undefined;
1514
  return (
1515
  <button type="button" className="sheet-action" disabled={!sectionComplete[section] || !next}
1516
  onClick={() => { if (next) setActiveSection(next.key); }}>
 
1891
  {renderNext("rows")}
1892
  </>
1893
  )}
1894
+ {activeSection === "related" && (
1895
+ <>
1896
+ <fieldset className="sheet-scope">
1897
+ <legend>Relationship</legend>
1898
+ {shape === "view" ? <>
1899
+ <p className="sheet-period-note">Relationships apply to one value.</p>
1900
+ <button type="button" className="sheet-action"
1901
+ onClick={() => setShape("value")}>Use one value</button>
1902
+ {related && <button type="button" className="sheet-action"
1903
+ onClick={() => { setRelated(null); setPreview(""); }}>Remove relationship</button>}
1904
+ </> : <>
1905
+ {relationshipListing.database !== database || !relationshipListing.loaded ? (
1906
+ <p className="sheet-period-note" role="status">Loading relationships…</p>
1907
+ ) : <>
1908
+ {relationshipListing.notice && <>
1909
+ <p className="sheet-notice" role="status">{relationshipListing.notice}</p>
1910
+ <button type="button" className="sheet-action"
1911
+ onClick={() => relationshipListing.failed
1912
+ ? setRelationshipRetry((value) => value + 1) : setActiveSection("data")}>
1913
+ {relationshipListing.failed ? "Retry" : "Choose database"}
1914
+ </button>
1915
+ </>}
1916
+ {relationshipEntries.length > 0 && (
1917
+ <label className="sheet-field">
1918
+ <span>Related database</span>
1919
+ <select aria-label="Related database" value={selectedRelationship?.key ?? ""}
1920
+ onChange={(event) => {
1921
+ const entry = relationshipEntries.find((item) => item.key === event.target.value);
1922
+ setRelated(entry ? { via: entry.key, filter: { conj: "and", nodes: [] } } : null);
1923
+ setRelatedPopupOpen(false);
1924
+ setPreview("");
1925
+ }}>
1926
+ <option value="">No relationship</option>
1927
+ {relationshipEntries.map((entry) => <option key={entry.key} value={entry.key}>
1928
+ {`${databases.find((item) => item.key === entry.target)?.label || entry.label} (${entry.key})`}
1929
+ </option>)}
1930
+ </select>
1931
+ </label>
1932
+ )}
1933
+ </>}
1934
+ {related && <>
1935
+ <p className="sheet-period-note">{`Relationship: ${related.via}`}</p>
1936
+ <button type="button" className="sheet-action" onClick={() => {
1937
+ setRelated(null); setRelatedPopupOpen(false); setPreview("");
1938
+ }}>Remove relationship</button>
1939
+ {selectedRelationship && <>
1940
+ {relatedWorkspace.target !== relatedTarget
1941
+ ? <p className="sheet-period-note" role="status">Loading related fields…</p>
1942
+ : relatedWorkspace.notice
1943
+ ? <p className="sheet-notice" role="alert">{relatedWorkspace.notice}</p>
1944
+ : null}
1945
+ {relatedRows.target === relatedTarget && relatedRows.notice
1946
+ && <p className="sheet-notice" role="alert">{relatedRows.notice}</p>}
1947
+ {(relatedWorkspace.notice || relatedRows.notice) && <button type="button"
1948
+ className="sheet-action" onClick={() => setRelationshipRetry((value) => value + 1)}>
1949
+ Retry
1950
+ </button>}
1951
+ <button type="button" className="sheet-action" disabled={!relatedFields.length}
1952
+ aria-haspopup="dialog" aria-expanded={relatedPopupOpen}
1953
+ onClick={() => setRelatedPopupOpen(true)}>
1954
+ {countConditions(relatedTree.nodes) ? "Edit related filter" : "Build related filter"}
1955
+ </button>
1956
+ {countConditions(relatedTree.nodes) > 0 && <p className="sheet-period-note">
1957
+ {filterSentence(relatedTree, relatedFields)}
1958
+ </p>}
1959
+ {relatedPopupOpen && <SheetFilterPopup
1960
+ addr={`${addr} through ${selectedRelationship.label}`}
1961
+ fields={relatedFields} filters={relatedTree} statusValues={relatedStatusValues}
1962
+ onChange={(filter) => { setRelated({ via: related.via, filter }); setPreview(""); }}
1963
+ onClose={() => setRelatedPopupOpen(false)} />}
1964
+ </>}
1965
+ {relationshipListing.database === database && relationshipListing.loaded
1966
+ && !selectedRelationship && <p className="sheet-notice" role="alert">
1967
+ This saved relationship is unavailable. Choose another relationship or remove it.
1968
+ </p>}
1969
+ </>}
1970
+ </>}
1971
+ </fieldset>
1972
+ {renderNext("related")}
1973
+ </>
1974
+ )}
1975
  {activeSection === "period" && (
1976
  <>
1977
  {/* ══ R9: THE PERIOD ══════════════════════════════════════════════════════════════════ */}
web/src/sheet/SheetGrid.tsx CHANGED
@@ -148,6 +148,8 @@ import { RulesDialog, ValidationDialog } from "./RulesDialog";
148
  import ChartDialog from "./ChartDialog";
149
  import SheetChartLayer from "./SheetChartLayer";
150
  import SheetViewLayer from "./SheetViewLayer";
 
 
151
  import { copyChartImage } from "./sheetExport";
152
  import { sheetPageGrid } from "./pageViews";
153
  import ShortcutsPanel from "./ShortcutsPanel";
@@ -189,7 +191,7 @@ import {
189
  } from "./types";
190
  import type {
191
  Cell, CellStyle, CellStylePatch, CellValign, SheetChartSpec, SheetRule, SheetTab, SheetTabView,
192
- SheetViewDoor, ViewBinding, ViewRowsAnswer, Workbook,
193
  } from "./types";
194
  import {
195
  addressOf, appendLineBreak, applyStructureWorkbook, autoSumFormula, boundDragLabel, cellAt,
@@ -198,9 +200,9 @@ import {
198
  editableText, fillCells, fillDown, fillRight, findMatches,
199
  isFilled, markOf, noMatchLabel, nothingHiddenLabel, paintPatch, pasteCells,
200
  chartPaneProjections, frozenBandSize, hideColumnByWidth, lastVisibleWidth, lockstepScrollX,
201
- rememberCut, setFormula, shiftCells, splitAddress, styleCells, styleOf, usedExtent,
202
  structureRefusal, viewIndexOf,
203
- visibleIndices, withHidden,
204
  } from "./sheetState";
205
  import type {
206
  CellRange, DragContext, FillEdit, OptionCatalogue, StructureOp,
@@ -678,6 +680,8 @@ export interface SheetGridProps {
678
  * sheet stays open, which is stated in the notice rather than left to be discovered.
679
  */
680
  onHideBands?: (patch: { hiddenRows?: number[]; hiddenCols?: number[] }) => void;
 
 
681
 
682
  // ── W51-T18, contract C2 ───────────────────────────────────────────────────────────────────
683
  /**
@@ -991,12 +995,38 @@ interface FormulaEditState {
991
  rangeAnchor: RealCell | null;
992
  }
993
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
994
  export default function SheetGrid({
995
  workbook: storedWorkbook, tab: storedTab, busy = false, onEdit, onViewRows,
996
  formulaBar, onRefresh, onSaveNow, onOpenImport,
997
  onCommit, openAt, onUndo, onRedo, onNotice, onEvaluateBindings,
998
  onSelect, onStructure, onGrow, onFreeze, onColumnWidth, onRowHeight, onHideBands, onRules, onCharts,
999
- onTabView, onTabVisibility,
1000
  onSelectTab,
1001
  options, viewShadows,
1002
  }: SheetGridProps) {
@@ -1228,18 +1258,23 @@ export default function SheetGrid({
1228
  */
1229
  const bandGridRef = useRef<DataEditorRef | null>(null);
1230
  const frozenBandRef = useRef<HTMLDivElement | null>(null);
1231
- // One post-frame run per spill owner. The callback never queues itself, so this settles after
1232
- // one frame instead of turning text overflow into a permanent canvas animation.
1233
  const spillPaintQueue = useRef(new Map<string, () => void>());
 
1234
  const spillPaintFrame = useRef<number | null>(null);
1235
  // A document render supersedes any not-yet-flushed run. The already-booked frame can collect
1236
  // the new callbacks, but it must never paint an owner from the document it just replaced.
1237
  spillPaintQueue.current.clear();
1238
- const queueSpillPaint = useCallback((key: string, paint: () => void) => {
1239
- spillPaintQueue.current.set(key, paint);
 
1240
  if (spillPaintFrame.current !== null) return;
1241
  spillPaintFrame.current = window.requestAnimationFrame(() => {
1242
  spillPaintFrame.current = null;
 
 
 
1243
  const paints = [...spillPaintQueue.current.values()];
1244
  spillPaintQueue.current.clear();
1245
  for (const run of paints) run();
@@ -1249,6 +1284,7 @@ export default function SheetGrid({
1249
  if (spillPaintFrame.current !== null) window.cancelAnimationFrame(spillPaintFrame.current);
1250
  spillPaintFrame.current = null;
1251
  spillPaintQueue.current.clear();
 
1252
  }, []);
1253
  /** PageUp/PageDown use the body viewport even when the frozen band currently owns focus. */
1254
  const bodyPageRowsRef = useRef(1);
@@ -1495,7 +1531,12 @@ export default function SheetGrid({
1495
  // ⚠ MEMOISED ON A STRING KEY, not on the array. A hidden band is rebuilt on every render (it is
1496
  // read through two `??`s), so an array in the dependency list would be a new object every time
1497
  // and the memo would rebuild a 100,000 entry table per keystroke on a grown sheet.
1498
- const hiddenRowsKey = hiddenRows.join(",");
 
 
 
 
 
1499
  const hiddenColsKey = hiddenCols.join(",");
1500
  const allVisRows = useMemo(
1501
  () => visibleIndices(extent.rows, hiddenRowsKey ? hiddenRowsKey.split(",").map(Number) : []),
@@ -2892,20 +2933,20 @@ export default function SheetGrid({
2892
  const col0 = realCol(Math.min(range.col0, range.col1));
2893
  const col1 = realCol(Math.max(range.col0, range.col1));
2894
  const documentRange = { col0, col1, row0: 0, row1: Math.max(0, extent.rows - 1) };
2895
- return buildCopyPayload(documentRange, cells, (col, row) => addressOf(col, row),
2896
- value => value, value => value, extent);
2897
  }
2898
  if (selection?.rows.length) {
2899
  const row0 = realRow(Math.min(range.row0, range.row1));
2900
  const row1 = realRow(Math.max(range.row0, range.row1));
2901
  const documentRange = { col0: 0, col1: Math.max(0, extent.cols - 1), row0, row1 };
2902
- return buildCopyPayload(documentRange, cells, (col, row) => addressOf(col, row),
2903
- value => value, value => value, extent);
2904
  }
2905
- return buildCopyPayload(range, cells, addrAt, realCol, realRow,
2906
- { cols: visCols.length, rows: bandRows + visRows.length });
2907
  },
2908
- [addrAt, bandRows, cells, extent, realCol, realRow, selection, visCols.length, visRows.length],
2909
  );
2910
 
2911
  /**
@@ -2960,20 +3001,18 @@ export default function SheetGrid({
2960
  (values: readonly (readonly string[])[]): DragContext | undefined => {
2961
  const held = copiedRef.current;
2962
  if (!held) {
2963
- return options || viewShadows ? { catalogue: options, shadows: viewShadows } : undefined;
2964
  }
2965
  const text = values.map((row) => row.join("\t")).join("\n");
2966
  if (text !== held.text) {
2967
- return options || viewShadows
2968
- ? { catalogue: options, shadows: viewShadows }
2969
- : undefined;
2970
  }
2971
  return {
2972
- catalogue: options, shadows: viewShadows,
2973
  cells: held.cells, from: { col: held.col, row: held.row },
2974
  };
2975
  },
2976
- [options, viewShadows],
2977
  );
2978
 
2979
  /**
@@ -2991,7 +3030,9 @@ export default function SheetGrid({
2991
  */
2992
  const isRecognizedCopy = useCallback(
2993
  (text: string): boolean => {
2994
- const held = copiedRef.current;
 
 
2995
  return held !== null && held.text === text;
2996
  },
2997
  [],
@@ -2999,7 +3040,7 @@ export default function SheetGrid({
2999
 
3000
  /** The whole axis behind this clipboard text, when this app is the one that copied it. */
3001
  const copiedAxis = useCallback((text: string): WholeAxis => {
3002
- const held = copiedRef.current;
3003
  if (!held) return null;
3004
  const key = wholeAxisClipboardKey(text);
3005
  // Glide's HTML copy returns editable text; the ribbon returns formatted text. Matching
@@ -3096,14 +3137,17 @@ export default function SheetGrid({
3096
  : undefined);
3097
  // ⛔ A SIZE REFUSAL WRITES NOTHING, so it is said and the door closes before anything is
3098
  // landed or highlighted.
3099
- if (out.sizeRefusal) {
3100
- onNotice(out.sizeRefusal);
3101
  return false;
3102
  }
3103
  // ⛔⛔ W51-T18 / C2 — A PASTE IS ONE OF THE TWO DOORS THAT CAN LAND A VALUE OUTSIDE A CELL'S
3104
  // LIST, and it is the one that gets forgotten because the dropdown looks like the whole
3105
  // feature. The block is screened against the validation the TARGET already carries, the
3106
  // allowed cells land, and every refusal is named in one sentence rather than forty.
 
 
 
3107
  landFill(out, true);
3108
  if (out.tab) {
3109
  if (out.tab.charts !== tab.charts) writeCharts(out.tab.charts ?? []);
@@ -4145,6 +4189,55 @@ export default function SheetGrid({
4145
  onHideBands?.({ hiddenRows: [], hiddenCols: [] });
4146
  }, [hiddenCols.length, hiddenRows.length, onHideBands, onNotice, tab.id]);
4147
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4148
  /** Apply what the row height or column width dialog was given. */
4149
  const applyAsk = useCallback((value: number) => {
4150
  if (!ask) return;
@@ -5371,6 +5464,41 @@ export default function SheetGrid({
5371
  ?? args.theme.bgCell;
5372
  const cell = cells[addrAt(col, row)] ?? null;
5373
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5374
  // ═══════════════════════════════════════════════════════════════════════════════
5375
  // ⭐ WAVE 54 BASE KIT — THE SPARKLINE SEAM, ASKED AS EARLY AS THE SIGNATURE ALLOWS.
5376
  //
@@ -5743,13 +5871,13 @@ export default function SheetGrid({
5743
  // leg reads it as exactly that. Deleting it as dead reds a gate in another ticket's
5744
  // territory for a line that was never wrong, only no longer load bearing.
5745
  return true;
5746
- // ⛔ `gridlinesVisible` IS LAST ON PURPOSE, NOT BY SLOPPINESS. `verify_grid_ux.py` 13468's
5747
  // W62-T02 claim matches `frozenCols, pasteHighlight` as ADJACENT TEXT, so putting this
5748
  // entry in alphabetical order between them reds a leg that owns the spill paint. React
5749
  // does not care what order a dependency array is in; that gate does.
5750
  }, [addrAt, blocksSpill, cellValueGetter, cells, columns, copyMarquee, formulaPointCells, formulaRefCells,
5751
  frozenCols, pasteHighlight, queueSpillPaint, realCol, realRow, rules, spillWidths, tab.name, zoom,
5752
- gridlinesVisible]);
5753
 
5754
  /**
5755
  * ⭐ THE BAND'S PAINT: the SAME callback, told which row it is looking at. `fromBand` is not
@@ -5838,6 +5966,22 @@ export default function SheetGrid({
5838
  );
5839
  const frozenBandHeight = headRows.reduce((height, _, index) => height + frozenRowHeightAt(index), 0);
5840
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5841
  // Match SheetChartLayer's scroll offsets and frozen-pane clipping. Page starts already use
5842
  // document pixels, so only zoom and the shared viewport projection belong in this layer.
5843
  const pageScrollY = useMemo(() => allVisRows.slice(bandRows, bandRows + chartViewport.y)
@@ -5986,6 +6130,9 @@ export default function SheetGrid({
5986
  || !!viewChromeRefusal(cells[formulaBar.props.addr]) })
5987
  : formulaBar}
5988
 
 
 
 
5989
  <div
5990
  className="sheet-grid-canvas"
5991
  onKeyDownCapture={(event) => {
@@ -5997,6 +6144,14 @@ export default function SheetGrid({
5997
  const typing = target instanceof Element
5998
  && !!target.closest('input, textarea, [contenteditable="true"]');
5999
  const held = selectionRef.current;
 
 
 
 
 
 
 
 
6000
  const primary = event.ctrlKey || event.metaKey;
6001
  const copyKey = event.key.toLowerCase();
6002
  // A selection may span both DataEditors. Letting the focused one answer native Copy
@@ -6472,6 +6627,7 @@ export default function SheetGrid({
6472
  />
6473
  ) : null}
6474
  </div>
 
6475
 
6476
  {/* ⭐⭐ THE RIGHT-CLICK MENU, IN THE HOUSE OVERLAY VOCABULARY. `AnchoredOverlay` is what
6477
  every other anchored menu in this app uses, so this one dismisses on an outside click
@@ -6497,6 +6653,16 @@ export default function SheetGrid({
6497
  ⚠ Every item routes to a door that already exists, so no act here opens a second
6498
  save path and none of them re-decides a refusal the page owns. */}
6499
  <div className="cg-type-list">
 
 
 
 
 
 
 
 
 
 
6500
  {menu.on !== "column" && (
6501
  <>
6502
  <button
 
148
  import ChartDialog from "./ChartDialog";
149
  import SheetChartLayer from "./SheetChartLayer";
150
  import SheetViewLayer from "./SheetViewLayer";
151
+ import { IconRowGroup } from "./ribbonIcons";
152
+ import "./rowOutline.css";
153
  import { copyChartImage } from "./sheetExport";
154
  import { sheetPageGrid } from "./pageViews";
155
  import ShortcutsPanel from "./ShortcutsPanel";
 
191
  } from "./types";
192
  import type {
193
  Cell, CellStyle, CellStylePatch, CellValign, SheetChartSpec, SheetRule, SheetTab, SheetTabView,
194
+ SheetViewDoor, SheetRowGroup, ViewBinding, ViewRowsAnswer, Workbook,
195
  } from "./types";
196
  import {
197
  addressOf, appendLineBreak, applyStructureWorkbook, autoSumFormula, boundDragLabel, cellAt,
 
200
  editableText, fillCells, fillDown, fillRight, findMatches,
201
  isFilled, markOf, noMatchLabel, nothingHiddenLabel, paintPatch, pasteCells,
202
  chartPaneProjections, frozenBandSize, hideColumnByWidth, lastVisibleWidth, lockstepScrollX,
203
+ copyCells, recallCopy, rememberCut, setFormula, shiftCells, splitAddress, styleCells, styleOf, usedExtent,
204
  structureRefusal, viewIndexOf,
205
+ visibleIndices, withHidden, outlineHiddenRows, rowGroupRefusal, rowOutlineItems,
206
  } from "./sheetState";
207
  import type {
208
  CellRange, DragContext, FillEdit, OptionCatalogue, StructureOp,
 
680
  * sheet stays open, which is stated in the notice rather than left to be discovered.
681
  */
682
  onHideBands?: (patch: { hiddenRows?: number[]; hiddenCols?: number[] }) => void;
683
+ /** No local fallback: only an editor with the document save door can change an outline. */
684
+ onRowGroups?: (groups: SheetRowGroup[]) => void;
685
 
686
  // ── W51-T18, contract C2 ───────────────────────────────────────────────────────────────────
687
  /**
 
995
  rangeAnchor: RealCell | null;
996
  }
997
 
998
+ /** The gutter belongs to the grid, while the collapse state belongs to the document. */
999
+ export function RowOutline({ items, levels, onToggle }: {
1000
+ items: { group: SheetRowGroup; level: number; top: number; bottom: number }[];
1001
+ levels: number;
1002
+ onToggle?: (id: string) => void;
1003
+ }) {
1004
+ if (levels === 0) return null;
1005
+ return <div className="sheet-row-outline" aria-label="Row groups" style={{ width: levels * 24 }}>
1006
+ {items.map(({ group, level, top, bottom }) => <div key={group.id}
1007
+ className="sheet-row-outline-track" style={{ left: level * 24, top, height: Math.max(24, bottom - top) }}>
1008
+ {!group.collapsed && bottom - top > 24 && <span className="sheet-row-outline-bracket" />}
1009
+ {onToggle ? <button type="button" className="sheet-row-group-toggle"
1010
+ data-row-group={group.id} data-collapsed={group.collapsed}
1011
+ aria-expanded={!group.collapsed}
1012
+ aria-label={`${group.collapsed ? "Expand" : "Collapse"} rows ${group.start} to ${group.end}`}
1013
+ title={`${group.collapsed ? "Expand" : "Collapse"} rows ${group.start} to ${group.end}`}
1014
+ onClick={() => onToggle(group.id)}>
1015
+ <IconRowGroup collapsed={group.collapsed} />
1016
+ </button> : <span className="sheet-row-group-readonly"
1017
+ title={`Rows ${group.start} to ${group.end}: ${group.collapsed ? "collapsed" : "expanded"}. View only.`}>
1018
+ <IconRowGroup collapsed={group.collapsed} />
1019
+ </span>}
1020
+ </div>)}
1021
+ </div>;
1022
+ }
1023
+
1024
  export default function SheetGrid({
1025
  workbook: storedWorkbook, tab: storedTab, busy = false, onEdit, onViewRows,
1026
  formulaBar, onRefresh, onSaveNow, onOpenImport,
1027
  onCommit, openAt, onUndo, onRedo, onNotice, onEvaluateBindings,
1028
  onSelect, onStructure, onGrow, onFreeze, onColumnWidth, onRowHeight, onHideBands, onRules, onCharts,
1029
+ onTabView, onTabVisibility, onRowGroups,
1030
  onSelectTab,
1031
  options, viewShadows,
1032
  }: SheetGridProps) {
 
1258
  */
1259
  const bandGridRef = useRef<DataEditorRef | null>(null);
1260
  const frozenBandRef = useRef<HTMLDivElement | null>(null);
1261
+ // One post-frame pass repairs boundaries, then paints each spill owner. The callback never
1262
+ // queues itself, so this settles after one frame instead of creating a canvas animation.
1263
  const spillPaintQueue = useRef(new Map<string, () => void>());
1264
+ const borderPaintQueue = useRef(new Map<string, () => void>());
1265
  const spillPaintFrame = useRef<number | null>(null);
1266
  // A document render supersedes any not-yet-flushed run. The already-booked frame can collect
1267
  // the new callbacks, but it must never paint an owner from the document it just replaced.
1268
  spillPaintQueue.current.clear();
1269
+ borderPaintQueue.current.clear();
1270
+ const queueSpillPaint = useCallback((key: string, paint: () => void, border = false) => {
1271
+ (border ? borderPaintQueue : spillPaintQueue).current.set(key, paint);
1272
  if (spillPaintFrame.current !== null) return;
1273
  spillPaintFrame.current = window.requestAnimationFrame(() => {
1274
  spillPaintFrame.current = null;
1275
+ const borders = [...borderPaintQueue.current.values()];
1276
+ borderPaintQueue.current.clear();
1277
+ for (const paint of borders) paint();
1278
  const paints = [...spillPaintQueue.current.values()];
1279
  spillPaintQueue.current.clear();
1280
  for (const run of paints) run();
 
1284
  if (spillPaintFrame.current !== null) window.cancelAnimationFrame(spillPaintFrame.current);
1285
  spillPaintFrame.current = null;
1286
  spillPaintQueue.current.clear();
1287
+ borderPaintQueue.current.clear();
1288
  }, []);
1289
  /** PageUp/PageDown use the body viewport even when the frozen band currently owns focus. */
1290
  const bodyPageRowsRef = useRef(1);
 
1531
  // ⚠ MEMOISED ON A STRING KEY, not on the array. A hidden band is rebuilt on every render (it is
1532
  // read through two `??`s), so an array in the dependency list would be a new object every time
1533
  // and the memo would rebuild a 100,000 entry table per keystroke on a grown sheet.
1534
+ const rowGroups = useMemo(() => tab.rowGroups ?? [], [tab.rowGroups]);
1535
+ const effectiveHiddenRows = useMemo(() => outlineHiddenRows(hiddenRows, rowGroups),
1536
+ // Manual membership is value-keyed just like the existing display map.
1537
+ // eslint-disable-next-line react-hooks/exhaustive-deps
1538
+ [hiddenRows.join(","), rowGroups]);
1539
+ const hiddenRowsKey = effectiveHiddenRows.join(",");
1540
  const hiddenColsKey = hiddenCols.join(",");
1541
  const allVisRows = useMemo(
1542
  () => visibleIndices(extent.rows, hiddenRowsKey ? hiddenRowsKey.split(",").map(Number) : []),
 
2933
  const col0 = realCol(Math.min(range.col0, range.col1));
2934
  const col1 = realCol(Math.max(range.col0, range.col1));
2935
  const documentRange = { col0, col1, row0: 0, row1: Math.max(0, extent.rows - 1) };
2936
+ return copyCells(tab, buildCopyPayload(documentRange, cells, (col, row) => addressOf(col, row),
2937
+ value => value, value => value, extent), workbook.id);
2938
  }
2939
  if (selection?.rows.length) {
2940
  const row0 = realRow(Math.min(range.row0, range.row1));
2941
  const row1 = realRow(Math.max(range.row0, range.row1));
2942
  const documentRange = { col0: 0, col1: Math.max(0, extent.cols - 1), row0, row1 };
2943
+ return copyCells(tab, buildCopyPayload(documentRange, cells, (col, row) => addressOf(col, row),
2944
+ value => value, value => value, extent), workbook.id);
2945
  }
2946
+ return copyCells(tab, buildCopyPayload(range, cells, addrAt, realCol, realRow,
2947
+ { cols: visCols.length, rows: bandRows + visRows.length }), workbook.id);
2948
  },
2949
+ [addrAt, bandRows, cells, extent, realCol, realRow, selection, tab, visCols.length, visRows.length, workbook.id],
2950
  );
2951
 
2952
  /**
 
3001
  (values: readonly (readonly string[])[]): DragContext | undefined => {
3002
  const held = copiedRef.current;
3003
  if (!held) {
3004
+ return { catalogue: options, shadows: viewShadows, workbookId: workbook.id };
3005
  }
3006
  const text = values.map((row) => row.join("\t")).join("\n");
3007
  if (text !== held.text) {
3008
+ return { catalogue: options, shadows: viewShadows, workbookId: workbook.id };
 
 
3009
  }
3010
  return {
3011
+ catalogue: options, shadows: viewShadows, workbookId: workbook.id,
3012
  cells: held.cells, from: { col: held.col, row: held.row },
3013
  };
3014
  },
3015
+ [options, viewShadows, workbook.id],
3016
  );
3017
 
3018
  /**
 
3030
  */
3031
  const isRecognizedCopy = useCallback(
3032
  (text: string): boolean => {
3033
+ const recovered = recallCopy(text);
3034
+ // The lookup has already matched either normalized clipboard representation.
3035
+ const held = recovered ? { ...recovered, text } : copiedRef.current;
3036
  return held !== null && held.text === text;
3037
  },
3038
  [],
 
3040
 
3041
  /** The whole axis behind this clipboard text, when this app is the one that copied it. */
3042
  const copiedAxis = useCallback((text: string): WholeAxis => {
3043
+ const held = copiedRef.current ?? recallCopy(text);
3044
  if (!held) return null;
3045
  const key = wholeAxisClipboardKey(text);
3046
  // Glide's HTML copy returns editable text; the ribbon returns formatted text. Matching
 
3137
  : undefined);
3138
  // ⛔ A SIZE REFUSAL WRITES NOTHING, so it is said and the door closes before anything is
3139
  // landed or highlighted.
3140
+ if (out.sizeRefusal || out.layerRefusal) {
3141
+ onNotice(out.sizeRefusal ?? out.layerRefusal ?? "");
3142
  return false;
3143
  }
3144
  // ⛔⛔ W51-T18 / C2 — A PASTE IS ONE OF THE TWO DOORS THAT CAN LAND A VALUE OUTSIDE A CELL'S
3145
  // LIST, and it is the one that gets forgotten because the dropdown looks like the whole
3146
  // feature. The block is screened against the validation the TARGET already carries, the
3147
  // allowed cells land, and every refusal is named in one sentence rather than forty.
3148
+ // ⚠ S65-T07 turned this OFF and it is turned back ON: R12 governs what a pasted cell
3149
+ // CARRIES, never whether a value the target forbids is allowed to land. The one place the
3150
+ // two rules do meet is disclosed on the ticket rather than settled by retiring this one.
3151
  landFill(out, true);
3152
  if (out.tab) {
3153
  if (out.tab.charts !== tab.charts) writeCharts(out.tab.charts ?? []);
 
4189
  onHideBands?.({ hiddenRows: [], hiddenCols: [] });
4190
  }, [hiddenCols.length, hiddenRows.length, onHideBands, onNotice, tab.id]);
4191
 
4192
+ const selectedRowRange = () => {
4193
+ const held = selectionRef.current;
4194
+ const rows = held?.rows.toArray() ?? [];
4195
+ if (rows.length) return { start: realRow(rows[0]) + 1, end: realRow(rows[rows.length - 1]) + 1 };
4196
+ const range = held?.current?.range;
4197
+ return range ? { start: realRow(range.y) + 1, end: realRow(range.y + range.height - 1) + 1 } : null;
4198
+ };
4199
+ const groupRows = () => {
4200
+ if (!onRowGroups || busy) return;
4201
+ const range = selectedRowRange();
4202
+ if (!range) { onNotice("Select a row range first."); return; }
4203
+ const refusal = rowGroupRefusal(rowGroups, range.start, range.end, extent.rows);
4204
+ if (refusal) { onNotice(refusal); return; }
4205
+ onRowGroups([...rowGroups, { id: crypto.randomUUID(), ...range, collapsed: false }]);
4206
+ };
4207
+ const ungroupRows = () => {
4208
+ if (!onRowGroups || busy) return;
4209
+ const range = selectedRowRange();
4210
+ if (!range) return;
4211
+ // Remove the innermost matching group, preserving the other nested levels and manual hides.
4212
+ const found = rowGroups.filter(group => group.start <= range.start && group.end >= range.end)
4213
+ .sort((a, b) => (a.end - a.start) - (b.end - b.start))[0];
4214
+ if (found) onRowGroups(rowGroups.filter(group => group.id !== found.id));
4215
+ else onNotice("Select rows inside a group first.");
4216
+ };
4217
+ const toggleRowGroup = (id: string) => {
4218
+ if (!onRowGroups || busy) return;
4219
+ const next = rowGroups.map(group => group.id === id ? { ...group, collapsed: !group.collapsed } : group);
4220
+ const visible = visibleIndices(extent.rows, outlineHiddenRows(hiddenRows, next));
4221
+ if (visible.length === 0) {
4222
+ onNotice("Leave a row visible outside the group.");
4223
+ return;
4224
+ }
4225
+ setAnchor(null);
4226
+ const current = selectionRef.current?.current?.cell;
4227
+ const real = current ? realRow(current[1]) : 0;
4228
+ const following = visible.findIndex(row => row >= real);
4229
+ const row = (following < 0 ? visible.length - 1 : following) - frozenBandSize(visible, frozenRows);
4230
+ onRowGroups(next);
4231
+ // Reproject after the document commit updates selectionContextRef. A collapsed selection
4232
+ // must not leave the name box/edit door pointing at the hidden cell beside a different row.
4233
+ requestAnimationFrame(() => {
4234
+ selectionIntentRef.current = "app";
4235
+ onSelectionChange({ columns: CompactSelection.empty(), rows: CompactSelection.empty(),
4236
+ current: { cell: [current?.[0] ?? 0, row],
4237
+ range: { x: current?.[0] ?? 0, y: row, width: 1, height: 1 }, rangeStack: [] } });
4238
+ });
4239
+ };
4240
+
4241
  /** Apply what the row height or column width dialog was given. */
4242
  const applyAsk = useCallback((value: number) => {
4243
  if (!ask) return;
 
5464
  ?? args.theme.bgCell;
5465
  const cell = cells[addrAt(col, row)] ?? null;
5466
 
5467
+ // S65-T06: Glide clips shared boundaries during damage paints. Restore them on the same
5468
+ // canvas after that clip is released, ahead of the spill mask. Include the touching edge
5469
+ // of each neighbour: repainting an UNBORDERED cell must not erase its neighbour's border.
5470
+ // Only adjacent projected cells participate; hidden columns use addrAt's existing projection.
5471
+ const ownBorder = cell?.style?.border;
5472
+ const borderAt = (c: number, r: number) => c >= 0 && c < columns.length
5473
+ && r >= -bandRows && r < visRows.length ? cells[addrAt(c, r)]?.style?.border : undefined;
5474
+ const border = {
5475
+ left: ownBorder?.left || borderAt(col - 1, row)?.right,
5476
+ right: ownBorder?.right || borderAt(col + 1, row)?.left,
5477
+ top: ownBorder?.top || borderAt(col, row - 1)?.bottom,
5478
+ bottom: ownBorder?.bottom || borderAt(col, row + 1)?.top,
5479
+ };
5480
+ if (border.left || border.right || border.top || border.bottom) {
5481
+ // Glide reuses its rect object for later cells in the same draw. Snapshot its values,
5482
+ // never the mutable object, for this one pending frame.
5483
+ const borderRect = { ...rect };
5484
+ const transform = ctx.getTransform();
5485
+ const paneLeft = col < frozenCols ? ROW_MARKER_WIDTH : columnX(frozenCols);
5486
+ const paneRight = col < frozenCols ? columnX(frozenCols) + 1
5487
+ : ctx.canvas.width / transform.a;
5488
+ const paneTop = row < 0 || bandRows === 0 ? HEADER_HEIGHT : 0;
5489
+ const paneBottom = ctx.canvas.height / transform.d;
5490
+ queueSpillPaint(`border:${row}:${col}`, () => {
5491
+ ctx.save();
5492
+ ctx.setTransform(transform);
5493
+ ctx.beginPath();
5494
+ ctx.rect(paneLeft, paneTop, Math.max(0, paneRight - paneLeft),
5495
+ Math.max(0, paneBottom - paneTop));
5496
+ ctx.clip();
5497
+ paintCellBorders(ctx, borderRect, border);
5498
+ ctx.restore();
5499
+ }, true);
5500
+ }
5501
+
5502
  // ═══════════════════════════════════════════════════════════════════════════════
5503
  // ⭐ WAVE 54 BASE KIT — THE SPARKLINE SEAM, ASKED AS EARLY AS THE SIGNATURE ALLOWS.
5504
  //
 
5871
  // leg reads it as exactly that. Deleting it as dead reds a gate in another ticket's
5872
  // territory for a line that was never wrong, only no longer load bearing.
5873
  return true;
5874
+ // ⛔ New dependencies stay in the suffix. `verify_grid_ux.py` 13468's
5875
  // W62-T02 claim matches `frozenCols, pasteHighlight` as ADJACENT TEXT, so putting this
5876
  // entry in alphabetical order between them reds a leg that owns the spill paint. React
5877
  // does not care what order a dependency array is in; that gate does.
5878
  }, [addrAt, blocksSpill, cellValueGetter, cells, columns, copyMarquee, formulaPointCells, formulaRefCells,
5879
  frozenCols, pasteHighlight, queueSpillPaint, realCol, realRow, rules, spillWidths, tab.name, zoom,
5880
+ gridlinesVisible, bandRows, columnX, HEADER_HEIGHT, ROW_MARKER_WIDTH, visRows.length]);
5881
 
5882
  /**
5883
  * ⭐ THE BAND'S PAINT: the SAME callback, told which row it is looking at. `fromBand` is not
 
5966
  );
5967
  const frozenBandHeight = headRows.reduce((height, _, index) => height + frozenRowHeightAt(index), 0);
5968
 
5969
+ const outlineItems = useMemo(() => rowOutlineItems(rowGroups, allVisRows), [rowGroups, allVisRows]);
5970
+ const outlineOffsets = useMemo(() => {
5971
+ const offsets = [0];
5972
+ for (let index = 0; rowGroups.length > 0 && index < allVisRows.length; index++)
5973
+ offsets.push(offsets[index] + allRowHeightAt(index));
5974
+ return offsets;
5975
+ }, [allVisRows, allRowHeightAt, rowGroups.length]);
5976
+ const outlineTop = (index: number) => HEADER_HEIGHT + outlineOffsets[index]
5977
+ - (index < bandRows ? 0 : (outlineOffsets[Math.min(allVisRows.length, bandRows + chartViewport.y)]
5978
+ - outlineOffsets[bandRows] - chartViewport.ty));
5979
+ const outlinePaint = outlineItems.map(item => ({ ...item,
5980
+ top: outlineTop(item.index) + Math.max(0, (allRowHeightAt(item.index) - 24) / 2),
5981
+ bottom: outlineTop(item.last) + allRowHeightAt(item.last),
5982
+ })).filter(item => item.top >= (item.index < bandRows ? HEADER_HEIGHT : HEADER_HEIGHT + frozenBandHeight));
5983
+ const outlineLevels = rowGroups.length ? Math.max(1, ...outlineItems.map(item => item.level + 1)) : 0;
5984
+
5985
  // Match SheetChartLayer's scroll offsets and frozen-pane clipping. Page starts already use
5986
  // document pixels, so only zoom and the shared viewport projection belong in this layer.
5987
  const pageScrollY = useMemo(() => allVisRows.slice(bandRows, bandRows + chartViewport.y)
 
6130
  || !!viewChromeRefusal(cells[formulaBar.props.addr]) })
6131
  : formulaBar}
6132
 
6133
+ <div className="sheet-grid-surface">
6134
+ <RowOutline items={outlinePaint} levels={outlineLevels}
6135
+ onToggle={onRowGroups && !busy ? toggleRowGroup : undefined} />
6136
  <div
6137
  className="sheet-grid-canvas"
6138
  onKeyDownCapture={(event) => {
 
6144
  const typing = target instanceof Element
6145
  && !!target.closest('input, textarea, [contenteditable="true"]');
6146
  const held = selectionRef.current;
6147
+ if (!typing && !formulaEdit && event.altKey && event.shiftKey
6148
+ && (event.key === "ArrowRight" || event.key === "ArrowLeft")) {
6149
+ event.preventDefault();
6150
+ event.stopPropagation();
6151
+ if (event.key === "ArrowRight") groupRows();
6152
+ else ungroupRows();
6153
+ return;
6154
+ }
6155
  const primary = event.ctrlKey || event.metaKey;
6156
  const copyKey = event.key.toLowerCase();
6157
  // A selection may span both DataEditors. Letting the focused one answer native Copy
 
6627
  />
6628
  ) : null}
6629
  </div>
6630
+ </div>
6631
 
6632
  {/* ⭐⭐ THE RIGHT-CLICK MENU, IN THE HOUSE OVERLAY VOCABULARY. `AnchoredOverlay` is what
6633
  every other anchored menu in this app uses, so this one dismisses on an outside click
 
6653
  ⚠ Every item routes to a door that already exists, so no act here opens a second
6654
  save path and none of them re-decides a refusal the page owns. */}
6655
  <div className="cg-type-list">
6656
+ {menu.on !== "column" && onRowGroups && <>
6657
+ <button type="button" role="menuitem" className="cg-type-row" disabled={busy}
6658
+ onClick={() => { setMenu(null); groupRows(); }}>
6659
+ <span className="cg-type-label">Group rows</span>
6660
+ </button>
6661
+ {rowGroups.length > 0 && <button type="button" role="menuitem" className="cg-type-row" disabled={busy}
6662
+ onClick={() => { setMenu(null); ungroupRows(); }}>
6663
+ <span className="cg-type-label">Ungroup rows</span>
6664
+ </button>}
6665
+ </>}
6666
  {menu.on !== "column" && (
6667
  <>
6668
  <button
web/src/sheet/SheetPage.tsx CHANGED
@@ -88,11 +88,11 @@ import {
88
  addTab, applyStructure, bandBoundLabel, boundCellsInBand, cellAt,
89
  drillAffordance, emptyHistory, growSheet, moveTab, pushHistory, redoHistory, removeTab,
90
  removeTabRefusal, renameTab, renameTabRefusal, setColumnWidth, setFreeze, setTabView,
91
- setTabVisibility, splitAddress, structureRefusal, tabCellCount, undoHistory, withCells,
92
  } from "./sheetState";
93
  import type { SheetHistory, StructureOp } from "./sheetState";
94
  import { bindingDisplay, emptyIndex, ROOT_FOLDER_ID, sheetExtent, withBindingDisplay } from "./types";
95
- import type { BindingDisplay, Cell, IndexRepair, SheetChartSpec, SheetPrintSettings, SheetRule, SheetTab, SheetTabView, Workbook } from "./types";
96
  import { ChartWorkbookContext } from "./ChartDialog";
97
  import { SheetExportContext } from "./Ribbon";
98
 
@@ -1702,6 +1702,18 @@ export default function SheetPage() {
1702
  : t)));
1703
  }, [commitSheets, openTabId]);
1704
 
 
 
 
 
 
 
 
 
 
 
 
 
1705
  // ── the tab bar (wave-49 R7) ───────────────────────────────────────────────────────────────
1706
 
1707
  const onAddTab = useCallback(() => {
@@ -2965,6 +2977,7 @@ export default function SheetPage() {
2965
  // W50-T17 row reds a ticket this does not own.
2966
  onRules={onRules}
2967
  onHideBands={onHideBands}
 
2968
  // ⭐⭐ W51-T08 / CONTRACT C1 — THE FOUR SEAM PROPS THE RIBBON IS FED THROUGH.
2969
  //
2970
  // ⚠ THEY SIT AFTER `onCommit` AND THAT IS LOAD BEARING, not tidiness. `verify_wiring`'s
 
88
  addTab, applyStructure, bandBoundLabel, boundCellsInBand, cellAt,
89
  drillAffordance, emptyHistory, growSheet, moveTab, pushHistory, redoHistory, removeTab,
90
  removeTabRefusal, renameTab, renameTabRefusal, setColumnWidth, setFreeze, setTabView,
91
+ setTabVisibility, splitAddress, structureRefusal, tabCellCount, undoHistory, withCells, withRowGroupsTab,
92
  } from "./sheetState";
93
  import type { SheetHistory, StructureOp } from "./sheetState";
94
  import { bindingDisplay, emptyIndex, ROOT_FOLDER_ID, sheetExtent, withBindingDisplay } from "./types";
95
+ import type { BindingDisplay, Cell, IndexRepair, SheetChartSpec, SheetPrintSettings, SheetRule, SheetRowGroup, SheetTab, SheetTabView, Workbook } from "./types";
96
  import { ChartWorkbookContext } from "./ChartDialog";
97
  import { SheetExportContext } from "./Ribbon";
98
 
 
1702
  : t)));
1703
  }, [commitSheets, openTabId]);
1704
 
1705
+ // The index carries the server's effective role, including shares and public view access.
1706
+ const outlineRole = (index.workbooks.concat(index.sharedWithMe ?? [])
1707
+ .find(row => row.id === book?.id) as { role?: string } | undefined)?.role;
1708
+ const canEditOutline = outlineRole === "owner" || outlineRole === "editor";
1709
+ const onRowGroups = useCallback((groups: SheetRowGroup[]) => {
1710
+ const base = bookRef.current;
1711
+ if (!base || !canEditOutline) return;
1712
+ const target = openTabId(base);
1713
+ if (!target) return;
1714
+ commitSheets(base.sheets.map(t => t.id === target ? withRowGroupsTab(t, groups) : t));
1715
+ }, [canEditOutline, commitSheets, openTabId]);
1716
+
1717
  // ── the tab bar (wave-49 R7) ───────────────────────────────────────────────────────────────
1718
 
1719
  const onAddTab = useCallback(() => {
 
2977
  // W50-T17 row reds a ticket this does not own.
2978
  onRules={onRules}
2979
  onHideBands={onHideBands}
2980
+ onRowGroups={canEditOutline ? onRowGroups : undefined}
2981
  // ⭐⭐ W51-T08 / CONTRACT C1 — THE FOUR SEAM PROPS THE RIBBON IS FED THROUGH.
2982
  //
2983
  // ⚠ THEY SIT AFTER `onCommit` AND THAT IS LOAD BEARING, not tidiness. `verify_wiring`'s
web/src/sheet/cellBorders.ts CHANGED
@@ -47,26 +47,33 @@ export interface CellBorderRect { x: number; y: number; width: number; height: n
47
  type BorderStrip = CellBorderRect;
48
 
49
  /**
50
- * Turn the current Glide cell rectangle into its four one-pixel inner edge strips.
51
  *
52
- * The cell rectangle is the source on every paint, so fractional scroll positions and browser
53
- * zoom cannot leave a cached border behind. `+ 1` is Glide's first paintable coordinate during a
54
- * damage repaint; the strip starts there and touches the grid line without the half-pixel stroke
55
- * inset that made left/top visibly different from right/bottom. Filled strips avoid antialiasing
56
- * and survive the light grid lines Glide paints after cell content.
 
 
 
 
57
  */
58
  export function cellBorderStrips(rect: CellBorderRect, border: CellBorder): BorderStrip[] {
59
- const left = rect.x + 1;
60
- const top = rect.y + 1;
61
  const right = rect.x + rect.width;
62
  const bottom = rect.y + rect.height;
63
  const width = Math.max(0, right - left);
64
  const height = Math.max(0, bottom - top);
65
  const strips: BorderStrip[] = [];
 
66
  if (border.top && width > 0) strips.push({ x: left, y: top, width, height: 1 });
67
- if (border.right && height > 0) strips.push({ x: right - 1, y: top, width: 1, height });
68
- if (border.bottom && width > 0) strips.push({ x: left, y: bottom - 1, width, height: 1 });
69
  if (border.left && height > 0) strips.push({ x: left, y: top, width: 1, height });
 
 
70
  return strips;
71
  }
72
 
 
47
  type BorderStrip = CellBorderRect;
48
 
49
  /**
50
+ * Turn the current Glide cell rectangle into canonical one-pixel boundary strips.
51
  *
52
+ * A boundary owns the pixel starting at its coordinate: left = x, right = x + width,
53
+ * top = y, bottom = y + height. Horizontal spans are [x, x + width); vertical spans
54
+ * are [y, y + height). Neighbours therefore tile a run and agree on the SAME shared edge.
55
+ * The live rect remains the source on every paint, including scroll and zoom.
56
+ *
57
+ * Glide's damage clip really can start at x + 1 / y + 1, and its column clip excludes
58
+ * the right boundary. SheetGrid restores these strips after Glide releases those clips,
59
+ * before spill masks, with a pane clip instead. Moving a boundary inward is not a clip fix:
60
+ * it creates a different edge for each neighbour. Keep this geometry independent of neighbours.
61
  */
62
  export function cellBorderStrips(rect: CellBorderRect, border: CellBorder): BorderStrip[] {
63
+ const left = rect.x;
64
+ const top = rect.y;
65
  const right = rect.x + rect.width;
66
  const bottom = rect.y + rect.height;
67
  const width = Math.max(0, right - left);
68
  const height = Math.max(0, bottom - top);
69
  const strips: BorderStrip[] = [];
70
+ if (width === 0 || height === 0) return strips;
71
  if (border.top && width > 0) strips.push({ x: left, y: top, width, height: 1 });
72
+ if (border.right && height > 0) strips.push({ x: right, y: top, width: 1, height });
73
+ if (border.bottom && width > 0) strips.push({ x: left, y: bottom, width, height: 1 });
74
  if (border.left && height > 0) strips.push({ x: left, y: top, width: 1, height });
75
+ // Half-open spans tile runs without overlap; close a box's one otherwise-excluded corner.
76
+ if (border.right && border.bottom) strips.push({ x: right, y: bottom, width: 1, height: 1 });
77
  return strips;
78
  }
79
 
web/src/sheet/cellStyleOps.ts CHANGED
@@ -147,6 +147,10 @@ export const clearAll = (
147
  export const styleOf = (cell: Cell | null | undefined): CellStyle | null =>
148
  cell?.style ? { ...cell.style } : null;
149
 
 
 
 
 
150
  /** Replace only a cell's formatting layer, preserving content and every other target layer. */
151
  export const replaceCellStyle = (
152
  cell: Cell | null | undefined,
 
147
  export const styleOf = (cell: Cell | null | undefined): CellStyle | null =>
148
  cell?.style ? { ...cell.style } : null;
149
 
150
+ /** R12: the address is the cell-map key. Copy every payload property, including future ones. */
151
+ export const copyCell = (cell: Cell | null | undefined): Cell | null =>
152
+ cell ? structuredClone(cell) : null;
153
+
154
  /** Replace only a cell's formatting layer, preserving content and every other target layer. */
155
  export const replaceCellStyle = (
156
  cell: Cell | null | undefined,
web/src/sheet/ribbonIcons.tsx CHANGED
@@ -90,6 +90,14 @@ export function IconChartRecommended() {
90
  );
91
  }
92
 
 
 
 
 
 
 
 
 
93
  /** Two handle loops and the crossing blades. */
94
  export function IconCut() {
95
  return (
 
90
  );
91
  }
92
 
93
+ /** Excel's outline toggle in the existing sheet glyph vocabulary. */
94
+ export function IconRowGroup({ collapsed }: { collapsed: boolean }) {
95
+ return <svg viewBox="0 0 16 16" aria-hidden="true" className="sheet-ribbon-icon">
96
+ <rect x="2.5" y="2.5" width="11" height="11" rx="1" />
97
+ <path d={collapsed ? "M5 8h6M8 5v6" : "M5 8h6"} />
98
+ </svg>;
99
+ }
100
+
101
  /** Two handle loops and the crossing blades. */
102
  export function IconCut() {
103
  return (
web/src/sheet/rowOutline.css ADDED
@@ -0,0 +1,46 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ .sheet-grid-surface {
2
+ display: flex;
3
+ flex: 1 1 auto;
4
+ min-height: 0;
5
+ min-width: 0;
6
+ }
7
+ .sheet-grid-surface > .sheet-grid-canvas { min-width: 0; }
8
+ .sheet-row-outline {
9
+ position: relative;
10
+ flex: none;
11
+ overflow: hidden;
12
+ color: var(--lp-purple-deep);
13
+ background: var(--lp-surface-2);
14
+ border-right: 1px solid var(--lp-line);
15
+ }
16
+ .sheet-row-outline-track { position: absolute; width: 24px; }
17
+ .sheet-row-outline-bracket {
18
+ position: absolute;
19
+ top: 24px;
20
+ bottom: 0;
21
+ left: 12px;
22
+ width: 8px;
23
+ border-left: 1px solid var(--lp-purple-deep);
24
+ border-bottom: 1px solid var(--lp-purple-deep);
25
+ }
26
+ .sheet-row-group-toggle {
27
+ border: 0;
28
+ background: transparent;
29
+ font: inherit;
30
+ color: inherit;
31
+ padding: 4px;
32
+ width: 24px;
33
+ height: 24px;
34
+ display: flex;
35
+ align-items: center;
36
+ justify-content: center;
37
+ position: relative;
38
+ border-radius: var(--lp-r-sm);
39
+ cursor: pointer;
40
+ }
41
+ .sheet-row-group-toggle:focus-visible { outline: 2px solid var(--lp-purple-deep); outline-offset: -2px; }
42
+ @media (hover: hover) and (pointer: fine) {
43
+ .sheet-row-group-toggle:hover { background: var(--lp-purple-tint); }
44
+ }
45
+ .sheet-row-group-readonly { display: flex; padding: 4px; }
46
+ .sheet-row-outline .sheet-ribbon-icon { width: 16px; height: 16px; }
web/src/sheet/sheetState.ts CHANGED
@@ -12,11 +12,11 @@
12
 
13
  import type {
14
  BindingOnDrag, BindingPeriod, Cell, CellFormat, CellMap, CellState,
15
- PeriodUnit, Workbook, SheetTab, SheetTabView, SheetChartSpec, StructureOp,
16
  } from "./types";
17
  import {
18
  asNumber, bindingOnDrag, bindingPeriod, BINDING_PERIOD_STEP, BINDING_ENDING_STEP, formatCellText, chartDocumentGeometry, chartRangeAfterStructure,
19
- DEFAULT_COL_WIDTH, MAX_COL_WIDTH, MAX_SHEET_COLS, MAX_SHEET_ROWS, MIN_COL_WIDTH, sheetExtent, viewBlockSize,
20
  } from "./types";
21
  // ⭐ THE ONLY THING THIS FILE BORROWS. `a1.ts` owns Excel's `$` anchoring rule, the quoted-text
22
  // guard and the one reference scanner; `fillCells` and the structural doors below call it rather
@@ -44,9 +44,9 @@ import {
44
  WorkbookCalculation as FormulaCalculation, workbookFormulaGetter,
45
  } from "./formulaEval";
46
  import type { CellValue, QualifiedFormula, SpillChildMarker, FormulaErrorCode } from "./formulaEval";
47
- import { replaceCellStyle } from "./cellStyleOps";
48
  import type { PasteMode } from "./clipboardOps";
49
- import { parseRange, withRuleRange } from "./rules";
50
 
51
  /** Corner marks distinguish database freshness, locally computed formulas (`typed`) and refusals.
52
  * Empty cells and hand typed literals use `none`. */
@@ -967,6 +967,7 @@ export const bindingOptionKey = (database: string, field: string): string =>
967
 
968
  /** What a bulk door needs to know to drag a BOUND cell. Every member is optional by design. */
969
  export interface DragContext {
 
970
  /**
971
  * The field option order. `SheetGrid.tsx` stays schema free, so its page supplies this catalogue.
972
  * When it is absent the filter stays unchanged and {@link boundDragLabel} says why.
@@ -1307,6 +1308,11 @@ export interface CopiedBlock {
1307
  * native Ctrl+C pasting with the destination's own formatting still on it.
1308
  */
1309
  editable?: string;
 
 
 
 
 
1310
  }
1311
 
1312
  /** How many copies the registry remembers. A clipboard holds one; the spare covers a cut. */
@@ -1330,6 +1336,35 @@ const copyRegistry: CopiedBlock[] = [];
1330
  */
1331
  let pendingCut: CopiedBlock | null = null;
1332
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1333
  /**
1334
  * The lookup key: the clipboard text with its line endings normalised and any trailing newline
1335
  * dropped. Windows writes `\r\n` and Excel appends a final newline; neither of those changes
@@ -1366,31 +1401,42 @@ export const rememberCopy = (block: CopiedBlock): void => {
1366
  const held = copyRegistry[i];
1367
  if (held && copyKeys(held).some((key) => keys.includes(key))) copyRegistry.splice(i, 1);
1368
  }
1369
- copyRegistry.unshift(block);
1370
  while (copyRegistry.length > COPY_REGISTRY_LIMIT) copyRegistry.pop();
 
1371
  };
1372
 
1373
  /** The cells behind this clipboard text, when this app is the one that copied them. */
1374
  export const recallCopy = (text: string): CopiedBlock | null => {
 
1375
  const key = clipboardKey(text);
1376
  return copyRegistry.find((held) => copyKeys(held).includes(key)) ?? null;
1377
  };
1378
 
1379
- /** Empty the registry. A proof needs it; nothing in the app has to forget a copy. */
1380
- export const forgetCopies = (): void => { copyRegistry.length = 0; };
 
 
 
 
 
 
1381
 
1382
  /**
1383
  * ⭐⭐ W54-T16 — ARM THE CUT. `clipboardOps.ts::runCopySelection` calls this on a cut whose
1384
  * clipboard write was ACCEPTED, and only then: a browser that refuses the write leaves nothing
1385
  * armed, so nothing is ever deleted with an empty clipboard to paste back from.
1386
  */
1387
- export const rememberCut = (block: CopiedBlock): void => { pendingCut = block; };
 
 
 
1388
 
1389
  /** The cut waiting for its paste, if there is one. Read by proofs; {@link pasteCells} owns it. */
1390
  export const recallCut = (): CopiedBlock | null => pendingCut;
1391
 
1392
  /** Disarm the cut. Called when its paste has landed, and by a proof between cases. */
1393
- export const forgetCut = (): void => { pendingCut = null; };
1394
 
1395
  /**
1396
  * A CHEAP FINGERPRINT OF ONE CELL, which is all the identity guard below needs.
@@ -1451,6 +1497,7 @@ const clearCutSource = (
1451
  const block = pendingCut;
1452
  if (!block) return;
1453
  if (!completesCut(pastedText)) return;
 
1454
  const addrs: string[] = [];
1455
  for (let r = 0; r < block.cells.length; r += 1) {
1456
  const row = block.cells[r] ?? [];
@@ -1466,7 +1513,7 @@ const clearCutSource = (
1466
  if (Object.prototype.hasOwnProperty.call(edits, addr)) continue;
1467
  edits[addr] = null;
1468
  }
1469
- pendingCut = null;
1470
  };
1471
 
1472
  /**
@@ -1488,7 +1535,12 @@ const withSourceStyle = (
1488
  landed: Cell | null,
1489
  copied: Cell | null,
1490
  sourceKnown = true,
1491
- ): Cell | null => sourceKnown ? replaceCellStyle(landed, copied?.style) : landed;
 
 
 
 
 
1492
 
1493
  /** Remove only value/formula/binding content, retaining the target's other cell layers. */
1494
  const withoutValueLayer = (cell: Cell | null | undefined): Cell | null => {
@@ -1523,6 +1575,51 @@ const withValueLayer = (
1523
  return text === "" ? withoutValueLayer(target) : setLiteral(target, text);
1524
  };
1525
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1526
  /**
1527
  * A TSV paste, landed with its top left corner at the target cell.
1528
  *
@@ -1562,7 +1659,7 @@ export const pasteCells = (
1562
  // reaches this door as `[[""]]`, but an empty row says exactly the same thing, and a payload
1563
  // that is genuinely nothing was already refused by the door that read the clipboard. Without
1564
  // this, "paste a blank over twenty cells" would write nothing and say nothing.
1565
- const source = values.length === 0 || values.every((row) => row.length === 0)
1566
  ? ([[""]] as readonly (readonly string[])[])
1567
  : values;
1568
  // ⭐⭐ W54-T15 — WHERE THE SOURCE CELLS COME FROM WHEN THE DOOR THAT PASTED HAS NONE. The
@@ -1576,14 +1673,15 @@ export const pasteCells = (
1576
  const pastedText = source.map((row) => row.join("\t")).join("\n");
1577
  // ⛔⛔ W54-T16 — A CUT IS A MOVE, AND A MOVE SHIFTS NOTHING. Answered ONCE, before any cell is
1578
  // built, because every landing cell in the block has to agree about it.
 
1579
  const moving = mode === "normal" && completesCut(pastedText);
1580
  const cut = moving ? pendingCut : null;
1581
- const recalled = drag?.cells
1582
- ? null
1583
- : recallCopy(pastedText);
1584
  const held = drag?.cells ?? recalled?.cells ?? null;
1585
  const heldFrom = drag?.from ?? (recalled ? { col: recalled.col, row: recalled.row } : null);
1586
  const sourceKnown = held !== null;
 
 
 
1587
  if (mode === "formatting" && !sourceKnown) {
1588
  return {
1589
  edits: {}, ...emptyTally(),
@@ -1605,6 +1703,9 @@ export const pasteCells = (
1605
  // external paste stays verbatim because there is no honest delta to measure.
1606
  const dCol = heldFrom ? (moving ? 0 : originCol - heldFrom.col) : 0;
1607
  const dRow = heldFrom ? (moving ? 0 : originRow - heldFrom.row) : 0;
 
 
 
1608
  for (let r = 0; r < source.length; r += 1) {
1609
  const row = source[r] ?? [];
1610
  for (let c = 0; c < row.length; c += 1) {
@@ -1612,7 +1713,9 @@ export const pasteCells = (
1612
  const rowIndex = originRow + r;
1613
  if (col >= bounds.cols || rowIndex >= bounds.rows) continue;
1614
  const addr = addressOf(col, rowIndex);
1615
- const cell = cellAt(tab, addr);
 
 
1616
  // ⭐⭐ R5 (W52-T09): A BOUND TARGET IS NO LONGER SKIPPED. Landing a plain value on a
1617
  // database-bound cell now clears it and drops its binding through `commitTyped`, exactly
1618
  // as typing over one does — the wall this door once kept is gone (see `BulkEdit`'s note).
@@ -1628,7 +1731,6 @@ export const pasteCells = (
1628
  // the TARGET cell, which is right for a typed edit and wrong for a paste: the
1629
  // destination kept its own fill, borders and number format while the source's were
1630
  // dropped. {@link withSourceStyle} carries the style object across as a whole.
1631
- const copied = held?.[r]?.[c] ?? null;
1632
  if (mode === "formatting") {
1633
  const styled = withSourceStyle(cell, copied, true);
1634
  if (styled !== cell) edits[addr] = styled;
@@ -1683,6 +1785,12 @@ export const pasteCells = (
1683
  if (mode === "normal" && copied && heldFrom && landing.startsWith("=")) {
1684
  landing = moveFormula(landing, dRow, dCol, moving ? "cut" : "copy");
1685
  }
 
 
 
 
 
 
1686
  edits[addr] = withSourceStyle(commitTyped(cell, landing, read), copied, sourceKnown);
1687
  }
1688
  }
@@ -1713,7 +1821,9 @@ export const pasteCells = (
1713
  }
1714
  // C2: a cut follows the FIRST landing block if the selection tiles it. Use its actual offset,
1715
  // not the zero delta that deliberately keeps moved formulas and bindings verbatim above.
1716
- const movedTab = tab && cut && Object.keys(edits).length > 0
 
 
1717
  ? rewriteRangesOnMove(tab, {
1718
  dCol: (anchored ? targetCol : rect.col0) - cut.col,
1719
  dRow: (anchored ? targetRow : rect.row0) - cut.row,
@@ -1722,10 +1832,27 @@ export const pasteCells = (
1722
  col1: cut.col + srcCols - 1, row1: cut.row + srcRows - 1,
1723
  })
1724
  : tab;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1725
  // ⛔ W54-T16: same rule on the tiled path, and after every tile - a cut tiled back over its own
1726
  // rectangle keeps the copies that landed there. A SIZE REFUSAL above wrote nothing and returned
1727
  // before this line, so a refused paste also leaves the cut armed for the paste that works.
1728
- if (mode === "normal") clearCutSource(tab, edits, pastedText);
1729
  return { edits, ...tally, ...(movedTab ? { tab: tabWithEdits(movedTab, edits) } : {}) };
1730
  };
1731
 
@@ -2110,6 +2237,20 @@ export const applyStructure = (
2110
  const chartPatch = charts ? { charts } : {};
2111
  if (tab.id !== tabId) return { ...tab, cells, ...chartPatch };
2112
  const next: SheetTab = { ...tab, cells: moveCells(cells, op), ...chartPatch };
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2113
  const widths = moveColWidths(tab.colWidths, op);
2114
  if (Object.keys(widths).length > 0) next.colWidths = widths;
2115
  else delete next.colWidths;
@@ -2683,6 +2824,68 @@ export const withHiddenTab = (
2683
  return out;
2684
  };
2685
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2686
  /** The sentence Unhide states when there was nothing hidden to bring back. */
2687
  export const nothingHiddenLabel = (): string =>
2688
  "Nothing is hidden on this sheet, so there is nothing to bring back.";
 
12
 
13
  import type {
14
  BindingOnDrag, BindingPeriod, Cell, CellFormat, CellMap, CellState,
15
+ PeriodUnit, Workbook, SheetTab, SheetTabView, SheetChartSpec, SheetRule, SheetRowGroup, StructureOp,
16
  } from "./types";
17
  import {
18
  asNumber, bindingOnDrag, bindingPeriod, BINDING_PERIOD_STEP, BINDING_ENDING_STEP, formatCellText, chartDocumentGeometry, chartRangeAfterStructure,
19
+ DEFAULT_COL_WIDTH, MAX_COL_WIDTH, MAX_SHEET_COLS, MAX_SHEET_ROWS, MAX_SHEET_RULES, MIN_COL_WIDTH, sheetExtent, viewBlockSize,
20
  } from "./types";
21
  // ⭐ THE ONLY THING THIS FILE BORROWS. `a1.ts` owns Excel's `$` anchoring rule, the quoted-text
22
  // guard and the one reference scanner; `fillCells` and the structural doors below call it rather
 
44
  WorkbookCalculation as FormulaCalculation, workbookFormulaGetter,
45
  } from "./formulaEval";
46
  import type { CellValue, QualifiedFormula, SpillChildMarker, FormulaErrorCode } from "./formulaEval";
47
+ import { copyCell, replaceCellStyle } from "./cellStyleOps";
48
  import type { PasteMode } from "./clipboardOps";
49
+ import { newRuleId, parseRange, withRuleRange } from "./rules";
50
 
51
  /** Corner marks distinguish database freshness, locally computed formulas (`typed`) and refusals.
52
  * Empty cells and hand typed literals use `none`. */
 
967
 
968
  /** What a bulk door needs to know to drag a BOUND cell. Every member is optional by design. */
969
  export interface DragContext {
970
+ workbookId?: string;
971
  /**
972
  * The field option order. `SheetGrid.tsx` stays schema free, so its page supplies this catalogue.
973
  * When it is absent the filter stays unchanged and {@link boundDragLabel} says why.
 
1308
  * native Ctrl+C pasting with the destination's own formatting still on it.
1309
  */
1310
  editable?: string;
1311
+ /** S65-T07: tab-owned cell properties travel beside the full cell snapshot. */
1312
+ rules?: readonly SheetRule[];
1313
+ tabId?: string;
1314
+ workbookId?: string;
1315
+ wholeAxis?: "row" | "column" | null;
1316
  }
1317
 
1318
  /** How many copies the registry remembers. A clipboard holds one; the spare covers a cut. */
 
1336
  */
1337
  let pendingCut: CopiedBlock | null = null;
1338
 
1339
+ // Session storage survives reload and workbook navigation without retaining a second document
1340
+ // cache after this browser tab closes. Storage-denied browsers still use the in-memory copy.
1341
+ const COPY_STORAGE_KEY = "loopable.sheet.clipboard.v1";
1342
+ const persistCopies = (): void => {
1343
+ try {
1344
+ sessionStorage.setItem(COPY_STORAGE_KEY, JSON.stringify({ version: 1, copies: copyRegistry, cut: pendingCut }));
1345
+ } catch { /* Clipboard access must still work when browser storage is unavailable. */ }
1346
+ };
1347
+ const restoreCopies = (): void => {
1348
+ if (copyRegistry.length) return;
1349
+ try {
1350
+ const saved = JSON.parse(sessionStorage.getItem(COPY_STORAGE_KEY) ?? "null");
1351
+ const valid = (block: CopiedBlock | null): block is CopiedBlock => !!block
1352
+ && typeof block.text === "string" && Number.isInteger(block.col) && Number.isInteger(block.row)
1353
+ && Array.isArray(block.cells) && block.cells.every(row => Array.isArray(row))
1354
+ && (block.rules === undefined || Array.isArray(block.rules));
1355
+ if (saved?.version !== 1 || !Array.isArray(saved.copies) || !saved.copies.every(valid)) return;
1356
+ copyRegistry.push(...saved.copies.slice(0, COPY_REGISTRY_LIMIT));
1357
+ pendingCut = valid(saved.cut) ? saved.cut : null;
1358
+ } catch { /* A missing or malformed browser snapshot is an ordinary external paste. */ }
1359
+ };
1360
+
1361
+ /** Attach tab-level formatting at the shared copy door, before either copy or cut is armed. */
1362
+ export const copyCells = <T extends CopiedBlock>(tab: SheetTab, block: T, workbookId?: string): T & CopiedBlock => {
1363
+ const snapshot = structuredClone({ ...block, rules: tab.rules ?? [], tabId: tab.id, workbookId });
1364
+ rememberCopy(snapshot);
1365
+ return snapshot;
1366
+ };
1367
+
1368
  /**
1369
  * The lookup key: the clipboard text with its line endings normalised and any trailing newline
1370
  * dropped. Windows writes `\r\n` and Excel appends a final newline; neither of those changes
 
1401
  const held = copyRegistry[i];
1402
  if (held && copyKeys(held).some((key) => keys.includes(key))) copyRegistry.splice(i, 1);
1403
  }
1404
+ copyRegistry.unshift(structuredClone(block));
1405
  while (copyRegistry.length > COPY_REGISTRY_LIMIT) copyRegistry.pop();
1406
+ persistCopies();
1407
  };
1408
 
1409
  /** The cells behind this clipboard text, when this app is the one that copied them. */
1410
  export const recallCopy = (text: string): CopiedBlock | null => {
1411
+ restoreCopies();
1412
  const key = clipboardKey(text);
1413
  return copyRegistry.find((held) => copyKeys(held).includes(key)) ?? null;
1414
  };
1415
 
1416
+ /** Clear memory like a reload; the default also clears storage for a fresh clipboard session. */
1417
+ export const forgetCopies = (reload = false): void => {
1418
+ copyRegistry.length = 0;
1419
+ pendingCut = null;
1420
+ if (!reload) {
1421
+ try { sessionStorage.removeItem(COPY_STORAGE_KEY); } catch { /* No browser storage. */ }
1422
+ }
1423
+ };
1424
 
1425
  /**
1426
  * ⭐⭐ W54-T16 — ARM THE CUT. `clipboardOps.ts::runCopySelection` calls this on a cut whose
1427
  * clipboard write was ACCEPTED, and only then: a browser that refuses the write leaves nothing
1428
  * armed, so nothing is ever deleted with an empty clipboard to paste back from.
1429
  */
1430
+ export const rememberCut = (block: CopiedBlock): void => {
1431
+ pendingCut = structuredClone(block);
1432
+ persistCopies();
1433
+ };
1434
 
1435
  /** The cut waiting for its paste, if there is one. Read by proofs; {@link pasteCells} owns it. */
1436
  export const recallCut = (): CopiedBlock | null => pendingCut;
1437
 
1438
  /** Disarm the cut. Called when its paste has landed, and by a proof between cases. */
1439
+ export const forgetCut = (): void => { pendingCut = null; persistCopies(); };
1440
 
1441
  /**
1442
  * A CHEAP FINGERPRINT OF ONE CELL, which is all the identity guard below needs.
 
1497
  const block = pendingCut;
1498
  if (!block) return;
1499
  if (!completesCut(pastedText)) return;
1500
+ if (block.tabId && block.tabId !== tab?.id) return;
1501
  const addrs: string[] = [];
1502
  for (let r = 0; r < block.cells.length; r += 1) {
1503
  const row = block.cells[r] ?? [];
 
1513
  if (Object.prototype.hasOwnProperty.call(edits, addr)) continue;
1514
  edits[addr] = null;
1515
  }
1516
+ forgetCut();
1517
  };
1518
 
1519
  /**
 
1535
  landed: Cell | null,
1536
  copied: Cell | null,
1537
  sourceKnown = true,
1538
+ ): Cell | null => {
1539
+ // A transformed snapshot already carries its source style. Replacing an identical style
1540
+ // would unnecessarily rewrite formula metadata (or manufacture an empty formulaMeta object).
1541
+ if (!sourceKnown || landed?.style === copied?.style) return landed;
1542
+ return replaceCellStyle(landed, copied?.style);
1543
+ };
1544
 
1545
  /** Remove only value/formula/binding content, retaining the target's other cell layers. */
1546
  const withoutValueLayer = (cell: Cell | null | undefined): Cell | null => {
 
1575
  return text === "" ? withoutValueLayer(target) : setLiteral(target, text);
1576
  };
1577
 
1578
+ const intersectCopyRange = (a: CellRange, b: CellRange): CellRange | null => {
1579
+ const rect = { col0: Math.max(a.col0, b.col0), row0: Math.max(a.row0, b.row0),
1580
+ col1: Math.min(a.col1, b.col1), row1: Math.min(a.row1, b.row1) };
1581
+ return rect.col0 <= rect.col1 && rect.row0 <= rect.row1 ? rect : null;
1582
+ };
1583
+
1584
+ /** Replace rule coverage inside a paste, preserving every part of an old rule outside it. */
1585
+ const withoutRulesIn = (rules: readonly SheetRule[], area: CellRange): SheetRule[] => rules.flatMap(rule => {
1586
+ const range = parseRange(rule.range);
1587
+ const overlap = range && intersectCopyRange(range, area);
1588
+ if (!range || !overlap) return [rule];
1589
+ const pieces = [
1590
+ { ...range, row1: overlap.row0 - 1 },
1591
+ { ...range, row0: overlap.row1 + 1 },
1592
+ { col0: range.col0, col1: overlap.col0 - 1, row0: overlap.row0, row1: overlap.row1 },
1593
+ { col0: overlap.col1 + 1, col1: range.col1, row0: overlap.row0, row1: overlap.row1 },
1594
+ ].filter(part => part.col0 <= part.col1 && part.row0 <= part.row1);
1595
+ return pieces.map((part, index) => {
1596
+ const next = withRuleRange({ ...rule, id: index ? newRuleId() : rule.id }, part);
1597
+ // Formula-rule conditions are relative to the rule's top-left cell, even after a split.
1598
+ return rule.kind === "formula" && typeof rule.value === "string"
1599
+ ? { ...next, value: moveFormula(rule.value, part.row0 - range.row0, part.col0 - range.col0, "copy") }
1600
+ : next;
1601
+ });
1602
+ });
1603
+
1604
+ /** Snapshot whole rule objects; only their identity and covered addresses belong to the target. */
1605
+ const copiedRulesAt = (
1606
+ block: CopiedBlock, source: CellRange, destination: CellRange,
1607
+ ): SheetRule[] => (block.rules ?? []).flatMap(rule => {
1608
+ const range = parseRange(rule.range);
1609
+ const part = range && intersectCopyRange(range, source);
1610
+ if (!range || !part) return [];
1611
+ const dCol = destination.col0 - source.col0;
1612
+ const dRow = destination.row0 - source.row0;
1613
+ const landed = intersectCopyRange({ col0: part.col0 + dCol, col1: part.col1 + dCol,
1614
+ row0: part.row0 + dRow, row1: part.row1 + dRow }, destination);
1615
+ if (!landed) return [];
1616
+ const next = withRuleRange({ ...structuredClone(rule), id: newRuleId() }, landed);
1617
+ return [rule.kind === "formula" && typeof rule.value === "string"
1618
+ ? { ...next, value: moveFormula(rule.value, part.row0 - range.row0 + dRow,
1619
+ part.col0 - range.col0 + dCol, "copy") }
1620
+ : next];
1621
+ });
1622
+
1623
  /**
1624
  * A TSV paste, landed with its top left corner at the target cell.
1625
  *
 
1659
  // reaches this door as `[[""]]`, but an empty row says exactly the same thing, and a payload
1660
  // that is genuinely nothing was already refused by the door that read the clipboard. Without
1661
  // this, "paste a blank over twenty cells" would write nothing and say nothing.
1662
+ let source = values.length === 0 || values.every((row) => row.length === 0)
1663
  ? ([[""]] as readonly (readonly string[])[])
1664
  : values;
1665
  // ⭐⭐ W54-T15 — WHERE THE SOURCE CELLS COME FROM WHEN THE DOOR THAT PASTED HAS NONE. The
 
1673
  const pastedText = source.map((row) => row.join("\t")).join("\n");
1674
  // ⛔⛔ W54-T16 — A CUT IS A MOVE, AND A MOVE SHIFTS NOTHING. Answered ONCE, before any cell is
1675
  // built, because every landing cell in the block has to agree about it.
1676
+ const recalled = recallCopy(pastedText);
1677
  const moving = mode === "normal" && completesCut(pastedText);
1678
  const cut = moving ? pendingCut : null;
 
 
 
1679
  const held = drag?.cells ?? recalled?.cells ?? null;
1680
  const heldFrom = drag?.from ?? (recalled ? { col: recalled.col, row: recalled.row } : null);
1681
  const sourceKnown = held !== null;
1682
+ // TSV readers trim trailing blank rows. The snapshot retains the actual copied rectangle.
1683
+ if (held) source = held.map(row => row.map(cell => editableText(cell)));
1684
+ const landedRanges: CellRange[] = [];
1685
  if (mode === "formatting" && !sourceKnown) {
1686
  return {
1687
  edits: {}, ...emptyTally(),
 
1703
  // external paste stays verbatim because there is no honest delta to measure.
1704
  const dCol = heldFrom ? (moving ? 0 : originCol - heldFrom.col) : 0;
1705
  const dRow = heldFrom ? (moving ? 0 : originRow - heldFrom.row) : 0;
1706
+ landedRanges.push({ col0: originCol, row0: originRow,
1707
+ col1: Math.min(bounds.cols - 1, originCol + Math.max(...source.map(row => row.length)) - 1),
1708
+ row1: Math.min(bounds.rows - 1, originRow + source.length - 1) });
1709
  for (let r = 0; r < source.length; r += 1) {
1710
  const row = source[r] ?? [];
1711
  for (let c = 0; c < row.length; c += 1) {
 
1713
  const rowIndex = originRow + r;
1714
  if (col >= bounds.cols || rowIndex >= bounds.rows) continue;
1715
  const addr = addressOf(col, rowIndex);
1716
+ const copied = copyCell(held?.[r]?.[c]);
1717
+ // R12: transform the complete source snapshot, never inherit destination metadata.
1718
+ const cell = mode === "normal" && sourceKnown ? copied : cellAt(tab, addr);
1719
  // ⭐⭐ R5 (W52-T09): A BOUND TARGET IS NO LONGER SKIPPED. Landing a plain value on a
1720
  // database-bound cell now clears it and drops its binding through `commitTyped`, exactly
1721
  // as typing over one does — the wall this door once kept is gone (see `BulkEdit`'s note).
 
1731
  // the TARGET cell, which is right for a typed edit and wrong for a paste: the
1732
  // destination kept its own fill, borders and number format while the source's were
1733
  // dropped. {@link withSourceStyle} carries the style object across as a whole.
 
1734
  if (mode === "formatting") {
1735
  const styled = withSourceStyle(cell, copied, true);
1736
  if (styled !== cell) edits[addr] = styled;
 
1785
  if (mode === "normal" && copied && heldFrom && landing.startsWith("=")) {
1786
  landing = moveFormula(landing, dRow, dCol, moving ? "cut" : "copy");
1787
  }
1788
+ // Literal and empty payloads have no location-dependent content to recompute. Keep
1789
+ // their exact value type, display and every metadata property, including future ones.
1790
+ if (sourceKnown && (!copied || copied.kind === "literal" || copied.kind === "empty")) {
1791
+ edits[addr] = withSourceStyle(copied, copied, sourceKnown);
1792
+ continue;
1793
+ }
1794
  edits[addr] = withSourceStyle(commitTyped(cell, landing, read), copied, sourceKnown);
1795
  }
1796
  }
 
1821
  }
1822
  // C2: a cut follows the FIRST landing block if the selection tiles it. Use its actual offset,
1823
  // not the zero delta that deliberately keeps moved formulas and bindings verbatim above.
1824
+ const sameCutTab = cut && (!cut.tabId || cut.tabId === tab?.id)
1825
+ && (!cut.workbookId || cut.workbookId === drag?.workbookId);
1826
+ let movedTab = tab && cut && sameCutTab && Object.keys(edits).length > 0
1827
  ? rewriteRangesOnMove(tab, {
1828
  dCol: (anchored ? targetCol : rect.col0) - cut.col,
1829
  dRow: (anchored ? targetRow : rect.row0) - cut.row,
 
1832
  col1: cut.col + srcCols - 1, row1: cut.row + srcRows - 1,
1833
  })
1834
  : tab;
1835
+ if (movedTab && sourceKnown && mode !== "values" && heldFrom && recalled?.rules) {
1836
+ const sourceRect = { col0: heldFrom.col, row0: heldFrom.row,
1837
+ col1: heldFrom.col + srcCols - 1, row1: heldFrom.row + srcRows - 1 };
1838
+ const movedIds = new Set(sameCutTab ? (tab?.rules ?? []).filter(rule => {
1839
+ const range = parseRange(rule.range);
1840
+ return range && intersectCopyRange(range, sourceRect);
1841
+ }).map(rule => rule.id) : []);
1842
+ let rules = (movedTab.rules ?? []).filter(rule => !movedIds.has(rule.id));
1843
+ for (const destination of landedRanges) rules = withoutRulesIn(rules, destination);
1844
+ const carried = landedRanges.flatMap((destination, index) => sameCutTab && index === 0
1845
+ ? (movedTab?.rules ?? []).filter(rule => movedIds.has(rule.id))
1846
+ : copiedRulesAt(recalled, sourceRect, destination));
1847
+ rules.push(...carried);
1848
+ if (rules.length > MAX_SHEET_RULES) return { edits: {}, ...emptyTally(),
1849
+ layerRefusal: `This paste would exceed the sheet's ${MAX_SHEET_RULES} conditional formatting rules.` };
1850
+ movedTab = { ...movedTab, rules };
1851
+ }
1852
  // ⛔ W54-T16: same rule on the tiled path, and after every tile - a cut tiled back over its own
1853
  // rectangle keeps the copies that landed there. A SIZE REFUSAL above wrote nothing and returned
1854
  // before this line, so a refused paste also leaves the cut armed for the paste that works.
1855
+ if (mode === "normal" && sameCutTab) clearCutSource(tab, edits, pastedText);
1856
  return { edits, ...tally, ...(movedTab ? { tab: tabWithEdits(movedTab, edits) } : {}) };
1857
  };
1858
 
 
2237
  const chartPatch = charts ? { charts } : {};
2238
  if (tab.id !== tabId) return { ...tab, cells, ...chartPatch };
2239
  const next: SheetTab = { ...tab, cells: moveCells(cells, op), ...chartPatch };
2240
+ if (op.axis === "row" && tab.rowGroups) {
2241
+ const groups = tab.rowGroups.flatMap(group => {
2242
+ const first = op.delta < 0 && group.start >= op.at
2243
+ ? Math.max(group.start, op.at - op.delta) : group.start;
2244
+ const last = op.delta < 0 && group.end < op.at - op.delta
2245
+ ? Math.min(group.end, op.at - 1) : group.end;
2246
+ if (first > last) return [];
2247
+ const start = movedIndex(first, op.at, op.delta);
2248
+ const end = movedIndex(last, op.at, op.delta);
2249
+ return start === null || end === null ? [] : [{ ...group, start, end }];
2250
+ });
2251
+ if (groups.length) next.rowGroups = groups;
2252
+ else delete next.rowGroups;
2253
+ }
2254
  const widths = moveColWidths(tab.colWidths, op);
2255
  if (Object.keys(widths).length > 0) next.colWidths = widths;
2256
  else delete next.colWidths;
 
2824
  return out;
2825
  };
2826
 
2827
+ /** Collapse owns only rowGroups. Manual Unhide cannot expand an outline, or vice versa. */
2828
+ export const outlineHiddenRows = (
2829
+ hidden: readonly number[], groups: readonly SheetRowGroup[],
2830
+ ): number[] => {
2831
+ const gone = new Set(hidden);
2832
+ for (const group of groups) if (group.collapsed) {
2833
+ for (let row = group.start; row <= group.end; row++) gone.add(row);
2834
+ }
2835
+ return [...gone].sort((a, b) => a - b);
2836
+ };
2837
+
2838
+ export const withRowGroupsTab = (tab: SheetTab, groups: SheetRowGroup[]): SheetTab => {
2839
+ const out = { ...tab };
2840
+ if (groups.length) out.rowGroups = groups;
2841
+ else delete out.rowGroups;
2842
+ return out;
2843
+ };
2844
+
2845
+ /** Nesting is allowed; partial overlaps and duplicate ranges have no unambiguous outline. */
2846
+ export const rowGroupRefusal = (
2847
+ groups: readonly SheetRowGroup[], start: number, end: number, rows: number,
2848
+ ): string | null => {
2849
+ if (!Number.isInteger(start) || !Number.isInteger(end) || start < 1 || end < start || end > rows)
2850
+ return "Select a row range first.";
2851
+ if (start === 1 && end === rows) return "Leave a row outside the group.";
2852
+ for (const group of groups) {
2853
+ if (start === group.start && end === group.end) return "These rows are already grouped.";
2854
+ const disjoint = end < group.start || start > group.end;
2855
+ const nested = (start >= group.start && end <= group.end)
2856
+ || (start <= group.start && end >= group.end);
2857
+ if (!disjoint && !nested) return "Groups can be nested, but cannot partially overlap.";
2858
+ }
2859
+ return null;
2860
+ };
2861
+
2862
+ /** Controls use the same flat display map as Glide, including manual hides and frozen rows. */
2863
+ export const rowOutlineItems = (groups: readonly SheetRowGroup[], visible: readonly number[]) => {
2864
+ const ordered = [...groups].sort((a, b) => a.start - b.start || b.end - a.end);
2865
+ const items: { group: SheetRowGroup; index: number; last: number; level: number }[] = [];
2866
+ const lowerBound = (row: number) => {
2867
+ let low = 0, high = visible.length;
2868
+ while (low < high) {
2869
+ const mid = Math.floor((low + high) / 2);
2870
+ if (visible[mid] < row) low = mid + 1;
2871
+ else high = mid;
2872
+ }
2873
+ return low;
2874
+ };
2875
+ for (const group of ordered) {
2876
+ const parents = ordered.filter(parent => parent.id !== group.id
2877
+ && parent.start <= group.start && parent.end >= group.end);
2878
+ if (parents.some(parent => parent.collapsed) || visible.length === 0) continue;
2879
+ const index = Math.min(visible.length - 1, lowerBound(group.start - 1));
2880
+ const last = group.collapsed ? index : Math.max(index, lowerBound(group.end) - 1);
2881
+ let level = parents.length;
2882
+ // Adjacent collapsed groups can share an anchor row. Give each its own clickable track.
2883
+ while (items.some(item => item.level === level && item.index <= last && item.last >= index)) level++;
2884
+ items.push({ group, index, last, level });
2885
+ }
2886
+ return items;
2887
+ };
2888
+
2889
  /** The sentence Unhide states when there was nothing hidden to bring back. */
2890
  export const nothingHiddenLabel = (): string =>
2891
  "Nothing is hidden on this sheet, so there is nothing to bring back.";
web/src/sheet/types.ts CHANGED
@@ -74,6 +74,20 @@ export interface CellSource {
74
  */
75
  export type CellBinding = Record<string, unknown>;
76
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
77
  // W62 C2: platform/core/sheets.py carries the same three constants; a gate checks the pair.
78
  export const VIEW_BINDING_TYPES = [
79
  "grid", "kanban", "map", "gallery", "timeline", "list", "calendar", "catalog", "swipe",
@@ -1273,6 +1287,14 @@ export interface SheetViewDoor {
1273
  onTabVisibility: (tabId: string, visibility: "visible" | "hidden") => void;
1274
  }
1275
 
 
 
 
 
 
 
 
 
1276
  export interface SheetTab {
1277
  id: string;
1278
  name: string;
@@ -1300,6 +1322,8 @@ export interface SheetTab {
1300
  // ── W51, contract C2: the sheet-level slots the ribbon's Cells and Styles groups need ──────
1301
  /** C2: conditional formatting, at most {@link MAX_SHEET_RULES}. The editor is W51-T18's. */
1302
  rules?: SheetRule[];
 
 
1303
  /**
1304
  * ⛔ C2: the 1 BASED rows this sheet hides, and 1 based is not a detail. Every other index in
1305
  * this module that reaches glide is zero based, so the two are told apart by their name and by
 
74
  */
75
  export type CellBinding = Record<string, unknown>;
76
 
77
+ /** C1: one declared edge; the server owns the filter's interior, as it does CellBinding. */
78
+ export interface BindingRelated {
79
+ via: string;
80
+ filter: unknown;
81
+ }
82
+
83
+ /** Keep a saved relationship intact until its filter is actually edited. */
84
+ export const bindingRelated = (binding?: CellBinding | null): BindingRelated | null => {
85
+ const related = asRecord(binding?.related);
86
+ return related && Object.keys(related).length === 2
87
+ && typeof related.via === "string" && related.via.trim() && "filter" in related
88
+ ? related as unknown as BindingRelated : null;
89
+ };
90
+
91
  // W62 C2: platform/core/sheets.py carries the same three constants; a gate checks the pair.
92
  export const VIEW_BINDING_TYPES = [
93
  "grid", "kanban", "map", "gallery", "timeline", "list", "calendar", "catalog", "swipe",
 
1287
  onTabVisibility: (tabId: string, visibility: "visible" | "hidden") => void;
1288
  }
1289
 
1290
+ /** A document-owned outline. Row endpoints are inclusive, 1-based sheet coordinates. */
1291
+ export interface SheetRowGroup {
1292
+ id: string;
1293
+ start: number;
1294
+ end: number;
1295
+ collapsed: boolean;
1296
+ }
1297
+
1298
  export interface SheetTab {
1299
  id: string;
1300
  name: string;
 
1322
  // ── W51, contract C2: the sheet-level slots the ribbon's Cells and Styles groups need ──────
1323
  /** C2: conditional formatting, at most {@link MAX_SHEET_RULES}. The editor is W51-T18's. */
1324
  rules?: SheetRule[];
1325
+ /** Independent of manual hiddenRows; an empty outline is stored as an absence. */
1326
+ rowGroups?: SheetRowGroup[];
1327
  /**
1328
  * ⛔ C2: the 1 BASED rows this sheet hides, and 1 based is not a detail. Every other index in
1329
  * this module that reaches glide is zero based, so the two are told apart by their name and by
web/src/shell/Shell.tsx CHANGED
@@ -113,8 +113,6 @@ import type { TemplateModule } from "../sheet/templates/templatesApi";
113
  /* ⭐ W35-T09 — the assistant's EXISTING door for opening an AI-built view: hash + a retry
114
  ladder, returning a canceller. A second emit here would be a second answer. */
115
  import { openBuiltView } from "../assistant/AssistantPage";
116
- import { financeNavigation } from "../home/homeModel";
117
- import type { NavigationApplication } from "../home/homeModel";
118
  const HomePage = lazy(() => import("../home/HomePage"));
119
  const SheetGalleryPage = lazy(() =>
120
  import("../home/HomePage").then((m) => ({ default: m.SheetGalleryPage })));
@@ -166,8 +164,9 @@ import FormPublic from "../forms/FormPublic";
166
  // paints, to save a signed-in user bytes they have already paid for. The page imports nothing
167
  // from `customer-grid/**`, so it drags no spreadsheet engine along with it.
168
  import PublishedView from "../publish/PublishedView";
169
- import { mergeRecents } from "../home/homeModel";
170
  import type { AutomationTile } from "../home/homeModel";
 
171
  // ⭐ WAVE 24 item 13 (R10, wiring W24-W3) — Home's Automations section.
172
  // ⚠ WAVE 26 ITEM 18 (R14): `stateOf` came out of this import with Home's status dot. The old note
173
  // here said it was imported rather than re-derived because it is the ONE place "is this running"
@@ -256,7 +255,21 @@ function boardedFor(
256
  function Lazily({ children, surface }: { children: ReactNode; surface: string }) {
257
  return (
258
  <ErrorBoundary surface={surface}>
259
- <Suspense fallback={null}>{children}</Suspense>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
260
  </ErrorBoundary>
261
  );
262
  }
@@ -896,6 +909,10 @@ type Nav =
896
  }
897
  | { phase: "error"; timedOut?: boolean; malformed?: boolean };
898
 
 
 
 
 
899
  const NO_UTILITY: NavPage[] = [];
900
  /** Stable identity, like `NO_ENTRIES` — a fresh `[]` per render would re-run Home's memo. */
901
  const NO_RECENTS: Recent[] = [];
@@ -970,8 +987,8 @@ const findAutomation = (entries: NavEntry[]) =>
970
  * `degraded` are UNCHANGED: they draw the real rows with their unavailable arms, because there
971
  * the answer has arrived and is bad news, which is a fact worth showing rather than a wait.
972
  *
973
- * ⚠ The count is the rail's own maximum, not a guess. WAVE 63's expanded Finance group adds one
974
- * header plus six application rows to the nine-row settled chrome, so it is **16**.
975
  * ⛔ KEEP THIS NUMBER >= THE SETTLED ROW COUNT AND NEVER BELOW IT. A skeleton one bar TALLER than
976
  * the settled rail is a shrink, which is fine; one bar SHORTER is the appear-from-nowhere shove
977
  * W33-T22 was written about, arriving by a different door. The two `.shell-nav-sep` hairlines are
@@ -1609,11 +1626,6 @@ type NavFold = "0" | "1" | "auto";
1609
  /** The one key both halves of the fold read and write. */
1610
  const NAV_FOLD_KEY = "aios-nav-collapsed";
1611
 
1612
- type FinanceNavState =
1613
- | { phase: "idle" | "loading" }
1614
- | { phase: "error"; message: string }
1615
- | { phase: "ready"; applications: NavigationApplication[] };
1616
-
1617
  /**
1618
  * ⭐⭐ WAVE 53 · T32 (ruling R1) — WHO FOLDED THE RAIL, not merely whether it is folded.
1619
  *
@@ -1645,6 +1657,8 @@ function readNavFold(): NavFold {
1645
  function ShellFrame() {
1646
  const [session, setSession] = useState<Session>({ phase: "checking" });
1647
  const [nav, setNav] = useState<Nav>({ phase: "idle" });
 
 
1648
  // Wave 18 (C3-UT): bumped after "+ New database" so the rail refetches and the new ut_ key
1649
  // appears without a reload. Rename, create and delete paths share the same bumper: the
1650
  // authoritative answer lives in the SERVER's nav payload, so the rail re-asks rather than
@@ -1655,8 +1669,6 @@ function ShellFrame() {
1655
  const navRequestEpoch = useRef(0);
1656
  const [applicationsEpoch, setApplicationsEpoch] = useState(0);
1657
  const applicationCheckEpoch = useRef(0);
1658
- const [financeNav, setFinanceNav] = useState<FinanceNavState>({ phase: "idle" });
1659
- const financeRequestEpoch = useRef(0);
1660
  const [dataError, setDataError] = useState("");
1661
  const [toast, setToast] = useState("");
1662
  // `null` = closed. The SECTION is the open state, so "Settings" and
@@ -2095,6 +2107,7 @@ function ShellFrame() {
2095
  useEffect(() => {
2096
  const refresh = () => {
2097
  applicationCheckEpoch.current += 1;
 
2098
  setApplicationsEpoch((epoch) => epoch + 1);
2099
  };
2100
  const changed = (event: Event) => {
@@ -2140,37 +2153,6 @@ function ShellFrame() {
2140
  return () => controller.abort();
2141
  }, [who, dataPath?.database, dataPath?.application, applicationsEpoch, leaveDeletedApplication]);
2142
 
2143
- useEffect(() => {
2144
- const requestEpoch = ++financeRequestEpoch.current;
2145
- if (!who) {
2146
- setFinanceNav({ phase: "idle" });
2147
- return;
2148
- }
2149
- const controller = new AbortController();
2150
- setFinanceNav((current) => current.phase === "ready" ? current : { phase: "loading" });
2151
- void fetch(`${API_V1}/nav/applications`, { credentials: CREDENTIALS, signal: controller.signal })
2152
- .then(async (applicationsResponse) => {
2153
- const applicationsBody = await applicationsResponse.json();
2154
- if (!applicationsResponse.ok) {
2155
- throw new Error(applicationsBody?.detail?.error?.message || "Finance applications could not be loaded.");
2156
- }
2157
- if (!Array.isArray(applicationsBody?.applications)) {
2158
- throw new Error("Finance applications could not be read.");
2159
- }
2160
- if (!controller.signal.aborted && requestEpoch === financeRequestEpoch.current) {
2161
- setFinanceNav({ phase: "ready", applications: financeNavigation(applicationsBody.applications) });
2162
- }
2163
- }).catch((error: unknown) => {
2164
- if (!controller.signal.aborted && requestEpoch === financeRequestEpoch.current) {
2165
- setFinanceNav((current) => current.phase === "ready" ? current : {
2166
- phase: "error",
2167
- message: error instanceof Error ? error.message : "Finance navigation could not be loaded.",
2168
- });
2169
- }
2170
- });
2171
- return () => controller.abort();
2172
- }, [who, applicationsEpoch]);
2173
-
2174
  useEffect(() => {
2175
  const onWorkspaceStale = () => {
2176
  // W63-T29: connector creation/enablement/removal changes both membership and the rows a
@@ -2180,6 +2162,7 @@ function ShellFrame() {
2180
  setDataError("");
2181
  // Invalidate immediately: an older response can resolve before the next effect cleans up.
2182
  navRequestEpoch.current += 1;
 
2183
  setNavEpoch((epoch) => epoch + 1);
2184
  };
2185
  window.addEventListener(WORKSPACE_STALE_EVENT, onWorkspaceStale);
@@ -2242,6 +2225,37 @@ function ShellFrame() {
2242
  };
2243
  }, [who, navEpoch]);
2244
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2245
  /**
2246
  * ⭐⭐ W33-T22 — RECORD THE RAIL THE PAYLOAD JUST DESCRIBED, for the next first paint.
2247
  *
@@ -3055,8 +3069,8 @@ function ShellFrame() {
3055
  * skeleton on AND what makes the slot function unreachable, so the two cannot come to disagree
3056
  * about when the nav is settled [[one-question-two-normalizers]].
3057
  */
3058
- const railLoading = nav.phase === "loading" || nav.phase === "idle"
3059
- || financeNav.phase === "loading" || financeNav.phase === "idle";
3060
  const navFailureMessage = nav.phase !== "error"
3061
  ? ""
3062
  : nav.timedOut
@@ -3074,7 +3088,6 @@ function ShellFrame() {
3074
  : "absent";
3075
  const automationSlot: RailSlot = railSlot(!!automation);
3076
  const analystSlot: RailSlot = railSlot(!!analyst);
3077
- const financeApplications = financeNav.phase === "ready" ? financeNav.applications : [];
3078
  const financeAppKey = /^#\/finance\/([^/?#]+)/.exec(hash)?.[1];
3079
  const financeCurrent = Boolean(financeAppKey);
3080
  // WAVE 23 C10 — the flyout's search. A plain label substring, case-folded: this list is at
@@ -3478,29 +3491,6 @@ function ShellFrame() {
3478
  <span className="shell-nav-label">App</span>
3479
  </a>
3480
 
3481
- {/* S64-T07 / R6 / owner instruction 2: Finance stopped being a top-level rail
3482
- module and became Application records reached through GET /nav/applications,
3483
- the same path Routing and Catalog ride. FinanceWorkspace is still the opener.
3484
- The collapsed-group preference went with the disclosure because there is no
3485
- longer a group to collapse. */}
3486
- {financeApplications.map((application) => {
3487
- if (!application.deepLink?.startsWith("/finance/")) return null;
3488
- const current = financeAppKey === application.deepLink.slice("/finance/".length).split(/[/?#]/)[0];
3489
- return (
3490
- <a
3491
- key={application.id}
3492
- className={"shell-nav-item shell-nav-app-child" + (current ? " is-active" : "")}
3493
- href={`#${application.deepLink}`}
3494
- aria-current={current ? "page" : undefined}
3495
- onClick={expandOnNavClick}
3496
- style={{ paddingLeft: 34 }}
3497
- >
3498
- <span aria-hidden="true" style={{ width: 16, textAlign: "center", color: "var(--lp-muted)" }}>·</span>
3499
- <span className="shell-nav-label">{application.name}</span>
3500
- </a>
3501
- );
3502
- })}
3503
-
3504
  {/* Agents stays permission-aware after App. Its label still comes from the server
3505
  registry when present; moving all three arms together prevents a missing grant from
3506
  changing the module band's order or spacing. */}
@@ -4089,6 +4079,7 @@ function ShellFrame() {
4089
  <Lazily surface={route === APP_ROUTE ? "App" : route === DATA_ROUTE ? "Data" : "Home"}>
4090
  <HomePage
4091
  mode={route === APP_ROUTE ? "app" : route === DATA_ROUTE ? "data" : "home"}
 
4092
  initialStarredOnly={window.location.hash.includes("filter=starred")}
4093
  // ⭐ `dbEntries`, NOT `entries` — found by LOOKING at it (wave 24 close-out visual
4094
  // pass), which is the only way it could have been found. The Automation SURFACE is a
 
113
  /* ⭐ W35-T09 — the assistant's EXISTING door for opening an AI-built view: hash + a retry
114
  ladder, returning a canceller. A second emit here would be a second answer. */
115
  import { openBuiltView } from "../assistant/AssistantPage";
 
 
116
  const HomePage = lazy(() => import("../home/HomePage"));
117
  const SheetGalleryPage = lazy(() =>
118
  import("../home/HomePage").then((m) => ({ default: m.SheetGalleryPage })));
 
164
  // paints, to save a signed-in user bytes they have already paid for. The page imports nothing
165
  // from `customer-grid/**`, so it drags no spreadsheet engine along with it.
166
  import PublishedView from "../publish/PublishedView";
167
+ import { financeNavigation, mergeRecents } from "../home/homeModel";
168
  import type { AutomationTile } from "../home/homeModel";
169
+ import type { ApplicationTile } from "../home/HomePage";
170
  // ⭐ WAVE 24 item 13 (R10, wiring W24-W3) — Home's Automations section.
171
  // ⚠ WAVE 26 ITEM 18 (R14): `stateOf` came out of this import with Home's status dot. The old note
172
  // here said it was imported rather than re-derived because it is the ONE place "is this running"
 
255
  function Lazily({ children, surface }: { children: ReactNode; surface: string }) {
256
  return (
257
  <ErrorBoundary surface={surface}>
258
+ <Suspense fallback={
259
+ <div className="shell-rail-skeleton is-destination" role="status" aria-label={`Loading ${surface}`}>
260
+ <div className="shell-rail-skeleton-row is-heading" aria-hidden="true">
261
+ <span className="shell-rail-skeleton-mark" />
262
+ <span className="shell-rail-skeleton-bar" />
263
+ </div>
264
+ {Array.from({ length: 6 }, (_, row) => (
265
+ <div className="shell-rail-skeleton-row" key={row} aria-hidden="true">
266
+ {Array.from({ length: 4 }, (_, column) => (
267
+ <span className="shell-rail-skeleton-bar" key={column} />
268
+ ))}
269
+ </div>
270
+ ))}
271
+ </div>
272
+ }>{children}</Suspense>
273
  </ErrorBoundary>
274
  );
275
  }
 
909
  }
910
  | { phase: "error"; timedOut?: boolean; malformed?: boolean };
911
 
912
+ type FinanceNav =
913
+ | { phase: "idle" | "loading" | "error" }
914
+ | { phase: "ready"; applications: ApplicationTile[] };
915
+
916
  const NO_UTILITY: NavPage[] = [];
917
  /** Stable identity, like `NO_ENTRIES` — a fresh `[]` per render would re-run Home's memo. */
918
  const NO_RECENTS: Recent[] = [];
 
987
  * `degraded` are UNCHANGED: they draw the real rows with their unavailable arms, because there
988
  * the answer has arrived and is bad news, which is a fact worth showing rather than a wait.
989
  *
990
+ * The sixteen-row skeleton is a deliberate ceiling over the settled rail of nine or ten rows.
991
+ * Finance applications now live as cards inside App and contribute no rail rows.
992
  * ⛔ KEEP THIS NUMBER >= THE SETTLED ROW COUNT AND NEVER BELOW IT. A skeleton one bar TALLER than
993
  * the settled rail is a shrink, which is fine; one bar SHORTER is the appear-from-nowhere shove
994
  * W33-T22 was written about, arriving by a different door. The two `.shell-nav-sep` hairlines are
 
1626
  /** The one key both halves of the fold read and write. */
1627
  const NAV_FOLD_KEY = "aios-nav-collapsed";
1628
 
 
 
 
 
 
1629
  /**
1630
  * ⭐⭐ WAVE 53 · T32 (ruling R1) — WHO FOLDED THE RAIL, not merely whether it is folded.
1631
  *
 
1657
  function ShellFrame() {
1658
  const [session, setSession] = useState<Session>({ phase: "checking" });
1659
  const [nav, setNav] = useState<Nav>({ phase: "idle" });
1660
+ const [financeNav, setFinanceNav] = useState<FinanceNav>({ phase: "idle" });
1661
+ const financeNavRequestEpoch = useRef(0);
1662
  // Wave 18 (C3-UT): bumped after "+ New database" so the rail refetches and the new ut_ key
1663
  // appears without a reload. Rename, create and delete paths share the same bumper: the
1664
  // authoritative answer lives in the SERVER's nav payload, so the rail re-asks rather than
 
1669
  const navRequestEpoch = useRef(0);
1670
  const [applicationsEpoch, setApplicationsEpoch] = useState(0);
1671
  const applicationCheckEpoch = useRef(0);
 
 
1672
  const [dataError, setDataError] = useState("");
1673
  const [toast, setToast] = useState("");
1674
  // `null` = closed. The SECTION is the open state, so "Settings" and
 
2107
  useEffect(() => {
2108
  const refresh = () => {
2109
  applicationCheckEpoch.current += 1;
2110
+ financeNavRequestEpoch.current += 1;
2111
  setApplicationsEpoch((epoch) => epoch + 1);
2112
  };
2113
  const changed = (event: Event) => {
 
2153
  return () => controller.abort();
2154
  }, [who, dataPath?.database, dataPath?.application, applicationsEpoch, leaveDeletedApplication]);
2155
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2156
  useEffect(() => {
2157
  const onWorkspaceStale = () => {
2158
  // W63-T29: connector creation/enablement/removal changes both membership and the rows a
 
2162
  setDataError("");
2163
  // Invalidate immediately: an older response can resolve before the next effect cleans up.
2164
  navRequestEpoch.current += 1;
2165
+ financeNavRequestEpoch.current += 1;
2166
  setNavEpoch((epoch) => epoch + 1);
2167
  };
2168
  window.addEventListener(WORKSPACE_STALE_EVENT, onWorkspaceStale);
 
2225
  };
2226
  }, [who, navEpoch]);
2227
 
2228
+ // The shell owns the grant-filtered read; App home owns its cards.
2229
+ useEffect(() => {
2230
+ const requestEpoch = ++financeNavRequestEpoch.current;
2231
+ if (who === null) {
2232
+ setFinanceNav({ phase: "idle" });
2233
+ return;
2234
+ }
2235
+ const controller = new AbortController();
2236
+ setFinanceNav((current) => current.phase === "ready" ? current : { phase: "loading" });
2237
+ void fetch(`${API_V1}/nav/applications`, {
2238
+ credentials: CREDENTIALS,
2239
+ signal: controller.signal,
2240
+ }).then(async (response) => {
2241
+ if (!response.ok) throw new Error("application_list_failed");
2242
+ const body = await response.json();
2243
+ if (!Array.isArray(body?.applications)) throw new Error("application_list_invalid");
2244
+ if (!controller.signal.aborted && requestEpoch === financeNavRequestEpoch.current) {
2245
+ setFinanceNav({ phase: "ready", applications: body.applications });
2246
+ }
2247
+ }).catch(() => {
2248
+ if (!controller.signal.aborted && requestEpoch === financeNavRequestEpoch.current) {
2249
+ setFinanceNav({ phase: "error" });
2250
+ }
2251
+ });
2252
+ return () => controller.abort();
2253
+ }, [who, navEpoch, applicationsEpoch]);
2254
+ const financeApplications = useMemo(
2255
+ () => financeNav.phase === "ready" ? financeNavigation(financeNav.applications) : [],
2256
+ [financeNav]
2257
+ );
2258
+
2259
  /**
2260
  * ⭐⭐ W33-T22 — RECORD THE RAIL THE PAYLOAD JUST DESCRIBED, for the next first paint.
2261
  *
 
3069
  * skeleton on AND what makes the slot function unreachable, so the two cannot come to disagree
3070
  * about when the nav is settled [[one-question-two-normalizers]].
3071
  */
3072
+ // Finance paints only App cards, so its read must not delay the rail.
3073
+ const railLoading = nav.phase === "loading" || nav.phase === "idle";
3074
  const navFailureMessage = nav.phase !== "error"
3075
  ? ""
3076
  : nav.timedOut
 
3088
  : "absent";
3089
  const automationSlot: RailSlot = railSlot(!!automation);
3090
  const analystSlot: RailSlot = railSlot(!!analyst);
 
3091
  const financeAppKey = /^#\/finance\/([^/?#]+)/.exec(hash)?.[1];
3092
  const financeCurrent = Boolean(financeAppKey);
3093
  // WAVE 23 C10 — the flyout's search. A plain label substring, case-folded: this list is at
 
3491
  <span className="shell-nav-label">App</span>
3492
  </a>
3493
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3494
  {/* Agents stays permission-aware after App. Its label still comes from the server
3495
  registry when present; moving all three arms together prevents a missing grant from
3496
  changing the module band's order or spacing. */}
 
4079
  <Lazily surface={route === APP_ROUTE ? "App" : route === DATA_ROUTE ? "Data" : "Home"}>
4080
  <HomePage
4081
  mode={route === APP_ROUTE ? "app" : route === DATA_ROUTE ? "data" : "home"}
4082
+ financeApplications={financeApplications}
4083
  initialStarredOnly={window.location.hash.includes("filter=starred")}
4084
  // ⭐ `dbEntries`, NOT `entries` — found by LOOKING at it (wave 24 close-out visual
4085
  // pass), which is the only way it could have been found. The Automation SURFACE is a
web/src/shell/nav.ts CHANGED
@@ -1252,6 +1252,13 @@ export const APP_ROUTE = "app";
1252
  * branch. Joining CHROME_ROUTES is inert for firstDestination: LANDING_PREFERENCE is [HOME_ROUTE]. */
1253
  export const DATA_ROUTE = "data";
1254
 
 
 
 
 
 
 
 
1255
  /** C6's Data address, including the folder stratum above the grid's database/view path. */
1256
  export interface DataAddress { database?: string; view?: string; folder?: string }
1257
 
 
1252
  * branch. Joining CHROME_ROUTES is inert for firstDestination: LANDING_PREFERENCE is [HOME_ROUTE]. */
1253
  export const DATA_ROUTE = "data";
1254
 
1255
+ /** Commit the destination before starting any asynchronous existence or data read. */
1256
+ export function commitRoute(href: string): boolean {
1257
+ const previous = window.location.hash;
1258
+ window.location.hash = href;
1259
+ return window.location.hash !== previous;
1260
+ }
1261
+
1262
  /** C6's Data address, including the folder stratum above the grid's database/view path. */
1263
  export interface DataAddress { database?: string; view?: string; folder?: string }
1264
 
web/src/shell/navExtras.css CHANGED
@@ -115,6 +115,49 @@
115
  display: none;
116
  }
117
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
118
  .shell-nav-row > .shell-dots,
119
  .shell-nav-folder > .shell-dots {
120
  flex: 0 0 auto;
 
115
  display: none;
116
  }
117
 
118
+ .shell-rail-skeleton.is-destination {
119
+ flex: 1;
120
+ min-width: 0;
121
+ padding: 24px;
122
+ gap: 8px;
123
+ animation: shell-rail-skeleton-in 150ms ease-out;
124
+ }
125
+
126
+ .shell-rail-skeleton.is-destination .shell-rail-skeleton-row {
127
+ display: grid;
128
+ grid-template-columns: 2fr repeat(3, 1fr);
129
+ gap: 24px;
130
+ min-height: 40px;
131
+ padding: 8px 0;
132
+ border-bottom: 1px solid var(--lp-line);
133
+ }
134
+
135
+ .shell-rail-skeleton.is-destination .shell-rail-skeleton-bar {
136
+ width: 100%;
137
+ height: 12px;
138
+ }
139
+
140
+ .shell-rail-skeleton.is-destination .is-heading {
141
+ display: flex;
142
+ gap: 8px;
143
+ margin-bottom: 16px;
144
+ border-bottom: 0;
145
+ }
146
+
147
+ .shell-rail-skeleton.is-destination .is-heading .shell-rail-skeleton-bar {
148
+ width: 160px;
149
+ height: 16px;
150
+ }
151
+
152
+ @keyframes shell-rail-skeleton-in {
153
+ from { opacity: 0; }
154
+ to { opacity: 1; }
155
+ }
156
+
157
+ @media (prefers-reduced-motion: reduce) {
158
+ .shell-rail-skeleton.is-destination { animation: none; }
159
+ }
160
+
161
  .shell-nav-row > .shell-dots,
162
  .shell-nav-folder > .shell-dots {
163
  flex: 0 0 auto;