fsanyoto commited on
Commit
cf09724
·
verified ·
1 Parent(s): 7aafd30

Deploy AIOS web (React glide grid + FastAPI slice)

Browse files
This view is limited to 50 files because it contains too many changes.   See raw diff
Files changed (50) hide show
  1. RELEASES.json +1 -1
  2. VERSION +1 -1
  3. api/amazon_relational.py +127 -20
  4. api/application_registry.py +103 -9
  5. api/catalog_store.py +97 -0
  6. api/connectors_amazon.py +2 -2
  7. api/external_freshness.py +98 -12
  8. api/loopy_catalog_tools.py +93 -4
  9. api/loopy_links.py +28 -3
  10. api/main.py +4 -0
  11. api/odoo_attachments.py +103 -0
  12. api/odoo_relational.py +3 -0
  13. api/routes_amazon_profit.py +200 -0
  14. api/routes_competitor_watch.py +217 -0
  15. api/routes_customers.py +5 -103
  16. api/routes_external.py +421 -51
  17. api/routes_forms.py +4 -3
  18. api/routes_nav.py +4 -2
  19. api/routes_odoo_attachments.py +31 -0
  20. api/routes_publish.py +3 -1
  21. api/routes_templates.py +18 -3
  22. api/tool_groups/__init__.py +46 -4
  23. api/tool_groups/apps.py +40 -1
  24. api/tool_groups/data.py +23 -1
  25. api/tool_groups/sheet.py +1 -1
  26. api/tool_groups/views.py +128 -19
  27. platform/core/connector_spec.py +0 -0
  28. platform/core/external_tools.py +1 -1
  29. platform/core/registry.py +5 -0
  30. platform/core/route_system.py +0 -58
  31. platform/core/view_templates.py +39 -1
  32. platform/harness/amazon_client.py +53 -1
  33. platform/harness/amazon_schema.py +2 -0
  34. platform/harness/amazon_store.py +186 -16
  35. platform/harness/semantic.py +2 -0
  36. platform/model/metrics/amazon_profit.yml +56 -0
  37. platform/modules/amazon_profit.py +1424 -0
  38. platform/modules/competitor_watch.py +660 -0
  39. web/public/AIOS_DEPLOY_RECEIPT +1 -1
  40. web/public/brand/SOURCES.md +1 -0
  41. web/public/brand/google-maps.svg +1 -0
  42. web/s71_frontend_contracts.py +4 -1
  43. web/src/apps/competitor-watch/CompetitorWatchView.tsx +485 -0
  44. web/src/customer-grid/AmazonPeriodPicker.tsx +82 -0
  45. web/src/customer-grid/CustomerGrid.tsx +11 -2
  46. web/src/customer-grid/DeliveryPhotos.tsx +138 -0
  47. web/src/customer-grid/MapView.tsx +10 -22
  48. web/src/customer-grid/RecordDetail.tsx +9 -0
  49. web/src/customer-grid/RouteNav.tsx +95 -43
  50. web/src/customer-grid/ViewSidebar.tsx +85 -5
RELEASES.json CHANGED
@@ -1,4 +1,4 @@
1
  {
2
- "current": "eb8f3aa0d",
3
  "releases": []
4
  }
 
1
  {
2
+ "current": "add0f45e",
3
  "releases": []
4
  }
VERSION CHANGED
@@ -1 +1 @@
1
- eb8f3aa0d
 
1
+ add0f45e
api/amazon_relational.py CHANGED
@@ -34,6 +34,7 @@ them to read-through too. The shared document holds their schemas, never a trunc
34
  import hashlib
35
  import json
36
  import os
 
37
  import sys
38
  from collections import OrderedDict
39
  from pathlib import Path
@@ -132,9 +133,61 @@ _MONEY.update({"estimated_fee_total", "estimated_referral_fee_per_unit",
132
  "estimated_pick_pack_fee_per_unit", "estimated_weight_handling_fee_per_unit",
133
  "expected_fulfillment_fee_per_unit", "estimated_monthly_storage_fee"})
134
 
135
- #: Percentages and rates are fractional too, but they are not money. `currency` is the only
136
- #: fractional field type the grid offers, so they take it and the LABEL carries the meaning.
137
- _RATE_SUFFIX = ("_percentage", "_percentage_b2_b", "_rate", "_ctr")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
138
 
139
  # Inventory reports remain VARCHAR when a quantity column mixes numbers and blanks.
140
  # Names identify units; identifiers such as SKU and FNSKU must stay text.
@@ -161,7 +214,9 @@ def _ftype(col, duck_type):
161
  return "int"
162
  if any(col == s or col.endswith(s) for s in _DATEISH):
163
  return "date"
164
- if col in _MONEY or col.endswith(("_amount", "_fee")) or any(col.endswith(s) for s in _RATE_SUFFIX):
 
 
165
  return "currency"
166
  base = str(duck_type or "").upper().split("(")[0]
167
  if base in ("DOUBLE", "FLOAT", "DECIMAL"):
@@ -171,6 +226,18 @@ def _ftype(col, duck_type):
171
  return "text"
172
 
173
 
 
 
 
 
 
 
 
 
 
 
 
 
174
  def mirror_columns(cur, table):
175
  """[(name, type)] for a mirror table, or [] when it has never been synced."""
176
  try:
@@ -197,6 +264,8 @@ def mirror_columns(cur, table):
197
  LISTINGS = PREFIX + "listings"
198
  LOOKUP_PARENT, LOOKUP_SKU, LOOKUP_ASIN = "lookup_parent_asin", "lookup_sku", "lookup_asin"
199
  LOOKUP_KEYS = frozenset((LOOKUP_PARENT, LOOKUP_SKU, LOOKUP_ASIN))
 
 
200
  _LOOKUP_LABELS = {LOOKUP_PARENT: "Parent ASIN", LOOKUP_SKU: "SKU", LOOKUP_ASIN: "ASIN"}
201
  _LOOKUP_DESCRIPTIONS = {
202
  LOOKUP_PARENT: ("The parent ASIN of this row's product, from Amazon's catalog, else the "
@@ -342,9 +411,11 @@ def lookups(cur, key, names=None):
342
  elif sku and latest:
343
  ref = f"TRIM(CAST({table}.{_quoted(sku)} AS VARCHAR))"
344
  via = sku_via if "seller_sku" in listing_names else None
345
- add(LOOKUP_ASIN, sku,
346
- f"(SELECT string_agg(DISTINCT _l.asin, ', ' ORDER BY _l.asin) "
347
- f"FROM ({latest}) AS _l WHERE _l.sku = {ref})", via)
 
 
348
  if parents:
349
  add(LOOKUP_PARENT, sku,
350
  f"(SELECT string_agg(DISTINCT _p.parent_asin, ', ' ORDER BY _p.parent_asin) "
@@ -359,6 +430,8 @@ def _fields_for(cur, key, *, read_through=False):
359
  if not cols:
360
  return []
361
  declared = {field["name"]: field for field in connector_spec.AMAZON_FIELDS.get(key, ())}
 
 
362
  names = {c[0] for c in cols}
363
  pinned = PINNED.get(key) if PINNED.get(key) in names else None
364
  # S67-T30: each lookup lands IMMEDIATELY after the column it derives from, shown by default,
@@ -373,13 +446,15 @@ def _fields_for(cur, key, *, read_through=False):
373
  # report's first column is whatever Amazon put there (`item_name`, `_data_origin`), so a
374
  # listing opened from an order must lead with its seller SKU, as Odoo's pinned fields do.
375
  for name, dtype in sorted(cols, key=lambda col: col[0] != pinned):
 
376
  out.append(_odoo._preset({
377
- "key": name, "label": declared.get(name, {}).get("label") or _label(name),
 
378
  "type": _ftype(name, dtype),
379
  "source": "overlay",
380
- "default": name == pinned or name in _DEFAULT_COLUMNS or name in product,
381
  "pinned": name == pinned,
382
- **({"format": {"decimals": 4}} if name == "per_unit_volume" else {}),
383
  }, flow="amazon_relational"))
384
  for lookup in derived.get(name, ()):
385
  field = {"key": lookup["key"], "label": lookup["label"], "type": "text",
@@ -402,9 +477,15 @@ def _fields_for(cur, key, *, read_through=False):
402
  return out
403
 
404
 
405
- #: Columns worth showing before a person picks their own. Deliberately short: these tables are
406
- #: wide, and a default of "everything" is the same as no default at all.
407
- _DEFAULT_COLUMNS = {
 
 
 
 
 
 
408
  "amazon_order_id", "purchase_date", "order_status", "sku", "seller_sku", "asin", "asin1",
409
  "quantity", "quantity_purchased", "item_price", "item_status", "product_name", "item_name",
410
  "settlement_id", "amount", "amount_type", "amount_description", "posted_date",
@@ -413,7 +494,10 @@ _DEFAULT_COLUMNS = {
413
  "backend_keywords",
414
  "month", "search_query", "impressions", "clicks", "cart_adds", "purchases", "source_basis",
415
  "keyword", "date", "organic_rank", "sponsored_rank", "sponsored_rank_basis",
416
- }
 
 
 
417
 
418
 
419
  #: The original seven used first-field identities. Retained for legacy-id migration
@@ -549,9 +633,11 @@ def grid_source(cur, key):
549
  continue
550
  kind = _ftype(name, dtype)
551
  expr = _quoted(name)
552
- fractional = kind == "currency" or name == "per_unit_volume"
553
- if kind in ("currency", "int"):
554
  expr = f"TRY_CAST({expr} AS {'DOUBLE' if fractional else 'BIGINT'})"
 
 
555
  cols[name] = (expr, _number if fractional else {"int": _integer}.get(kind, _text))
556
  # S67-T30: the product lookups bind like any mirror column, so a filter (`=` a parent), a
557
  # group (count by parent) and a sort compile against them in SQL with no per-row Python.
@@ -613,7 +699,7 @@ def _read(cur, key):
613
  quoted = ", ".join(spec["cols"][c][0] for c in cols)
614
  personal = set(amazon_store.personal_columns(key))
615
  numeric = {name for name, dtype in mirror_columns(cur, SOURCE[key])
616
- if name not in personal and _ftype(name, dtype) in ("currency", "int")}
617
  # S67-T30: a stored snapshot carries the same product lookups, computed by the SAME SQL
618
  # expressions the read-through binding uses, in this one SELECT (never per row).
619
  derived = [(lookup["key"], lookup["expr"]) for lookup in lookups(cur, key)]
@@ -729,6 +815,11 @@ def plan(cur, rt=None):
729
  built[key] = {"readThrough": True,
730
  "fields": _fields_for(cur, key, read_through=True), "count": n}
731
  continue
 
 
 
 
 
732
  rows = _read(cur, key)
733
  if rows:
734
  built[key] = rows
@@ -750,7 +841,9 @@ def plan_fingerprint(cur, built):
750
  rows = built.get(key) or []
751
  canonical = sorted(rows, key=lambda row: json.dumps(
752
  row, sort_keys=True, ensure_ascii=True, separators=(",", ":"), default=str))
753
- tables.append({"key": key, "fields": _fields_for(cur, key), "rows": canonical})
 
 
754
  payload = json.dumps(tables, sort_keys=True, ensure_ascii=True,
755
  separators=(",", ":"), default=str)
756
  return hashlib.sha256(payload.encode("utf-8")).hexdigest()
@@ -979,10 +1072,15 @@ def apply_plan(rt, built, username="amazon", today=None):
979
  not_stored.clear()
980
  live_columns = {key: {field["key"] for field in table.get("fields", ())}
981
  for key, table in doc.items() if key in SOURCE and isinstance(table, dict)}
 
 
 
982
  live_columns.update({key: {field["key"] for field in fields}
983
- for key, _label, fields, _rows in plans})
984
  generated = connector_spec.system_link_fields("amazon", live_columns)
985
  for key, label, fields, rows in plans:
 
 
986
  stub = isinstance(rows, dict) and rows.get("readThrough") is True
987
 
988
  def unbacked_refreshed(field):
@@ -1038,6 +1136,15 @@ def apply_plan(rt, built, username="amazon", today=None):
1038
  removed = len((doc.get(key) or {}).get("rows") or {}) if stub else 0
1039
  written[key] = _odoo._ensure_table_inplace(doc, key, label, fields, None if stub else rows,
1040
  username, stamp)
 
 
 
 
 
 
 
 
 
1041
  if stub:
1042
  doc[key]["readThrough"] = True
1043
  doc[key]["rows"] = {}
@@ -1048,7 +1155,7 @@ def apply_plan(rt, built, username="amazon", today=None):
1048
  # The shared merger compares string spellings, so an old "2" and a new
1049
  # integer 2 otherwise compare equal and leave the old cell untyped.
1050
  numeric = {f["key"] for f in doc[key].get("fields", [])
1051
- if f.get("type") in ("currency", "int")
1052
  and (f.get("automation") or {}).get("flowId") == "amazon_relational"
1053
  and not _odoo._ut().user_edited(f)}
1054
  stored = doc[key].get("rows") or {}
 
34
  import hashlib
35
  import json
36
  import os
37
+ import re
38
  import sys
39
  from collections import OrderedDict
40
  from pathlib import Path
 
133
  "estimated_pick_pack_fee_per_unit", "estimated_weight_handling_fee_per_unit",
134
  "expected_fulfillment_fee_per_unit", "estimated_monthly_storage_fee"})
135
 
136
+ #: S78-T01: money the report stores as text or names without an `_amount` / `_fee` suffix.
137
+ #: ⚠ No `_price` suffix rule: `attributes_list_price` and the `*_median_*_price` details are JSON.
138
+ _MONEY.update({"business_price", "label_cost", "fee_total", "sales_price", "item_price_per_unit",
139
+ "featuredoffer_price", "lowest_price_new_plus_shipping", "lowest_price_used",
140
+ "recommended_sales_price", "estimated_cost_savings_of_recommended_actions",
141
+ "estimated_storage_cost_next_month", "sales_last_30_days", "amount_charged",
142
+ "rate_surcharge", "estimated_referral_fee_per_item", "amount_per_unit",
143
+ "amount_total", "base_rate", "est_base_msf", "est_sus", "utilization_surcharge_rate",
144
+ "estimated_future_fee_current_selling_on_amazon_future_fulfillment_fees",
145
+ "estimated_future_order_handling_fee_per_order",
146
+ "estimated_future_pick_pack_fee_per_unit",
147
+ "estimated_future_weight_handling_fee_per_unit",
148
+ "expected_future_fulfillment_fee_per_unit", "lost_revenue_due_to_oos",
149
+ "non_subscriber_average_revenue", "subscriber_average_revenue",
150
+ "total_subscriptions_revenue"})
151
+ _MONEY_PREFIX = ("cost_", "sales_shipped_last_", "estimated_ais_", "sns_sale_price_week_",
152
+ "revenue_from_")
153
+ _MONEY_INFIX = ("_life_time_value_",)
154
+
155
+ #: ⭐ S78-T01: rates and shares are `pct`, and the grid shows a `pct` value as the number plus
156
+ #: "%" with no scaling. So the scale is MEASURED per column on the staging mirror (2026-10-20):
157
+ #: `_PERCENT` columns already hold 0 to 100, `_FRACTION_PERCENT` columns hold 0 to 1 and are
158
+ #: multiplied by 100 in the read path (`grid_source`), so 0.15 reads "15%" and never "0.15%".
159
+ #: ⛔ A rate whose scale was not measured stays out of both sets (see `oos_rate_week_*`).
160
+ _PERCENT_SUFFIX = ("_percentage", "_percentage_b2_b")
161
+ _PERCENT = {"sales_by_asin_refund_rate", "sales_by_asin_refund_rate_b2_b",
162
+ "cart_add_data_asin_cart_add_share", "click_data_asin_click_share",
163
+ "impression_data_asin_impression_share", "purchase_data_asin_purchase_share",
164
+ "cart_add_data_total_cart_add_rate", "click_data_total_click_rate",
165
+ "purchase_data_total_purchase_rate", "revenue_penetration",
166
+ "coupons_revenue_penetration", "share_of_coupon_subscriptions",
167
+ "subscriber_retention_for30_days", "subscriber_retention_for90_days",
168
+ *(f"{metric}_for{n}_percent_seller_funding" for metric in
169
+ ("revenue_penetration", "signup_conversion") for n in (0, 5, 10))}
170
+ _FRACTION_PERCENT = {"click_share", "conversion_share", "click_data_click_rate",
171
+ "purchase_data_conversion_rate", "combination_pct"}
172
+ #: Account health reports each rate metric and its target as a 0 to 1 fraction.
173
+ _FRACTION_PERCENT_RE = re.compile(r"[a-z_]+_rate(?:_afn|_mfn)?_(?:rate|target_value)")
174
+
175
+ #: Non-money numbers stored as text. With the DOUBLE columns that are not money, they take
176
+ #: `currency` (the grid's only fractional type) with an EMPTY currency symbol, so no "$" shows.
177
+ _NUMBER = {"storage_utilization_ratio"}
178
+
179
+
180
+ def _is_money(col):
181
+ return (col in _MONEY or col.endswith(("_amount", "_fee", "_fees")) or col.startswith(_MONEY_PREFIX)
182
+ or any(part in col for part in _MONEY_INFIX))
183
+
184
+
185
+ def _is_fraction_percent(col):
186
+ return col in _FRACTION_PERCENT or bool(_FRACTION_PERCENT_RE.fullmatch(col))
187
+
188
+
189
+ def _is_percent(col):
190
+ return col in _PERCENT or col.endswith(_PERCENT_SUFFIX) or _is_fraction_percent(col)
191
 
192
  # Inventory reports remain VARCHAR when a quantity column mixes numbers and blanks.
193
  # Names identify units; identifiers such as SKU and FNSKU must stay text.
 
214
  return "int"
215
  if any(col == s or col.endswith(s) for s in _DATEISH):
216
  return "date"
217
+ if _is_percent(col):
218
+ return "pct"
219
+ if _is_money(col) or col in _NUMBER:
220
  return "currency"
221
  base = str(duck_type or "").upper().split("(")[0]
222
  if base in ("DOUBLE", "FLOAT", "DECIMAL"):
 
226
  return "text"
227
 
228
 
229
+ def _format(col, duck_type):
230
+ """The display format a field ships with, or None for the grid's default."""
231
+ kind = _ftype(col, duck_type)
232
+ if col == "per_unit_volume":
233
+ return {"decimals": 4}
234
+ if kind == "pct":
235
+ return {"decimals": 2}
236
+ if kind == "currency" and not _is_money(col):
237
+ return {"currencySymbol": "", "decimals": 2}
238
+ return None
239
+
240
+
241
  def mirror_columns(cur, table):
242
  """[(name, type)] for a mirror table, or [] when it has never been synced."""
243
  try:
 
264
  LISTINGS = PREFIX + "listings"
265
  LOOKUP_PARENT, LOOKUP_SKU, LOOKUP_ASIN = "lookup_parent_asin", "lookup_sku", "lookup_asin"
266
  LOOKUP_KEYS = frozenset((LOOKUP_PARENT, LOOKUP_SKU, LOOKUP_ASIN))
267
+ #: Native columns that already show a row's ASIN (orders, order items, replenishment carry `asin`).
268
+ _NATIVE_ASIN = frozenset(("asin", "asin1", "child_asin"))
269
  _LOOKUP_LABELS = {LOOKUP_PARENT: "Parent ASIN", LOOKUP_SKU: "SKU", LOOKUP_ASIN: "ASIN"}
270
  _LOOKUP_DESCRIPTIONS = {
271
  LOOKUP_PARENT: ("The parent ASIN of this row's product, from Amazon's catalog, else the "
 
411
  elif sku and latest:
412
  ref = f"TRIM(CAST({table}.{_quoted(sku)} AS VARCHAR))"
413
  via = sku_via if "seller_sku" in listing_names else None
414
+ # S78-T01: a table that carries its own ASIN column gains no second "ASIN".
415
+ if not names & _NATIVE_ASIN:
416
+ add(LOOKUP_ASIN, sku,
417
+ f"(SELECT string_agg(DISTINCT _l.asin, ', ' ORDER BY _l.asin) "
418
+ f"FROM ({latest}) AS _l WHERE _l.sku = {ref})", via)
419
  if parents:
420
  add(LOOKUP_PARENT, sku,
421
  f"(SELECT string_agg(DISTINCT _p.parent_asin, ', ' ORDER BY _p.parent_asin) "
 
430
  if not cols:
431
  return []
432
  declared = {field["name"]: field for field in connector_spec.AMAZON_FIELDS.get(key, ())}
433
+ written = connector_spec.AMAZON_LABELS.get(key, {})
434
+ shown = default_columns(key)
435
  names = {c[0] for c in cols}
436
  pinned = PINNED.get(key) if PINNED.get(key) in names else None
437
  # S67-T30: each lookup lands IMMEDIATELY after the column it derives from, shown by default,
 
446
  # report's first column is whatever Amazon put there (`item_name`, `_data_origin`), so a
447
  # listing opened from an order must lead with its seller SKU, as Odoo's pinned fields do.
448
  for name, dtype in sorted(cols, key=lambda col: col[0] != pinned):
449
+ fmt = _format(name, dtype)
450
  out.append(_odoo._preset({
451
+ "key": name,
452
+ "label": declared.get(name, {}).get("label") or written.get(name) or _label(name),
453
  "type": _ftype(name, dtype),
454
  "source": "overlay",
455
+ "default": name == pinned or name in shown or name in product,
456
  "pinned": name == pinned,
457
+ **({"format": fmt} if fmt else {}),
458
  }, flow="amazon_relational"))
459
  for lookup in derived.get(name, ()):
460
  field = {"key": lookup["key"], "label": lookup["label"], "type": "text",
 
477
  return out
478
 
479
 
480
+ def default_columns(key):
481
+ """The columns `key` opens on beyond the pinned, product, lookup and link fields."""
482
+ declared = connector_spec.AMAZON_DEFAULT_COLUMNS.get(key)
483
+ return frozenset(declared) if declared is not None else _UNDECLARED_DEFAULT_COLUMNS
484
+
485
+
486
+ #: The shared fallback for a table `connector_spec.AMAZON_DEFAULT_COLUMNS` does not declare yet
487
+ #: (one the staging mirror has never synced). A declared table reads only its own list.
488
+ _UNDECLARED_DEFAULT_COLUMNS = frozenset({
489
  "amazon_order_id", "purchase_date", "order_status", "sku", "seller_sku", "asin", "asin1",
490
  "quantity", "quantity_purchased", "item_price", "item_status", "product_name", "item_name",
491
  "settlement_id", "amount", "amount_type", "amount_description", "posted_date",
 
494
  "backend_keywords",
495
  "month", "search_query", "impressions", "clicks", "cart_adds", "purchases", "source_basis",
496
  "keyword", "date", "organic_rank", "sponsored_rank", "sponsored_rank_basis",
497
+ })
498
+
499
+ #: Every name any Amazon table may open on (`verify_agent_knowledge` reads it by name).
500
+ _DEFAULT_COLUMNS = _UNDECLARED_DEFAULT_COLUMNS.union(*connector_spec.AMAZON_DEFAULT_COLUMNS.values())
501
 
502
 
503
  #: The original seven used first-field identities. Retained for legacy-id migration
 
633
  continue
634
  kind = _ftype(name, dtype)
635
  expr = _quoted(name)
636
+ fractional = kind in ("currency", "pct") or name == "per_unit_volume"
637
+ if kind in ("currency", "pct", "int"):
638
  expr = f"TRY_CAST({expr} AS {'DOUBLE' if fractional else 'BIGINT'})"
639
+ if kind == "pct" and _is_fraction_percent(name):
640
+ expr = f"ROUND({expr} * 100, 8)" # 8 places drops float noise, keeps every digit
641
  cols[name] = (expr, _number if fractional else {"int": _integer}.get(kind, _text))
642
  # S67-T30: the product lookups bind like any mirror column, so a filter (`=` a parent), a
643
  # group (count by parent) and a sort compile against them in SQL with no per-row Python.
 
699
  quoted = ", ".join(spec["cols"][c][0] for c in cols)
700
  personal = set(amazon_store.personal_columns(key))
701
  numeric = {name for name, dtype in mirror_columns(cur, SOURCE[key])
702
+ if name not in personal and _ftype(name, dtype) in ("currency", "pct", "int")}
703
  # S67-T30: a stored snapshot carries the same product lookups, computed by the SAME SQL
704
  # expressions the read-through binding uses, in this one SELECT (never per row).
705
  derived = [(lookup["key"], lookup["expr"]) for lookup in lookups(cur, key)]
 
815
  built[key] = {"readThrough": True,
816
  "fields": _fields_for(cur, key, read_through=True), "count": n}
817
  continue
818
+ if not n:
819
+ # S78-T02: an emptied mirror table is an empty population, never a skip, or the stored
820
+ # definition keeps rows the source no longer holds. `apply_plan` creates no table for it.
821
+ built[key] = []
822
+ continue
823
  rows = _read(cur, key)
824
  if rows:
825
  built[key] = rows
 
841
  rows = built.get(key) or []
842
  canonical = sorted(rows, key=lambda row: json.dumps(
843
  row, sort_keys=True, ensure_ascii=True, separators=(",", ":"), default=str))
844
+ # S78-T02: an empty population differs from an absent table, so a stale copy is rewritten.
845
+ empty = {"empty": True} if built.get(key) == [] else {}
846
+ tables.append({"key": key, "fields": _fields_for(cur, key), "rows": canonical, **empty})
847
  payload = json.dumps(tables, sort_keys=True, ensure_ascii=True,
848
  separators=(",", ":"), default=str)
849
  return hashlib.sha256(payload.encode("utf-8")).hexdigest()
 
1072
  not_stored.clear()
1073
  live_columns = {key: {field["key"] for field in table.get("fields", ())}
1074
  for key, table in doc.items() if key in SOURCE and isinstance(table, dict)}
1075
+ # S78-T02: an empty population reconciles an EXISTING definition only; it creates none.
1076
+ unborn = {key for key, _label, _fields, rows in plans
1077
+ if isinstance(rows, list) and not rows and not isinstance(doc.get(key), dict)}
1078
  live_columns.update({key: {field["key"] for field in fields}
1079
+ for key, _label, fields, _rows in plans if key not in unborn})
1080
  generated = connector_spec.system_link_fields("amazon", live_columns)
1081
  for key, label, fields, rows in plans:
1082
+ if key in unborn:
1083
+ continue
1084
  stub = isinstance(rows, dict) and rows.get("readThrough") is True
1085
 
1086
  def unbacked_refreshed(field):
 
1136
  removed = len((doc.get(key) or {}).get("rows") or {}) if stub else 0
1137
  written[key] = _odoo._ensure_table_inplace(doc, key, label, fields, None if stub else rows,
1138
  username, stamp)
1139
+ # S78-T01: `_ensure_table_inplace` does not forward `format`, so a stored preset field
1140
+ # would keep showing "$" on a weight or 0 decimals on a percent.
1141
+ formats = {f["key"]: f["format"] for f in fields if f.get("format")}
1142
+ for stored_field in doc[key].get("fields", []):
1143
+ if (stored_field.get("key") in formats
1144
+ and (stored_field.get("automation") or {}).get("flowId") == "amazon_relational"
1145
+ and (stored_field.get("automation") or {}).get("preset")
1146
+ and not _odoo._ut().user_edited(stored_field)):
1147
+ stored_field["format"] = dict(formats[stored_field["key"]])
1148
  if stub:
1149
  doc[key]["readThrough"] = True
1150
  doc[key]["rows"] = {}
 
1155
  # The shared merger compares string spellings, so an old "2" and a new
1156
  # integer 2 otherwise compare equal and leave the old cell untyped.
1157
  numeric = {f["key"] for f in doc[key].get("fields", [])
1158
+ if f.get("type") in ("currency", "pct", "int")
1159
  and (f.get("automation") or {}).get("flowId") == "amazon_relational"
1160
  and not _odoo._ut().user_edited(f)}
1161
  stored = doc[key].get("rows") or {}
api/application_registry.py CHANGED
@@ -69,6 +69,76 @@ _TEMPLATE_CONTRACTS = {
69
  APPLICATION_WIZARD_TEMPLATE_KINDS = tuple(_TEMPLATE_CONTRACTS)
70
  APPLICATION_TEMPLATE_KINDS = tuple(_TEMPLATE_CONTRACTS)
71
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72
 
73
  class ApplicationError(ValueError):
74
  pass
@@ -132,8 +202,19 @@ def own_template_apps(runtime, user):
132
  return owned
133
 
134
 
135
- def template_contracts():
136
- """The trusted renderer contracts offered by the Application creation flow."""
 
 
 
 
 
 
 
 
 
 
 
137
  return [copy.deepcopy(contract) for contract in _TEMPLATE_CONTRACTS.values()]
138
 
139
 
@@ -627,7 +708,7 @@ def _refuse_legacy_catalog_changes(app, config):
627
 
628
  def _template_definition(kind, payload, *, semantic_records=None, field_contracts=None,
629
  allowed_databases=None):
630
- contract = _TEMPLATE_CONTRACTS.get(kind)
631
  if contract is None:
632
  raise ApplicationError("application template kind is not recognized")
633
  template_kind = str(payload.get("templateKind") or "").strip().lower()
@@ -636,6 +717,10 @@ def _template_definition(kind, payload, *, semantic_records=None, field_contract
636
  source = str(payload.get("sourceDatabase") or "").strip()[:120]
637
  if not source:
638
  raise ApplicationError("sourceDatabase is required")
 
 
 
 
639
  if source not in set(allowed_databases or ()):
640
  raise PermissionError("an Application cannot bind a database you cannot open")
641
  if "compatibleDatabases" in payload:
@@ -706,6 +791,14 @@ def validate_application(payload, tenant, *, semantic_records=None, field_contra
706
  if "tenant" in payload and str(payload.get("tenant") or "") != str(tenant):
707
  raise PermissionError("an Application cannot be created for another tenant")
708
  template_kind = str(payload.get("templateKind") or "").strip().lower()
 
 
 
 
 
 
 
 
709
  if template_kind and template_kind not in _TEMPLATE_CONTRACTS:
710
  raise ApplicationError("application template kind is not recognized")
711
  expected_type = (_TEMPLATE_CONTRACTS[template_kind]["applicationType"]
@@ -843,7 +936,7 @@ def _build_application(tenant, user, payload, *, semantic_records=None, field_co
843
  """Build the same validated record for authored Apps and boot migrations."""
844
  payload=payload if isinstance(payload,dict) else {}
845
  template_kind=str(payload.get("templateKind") or "").strip().lower()
846
- expected_type = (_TEMPLATE_CONTRACTS.get(template_kind) or {}).get("applicationType")
847
  kind=str(payload.get("type") or expected_type or "").strip().lower()
848
  definition = validate_application(
849
  payload, tenant, semantic_records=semantic_records, field_contracts=field_contracts,
@@ -858,7 +951,7 @@ def _build_application(tenant, user, payload, *, semantic_records=None, field_co
858
  raw_config = payload.get("config")
859
  if definition and raw_config is None:
860
  raw_config = {"schemaVersion": 1,
861
- "display": {"mode": _TEMPLATE_CONTRACTS[template_kind]["displayMode"]}}
862
  app={"id":app_id,"tenant":str(tenant),"type":kind,"name":name,
863
  "compatibleDatabases":compatible,
864
  "semanticRoleBindings":_governed_bindings(
@@ -867,8 +960,8 @@ def _build_application(tenant, user, payload, *, semantic_records=None, field_co
867
  "share":{"mode":"private","users":[]},"starredBy":[],"createdBy":user,
868
  "createdAt":now,"updatedAt":now,"revision":1}
869
  app.update(definition)
870
- if definition and _TEMPLATE_CONTRACTS[template_kind].get("deepLink"):
871
- app["deepLink"] = _TEMPLATE_CONTRACTS[template_kind]["deepLink"].replace("<id>", app_id)
872
  if kind == "code":
873
  app.update(deepLink=f"/app/code/{app_id}", origin=None)
874
  app["origin"] = _server_origin(origin_door, via)
@@ -1237,7 +1330,8 @@ def mutate(runtime, app_id, user, is_admin, patch, *, semantic_records=None, fie
1237
  if not _is_finance(app) and not _allowed(app.get("compatibleDatabases"), allowed_databases):
1238
  if not _database_free_code(app):
1239
  raise ApplicationError("application does not exist")
1240
- if app.get("templateKind") in APPLICATION_TEMPLATE_KINDS and "compatibleDatabases" in patch:
 
1241
  raise ApplicationError("a template Application's sourceDatabase is immutable")
1242
  star_only = set(patch) <= {"starred"}
1243
  if star_only:
@@ -1522,7 +1616,7 @@ def _retirement_plan(runtime, tenant):
1522
  for app in applications.values()):
1523
  raise ApplicationError("the Application registry has an invalid tenant record")
1524
  removed = {identity: app for identity, app in applications.items()
1525
- if app.get("templateKind") not in ("route", "catalog")}
1526
  tables = _retirement_read(runtime, user_tables.STORE_KEY)
1527
  databases = {"customer_data", "product_data"} | {key for key in tables if key.startswith("ut_")}
1528
  for app in applications.values():
 
69
  APPLICATION_WIZARD_TEMPLATE_KINDS = tuple(_TEMPLATE_CONTRACTS)
70
  APPLICATION_TEMPLATE_KINDS = tuple(_TEMPLATE_CONTRACTS)
71
 
72
+ #: S78-T17 (C4, R20, R21): templates offered only to a tenant that passes the kind's gate.
73
+ #: They stay out of the ungated tuples above, which other gates pin to Routing and Catalog.
74
+ BRAND_ANALYTICS_DATABASE = "ut_amzn_brand_analytics"
75
+ _GATED_TEMPLATE_CONTRACTS = {
76
+ "competitor_watch": {
77
+ "kind": "competitor_watch",
78
+ "label": "Competitor watch",
79
+ # The screen reads the competitor watch routes; the source names the Amazon database.
80
+ "applicationType": "map",
81
+ "displayMode": "map",
82
+ "fieldRoles": [
83
+ {"key": "term", "label": "Search term", "required": True, "types": []},
84
+ ],
85
+ "defaultPlacement": {"section": "app", "order": 0},
86
+ "sourceDatabase": BRAND_ANALYTICS_DATABASE,
87
+ "sourceLabel": "Amazon brand analytics",
88
+ },
89
+ }
90
+ GATED_TEMPLATE_KINDS = tuple(_GATED_TEMPLATE_CONTRACTS)
91
+
92
+
93
+ def _template_contract(kind):
94
+ """The contract for an ungated or gated template kind, or None."""
95
+ return _TEMPLATE_CONTRACTS.get(kind) or _GATED_TEMPLATE_CONTRACTS.get(kind)
96
+
97
+
98
+ def brand_analytics_holds(connected, enabled, refused):
99
+ """R21: Amazon is connected, brand analytics is switched on and Amazon has not refused it."""
100
+ return connected is True and enabled is True and refused is not True
101
+
102
+
103
+ def _brand_analytics_refused(runtime):
104
+ """True when the mirror's last brand analytics pass was refused; unreadable is no evidence."""
105
+ try:
106
+ import duckdb
107
+ from pathlib import Path
108
+ from harness import amazon_store as az, datastore
109
+ path = az._tenant_mirror_path(runtime.key, rt=runtime)
110
+ if not path.is_file():
111
+ return False
112
+ query = "SELECT phase FROM _sync_state WHERE entity = ?"
113
+ key = [az.entity_key("brand_analytics")]
114
+ if path.resolve() == Path(datastore.DB_PATH).resolve():
115
+ row = datastore.ro_cursor().execute(query, key).fetchone()
116
+ else:
117
+ with duckdb.connect(str(path), read_only=True) as cursor:
118
+ row = cursor.execute(query, key).fetchone()
119
+ return bool(row) and row[0] == "refused"
120
+ except Exception: # noqa: BLE001
121
+ return False
122
+
123
+
124
+ def brand_analytics_offered(session):
125
+ """R21 gate for the Competitor watch template. Any read failure withholds the template."""
126
+ try:
127
+ import connectors_amazon as cx
128
+ from routes_connectors import _entry_types
129
+ types, _scopes, failure = _entry_types(session.runtime, session.uname)
130
+ connected = failure is None and cx.ENTRY_TYPE in set(types)
131
+ enablement = cx.read_database_enablement(session.runtime)
132
+ enabled = (enablement.get("available") is True
133
+ and (enablement.get("databases") or {}).get(BRAND_ANALYTICS_DATABASE) is True)
134
+ refused = _brand_analytics_refused(session.runtime) if connected and enabled else None
135
+ return brand_analytics_holds(connected, enabled, refused)
136
+ except Exception: # noqa: BLE001
137
+ return False
138
+
139
+
140
+ _TEMPLATE_GATES = {"competitor_watch": brand_analytics_offered}
141
+
142
 
143
  class ApplicationError(ValueError):
144
  pass
 
202
  return owned
203
 
204
 
205
+ def template_contracts(session=None):
206
+ """The trusted renderer contracts offered by the Application creation flow.
207
+
208
+ A gated template joins only for a session whose tenant passes its gate (R21).
209
+ """
210
+ rows = _ungated_template_contracts()
211
+ if session is not None:
212
+ rows.extend(copy.deepcopy(contract) for kind, contract in _GATED_TEMPLATE_CONTRACTS.items()
213
+ if _TEMPLATE_GATES[kind](session))
214
+ return rows
215
+
216
+
217
+ def _ungated_template_contracts():
218
  return [copy.deepcopy(contract) for contract in _TEMPLATE_CONTRACTS.values()]
219
 
220
 
 
708
 
709
  def _template_definition(kind, payload, *, semantic_records=None, field_contracts=None,
710
  allowed_databases=None):
711
+ contract = _TEMPLATE_CONTRACTS.get(kind) or _GATED_TEMPLATE_CONTRACTS.get(kind)
712
  if contract is None:
713
  raise ApplicationError("application template kind is not recognized")
714
  template_kind = str(payload.get("templateKind") or "").strip().lower()
 
717
  source = str(payload.get("sourceDatabase") or "").strip()[:120]
718
  if not source:
719
  raise ApplicationError("sourceDatabase is required")
720
+ if contract.get("sourceDatabase") and source != contract["sourceDatabase"]:
721
+ raise ApplicationError(f"{contract['label']} reads "
722
+ f"{contract.get('sourceLabel') or contract['sourceDatabase']} only. "
723
+ "Choose it as the source database.")
724
  if source not in set(allowed_databases or ()):
725
  raise PermissionError("an Application cannot bind a database you cannot open")
726
  if "compatibleDatabases" in payload:
 
791
  if "tenant" in payload and str(payload.get("tenant") or "") != str(tenant):
792
  raise PermissionError("an Application cannot be created for another tenant")
793
  template_kind = str(payload.get("templateKind") or "").strip().lower()
794
+ gated = _GATED_TEMPLATE_CONTRACTS.get(template_kind)
795
+ if gated is not None:
796
+ if str(payload.get("type") or gated["applicationType"]).strip().lower() != gated["applicationType"]:
797
+ raise ApplicationError(
798
+ f"{template_kind} template Applications require type {gated['applicationType']!r}")
799
+ return _template_definition(
800
+ template_kind, payload, semantic_records=semantic_records,
801
+ field_contracts=field_contracts, allowed_databases=allowed_databases)
802
  if template_kind and template_kind not in _TEMPLATE_CONTRACTS:
803
  raise ApplicationError("application template kind is not recognized")
804
  expected_type = (_TEMPLATE_CONTRACTS[template_kind]["applicationType"]
 
936
  """Build the same validated record for authored Apps and boot migrations."""
937
  payload=payload if isinstance(payload,dict) else {}
938
  template_kind=str(payload.get("templateKind") or "").strip().lower()
939
+ expected_type = (_template_contract(template_kind) or {}).get("applicationType")
940
  kind=str(payload.get("type") or expected_type or "").strip().lower()
941
  definition = validate_application(
942
  payload, tenant, semantic_records=semantic_records, field_contracts=field_contracts,
 
951
  raw_config = payload.get("config")
952
  if definition and raw_config is None:
953
  raw_config = {"schemaVersion": 1,
954
+ "display": {"mode": _template_contract(template_kind)["displayMode"]}}
955
  app={"id":app_id,"tenant":str(tenant),"type":kind,"name":name,
956
  "compatibleDatabases":compatible,
957
  "semanticRoleBindings":_governed_bindings(
 
960
  "share":{"mode":"private","users":[]},"starredBy":[],"createdBy":user,
961
  "createdAt":now,"updatedAt":now,"revision":1}
962
  app.update(definition)
963
+ if definition and _template_contract(template_kind).get("deepLink"):
964
+ app["deepLink"] = _template_contract(template_kind)["deepLink"].replace("<id>", app_id)
965
  if kind == "code":
966
  app.update(deepLink=f"/app/code/{app_id}", origin=None)
967
  app["origin"] = _server_origin(origin_door, via)
 
1330
  if not _is_finance(app) and not _allowed(app.get("compatibleDatabases"), allowed_databases):
1331
  if not _database_free_code(app):
1332
  raise ApplicationError("application does not exist")
1333
+ if (app.get("templateKind") in APPLICATION_TEMPLATE_KINDS + GATED_TEMPLATE_KINDS
1334
+ and "compatibleDatabases" in patch):
1335
  raise ApplicationError("a template Application's sourceDatabase is immutable")
1336
  star_only = set(patch) <= {"starred"}
1337
  if star_only:
 
1616
  for app in applications.values()):
1617
  raise ApplicationError("the Application registry has an invalid tenant record")
1618
  removed = {identity: app for identity, app in applications.items()
1619
+ if app.get("templateKind") not in ("route", "catalog", *GATED_TEMPLATE_KINDS)}
1620
  tables = _retirement_read(runtime, user_tables.STORE_KEY)
1621
  databases = {"customer_data", "product_data"} | {key for key in tables if key.startswith("ut_")}
1622
  for app in applications.values():
api/catalog_store.py CHANGED
@@ -381,3 +381,100 @@ def delete_catalog(session, catalog_id):
381
  return {"deleted": catalog_id}
382
 
383
  return _update(session.runtime, apply)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
381
  return {"deleted": catalog_id}
382
 
383
  return _update(session.runtime, apply)
384
+
385
+
386
+ # Long PDF exports: an MCP caller polls one of these through operation_status.
387
+ EXPORT_KEY = "catalog_exports_v1"
388
+ EXPORT_RETENTION_SECONDS = 24 * 3600
389
+ # A running export older than this lost its worker (a restart), so it reads as failed.
390
+ EXPORT_STALE_SECONDS = 30 * 60
391
+
392
+
393
+ def _export_bindings(session):
394
+ from routes_external import _operation_bindings
395
+ return _operation_bindings(session)
396
+
397
+
398
+ def _exports(raw, now):
399
+ doc = raw if isinstance(raw, dict) and isinstance(raw.get("exports"), dict) else {"exports": {}}
400
+ doc = copy.deepcopy(doc)
401
+ doc["exports"] = {key: value for key, value in doc["exports"].items()
402
+ if isinstance(value, dict) and float(value.get("retainUntil") or 0) >= now}
403
+ return doc
404
+
405
+
406
+ def start_export(session, catalog_id):
407
+ """Record a running export bound to this caller's account and connection, and return its id."""
408
+ import secrets
409
+ import time
410
+
411
+ operation_id = secrets.token_hex(32)
412
+ now = time.time()
413
+ item = {"bindings": _export_bindings(session), "catalogId": catalog_id, "status": "running",
414
+ "startedAt": now, "retainUntil": now + EXPORT_RETENTION_SECONDS}
415
+
416
+ def apply(raw):
417
+ doc = _exports(raw, now)
418
+ doc["exports"][operation_id] = item
419
+ return doc
420
+
421
+ session.runtime.update(EXPORT_KEY, apply, flush="sync")
422
+ return operation_id
423
+
424
+
425
+ def _export_error(error):
426
+ from fastapi import HTTPException
427
+ from core import sheets
428
+
429
+ if isinstance(error, sheets.SheetRefusal):
430
+ return {"code": error.code, "message": error.message, "status": 409}
431
+ if isinstance(error, HTTPException) and isinstance(error.detail, dict):
432
+ info = error.detail.get("error") or {}
433
+ if isinstance(info.get("code"), str) and isinstance(info.get("message"), str):
434
+ return {"code": info["code"], "message": info["message"], "status": error.status_code}
435
+ return {"code": "catalog_export_failed", "status": 503,
436
+ "message": "The PDF export did not finish. Call apps.catalog_pdf again with the same catalog_id."}
437
+
438
+
439
+ def finish_export(session, operation_id, result, error=None):
440
+ """Store the worker's outcome on its export record."""
441
+ import time
442
+
443
+ now = time.time()
444
+
445
+ def apply(raw):
446
+ doc = _exports(raw, now)
447
+ item = doc["exports"].get(operation_id)
448
+ if item is not None:
449
+ item.update(status="failed" if error is not None else "done", finishedAt=now,
450
+ retainUntil=now + EXPORT_RETENTION_SECONDS)
451
+ if error is not None:
452
+ item["error"] = _export_error(error)
453
+ else:
454
+ item["result"] = copy.deepcopy(result)
455
+ return doc
456
+
457
+ session.runtime.update(EXPORT_KEY, apply, flush="sync")
458
+
459
+
460
+ def export_status(session, operation_id):
461
+ """Read this caller's export by id, or None when no export of theirs has that id."""
462
+ import time
463
+
464
+ now = time.time()
465
+ try:
466
+ raw = session.runtime.get(EXPORT_KEY, fresh=True)
467
+ except Exception:
468
+ # The confirmation read that follows reports an unavailable store with its own code.
469
+ return None
470
+ item = _exports(raw, now)["exports"].get(operation_id)
471
+ if not isinstance(item, dict) or item.get("bindings") != _export_bindings(session):
472
+ return None
473
+ base = {"operation_id": operation_id, "catalog_id": item.get("catalogId")}
474
+ if item.get("status") == "done":
475
+ return {**copy.deepcopy(item["result"]), **base, "state": "done", "retry": False}
476
+ if item.get("status") == "failed" or now - float(item.get("startedAt") or 0) > EXPORT_STALE_SECONDS:
477
+ error = item.get("error") or _export_error(None)
478
+ return {**base, "ok": False, "state": "failed", "retry": False, "error": copy.deepcopy(error)}
479
+ return {**base, "state": "running", "retry": True,
480
+ "message": "The PDF is still rendering. Call operation_status again shortly."}
api/connectors_amazon.py CHANGED
@@ -534,7 +534,7 @@ def sync_state(rt, tenant_key, *, cadence_seconds=None, now=None):
534
  if plan is None and landed.get("phase") not in ("refused", "failed", "throttled"):
535
  unknown.append("The sync schedule is unknown because a saved timestamp could not be read. Retry sync to refresh it.")
536
  limit = None
537
- if (table in az.GROUP_A_TABLES and table != "catalog_items") or table == "transactions":
538
  marker = entities.get(az.entity_key("limit_" + table)) or {}
539
  try:
540
  limit = json.loads(marker.get("cursor") or "{}").get("reason")
@@ -594,7 +594,7 @@ def sync_state(rt, tenant_key, *, cadence_seconds=None, now=None):
594
  "stuck": stuck, "stuckCause": stuck_cause,
595
  "unknownCause": " ".join(unknown),
596
  }
597
- if table == az.SQP_TABLE or table in az.GROUP_A_TABLES or table == "transactions":
598
  answer[table]["limit"] = limit
599
  answer["sku_keywords"] = {
600
  "rowsLoaded": mirrored.get("sku_keywords"),
 
534
  if plan is None and landed.get("phase") not in ("refused", "failed", "throttled"):
535
  unknown.append("The sync schedule is unknown because a saved timestamp could not be read. Retry sync to refresh it.")
536
  limit = None
537
+ if (table in az.GROUP_A_TABLES and table != "catalog_items") or table in ("transactions", "brand_analytics"):
538
  marker = entities.get(az.entity_key("limit_" + table)) or {}
539
  try:
540
  limit = json.loads(marker.get("cursor") or "{}").get("reason")
 
594
  "stuck": stuck, "stuckCause": stuck_cause,
595
  "unknownCause": " ".join(unknown),
596
  }
597
+ if table == az.SQP_TABLE or table in az.GROUP_A_TABLES or table in ("transactions", "brand_analytics"):
598
  answer[table]["limit"] = limit
599
  answer["sku_keywords"] = {
600
  "rowsLoaded": mirrored.get("sku_keywords"),
api/external_freshness.py CHANGED
@@ -59,27 +59,64 @@ def _sync_date(value):
59
  return None
60
 
61
 
62
- def amazon_sync_stamp(cur, table_key):
63
- """Read a table's last successful source pass before its legacy raw-table receipt."""
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
64
  import amazon_relational
65
 
66
  raw = amazon_relational.SOURCE.get(table_key)
67
- if not raw or cur is None:
68
  return None
69
- marker = "amzn_sync_mark_" + raw.removeprefix("amzn_")
70
- for entity in (marker, raw):
71
- row = cur.execute("SELECT updated_at FROM _sync_state WHERE entity = ? AND phase = 'done'",
72
- [entity]).fetchone()
73
- if row:
74
- return row[0]
75
- return None
 
 
 
 
76
 
77
 
78
  def _amazon_refreshes(session, keys):
79
  """Read only sync metadata for the authorized Amazon databases on this tenant's cursor."""
80
  import assistant_mirror
81
 
82
- cur, refreshed = None, {}
83
  for key in keys:
84
  try:
85
  if cur is None:
@@ -87,12 +124,61 @@ def _amazon_refreshes(session, keys):
87
  if refusal is not None or cur is None:
88
  cur = None
89
  continue
90
- refreshed[key] = amazon_sync_stamp(cur, key)
 
 
91
  except Exception:
92
  continue
93
  return refreshed
94
 
95
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
96
  def _mirror_refreshes(session, definitions, keys):
97
  """Read authorized mirror stamps with cached successful cursors and no product-row reads."""
98
  import assistant_mirror
 
59
  return None
60
 
61
 
62
+ #: S78-T02 (R11): a monthly reconciliation proof, `amzn_reconcile_<table>_<yyyy>_<mm>`.
63
+ _PERIOD_PROOF = re.compile(r"_\d{4}_\d{2}")
64
+ #: A derived view is as fresh as its oldest input. ⛔ Never fresher than the data it reads.
65
+ _AMAZON_DERIVED_INPUTS = {"sku_keywords": ("listing_items", "search_query_performance")}
66
+ #: A derived table whose rows arrive by an import with its own receipt.
67
+ _AMAZON_DERIVED_RECEIPTS = {"keyword_ranks": "amzn_apify_keyword_ranks"}
68
+
69
+
70
+ def amazon_sync_state(cur):
71
+ """`{entity: updated_at}` for every `done` Amazon `_sync_state` row, in one read."""
72
+ return {str(entity): at for entity, at in cur.execute(
73
+ "SELECT entity, updated_at FROM _sync_state "
74
+ "WHERE phase = 'done' AND starts_with(entity, 'amzn_')").fetchall()}
75
+
76
+
77
+ def _amazon_table_stamp(state, table):
78
+ """The mark, else the legacy raw receipt, else the newest reconciliation proof, or None.
79
+
80
+ ⛔ `sync_tick_` is never a receipt: a refused pass also writes it `done`.
81
+ """
82
+ for entity in ("amzn_sync_mark_" + table, "amzn_" + table):
83
+ if state.get(entity) is not None:
84
+ return state[entity]
85
+ proof = "amzn_reconcile_" + table
86
+ return _latest(*(at for entity, at in state.items()
87
+ if entity == proof or entity.startswith(proof + "_")
88
+ and _PERIOD_PROOF.fullmatch(entity[len(proof):])))
89
+
90
+
91
+ def amazon_sync_stamp(cur, table_key, state=None):
92
+ """A table's true last successful sync from its `_sync_state` receipts, or None.
93
+
94
+ R11: a refusal overwrites the raw receipt and a pass with no window writes no mark, so the
95
+ reconciliation proofs also count. The time is the receipt's own, never a restore or read time.
96
+ """
97
  import amazon_relational
98
 
99
  raw = amazon_relational.SOURCE.get(table_key)
100
+ if not raw or (cur is None and state is None):
101
  return None
102
+ if state is None:
103
+ state = amazon_sync_state(cur)
104
+ table = raw.removeprefix("amzn_")
105
+ if table in _AMAZON_DERIVED_RECEIPTS:
106
+ return state.get(_AMAZON_DERIVED_RECEIPTS[table])
107
+ if table in _AMAZON_DERIVED_INPUTS:
108
+ stamps = [stamp for name in _AMAZON_DERIVED_INPUTS[table]
109
+ if (stamp := utc_stamp(_amazon_table_stamp(state, name))) is not None]
110
+ return min(stamps, key=lambda stamp: datetime.fromisoformat(stamp.replace("Z", "+00:00"))) \
111
+ if stamps else None
112
+ return _amazon_table_stamp(state, table)
113
 
114
 
115
  def _amazon_refreshes(session, keys):
116
  """Read only sync metadata for the authorized Amazon databases on this tenant's cursor."""
117
  import assistant_mirror
118
 
119
+ cur, state, refreshed = None, None, {}
120
  for key in keys:
121
  try:
122
  if cur is None:
 
124
  if refusal is not None or cur is None:
125
  cur = None
126
  continue
127
+ if state is None:
128
+ state = amazon_sync_state(cur)
129
+ refreshed[key] = amazon_sync_stamp(cur, key, state=state)
130
  except Exception:
131
  continue
132
  return refreshed
133
 
134
 
135
+ def amazon_nav(session, pages):
136
+ """Add `group` and `sync` to each Amazon nav row in place; returns `pages`. Never raises.
137
+
138
+ `sync` is `{"at": <UTC stamp> | None, "empty": bool | None}` and is read on the request,
139
+ never stored: one `_sync_state` read and one EXISTS per mirror table, no product value.
140
+ It is absent when the mirror cannot answer, so "unknown" never reads as "never synced".
141
+ """
142
+ try:
143
+ from core import connector_spec
144
+ rows = [page for page in pages if str(page.get("key") or "").startswith("ut_amzn_")]
145
+ for page in rows:
146
+ group = connector_spec.table_group(page["key"])
147
+ if group:
148
+ page["group"] = group
149
+ if not rows:
150
+ return pages
151
+ import amazon_relational
152
+ import assistant_mirror
153
+
154
+ cur, refusal = assistant_mirror.open_cursor(session, rows[0]["key"])
155
+ if refusal is not None or cur is None:
156
+ return pages
157
+ state = amazon_sync_state(cur)
158
+ if not state:
159
+ # An unrestored or absent mirror holds no receipt at all: unknown, not never synced.
160
+ return pages
161
+ bases = {str(name) for (name,) in cur.execute(
162
+ "SELECT table_name FROM information_schema.tables WHERE table_schema = 'main' "
163
+ "AND table_type = 'BASE TABLE' AND starts_with(table_name, 'amzn_')").fetchall()}
164
+ raws = {page["key"]: amazon_relational.SOURCE.get(page["key"]) for page in rows}
165
+ probed = sorted({raw for raw in raws.values() if raw in bases})
166
+ held = {}
167
+ if probed:
168
+ held = {str(name): bool(has) for name, has in cur.execute(" UNION ALL ".join(
169
+ f"SELECT '{raw}' AS name, EXISTS (SELECT 1 FROM \"{raw}\") AS has"
170
+ for raw in probed)).fetchall()}
171
+ for page in rows:
172
+ raw = raws.get(page["key"])
173
+ if not raw:
174
+ continue
175
+ stamp = utc_stamp(amazon_sync_stamp(cur, page["key"], state=state))
176
+ page["sync"] = {"at": stamp, "empty": (not held[raw]) if raw in held else None}
177
+ except Exception:
178
+ pass
179
+ return pages
180
+
181
+
182
  def _mirror_refreshes(session, definitions, keys):
183
  """Read authorized mirror stamps with cached successful cursors and no product-row reads."""
184
  import assistant_mirror
api/loopy_catalog_tools.py CHANGED
@@ -172,7 +172,8 @@ def catalog_build(ctx, args):
172
  keys = [str(row.get(mapping["key"], "")).strip() if row.get(mapping["key"]) is not None else "" for row in rows]
173
  if any(not key for key in keys) or len(set(keys)) != len(keys):
174
  _build_refusal("catalog_key_ambiguous", "Products need distinct nonempty source keys. Rebind the App's record key before building.")
175
- name = args.get("name") or _no_dashes(str(title or "Catalog"))[:120]
 
176
  kinds = ["cover", "toc", *(["product"] * len(rows)), "closing"]
177
  pages = []
178
  for kind in kinds:
@@ -241,13 +242,101 @@ def catalog_pdf(session, args):
241
  mcp = (getattr(session, "claims", None) or {}).get("external") is True
242
  link = (assistant_files.capability_url(session.runtime, saved["id"])
243
  if door == "whatsapp" and not mcp else saved["link"])
244
- return {"ok": True, "fileId": saved["id"], "link": _secure_link(link),
245
- "message": "Catalog PDF ready"}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
246
 
247
 
248
  def _schema():
249
  return {"type": "object",
250
- "description": "Make a PDF of a stored catalog's designed pages and product images. Returns fileId and link for a person to send. This tool does not send.",
 
 
 
251
  "properties": {"catalog_id": {"type": "string", "minLength": 1, "maxLength": 256}},
252
  "required": ["catalog_id"],
253
  "additionalProperties": False}
 
172
  keys = [str(row.get(mapping["key"], "")).strip() if row.get(mapping["key"]) is not None else "" for row in rows]
173
  if any(not key for key in keys) or len(set(keys)) != len(keys):
174
  _build_refusal("catalog_key_ambiguous", "Products need distinct nonempty source keys. Rebind the App's record key before building.")
175
+ # The store refuses long dashes in a name, so normalise an AI's name before the preview.
176
+ name = _no_dashes(str(args.get("name") or title or "Catalog")).strip()[:120] or "Catalog"
177
  kinds = ["cover", "toc", *(["product"] * len(rows)), "closing"]
178
  pages = []
179
  for kind in kinds:
 
242
  mcp = (getattr(session, "claims", None) or {}).get("external") is True
243
  link = (assistant_files.capability_url(session.runtime, saved["id"])
244
  if door == "whatsapp" and not mcp else saved["link"])
245
+ result = {"ok": True, "fileId": saved["id"], "link": _secure_link(link),
246
+ "message": "Catalog PDF ready"}
247
+ if mcp:
248
+ result.update(external_download(saved["id"], len(data)))
249
+ else:
250
+ # Declared provenance keeps the Assistant turn from marking this artifact unknown.
251
+ result["sources"] = [app["sourceDatabase"]]
252
+ return result
253
+
254
+
255
+ EXTERNAL_FILES_PATH = "/api/v1/external/files/"
256
+ FILE_RESOURCE_PREFIX = "loopable://files/"
257
+
258
+
259
+ def external_download(file_id, size):
260
+ """Name the two credential-bound ways an MCP caller fetches the PDF bytes."""
261
+ from loopy_file_tools import _links, _secure_link
262
+
263
+ base = _links().public_base()
264
+ return {"mime": "application/pdf", "bytes": size,
265
+ "downloadUrl": _secure_link((base or "") + EXTERNAL_FILES_PATH + file_id),
266
+ "resourceUri": FILE_RESOURCE_PREFIX + file_id,
267
+ "download": ("GET downloadUrl with this connection's Authorization header, "
268
+ "or read resourceUri with MCP resources/read. Both return application/pdf.")}
269
+
270
+
271
+ # A render past this many seconds answers with an operation_id instead of holding the call.
272
+ EXPORT_BUDGET_SECONDS = 20.0
273
+
274
+
275
+ def export_budget():
276
+ import os
277
+ try:
278
+ value = float(os.environ.get("AIOS_CATALOG_PDF_BUDGET_SECONDS", "") or EXPORT_BUDGET_SECONDS)
279
+ except ValueError:
280
+ value = EXPORT_BUDGET_SECONDS
281
+ return value if value > 0 else EXPORT_BUDGET_SECONDS
282
+
283
+
284
+ def catalog_pdf_within_budget(session, args, render=None, budget=None):
285
+ """Render in a worker thread. Past the budget, return an operation_id that operation_status reads."""
286
+ import contextvars
287
+ import sys
288
+ import threading
289
+ import catalog_store
290
+
291
+ render = render or sys.modules[__name__].catalog_pdf
292
+ budget = export_budget() if budget is None else budget
293
+ lock = threading.Lock()
294
+ state = {"finished": False, "operation_id": None}
295
+
296
+ def work():
297
+ try:
298
+ outcome = (render(session, args), None)
299
+ except BaseException as exc: # The caller or the export record receives every failure.
300
+ outcome = (None, exc)
301
+ with lock:
302
+ state.update(finished=True, outcome=outcome)
303
+ operation_id = state["operation_id"]
304
+ if operation_id is not None:
305
+ try:
306
+ catalog_store.finish_export(session, operation_id, *outcome)
307
+ except Exception as exc:
308
+ # The record then reads as failed once it is stale, so the caller retries.
309
+ import logging
310
+ logging.getLogger(__name__).warning("Catalog export result not saved (%s)", type(exc).__name__)
311
+
312
+ context = contextvars.copy_context()
313
+ worker = threading.Thread(target=context.run, args=(work,), daemon=True, name="catalog-pdf")
314
+ try:
315
+ worker.start()
316
+ except Exception:
317
+ # No worker can start here, so the call renders inline and holds until it finishes.
318
+ return render(session, args)
319
+ worker.join(budget)
320
+ with lock:
321
+ if state["finished"]:
322
+ result, error = state["outcome"]
323
+ if error is not None:
324
+ raise error
325
+ return result
326
+ # The worker waits on this lock, so it reads the id after the record exists.
327
+ state["operation_id"] = catalog_store.start_export(session, args["catalog_id"])
328
+ return {"operation_id": state["operation_id"], "state": "running", "retry": True,
329
+ "catalog_id": args["catalog_id"],
330
+ "message": ("The PDF is still rendering. Call table with action operation_status and this "
331
+ "operation_id until state is done. The done result carries fileId, link and downloadUrl.")}
332
 
333
 
334
  def _schema():
335
  return {"type": "object",
336
+ "description": ("Make a PDF of a stored catalog's designed pages and product images. Use the catalog_id that "
337
+ "catalog_build returned after confirm_change. Returns fileId and link for a person to send. "
338
+ "An MCP call also gets downloadUrl and resourceUri for the bytes, or an operation_id to poll "
339
+ "with operation_status when the render is slow. This tool does not send."),
340
  "properties": {"catalog_id": {"type": "string", "minLength": 1, "maxLength": 256}},
341
  "required": ["catalog_id"],
342
  "additionalProperties": False}
api/loopy_links.py CHANGED
@@ -6,12 +6,37 @@ import re
6
  from urllib.parse import quote, urlsplit
7
 
8
  FRAGMENT = re.compile(r"(?<![\w/])#/[a-z]")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9
 
10
 
11
  def public_base() -> str | None:
12
- """Return the configured HTTPS base without guessing a production host."""
13
- base = (os.environ.get("AIOS_PUBLIC_BASE", "").strip()
14
- or os.environ.get("APP_BASE_URL", "").strip()).rstrip("/")
 
 
 
 
 
 
 
 
 
 
15
  if (not base or any(char.isspace() or ord(char) < 32 for char in base)
16
  or any(char in base for char in "\\?#")):
17
  return None
 
6
  from urllib.parse import quote, urlsplit
7
 
8
  FRAGMENT = re.compile(r"(?<![\w/])#/[a-z]")
9
+ # C3: the live deployment's canonical address. Its Space host is never a link target.
10
+ LIVE_BASE = "https://runloopable.com"
11
+
12
+
13
+ def _deployment_base() -> str | None:
14
+ """Answer the base this container's own identity implies, or None off a Space."""
15
+ try:
16
+ from core import data_binding
17
+ except ImportError:
18
+ return None
19
+ if data_binding.is_production_deployment():
20
+ return LIVE_BASE
21
+ # HF sets SPACE_HOST inside a Space. An identity alone (a gate box) implies no host.
22
+ host = os.environ.get("SPACE_HOST", "").strip().rstrip("/")
23
+ return _checked_base("https://" + host) if host and data_binding.deployment_id() else None
24
 
25
 
26
  def public_base() -> str | None:
27
+ """Return the configured HTTPS base, else the deployment's own. Live never answers *.hf.space."""
28
+ configured = _checked_base(os.environ.get("AIOS_PUBLIC_BASE", "").strip()
29
+ or os.environ.get("APP_BASE_URL", "").strip())
30
+ identity = _deployment_base()
31
+ if configured is not None and not (
32
+ identity == LIVE_BASE and (urlsplit(configured).hostname or "").endswith(".hf.space")):
33
+ return configured
34
+ return identity
35
+
36
+
37
+ def _checked_base(base: str) -> str | None:
38
+ """Accept one HTTPS origin with an optional path and nothing else."""
39
+ base = (base or "").strip().rstrip("/")
40
  if (not base or any(char.isspace() or ord(char) < 32 for char in base)
41
  or any(char in base for char in "\\?#")):
42
  return None
api/main.py CHANGED
@@ -45,6 +45,7 @@ from starlette.exceptions import HTTPException as StarletteHTTPException # noqa
45
 
46
  import aios_session # noqa: E402
47
  import routes_admin # noqa: E402
 
48
  import routes_alerts # noqa: E402 (wave 20 item 25 — the Alerts inbox)
49
  import routes_assets # noqa: E402 (wave 18 C2-ASSET — catalog product imagery)
50
  import routes_auth # noqa: E402
@@ -549,7 +550,10 @@ app.include_router(routes_tickets.router)
549
  # rate-limited by POLITENESS rather than by a bill (~1 req/s, and bulk harvesting is forbidden).
550
  app.include_router(routes_geo.router) # R14 / A11 — D's router, A's line (map providers)
551
  app.include_router(routes_external.router)
 
552
  _mount_router("routes_security") # W59-T43: lane F declares the router; keep before static mount.
 
 
553
 
554
 
555
  # --- DEPRECATED ALIASES (removed when S2's shell flips; kept so the current bundle keeps working)
 
45
 
46
  import aios_session # noqa: E402
47
  import routes_admin # noqa: E402
48
+ import routes_competitor_watch # noqa: E402 (S78-T16 / S78-T17 competitor watch)
49
  import routes_alerts # noqa: E402 (wave 20 item 25 — the Alerts inbox)
50
  import routes_assets # noqa: E402 (wave 18 C2-ASSET — catalog product imagery)
51
  import routes_auth # noqa: E402
 
550
  # rate-limited by POLITENESS rather than by a bill (~1 req/s, and bulk harvesting is forbidden).
551
  app.include_router(routes_geo.router) # R14 / A11 — D's router, A's line (map providers)
552
  app.include_router(routes_external.router)
553
+ app.include_router(routes_competitor_watch.router) # S78-T16 / S78-T17 competitor watch
554
  _mount_router("routes_security") # W59-T43: lane F declares the router; keep before static mount.
555
+ _mount_router("routes_amazon_profit") # S78-T03: the Amazon SKU profit refresh and settings doors.
556
+ _mount_router("routes_odoo_attachments") # S78-T14 (lane G, C5): delivery photo doors; before static mount.
557
 
558
 
559
  # --- DEPRECATED ALIASES (removed when S2's shell flips; kept so the current bundle keeps working)
api/odoo_attachments.py ADDED
@@ -0,0 +1,103 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Odoo delivery photos (S78-T14, contract C5): list and stream a picking's image attachments.
2
+
3
+ AntsRoute stores each proof-of-delivery photo as an `ir.attachment` on `stock.picking`. It has no
4
+ photo field of its own, only the `antsroute_nb_delivery_photo` count.
5
+ Rule 4: Odoo is read with `search_read` only. Rule 1: every photo of the picking is listed.
6
+ The bytes pass through the response and are never stored.
7
+ The caller's read wall on the delivery databases is checked BEFORE any photo byte is read.
8
+ """
9
+ import base64
10
+ import binascii
11
+
12
+ from deps import err
13
+
14
+ ATTACHMENT_MODEL = "ir.attachment"
15
+ PICKING_MODEL = "stock.picking"
16
+ #: Raster types only. An SVG can carry script, so it is never served from our origin.
17
+ IMAGE_TYPES = ("image/jpeg", "image/png", "image/gif", "image/webp")
18
+ _META_FIELDS = ["id", "name", "mimetype", "res_model", "res_id", "type"]
19
+
20
+
21
+ def attachment_path(attachment_id):
22
+ """The C5 bytes path for one attachment."""
23
+ return f"/api/v1/odoo/attachments/{int(attachment_id)}"
24
+
25
+
26
+ def _search_read(session, model, domain, fields, **kw):
27
+ """One read through the caller's tenant Odoo connection."""
28
+ from core import odoo
29
+ source = session.runtime.odoo_source()
30
+ if source is None:
31
+ raise err(409, "odoo_not_connected", "Connect Odoo in Settings to see delivery photos.")
32
+ with source._bound():
33
+ return odoo.search_read(model, domain, fields, **kw)
34
+
35
+
36
+ def _wall_admits(session, key, picking_id):
37
+ """True when the caller's read wall on `key` returns the picking's row."""
38
+ import routes_odoo_tables as rot
39
+ page = rot.odoo_table_rows(key, offset=0, limit=1, filters=None, filterConj="and",
40
+ sorts=None, search=None, related=None, groupBy=None,
41
+ groupKey=None, session=session, body={"ids": [int(picking_id)]})
42
+ return any(int(row.get("pid", -1)) == int(picking_id) for row in page.get("rows") or [])
43
+
44
+
45
+ def require_delivery_read(session, picking_id, key_allowed=None):
46
+ """Return the delivery database key that admits the caller, or raise 403.
47
+
48
+ A 403 or 404 from one key falls through to the next. `key_allowed(key)` may raise 403 to
49
+ narrow the keys further, as an MCP credential's database scope does.
50
+ """
51
+ import odoo_relational as rel
52
+ other = None
53
+ for key in rel.DELIVERY_KEYS:
54
+ try:
55
+ if key_allowed is not None:
56
+ key_allowed(key)
57
+ if _wall_admits(session, key, picking_id):
58
+ return key
59
+ except Exception as exc: # noqa: BLE001
60
+ status = getattr(exc, "status_code", None)
61
+ if status in (403, 404):
62
+ continue
63
+ other = other or exc
64
+ if other is not None:
65
+ raise other
66
+ raise err(403, "delivery_read_forbidden",
67
+ "You cannot read this delivery, so ask an admin for access to Odoo shipments.")
68
+
69
+
70
+ def _photo(row, base=""):
71
+ return {"id": int(row["id"]), "name": str(row.get("name") or ""),
72
+ "mimetype": str(row.get("mimetype") or ""), "url": base + attachment_path(row["id"])}
73
+
74
+
75
+ def list_photos(session, picking_id, key_allowed=None, base=""):
76
+ """Every image attachment of one picking, oldest first, after the read wall passes."""
77
+ require_delivery_read(session, picking_id, key_allowed)
78
+ rows = _search_read(session, ATTACHMENT_MODEL, [
79
+ ("res_model", "=", PICKING_MODEL), ("res_id", "=", int(picking_id)),
80
+ ("type", "=", "binary"), ("mimetype", "in", list(IMAGE_TYPES)),
81
+ ], ["id", "name", "mimetype"], order="id asc")
82
+ return [_photo(row, base) for row in rows or []]
83
+
84
+
85
+ def read_photo(session, attachment_id):
86
+ """`(bytes, mimetype, name)` of one delivery photo. The bytes are read only after the wall."""
87
+ meta = _search_read(session, ATTACHMENT_MODEL, [("id", "=", int(attachment_id))], _META_FIELDS)
88
+ row = (meta or [None])[0]
89
+ res_id = row.get("res_id") if row else None
90
+ if (not row or row.get("res_model") != PICKING_MODEL or row.get("type") != "binary"
91
+ or row.get("mimetype") not in IMAGE_TYPES or isinstance(res_id, bool)
92
+ or not isinstance(res_id, int) or res_id <= 0):
93
+ raise err(404, "photo_not_found", "This delivery photo was not found.")
94
+ require_delivery_read(session, res_id)
95
+ data = _search_read(session, ATTACHMENT_MODEL, [("id", "=", int(attachment_id))], ["datas"])
96
+ raw = (data or [{}])[0].get("datas")
97
+ if not raw:
98
+ raise err(404, "photo_not_found", "This delivery photo has no image data.")
99
+ try:
100
+ body = base64.b64decode(raw, validate=False)
101
+ except (binascii.Error, ValueError, TypeError):
102
+ raise err(502, "photo_unreadable", "Odoo sent a photo that could not be read.")
103
+ return body, row["mimetype"], str(row.get("name") or f"photo-{int(attachment_id)}")
api/odoo_relational.py CHANGED
@@ -106,6 +106,9 @@ from odoo_purchasing import (ORDERS_KEY as PURCHASE_ORDERS_KEY, LINES_KEY as PUR
106
  source_specs as purchase_source_specs,
107
  validate as validate_purchasing)
108
 
 
 
 
109
  #: The join column the partner-grain tables carry. Derived links resolve through it (`on`/`from`).
110
  JOIN_KEY = "partner_id"
111
  #: The product-grain equivalent.
 
106
  source_specs as purchase_source_specs,
107
  validate as validate_purchasing)
108
 
109
+ #: S78-T14: the databases whose row id is a `stock.picking` id. Their read wall admits a delivery photo.
110
+ DELIVERY_KEYS = (SHIPMENTS_KEY, PICKINGS_KEY)
111
+
112
  #: The join column the partner-grain tables carry. Derived links resolve through it (`on`/`from`).
113
  JOIN_KEY = "partner_id"
114
  #: The product-grain equivalent.
api/routes_amazon_profit.py ADDED
@@ -0,0 +1,200 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Amazon SKU profit doors: read the settings, switch the period, recompute, set the owner,
2
+ and confirm or reject a suggested Odoo match.
3
+
4
+ The table itself (`ut_amazon_sku_profit`) is read and edited through the ordinary table doors.
5
+ A refresh rewrites only computed columns, so owner, status and due date survive a period switch.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from typing import Any
11
+
12
+ from fastapi import APIRouter, Body, Depends, HTTPException
13
+
14
+ from deps import Session, err, require_session
15
+ from modules import amazon_profit
16
+
17
+ router = APIRouter(prefix="/api/v1")
18
+
19
+
20
+ def _admin(session):
21
+ if not session.admin:
22
+ raise err(403, "forbidden", "Only an Administrator can refresh Amazon SKU profit.")
23
+
24
+
25
+ def _may_edit(session):
26
+ """Editors and Administrators of the table; a viewer reads only."""
27
+ import core.user_tables as ut
28
+ return bool(session.admin) or ut.may_edit_database(
29
+ amazon_profit.TABLE_KEY, session.uname, is_admin=session.admin, st=session.runtime)
30
+
31
+
32
+ def _cost_reader(runtime):
33
+ """Odoo cost for linked references, bound to this tenant's own read-only connection."""
34
+ def read(codes):
35
+ source = runtime.odoo_source()
36
+ if source is None:
37
+ return {}, [f"{code}: this workspace has no Odoo connection" for code in sorted(codes)]
38
+ try:
39
+ with source._bound():
40
+ return amazon_profit.odoo_costs(codes)
41
+ except amazon_profit.SourceUnavailable:
42
+ raise
43
+ except Exception as exc: # noqa: BLE001
44
+ raise amazon_profit.SourceUnavailable(
45
+ f"The Odoo cost read failed ({type(exc).__name__}). Try again.") from None
46
+ return read
47
+
48
+
49
+ def _mirror(runtime):
50
+ """A private read cursor on this tenant's mirror. Amazon readiness is its own table check,
51
+ not the Odoo backfill gate `ro_con` waits on, so this asserts the tenant and opens a cursor."""
52
+ from harness import datastore as DS
53
+ from harness import runtime as R
54
+ from pathlib import Path
55
+ try:
56
+ runtime.assert_datastore_matches()
57
+ if not Path(runtime.datastore_path).is_file():
58
+ raise err(503, "amazon_source_unavailable", "This workspace has no Amazon data yet.")
59
+ return DS.ro_cursor()
60
+ except R.DatastoreMismatch:
61
+ raise err(500, "store_mismatch", "This workspace is reading another workspace's data.") from None
62
+ except RuntimeError:
63
+ raise err(503, "store_not_ready", "Amazon data is still loading. Try again shortly.") from None
64
+
65
+
66
+ @router.get("/amazon-profit")
67
+ def profit_status(session: Session = Depends(require_session)):
68
+ """The current period, thin threshold, last refresh and owner setting, with the choices."""
69
+ import core.user_tables as ut
70
+ settings = amazon_profit.read_settings(session.runtime)
71
+ return {"tableKey": amazon_profit.TABLE_KEY,
72
+ "tableExists": ut.get_one(amazon_profit.TABLE_KEY, session.runtime) is not None,
73
+ "period": amazon_profit.period_bounds(settings["period"]),
74
+ "thin": settings["thin"],
75
+ "refreshedAt": settings.get("refreshedAt"),
76
+ "skus": settings.get("skus"),
77
+ "linked": settings.get("linked"),
78
+ "verifiedMonth": settings.get("verifiedMonth"),
79
+ "refusal": settings.get("refusal"),
80
+ "defaultOwner": settings["defaultOwner"],
81
+ "periods": amazon_profit.period_choices(),
82
+ "statuses": list(amazon_profit.STATUSES),
83
+ "matchStates": list(amazon_profit.MATCH_STATES),
84
+ "matchedAt": settings.get("matchedAt"),
85
+ "matches": settings.get("matches"),
86
+ "matchError": settings.get("matchError"),
87
+ "dueDays": amazon_profit.DUE_DAYS,
88
+ "reopenDays": amazon_profit.REOPEN_DAYS,
89
+ "canEdit": _may_edit(session),
90
+ "canAdmin": bool(session.admin)}
91
+
92
+
93
+ def _recompute(session, period=None, thin=None):
94
+ """Run one refresh through the tenant's mirror and Odoo cost read; 409 on a failed tie."""
95
+ try:
96
+ if period is not None:
97
+ amazon_profit.period_bounds(period)
98
+ if thin is not None:
99
+ amazon_profit.clean_thin(thin)
100
+ except ValueError as exc:
101
+ raise err(400, "invalid_setting", str(exc)) from None
102
+ con = _mirror(session.runtime)
103
+ try:
104
+ report = amazon_profit.refresh(session.runtime, con, period=period, thin=thin,
105
+ by=session.uname, cost_reader=_cost_reader(session.runtime),
106
+ tenant=session.tenant)
107
+ except amazon_profit.SourceUnavailable as exc:
108
+ raise err(503, "amazon_source_unavailable", str(exc)) from None
109
+ except amazon_profit.TableRefused as exc:
110
+ raise err(409, "table_refused", str(exc)) from None
111
+ except ValueError as exc:
112
+ raise err(400, "invalid_setting", str(exc)) from None
113
+ finally:
114
+ try:
115
+ con.close()
116
+ except Exception: # noqa: BLE001
117
+ pass
118
+ if report.get("refusal"):
119
+ raise err(409, "not_verified", report["refusal"])
120
+ return report
121
+
122
+
123
+ @router.post("/amazon-profit/refresh")
124
+ def profit_refresh(body: Any = Body(default=None), session: Session = Depends(require_session)):
125
+ """Recompute every SKU for the period (30d, 90d or YYYY-MM) and store the settings."""
126
+ _admin(session)
127
+ body = body if isinstance(body, dict) else {}
128
+ return _recompute(session, body.get("period"), body.get("thin"))
129
+
130
+
131
+ @router.post("/amazon-profit/period")
132
+ def profit_period(body: Any = Body(default=None), session: Session = Depends(require_session)):
133
+ """Switch the table to another period and recompute every row; owned cells stay."""
134
+ if not _may_edit(session):
135
+ raise err(403, "forbidden", "Only an editor of Amazon SKU profit can change its period.")
136
+ body = body if isinstance(body, dict) else {}
137
+ period = body.get("period")
138
+ if not period:
139
+ raise err(400, "invalid_setting", "Choose 30 days, 90 days or a calendar month.")
140
+ return _recompute(session, period)
141
+
142
+
143
+ @router.put("/amazon-profit/settings")
144
+ def profit_settings(body: Any = Body(default=None), session: Session = Depends(require_session)):
145
+ """Administrator settings: the default owner of new items and the thin margin."""
146
+ if not session.admin:
147
+ raise err(403, "forbidden", "Only an Administrator can change Amazon SKU profit settings.")
148
+ body = body if isinstance(body, dict) else {}
149
+ try:
150
+ if "defaultOwner" in body:
151
+ amazon_profit.set_default_owner(session.runtime, body.get("defaultOwner"),
152
+ tenant=session.tenant, by=session.uname)
153
+ if "thin" in body:
154
+ amazon_profit.write_settings(session.runtime,
155
+ thin=amazon_profit.clean_thin(body.get("thin")))
156
+ except ValueError as exc:
157
+ raise err(400, "invalid_setting", str(exc)) from None
158
+ settings = amazon_profit.read_settings(session.runtime)
159
+ return {"defaultOwner": settings["defaultOwner"], "thin": settings["thin"]}
160
+
161
+
162
+ @router.post("/amazon-profit/matches/{sku:path}/{decision}")
163
+ def profit_match(sku: str, decision: str, session: Session = Depends(require_session)):
164
+ """Confirm or reject the suggested Odoo product for one SKU; editors only.
165
+
166
+ Confirm copies the suggestion into the link and recomputes the period, so COGS and profit
167
+ fill at once. Reject clears the suggestion, keeps the SKU unlinked and remembers the code."""
168
+ import core.user_tables as ut
169
+ states = {"confirm": amazon_profit.CONFIRMED, "reject": amazon_profit.REJECTED}
170
+ if decision not in states:
171
+ raise err(404, "not_found", "Choose confirm or reject.")
172
+ if not _may_edit(session):
173
+ raise err(403, "forbidden", "Only an editor of Amazon SKU profit can confirm or reject a match.")
174
+ sku = str(sku or "").strip()
175
+ rows = [r for r in amazon_profit.table_rows(session.runtime).values()
176
+ if str(r.get("sku") or "").strip() == sku]
177
+ if ut.get_one(amazon_profit.TABLE_KEY, session.runtime) is None or not rows:
178
+ raise err(404, "not_found", "This SKU is not in Amazon SKU profit.")
179
+ row = rows[0]
180
+ if str(row.get("odoo_product") or "").strip():
181
+ raise err(409, "already_linked", "This SKU already has an Odoo product.")
182
+ if not str(row.get("suggested_product") or "").strip():
183
+ raise err(409, "no_suggestion", "This SKU has no suggested Odoo product.")
184
+ with amazon_profit._LOCK:
185
+ result = amazon_profit.apply_decisions(session.runtime, by=session.uname, sku=sku,
186
+ state=states[decision])
187
+ out = {"sku": sku, "matchState": (result["row"] or {}).get("match_state"),
188
+ "odooProduct": (result["row"] or {}).get("odoo_product"),
189
+ "unitsPerSku": (result["row"] or {}).get("units_per_sku")}
190
+ if decision == "confirm":
191
+ try:
192
+ report = _recompute(session)
193
+ out["refresh"] = {k: report.get(k) for k in ("skus", "linked", "refreshedAt")}
194
+ except HTTPException as exc:
195
+ out["refreshError"] = ((exc.detail or {}).get("error") or {}).get("message")
196
+ current = next((r for r in amazon_profit.table_rows(session.runtime).values()
197
+ if str(r.get("sku") or "").strip() == sku), {})
198
+ out.update(cogsPerUnit=current.get("cogs_per_unit"), netProfit=current.get("net_profit"),
199
+ margin=current.get("margin"), band=current.get("band"))
200
+ return out
api/routes_competitor_watch.py ADDED
@@ -0,0 +1,217 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Competitor watch App routes: watched terms, term detail, settings and owned alerts."""
2
+ from fastapi import APIRouter, Body, Depends, Query
3
+
4
+ from deps import Session, err, require_session
5
+
6
+ router = APIRouter(prefix="/api/v1/competitor-watch", tags=["competitor-watch"])
7
+ SOURCE = "ut_amzn_brand_analytics"
8
+
9
+
10
+ def _module():
11
+ from modules import competitor_watch
12
+ return competitor_watch
13
+
14
+
15
+ def _reader(session: Session = Depends(require_session)) -> Session:
16
+ """Reads need read access to the brand analytics database."""
17
+ from core import perm_scope
18
+ if not perm_scope.may_read(session.user, SOURCE, st=session.runtime):
19
+ raise err(403, "competitor_watch_forbidden", "Your account cannot read Amazon brand analytics.")
20
+ return session
21
+
22
+
23
+ def _writer(session: Session = Depends(_reader)) -> Session:
24
+ """Writes also need a role that may edit."""
25
+ if str(session.user.get("role") or "user").strip().lower() == "viewer":
26
+ raise err(403, "competitor_watch_read_only", "Your account can view the competitor watch but not change it.")
27
+ return session
28
+
29
+
30
+ def _tenant(session):
31
+ return str(getattr(session.runtime, "key", "") or session.tenant)
32
+
33
+
34
+ def _call(fn, *args, **kwargs):
35
+ try:
36
+ return fn(*args, **kwargs)
37
+ except ValueError as exc:
38
+ raise err(400, "competitor_watch_invalid", str(exc)) from exc
39
+ except KeyError as exc:
40
+ raise err(404, "competitor_watch_alert_not_found", "That alert does not exist.") from exc
41
+ except Exception as exc: # noqa: BLE001
42
+ raise err(503, "competitor_watch_unavailable", "The competitor watch could not be read. Try again shortly.") from exc
43
+
44
+
45
+ # --------------------------------------------------------------------------- S78-T17 App binding
46
+
47
+ TEMPLATE_KIND = "competitor_watch"
48
+
49
+
50
+ def _app(session, app_id):
51
+ """The Competitor watch App record this request names, readable by the caller (404 otherwise)."""
52
+ import application_registry
53
+ try:
54
+ app = application_registry.load(session.runtime)["applications"].get(str(app_id or ""))
55
+ except Exception as exc: # noqa: BLE001
56
+ raise err(503, "competitor_watch_unavailable", "The App could not be read. Try again shortly.") from exc
57
+ if (not isinstance(app, dict) or app.get("templateKind") != TEMPLATE_KIND or app.get("retired") is True
58
+ or not application_registry.may_read(app, session.uname, is_admin=session.admin)):
59
+ raise err(404, "competitor_watch_app_not_found", "That Competitor watch App does not exist.")
60
+ return app
61
+
62
+
63
+ def _may_edit(session, app):
64
+ import application_registry
65
+ role = str(session.user.get("role") or "user").strip().lower()
66
+ return role != "viewer" and application_registry.may_edit(app, session.uname, is_admin=session.admin)
67
+
68
+
69
+ def _app_reader(app: str = Query(..., min_length=1), session: Session = Depends(_reader)) -> Session:
70
+ """C4: a read names the App, and the caller must be able to read that App."""
71
+ _app(session, app)
72
+ return session
73
+
74
+
75
+ def _app_writer(app: str = Query(..., min_length=1), session: Session = Depends(_writer)) -> Session:
76
+ """C4: a write names the App, and only an editor of that App may change it."""
77
+ if not _may_edit(session, _app(session, app)):
78
+ raise err(403, "competitor_watch_read_only", "You can view this App but not change it.")
79
+ return session
80
+
81
+
82
+ @router.get("/terms")
83
+ def list_terms(session: Session = Depends(_app_reader)):
84
+ cw = _module()
85
+ return _call(cw.terms_summary, _tenant(session), st=session.runtime)
86
+
87
+
88
+ @router.get("/terms/detail")
89
+ def term_detail(term: str = Query(..., min_length=1), session: Session = Depends(_app_reader)):
90
+ cw = _module()
91
+ return _call(cw.term_detail, _tenant(session), term, st=session.runtime)
92
+
93
+
94
+ @router.post("/terms")
95
+ def add_terms(terms: list[str] = Body(..., embed=True), session: Session = Depends(_app_writer)):
96
+ cw = _module()
97
+ return {"terms": _call(cw.add_terms, _tenant(session), terms, st=session.runtime)}
98
+
99
+
100
+ @router.post("/terms/remove")
101
+ def remove_terms(terms: list[str] = Body(..., embed=True), session: Session = Depends(_app_writer)):
102
+ cw = _module()
103
+ return {"terms": _call(cw.remove_terms, _tenant(session), terms, st=session.runtime)}
104
+
105
+
106
+ @router.get("/settings")
107
+ def read_settings(session: Session = Depends(_app_reader)):
108
+ cw = _module()
109
+ return _call(cw.settings, _tenant(session), st=session.runtime)
110
+
111
+
112
+ @router.patch("/settings")
113
+ def write_settings(undercutPct: float | None = Body(None), rankSurgePct: float | None = Body(None),
114
+ defaultOwner: str | None = Body(None), session: Session = Depends(_app_writer)):
115
+ cw = _module()
116
+ return _call(cw.set_settings, _tenant(session), undercut_pct=undercutPct, rank_surge_pct=rankSurgePct,
117
+ default_owner=defaultOwner, st=session.runtime)
118
+
119
+
120
+ @router.get("/alerts")
121
+ def list_alerts(app: str = Query(..., min_length=1), status: str | None = Query(None),
122
+ session: Session = Depends(_app_reader)):
123
+ cw = _module()
124
+ listed = _call(cw.alerts, _tenant(session), status=status, st=session.runtime)
125
+ return {**listed, "canEdit": _may_edit(session, _app(session, app))}
126
+
127
+
128
+ @router.patch("/alerts/{alert_id}")
129
+ def update_alert(alert_id: str, owner: str | None = Body(None), status: str | None = Body(None),
130
+ due: str | None = Body(None), session: Session = Depends(_app_writer)):
131
+ cw = _module()
132
+ return _call(cw.update_alert, _tenant(session), alert_id, owner=owner, status=status, due=due,
133
+ user=session.uname or "unknown", st=session.runtime)
134
+
135
+
136
+ def _week_end(start):
137
+ import datetime as dt
138
+ try:
139
+ return (dt.date.fromisoformat(str(start)[:10]) + dt.timedelta(days=6)).isoformat()
140
+ except ValueError:
141
+ return str(start)
142
+
143
+
144
+ def _not_ready_message(cw, periods):
145
+ """The plain sentence naming when comparison starts (one week held, or none)."""
146
+ import datetime as dt
147
+ if len(periods) == 1:
148
+ try:
149
+ due = dt.date.fromisoformat(str(periods[0])[:10]) + dt.timedelta(days=14)
150
+ return f"Comparison starts after the next weekly pull, about {due.strftime('%b')} {due.day}."
151
+ except ValueError:
152
+ pass
153
+ return cw.NOT_READY
154
+
155
+
156
+ def screen_payload(cw, detail, terms, term, can_edit):
157
+ """Project `term_detail` to the screen: shares in percent points, previous values, causes, trend."""
158
+ periods = list(detail.get("periods") or ())
159
+ top3 = list(detail.get("top3") or ())
160
+ shares = [abs(v) for row in top3 for v in (row.get("clickShare"), row.get("conversionShare"))
161
+ if isinstance(v, (int, float))]
162
+ shares += [abs(v) for row in detail.get("trend") or () for v in row.get("clickShare") or ()
163
+ if isinstance(v, (int, float))]
164
+ # Unknown: whether Amazon sends shares as fractions or percent. All values at or under 1 read as fractions.
165
+ scale = 100.0 if shares and max(shares) <= 1 else 1.0
166
+
167
+ def pts(value):
168
+ return None if not isinstance(value, (int, float)) else round(value * scale, 4)
169
+
170
+ def previous(value, delta):
171
+ return None if value is None or not isinstance(delta, (int, float)) else round(value - delta * scale, 4)
172
+ rows = []
173
+ for row in top3:
174
+ change = row.get("change") or {}
175
+ click, conv = pts(row.get("clickShare")), pts(row.get("conversionShare"))
176
+ causes = [str(row[key]) for key in ("priceCause", "rankCause") if row.get(key)]
177
+ rows.append({"rank": row.get("rank"), "asin": row.get("asin"), "ours": row.get("isOurs") is True,
178
+ "clickShare": click, "conversionShare": conv,
179
+ "previousRank": change.get("previousRank"),
180
+ "previousClickShare": previous(click, change.get("clickShareDelta")),
181
+ "previousConversionShare": previous(conv, change.get("conversionShareDelta")),
182
+ "cause": " ".join(causes) or None})
183
+ # One line per ASIN in the newest top 3, plus our ASIN when it fell out (at most four lines).
184
+ shown = [row["asin"] for row in rows]
185
+ ours = [row for row in detail.get("trend") or () if row.get("isOurs") and row.get("asin") not in shown]
186
+ wanted = shown + [row["asin"] for row in ours[:1]]
187
+ by_asin = {row.get("asin"): row for row in detail.get("trend") or ()}
188
+ trend = []
189
+ for asin in wanted:
190
+ row = by_asin.get(asin) or {}
191
+ values = list(row.get("clickShare") or ())
192
+ points = [{"start": period, "clickShare": pts(values[i] if i < len(values) else None)}
193
+ for i, period in enumerate(periods)]
194
+ trend.append({"asin": asin, "ours": row.get("isOurs") is True,
195
+ "points": sorted(points, key=lambda p: p["start"])})
196
+ comparison = detail.get("comparison") or {}
197
+ ready = comparison.get("ready") is True
198
+ return {"canEdit": bool(can_edit), "terms": list(terms), "term": term,
199
+ "week": {"start": periods[0], "end": _week_end(periods[0])} if periods else None,
200
+ "previousWeek": {"start": periods[1], "end": _week_end(periods[1])} if len(periods) > 1 else None,
201
+ "comparisonReady": ready,
202
+ "comparisonMessage": "" if ready else _not_ready_message(cw, periods),
203
+ "top3": rows, "trend": trend, "problems": []}
204
+
205
+
206
+ @router.get("/screen")
207
+ def app_screen(app: str = Query(..., min_length=1), term: str | None = Query(None),
208
+ session: Session = Depends(_app_reader)):
209
+ """S78-T17: the Terms view in one read (watched terms, the picked term's top 3 and trend)."""
210
+ cw = _module()
211
+ tenant = _tenant(session)
212
+ record = _app(session, app)
213
+ terms = [row["term"] for row in _call(cw.terms_summary, tenant, st=session.runtime)["terms"]]
214
+ picked = " ".join(str(term or "").split()).lower()
215
+ picked = picked if picked in terms else (terms[0] if terms else None)
216
+ detail = _call(cw.term_detail, tenant, picked, st=session.runtime) if picked else {}
217
+ return screen_payload(cw, detail, terms, picked, _may_edit(session, record))
api/routes_customers.py CHANGED
@@ -1374,83 +1374,6 @@ def _ensure_route_migration(session):
1374
  _ROUTE_MIGRATED_TENANTS.add(tenant)
1375
 
1376
 
1377
- #: (tenant, user, Routing App) triples with no no-App Route left to adopt in this process.
1378
- _ROUTE_ADOPTED_USERS: set = set()
1379
-
1380
-
1381
- def _home_route_application(session):
1382
- """The id of the caller's own Routing App, or None."""
1383
- import application_registry as registry
1384
- me = str(getattr(session, "uname", "") or "").strip().lower()
1385
- if not me:
1386
- return None
1387
- try:
1388
- doc = registry._read_strict(session.runtime, registry._KEY) or {}
1389
- apps = doc.get("applications", {}) if isinstance(doc, dict) else None
1390
- if not isinstance(apps, dict):
1391
- return None
1392
- candidates = []
1393
- for app_id, app in apps.items():
1394
- if (not isinstance(app, dict) or app.get("retired") is True
1395
- or str(app.get("createdBy") or "").strip().lower() != me
1396
- or app.get("tenant") != session.tenant
1397
- or not (app.get("templateKind") == "route"
1398
- or (app.get("type") == "route" and not app.get("templateKind")))
1399
- or not registry.may_read(app, session.uname, is_admin=session.admin)):
1400
- continue
1401
- source = app.get("sourceDatabase")
1402
- if source not in (MODULE, "ut_odoo_customers") and MODULE not in (app.get("compatibleDatabases") or ()):
1403
- continue
1404
- starred = me in {str(user or "").strip().lower() for user in app.get("starredBy") or ()}
1405
- candidates.append((not starred, str(app.get("createdAt") or ""), str(app_id)))
1406
- except Exception:
1407
- # An unreadable registry falls back to the no-App partition, which still works.
1408
- return None
1409
- return min(candidates)[2] if candidates else None
1410
-
1411
-
1412
- def _adopt_unscoped_routes(session, application):
1413
- """Move the caller's post-R20 no-App Routes into their own Routing App, once per process."""
1414
- from core import route_system
1415
- key = (str(getattr(session, "tenant", "") or ""), str(session.uname or "").strip().lower(), application)
1416
- if key in _ROUTE_ADOPTED_USERS:
1417
- return
1418
- try:
1419
- route_system.adopt_unscoped_routes(session.runtime, owner=session.uname, application=application)
1420
- except Exception:
1421
- # A failed adoption leaves the Routes where they are and retries on the next request.
1422
- return
1423
- _ROUTE_ADOPTED_USERS.add(key)
1424
-
1425
-
1426
- def _entry_route_application(session, application, *, write=False):
1427
- """A Route request that names no Routing App uses the caller's own one, when they have one."""
1428
- if application is not None:
1429
- return _route_application(session, application, write=write)
1430
- home = _home_route_application(session)
1431
- if home is None:
1432
- return _route_application(session, None, write=write)
1433
- resolved = _route_application(session, home, write=write)
1434
- _adopt_unscoped_routes(session, resolved)
1435
- return resolved
1436
-
1437
-
1438
- def _entry_route_zone(session, raw, requested, application):
1439
- """A no-App request may name a legacy Zone id. Map it to that Zone's R20 copy in the home App."""
1440
- from core import route_system
1441
- key = "zoneId" if "zoneId" in raw else "zone_id" if "zone_id" in raw else None
1442
- wanted = str(raw.get(key) or "").strip() if key else ""
1443
- if requested is not None or application is None or not wanted:
1444
- return raw
1445
- if wanted in route_system.zone_ids(session.runtime, table_key=route_system.DEFAULT_ZONE_TABLE,
1446
- application=application):
1447
- return raw
1448
- receipt = route_system.read(session.runtime).get(route_system.APPLICATION_MIGRATION) or {}
1449
- zones = ((receipt.get("applications") or {}).get(application) or {}).get("zones") or {}
1450
- mapped = zones.get(f"{route_system.DEFAULT_ZONE_TABLE}:{wanted}")
1451
- return dict(raw, **{key: mapped}) if mapped else raw
1452
-
1453
-
1454
  def _route_application_body(raw, application):
1455
  if "application" in raw and raw["application"] != application:
1456
  raise err(400, "route_application_mismatch", "the body must name the same Routing App as the query")
@@ -1736,7 +1659,7 @@ def routes(session: Session = Depends(module_gate(MODULE)), application: str = N
1736
  50,000 visible records sends exactly the same request as an empty grid; a future annotation
1737
  door may accept a compact saved-View/filter reference without reopening that row-sized wire.
1738
  """
1739
- application = _entry_route_application(session, application)
1740
  allowed = allowed_pids(session)
1741
  records = _route_share_records(session)
1742
  navigation = _route_navigation(session, _visible_routes(session, records, application), application)
@@ -1749,7 +1672,7 @@ def routes(session: Session = Depends(module_gate(MODULE)), application: str = N
1749
 
1750
  @router.get("/customers/routes/delivery-recipients")
1751
  def route_delivery_recipients(session: Session = Depends(module_gate(MODULE)), application: str = None):
1752
- _entry_route_application(session, application)
1753
  return {"people": _route_delivery_people(session)}
1754
 
1755
 
@@ -1764,9 +1687,8 @@ def create_route(body: dict = Body(default=None), session: Session = Depends(mod
1764
  application: str = None):
1765
  from core import route_system
1766
  raw = dict(body or {})
1767
- requested, application = application, _entry_route_application(session, application, write=True)
1768
  _route_application_body(raw, application)
1769
- raw = _entry_route_zone(session, raw, requested, application)
1770
  _reject_client_create_id(raw, "Route")
1771
  source_view = raw.get("sourceViewId", raw.get("source_view_id"))
1772
  if source_view and not _route_view_can_edit(session, source_view):
@@ -1787,7 +1709,7 @@ def create_route(body: dict = Body(default=None), session: Session = Depends(mod
1787
  def duplicate_route(route_id: str, body: dict = Body(default=None),
1788
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1789
  from core import route_system
1790
- application = _entry_route_application(session, application, write=True)
1791
  _route_application_body(body or {}, application)
1792
  prior = _route_or_404(session, route_id, application)
1793
  if prior.get("sourceViewId"):
@@ -1806,7 +1728,6 @@ def duplicate_route(route_id: str, body: dict = Body(default=None),
1806
 
1807
  @router.post("/customers/routes/{route_id}/share-ready")
1808
  def route_share_ready(route_id: str, session: Session = Depends(module_gate(MODULE)), application: str = None):
1809
- application = _entry_route_application(session, application)
1810
  route = _route_or_404(session, route_id, application)
1811
  _route_mutation_allowed(session, route)
1812
  key = _ensure_route_share_bridge(session, route)
@@ -1817,11 +1738,9 @@ def route_share_ready(route_id: str, session: Session = Depends(module_gate(MODU
1817
  def update_route(route_id: str, body: dict = Body(default=None),
1818
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1819
  from core import route_system
1820
- requested, application = application, _entry_route_application(session, application, write=True)
1821
  prior = _route_or_404(session, route_id, application)
1822
  raw = dict(body or {})
1823
  _route_application_body(raw, application)
1824
- raw = _entry_route_zone(session, raw, requested, application)
1825
  _route_mutation_allowed(session, prior, raw.get("sourceViewId", prior.get("sourceViewId")))
1826
  raw["id"] = prior["id"]
1827
  if "stops" in raw and any(pid not in allowed_pids(session) for pid in _route_input_pids(raw)):
@@ -1839,7 +1758,6 @@ def update_route(route_id: str, body: dict = Body(default=None),
1839
  def move_route_stop(route_id: str, body: dict = Body(default=None),
1840
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1841
  from core import route_system
1842
- application = _entry_route_application(session, application, write=True)
1843
  prior = _route_or_404(session, route_id, application)
1844
  _route_mutation_allowed(session, prior)
1845
  raw = dict(body or {})
@@ -1864,7 +1782,6 @@ def set_route_stop_membership(route_id: str, body: dict = Body(default=None),
1864
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1865
  """Add or remove one permitted customer while preserving every other ordered stop."""
1866
  from core import route_system
1867
- application = _entry_route_application(session, application, write=True)
1868
  prior = _route_or_404(session, route_id, application)
1869
  _route_mutation_allowed(session, prior)
1870
  raw = dict(body or {})
@@ -1893,7 +1810,6 @@ def set_route_stop_membership(route_id: str, body: dict = Body(default=None),
1893
  @router.delete("/customers/routes/{route_id}")
1894
  def remove_route(route_id: str, session: Session = Depends(module_gate(MODULE)), application: str = None):
1895
  from core import route_system
1896
- application = _entry_route_application(session, application, write=True)
1897
  route = _route_or_404(session, route_id, application)
1898
  _route_mutation_allowed(session, route)
1899
  linked_delivery_ids = _linked_route_delivery_ids(session.runtime, route_id)
@@ -1919,7 +1835,6 @@ def remove_route(route_id: str, session: Session = Depends(module_gate(MODULE)),
1919
  def move_route_to_folder(route_id: str, body: dict = Body(default=None),
1920
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1921
  from core import route_system
1922
- application = _entry_route_application(session, application, write=True)
1923
  _route_application_body(body or {}, application)
1924
  routes, legacy_folders, legacy_placements = _route_nav_mutation_context(session, **_route_scope(application))
1925
  if str(route_id) not in {str(route.get("id")) for route in routes}:
@@ -1942,7 +1857,6 @@ def move_route_to_folder(route_id: str, body: dict = Body(default=None),
1942
  def reorder_route_navigation(body: dict = Body(default=None),
1943
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1944
  from core import route_system
1945
- application = _entry_route_application(session, application, write=True)
1946
  _route_application_body(body or {}, application)
1947
  routes, legacy_folders, legacy_placements = _route_nav_mutation_context(session, **_route_scope(application))
1948
  order = (body or {}).get("order")
@@ -1960,7 +1874,6 @@ def reorder_route_navigation(body: dict = Body(default=None),
1960
  def create_route_folder(body: dict = Body(default=None),
1961
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1962
  from core import route_system
1963
- application = _entry_route_application(session, application, write=True)
1964
  _route_application_body(body or {}, application)
1965
  _reject_client_create_id(body or {}, "Route folder")
1966
  routes, legacy_folders, legacy_placements = _route_nav_mutation_context(session, **_route_scope(application))
@@ -1976,7 +1889,6 @@ def create_route_folder(body: dict = Body(default=None),
1976
  def update_route_folder(folder_id: str, body: dict = Body(default=None),
1977
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1978
  from core import route_system
1979
- application = _entry_route_application(session, application, write=True)
1980
  _route_application_body(body or {}, application)
1981
  routes, legacy_folders, legacy_placements = _route_nav_mutation_context(session, **_route_scope(application))
1982
  current = next((folder for folder in _route_navigation(session, routes, **_route_scope(application))["folders"]
@@ -1997,7 +1909,6 @@ def update_route_folder(folder_id: str, body: dict = Body(default=None),
1997
  @router.delete("/customers/route-folders/{folder_id}")
1998
  def remove_route_folder(folder_id: str, session: Session = Depends(module_gate(MODULE)), application: str = None):
1999
  from core import route_system
2000
- application = _entry_route_application(session, application, write=True)
2001
  routes, legacy_folders, legacy_placements = _route_nav_mutation_context(session, **_route_scope(application))
2002
  if not route_system.delete_route_folder(
2003
  session.runtime, session.uname, folder_id, routes,
@@ -2010,7 +1921,6 @@ def remove_route_folder(folder_id: str, session: Session = Depends(module_gate(M
2010
  def reorder_route_folder_navigation(body: dict = Body(default=None),
2011
  session: Session = Depends(module_gate(MODULE)), application: str = None):
2012
  from core import route_system
2013
- application = _entry_route_application(session, application, write=True)
2014
  _route_application_body(body or {}, application)
2015
  routes, legacy_folders, legacy_placements = _route_nav_mutation_context(session, **_route_scope(application))
2016
  order = (body or {}).get("order")
@@ -2030,7 +1940,7 @@ def route_selection(body: dict = Body(default=None), session: Session = Depends(
2030
  """Dedicated managed-OR mutation; user filter clauses are returned byte-for-byte intact."""
2031
  from core import route_system
2032
  raw = dict(body or {})
2033
- application = _entry_route_application(session, application)
2034
  _route_application_body(raw, application)
2035
  chosen = [str(item) for item in raw.get("routeIds") or ()]
2036
  compatible = _visible_routes(session, application=application)
@@ -2280,8 +2190,6 @@ def patch_customer(pid: int, body: dict = Body(default=None),
2280
  # refused key or a truncated value must not be reported as accepted.
2281
  stored = (grid_events.table_workspace(_ctx_for(session, pool), allowed_pids=None)
2282
  .get("overlays") or {}).get(str(pid)) or {}
2283
- # A tenant-wide column saves to the shared stratum, so read it back from there too.
2284
- stored = {**stored, **(shared_cells([pid], st=session.runtime).get(str(pid)) or {})}
2285
  accepted = {k: stored.get(k) for k in updates if k in stored}
2286
  refused = sorted(k for k in updates if k not in accepted or stored.get(k) != str(updates[k]))
2287
  # No cache to patch: the overlay stratum is re-read from the store on every `_payload`, so
@@ -2538,7 +2446,6 @@ def _linked_route_delivery_ids(runtime, route_id):
2538
  @router.get("/customers/route-deliveries")
2539
  def route_delivery_list(session: Session = Depends(module_gate(MODULE)), application: str = None):
2540
  """Saved C2 route deliveries owned by the caller (or all for an administrator)."""
2541
- application = _entry_route_application(session, application)
2542
  return {"deliveries": _route_delivery_definitions(session, application=application)}
2543
 
2544
 
@@ -2546,7 +2453,6 @@ def route_delivery_list(session: Session = Depends(module_gate(MODULE)), applica
2546
  def normalized_route_delivery_list(route_id: str,
2547
  session: Session = Depends(module_gate(MODULE)), application: str = None):
2548
  """Deliveries for the one normalized Route whose detail is open."""
2549
- application = _entry_route_application(session, application)
2550
  _route_or_404(session, route_id, application)
2551
  return {"deliveries": _route_delivery_definitions(session, route_id, application)}
2552
 
@@ -2586,7 +2492,6 @@ def _create_route_delivery_for_route(session, route, body):
2586
  def normalized_route_delivery_create(route_id: str, body: dict = Body(default=None),
2587
  session: Session = Depends(module_gate(MODULE)), application: str = None):
2588
  """Schedule a named normalized Route from its server-resolved View and stop relation."""
2589
- application = _entry_route_application(session, application, write=True)
2590
  _route_application_body(body or {}, application)
2591
  return _create_route_delivery_for_route(
2592
  session, _route_or_404(session, route_id, application), body if isinstance(body, dict) else {})
@@ -2597,7 +2502,6 @@ def route_delivery_create(body: dict = Body(default=None),
2597
  session: Session = Depends(module_gate(MODULE)), application: str = None):
2598
  """Compatibility door: a normalized Route id is still mandatory and server-resolved."""
2599
  body = body if isinstance(body, dict) else {}
2600
- application = _entry_route_application(session, application, write=True)
2601
  _route_application_body(body, application)
2602
  route_id = str(body.get("routeId") or "").strip()
2603
  if not route_id:
@@ -2634,7 +2538,6 @@ def _delete_route_delivery(session, delivery_id, route_id=None, application=None
2634
  def normalized_route_delivery_delete(route_id: str, delivery_id: str,
2635
  session: Session = Depends(module_gate(MODULE)), application: str = None):
2636
  """Remove one delivery from the normalized Route detail that owns it."""
2637
- application = _entry_route_application(session, application, write=True)
2638
  route = _route_or_404(session, route_id, application)
2639
  _route_mutation_allowed(session, route)
2640
  return _delete_route_delivery(session, delivery_id, route_id, application)
@@ -2644,5 +2547,4 @@ def normalized_route_delivery_delete(route_id: str, delivery_id: str,
2644
  def route_delivery_delete(delivery_id: str,
2645
  session: Session = Depends(module_gate(MODULE)), application: str = None):
2646
  """Compatibility removal for existing schedule links."""
2647
- application = _entry_route_application(session, application, write=True)
2648
  return _delete_route_delivery(session, delivery_id, application=application)
 
1374
  _ROUTE_MIGRATED_TENANTS.add(tenant)
1375
 
1376
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1377
  def _route_application_body(raw, application):
1378
  if "application" in raw and raw["application"] != application:
1379
  raise err(400, "route_application_mismatch", "the body must name the same Routing App as the query")
 
1659
  50,000 visible records sends exactly the same request as an empty grid; a future annotation
1660
  door may accept a compact saved-View/filter reference without reopening that row-sized wire.
1661
  """
1662
+ application = _route_application(session, application)
1663
  allowed = allowed_pids(session)
1664
  records = _route_share_records(session)
1665
  navigation = _route_navigation(session, _visible_routes(session, records, application), application)
 
1672
 
1673
  @router.get("/customers/routes/delivery-recipients")
1674
  def route_delivery_recipients(session: Session = Depends(module_gate(MODULE)), application: str = None):
1675
+ _route_application(session, application)
1676
  return {"people": _route_delivery_people(session)}
1677
 
1678
 
 
1687
  application: str = None):
1688
  from core import route_system
1689
  raw = dict(body or {})
1690
+ application = _route_application(session, application, write=True)
1691
  _route_application_body(raw, application)
 
1692
  _reject_client_create_id(raw, "Route")
1693
  source_view = raw.get("sourceViewId", raw.get("source_view_id"))
1694
  if source_view and not _route_view_can_edit(session, source_view):
 
1709
  def duplicate_route(route_id: str, body: dict = Body(default=None),
1710
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1711
  from core import route_system
1712
+ application = _route_application(session, application, write=True)
1713
  _route_application_body(body or {}, application)
1714
  prior = _route_or_404(session, route_id, application)
1715
  if prior.get("sourceViewId"):
 
1728
 
1729
  @router.post("/customers/routes/{route_id}/share-ready")
1730
  def route_share_ready(route_id: str, session: Session = Depends(module_gate(MODULE)), application: str = None):
 
1731
  route = _route_or_404(session, route_id, application)
1732
  _route_mutation_allowed(session, route)
1733
  key = _ensure_route_share_bridge(session, route)
 
1738
  def update_route(route_id: str, body: dict = Body(default=None),
1739
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1740
  from core import route_system
 
1741
  prior = _route_or_404(session, route_id, application)
1742
  raw = dict(body or {})
1743
  _route_application_body(raw, application)
 
1744
  _route_mutation_allowed(session, prior, raw.get("sourceViewId", prior.get("sourceViewId")))
1745
  raw["id"] = prior["id"]
1746
  if "stops" in raw and any(pid not in allowed_pids(session) for pid in _route_input_pids(raw)):
 
1758
  def move_route_stop(route_id: str, body: dict = Body(default=None),
1759
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1760
  from core import route_system
 
1761
  prior = _route_or_404(session, route_id, application)
1762
  _route_mutation_allowed(session, prior)
1763
  raw = dict(body or {})
 
1782
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1783
  """Add or remove one permitted customer while preserving every other ordered stop."""
1784
  from core import route_system
 
1785
  prior = _route_or_404(session, route_id, application)
1786
  _route_mutation_allowed(session, prior)
1787
  raw = dict(body or {})
 
1810
  @router.delete("/customers/routes/{route_id}")
1811
  def remove_route(route_id: str, session: Session = Depends(module_gate(MODULE)), application: str = None):
1812
  from core import route_system
 
1813
  route = _route_or_404(session, route_id, application)
1814
  _route_mutation_allowed(session, route)
1815
  linked_delivery_ids = _linked_route_delivery_ids(session.runtime, route_id)
 
1835
  def move_route_to_folder(route_id: str, body: dict = Body(default=None),
1836
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1837
  from core import route_system
 
1838
  _route_application_body(body or {}, application)
1839
  routes, legacy_folders, legacy_placements = _route_nav_mutation_context(session, **_route_scope(application))
1840
  if str(route_id) not in {str(route.get("id")) for route in routes}:
 
1857
  def reorder_route_navigation(body: dict = Body(default=None),
1858
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1859
  from core import route_system
 
1860
  _route_application_body(body or {}, application)
1861
  routes, legacy_folders, legacy_placements = _route_nav_mutation_context(session, **_route_scope(application))
1862
  order = (body or {}).get("order")
 
1874
  def create_route_folder(body: dict = Body(default=None),
1875
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1876
  from core import route_system
 
1877
  _route_application_body(body or {}, application)
1878
  _reject_client_create_id(body or {}, "Route folder")
1879
  routes, legacy_folders, legacy_placements = _route_nav_mutation_context(session, **_route_scope(application))
 
1889
  def update_route_folder(folder_id: str, body: dict = Body(default=None),
1890
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1891
  from core import route_system
 
1892
  _route_application_body(body or {}, application)
1893
  routes, legacy_folders, legacy_placements = _route_nav_mutation_context(session, **_route_scope(application))
1894
  current = next((folder for folder in _route_navigation(session, routes, **_route_scope(application))["folders"]
 
1909
  @router.delete("/customers/route-folders/{folder_id}")
1910
  def remove_route_folder(folder_id: str, session: Session = Depends(module_gate(MODULE)), application: str = None):
1911
  from core import route_system
 
1912
  routes, legacy_folders, legacy_placements = _route_nav_mutation_context(session, **_route_scope(application))
1913
  if not route_system.delete_route_folder(
1914
  session.runtime, session.uname, folder_id, routes,
 
1921
  def reorder_route_folder_navigation(body: dict = Body(default=None),
1922
  session: Session = Depends(module_gate(MODULE)), application: str = None):
1923
  from core import route_system
 
1924
  _route_application_body(body or {}, application)
1925
  routes, legacy_folders, legacy_placements = _route_nav_mutation_context(session, **_route_scope(application))
1926
  order = (body or {}).get("order")
 
1940
  """Dedicated managed-OR mutation; user filter clauses are returned byte-for-byte intact."""
1941
  from core import route_system
1942
  raw = dict(body or {})
1943
+ application = _route_application(session, application)
1944
  _route_application_body(raw, application)
1945
  chosen = [str(item) for item in raw.get("routeIds") or ()]
1946
  compatible = _visible_routes(session, application=application)
 
2190
  # refused key or a truncated value must not be reported as accepted.
2191
  stored = (grid_events.table_workspace(_ctx_for(session, pool), allowed_pids=None)
2192
  .get("overlays") or {}).get(str(pid)) or {}
 
 
2193
  accepted = {k: stored.get(k) for k in updates if k in stored}
2194
  refused = sorted(k for k in updates if k not in accepted or stored.get(k) != str(updates[k]))
2195
  # No cache to patch: the overlay stratum is re-read from the store on every `_payload`, so
 
2446
  @router.get("/customers/route-deliveries")
2447
  def route_delivery_list(session: Session = Depends(module_gate(MODULE)), application: str = None):
2448
  """Saved C2 route deliveries owned by the caller (or all for an administrator)."""
 
2449
  return {"deliveries": _route_delivery_definitions(session, application=application)}
2450
 
2451
 
 
2453
  def normalized_route_delivery_list(route_id: str,
2454
  session: Session = Depends(module_gate(MODULE)), application: str = None):
2455
  """Deliveries for the one normalized Route whose detail is open."""
 
2456
  _route_or_404(session, route_id, application)
2457
  return {"deliveries": _route_delivery_definitions(session, route_id, application)}
2458
 
 
2492
  def normalized_route_delivery_create(route_id: str, body: dict = Body(default=None),
2493
  session: Session = Depends(module_gate(MODULE)), application: str = None):
2494
  """Schedule a named normalized Route from its server-resolved View and stop relation."""
 
2495
  _route_application_body(body or {}, application)
2496
  return _create_route_delivery_for_route(
2497
  session, _route_or_404(session, route_id, application), body if isinstance(body, dict) else {})
 
2502
  session: Session = Depends(module_gate(MODULE)), application: str = None):
2503
  """Compatibility door: a normalized Route id is still mandatory and server-resolved."""
2504
  body = body if isinstance(body, dict) else {}
 
2505
  _route_application_body(body, application)
2506
  route_id = str(body.get("routeId") or "").strip()
2507
  if not route_id:
 
2538
  def normalized_route_delivery_delete(route_id: str, delivery_id: str,
2539
  session: Session = Depends(module_gate(MODULE)), application: str = None):
2540
  """Remove one delivery from the normalized Route detail that owns it."""
 
2541
  route = _route_or_404(session, route_id, application)
2542
  _route_mutation_allowed(session, route)
2543
  return _delete_route_delivery(session, delivery_id, route_id, application)
 
2547
  def route_delivery_delete(delivery_id: str,
2548
  session: Session = Depends(module_gate(MODULE)), application: str = None):
2549
  """Compatibility removal for existing schedule links."""
 
2550
  return _delete_route_delivery(session, delivery_id, application=application)
api/routes_external.py CHANGED
@@ -79,7 +79,13 @@ def _json_digest(value) -> str:
79
  return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
80
 
81
 
82
- def _canonical_json(value) -> bytes:
 
 
 
 
 
 
83
  try:
84
  encoded = json.dumps(value, sort_keys=True, separators=(",", ":"),
85
  ensure_ascii=True, allow_nan=False)
@@ -87,8 +93,7 @@ def _canonical_json(value) -> bytes:
87
  raise err(400, "tool_arguments_invalid",
88
  "The tool arguments contain a value that cannot be represented safely.") from exc
89
  raw = encoded.encode("utf-8")
90
- from tool_groups.apps import code_transport_fits
91
- if len(raw) > _CONFIRMATION_MAX_BYTES and not code_transport_fits(value, _CONFIRMATION_MAX_BYTES):
92
  raise err(413, "confirmation_too_large",
93
  "This change is too large for one preview. Split it into smaller changes.")
94
  if _contains_credential(encoded):
@@ -344,7 +349,9 @@ class _ConfirmationRuntime:
344
 
345
 
346
  def _diff_documents(documents, *, limit=250):
 
347
  changes = []
 
348
 
349
  def walk(before, after, path):
350
  if len(changes) >= limit or before == after:
@@ -372,6 +379,70 @@ def _diff_documents(documents, *, limit=250):
372
  return changes, len(changes) >= limit
373
 
374
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
375
  def _database_preview_documents(session, before, after):
376
  """Project changed records and fields through the caller's current database permissions."""
377
  import routes_tables
@@ -468,13 +539,29 @@ def _credential_binding(session: Session) -> str:
468
  return str(claims.get("external_credential_id") or claims.get("external_key_id") or "")
469
 
470
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
471
  def _confirmation_token(payload) -> str:
472
- wire_payload = copy.deepcopy(payload)
473
- if payload.get("tool") == "apps" and payload.get("arguments", {}).get("action") == "save_code":
474
- wire_payload = {"v": 2, "operation_id": payload["operation_id"],
475
- "payload_digest": _json_digest(payload),
476
- **{key: payload[key] for key in ("tenant", "actor", "credential", "authentication")}}
477
- raw = _canonical_json(wire_payload)
478
  signature = aios_session._sign(b"external-confirm:v1:" + raw)
479
  return f"{_CONFIRMATION_PREFIX}.{_b64(raw)}.{signature}"
480
 
@@ -491,8 +578,20 @@ def _read_confirmation_token(token, session=None) -> dict:
491
  payload = json.loads(raw.decode("utf-8"))
492
  except (ValueError, TypeError, UnicodeError, json.JSONDecodeError) as exc:
493
  raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.") from exc
494
- if not isinstance(payload, dict) or payload.get("v") not in (1, 2):
495
  raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.")
 
 
 
 
 
 
 
 
 
 
 
 
496
  if payload["v"] == 2:
497
  if (set(payload) != {"v", "operation_id", "payload_digest", "tenant", "actor", "credential", "authentication"}
498
  or not isinstance(payload.get("operation_id"), str)
@@ -1045,7 +1144,12 @@ def _assert_write_scope(session, tool_name, arguments=None):
1045
  _, args = tool_groups.resolve(tool_name, arguments)
1046
  _assert_workbook_scope(session, args["workbook_id"])
1047
  elif not external_access.may_write(access):
1048
- raise err(403, "key_read_only", f"{tool_name} writes, and this credential is read only.")
 
 
 
 
 
1049
  code = _test_environment_refusal(session)
1050
  if code:
1051
  raise err(403, code, MCP_RESULT_CODES[code])
@@ -3511,7 +3615,7 @@ def _execute_database_object(session, args, *, plan=None):
3511
  flush="sync", expect_rev=expected_rev)
3512
  except (view_audit.ViewRevisionStale, view_audit.RevisionUnverifiable) as exc:
3513
  raise err(409, "confirmation_stale",
3514
- "The database changed after preview. Preview the change again.") from exc
3515
  return {"database": database, **copy.deepcopy(plan.get("planned") or {}),
3516
  "affected": copy.deepcopy(plan.get("affected") or {})}
3517
 
@@ -3959,7 +4063,24 @@ def _build_purpose(value):
3959
  return wiki_log.purpose_line(value)
3960
 
3961
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3962
  def _build_about(value):
 
3963
  missing = ["about." + key for key in ("title", "description", "tags")
3964
  if not isinstance(value, dict) or key not in value]
3965
  example = {"about": {"title": "Weekly sales review", "description": "Review weekly sales before the team meeting.",
@@ -4000,7 +4121,9 @@ def _build_about(value):
4000
  else "[unknown]") for key in value if key not in rules]
4001
  invalid = invalid or ["about"]
4002
  details = {"missing": missing, "invalid": invalid, "example": example}
4003
- message = ("Send about with title, description and tags." if missing
 
 
4004
  else "Fix " + ", ".join(invalid) + ".")
4005
  if not isinstance(value, dict) or "about.tags" in invalid or "about.tags" in missing:
4006
  details["allowed"] = tags
@@ -4073,7 +4196,7 @@ def _preview_external_write(session, name, arguments, *, issue_token=True, execu
4073
  about = _build_about(about)
4074
  build_kind = _external_build_kind(name, arguments)
4075
  environment = _write_environment()
4076
- normalised = json.loads(_canonical_json(arguments).decode("utf-8"))
4077
  _assert_tool_database_scope(session, name, normalised)
4078
 
4079
  preview_runtime = _PreviewRuntime(session.runtime)
@@ -4105,9 +4228,9 @@ def _preview_external_write(session, name, arguments, *, issue_token=True, execu
4105
  projected = _request_preview_documents(session, normalised["arguments"]["id"], documents)
4106
  else:
4107
  projected = _public_preview_documents(session, documents)
4108
- diff, truncated = _diff_documents(projected)
4109
- warnings = (["The preview diff reached its display cap; split this change."]
4110
- if truncated else [])
4111
  affected = _affected_for(name, normalised, diff, result)
4112
  current_revision = {
4113
  key: revision for key, revision in preview_runtime.base_revisions().items()
@@ -4127,8 +4250,15 @@ def _preview_external_write(session, name, arguments, *, issue_token=True, execu
4127
  {"user": row["user"], "role": row["role"]}
4128
  for row in result["current_entries"]]
4129
 
4130
- _canonical_json(diff)
4131
  diff_digest = _json_digest(diff)
 
 
 
 
 
 
 
4132
  revision_digest = plan["source_fingerprint"] if remote_note else _json_digest(current_revision)
4133
  expires_at = int(time.time()) + _CONFIRMATION_TTL_SECONDS
4134
  payload = {
@@ -4158,13 +4288,15 @@ def _preview_external_write(session, name, arguments, *, issue_token=True, execu
4158
  "operation_id": payload["operation_id"], "state": "not_committed",
4159
  "preview": True, "mutated": False, "tool": name,
4160
  "environment": environment,
4161
- "diff": diff, "diff_digest": diff_digest,
4162
  "affected": affected, "warnings": warnings,
4163
  "current_revision": current_revision,
4164
  "expires_at": expires_at, "requires_confirmation": True,
4165
  "strong_confirmation_required": payload["strong"],
4166
  "about": copy.deepcopy(about), "buildKind": build_kind,
4167
  }
 
 
4168
  if purpose is not None:
4169
  response["purpose"] = purpose
4170
  if remote_note:
@@ -4197,15 +4329,49 @@ def _refresh_authority(session):
4197
  session.claims.get("external_workbooks", [])])
4198
 
4199
 
4200
- def _prune_operations(raw):
 
4201
  doc = raw if isinstance(raw, dict) else {}
4202
  now = time.time()
4203
- doc["claims"] = {key: value for key, value in (doc.get("claims") or {}).items()
4204
- if isinstance(value, dict) and
4205
- float(value.get("retain_until", value.get("expiry", 0))) >= now}
 
 
 
 
4206
  return doc
4207
 
4208
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4209
  def _store_operation(session, payload, preview, staged, intent=None):
4210
  """Keep the preview identity outside every affected object's revision."""
4211
  operation_id = payload["operation_id"]
@@ -4235,17 +4401,38 @@ def _store_operation(session, payload, preview, staged, intent=None):
4235
  if isinstance(intent, str):
4236
  # Intent stays outside the signed payload, redacted, so confirm_change can reuse it.
4237
  item["intent"] = audit.redact_intent(intent)
 
 
 
 
 
 
 
 
 
 
 
 
 
4238
  def save(raw):
4239
- doc = _prune_operations(raw)
 
4240
  if operation_id in doc["claims"]:
4241
- raise err(409, "confirmation_stale", "Preview the change again.")
4242
  stored_item = copy.deepcopy(item)
4243
- if payload["tool"] == "apps":
4244
- from tool_groups.apps import pending_arguments
4245
- stored_item["payload"]["arguments"] = pending_arguments(payload["arguments"], encode=True)
 
4246
  doc["claims"][operation_id] = stored_item
4247
  return doc
4248
- session.runtime.update(_CONFIRMATION_BUCKET, save, flush="sync")
 
 
 
 
 
 
4249
 
4250
 
4251
  def _operation_access(session, item, *, confirming=False):
@@ -4369,6 +4556,19 @@ def _load_operation(session, operation_id, *, confirming=False):
4369
  if (not isinstance(item, dict) or "payload" not in item
4370
  or item.get("retain_until", 0) < time.time()):
4371
  raise err(404, "operation_unavailable", _OPERATION_UNAVAILABLE_MESSAGE)
 
 
 
 
 
 
 
 
 
 
 
 
 
4372
  if item["payload"]["tool"] == "apps":
4373
  from tool_groups.apps import pending_arguments
4374
  item = copy.deepcopy(item)
@@ -4402,6 +4602,11 @@ def _operation_result(operation_id, item):
4402
 
4403
  def _operation_status(session, args):
4404
  """Read a retained result without changing any object or operation revision."""
 
 
 
 
 
4405
  _, item = _load_operation(session, args["operation_id"])
4406
  return _operation_result(args["operation_id"], item)
4407
 
@@ -4538,6 +4743,23 @@ def _finish_website_note(session, payload, plan, result):
4538
  return response
4539
 
4540
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4541
  def _confirm_change(session, args):
4542
  from core import view_audit, write_execution
4543
 
@@ -4554,7 +4776,7 @@ def _confirm_change(session, args):
4554
  return _operation_result(operation_id, stored)
4555
  _assert_write_scope(fresh_session, payload.get("tool"), payload.get("arguments"))
4556
  if payload.get("environment") != _write_environment():
4557
- raise err(409, "confirmation_stale", "The environment changed. Preview the change again.")
4558
  if int(payload.get("expiry") or 0) <= int(time.time()):
4559
  raise err(409, "confirmation_expired",
4560
  "This confirmation token expired. Preview the change again.")
@@ -4567,8 +4789,7 @@ def _confirm_change(session, args):
4567
  execution = payload.get('execution')
4568
  if (not isinstance(execution, dict) or not isinstance(execution.get('seed'), str)
4569
  or not execution['seed'] or type(execution.get('timestamp')) not in (int, float)):
4570
- raise err(409, 'confirmation_stale',
4571
- 'This preview is no longer current. Preview the change again.')
4572
  try:
4573
  _confirmation_claim(fresh_session, operation_id)
4574
  except _OperationAlreadyClaimed:
@@ -4589,7 +4810,7 @@ def _confirm_change(session, args):
4589
  or any((key in payload, payload.get(key)) != (key in current, current.get(key))
4590
  for key in ("purpose", "purpose_digest", "about", "about_digest", "buildKind"))):
4591
  raise err(409, "confirmation_stale",
4592
- "The data, permissions, or resulting diff changed. Preview the change again.")
4593
  if remote_note:
4594
  import website_tools
4595
  ctx = _tool_context(fresh_session)
@@ -4618,7 +4839,7 @@ def _confirm_change(session, args):
4618
  {"state": "unknown", "applied": None, "reason": "remote_response_lost"})
4619
  _confirmation_status(fresh_session, operation_id, "failed")
4620
  raise err(409, "confirmation_stale",
4621
- "The data changed while confirmation was committing. Preview it again.") from exc
4622
  except Exception:
4623
  if remote_note and capability is not None and capability.transport_started:
4624
  return _finish_website_note(fresh_session, payload, recomputed["_plan"],
@@ -4664,6 +4885,8 @@ def _confirm_change(session, args):
4664
  if tool == "apps" and arguments.get("action") == "catalog_build":
4665
  response.update({key: copy.deepcopy(result[key]) for key in _CATALOG_BUILD_RESULT_FIELDS})
4666
  _confirmation_status(fresh_session, operation_id, "committed", response)
 
 
4667
  if tool != "database_object" and receipt.get("persisted") is True:
4668
  try:
4669
  targets, native_ids = _committed_build_evidence(fresh_session, guarded_session.runtime, arguments,
@@ -4753,6 +4976,20 @@ _MCP_CODE_GROUPS = (
4753
  ("Check the View's sharing settings before changing it.", """
4754
  view_is_shared view_not_personal share_owner_redundant share_role_unknown share_who_required
4755
  """),
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4756
  )
4757
  MCP_RESULT_CODES = {
4758
  code: reason for reason, codes in _MCP_CODE_GROUPS for code in codes.split()
@@ -4768,6 +5005,7 @@ MCP_RESULT_CODES.update({
4768
  "unknown_people": "Choose active people in this workspace.",
4769
  "grant_exceeds_role": "You cannot grant a role above your own access.",
4770
  "revoke_not_yours": "You can remove only people you added.",
 
4771
  "key_refresh_only": "This connection can only refresh source cells in its granted workbooks.",
4772
  "key_workbook_out_of_scope": "This connection cannot refresh this workbook.",
4773
  "external_workbooks_invalid": "Choose up to 100 workbook ids. All workbooks is not a valid choice.",
@@ -4785,11 +5023,15 @@ MCP_RESULT_CODES.update({
4785
  "operation_pending": "The change is still being saved. Ask again shortly.",
4786
  "operation_not_committed": "This change has not been committed.",
4787
  "operation_unavailable": _OPERATION_UNAVAILABLE_MESSAGE,
 
 
4788
  "credential_in_arguments": "Remove credential values from the arguments.",
4789
- "build_about_required": "Send about with title, description of 20 to 240 characters, and tags from the guide. See missing and example.",
 
4790
  "build_about_invalid": ("Fix the fields in invalid. Use a nonempty title, a description of 20 to 240 characters, "
4791
  "and tags from allowed, each once: " + ", ".join(external_tools.BUILD_TAGS) + "."),
4792
- "call_intent_required": "Send intent explaining why you are making this write. See example.",
 
4793
  "call_intent_invalid": "Send intent as a string of 1 to 500 characters. See example.",
4794
  "invalid_external_credential": "The credential is invalid, expired, or revoked.",
4795
  "credential_in_output": "The result contained a credential value and was withheld.",
@@ -4891,7 +5133,7 @@ _MCP_RESULT_OPAQUE = frozenset({
4891
  "revision_before", "revision_after", "filters", "sorts", "config", "binding", "bindings",
4892
  })
4893
  _MCP_RESULT_IDENTIFIERS = frozenset({
4894
- "resourceUri", "deepLink", "pdfLink", "src", "websiteUrl", "fileId", "link", "href",
4895
  "id", "ids", "operation_id", "key", "keys", "pid", "pids", "database", "databases", "sourceDatabase",
4896
  "compatibleDatabases", "field", "fields", "field_key", "colId", "metric_key", "groupBy",
4897
  "workbook_id", "worksheet", "tab", "view_id", "app_id", "catalog_id", "chart_id", "record_id", "contextId",
@@ -5052,6 +5294,26 @@ def _mcp_protocol_error(rid, code, message):
5052
  return {"jsonrpc": "2.0", "id": rid, "error": {"code": code, "message": out["reason"], "data": out}}
5053
 
5054
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5055
  def _mcp_protocol_result(rid, data):
5056
  out = _shape_mcp_result({"ok": True, "data": data})
5057
  return {"jsonrpc": "2.0", "id": rid, "result": {
@@ -5065,8 +5327,7 @@ def _mcp_protocol_result(rid, data):
5065
  # `loopable_guide` tool (every client can call a tool). ⛔ Model-facing text is user-facing copy:
5066
  # no em or en dashes here.
5067
  MCP_GUIDE_TOOL = "loopable_guide"
5068
- _MCP_INTENT_SCHEMA = {"type": "string", "minLength": 1, "maxLength": 500,
5069
- "description": "State why you are making this call. Required for every write, including confirmation."}
5070
  MCP_INSTRUCTIONS = "\n".join([
5071
  "1. Loopable is a governed business data workspace: Table databases, saved Views, Sheet workbooks and "
5072
  "Apps. Every call runs as the signed-in user, with that user's own permissions. "
@@ -5088,6 +5349,7 @@ MCP_INSTRUCTIONS = "\n".join([
5088
  "intelligence.create_wiki publishes a new wiki/ page at once without preview, confirmation or owner approval. "
5089
  "It cannot replace a committed page. Existing wiki edits use intelligence.propose with confirmation and file approval. "
5090
  "Send intent beside action and arguments on every write, including confirm_change. "
 
5091
  "Reads may send intent. Use 1 to 500 characters explaining why you are making this call."
5092
  " Use requests.list_team for teammate names and last-active times, requests.send_message for questions or change proposals, "
5093
  "requests.check_inbox for incoming requests, and requests.ask_user for recipient Approve or Deny decisions. "
@@ -5116,7 +5378,8 @@ _MCP_GUIDE_SPEC = {
5116
  "name": MCP_GUIDE_TOOL,
5117
  "description": "Read workspace connections, your skills, databases and the group index, "
5118
  "or choose a group for its actions and argument schemas.",
5119
- "inputSchema": {"type": "object", "properties": {"group": {"type": "string"}}, "required": [],
 
5120
  "additionalProperties": False},
5121
  "annotations": {"title": "Loopable guide", "readOnlyHint": True,
5122
  "destructiveHint": False, "openWorldHint": False},
@@ -5473,11 +5736,17 @@ def _guide_unread_count(session: Session) -> int:
5473
  def _mcp_guide(session: Session, group=None) -> str:
5474
  """Return the group index or one group's action schemas without reading records."""
5475
  import tool_groups
 
 
 
 
 
 
5476
  alias = group == "data"
5477
  group = tool_groups.canonical_name(group)
5478
- groups = tool_groups.groups()
5479
  if group is not None and group not in groups:
5480
- raise sheets.SheetRefusal("tool_not_found", "The requested group is not available.")
 
5481
  # One rows-free definitions read per guide: a live runtime pays one pool checkout per database.
5482
  # The guide reads schemas only, so no reader here needs `rows`. On a failed read, keep the old path.
5483
  try:
@@ -5602,6 +5871,7 @@ def _mcp_tool_specs() -> list[dict]:
5602
  group_names = set(groups)
5603
  for spec in specs:
5604
  spec["inputSchema"]["properties"]["intent"] = copy.deepcopy(_MCP_INTENT_SCHEMA)
 
5605
  if spec["name"] == "confirm_change":
5606
  spec["inputSchema"]["required"] = [*spec["inputSchema"].get("required", []), "intent"]
5607
  if spec["name"] in group_names:
@@ -5784,7 +6054,7 @@ def _mcp_call_intent(arguments):
5784
  def _mcp_saved_intent(session, arguments):
5785
  """Return the intent saved with the preview the signed token names, or None."""
5786
  try:
5787
- payload = _read_confirmation_token(arguments.get("confirmation_token"))
5788
  _, stored = _load_operation(session, payload.get("operation_id", ""), confirming=True)
5789
  if stored["payload"] != payload:
5790
  return None
@@ -5794,12 +6064,48 @@ def _mcp_saved_intent(session, arguments):
5794
  return intent if isinstance(intent, str) and intent.strip() else None
5795
 
5796
 
 
 
 
 
 
 
 
 
 
 
 
5797
  def _mcp_hoist_call_metadata(name, arguments):
5798
  """Return group call arguments with intent, about and purpose lifted out of the inner arguments."""
5799
  import tool_groups
5800
  keys = ("intent", "about", "purpose")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5801
  # The Table group's `data` alias hoists like `table` (C4).
5802
- if (not isinstance(name, str) or tool_groups.canonical_call(name, arguments)[0] not in tool_groups.groups()
5803
  or not isinstance(arguments, dict)
5804
  or not isinstance(arguments.get("arguments"), dict)
5805
  or not any(key in arguments["arguments"] for key in keys)):
@@ -5813,6 +6119,27 @@ def _mcp_hoist_call_metadata(name, arguments):
5813
  return hoisted
5814
 
5815
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5816
  def _mcp_requires_intent(name, arguments):
5817
  """Classify declared writes before argument validation can mask the intent requirement."""
5818
  import tool_groups
@@ -5834,9 +6161,10 @@ def _dispatch_mcp(req, session: Session, base_url: str = ""):
5834
  if isinstance(req, dict) and req.get("method") == "tools/call" and isinstance(req.get("params"), dict):
5835
  params = req["params"]
5836
  original = params.get("name")
5837
- name, arguments = tool_groups.canonical_call(original, params.get("arguments", {}))
 
5838
  alias = isinstance(original, str) and (original == "data" or original.startswith("data.")) and name == "table"
5839
- if name != original:
5840
  req = {**req, "params": {**params, "name": name, "arguments": arguments}}
5841
  reply = _dispatch_mcp_call(req, session, base_url)
5842
  if alias and isinstance(reply, dict) and "content" in reply.get("result", {}):
@@ -5865,6 +6193,8 @@ def _dispatch_mcp_call(req, session: Session, base_url: str = ""):
5865
  if not isinstance(params, dict):
5866
  return protocol_error(rid, -32602, "MCP params must be an object.")
5867
  name = params.get("name")
 
 
5868
  try:
5869
  # Same AI apps wall as the read doors, inside the dispatcher so a grant refusal
5870
  # remains MCP content. Only the unchanged bearer dependency produces an HTTP 401.
@@ -5902,6 +6232,10 @@ def _dispatch_mcp_call(req, session: Session, base_url: str = ""):
5902
  "_meta": {"ui": {"csp": {"connectDomains": [], "resourceDomains": [], "frameDomains": []}}}}
5903
  if method == "resources/list":
5904
  return {"jsonrpc": "2.0", "id": rid, "result": {"resources": [resource]}}
 
 
 
 
5905
  if params.get("uri") != WORKBOOK_RESOURCE_URI:
5906
  return protocol_error(rid, -32602, "That resource is not available.")
5907
  resource["text"] = (Path(__file__).parent / "side_view" / "workbook.html").read_text(encoding="utf-8")
@@ -5915,7 +6249,7 @@ def _dispatch_mcp_call(req, session: Session, base_url: str = ""):
5915
  if intent is not None:
5916
  external_activity.note_saved_intent(intent)
5917
  if intent is None and _mcp_requires_intent(name, arguments):
5918
- raise err(400, "call_intent_required", "Send intent explaining why you are making this write.",
5919
  {"example": {"intent": "Prepare the weekly sales review"}})
5920
  if isinstance(arguments, dict):
5921
  arguments = {key: value for key, value in arguments.items() if key != "intent"}
@@ -5949,6 +6283,10 @@ def _dispatch_mcp_call(req, session: Session, base_url: str = ""):
5949
  or action in {"describe_database", "query_database"}):
5950
  from tool_groups.data import READ_ARGUMENT_HELP
5951
  raise sheets.SheetRefusal(exc.code, exc.message + " " + READ_ARGUMENT_HELP) from exc
 
 
 
 
5952
  raise
5953
  confirm = True
5954
  scoped_arguments = arguments
@@ -6013,6 +6351,8 @@ def _dispatch_mcp_call(req, session: Session, base_url: str = ""):
6013
  out = _tool_refusal(name, "external_access_unavailable", "The AI API is unavailable right now.", 503)
6014
  except sheets.SheetRefusal as exc:
6015
  import routes_sheet
 
 
6016
  translated = routes_sheet._refuse(exc)
6017
  info = translated.detail["error"]
6018
  out = _tool_refusal(name, info["code"], info["message"], translated.status_code,
@@ -6034,12 +6374,15 @@ def _dispatch_mcp_call(req, session: Session, base_url: str = ""):
6034
  retry["suggestions"] = details.get("suggestions", [])
6035
  if info.get("code") == "workbook_name_ambiguous" and isinstance(details, dict):
6036
  retry["candidates"] = details.get("candidates", [])
6037
- out = _tool_refusal(name, info.get("code", "tool_refused"),
6038
- info.get("message", "The app refused this operation."), exc.status_code, **retry)
 
 
6039
  except (TypeError, ValueError, KeyError, AttributeError):
6040
  out = _tool_refusal(name, "tool_arguments_invalid", "The arguments could not be read. Use the published input schema.")
6041
  except Exception:
6042
- out = _tool_refusal(name, "tool_unavailable", "The tool could not complete this operation.", 503)
 
6043
  return _mcp_content(rid, out, session)
6044
 
6045
 
@@ -6050,10 +6393,37 @@ async def external_mcp(request: Request, session: Session = Depends(require_exte
6050
  req = await request.json()
6051
  except (ValueError, UnicodeError):
6052
  return _mcp_protocol_error(None, -32700, "The request body must be valid JSON.")
6053
- reply = await run_in_threadpool(_handle_mcp, req, session, str(request.base_url))
6054
  return Response(status_code=204) if reply is None else reply
6055
 
6056
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
6057
  # R8 (SDLC 61) revokes the read-only surface. Every write must be named here deliberately.
6058
  # A new write in the registry without a matching literal raises at import, before serving.
6059
  _WRITE_TOOLS = frozenset({
 
79
  return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
80
 
81
 
82
+ def _fits_token(value, raw) -> bool:
83
+ from tool_groups.apps import code_transport_fits
84
+ return len(raw) <= _CONFIRMATION_MAX_BYTES or code_transport_fits(value, _CONFIRMATION_MAX_BYTES)
85
+
86
+
87
+ def _canonical_json(value, *, capped=True) -> bytes:
88
+ """Encode a value canonically. The byte cap binds a signed token only, never a write (rule 1)."""
89
  try:
90
  encoded = json.dumps(value, sort_keys=True, separators=(",", ":"),
91
  ensure_ascii=True, allow_nan=False)
 
93
  raise err(400, "tool_arguments_invalid",
94
  "The tool arguments contain a value that cannot be represented safely.") from exc
95
  raw = encoded.encode("utf-8")
96
+ if capped and not _fits_token(value, raw):
 
97
  raise err(413, "confirmation_too_large",
98
  "This change is too large for one preview. Split it into smaller changes.")
99
  if _contains_credential(encoded):
 
349
 
350
 
351
  def _diff_documents(documents, *, limit=250):
352
+ """List changed leaves. limit=None lists every change."""
353
  changes = []
354
+ limit = float("inf") if limit is None else limit
355
 
356
  def walk(before, after, path):
357
  if len(changes) >= limit or before == after:
 
379
  return changes, len(changes) >= limit
380
 
381
 
382
+ _PREVIEW_DIFF_LIMIT = 250
383
+ _PREVIEW_SAMPLE_CHANGES = 20
384
+ _PREVIEW_SAMPLE_ROW_BYTES = 4096
385
+ _CELL_ADDRESS = re.compile(r"([A-Z]{1,3})([0-9]{1,7})")
386
+
387
+
388
+ def _column_number(letters):
389
+ number = 0
390
+ for letter in letters:
391
+ number = number * 26 + ord(letter) - 64
392
+ return number
393
+
394
+
395
+ def _column_letters(number):
396
+ letters = ""
397
+ while number:
398
+ number, rest = divmod(number - 1, 26)
399
+ letters = chr(65 + rest) + letters
400
+ return letters
401
+
402
+
403
+ def _summarise_diff(diff, documents):
404
+ """Return the diff a preview shows and its summary. A diff that fits shows whole, with no summary."""
405
+ if (len(diff) < _PREVIEW_DIFF_LIMIT
406
+ and len(_canonical_json(diff, capped=False)) <= _CONFIRMATION_MAX_BYTES):
407
+ return diff, None
408
+ cells, cell_rows, other_rows = {}, [], []
409
+ for row in diff:
410
+ parts = [part.replace("~1", "/").replace("~0", "~") for part in row["path"][1:].split("/")]
411
+ if not (len(parts) >= 6 and parts[0] == "workbooks" and parts[2] == "sheets" and parts[4] == "cells"):
412
+ other_rows.append(row)
413
+ continue
414
+ cell_rows.append(row)
415
+ kind = "changed"
416
+ if len(parts) == 6 and row["before"] is None:
417
+ kind = "added"
418
+ elif len(parts) == 6 and row["after"] is None:
419
+ kind = "removed"
420
+ tab = cells.setdefault((parts[1], parts[3]), {})
421
+ if tab.get(parts[5]) in (None, "changed"):
422
+ tab[parts[5]] = kind
423
+ counts = {"added": 0, "changed": 0, "removed": 0}
424
+ ranges = []
425
+ for (workbook_id, index), addresses in sorted(cells.items()):
426
+ for kind in addresses.values():
427
+ counts[kind] += 1
428
+ pair = documents.get("workbooks/" + workbook_id) or {}
429
+ sheets_list = ((pair.get("after") or pair.get("before") or {}).get("sheets") or [])
430
+ sheet = sheets_list[int(index)] if index.isdigit() and int(index) < len(sheets_list) else {}
431
+ found = [_CELL_ADDRESS.fullmatch(address) for address in addresses]
432
+ found = [(_column_number(match[1]), int(match[2])) for match in found if match]
433
+ span = (f"{_column_letters(min(c for c, _ in found))}{min(r for _, r in found)}:"
434
+ f"{_column_letters(max(c for c, _ in found))}{max(r for _, r in found)}") if found else ""
435
+ ranges.append({"workbook_id": workbook_id, "tab": (sheet or {}).get("name") or (sheet or {}).get("id"),
436
+ "tab_id": (sheet or {}).get("id"), "range": span, "cells": len(addresses)})
437
+ sample = []
438
+ for row in (cell_rows + other_rows)[:_PREVIEW_SAMPLE_CHANGES]:
439
+ size = len(_canonical_json(row, capped=False))
440
+ sample.append(row if size <= _PREVIEW_SAMPLE_ROW_BYTES
441
+ else {"path": row["path"], "omitted": True, "bytes": size})
442
+ return sample, {"changes": len(diff), "cells": {**counts, "total": sum(counts.values())},
443
+ "other_changes": len(other_rows), "ranges": ranges, "sample": len(sample), "complete": False}
444
+
445
+
446
  def _database_preview_documents(session, before, after):
447
  """Project changed records and fields through the caller's current database permissions."""
448
  import routes_tables
 
539
  return str(claims.get("external_credential_id") or claims.get("external_key_id") or "")
540
 
541
 
542
+ def _is_save_code(payload):
543
+ return payload.get("tool") == "apps" and payload.get("arguments", {}).get("action") == "save_code"
544
+
545
+
546
+ def _arguments_outside_token(payload):
547
+ """True when a payload's arguments are too large for a token, so v3 applies."""
548
+ return not _is_save_code(payload) and not _fits_token(payload, _canonical_json(payload, capped=False))
549
+
550
+
551
+ def _token_wire(payload):
552
+ """Return what the token signs. Arguments too large for a token stay in the stored operation."""
553
+ if _is_save_code(payload):
554
+ return {"v": 2, "operation_id": payload["operation_id"],
555
+ "payload_digest": _json_digest(payload),
556
+ **{key: payload[key] for key in ("tenant", "actor", "credential", "authentication")}}
557
+ if not _arguments_outside_token(payload):
558
+ return copy.deepcopy(payload)
559
+ # v3 signs every field but the arguments. arguments_digest binds them to the stored operation.
560
+ return {**{key: copy.deepcopy(value) for key, value in payload.items() if key != "arguments"}, "v": 3}
561
+
562
+
563
  def _confirmation_token(payload) -> str:
564
+ raw = _canonical_json(_token_wire(payload))
 
 
 
 
 
565
  signature = aios_session._sign(b"external-confirm:v1:" + raw)
566
  return f"{_CONFIRMATION_PREFIX}.{_b64(raw)}.{signature}"
567
 
 
578
  payload = json.loads(raw.decode("utf-8"))
579
  except (ValueError, TypeError, UnicodeError, json.JSONDecodeError) as exc:
580
  raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.") from exc
581
+ if not isinstance(payload, dict) or payload.get("v") not in (1, 2, 3):
582
  raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.")
583
+ if payload["v"] == 3:
584
+ if ("arguments" in payload or not isinstance(payload.get("operation_id"), str)
585
+ or not re.fullmatch(r"[a-f0-9]{64}", payload["operation_id"])
586
+ or not isinstance(payload.get("arguments_digest"), str)):
587
+ raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.")
588
+ if session is None:
589
+ raise err(400, "confirmation_session_required", "Read this confirmation through its authenticated connection.")
590
+ if any(payload.get(key) != value for key, value in _operation_bindings(session).items()):
591
+ raise err(403, "confirmation_principal_changed", "This confirmation belongs to another account or connection.")
592
+ _, item = _load_operation(session, payload["operation_id"], confirming=True)
593
+ # The stored arguments return unchecked here; confirm_change refuses them as stale unless their digest matches.
594
+ return {**payload, "v": 1, "arguments": copy.deepcopy(item["payload"].get("arguments"))}
595
  if payload["v"] == 2:
596
  if (set(payload) != {"v", "operation_id", "payload_digest", "tenant", "actor", "credential", "authentication"}
597
  or not isinstance(payload.get("operation_id"), str)
 
1144
  _, args = tool_groups.resolve(tool_name, arguments)
1145
  _assert_workbook_scope(session, args["workbook_id"])
1146
  elif not external_access.may_write(access):
1147
+ import tool_groups
1148
+ # A group tool names the fix. A legacy tool keeps its published sentence.
1149
+ fix = (", so connect with a Read and write key and call again"
1150
+ if isinstance(tool_name, str) and tool_groups.canonical_name(tool_name) in tool_groups.groups()
1151
+ else "")
1152
+ raise err(403, "key_read_only", f"{tool_name} writes, and this credential is read only{fix}.")
1153
  code = _test_environment_refusal(session)
1154
  if code:
1155
  raise err(403, code, MCP_RESULT_CODES[code])
 
3615
  flush="sync", expect_rev=expected_rev)
3616
  except (view_audit.ViewRevisionStale, view_audit.RevisionUnverifiable) as exc:
3617
  raise err(409, "confirmation_stale",
3618
+ "The database changed after the preview, " + _STALE_FIX) from exc
3619
  return {"database": database, **copy.deepcopy(plan.get("planned") or {}),
3620
  "affected": copy.deepcopy(plan.get("affected") or {})}
3621
 
 
4063
  return wiki_log.purpose_line(value)
4064
 
4065
 
4066
+ def _build_about_normalised(value):
4067
+ """Trim and lower-case tags, collapse repeats in first-seen order, and rewrite dashes in title and description."""
4068
+ if not isinstance(value, dict):
4069
+ return value
4070
+ value = dict(value)
4071
+ for key in ("title", "description"):
4072
+ if isinstance(value.get(key), str):
4073
+ # A dash at either end has no clause to join, so it goes before the rewrite.
4074
+ trimmed = value[key].strip().strip(dash_norm._DASH_CHARS).strip()
4075
+ value[key] = dash_norm.plain(trimmed).strip() if trimmed else trimmed
4076
+ if isinstance(value.get("tags"), list):
4077
+ tags = [tag.strip().lower() if isinstance(tag, str) else tag for tag in value["tags"]]
4078
+ value["tags"] = list(dict.fromkeys(tags)) if all(isinstance(tag, str) for tag in tags) else tags
4079
+ return value
4080
+
4081
+
4082
  def _build_about(value):
4083
+ value = _build_about_normalised(value)
4084
  missing = ["about." + key for key in ("title", "description", "tags")
4085
  if not isinstance(value, dict) or key not in value]
4086
  example = {"about": {"title": "Weekly sales review", "description": "Review weekly sales before the team meeting.",
 
4121
  else "[unknown]") for key in value if key not in rules]
4122
  invalid = invalid or ["about"]
4123
  details = {"missing": missing, "invalid": invalid, "example": example}
4124
+ message = ("Send about with title, description and tags." if value is None
4125
+ else "Send about as an object with title, description and tags." if not isinstance(value, dict)
4126
+ else "Add " + ", ".join(missing) + " to about." if missing
4127
  else "Fix " + ", ".join(invalid) + ".")
4128
  if not isinstance(value, dict) or "about.tags" in invalid or "about.tags" in missing:
4129
  details["allowed"] = tags
 
4196
  about = _build_about(about)
4197
  build_kind = _external_build_kind(name, arguments)
4198
  environment = _write_environment()
4199
+ normalised = json.loads(_canonical_json(arguments, capped=False).decode("utf-8"))
4200
  _assert_tool_database_scope(session, name, normalised)
4201
 
4202
  preview_runtime = _PreviewRuntime(session.runtime)
 
4228
  projected = _request_preview_documents(session, normalised["arguments"]["id"], documents)
4229
  else:
4230
  projected = _public_preview_documents(session, documents)
4231
+ # The whole diff is computed and digested. Only its display is summarised (rule 1).
4232
+ diff, _ = _diff_documents(projected, limit=None)
4233
+ warnings = []
4234
  affected = _affected_for(name, normalised, diff, result)
4235
  current_revision = {
4236
  key: revision for key, revision in preview_runtime.base_revisions().items()
 
4250
  {"user": row["user"], "role": row["role"]}
4251
  for row in result["current_entries"]]
4252
 
4253
+ _canonical_json(diff, capped=False)
4254
  diff_digest = _json_digest(diff)
4255
+ shown_diff, diff_summary = (diff, None) if plan is not None else _summarise_diff(diff, projected)
4256
+ if diff_summary is not None:
4257
+ warnings.append(f"The preview shows {diff_summary['sample']} of {diff_summary['changes']} changes. "
4258
+ "confirm_change applies all of them.")
4259
+ if len(affected.get("ranges") or []) > _PREVIEW_SAMPLE_CHANGES:
4260
+ affected = {**affected, "ranges": [
4261
+ {key: row[key] for key in ("workbook_id", "tab", "range")} for row in diff_summary["ranges"]]}
4262
  revision_digest = plan["source_fingerprint"] if remote_note else _json_digest(current_revision)
4263
  expires_at = int(time.time()) + _CONFIRMATION_TTL_SECONDS
4264
  payload = {
 
4288
  "operation_id": payload["operation_id"], "state": "not_committed",
4289
  "preview": True, "mutated": False, "tool": name,
4290
  "environment": environment,
4291
+ "diff": shown_diff, "diff_digest": diff_digest,
4292
  "affected": affected, "warnings": warnings,
4293
  "current_revision": current_revision,
4294
  "expires_at": expires_at, "requires_confirmation": True,
4295
  "strong_confirmation_required": payload["strong"],
4296
  "about": copy.deepcopy(about), "buildKind": build_kind,
4297
  }
4298
+ if diff_summary is not None:
4299
+ response["diff_summary"] = diff_summary
4300
  if purpose is not None:
4301
  response["purpose"] = purpose
4302
  if remote_note:
 
4329
  session.claims.get("external_workbooks", [])])
4330
 
4331
 
4332
+ def _prune_operations(raw, removed=None):
4333
+ """Drop expired claims. The argument documents of dropped claims are added to removed."""
4334
  doc = raw if isinstance(raw, dict) else {}
4335
  now = time.time()
4336
+ kept = {}
4337
+ for key, value in (doc.get("claims") or {}).items():
4338
+ if isinstance(value, dict) and float(value.get("retain_until", value.get("expiry", 0))) >= now:
4339
+ kept[key] = value
4340
+ elif removed is not None and isinstance(value, dict) and isinstance(value.get("arguments_ref"), dict):
4341
+ removed.append(value["arguments_ref"].get("key"))
4342
+ doc["claims"] = kept
4343
  return doc
4344
 
4345
 
4346
+ _OPERATION_ARGUMENTS_PREFIX = "external_confirmation_arguments_"
4347
+ _OPERATION_ARGUMENT_STUB_BYTES = 4096
4348
+
4349
+
4350
+ def _drop_operation_documents(session, keys):
4351
+ """Remove argument documents, best effort. Call it after the bucket update, never inside it."""
4352
+ for key in keys:
4353
+ if not isinstance(key, str) or not key.startswith(_OPERATION_ARGUMENTS_PREFIX):
4354
+ continue
4355
+ try:
4356
+ session.runtime.delete_document(key)
4357
+ except Exception:
4358
+ try:
4359
+ session.runtime.put(key, {})
4360
+ except Exception:
4361
+ pass
4362
+
4363
+
4364
+ def _holds_arguments_apart(payload):
4365
+ """True when a stored operation keeps its arguments in their own document."""
4366
+ return _arguments_outside_token(payload)
4367
+
4368
+
4369
+ def _receipt_arguments(arguments):
4370
+ """Keep the small top-level arguments a receipt check reads after the full document is removed."""
4371
+ return {key: copy.deepcopy(value) for key, value in arguments.items()
4372
+ if len(_canonical_json(value, capped=False)) <= _OPERATION_ARGUMENT_STUB_BYTES}
4373
+
4374
+
4375
  def _store_operation(session, payload, preview, staged, intent=None):
4376
  """Keep the preview identity outside every affected object's revision."""
4377
  operation_id = payload["operation_id"]
 
4401
  if isinstance(intent, str):
4402
  # Intent stays outside the signed payload, redacted, so confirm_change can reuse it.
4403
  item["intent"] = audit.redact_intent(intent)
4404
+ stored_arguments = copy.deepcopy(payload["arguments"])
4405
+ if payload["tool"] == "apps":
4406
+ from tool_groups.apps import pending_arguments
4407
+ stored_arguments = pending_arguments(payload["arguments"], encode=True)
4408
+ ref = None
4409
+ if _holds_arguments_apart(payload):
4410
+ # Large arguments get their own document, so every other preview keeps a small bucket.
4411
+ ref = {"key": _OPERATION_ARGUMENTS_PREFIX + operation_id, "digest": _json_digest(stored_arguments)}
4412
+ session.runtime.put(ref["key"], {"operation_id": operation_id, "arguments": stored_arguments})
4413
+ item["arguments_ref"] = ref
4414
+ item["receipt_arguments"] = _receipt_arguments(stored_arguments)
4415
+ removed = []
4416
+
4417
  def save(raw):
4418
+ removed.clear()
4419
+ doc = _prune_operations(raw, removed)
4420
  if operation_id in doc["claims"]:
4421
+ raise err(409, "confirmation_stale", "This preview was already saved, " + _STALE_FIX)
4422
  stored_item = copy.deepcopy(item)
4423
+ if ref is None:
4424
+ stored_item["payload"]["arguments"] = copy.deepcopy(stored_arguments)
4425
+ else:
4426
+ stored_item["payload"].pop("arguments", None)
4427
  doc["claims"][operation_id] = stored_item
4428
  return doc
4429
+ try:
4430
+ session.runtime.update(_CONFIRMATION_BUCKET, save, flush="sync")
4431
+ except Exception:
4432
+ if ref is not None:
4433
+ _drop_operation_documents(session, [ref["key"]])
4434
+ raise
4435
+ _drop_operation_documents(session, removed)
4436
 
4437
 
4438
  def _operation_access(session, item, *, confirming=False):
 
4556
  if (not isinstance(item, dict) or "payload" not in item
4557
  or item.get("retain_until", 0) < time.time()):
4558
  raise err(404, "operation_unavailable", _OPERATION_UNAVAILABLE_MESSAGE)
4559
+ if isinstance(item.get("arguments_ref"), dict):
4560
+ item = copy.deepcopy(item)
4561
+ ref = item["arguments_ref"]
4562
+ held = session.runtime.get(ref.get("key"), fresh=True) if str(ref.get("key", "")).startswith(
4563
+ _OPERATION_ARGUMENTS_PREFIX) else None
4564
+ if (isinstance(held, dict) and held.get("operation_id") == operation_id
4565
+ and isinstance(held.get("arguments"), dict) and _json_digest(held["arguments"]) == ref.get("digest")):
4566
+ item["payload"]["arguments"] = held["arguments"]
4567
+ elif item.get("status") != "preview" and isinstance(item.get("receipt_arguments"), dict):
4568
+ # A confirmed operation removed its document. Its receipt reads the small arguments kept in the claim.
4569
+ item["payload"]["arguments"] = item["receipt_arguments"]
4570
+ else:
4571
+ raise err(409, "confirmation_stale", "This preview's saved arguments are gone, " + _STALE_FIX)
4572
  if item["payload"]["tool"] == "apps":
4573
  from tool_groups.apps import pending_arguments
4574
  item = copy.deepcopy(item)
 
4602
 
4603
  def _operation_status(session, args):
4604
  """Read a retained result without changing any object or operation revision."""
4605
+ import catalog_store
4606
+ # A long Catalog PDF export is an operation too. Only its own caller can read it.
4607
+ export = catalog_store.export_status(session, args["operation_id"])
4608
+ if export is not None:
4609
+ return export
4610
  _, item = _load_operation(session, args["operation_id"])
4611
  return _operation_result(args["operation_id"], item)
4612
 
 
4743
  return response
4744
 
4745
 
4746
+ _STALE_FIX = "so repeat the original call for a new preview and confirm with its new confirmation_token."
4747
+
4748
+
4749
+ def _confirm_fix(args):
4750
+ """Name what a confirm_change call got wrong and the shape that succeeds."""
4751
+ allowed = ("confirmation_token", "confirmation_phrase", "intent")
4752
+ extra = sorted(str(key) for key in args if key not in allowed) if isinstance(args, dict) else []
4753
+ phrase = args.get("confirmation_phrase", "") if isinstance(args, dict) else ""
4754
+ cause = (extra[0] + " is not a confirm_change field" if len(extra) == 1
4755
+ else ", ".join(extra) + " are not confirm_change fields" if extra
4756
+ else "confirmation_phrase is not text" if isinstance(args, dict)
4757
+ and isinstance(args.get("confirmation_token"), str) and not isinstance(phrase, str)
4758
+ else "confirmation_token is missing or not text")
4759
+ return (cause + ", so send only confirmation_token from the preview, plus confirmation_phrase "
4760
+ "when the preview asks for it.")
4761
+
4762
+
4763
  def _confirm_change(session, args):
4764
  from core import view_audit, write_execution
4765
 
 
4776
  return _operation_result(operation_id, stored)
4777
  _assert_write_scope(fresh_session, payload.get("tool"), payload.get("arguments"))
4778
  if payload.get("environment") != _write_environment():
4779
+ raise err(409, "confirmation_stale", "The environment changed after the preview, " + _STALE_FIX)
4780
  if int(payload.get("expiry") or 0) <= int(time.time()):
4781
  raise err(409, "confirmation_expired",
4782
  "This confirmation token expired. Preview the change again.")
 
4789
  execution = payload.get('execution')
4790
  if (not isinstance(execution, dict) or not isinstance(execution.get('seed'), str)
4791
  or not execution['seed'] or type(execution.get('timestamp')) not in (int, float)):
4792
+ raise err(409, 'confirmation_stale', 'This preview is no longer current, ' + _STALE_FIX)
 
4793
  try:
4794
  _confirmation_claim(fresh_session, operation_id)
4795
  except _OperationAlreadyClaimed:
 
4810
  or any((key in payload, payload.get(key)) != (key in current, current.get(key))
4811
  for key in ("purpose", "purpose_digest", "about", "about_digest", "buildKind"))):
4812
  raise err(409, "confirmation_stale",
4813
+ "The data, permissions, or resulting diff changed after the preview, " + _STALE_FIX)
4814
  if remote_note:
4815
  import website_tools
4816
  ctx = _tool_context(fresh_session)
 
4839
  {"state": "unknown", "applied": None, "reason": "remote_response_lost"})
4840
  _confirmation_status(fresh_session, operation_id, "failed")
4841
  raise err(409, "confirmation_stale",
4842
+ "The data changed while this change was being saved, " + _STALE_FIX) from exc
4843
  except Exception:
4844
  if remote_note and capability is not None and capability.transport_started:
4845
  return _finish_website_note(fresh_session, payload, recomputed["_plan"],
 
4885
  if tool == "apps" and arguments.get("action") == "catalog_build":
4886
  response.update({key: copy.deepcopy(result[key]) for key in _CATALOG_BUILD_RESULT_FIELDS})
4887
  _confirmation_status(fresh_session, operation_id, "committed", response)
4888
+ if isinstance(stored.get("arguments_ref"), dict):
4889
+ _drop_operation_documents(fresh_session, [stored["arguments_ref"].get("key")])
4890
  if tool != "database_object" and receipt.get("persisted") is True:
4891
  try:
4892
  targets, native_ids = _committed_build_evidence(fresh_session, guarded_session.runtime, arguments,
 
4976
  ("Check the View's sharing settings before changing it.", """
4977
  view_is_shared view_not_personal share_owner_redundant share_role_unknown share_who_required
4978
  """),
4979
+ # Catalog refusals keep their own code. An unpublished code collapsed to tool_refused.
4980
+ ("The catalog selection or design is invalid. Correct the field the refusal names and preview again.", """
4981
+ catalog_selection_invalid catalog_design_invalid catalog_view_invalid catalog_skus_invalid
4982
+ catalog_skus_missing catalog_sku_ambiguous catalog_key_ambiguous catalog_no_matches catalog_empty
4983
+ catalog_source_mismatch invalid_catalog invalid_catalog_paper invalid_catalog_cursor invalid_catalog_limit
4984
+ """),
4985
+ ("The Catalog App or its fields are not available to this account.", """
4986
+ catalog_app_unavailable catalog_app_not_found catalog_forbidden catalog_fields_forbidden
4987
+ catalog_source_forbidden catalog_tenant_forbidden
4988
+ """),
4989
+ ("Catalog storage did not finish this request. Read the catalog again, then retry.", """
4990
+ catalog_query_incomplete catalog_id_conflict catalog_migration_invalid catalog_save_failed
4991
+ catalog_store_invalid catalog_export_failed
4992
+ """),
4993
  )
4994
  MCP_RESULT_CODES = {
4995
  code: reason for reason, codes in _MCP_CODE_GROUPS for code in codes.split()
 
5005
  "unknown_people": "Choose active people in this workspace.",
5006
  "grant_exceeds_role": "You cannot grant a role above your own access.",
5007
  "revoke_not_yours": "You can remove only people you added.",
5008
+ "field_not_shared": "A field in this View is private to its creator. Hide it in the View or ask its creator to share it.",
5009
  "key_refresh_only": "This connection can only refresh source cells in its granted workbooks.",
5010
  "key_workbook_out_of_scope": "This connection cannot refresh this workbook.",
5011
  "external_workbooks_invalid": "Choose up to 100 workbook ids. All workbooks is not a valid choice.",
 
5023
  "operation_pending": "The change is still being saved. Ask again shortly.",
5024
  "operation_not_committed": "This change has not been committed.",
5025
  "operation_unavailable": _OPERATION_UNAVAILABLE_MESSAGE,
5026
+ "catalog_not_found": ("No stored catalog has this catalog_id. Use the catalog_id that apps.catalog_build "
5027
+ "returned, after confirm_change committed that build."),
5028
  "credential_in_arguments": "Remove credential values from the arguments.",
5029
+ "build_about_required": ("Send about with title, description of 20 to 240 characters, and tags from the guide, "
5030
+ "beside action and arguments or inside arguments. See missing and example."),
5031
  "build_about_invalid": ("Fix the fields in invalid. Use a nonempty title, a description of 20 to 240 characters, "
5032
  "and tags from allowed, each once: " + ", ".join(external_tools.BUILD_TAGS) + "."),
5033
+ "call_intent_required": ("Send intent explaining why you are making this write, beside action and arguments "
5034
+ "or inside arguments. See example."),
5035
  "call_intent_invalid": "Send intent as a string of 1 to 500 characters. See example.",
5036
  "invalid_external_credential": "The credential is invalid, expired, or revoked.",
5037
  "credential_in_output": "The result contained a credential value and was withheld.",
 
5133
  "revision_before", "revision_after", "filters", "sorts", "config", "binding", "bindings",
5134
  })
5135
  _MCP_RESULT_IDENTIFIERS = frozenset({
5136
+ "resourceUri", "deepLink", "pdfLink", "downloadUrl", "src", "websiteUrl", "fileId", "link", "href",
5137
  "id", "ids", "operation_id", "key", "keys", "pid", "pids", "database", "databases", "sourceDatabase",
5138
  "compatibleDatabases", "field", "fields", "field_key", "colId", "metric_key", "groupBy",
5139
  "workbook_id", "worksheet", "tab", "view_id", "app_id", "catalog_id", "chart_id", "record_id", "contextId",
 
5294
  return {"jsonrpc": "2.0", "id": rid, "error": {"code": code, "message": out["reason"], "data": out}}
5295
 
5296
 
5297
+ def _mcp_file_resource(rid, session, uri):
5298
+ """Answer resources/read for a caller's own file with its bytes as a base64 blob."""
5299
+ import assistant_files
5300
+ from loopy_catalog_tools import FILE_RESOURCE_PREFIX
5301
+ try:
5302
+ item = _external_file(session, uri[len(FILE_RESOURCE_PREFIX):])
5303
+ data = assistant_files.read_bytes(session.runtime, item)
5304
+ except HTTPException as exc:
5305
+ if exc.status_code == 401:
5306
+ _auth_refusal()
5307
+ data = None
5308
+ except Exception:
5309
+ data = None
5310
+ if data is None:
5311
+ return _mcp_protocol_error(rid, -32602, "That resource is not available.")
5312
+ return {"jsonrpc": "2.0", "id": rid, "result": {"contents": [{
5313
+ "uri": uri, "mimeType": item["mime"], "name": item["filename"],
5314
+ "blob": base64.b64encode(data).decode("ascii")}]}}
5315
+
5316
+
5317
  def _mcp_protocol_result(rid, data):
5318
  out = _shape_mcp_result({"ok": True, "data": data})
5319
  return {"jsonrpc": "2.0", "id": rid, "result": {
 
5327
  # `loopable_guide` tool (every client can call a tool). ⛔ Model-facing text is user-facing copy:
5328
  # no em or en dashes here.
5329
  MCP_GUIDE_TOOL = "loopable_guide"
5330
+ from tool_groups import INTENT_SCHEMA as _MCP_INTENT_SCHEMA # noqa: E402 - one schema for base and served specs
 
5331
  MCP_INSTRUCTIONS = "\n".join([
5332
  "1. Loopable is a governed business data workspace: Table databases, saved Views, Sheet workbooks and "
5333
  "Apps. Every call runs as the signed-in user, with that user's own permissions. "
 
5349
  "intelligence.create_wiki publishes a new wiki/ page at once without preview, confirmation or owner approval. "
5350
  "It cannot replace a committed page. Existing wiki edits use intelligence.propose with confirmation and file approval. "
5351
  "Send intent beside action and arguments on every write, including confirm_change. "
5352
+ "If your client sends only action and arguments, put intent and about inside arguments. "
5353
  "Reads may send intent. Use 1 to 500 characters explaining why you are making this call."
5354
  " Use requests.list_team for teammate names and last-active times, requests.send_message for questions or change proposals, "
5355
  "requests.check_inbox for incoming requests, and requests.ask_user for recipient Approve or Deny decisions. "
 
5378
  "name": MCP_GUIDE_TOOL,
5379
  "description": "Read workspace connections, your skills, databases and the group index, "
5380
  "or choose a group for its actions and argument schemas.",
5381
+ "inputSchema": {"type": "object", "properties": {"action": {"type": "string", "enum": ["read"]},
5382
+ "group": {"type": "string"}}, "required": [],
5383
  "additionalProperties": False},
5384
  "annotations": {"title": "Loopable guide", "readOnlyHint": True,
5385
  "destructiveHint": False, "openWorldHint": False},
 
5736
  def _mcp_guide(session: Session, group=None) -> str:
5737
  """Return the group index or one group's action schemas without reading records."""
5738
  import tool_groups
5739
+ groups = tool_groups.groups()
5740
+ if isinstance(group, str) and group not in groups and group != "data":
5741
+ # A cased, plural or dotted name (Sheets, sheet.write_cells) reads the one group it names.
5742
+ key = group.strip().lower().partition(".")[0]
5743
+ group = next((name for name in (key, key[:-1] if key.endswith("s") else None)
5744
+ if name in groups or name == "data"), group)
5745
  alias = group == "data"
5746
  group = tool_groups.canonical_name(group)
 
5747
  if group is not None and group not in groups:
5748
+ raise sheets.SheetRefusal("tool_not_found", "Set group to one of: " + ", ".join(groups)
5749
+ + ". Omit group to read the index.")
5750
  # One rows-free definitions read per guide: a live runtime pays one pool checkout per database.
5751
  # The guide reads schemas only, so no reader here needs `rows`. On a failed read, keep the old path.
5752
  try:
 
5871
  group_names = set(groups)
5872
  for spec in specs:
5873
  spec["inputSchema"]["properties"]["intent"] = copy.deepcopy(_MCP_INTENT_SCHEMA)
5874
+ # Every write-capable tool requires intent. Groups carry it from tool_groups.tool_specs.
5875
  if spec["name"] == "confirm_change":
5876
  spec["inputSchema"]["required"] = [*spec["inputSchema"].get("required", []), "intent"]
5877
  if spec["name"] in group_names:
 
6054
  def _mcp_saved_intent(session, arguments):
6055
  """Return the intent saved with the preview the signed token names, or None."""
6056
  try:
6057
+ payload = _read_confirmation_token(arguments.get("confirmation_token"), session=session)
6058
  _, stored = _load_operation(session, payload.get("operation_id", ""), confirming=True)
6059
  if stored["payload"] != payload:
6060
  return None
 
6064
  return intent if isinstance(intent, str) and intent.strip() else None
6065
 
6066
 
6067
+ def _mcp_decode_about(arguments):
6068
+ """Return arguments with an about sent as JSON object text decoded, or the same object unchanged."""
6069
+ if not isinstance(arguments.get("about"), str):
6070
+ return arguments
6071
+ try:
6072
+ decoded = json.loads(arguments["about"])
6073
+ except ValueError:
6074
+ return arguments
6075
+ return {**arguments, "about": decoded} if isinstance(decoded, dict) else arguments
6076
+
6077
+
6078
  def _mcp_hoist_call_metadata(name, arguments):
6079
  """Return group call arguments with intent, about and purpose lifted out of the inner arguments."""
6080
  import tool_groups
6081
  keys = ("intent", "about", "purpose")
6082
+ if isinstance(arguments, dict) and isinstance(arguments.get("arguments"), str):
6083
+ # Some clients send arguments as a JSON object string. Only an object decodes.
6084
+ try:
6085
+ decoded = json.loads(arguments["arguments"])
6086
+ except ValueError:
6087
+ decoded = None
6088
+ if isinstance(decoded, dict):
6089
+ arguments = {**arguments, "arguments": decoded}
6090
+ if isinstance(arguments, dict):
6091
+ # about sent as JSON object text decodes the same way, beside action and arguments or inside arguments.
6092
+ arguments = _mcp_decode_about(arguments)
6093
+ if isinstance(arguments.get("arguments"), dict):
6094
+ inner = _mcp_decode_about(arguments["arguments"])
6095
+ if inner is not arguments["arguments"]:
6096
+ arguments = {**arguments, "arguments": inner}
6097
+ canonical = tool_groups.canonical_call(name, arguments)[0] if isinstance(name, str) else None
6098
+ if canonical in {"confirm_change", MCP_GUIDE_TOOL} and isinstance(arguments, dict):
6099
+ # A flat tool called in the group shape unwraps: its fields beside action and arguments win.
6100
+ flat = {key: value for key, value in arguments.items() if key != "arguments"}
6101
+ # "call" and "confirm" name the same step as confirm_change.
6102
+ if canonical == "confirm_change" and flat.get("action") in ("confirm_change", "call", "confirm"):
6103
+ flat.pop("action")
6104
+ if isinstance(arguments.get("arguments"), dict):
6105
+ return {**arguments["arguments"], **flat}
6106
+ return flat if "arguments" not in arguments else arguments
6107
  # The Table group's `data` alias hoists like `table` (C4).
6108
+ if (canonical not in tool_groups.groups()
6109
  or not isinstance(arguments, dict)
6110
  or not isinstance(arguments.get("arguments"), dict)
6111
  or not any(key in arguments["arguments"] for key in keys)):
 
6119
  return hoisted
6120
 
6121
 
6122
+ def _mcp_intent_fix(name):
6123
+ """Name the intent field and where this tool takes it."""
6124
+ import tool_groups
6125
+ if name == "confirm_change":
6126
+ return ("Send intent beside confirmation_token: 1 to 500 characters on why you are confirming this change. "
6127
+ "A client that sends only action and arguments may put both inside arguments.")
6128
+ if tool_groups.canonical_call(name, {})[0] in tool_groups.groups():
6129
+ return ("Send intent beside action and arguments: 1 to 500 characters on why you are making this write. "
6130
+ "If your client sends only action and arguments, put intent inside arguments.")
6131
+ return "Send intent beside this tool's other arguments: 1 to 500 characters on why you are making this write."
6132
+
6133
+
6134
+ def _mcp_about_fix(name):
6135
+ """Name where a group call takes about, or nothing for a flat tool."""
6136
+ import tool_groups
6137
+ if isinstance(name, str) and tool_groups.canonical_call(name, {})[0] in tool_groups.groups():
6138
+ return (" Put about beside action and arguments. "
6139
+ "If your client sends only action and arguments, put about inside arguments.")
6140
+ return ""
6141
+
6142
+
6143
  def _mcp_requires_intent(name, arguments):
6144
  """Classify declared writes before argument validation can mask the intent requirement."""
6145
  import tool_groups
 
6161
  if isinstance(req, dict) and req.get("method") == "tools/call" and isinstance(req.get("params"), dict):
6162
  params = req["params"]
6163
  original = params.get("name")
6164
+ raw = params.get("arguments", {})
6165
+ name, arguments = tool_groups.canonical_call(original, raw)
6166
  alias = isinstance(original, str) and (original == "data" or original.startswith("data.")) and name == "table"
6167
+ if name != original or arguments is not raw:
6168
  req = {**req, "params": {**params, "name": name, "arguments": arguments}}
6169
  reply = _dispatch_mcp_call(req, session, base_url)
6170
  if alias and isinstance(reply, dict) and "content" in reply.get("result", {}):
 
6193
  if not isinstance(params, dict):
6194
  return protocol_error(rid, -32602, "MCP params must be an object.")
6195
  name = params.get("name")
6196
+ called = name
6197
+ arguments = params.get("arguments", {})
6198
  try:
6199
  # Same AI apps wall as the read doors, inside the dispatcher so a grant refusal
6200
  # remains MCP content. Only the unchanged bearer dependency produces an HTTP 401.
 
6232
  "_meta": {"ui": {"csp": {"connectDomains": [], "resourceDomains": [], "frameDomains": []}}}}
6233
  if method == "resources/list":
6234
  return {"jsonrpc": "2.0", "id": rid, "result": {"resources": [resource]}}
6235
+ from loopy_catalog_tools import FILE_RESOURCE_PREFIX
6236
+ uri = params.get("uri")
6237
+ if isinstance(uri, str) and uri.startswith(FILE_RESOURCE_PREFIX):
6238
+ return _mcp_file_resource(rid, session, uri)
6239
  if params.get("uri") != WORKBOOK_RESOURCE_URI:
6240
  return protocol_error(rid, -32602, "That resource is not available.")
6241
  resource["text"] = (Path(__file__).parent / "side_view" / "workbook.html").read_text(encoding="utf-8")
 
6249
  if intent is not None:
6250
  external_activity.note_saved_intent(intent)
6251
  if intent is None and _mcp_requires_intent(name, arguments):
6252
+ raise err(400, "call_intent_required", _mcp_intent_fix(name),
6253
  {"example": {"intent": "Prepare the weekly sales review"}})
6254
  if isinstance(arguments, dict):
6255
  arguments = {key: value for key, value in arguments.items() if key != "intent"}
 
6283
  or action in {"describe_database", "query_database"}):
6284
  from tool_groups.data import READ_ARGUMENT_HELP
6285
  raise sheets.SheetRefusal(exc.code, exc.message + " " + READ_ARGUMENT_HELP) from exc
6286
+ if (tool_groups.canonical_name(name) == "views" and exc.code == "tool_arguments_invalid"
6287
+ and isinstance(arguments, dict) and arguments.get("action") == "share"):
6288
+ from tool_groups.views import share_arguments_fix
6289
+ raise sheets.SheetRefusal(exc.code, share_arguments_fix(arguments)) from exc
6290
  raise
6291
  confirm = True
6292
  scoped_arguments = arguments
 
6351
  out = _tool_refusal(name, "external_access_unavailable", "The AI API is unavailable right now.", 503)
6352
  except sheets.SheetRefusal as exc:
6353
  import routes_sheet
6354
+ if exc.code == "tool_arguments_invalid" and name == "confirm_change":
6355
+ exc = sheets.SheetRefusal(exc.code, _confirm_fix(arguments))
6356
  translated = routes_sheet._refuse(exc)
6357
  info = translated.detail["error"]
6358
  out = _tool_refusal(name, info["code"], info["message"], translated.status_code,
 
6374
  retry["suggestions"] = details.get("suggestions", [])
6375
  if info.get("code") == "workbook_name_ambiguous" and isinstance(details, dict):
6376
  retry["candidates"] = details.get("candidates", [])
6377
+ message = info.get("message", "The app refused this operation.")
6378
+ if info.get("code") == "build_about_required" and isinstance(message, str):
6379
+ message += _mcp_about_fix(called)
6380
+ out = _tool_refusal(name, info.get("code", "tool_refused"), message, exc.status_code, **retry)
6381
  except (TypeError, ValueError, KeyError, AttributeError):
6382
  out = _tool_refusal(name, "tool_arguments_invalid", "The arguments could not be read. Use the published input schema.")
6383
  except Exception:
6384
+ out = _tool_refusal(name, "tool_unavailable",
6385
+ "The tool could not complete this operation, so try the same call again shortly.", 503)
6386
  return _mcp_content(rid, out, session)
6387
 
6388
 
 
6393
  req = await request.json()
6394
  except (ValueError, UnicodeError):
6395
  return _mcp_protocol_error(None, -32700, "The request body must be valid JSON.")
6396
+ reply = await run_in_threadpool(_handle_mcp, req, session, _mcp_public_origin(request))
6397
  return Response(status_code=204) if reply is None else reply
6398
 
6399
 
6400
+ def _mcp_public_origin(request: Request) -> str:
6401
+ """C3: MCP links use the deployment's public base; only an unconfigured local run uses the request."""
6402
+ import loopy_links
6403
+ return loopy_links.public_base() or str(request.base_url)
6404
+
6405
+
6406
+ def _external_file(session: Session, file_id):
6407
+ """Return this caller's own file metadata when every source is inside the credential scope."""
6408
+ import assistant_files
6409
+ require_external_analyst(session)
6410
+ item = assistant_files.owned_metadata(session.runtime, session.uname, file_id)
6411
+ sources = (item or {}).get("sources")
6412
+ if item is None or session.tenant != item["tenant"] or not isinstance(sources, list) or not sources:
6413
+ raise err(404, "unknown_file", "That file does not exist.")
6414
+ for database in sources:
6415
+ _assert_database_scope(session, database)
6416
+ _external_read_scope(session, database, fields=[], mode="schema")
6417
+ return item
6418
+
6419
+
6420
+ @router.get("/files/{file_id}")
6421
+ def external_file(file_id: str, session: Session = Depends(require_external_session)):
6422
+ """Download a file this credential's own tool call produced, with the same bearer credential."""
6423
+ import routes_files
6424
+ return routes_files._response(session.runtime, _external_file(session, file_id))
6425
+
6426
+
6427
  # R8 (SDLC 61) revokes the read-only surface. Every write must be named here deliberately.
6428
  # A new write in the registry without a matching literal raises at import, before serving.
6429
  _WRITE_TOOLS = frozenset({
api/routes_forms.py CHANGED
@@ -410,11 +410,12 @@ def _clean_values(fields: list, raw: dict):
410
  def _public_base() -> str:
411
  """The origin a share link is built on. Empty = the client builds it from its own location.
412
 
413
- `AIOS_PUBLIC_BASE` is the same variable the OAuth callback resolves against, so a domain move
414
- takes the form links with it. Absent, we return a PATH rather than guessing a hostname:
415
  a link with the wrong origin looks right, gets pasted into an email and 404s for the reader.
416
  """
417
- return (os.environ.get("AIOS_PUBLIC_BASE") or os.environ.get("APP_BASE_URL") or "").rstrip("/")
 
418
 
419
 
420
  def _link_of(token: str) -> str:
 
410
  def _public_base() -> str:
411
  """The origin a share link is built on. Empty = the client builds it from its own location.
412
 
413
+ `loopy_links.public_base()` reads `AIOS_PUBLIC_BASE` like the OAuth callback, and live never
414
+ answers *.hf.space (C3). With no base it returns a PATH rather than guessing a hostname:
415
  a link with the wrong origin looks right, gets pasted into an email and 404s for the reader.
416
  """
417
+ import loopy_links
418
+ return loopy_links.public_base() or ""
419
 
420
 
421
  def _link_of(token: str) -> str:
api/routes_nav.py CHANGED
@@ -725,6 +725,8 @@ def nav(session: Session = Depends(require_session)):
725
  # marked as such. `degraded` is that mark; the shell renders it in the affected slot.
726
  _degraded.append("databases")
727
  pass
 
 
728
  # S73-T64: every viewer is admitted to the activity log, which then gates each event. Alone it
729
  # would turn "no access" and "no databases yet" into a rail holding one always-empty database,
730
  # so it rides only beside another page this session may open.
@@ -1479,7 +1481,7 @@ def update_schema_map_setup(key: str, body: dict = Body(default=None),
1479
  @router.get("/nav/application-templates")
1480
  def application_templates(session: Session = Depends(require_session)):
1481
  """The trusted template contracts the App creation flow may offer."""
1482
- return {"templates": application_registry.template_contracts()}
1483
 
1484
 
1485
  @router.post("/nav/applications", status_code=201)
@@ -1493,7 +1495,7 @@ def create_nav_application(body: dict = Body(default=None),
1493
  """
1494
  payload = body if isinstance(body, dict) else {}
1495
  template_kind = str(payload.get("templateKind") or "").strip().lower()
1496
- wizard_kinds = {row["kind"] for row in application_registry.template_contracts()}
1497
  if template_kind not in wizard_kinds:
1498
  raise err(400, "bad_application", "application template kind is not recognized")
1499
  source = str(payload.get("sourceDatabase") or "").strip()
 
725
  # marked as such. `degraded` is that mark; the shell renders it in the affected slot.
726
  _degraded.append("databases")
727
  pass
728
+ import external_freshness
729
+ external_freshness.amazon_nav(session, pages)
730
  # S73-T64: every viewer is admitted to the activity log, which then gates each event. Alone it
731
  # would turn "no access" and "no databases yet" into a rail holding one always-empty database,
732
  # so it rides only beside another page this session may open.
 
1481
  @router.get("/nav/application-templates")
1482
  def application_templates(session: Session = Depends(require_session)):
1483
  """The trusted template contracts the App creation flow may offer."""
1484
+ return {"templates": application_registry.template_contracts(session=session)}
1485
 
1486
 
1487
  @router.post("/nav/applications", status_code=201)
 
1495
  """
1496
  payload = body if isinstance(body, dict) else {}
1497
  template_kind = str(payload.get("templateKind") or "").strip().lower()
1498
+ wizard_kinds = {row["kind"] for row in application_registry.template_contracts(session=session)}
1499
  if template_kind not in wizard_kinds:
1500
  raise err(400, "bad_application", "application template kind is not recognized")
1501
  source = str(payload.get("sourceDatabase") or "").strip()
api/routes_odoo_attachments.py ADDED
@@ -0,0 +1,31 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Contract C5 (S78-T14): the delivery photo list and the photo bytes, behind the delivery read wall.
2
+
3
+ The work lives in `odoo_attachments.py`. This router decides who may ask and shapes the response.
4
+ Mounted by `main.py` through `_mount_router("routes_odoo_attachments")`.
5
+ """
6
+ from fastapi import APIRouter, Depends, Path
7
+ from fastapi.responses import Response
8
+
9
+ import odoo_attachments
10
+ from deps import Session, require_session
11
+
12
+ router = APIRouter(prefix="/api/v1")
13
+
14
+ _MAX_ID = 2 ** 31 - 1
15
+
16
+
17
+ @router.get("/odoo/deliveries/{picking_id}/photos")
18
+ def delivery_photos(picking_id: int = Path(..., ge=1, le=_MAX_ID), session: Session = Depends(require_session)):
19
+ """`[{id, name, mimetype, url}]`: every photo attachment of one delivery."""
20
+ return odoo_attachments.list_photos(session, picking_id)
21
+
22
+
23
+ @router.get("/odoo/attachments/{attachment_id}")
24
+ def delivery_photo(attachment_id: int = Path(..., ge=1, le=_MAX_ID), session: Session = Depends(require_session)):
25
+ """The photo bytes, streamed through and never stored."""
26
+ body, mimetype, _name = odoo_attachments.read_photo(session, attachment_id)
27
+ return Response(content=body, media_type=mimetype, headers={
28
+ "Cache-Control": "private, max-age=300",
29
+ "Content-Disposition": "inline",
30
+ "X-Content-Type-Options": "nosniff",
31
+ })
api/routes_publish.py CHANGED
@@ -186,7 +186,9 @@ def _equalise_pw_cost(entry) -> None:
186
 
187
 
188
  def _public_base() -> str:
189
- return (os.environ.get("AIOS_PUBLIC_BASE") or os.environ.get("APP_BASE_URL") or "").rstrip("/")
 
 
190
 
191
 
192
  def _link_of(token: str) -> str:
 
186
 
187
 
188
  def _public_base() -> str:
189
+ """The origin a published link is built on; live never links *.hf.space (C3)."""
190
+ import loopy_links
191
+ return loopy_links.public_base() or ""
192
 
193
 
194
  def _link_of(token: str) -> str:
api/routes_templates.py CHANGED
@@ -36,9 +36,10 @@ router = APIRouter(prefix="/api/v1")
36
 
37
  _TEMPLATE_CATEGORIES = {
38
  "sheet": "Sheet", "data": "Table", "app": "App", "agents": "Automation", "saved": "Saved",
39
- "route": "Operations", "catalog": "Sales",
40
  }
41
- _TEMPLATE_PREVIEW_LABELS = {**_TEMPLATE_CATEGORIES, "route": "Routing", "catalog": "Catalog"}
 
42
 
43
 
44
  @router.get("/templates/previews/{module}.svg")
@@ -74,6 +75,16 @@ M92 224h88 M240 224h38 M354 224h54"/>
74
  <g class="node"><circle cx="212" cy="116" r="10"/>
75
  <circle cx="276" cy="180" r="10"/><circle cx="352" cy="228" r="10"/></g>
76
  <path class="line" d="M308 116h96 M308 132h64 M212 228h72"/>
 
 
 
 
 
 
 
 
 
 
77
  </g>'''
78
  elif module == "catalog":
79
  drawing = '''<g id="catalog-collection">
@@ -349,6 +360,8 @@ def _catalog_row(key, name, description, requires, *, module="sheet", creation_m
349
  blocked = next((row for row in requires if row["state"] == "disconnected"), None)
350
  blocked = blocked or next((row for row in requires if row["state"] != "ready"), None)
351
  preview = key if module == "app" and key in ("route", "catalog") else module
 
 
352
  return {"key": key, "name": dash_norm.plain(str(name)),
353
  "description": dash_norm.plain(str(description)),
354
  "image": f"/api/v1/templates/previews/{preview}.svg",
@@ -608,7 +621,9 @@ def create_module_template(module: str, key: str, body: dict = Body(default=None
608
  if module == "agents":
609
  # A direct call to create_automation does not run its FastAPI dependency.
610
  session.require("automation")
611
- if module == "app" and key not in {"route", "catalog"}:
 
 
612
  raise err(404, "unknown_template", "That template does not exist.")
613
  section = next((row for row in _module_templates(session)["sections"] if row["module"] == module), None)
614
  template = next((row for row in section["templates"] if row["key"] == key), None) if section else None
 
36
 
37
  _TEMPLATE_CATEGORIES = {
38
  "sheet": "Sheet", "data": "Table", "app": "App", "agents": "Automation", "saved": "Saved",
39
+ "route": "Operations", "catalog": "Sales", "competitor_watch": "Sales",
40
  }
41
+ _TEMPLATE_PREVIEW_LABELS = {**_TEMPLATE_CATEGORIES, "route": "Routing", "catalog": "Catalog",
42
+ "competitor_watch": "Competitor watch"}
43
 
44
 
45
  @router.get("/templates/previews/{module}.svg")
 
75
  <g class="node"><circle cx="212" cy="116" r="10"/>
76
  <circle cx="276" cy="180" r="10"/><circle cx="352" cy="228" r="10"/></g>
77
  <path class="line" d="M308 116h96 M308 132h64 M212 228h72"/>
78
+ </g>'''
79
+ elif module == "competitor_watch":
80
+ # S78-T17: a ranked list beside a trend line, the App's own two panels.
81
+ drawing = '''<g id="competitor-watch">
82
+ <rect class="tint" x="44" y="92" width="184" height="32" rx="8"/>
83
+ <path class="line" d="M44 164h184 M44 204h184 M252 244h184 M252 92v152"/>
84
+ <path class="ink" d="M60 108h16 M92 108h96 M60 148h16 M92 148h72 M60 188h16 M92 188h88 M60 228h16 M92 228h56"/>
85
+ <path class="ink" d="M268 212l40-24 40 8 40-40 40-16"/>
86
+ <g class="node"><circle cx="268" cy="212" r="6"/><circle cx="308" cy="188" r="6"/>
87
+ <circle cx="348" cy="196" r="6"/><circle cx="388" cy="156" r="6"/><circle cx="428" cy="140" r="6"/></g>
88
  </g>'''
89
  elif module == "catalog":
90
  drawing = '''<g id="catalog-collection">
 
360
  blocked = next((row for row in requires if row["state"] == "disconnected"), None)
361
  blocked = blocked or next((row for row in requires if row["state"] != "ready"), None)
362
  preview = key if module == "app" and key in ("route", "catalog") else module
363
+ if module == "app" and key == "competitor_watch":
364
+ preview = key # S78-T17: the gated template draws its own preview.
365
  return {"key": key, "name": dash_norm.plain(str(name)),
366
  "description": dash_norm.plain(str(description)),
367
  "image": f"/api/v1/templates/previews/{preview}.svg",
 
621
  if module == "agents":
622
  # A direct call to create_automation does not run its FastAPI dependency.
623
  session.require("automation")
624
+ if module == "app" and key == "competitor_watch":
625
+ pass # S78-T17: gated by application_registry.template_contracts(session=...).
626
+ elif module == "app" and key not in {"route", "catalog"}:
627
  raise err(404, "unknown_template", "That template does not exist.")
628
  section = next((row for row in _module_templates(session)["sections"] if row["module"] == module), None)
629
  template = next((row for row in section["templates"] if row["key"] == key), None) if section else None
api/tool_groups/__init__.py CHANGED
@@ -8,6 +8,10 @@ from core import external_tools, sheets
8
 
9
  _GROUP_MODULE_NAMES = {"data": "table"}
10
  TABLE_ALIAS_NOTE = "The data tool is deprecated for one release. Use table for the Table module."
 
 
 
 
11
 
12
 
13
  def canonical_name(name):
@@ -15,14 +19,36 @@ def canonical_name(name):
15
  return "table" if name == "data" else name
16
 
17
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
18
  def canonical_call(name, arguments):
19
  """Adapt Table group aliases and dotted actions before normal admission."""
 
 
20
  if name == "data":
21
- return "table", arguments
22
  if not isinstance(name, str):
23
  return name, arguments
24
  prefix, separator, action = name.partition(".")
25
- if not separator or prefix not in {"table", "data"}:
 
 
26
  return name, arguments
27
  entry = groups().get("table", {}).get("actions", {}).get(action)
28
  if entry is None:
@@ -92,6 +118,14 @@ def resolve(name, arguments):
92
  group = groups().get(canonical_name(name)) if isinstance(name, str) else None
93
  if group is None:
94
  return None
 
 
 
 
 
 
 
 
95
  external_tools.validate_arguments(arguments, {
96
  "type": "object", "properties": {
97
  "action": {"type": "string", "enum": list(group["actions"])},
@@ -141,13 +175,21 @@ def action_grants(entry, group=""):
141
  return tuple(dict.fromkeys((*grants, *entry.get("grants", ()))))
142
 
143
 
 
 
 
 
 
144
  def tool_specs():
145
- """Publish compact group summaries with conservative effect hints."""
 
146
  return [{
147
  "name": name, "description": group["guide"],
148
  "inputSchema": {"type": "object", "properties": {
149
  "action": {"type": "string"}, "arguments": {"type": "object"},
150
- }, "required": ["action"], "additionalProperties": False},
 
 
151
  "annotations": {
152
  "title": group["title"],
153
  "readOnlyHint": all(entry["read"] for entry in group["actions"].values()),
 
8
 
9
  _GROUP_MODULE_NAMES = {"data": "table"}
10
  TABLE_ALIAS_NOTE = "The data tool is deprecated for one release. Use table for the Table module."
11
+ GUIDE_TOOL = "loopable_guide"
12
+ # One intent schema for the base specs and the served tools/list, so the two cannot drift.
13
+ INTENT_SCHEMA = {"type": "string", "minLength": 1, "maxLength": 500,
14
+ "description": "State why you are making this call. Required for every write, including confirmation."}
15
 
16
 
17
  def canonical_name(name):
 
19
  return "table" if name == "data" else name
20
 
21
 
22
+ def _prefixed_action(name, arguments):
23
+ """Strip a repeated group prefix from an action, as in sheet_write_cells, when the rest is exact."""
24
+ group = groups().get(canonical_name(name))
25
+ action = arguments.get("action") if isinstance(arguments, dict) else None
26
+ if group is None or not isinstance(action, str) or action in group["actions"]:
27
+ return arguments
28
+ inner = arguments.get("arguments")
29
+ if action == group["name"] and isinstance(inner, dict) and inner.get("action") in group["actions"]:
30
+ # The group name sent as the action, with the real action inside arguments, unwraps one level.
31
+ rest = {key: value for key, value in inner.items() if key != "action"}
32
+ return {**arguments, "action": inner["action"], "arguments": rest}
33
+ for prefix in {name, canonical_name(name)}:
34
+ for joint in ("_", "."):
35
+ if action.startswith(prefix + joint) and action[len(prefix) + 1:] in group["actions"]:
36
+ return {**arguments, "action": action[len(prefix) + 1:]}
37
+ return arguments
38
+
39
+
40
  def canonical_call(name, arguments):
41
  """Adapt Table group aliases and dotted actions before normal admission."""
42
+ if name == GUIDE_TOOL + ".read":
43
+ return GUIDE_TOOL, arguments
44
  if name == "data":
45
+ return "table", _prefixed_action("data", arguments)
46
  if not isinstance(name, str):
47
  return name, arguments
48
  prefix, separator, action = name.partition(".")
49
+ if not separator:
50
+ return name, _prefixed_action(name, arguments)
51
+ if prefix not in {"table", "data"}:
52
  return name, arguments
53
  entry = groups().get("table", {}).get("actions", {}).get(action)
54
  if entry is None:
 
118
  group = groups().get(canonical_name(name)) if isinstance(name, str) else None
119
  if group is None:
120
  return None
121
+ action = arguments.get("action") if isinstance(arguments, dict) else None
122
+ if isinstance(arguments, dict) and (not isinstance(action, str) or action not in group["actions"]):
123
+ # A bare group name as the action gets one clause naming the mix-up before the action list.
124
+ named = group["name"] + " is the tool name, not an action. " if action == group["name"] else ""
125
+ raise sheets.SheetRefusal("tool_arguments_invalid", (
126
+ named + "Tool arguments must match the published input schema. Set action to one of the "
127
+ + group["name"] + " actions: " + ", ".join(group["actions"]) + ". Put that action's inputs inside "
128
+ "arguments, and intent, about and purpose beside action and arguments."))
129
  external_tools.validate_arguments(arguments, {
130
  "type": "object", "properties": {
131
  "action": {"type": "string", "enum": list(group["actions"])},
 
175
  return tuple(dict.fromkeys((*grants, *entry.get("grants", ()))))
176
 
177
 
178
+ def writes(group):
179
+ """Tell whether any action in a group writes."""
180
+ return any(not entry["read"] for entry in group["actions"].values())
181
+
182
+
183
  def tool_specs():
184
+ """Publish compact group summaries with call metadata and conservative effect hints."""
185
+ import wiki_log
186
  return [{
187
  "name": name, "description": group["guide"],
188
  "inputSchema": {"type": "object", "properties": {
189
  "action": {"type": "string"}, "arguments": {"type": "object"},
190
+ "intent": copy.deepcopy(INTENT_SCHEMA), "about": copy.deepcopy(external_tools.ABOUT_SCHEMA),
191
+ "purpose": copy.deepcopy(wiki_log.PURPOSE_SCHEMA),
192
+ }, "required": ["action", "intent"] if writes(group) else ["action"], "additionalProperties": False},
193
  "annotations": {
194
  "title": group["title"],
195
  "readOnlyHint": all(entry["read"] for entry in group["actions"].values()),
api/tool_groups/apps.py CHANGED
@@ -78,13 +78,29 @@ def list_apps(ctx, args):
78
  _refuse(exc)
79
 
80
 
 
 
 
 
81
  def catalog_pdf(ctx, args):
82
  session = _admit(ctx)
83
  import catalog_store
84
  import loopy_catalog_tools
 
85
 
86
  # The stored record admits its actual App source and credential scope.
87
- catalog_store._record(session, args["catalog_id"])
 
 
 
 
 
 
 
 
 
 
 
88
  return loopy_catalog_tools.catalog_pdf(session, args)
89
 
90
 
@@ -127,6 +143,7 @@ def apply_template(ctx, args):
127
  payload = copy.deepcopy(args)
128
  if payload["templateKind"] not in {row["kind"] for row in applications.template_contracts()}:
129
  raise applications.ApplicationError("Choose a template from apps.templates.")
 
130
  share = payload.pop("share", None)
131
  source = payload.get("sourceDatabase")
132
  databases = [source] if source else []
@@ -147,6 +164,28 @@ def apply_template(ctx, args):
147
  _refuse(exc)
148
 
149
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
150
  def _result(app):
151
  result = {"application": _catalog_link(app)}
152
  if app.get("shareApproval"):
 
78
  _refuse(exc)
79
 
80
 
81
+ CATALOG_ID_FIX = ("No stored catalog has this catalog_id. Use the catalog_id that apps.catalog_build returned, "
82
+ "after confirm_change committed that build. A preview saves no catalog until it is confirmed.")
83
+
84
+
85
  def catalog_pdf(ctx, args):
86
  session = _admit(ctx)
87
  import catalog_store
88
  import loopy_catalog_tools
89
+ from fastapi import HTTPException
90
 
91
  # The stored record admits its actual App source and credential scope.
92
+ try:
93
+ catalog_store._record(session, args["catalog_id"])
94
+ except HTTPException as exc:
95
+ code = ((exc.detail or {}).get("error") or {}).get("code") if isinstance(exc.detail, dict) else None
96
+ if code == "catalog_not_found":
97
+ from deps import err
98
+ raise err(404, "catalog_not_found", CATALOG_ID_FIX) from exc
99
+ raise
100
+ if (session.claims or {}).get("external") is True:
101
+ # An MCP call has a time budget. A longer render answers with an operation_id.
102
+ return loopy_catalog_tools.catalog_pdf_within_budget(
103
+ session, args, render=lambda caller, values: loopy_catalog_tools.catalog_pdf(caller, values))
104
  return loopy_catalog_tools.catalog_pdf(session, args)
105
 
106
 
 
143
  payload = copy.deepcopy(args)
144
  if payload["templateKind"] not in {row["kind"] for row in applications.template_contracts()}:
145
  raise applications.ApplicationError("Choose a template from apps.templates.")
146
+ _template_inputs(payload)
147
  share = payload.pop("share", None)
148
  source = payload.get("sourceDatabase")
149
  databases = [source] if source else []
 
164
  _refuse(exc)
165
 
166
 
167
+ def _template_inputs(payload):
168
+ """Name the missing template input and where it goes before the registry answers generically."""
169
+ contract = next(row for row in applications.template_contracts() if row["kind"] == payload["templateKind"])
170
+ required = [role["key"] for role in contract["fieldRoles"] if role["required"]]
171
+ example = json.dumps({role: "<field key>" for role in required})
172
+ if not isinstance(payload.get("sourceDatabase"), str) or not payload["sourceDatabase"].strip():
173
+ raise applications.ApplicationError(
174
+ "apply_template is missing sourceDatabase. Put sourceDatabase inside arguments: the database key "
175
+ "this App reads, as table.list_databases returns it.")
176
+ field_map = payload.get("fieldMap")
177
+ if not isinstance(field_map, dict):
178
+ raise applications.ApplicationError(
179
+ "apply_template is missing fieldMap. Put fieldMap inside arguments: an object that maps the required "
180
+ "roles " + ", ".join(required) + " to field keys of sourceDatabase, for example " + example
181
+ + ". apps.templates lists the optional roles.")
182
+ missing = [role for role in required if not str(field_map.get(role) or "").strip()]
183
+ if missing:
184
+ raise applications.ApplicationError(
185
+ "fieldMap is missing the required role " + ", ".join(missing) + ". Map each to a field key of "
186
+ "sourceDatabase inside arguments.fieldMap, for example " + example + ".")
187
+
188
+
189
  def _result(app):
190
  result = {"application": _catalog_link(app)}
191
  if app.get("shareApproval"):
api/tool_groups/data.py CHANGED
@@ -109,9 +109,23 @@ def _operation_status(ctx, args):
109
  return read_status(ctx.session, args)
110
 
111
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
112
  GROUP = {
113
  "name": "table", "title": "Table",
114
- "guide": "Table: list databases, read fields, group and page records, propose changes or report a limitation. Read loopable_guide(group='table') for actions and a grouping example.",
115
  "actions": {
116
  "operation_status": {
117
  "read": True, "destructive": False, "confirm": False,
@@ -120,6 +134,14 @@ GROUP = {
120
  }, "required": ["operation_id"], "additionalProperties": False},
121
  "handler": _operation_status,
122
  },
 
 
 
 
 
 
 
 
123
  "report_limitation": {
124
  "read": True, "destructive": False, "confirm": False,
125
  "schema": {"type": "object", "properties": {
 
109
  return read_status(ctx.session, args)
110
 
111
 
112
+ def _delivery_photos(ctx, args):
113
+ """List one Odoo delivery's photos when this credential and account may read that delivery."""
114
+ import odoo_attachments
115
+ from loopy_links import public_base
116
+ from routes_external import _assert_database_scope
117
+
118
+ def key_allowed(key):
119
+ _assert_database_scope(ctx.session, key)
120
+
121
+ photos = odoo_attachments.list_photos(ctx.session, args["picking_id"], key_allowed=key_allowed,
122
+ base=public_base() or "")
123
+ return {"picking_id": args["picking_id"], "photos": photos}
124
+
125
+
126
  GROUP = {
127
  "name": "table", "title": "Table",
128
+ "guide": "Table: list databases, read fields, group and page records, propose changes, list an Odoo delivery's photos with delivery_photos, or report a limitation. Read loopable_guide(group='table') for actions and a grouping example.",
129
  "actions": {
130
  "operation_status": {
131
  "read": True, "destructive": False, "confirm": False,
 
134
  }, "required": ["operation_id"], "additionalProperties": False},
135
  "handler": _operation_status,
136
  },
137
+ "delivery_photos": {
138
+ "read": True, "destructive": False, "confirm": False,
139
+ "schema": {"type": "object", "properties": {
140
+ "picking_id": {"type": "integer", "minimum": 1, "maximum": 2147483647,
141
+ "description": "The stock.picking id: odoo_id in Odoo shipments."},
142
+ }, "required": ["picking_id"], "additionalProperties": False},
143
+ "handler": _delivery_photos,
144
+ },
145
  "report_limitation": {
146
  "read": True, "destructive": False, "confirm": False,
147
  "schema": {"type": "object", "properties": {
api/tool_groups/sheet.py CHANGED
@@ -208,7 +208,7 @@ GROUP["guide"] += ' Under MCP rule 9, ask "Do you want me to build a Sheet workb
208
  _BATCH_GUIDE = (
209
  " A batch has 1 to 50 operations for one workbook. Use name and arguments for each operation. "
210
  "Use sheet_add_tab, sheet_write_cells, sheet_set_binding, sheet_set_styles or sheet_set_dimensions "
211
- "with their published arguments. One sheet_write_cells operation can write 200 cells. "
212
  "Range actions use name='range_object', with action, workbook_id, worksheet and an A1 range. "
213
  "Put values inside arguments for write_values, write_formulas, write_styles or number_format. "
214
  "For worksheet_object.add, put name inside arguments. For worksheet_object.geometry, "
 
208
  _BATCH_GUIDE = (
209
  " A batch has 1 to 50 operations for one workbook. Use name and arguments for each operation. "
210
  "Use sheet_add_tab, sheet_write_cells, sheet_set_binding, sheet_set_styles or sheet_set_dimensions "
211
+ "with their published arguments. A sheet_write_cells preview of 250 or more changes shows counts, ranges and a sample. confirm_change writes every cell. "
212
  "Range actions use name='range_object', with action, workbook_id, worksheet and an A1 range. "
213
  "Put values inside arguments for write_values, write_formulas, write_styles or number_format. "
214
  "For worksheet_object.add, put name inside arguments. For worksheet_object.geometry, "
api/tool_groups/views.py CHANGED
@@ -1,11 +1,95 @@
1
  """Saved View actions through the existing permission checks."""
2
  import copy
 
3
 
4
  from fastapi import HTTPException
5
  from core import external_tools
6
  from . import legacy_action
7
 
8
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9
  def _share_source(session, args):
10
  """Resolve source ownership on a detached canonical workspace before revealing the audience."""
11
  import routes_external
@@ -17,8 +101,9 @@ def _share_source(session, args):
17
  topic, source_owner, view = routes_shares._find_view_record(
18
  session, args["view_id"], _snapshot=snapshot)
19
  workspace = routes_shares._field_storage_keys(args["database"])[0]
 
20
  if not view or not source_owner or f"{topic}_table_workspace" != workspace:
21
- raise routes_shares.err(403, "not_owner", "You cannot administer this View's audience.")
22
  rec = shares.grants("view", args["view_id"], st=session.runtime)
23
  if rec["owner"]:
24
  allowed = shares.may_administer(
@@ -26,7 +111,7 @@ def _share_source(session, args):
26
  else:
27
  allowed = session.admin or source_owner == session.uname
28
  if not allowed:
29
- raise routes_shares.err(403, "not_owner", "You cannot administer this View's audience.")
30
  return snapshot, topic, source_owner, view, rec
31
 
32
 
@@ -36,8 +121,40 @@ def _receipt_access(ctx, args):
36
  return True
37
 
38
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
39
  def share(ctx, args):
40
  """Replace a named audience through the on-screen share writer and its permission ceiling."""
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
41
  import routes_external
42
  import routes_shares
43
  from core import shares
@@ -47,15 +164,13 @@ def share(ctx, args):
47
  snapshot, topic, source_owner, view, rec = _share_source(session, args)
48
  entries = copy.deepcopy(args["entries"])
49
  if any(row["user"].strip().lower() in {shares.EVERYONE, "everyone"} for row in entries):
50
- raise routes_shares.err(
51
- 400, "audience_not_allowed", "A person must choose sharing with everyone on screen.")
52
  if any(not row["user"].strip() for row in entries):
53
- raise routes_shares.err(400, "unknown_people", "Choose an active person in this workspace.")
54
  people = {row["username"].strip().lower(): row for row in routes_shares._people(session.tenant)}
55
  unknown = sorted({row["user"].strip().lower() for row in entries} - people.keys())
56
  if unknown:
57
- raise routes_shares.err(
58
- 400, "unknown_people", "These people have no active account in this workspace: " + ", ".join(unknown) + ".")
59
  keys = routes_shares._view_field_keys(view)
60
  definitions = routes_shares._view_field_definitions(
61
  session, f"{topic}_table_workspace", keys, _snapshot=snapshot)
@@ -70,18 +185,12 @@ def share(ctx, args):
70
  _notify=False)
71
  except HTTPException as exc:
72
  code = (exc.detail.get("error") or {}).get("code")
73
- messages = {
74
- "not_owner": "You cannot administer this View's audience.",
75
- "unknown_people": "Choose active people in this workspace.",
76
- "grants_changed": "This View's audience changed, so preview the share again.",
77
- "grant_exceeds_role": "You can grant Can view because Can edit exceeds your own access.",
78
- "grant_exceeds_audience": "A person must choose sharing with everyone on screen.",
79
- "revoke_not_yours": "You can remove only people you added to this View.",
80
- "field_not_shared": "A private field must be shared by its owner before sharing this View.",
81
- "view_share_failed": "This View's access could not be saved, so try again.",
82
- }
83
- if code in messages:
84
- raise routes_shares.err(exc.status_code, code, messages[code]) from exc
85
  raise
86
  name = str(view.get("name") or "A View")
87
  audience = [{"user": row["user"], "name": people[row["user"]].get("name") or row["user"],
 
1
  """Saved View actions through the existing permission checks."""
2
  import copy
3
+ import re
4
 
5
  from fastapi import HTTPException
6
  from core import external_tools
7
  from . import legacy_action
8
 
9
 
10
+ # One line per refusal: why it was refused, then the call that would succeed.
11
+ SHARE_REFUSALS = {
12
+ "not_owner": "You cannot change who sees this View, so ask its owner or an Administrator to share it.",
13
+ "audience_not_allowed": ("Sharing with everyone is a choice a person makes on screen, "
14
+ "so name each person in entries instead."),
15
+ "blank_user": "An entry has an empty user, so set user to the username of an active person in this workspace.",
16
+ "grants_changed": ("This View's audience changed after it was read, "
17
+ "so call views share again without expect and confirm the new preview."),
18
+ "grant_exceeds_role": ("Can edit is above your own access to this View, "
19
+ "so set role to view for each new editor or ask its owner to grant edit."),
20
+ "grant_exceeds_audience": ("Only this View's owner or an Administrator can share it with everyone, "
21
+ "so name each person in entries instead."),
22
+ "revoke_not_yours": ("You can remove only people you added to this View, "
23
+ "so keep everyone else in entries and share again."),
24
+ "field_not_shared": ("This View shows a field that is still private to its creator, "
25
+ "so hide that field in the View or ask its creator to share it, then share again."),
26
+ "unknown_people": ("A person in entries has no active account in this workspace, "
27
+ "so set user to a username, not a display name or email."),
28
+ "forbidden": "Your account cannot share this View, so ask its owner or an Administrator to share it.",
29
+ "view_share_failed": "This View's access could not be saved, so send the same share call again.",
30
+ }
31
+ _SHARE_FIELDS = ("database", "view_id", "entries", "expect")
32
+ _CALL_FIELDS = ("action", "arguments", "intent", "about", "purpose")
33
+
34
+
35
+ def _share_refusal(code, status=403):
36
+ """Raise the one-line refusal for a share code."""
37
+ import routes_shares
38
+ raise routes_shares.err(status, code, SHARE_REFUSALS[code])
39
+
40
+
41
+ def _listed(names):
42
+ names = list(names)
43
+ if len(names) < 2:
44
+ return "".join(names)
45
+ return ", ".join(names[:-1]) + " and " + names[-1]
46
+
47
+
48
+ def share_arguments_fix(call):
49
+ """Name the first wrong part of a views share call and the shape that succeeds."""
50
+ shape = "each entry is user (a username) and role (view or edit)"
51
+ if not isinstance(call, dict):
52
+ return "The call is not an object, so send action share with arguments database, view_id and entries."
53
+ stray = [str(key) for key in call if key not in _CALL_FIELDS]
54
+ if stray:
55
+ return (_listed(stray) + (" sit" if len(stray) > 1 else " sits") + " beside action, so move "
56
+ + ("them" if len(stray) > 1 else "it") + " inside arguments, which holds database, view_id, entries and optional expect.")
57
+ args = call.get("arguments")
58
+ if not isinstance(args, dict):
59
+ return "arguments is missing or not an object, so send arguments with database, view_id and entries."
60
+ unknown = [key for key in args if key not in _SHARE_FIELDS]
61
+ if unknown:
62
+ return (_listed(map(str, unknown)) + (" are not share arguments" if len(unknown) > 1 else " is not a share argument") + ", so send only database, view_id, "
63
+ "entries and optional expect, where " + shape + ".")
64
+ missing = [key for key in ("database", "view_id", "entries") if key not in args]
65
+ if missing:
66
+ return ("arguments has no " + " or ".join(missing) + ", so add " + ("them" if len(missing) > 1 else "it") + ": database and view_id are text, "
67
+ "and entries is a list where " + shape + ".")
68
+ for key in ("database", "view_id"):
69
+ if not isinstance(args[key], str) or not args[key].strip() or key == "view_id" and len(args[key]) > 120:
70
+ return key + " is not a usable id, so set it to the text id that the View list returns."
71
+ for key in ("entries", "expect"):
72
+ rows = args.get(key)
73
+ if key not in args:
74
+ continue
75
+ if not isinstance(rows, list):
76
+ return key + " is not a list, so send a list where " + shape + ", or [] to make the View private."
77
+ if len(rows) > 200:
78
+ return key + " names more than 200 people, so share with at most 200 people in one call."
79
+ for row in rows:
80
+ if not isinstance(row, dict):
81
+ return key + " holds a plain value, so send objects where " + shape + "."
82
+ extra = [name for name in row if name not in ("user", "role")]
83
+ if extra or "user" not in row or "role" not in row:
84
+ return (key + " has an entry with " + (_listed(map(str, extra)) or "a missing field")
85
+ + ", so give every entry exactly user (a username) and role (view or edit).")
86
+ if not isinstance(row["user"], str) or not 1 <= len(row["user"]) <= 120:
87
+ return key + " has a user that is not a username, so set user to a username of 1 to 120 characters."
88
+ if row["role"] not in ("view", "edit"):
89
+ return key + " has a role other than view or edit, so set role to view for Can view or edit for Can edit."
90
+ return "The share arguments do not match, so send database, view_id and entries, where " + shape + "."
91
+
92
+
93
  def _share_source(session, args):
94
  """Resolve source ownership on a detached canonical workspace before revealing the audience."""
95
  import routes_external
 
101
  topic, source_owner, view = routes_shares._find_view_record(
102
  session, args["view_id"], _snapshot=snapshot)
103
  workspace = routes_shares._field_storage_keys(args["database"])[0]
104
+ # A missing View and another person's View read the same, so the refusal reveals nothing.
105
  if not view or not source_owner or f"{topic}_table_workspace" != workspace:
106
+ _share_refusal("not_owner")
107
  rec = shares.grants("view", args["view_id"], st=session.runtime)
108
  if rec["owner"]:
109
  allowed = shares.may_administer(
 
111
  else:
112
  allowed = session.admin or source_owner == session.uname
113
  if not allowed:
114
+ _share_refusal("not_owner")
115
  return snapshot, topic, source_owner, view, rec
116
 
117
 
 
121
  return True
122
 
123
 
124
+ def _unknown_people_refusal(unknown, people):
125
+ """Name each unknown username and, for an exact display name match, the username to use."""
126
+ import routes_shares
127
+ names = {}
128
+ for username, row in people.items():
129
+ label = str(row.get("name") or "").strip().lower()
130
+ if label:
131
+ names.setdefault(label, []).append(username)
132
+ hints = [names[who][0] + " for " + str(people[names[who][0]].get("name"))
133
+ for who in unknown if len(names.get(who, ())) == 1]
134
+ fix = ("set user to " + ", ".join(hints)
135
+ + (", and to a username for the rest" if len(hints) < len(unknown) else "")
136
+ if hints else "set user to a username, not a display name or email")
137
+ raise routes_shares.err(400, "unknown_people", "No active person in this workspace has the username "
138
+ + ", ".join(unknown) + ", so " + fix + ".")
139
+
140
+
141
  def share(ctx, args):
142
  """Replace a named audience through the on-screen share writer and its permission ceiling."""
143
+ import routes_external
144
+ import routes_shares
145
+ try:
146
+ return _share(ctx, args)
147
+ except HTTPException as exc:
148
+ error = (exc.detail.get("error") or {}) if isinstance(exc.detail, dict) else {}
149
+ code = error.get("code")
150
+ # A 403 without a published code reaches the AI as forbidden. It names the share fix.
151
+ if code == "forbidden" or (exc.status_code == 403 and code not in SHARE_REFUSALS
152
+ and code not in routes_external.MCP_RESULT_CODES):
153
+ raise routes_shares.err(403, "forbidden", SHARE_REFUSALS["forbidden"]) from exc
154
+ raise
155
+
156
+
157
+ def _share(ctx, args):
158
  import routes_external
159
  import routes_shares
160
  from core import shares
 
164
  snapshot, topic, source_owner, view, rec = _share_source(session, args)
165
  entries = copy.deepcopy(args["entries"])
166
  if any(row["user"].strip().lower() in {shares.EVERYONE, "everyone"} for row in entries):
167
+ _share_refusal("audience_not_allowed", 400)
 
168
  if any(not row["user"].strip() for row in entries):
169
+ raise routes_shares.err(400, "unknown_people", SHARE_REFUSALS["blank_user"])
170
  people = {row["username"].strip().lower(): row for row in routes_shares._people(session.tenant)}
171
  unknown = sorted({row["user"].strip().lower() for row in entries} - people.keys())
172
  if unknown:
173
+ _unknown_people_refusal(unknown, people)
 
174
  keys = routes_shares._view_field_keys(view)
175
  definitions = routes_shares._view_field_definitions(
176
  session, f"{topic}_table_workspace", keys, _snapshot=snapshot)
 
185
  _notify=False)
186
  except HTTPException as exc:
187
  code = (exc.detail.get("error") or {}).get("code")
188
+ if code == "view_share_failed":
189
+ reference = re.search(r"\bVS-[0-9A-F]{8}\b", str((exc.detail.get("error") or {}).get("message") or ""))
190
+ raise routes_shares.err(exc.status_code, code, SHARE_REFUSALS[code] + (
191
+ " If it fails again, report reference " + reference[0] + "." if reference else "")) from exc
192
+ if code in SHARE_REFUSALS:
193
+ raise routes_shares.err(exc.status_code, code, SHARE_REFUSALS[code]) from exc
 
 
 
 
 
 
194
  raise
195
  name = str(view.get("name") or "A View")
196
  audience = [{"user": row["user"], "name": people[row["user"]].get("name") or row["user"],
platform/core/connector_spec.py CHANGED
The diff for this file is too large to render. See raw diff
 
platform/core/external_tools.py CHANGED
@@ -248,7 +248,7 @@ _APPLICATION = {
248
  "type": {"enum": ["chart", "route", "map", "code"]},
249
  "compatibleDatabases": {"type": "array", "items": _STRING},
250
  "sourceDatabase": {"type": "string", "description": "Source for a template Application only."},
251
- "templateKind": {"enum": ["route", "catalog"]},
252
  "fieldMap": {"type": "object", "additionalProperties": _STRING},
253
  "navPlacement": _object({"section": {"const": "app"},
254
  "order": {"type": "integer", "minimum": 0, "maximum": 999}},
 
248
  "type": {"enum": ["chart", "route", "map", "code"]},
249
  "compatibleDatabases": {"type": "array", "items": _STRING},
250
  "sourceDatabase": {"type": "string", "description": "Source for a template Application only."},
251
+ "templateKind": {"enum": ["route", "catalog", "competitor_watch"]},
252
  "fieldMap": {"type": "object", "additionalProperties": _STRING},
253
  "navPlacement": _object({"section": {"const": "app"},
254
  "order": {"type": "integer", "minimum": 0, "maximum": 999}},
platform/core/registry.py CHANGED
@@ -225,6 +225,11 @@ REGISTRY = [
225
  {'key': 'customer_card', 'label': 'Customer Card', 'brand': True, 'hq': False, 'validate': True,
226
  'validate_only': True, 'nav': False, 'source': 'Odoo',
227
  'note': 'Template App customer receivables independently tied to res.partner.credit.'},
 
 
 
 
 
228
  {'key': 'intelligence', 'label': 'Brain', 'brand': False, 'hq': True, 'validate': False,
229
  'nav': False,
230
  'note': 'Workspace Markdown files: playbooks, agent prompts, company facts, dictionary and '
 
225
  {'key': 'customer_card', 'label': 'Customer Card', 'brand': True, 'hq': False, 'validate': True,
226
  'validate_only': True, 'nav': False, 'source': 'Odoo',
227
  'note': 'Template App customer receivables independently tied to res.partner.credit.'},
228
+ {'key': 'amazon_profit', 'label': 'Amazon SKU profit', 'brand': False, 'hq': True,
229
+ 'validate': True, 'validate_only': True, 'nav': False, 'source': 'Amazon',
230
+ 'note': 'Per SKU Amazon net profit, margin and band in the module table '
231
+ 'ut_amazon_sku_profit (Odoo cost times units). The row keeps validate.py tying '
232
+ 'monthly net proceeds to settlements within 2%; the table is the surface.'},
233
  {'key': 'intelligence', 'label': 'Brain', 'brand': False, 'hq': True, 'validate': False,
234
  'nav': False,
235
  'note': 'Workspace Markdown files: playbooks, agent prompts, company facts, dictionary and '
platform/core/route_system.py CHANGED
@@ -553,64 +553,6 @@ def migrate_application_routes(st, applications, *, legacy_navigation=None):
553
  return _persist(st, mutate)
554
 
555
 
556
- def adopt_unscoped_routes(st, *, owner, application):
557
- """Move one owner's no-App Routes made after the R20 receipt into that owner's Routing App.
558
-
559
- A moved Route keeps its id, stops, number, createdAt and createdBy. Returns the moved ids.
560
- """
561
- owner = str(owner or "").strip().lower()
562
- application = _application(application)
563
-
564
- def when(value):
565
- try:
566
- stamp = _dt.datetime.fromisoformat(str(value or ""))
567
- except (TypeError, ValueError):
568
- return None
569
- return stamp if stamp.tzinfo else stamp.replace(tzinfo=_dt.timezone.utc)
570
-
571
- def signature(route):
572
- return (str(route.get("createdBy") or "").strip().lower(), _name(route.get("name")),
573
- tuple(_pid(stop.get("customerPid")) for stop in ordered_stops(route)))
574
-
575
- def plan(state):
576
- receipt = state.get(APPLICATION_MIGRATION)
577
- cutoff = when(receipt.get("at")) if isinstance(receipt, dict) else None
578
- if not owner or application is None or cutoff is None:
579
- return []
580
- taken = {signature(item) for item in state.get("routes") or [] if _in_application(item, application)}
581
- moving = []
582
- for index, item in enumerate(state.get("routes") or []):
583
- if not _in_application(item, None) or str(item.get("createdBy") or "").strip().lower() != owner:
584
- continue
585
- made = when(item.get("createdAt"))
586
- # A Route made before the receipt already has its R20 copy, and an identical one is a duplicate.
587
- if made is None or made <= cutoff or signature(item) in taken:
588
- continue
589
- taken.add(signature(item))
590
- moving.append(index)
591
- return moving
592
-
593
- # The read-only plan keeps the common request from writing the Route document.
594
- if not plan(_store(st)):
595
- return []
596
-
597
- def mutate(state):
598
- zones = (((state.get(APPLICATION_MIGRATION) or {}).get("applications") or {})
599
- .get(application) or {}).get("zones") or {}
600
- moved = []
601
- for index in plan(state):
602
- route = dict(state["routes"][index])
603
- route.update(application=application, shareKey=route_share_key(route.get("id")),
604
- zoneId=zones.get(f"{DEFAULT_ZONE_TABLE}:{route.get('zoneId')}"))
605
- state["routes"][index] = route
606
- moved.append(str(route.get("id")))
607
- if moved:
608
- _reconcile_inbox_state(state, _inbox_day(None, st=st))
609
- return state, moved
610
-
611
- return _persist(st, mutate) or []
612
-
613
-
614
  def route_share_key(route_id):
615
  """Stable generic-field bridge id for the existing share registry.
616
 
 
553
  return _persist(st, mutate)
554
 
555
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
556
  def route_share_key(route_id):
557
  """Stable generic-field bridge id for the existing share registry.
558
 
platform/core/view_templates.py CHANGED
@@ -36,7 +36,7 @@ their shape without a store.
36
  #: The topic a template is FOR. A coarse grouping label used to filter the picker's list; the
37
  #: real gate is `missing_columns` below (a table whose contract has the columns can take the
38
  #: template, whatever we called its source).
39
- SOURCES = ('odoo_customer', 'odoo_product', 'instagram', 'any')
40
 
41
  #: The workspace bucket a topic's views live in. `<key>_table_workspace` for user tables
42
  #: (`core/user_tables.py:211` builds the same string when it deletes them), and the two built-ins
@@ -236,6 +236,44 @@ TEMPLATES = [
236
  ),
237
  ],
238
  },
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
239
  ]
240
 
241
 
 
36
  #: The topic a template is FOR. A coarse grouping label used to filter the picker's list; the
37
  #: real gate is `missing_columns` below (a table whose contract has the columns can take the
38
  #: template, whatever we called its source).
39
+ SOURCES = ('odoo_customer', 'odoo_product', 'instagram', 'amazon', 'any')
40
 
41
  #: The workspace bucket a topic's views live in. `<key>_table_workspace` for user tables
42
  #: (`core/user_tables.py:211` builds the same string when it deletes them), and the two built-ins
 
236
  ),
237
  ],
238
  },
239
+ {
240
+ # SDLC 78 (R7, R12). `modules/amazon_profit.py` writes these onto its own table when it
241
+ # creates or adopts it and grants them to everyone who can open it, so nobody applies them.
242
+ 'key': 'amazon_sku_profit',
243
+ 'label': 'Amazon money losers',
244
+ 'desc': 'Amazon SKUs that lose money, run thin, or have no cost to measure.',
245
+ 'source': 'amazon',
246
+ 'views': [
247
+ _view(
248
+ 'tpl_amazon_sku_profit_losing', 'Losing',
249
+ 'SKUs whose net profit is below 0 in this period, worst first.',
250
+ ['sku', 'title', 'period', 'net_profit', 'margin', 'net_sales', 'net_proceeds',
251
+ 'cogs_total', 'units_sold', 'owner', 'status', 'due', 'status_set'],
252
+ sorts=[{'colId': 'net_profit', 'dir': 'asc'}],
253
+ filters=[{'colId': 'net_profit', 'op': 'lt', 'value': '0'}],
254
+ ),
255
+ _view(
256
+ 'tpl_amazon_sku_profit_thin', 'Thin',
257
+ 'SKUs that make money below the thin margin threshold, thinnest first.',
258
+ ['sku', 'title', 'period', 'margin', 'net_profit', 'net_sales', 'net_proceeds',
259
+ 'cogs_total', 'units_sold', 'owner', 'status', 'due', 'status_set'],
260
+ sorts=[{'colId': 'margin', 'dir': 'asc'}],
261
+ filters=[{'colId': 'band', 'op': 'eq', 'value': 'Thin'}],
262
+ ),
263
+ _view(
264
+ 'tpl_amazon_sku_profit_cogs_missing', 'COGS missing',
265
+ 'SKUs with no Odoo product linked or no Odoo cost, so profit stays blank. '
266
+ 'Confirm or reject the suggested product to measure them.',
267
+ ['sku', 'title', 'suggested_product', 'suggested_units', 'match_rule',
268
+ 'match_state', 'odoo_product', 'units_per_sku', 'cogs_per_unit', 'net_sales',
269
+ 'net_proceeds', 'units_sold', 'asin', 'period'],
270
+ sorts=[{'colId': 'net_sales', 'dir': 'desc'}],
271
+ filters=[{'colId': 'odoo_product', 'op': 'isEmpty'},
272
+ {'colId': 'cogs_per_unit', 'op': 'isEmpty'}],
273
+ conj='or',
274
+ ),
275
+ ],
276
+ },
277
  ]
278
 
279
 
platform/harness/amazon_client.py CHANGED
@@ -364,8 +364,10 @@ REPORT_TYPES = {
364
  # ⚠ Returns data only for Brand Registry brand owners (owner ruling R5). Carried as the
365
  # wave's one UNPROVEN ticket with its exit condition written in advance: returns >0 rows
366
  # for any registered brand, else demote to a declared-but-unsynced stub.
 
 
367
  "report": "GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT",
368
- "monthly": True, "period": "MONTH",
369
  "json_root": "dataByDepartmentAndSearchTerm",
370
  "validates_against": "report period totals vs our search-term rows",
371
  "role": "Brand Analytics",
@@ -2883,3 +2885,53 @@ def marketplace_participations(fields, timeout=_TIMEOUT):
2883
  got = _request("sellers/v1/marketplaceParticipations", token, region=region, timeout=timeout,
2884
  sandbox=is_sandbox(fields))
2885
  return got.get("payload") or []
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
364
  # ⚠ Returns data only for Brand Registry brand owners (owner ruling R5). Carried as the
365
  # wave's one UNPROVEN ticket with its exit condition written in advance: returns >0 rows
366
  # for any registered brand, else demote to a declared-but-unsynced stub.
367
+ # R18 (SDLC 78): one completed Sunday to Saturday WEEK per window. A first load takes the
368
+ # latest week only; older weeks keep watched terms only (amazon_store.write_week).
369
  "report": "GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT",
370
+ "weekly": True, "period": "WEEK",
371
  "json_root": "dataByDepartmentAndSearchTerm",
372
  "validates_against": "report period totals vs our search-term rows",
373
  "role": "Brand Analytics",
 
2885
  got = _request("sellers/v1/marketplaceParticipations", token, region=region, timeout=timeout,
2886
  sandbox=is_sandbox(fields))
2887
  return got.get("payload") or []
2888
+
2889
+
2890
+ def _sales_rank(item, marketplace):
2891
+ """`{"rank", "group"}` from one catalog item: the display group rank, else the best classification rank."""
2892
+ for entry in (item or {}).get("salesRanks") or ():
2893
+ if not isinstance(entry, dict) or entry.get("marketplaceId") not in (None, marketplace):
2894
+ continue
2895
+ display = [r for r in entry.get("displayGroupRanks") or () if isinstance((r or {}).get("rank"), int)]
2896
+ if display:
2897
+ return {"rank": display[0]["rank"], "group": display[0].get("title")}
2898
+ ranks = [r for r in entry.get("classificationRanks") or () if isinstance((r or {}).get("rank"), int)]
2899
+ if ranks:
2900
+ best = min(ranks, key=lambda r: r["rank"])
2901
+ return {"rank": best["rank"], "group": best.get("title")}
2902
+ return {"rank": None, "group": None}
2903
+
2904
+
2905
+ def catalog_sales_ranks(fields, asins, timeout=_TIMEOUT, *, sleep=time.sleep, now=time.monotonic):
2906
+ """Read sales ranks for any ASINs through `searchCatalogItems`, 20 per call. -> {asin: {"rank", "group"}}.
2907
+
2908
+ An ASIN Amazon does not return is absent from the result; the caller names it.
2909
+ """
2910
+ unique = sorted({str(a or "").strip() for a in asins or () if str(a or "").strip()})
2911
+ if not unique:
2912
+ return {}
2913
+ if any(not re.fullmatch(r"[A-Z0-9]{10}", a) for a in unique):
2914
+ raise AmazonError("A sales rank read needs 10 character ASINs")
2915
+ f = fields or {}
2916
+ marketplace = str(f.get("marketplace_id") or US_MARKETPLACE_ID)
2917
+ region = str(f.get("region") or DEFAULT_REGION)
2918
+ path = OPERATIONS["searchCatalogItems"]["path"]
2919
+ token, issued = access_token(f, timeout=timeout), now()
2920
+ out = {}
2921
+ for offset in range(0, len(unique), 20):
2922
+ _pace_entity("searchCatalogItems", ENTITY_INTERVALS["searchCatalogItems"], sleep=sleep, now=now)
2923
+ if now() - issued >= 3000:
2924
+ token, issued = access_token(f, timeout=timeout), now()
2925
+ batch = unique[offset:offset + 20]
2926
+ got = _request(path, token, region=region, sandbox=is_sandbox(f), timeout=timeout,
2927
+ marketplaceIds=marketplace, identifiersType="ASIN", identifiers=",".join(batch),
2928
+ includedData="summaries,salesRanks", pageSize=20,
2929
+ throttle_fix="read sales ranks again after the next weekly pull")
2930
+ items = got.get("items") if isinstance(got, dict) else None
2931
+ if not isinstance(items, list):
2932
+ raise AmazonError("searchCatalogItems returned no item list; retry after Amazon restores its response")
2933
+ for item in items:
2934
+ asin = str((item or {}).get("asin") or "")
2935
+ if asin in batch:
2936
+ out[asin] = _sales_rank(item, marketplace)
2937
+ return out
platform/harness/amazon_schema.py CHANGED
@@ -415,8 +415,10 @@ TABLE_SPECS = {
415
  ("child_asin", "listings", "asin1", "many_to_one"),
416
  ("sku", "listings", "seller_sku", "many_to_one"),
417
  )),
 
418
  "brand_analytics": _table_spec("brand_analytics", (
419
  "department_name", "search_term", "clicked_asin", "click_share_rank",
 
420
  )),
421
  "economics": _table_spec("economics", ("start_date", "msku", "marketplace_id"), (
422
  ("msku", "listings", "seller_sku", "many_to_one"),
 
415
  ("child_asin", "listings", "asin1", "many_to_one"),
416
  ("sku", "listings", "seller_sku", "many_to_one"),
417
  )),
418
+ # D-2675: the report period is part of the identity, so each weekly pull of a term keeps its own rows.
419
  "brand_analytics": _table_spec("brand_analytics", (
420
  "department_name", "search_term", "clicked_asin", "click_share_rank",
421
+ "_period_start", "_period_end",
422
  )),
423
  "economics": _table_spec("economics", ("start_date", "msku", "marketplace_id"), (
424
  ("msku", "listings", "seller_sku", "many_to_one"),
platform/harness/amazon_store.py CHANGED
@@ -88,6 +88,20 @@ LEGACY_SNAPSHOT_TABLES = ("listings", "inventory")
88
  #: Head -> lines: both tables read the same document; a second report buys no new rows.
89
  SHARED_REPORT_SIBLINGS = {"orders": "order_items"}
90
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
91
  # C1 is a tenant-store document, not an API dependency. verify_amazon gates reader parity.
92
  ENABLEMENT_KEY = "amazon_connector_enablement"
93
  MIRROR_PREFIX = "amazon_mirror/"
@@ -1260,8 +1274,11 @@ def replace_keys_for(table):
1260
  if c not in _ORIGIN_TYPES)
1261
 
1262
 
1263
- def replace_window(con, table, cols, types, rows, keys):
1264
- """Replace incoming key groups atomically, or report why only insertion is possible."""
 
 
 
1265
  missing = [c for c in keys if c not in cols]
1266
  if missing:
1267
  note = (f"{table}: window replacement unavailable; missing identity columns: "
@@ -1284,6 +1301,8 @@ def replace_window(con, table, cols, types, rows, keys):
1284
  count = _replace(con, temporary, cols, types, rows, source_table=table)
1285
  con.execute(f'DELETE FROM {target} WHERE EXISTS (SELECT 1 FROM {temporary} AS "k" WHERE {predicate})')
1286
  con.execute(f"INSERT INTO {target} ({columns}) SELECT {columns} FROM {temporary}")
 
 
1287
  con.execute("COMMIT")
1288
  except Exception:
1289
  con.execute("ROLLBACK")
@@ -1315,6 +1334,94 @@ def _month_windows(start, end):
1315
  return out
1316
 
1317
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1318
  def sqp_batches(asins, max_chars=200):
1319
  """Stable, lossless space-joined options within Amazon's character ceiling."""
1320
  if type(max_chars) is not int or max_chars < 1:
@@ -1926,6 +2033,9 @@ def first_load_plan(tables, start, end, *, recent_days=None, size=MAX_WINDOW_DAY
1926
  continue
1927
  if spec.get("snapshot"):
1928
  recent.append((table, None, None))
 
 
 
1929
  elif spec.get("monthly"):
1930
  months = list(reversed(_month_windows(start, end)))
1931
  if not months:
@@ -2753,6 +2863,11 @@ class _AmazonMirrorStore(_mirrors.MirrorStore):
2753
  def part_max_bytes(self):
2754
  return MIRROR_PART_MAX_BYTES
2755
 
 
 
 
 
 
2756
  def _valid_table(self, name):
2757
  # Preserve older Amazon tables even when they are no longer advertised.
2758
  return isinstance(name, str) and bool(re.fullmatch(r"amzn_[a-z0-9_]+", name))
@@ -3405,8 +3520,8 @@ def record_backfill_floor(con, table, when):
3405
 
3406
 
3407
  def _undocumented_month(con, table):
3408
- """Repair a legacy completion that never parsed a monthly document."""
3409
- if table == SQP_TABLE or not (_client().REPORT_TYPES.get(table) or {}).get("monthly"):
3410
  return False
3411
  if not read_watermark(con, table) or _read_state(con, entity_key("reconcile_" + table)):
3412
  return False
@@ -3656,8 +3771,8 @@ def needs_first_load(tenant_key, rt=None, *, completed_tables=None, repair_table
3656
  return (refusals.get(table, {}).get("state") in ("not_offered", "failed")
3657
  or read_watermark(con, table) is not None)
3658
  spec = _client().REPORT_TYPES.get(table) or {}
3659
- proven = not (spec.get("monthly") or spec.get("snapshot")) or table in documented_tables
3660
- if not proven and spec.get("monthly") and table != SQP_TABLE and read_watermark(con, table):
3661
  mirror = table_name(table)
3662
  if not _columns_of(con, mirror) or con.execute(f"SELECT COUNT(*) FROM {mirror}").fetchone()[0] == 0:
3663
  repairs.add(table)
@@ -3756,6 +3871,14 @@ def sync_window(table, mark, *, now, since=None, backfill_days=None):
3756
  start = start.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
3757
  end = end.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
3758
  cause += "; completed calendar months only"
 
 
 
 
 
 
 
 
3759
  if table == "settlements":
3760
  # The watermark filters issued reports by creation time; it never requests one.
3761
  rtype = spec.get("report_discover")
@@ -4673,16 +4796,46 @@ def sync(tenant_key="royal-imports", tables=None, since=None, log=print, rt=None
4673
  expected = [name for name in (TABLES if tables is None else tables) if name in TABLES]
4674
  if scheduled and not first_load and expected and "settlements" not in expected:
4675
  expected.append("settlements")
 
4676
  with _mirrors.sync_mirror("amazon", tenant_key, rt, report=report, log=log, expected_tables=expected):
4677
  report.update(_sync_candidate(tenant_key, **options))
4678
  _refuse_unreconciled(tenant_key, rt, report, log)
 
 
4679
  return report
4680
 
4681
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4682
  def _refuse_unreconciled(tenant_key, rt, report, log):
4683
  """Standing rule 8: a table synced in this pass whose reconciliation refuses keeps its previous rows."""
4684
- synced = [table for table, row in (report.get("tables") or {}).items()
4685
- if isinstance(row, dict) and row.get("state", "done") == "done" and "rows" in row]
4686
  if not synced or report.get("state") in {"partial", "failed", "done"}:
4687
  return
4688
  try:
@@ -4864,8 +5017,11 @@ def _sync_candidate(tenant_key="royal-imports", tables=None, since=None, log=pri
4864
  "resync of each snapshot table replaces its earlier copies.")
4865
 
4866
  def write_window(table, cols, types, rows):
4867
- count, note = replace_window(con, table_name(table), cols, types, rows,
4868
- replace_keys_for(table))
 
 
 
4869
  if note and table not in noted:
4870
  noted.add(table)
4871
  report["problems"].append(note)
@@ -5165,9 +5321,18 @@ def _sync_candidate(tenant_key="royal-imports", tables=None, since=None, log=pri
5165
  record_backfill_floor(con, table, w0)
5166
  floors[table] = w0
5167
  elif table != "settlements":
 
5168
  windows = (([(task_start, task_end)] if task_end is not None else []) if first_load
5169
- else _month_windows(plan["start"], plan["end"]) if cx.REPORT_TYPES[table].get("monthly")
5170
  else _windows(plan["start"], plan["end"]))
 
 
 
 
 
 
 
 
5171
  for w0, w1 in (() if table == "settlements" else windows):
5172
  # W59-T43 / C2 has no amazon.access kind. Record each credential-backed
5173
  # vendor attempt as a sync ACCESS phase, distinct from the completion event.
@@ -5176,7 +5341,7 @@ def _sync_candidate(tenant_key="royal-imports", tables=None, since=None, log=pri
5176
  probe = _DocumentProbe(table, rtype)
5177
  with _report_resume(
5178
  con, table, rtype, start=_iso(w0),
5179
- end=_iso(w1 - timedelta(seconds=1)) if cx.REPORT_TYPES[table].get("monthly") else _iso(w1), max_wait=max_wait,
5180
  log=lambda message: log(f"{table}: {message}"),
5181
  **({"options": {**REPORT_OPTIONS.get(table, {}), "reportPeriod": cx.REPORT_TYPES[table]["period"]}}
5182
  if cx.REPORT_TYPES[table].get("period") else
@@ -5219,11 +5384,14 @@ def _sync_candidate(tenant_key="royal-imports", tables=None, since=None, log=pri
5219
  cols, rows = parse_flat_file(
5220
  text, document_id=meta.get("reportDocumentId"), report_type=rtype)
5221
  declared = {}
 
 
5222
  if not cols:
5223
  if first_load:
5224
- # Even an empty recent window clears old rows exactly once.
 
5225
  for empty_table in (table, sibling):
5226
- if empty_table and floors[empty_table] is None:
5227
  if con.execute("SELECT 1 FROM information_schema.tables WHERE table_name=?",
5228
  [table_name(empty_table)]).fetchone():
5229
  con.execute(f"DELETE FROM {table_name(empty_table)} WHERE 1=1")
@@ -5252,12 +5420,13 @@ def _sync_candidate(tenant_key="royal-imports", tables=None, since=None, log=pri
5252
  types = _ensure(con, mirror, cols, rows, declared=declared,
5253
  preserve_rows=True) if cols else {}
5254
  # Explicit windows and first loads replace the mirror; incremental passes keep history.
5255
- if not cleared and not plan["incremental"]:
 
5256
  con.execute(f"DELETE FROM {mirror} WHERE 1=1")
5257
  cleared = True
5258
  if cols:
5259
  written += write_window(table, cols, types, rows)
5260
- if cx.REPORT_TYPES[table].get("monthly"):
5261
  _record_reconciliation(con, table, {"start": _iso(w0), "end": _iso(w1),
5262
  "count": len(rows)})
5263
  probe.finish(len(rows) if cols else 0)
@@ -8039,6 +8208,7 @@ def _bounded_document_selftest(rows=24_000):
8039
  try:
8040
  cols, parsed = parse_json_report(document, "dataByDepartmentAndSearchTerm",
8041
  document_id="selftest-document", report_type="selftest")
 
8042
  cols = merge_columns([c for c, _t in amazon_schema.columns_for("brand_analytics")], cols)
8043
  types = _ensure(con, table, cols, parsed, declared=dict(amazon_schema.columns_for("brand_analytics")))
8044
  first, _note = replace_window(con, table, cols, types, parsed, replace_keys_for("brand_analytics"))
 
88
  #: Head -> lines: both tables read the same document; a second report buys no new rows.
89
  SHARED_REPORT_SIBLINGS = {"orders": "order_items"}
90
 
91
+ #: Contract C2: called as `fn(tenant, synced_tables)` after a pass publishes. Each import is lazy and a
92
+ #: failure is one log line, never a failed sync.
93
+ AFTER_SYNC = ("modules.amazon_profit:on_amazon_sync", "modules.competitor_watch:on_amazon_sync")
94
+
95
+ #: R18: `fn(tenant) -> iterable of str`. Older brand analytics weeks keep these search terms only.
96
+ #: A missing module is an empty set; a reader that raises prunes nothing that pass.
97
+ WATCHED_TERMS = "modules.competitor_watch:watched_terms"
98
+
99
+ #: Standing rule 1 copy for the brand analytics limit (o7-brand-analytics-week.md). It reaches a screen.
100
+ BRAND_ANALYTICS_LIMIT = (
101
+ "Brand analytics keeps the latest full week of search terms. Older weeks keep only your watched "
102
+ "search terms, because one week is about 9.6 million rows and 3.5 GB. "
103
+ "To keep a term's history, add it to the competitor watch.")
104
+
105
  # C1 is a tenant-store document, not an API dependency. verify_amazon gates reader parity.
106
  ENABLEMENT_KEY = "amazon_connector_enablement"
107
  MIRROR_PREFIX = "amazon_mirror/"
 
1274
  if c not in _ORIGIN_TYPES)
1275
 
1276
 
1277
+ def replace_window(con, table, cols, types, rows, keys, after=None):
1278
+ """Replace incoming key groups atomically, or report why only insertion is possible.
1279
+
1280
+ `after(con)` runs inside the same transaction, after the insert and before the commit.
1281
+ """
1282
  missing = [c for c in keys if c not in cols]
1283
  if missing:
1284
  note = (f"{table}: window replacement unavailable; missing identity columns: "
 
1301
  count = _replace(con, temporary, cols, types, rows, source_table=table)
1302
  con.execute(f'DELETE FROM {target} WHERE EXISTS (SELECT 1 FROM {temporary} AS "k" WHERE {predicate})')
1303
  con.execute(f"INSERT INTO {target} ({columns}) SELECT {columns} FROM {temporary}")
1304
+ if after is not None:
1305
+ after(con)
1306
  con.execute("COMMIT")
1307
  except Exception:
1308
  con.execute("ROLLBACK")
 
1334
  return out
1335
 
1336
 
1337
+ def _week_start(value):
1338
+ """The Sunday 00:00 UTC on or before `value`: Amazon's WEEK report runs Sunday to Saturday."""
1339
+ day = _utc(value).replace(hour=0, minute=0, second=0, microsecond=0)
1340
+ return day - timedelta(days=(day.weekday() + 1) % 7)
1341
+
1342
+
1343
+ def _week_windows(start, end):
1344
+ """Completed Sunday to Saturday weeks only, as half-open UTC windows."""
1345
+ current, stop, out = _week_start(start), _week_start(end), []
1346
+ while current < stop:
1347
+ out.append((current, current + timedelta(days=7)))
1348
+ current += timedelta(days=7)
1349
+ return out
1350
+
1351
+
1352
+ def _periodic(spec):
1353
+ """A report that lands one completed calendar period, a month or a week, per window."""
1354
+ return bool((spec or {}).get("monthly") or (spec or {}).get("weekly"))
1355
+
1356
+
1357
+ def _period_windows(spec, start, end):
1358
+ return _week_windows(start, end) if spec.get("weekly") else _month_windows(start, end)
1359
+
1360
+
1361
+ def stamp_week(cols, rows, w0, w1):
1362
+ """Stamp a window's report period on every row, for a table whose identity names the period."""
1363
+ period = {"_period_start": _iso(w0), "_period_end": _iso(w1)}
1364
+ return [*cols, *(c for c in period if c not in cols)], _stamp_rows(rows, period)
1365
+
1366
+
1367
+ def watched_terms(tenant_key):
1368
+ """R18's watched set -> `(terms, None)`, or `(None, problem)` when the reader fails."""
1369
+ module_name, _, name = WATCHED_TERMS.partition(":")
1370
+ try:
1371
+ import importlib
1372
+ module = importlib.import_module(module_name)
1373
+ except ModuleNotFoundError as exc:
1374
+ if exc.name == module_name or module_name.startswith(f"{exc.name}."):
1375
+ return set(), None
1376
+ return None, _watched_problem(exc)
1377
+ except Exception as exc: # noqa: BLE001
1378
+ return None, _watched_problem(exc)
1379
+ try:
1380
+ return {str(term).strip().lower() for term in getattr(module, name)(tenant_key) or ()
1381
+ if str(term or "").strip()}, None
1382
+ except Exception as exc: # noqa: BLE001
1383
+ return None, _watched_problem(exc)
1384
+
1385
+
1386
+ def _watched_problem(exc):
1387
+ return (f"brand_analytics: watched search terms unreadable ({type(exc).__name__}); older weeks "
1388
+ "are kept in full this pass and pruned when the list reads again.")
1389
+
1390
+
1391
+ def _retain_weekly(con, mirror, watched):
1392
+ """R18: the newest week stays in full; every older period keeps watched search terms only."""
1393
+ quote = lambda name: '"' + str(name).replace('"', '""') + '"'
1394
+ terms = quote("amazon_watched_terms_" + uuid.uuid4().hex)
1395
+ target = quote(mirror)
1396
+ con.execute(f"CREATE TEMP TABLE {terms} (term VARCHAR)")
1397
+ try:
1398
+ if watched:
1399
+ con.executemany(f"INSERT INTO {terms} VALUES (?)", [[term] for term in sorted(watched)])
1400
+ row = con.execute(
1401
+ f'DELETE FROM {target} WHERE "_period_start" IS DISTINCT FROM '
1402
+ f'(SELECT MAX("_period_start") FROM {target}) '
1403
+ f"AND (search_term IS NULL OR lower(trim(search_term)) NOT IN (SELECT term FROM {terms}))").fetchone()
1404
+ return int(row[0]) if row else 0
1405
+ finally:
1406
+ con.execute(f"DROP TABLE IF EXISTS {terms}")
1407
+
1408
+
1409
+ def write_week(con, table, cols, types, rows, tenant_key, report, log=print):
1410
+ """Land one week by its period identity and apply R18's retention in the same transaction."""
1411
+ watched, problem = watched_terms(tenant_key)
1412
+ if problem:
1413
+ report.setdefault("problems", []).append(problem)
1414
+ log(problem)
1415
+ mirror = table_name(table)
1416
+ after = None if watched is None else (lambda c: _retain_weekly(c, mirror, watched))
1417
+ return replace_window(con, mirror, cols, types, rows, replace_keys_for(table), after=after)
1418
+
1419
+
1420
+ def _record_brand_analytics_limit(con):
1421
+ _record_state(con, entity_key("limit_brand_analytics"), "done",
1422
+ detail=json.dumps({"reason": BRAND_ANALYTICS_LIMIT}))
1423
+
1424
+
1425
  def sqp_batches(asins, max_chars=200):
1426
  """Stable, lossless space-joined options within Amazon's character ceiling."""
1427
  if type(max_chars) is not int or max_chars < 1:
 
2033
  continue
2034
  if spec.get("snapshot"):
2035
  recent.append((table, None, None))
2036
+ elif spec.get("weekly"):
2037
+ # R18: a first load takes the latest completed week only; no weekly history is owed.
2038
+ recent.extend((table, w0, w1) for w0, w1 in _week_windows(start, end)[-1:])
2039
  elif spec.get("monthly"):
2040
  months = list(reversed(_month_windows(start, end)))
2041
  if not months:
 
2863
  def part_max_bytes(self):
2864
  return MIRROR_PART_MAX_BYTES
2865
 
2866
+ def _install_snapshot(self, con, manifest, rows, paths):
2867
+ result = super()._install_snapshot(con, manifest, rows, paths)
2868
+ _note_published() # C2: AFTER_SYNC runs only for a pass that published.
2869
+ return result
2870
+
2871
  def _valid_table(self, name):
2872
  # Preserve older Amazon tables even when they are no longer advertised.
2873
  return isinstance(name, str) and bool(re.fullmatch(r"amzn_[a-z0-9_]+", name))
 
3520
 
3521
 
3522
  def _undocumented_month(con, table):
3523
+ """Repair a legacy completion that never parsed a monthly or weekly document."""
3524
+ if table == SQP_TABLE or not _periodic(_client().REPORT_TYPES.get(table)):
3525
  return False
3526
  if not read_watermark(con, table) or _read_state(con, entity_key("reconcile_" + table)):
3527
  return False
 
3771
  return (refusals.get(table, {}).get("state") in ("not_offered", "failed")
3772
  or read_watermark(con, table) is not None)
3773
  spec = _client().REPORT_TYPES.get(table) or {}
3774
+ proven = not (_periodic(spec) or spec.get("snapshot")) or table in documented_tables
3775
+ if not proven and _periodic(spec) and table != SQP_TABLE and read_watermark(con, table):
3776
  mirror = table_name(table)
3777
  if not _columns_of(con, mirror) or con.execute(f"SELECT COUNT(*) FROM {mirror}").fetchone()[0] == 0:
3778
  repairs.add(table)
 
3871
  start = start.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
3872
  end = end.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
3873
  cause += "; completed calendar months only"
3874
+ if spec.get("weekly"):
3875
+ end = _week_start(end)
3876
+ if incremental or since is not None:
3877
+ start = _week_start(start)
3878
+ cause += "; completed Sunday to Saturday weeks only"
3879
+ else:
3880
+ start = end - timedelta(days=7)
3881
+ cause = "first load: the latest completed Sunday to Saturday week only (R18)"
3882
  if table == "settlements":
3883
  # The watermark filters issued reports by creation time; it never requests one.
3884
  rtype = spec.get("report_discover")
 
4796
  expected = [name for name in (TABLES if tables is None else tables) if name in TABLES]
4797
  if scheduled and not first_load and expected and "settlements" not in expected:
4798
  expected.append("settlements")
4799
+ _PUBLISHED.flag = False
4800
  with _mirrors.sync_mirror("amazon", tenant_key, rt, report=report, log=log, expected_tables=expected):
4801
  report.update(_sync_candidate(tenant_key, **options))
4802
  _refuse_unreconciled(tenant_key, rt, report, log)
4803
+ if getattr(_PUBLISHED, "flag", False):
4804
+ _after_sync(tenant_key, report, log)
4805
  return report
4806
 
4807
 
4808
+ #: Set when this thread's sync pass installs a published snapshot.
4809
+ _PUBLISHED = threading.local()
4810
+
4811
+
4812
+ def _note_published():
4813
+ _PUBLISHED.flag = True
4814
+
4815
+
4816
+ def _synced_tables(report):
4817
+ """The tables this pass landed: state `done` with a row count."""
4818
+ return [table for table, row in (report.get("tables") or {}).items()
4819
+ if isinstance(row, dict) and row.get("state", "done") == "done" and "rows" in row]
4820
+
4821
+
4822
+ def _after_sync(tenant_key, report, log):
4823
+ """Contract C2: each callback is imported lazily; any failure is one log line and changes nothing."""
4824
+ synced = tuple(_synced_tables(report))
4825
+ if not synced:
4826
+ return
4827
+ for target in AFTER_SYNC:
4828
+ try:
4829
+ import importlib
4830
+ module_name, _, name = target.partition(":")
4831
+ getattr(importlib.import_module(module_name), name)(tenant_key, synced)
4832
+ except Exception as exc: # noqa: BLE001
4833
+ log(f"Amazon after-sync callback {target} failed ({type(exc).__name__}); the sync result is unchanged.")
4834
+
4835
+
4836
  def _refuse_unreconciled(tenant_key, rt, report, log):
4837
  """Standing rule 8: a table synced in this pass whose reconciliation refuses keeps its previous rows."""
4838
+ synced = _synced_tables(report)
 
4839
  if not synced or report.get("state") in {"partial", "failed", "done"}:
4840
  return
4841
  try:
 
5017
  "resync of each snapshot table replaces its earlier copies.")
5018
 
5019
  def write_window(table, cols, types, rows):
5020
+ if cx.REPORT_TYPES[table].get("weekly"):
5021
+ count, note = write_week(con, table, cols, types, rows, tenant_key, report, log)
5022
+ else:
5023
+ count, note = replace_window(con, table_name(table), cols, types, rows,
5024
+ replace_keys_for(table))
5025
  if note and table not in noted:
5026
  noted.add(table)
5027
  report["problems"].append(note)
 
5321
  record_backfill_floor(con, table, w0)
5322
  floors[table] = w0
5323
  elif table != "settlements":
5324
+ period_spec = cx.REPORT_TYPES[table]
5325
  windows = (([(task_start, task_end)] if task_end is not None else []) if first_load
5326
+ else _period_windows(period_spec, plan["start"], plan["end"]) if _periodic(period_spec)
5327
  else _windows(plan["start"], plan["end"]))
5328
+ if period_spec.get("weekly"):
5329
+ _record_brand_analytics_limit(con)
5330
+ if not first_load and len(windows) > 1:
5331
+ # One week per pass, oldest first. The watermark stops at its end, so no week is asked twice.
5332
+ log(f"{table}: {len(windows) - 1} more completed weeks follow on later passes")
5333
+ windows = windows[:1]
5334
+ plan["end"] = windows[0][1]
5335
+ weekly = bool(table != "settlements" and cx.REPORT_TYPES[table].get("weekly"))
5336
  for w0, w1 in (() if table == "settlements" else windows):
5337
  # W59-T43 / C2 has no amazon.access kind. Record each credential-backed
5338
  # vendor attempt as a sync ACCESS phase, distinct from the completion event.
 
5341
  probe = _DocumentProbe(table, rtype)
5342
  with _report_resume(
5343
  con, table, rtype, start=_iso(w0),
5344
+ end=_iso(w1 - timedelta(seconds=1)) if _periodic(cx.REPORT_TYPES[table]) else _iso(w1), max_wait=max_wait,
5345
  log=lambda message: log(f"{table}: {message}"),
5346
  **({"options": {**REPORT_OPTIONS.get(table, {}), "reportPeriod": cx.REPORT_TYPES[table]["period"]}}
5347
  if cx.REPORT_TYPES[table].get("period") else
 
5384
  cols, rows = parse_flat_file(
5385
  text, document_id=meta.get("reportDocumentId"), report_type=rtype)
5386
  declared = {}
5387
+ if cols and (weekly or "_period_start" in replace_keys_for(table)):
5388
+ cols, rows = stamp_week(cols, rows, w0, w1)
5389
  if not cols:
5390
  if first_load:
5391
+ # Even an empty recent window clears old rows exactly once. A weekly
5392
+ # table never clears: R18's retention keeps watched history.
5393
  for empty_table in (table, sibling):
5394
+ if empty_table and floors[empty_table] is None and not weekly:
5395
  if con.execute("SELECT 1 FROM information_schema.tables WHERE table_name=?",
5396
  [table_name(empty_table)]).fetchone():
5397
  con.execute(f"DELETE FROM {table_name(empty_table)} WHERE 1=1")
 
5420
  types = _ensure(con, mirror, cols, rows, declared=declared,
5421
  preserve_rows=True) if cols else {}
5422
  # Explicit windows and first loads replace the mirror; incremental passes keep history.
5423
+ # A weekly table replaces by its period identity instead (D-2675).
5424
+ if not cleared and not plan["incremental"] and not weekly:
5425
  con.execute(f"DELETE FROM {mirror} WHERE 1=1")
5426
  cleared = True
5427
  if cols:
5428
  written += write_window(table, cols, types, rows)
5429
+ if _periodic(cx.REPORT_TYPES[table]):
5430
  _record_reconciliation(con, table, {"start": _iso(w0), "end": _iso(w1),
5431
  "count": len(rows)})
5432
  probe.finish(len(rows) if cols else 0)
 
8208
  try:
8209
  cols, parsed = parse_json_report(document, "dataByDepartmentAndSearchTerm",
8210
  document_id="selftest-document", report_type="selftest")
8211
+ cols, parsed = stamp_week(cols, parsed, _utc("2026-10-11T00:00:00Z"), _utc("2026-10-18T00:00:00Z"))
8212
  cols = merge_columns([c for c, _t in amazon_schema.columns_for("brand_analytics")], cols)
8213
  types = _ensure(con, table, cols, parsed, declared=dict(amazon_schema.columns_for("brand_analytics")))
8214
  first, _note = replace_window(con, table, cols, types, parsed, replace_keys_for("brand_analytics"))
platform/harness/semantic.py CHANGED
@@ -1120,6 +1120,8 @@ _VALIDATORS.update({key: _v_customer_rollup(key) for key in (
1120
  'customer_oldest_due', 'customer_invoiced_all_time', 'customer_days_since_invoice')})
1121
  from modules.finance_spine import FINANCE_VALIDATORS
1122
  _VALIDATORS.update(FINANCE_VALIDATORS)
 
 
1123
  _VALIDATORS.update({'standard_' + key: _v_standard_metric(key)
1124
  for key in ('booked', 'shipped', 'collected', 'margin')})
1125
  _VALIDATORS['invoiced_sales'] = _v_standard_metric('invoiced_sales')
 
1120
  'customer_oldest_due', 'customer_invoiced_all_time', 'customer_days_since_invoice')})
1121
  from modules.finance_spine import FINANCE_VALIDATORS
1122
  _VALIDATORS.update(FINANCE_VALIDATORS)
1123
+ from modules.amazon_profit import PROFIT_VALIDATORS
1124
+ _VALIDATORS.update(PROFIT_VALIDATORS)
1125
  _VALIDATORS.update({'standard_' + key: _v_standard_metric(key)
1126
  for key in ('booked', 'shipped', 'collected', 'margin')})
1127
  _VALIDATORS['invoiced_sales'] = _v_standard_metric('invoiced_sales')
platform/model/metrics/amazon_profit.yml ADDED
@@ -0,0 +1,56 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Amazon SKU profit. The module (platform/modules/amazon_profit.py) owns the per SKU table
2
+ # ut_amazon_sku_profit and registers the amazon_sku_net_profit validator when it loads.
3
+ # harness/semantic.py imports that validator, so the topic declares its measure at model load.
4
+ topics:
5
+ - key: amazon_sku_profit
6
+ label: "Amazon SKU profit"
7
+ entity: amazon.sku_profit
8
+ grain: "one row per Amazon seller SKU for the chosen period"
9
+ semantic:
10
+ approved: []
11
+ date_field: ""
12
+ date_col_note: "amzn_economics.start_date, one economics row per SKU per day"
13
+ scope: "Every Amazon seller SKU in the economics mirror for one period: the last 30 days, the last 90 days or a calendar month. Net proceeds are net sales minus Amazon fees minus sponsored ads. COGS is the linked Odoo product cost times units per SKU times units sold. A SKU without an Odoo link has a blank net profit, never zero."
14
+ measure: {key: amazon_sku_net_profit, validate: amazon_sku_net_profit}
15
+ fields:
16
+ - key: sku
17
+ label: "SKU"
18
+ type: text
19
+ kind: data
20
+ - key: net_proceeds
21
+ label: "Net proceeds"
22
+ type: currency
23
+ kind: data
24
+ - key: net_profit
25
+ label: "Net profit"
26
+ type: currency
27
+ kind: data
28
+ - key: margin
29
+ label: "Margin"
30
+ type: pct
31
+ kind: data
32
+ - key: band
33
+ label: "Band"
34
+ type: text
35
+ kind: data
36
+ topic: amazon_sku_profit
37
+ metrics:
38
+ - key: amazon_sku_net_profit
39
+ label: Amazon SKU net profit
40
+ agg: sum
41
+ field: net_profit
42
+ format: usd
43
+ empty: blank
44
+ description: Net proceeds minus Odoo COGS for each Amazon SKU over the chosen period.
45
+ ai_context: >
46
+ Amazon SKU net profit is net proceeds minus COGS for one seller SKU over the chosen period.
47
+ Net proceeds are net sales minus Amazon fees minus sponsored ads, from Amazon economics.
48
+ COGS is the linked Odoo product cost times units per SKU times net units sold.
49
+ A SKU with no Odoo link has a blank net profit and belongs in the COGS missing view; never treat it as zero.
50
+ Losing means net profit below zero. Thin means margin below the thin threshold, 10% of net sales by default.
51
+ Read the figures from the Amazon SKU profit database.
52
+ validate:
53
+ method: amazon_sku_net_profit
54
+ independent: >
55
+ Amazon's reported netProceeds total for the same window; the module validate() also ties
56
+ each month's net proceeds to settlements within 2%, excluding loan repayment and withheld tax.
platform/modules/amazon_profit.py ADDED
@@ -0,0 +1,1424 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Amazon SKU profit: one row per Amazon SKU with Odoo cost, net profit, margin and band.
2
+
3
+ Net proceeds = net sales minus fees minus sponsored ads, from the `amzn_economics` mirror.
4
+ COGS = Odoo `standard_price` of the linked product times units per SKU times units sold.
5
+ The module owns its table (`ut_amazon_sku_profit`). It is not a connector table, so people
6
+ edit the owned columns (Odoo product, units per SKU, owner, status, due date). A refresh
7
+ rewrites only the computed columns, keyed by SKU, so owned cells belong to the SKU and
8
+ survive every period switch.
9
+
10
+ `validate()` ties a month's net proceeds to Amazon settlements within 2%, excluding loan
11
+ repayments and withheld tax, and proves a negative control that drops fees goes red.
12
+ A refresh runs it for the last complete month and writes no figures when it fails.
13
+
14
+ Owned items (R10, R31): a refresh opens one item on a Losing or Thin SKU with no status, for the
15
+ default owner, due in 14 days. It reopens a failed fix 30 days after the status was set. The
16
+ `status_set` column records the status and the date a refresh first saw it, because the
17
+ activity log is delivered async and pruned, so a refresh cannot read a status date from it.
18
+ """
19
+ from __future__ import annotations
20
+
21
+ import atexit
22
+ import datetime as dt
23
+ import hashlib
24
+ import json
25
+ import math
26
+ import re
27
+ import shutil
28
+ import tempfile
29
+ import threading
30
+ from pathlib import Path
31
+
32
+ TABLE_KEY = "ut_amazon_sku_profit"
33
+ TABLE_LABEL = "Amazon SKU profit"
34
+ SETTINGS_KEY = "amazon_profit_settings"
35
+ VIA = "amazon_profit"
36
+ WRITER = "automation"
37
+ TENANT_ZERO = "royal-imports"
38
+
39
+ PERIOD_DEFAULT = "90d"
40
+ PERIOD_DAYS = {"30d": 30, "90d": 90}
41
+ THIN_DEFAULT = 0.10
42
+ STATUSES = ("Open", "Repriced", "Ads cut", "Delisted", "Keep", "COGS wrong")
43
+ #: A fix that reopens when the SKU still loses money or runs thin 30 days on. Keep never reopens.
44
+ FIX_STATUSES = ("Repriced", "Ads cut", "Delisted", "COGS wrong")
45
+ BANDS = ("Losing", "Thin")
46
+ NEEDS_REVIEW, CONFIRMED, REJECTED = "Needs review", "Confirmed", "Rejected"
47
+ MATCH_STATES = (NEEDS_REVIEW, CONFIRMED, REJECTED)
48
+ DUE_DAYS = 14
49
+ REOPEN_DAYS = 30
50
+ TEMPLATE_KEY = "amazon_sku_profit"
51
+ PICKER_MONTHS = 12
52
+ SETTLEMENT_TOLERANCE = 0.02
53
+
54
+ ECONOMICS = "amzn_economics"
55
+ SETTLEMENTS = "amzn_settlements"
56
+ LISTINGS = "amzn_listings"
57
+ LOAN_REPAYMENT = "Automated Loan Repayment"
58
+ WITHHELD_TAX = "ItemWithheldTax"
59
+ _ECONOMICS_REQUIRED = ("msku", "start_date", "sales_net_product_sales_amount",
60
+ "sales_net_units_sold", "fees_total_amount")
61
+ _SETTLEMENT_REQUIRED = ("amount", "posted_date", "transaction_type", "amount_type")
62
+ _ADS_TOTAL = re.compile(r"ads_[a-z0-9_]+_amount")
63
+ _MONTH = re.compile(r"(\d{4})-(\d{2})")
64
+ _LOCK = threading.Lock()
65
+
66
+
67
+ class SourceUnavailable(RuntimeError):
68
+ """The Amazon mirror lacks a table or column this module reads."""
69
+
70
+
71
+ class TableRefused(RuntimeError):
72
+ """The store refused the module table; the message names the cause and the fix."""
73
+
74
+
75
+ def _field(key, label, ftype, description, *, computed, **extra):
76
+ out = {"key": key, "label": label, "type": ftype, "origin": "loopable",
77
+ "valueAuthority": "computed" if computed else "user-entered",
78
+ "scope": "tenant", "description": description}
79
+ out.update(extra)
80
+ return out
81
+
82
+
83
+ #: Computed columns: a refresh owns them and the pre-set lock keeps people out of them.
84
+ COMPUTED_FIELDS = (
85
+ _field("sku", "SKU", "text", "Amazon seller SKU.", computed=True),
86
+ _field("asin", "ASIN", "text", "Amazon product id.", computed=True),
87
+ _field("title", "Title", "text", "Listing title.", computed=True),
88
+ _field("period", "Period", "text", "Dates these figures cover.", computed=True),
89
+ _field("units_sold", "Units sold", "int", "Net units sold in the period.", computed=True),
90
+ _field("net_sales", "Net sales", "currency", "Sales after refunds.", computed=True),
91
+ _field("fees", "Fees", "currency", "Amazon fees.", computed=True),
92
+ _field("sponsored_ads", "Sponsored ads", "currency", "Ad spend.", computed=True),
93
+ _field("net_proceeds", "Net proceeds", "currency", "Net sales minus fees and ads.",
94
+ computed=True),
95
+ _field("cogs_per_unit", "COGS per unit", "currency", "Odoo cost times units per SKU.",
96
+ computed=True),
97
+ _field("cogs_total", "COGS total", "currency", "COGS per unit times units sold.",
98
+ computed=True),
99
+ _field("net_profit", "Net profit", "currency", "Net proceeds minus COGS.", computed=True),
100
+ _field("margin", "Margin", "pct", "Net profit over net sales.", computed=True),
101
+ _field("band", "Band", "select", "Losing or thin.", computed=True, options=list(BANDS)),
102
+ )
103
+ #: Owned columns: people edit them and a refresh never writes them.
104
+ OWNED_FIELDS = (
105
+ _field("odoo_product", "Odoo product", "text", "Odoo internal reference.", computed=False),
106
+ _field("units_per_sku", "Units per SKU", "int", "Odoo units in one Amazon unit.",
107
+ computed=False, format={"decimals": 4}),
108
+ _field("owner", "Owner", "user", "Who acts on this SKU.", computed=False),
109
+ _field("status", "Status", "select", "Where the action stands.", computed=False,
110
+ options=list(STATUSES)),
111
+ _field("due", "Due date", "date", "When the action is due.", computed=False),
112
+ _field("match_state", "Match state", "select", "Confirm or reject the suggested product.",
113
+ computed=False, options=list(MATCH_STATES)),
114
+ )
115
+ #: Tracking columns: a refresh writes them, people read them, and a period switch keeps them.
116
+ TRACK_FIELDS = (
117
+ _field("status_set", "Status set", "text", "The status and the day a refresh first saw it.",
118
+ computed=True),
119
+ _field("suggested_product", "Suggested product", "text", "Odoo product the matcher suggests.",
120
+ computed=True),
121
+ _field("suggested_units", "Suggested units", "int", "Odoo units in one Amazon unit.",
122
+ computed=True, format={"decimals": 4}),
123
+ _field("match_rule", "Match rule", "text", "How the matcher found the product.", computed=True),
124
+ _field("match_rejected", "Rejected matches", "text", "Odoo codes a person rejected.",
125
+ computed=True),
126
+ )
127
+ COMPUTED_KEYS = tuple(f["key"] for f in COMPUTED_FIELDS)
128
+ OWNED_KEYS = tuple(f["key"] for f in OWNED_FIELDS)
129
+ TRACK_KEYS = tuple(f["key"] for f in TRACK_FIELDS)
130
+ ALL_KEYS = COMPUTED_KEYS + OWNED_KEYS + TRACK_KEYS
131
+ SUGGESTION_KEYS = ("suggested_product", "suggested_units", "match_rule")
132
+ #: Period figures a failed validate() blanks. COGS per unit is Odoo cost, not a period figure.
133
+ _UNVERIFIED_KEYS = ("units_sold", "net_sales", "fees", "sponsored_ads", "net_proceeds",
134
+ "cogs_total", "net_profit", "margin", "band")
135
+ _PERIOD_KEYS = tuple(k for k in COMPUTED_KEYS if k not in ("sku", "asin", "title"))
136
+
137
+
138
+ # ---------------------------------------------------------------- period and threshold
139
+
140
+ def _today():
141
+ return dt.datetime.now(dt.timezone.utc).date()
142
+
143
+
144
+ def period_bounds(period=None, today=None):
145
+ """`{key, start, end, label}` for 30d, 90d or YYYY-MM; ISO dates, end inclusive."""
146
+ key = str(period or PERIOD_DEFAULT).strip().lower()
147
+ today = today or _today()
148
+ if key in PERIOD_DAYS:
149
+ end = today - dt.timedelta(days=1)
150
+ start = end - dt.timedelta(days=PERIOD_DAYS[key] - 1)
151
+ label = f"Last {PERIOD_DAYS[key]} days"
152
+ else:
153
+ match = _MONTH.fullmatch(key)
154
+ if not match or not 1 <= int(match.group(2)) <= 12:
155
+ raise ValueError("Choose 30 days, 90 days or a calendar month.")
156
+ start = dt.date(int(match.group(1)), int(match.group(2)), 1)
157
+ if start > today:
158
+ raise ValueError("Choose a month that has started.")
159
+ following = (start.replace(day=28) + dt.timedelta(days=4)).replace(day=1)
160
+ end = following - dt.timedelta(days=1)
161
+ label = start.strftime("%B %Y")
162
+ return {"key": key, "start": start.isoformat(), "end": end.isoformat(),
163
+ "label": f"{label} ({start.isoformat()} to {end.isoformat()})"}
164
+
165
+
166
+ def period_choices(today=None, months=PICKER_MONTHS):
167
+ """`[{key, label}]`: 30 days, 90 days, then the last `months` complete calendar months."""
168
+ out = [{"key": key, "label": f"Last {days} days"} for key, days in PERIOD_DAYS.items()]
169
+ first = (today or _today()).replace(day=1)
170
+ for _ in range(months):
171
+ first = (first - dt.timedelta(days=1)).replace(day=1)
172
+ out.append({"key": first.strftime("%Y-%m"), "label": first.strftime("%B %Y")})
173
+ return out
174
+
175
+
176
+ def clean_thin(value):
177
+ """The Thin threshold as a fraction of net sales, 0 to under 1."""
178
+ if value is None or value == "":
179
+ return THIN_DEFAULT
180
+ try:
181
+ number = float(str(value).strip().rstrip("%"))
182
+ except (TypeError, ValueError):
183
+ raise ValueError("Enter the thin margin as a number.") from None
184
+ if str(value).strip().endswith("%"):
185
+ number /= 100.0
186
+ if not math.isfinite(number) or not 0 <= number < 1:
187
+ raise ValueError("Enter the thin margin between 0% and 99%.")
188
+ return number
189
+
190
+
191
+ def last_complete_month(today=None):
192
+ first = (today or _today()).replace(day=1)
193
+ return (first - dt.timedelta(days=1)).strftime("%Y-%m")
194
+
195
+
196
+ def verification_month(period=None, today=None):
197
+ """The month a refresh ties to settlements: a picked month once it has ended, else the last one."""
198
+ key = str(period or PERIOD_DEFAULT).strip().lower()
199
+ last = last_complete_month(today)
200
+ return key if _MONTH.fullmatch(key) and key <= last else last
201
+
202
+
203
+ # ---------------------------------------------------------------- pure arithmetic
204
+
205
+ def _num(value):
206
+ try:
207
+ number = float(value)
208
+ except (TypeError, ValueError):
209
+ return 0.0
210
+ return number if math.isfinite(number) else 0.0
211
+
212
+
213
+ def band_for(net_profit, margin, thin=THIN_DEFAULT):
214
+ """Losing below 0 profit, Thin below the threshold margin, else no band."""
215
+ if net_profit is None:
216
+ return None
217
+ if net_profit < 0:
218
+ return "Losing"
219
+ if margin is not None and margin < thin:
220
+ return "Thin"
221
+ return None
222
+
223
+
224
+ def compute_row(econ, cost=None, units_per_sku=1, thin=THIN_DEFAULT):
225
+ """One SKU's figures. `cost` None means unlinked: COGS, profit, margin and band stay blank."""
226
+ net_sales = _num(econ.get("net_sales"))
227
+ fees = _num(econ.get("fees"))
228
+ ads = _num(econ.get("ads"))
229
+ units = int(_num(econ.get("units")))
230
+ net_proceeds = net_sales - fees - ads
231
+ row = {"sku": econ.get("sku"), "asin": econ.get("asin") or None,
232
+ "title": econ.get("title") or None, "units_sold": units, "net_sales": net_sales,
233
+ "fees": fees, "sponsored_ads": ads, "net_proceeds": net_proceeds,
234
+ "cogs_per_unit": None, "cogs_total": None, "net_profit": None, "margin": None,
235
+ "band": None}
236
+ if cost is None:
237
+ return row
238
+ cogs_per_unit = _num(cost) * (units_per_sku or 1)
239
+ cogs_total = cogs_per_unit * units
240
+ net_profit = net_proceeds - cogs_total
241
+ margin = (net_profit / net_sales) if net_sales else None
242
+ row.update(cogs_per_unit=cogs_per_unit, cogs_total=cogs_total, net_profit=net_profit,
243
+ margin=margin, band=band_for(net_profit, margin, thin))
244
+ return row
245
+
246
+
247
+ def cells(row, period_label=""):
248
+ """Computed cells as stored strings; None means the cell is blank."""
249
+ out = {}
250
+ for key in COMPUTED_KEYS:
251
+ value = period_label if key == "period" else row.get(key)
252
+ if value is None or value == "":
253
+ out[key] = None
254
+ elif key == "margin":
255
+ out[key] = f"{value * 100:.2f}"
256
+ elif key == "units_sold":
257
+ out[key] = str(int(value))
258
+ elif isinstance(value, float):
259
+ out[key] = f"{value:.2f}"
260
+ else:
261
+ out[key] = str(value)
262
+ return out
263
+
264
+
265
+ def odoo_code(value):
266
+ """The Odoo internal reference a cell names: `RI-1` or `[RI-1] Name`."""
267
+ text = str(value or "").strip()
268
+ match = re.match(r"\[([^\]]+)\]", text)
269
+ return (match.group(1) if match else text).strip()
270
+
271
+
272
+ UNITS_DECIMALS = 4
273
+
274
+
275
+ def units_per_sku(value):
276
+ """Odoo units in one Amazon unit, a positive number that may be a fraction (0.1 of a
277
+ 1000-piece box). Blank, unreadable or not above 0 reads 1."""
278
+ try:
279
+ number = round(float(str(value).strip()), UNITS_DECIMALS)
280
+ except (TypeError, ValueError):
281
+ return 1.0
282
+ return number if math.isfinite(number) and number > 0 else 1.0
283
+
284
+
285
+ def units_text(value):
286
+ """The stored cell for a units value: at most 4 decimals, no trailing zeros."""
287
+ return f"{units_per_sku(value):.{UNITS_DECIMALS}f}".rstrip("0").rstrip(".")
288
+
289
+
290
+ # ---------------------------------------------------------------- owned items (pure)
291
+
292
+ _STATUS_SET = re.compile(r"(.+) since (\d{4}-\d{2}-\d{2})")
293
+
294
+
295
+ def status_set_cell(status, day):
296
+ return f"{status} since {day.isoformat()}"
297
+
298
+
299
+ def parse_status_set(value):
300
+ """`(status, date)` from a `status_set` cell, or `(None, None)`."""
301
+ match = _STATUS_SET.fullmatch(str(value or "").strip())
302
+ if not match:
303
+ return None, None
304
+ try:
305
+ return match.group(1), dt.date.fromisoformat(match.group(2))
306
+ except ValueError:
307
+ return None, None
308
+
309
+
310
+ def owned_changes(row, band, *, today, owner=None):
311
+ """Cells a refresh writes on one SKU's owned item. It never overwrites a person's choice,
312
+ except the reopen: a fix 30 days old on a SKU still Losing or Thin goes back to Open."""
313
+ status = str(row.get("status") or "").strip()
314
+ seen, since = parse_status_set(row.get("status_set"))
315
+ due = (today + dt.timedelta(days=DUE_DAYS)).isoformat()
316
+ if not status:
317
+ if band in BANDS:
318
+ out = {"status": "Open", "status_set": status_set_cell("Open", today)}
319
+ if owner and not str(row.get("owner") or "").strip():
320
+ out["owner"] = owner
321
+ if not str(row.get("due") or "").strip():
322
+ out["due"] = due
323
+ return out
324
+ return {"status_set": None} if row.get("status_set") else {}
325
+ if seen != status or since is None:
326
+ return {"status_set": status_set_cell(status, today)}
327
+ if status in FIX_STATUSES and band in BANDS and (today - since).days >= REOPEN_DAYS:
328
+ return {"status": "Open", "due": due, "status_set": status_set_cell("Open", today)}
329
+ return {}
330
+
331
+
332
+ # ---------------------------------------------------------------- mirror reads (SQL only)
333
+
334
+ def _columns(con, table):
335
+ rows = con.execute("SELECT column_name FROM information_schema.columns WHERE table_name = ?",
336
+ [table]).fetchall()
337
+ return {r[0] for r in rows}
338
+
339
+
340
+ def _require(con, table, required):
341
+ cols = _columns(con, table)
342
+ if not cols:
343
+ raise SourceUnavailable(f"The Amazon mirror has no {table} table. Sync Amazon first.")
344
+ missing = [c for c in required if c not in cols]
345
+ if missing:
346
+ raise SourceUnavailable(f"{table} lacks {', '.join(missing)}. Resync Amazon economics.")
347
+ return cols
348
+
349
+
350
+ def ads_columns(cols):
351
+ """Per ad type totals; charge detail columns are parts of these totals."""
352
+ return sorted(c for c in cols if _ADS_TOTAL.fullmatch(c) and "_charge_" not in c)
353
+
354
+
355
+ def economics_by_sku(con, start, end):
356
+ """`[{sku, asin, units, net_sales, fees, ads}]`: every SKU in the mirror, period sums."""
357
+ cols = _require(con, ECONOMICS, _ECONOMICS_REQUIRED)
358
+ if "currency_code" in cols:
359
+ currencies = con.execute(f"SELECT count(DISTINCT currency_code) FROM {ECONOMICS}").fetchone()[0]
360
+ if currencies > 1:
361
+ raise SourceUnavailable("Amazon economics mixes currencies; profit needs one currency.")
362
+ ads = " + ".join(f'COALESCE("{c}", 0)' for c in ads_columns(cols)) or "0"
363
+ asin = "arg_max(child_asin, start_date)" if "child_asin" in cols else "NULL"
364
+ window = "FILTER (WHERE left(start_date, 10) BETWEEN ? AND ?)"
365
+ sql = (f"SELECT msku, {asin}, "
366
+ f"COALESCE(SUM(sales_net_units_sold) {window}, 0), "
367
+ f"COALESCE(SUM(sales_net_product_sales_amount) {window}, 0), "
368
+ f"COALESCE(SUM(fees_total_amount) {window}, 0), "
369
+ f"COALESCE(SUM({ads}) {window}, 0) "
370
+ f"FROM {ECONOMICS} WHERE NULLIF(trim(msku), '') IS NOT NULL GROUP BY msku ORDER BY msku")
371
+ rows = con.execute(sql, [start, end] * 4).fetchall()
372
+ return [{"sku": r[0], "asin": r[1], "units": r[2], "net_sales": r[3], "fees": r[4],
373
+ "ads": r[5]} for r in rows]
374
+
375
+
376
+ def titles(con):
377
+ """`{seller_sku: item_name}` from the newest listing snapshot; empty without listings."""
378
+ cols = _columns(con, LISTINGS)
379
+ if not {"seller_sku", "item_name"} <= cols:
380
+ return {}
381
+ order = "COALESCE(_snapshot_date, '')" if "_snapshot_date" in cols else "1"
382
+ rows = con.execute(f"SELECT seller_sku, arg_max(item_name, {order}) FROM {LISTINGS} "
383
+ "WHERE seller_sku IS NOT NULL GROUP BY seller_sku").fetchall()
384
+ return {r[0]: r[1] for r in rows if r[1]}
385
+
386
+
387
+ def net_proceeds_total(con, start, end, *, drop_fees=False):
388
+ """Net sales minus fees and ads over the window; `drop_fees` is the negative control."""
389
+ cols = _require(con, ECONOMICS, _ECONOMICS_REQUIRED)
390
+ ads = " + ".join(f'COALESCE("{c}", 0)' for c in ads_columns(cols)) or "0"
391
+ fees = "0" if drop_fees else "COALESCE(fees_total_amount, 0)"
392
+ return float(con.execute(
393
+ f"SELECT COALESCE(SUM(COALESCE(sales_net_product_sales_amount, 0) - {fees} - ({ads})), 0) "
394
+ f"FROM {ECONOMICS} WHERE left(start_date, 10) BETWEEN ? AND ?", [start, end]).fetchone()[0])
395
+
396
+
397
+ def reported_net_proceeds(con, start, end):
398
+ """Amazon's own netProceeds total over the window, or None if the column is absent."""
399
+ if "net_proceeds_total_amount" not in _columns(con, ECONOMICS):
400
+ return None
401
+ return float(con.execute(
402
+ f"SELECT COALESCE(SUM(net_proceeds_total_amount), 0) FROM {ECONOMICS} "
403
+ "WHERE left(start_date, 10) BETWEEN ? AND ?", [start, end]).fetchone()[0])
404
+
405
+
406
+ def economics_currency(con):
407
+ if "currency_code" not in _columns(con, ECONOMICS):
408
+ return None
409
+ return con.execute(f"SELECT any_value(currency_code) FROM {ECONOMICS}").fetchone()[0]
410
+
411
+
412
+ def settlements_total(con, start, end, currency=None):
413
+ """Settlements posted in the window, excluding loan repayment and withheld tax.
414
+
415
+ `currency` keeps settlements whose header row names it: Amazon.ca and Amazon.com.mx settle
416
+ in their own currency, outside the economics marketplace. Their reports write DD.MM.YYYY.
417
+ """
418
+ cols = _require(con, SETTLEMENTS, _SETTLEMENT_REQUIRED)
419
+ scoped = currency is not None and {"currency", "settlement_id"} <= cols
420
+ stream = ("JOIN (SELECT settlement_id FROM {t} WHERE currency IS NOT NULL GROUP BY settlement_id "
421
+ "HAVING any_value(currency) = ?) h USING (settlement_id)").format(t=SETTLEMENTS) if scoped else ""
422
+ total, rows, undated = con.execute(
423
+ "SELECT COALESCE(SUM(amount) FILTER (WHERE d BETWEEN CAST(? AS DATE) AND CAST(? AS DATE)), 0), "
424
+ "count(*) FILTER (WHERE d BETWEEN CAST(? AS DATE) AND CAST(? AS DATE)), "
425
+ "count(*) FILTER (WHERE d IS NULL AND posted_date IS NOT NULL) "
426
+ "FROM (SELECT amount, posted_date, COALESCE(TRY_CAST(left(posted_date, 10) AS DATE), "
427
+ "CAST(try_strptime(left(posted_date, 10), '%d.%m.%Y') AS DATE)) AS d "
428
+ f"FROM {SETTLEMENTS} s {stream} WHERE COALESCE(transaction_type, '') <> ? "
429
+ "AND COALESCE(amount_type, '') <> ?)",
430
+ [start, end, start, end] + ([currency] if scoped else []) + [LOAN_REPAYMENT, WITHHELD_TAX]).fetchone()
431
+ return {"total": float(total), "rows": int(rows), "undated": int(undated),
432
+ "currency": currency if scoped else None}
433
+
434
+
435
+ # ---------------------------------------------------------------- Odoo cost (read only)
436
+
437
+ def odoo_costs(codes):
438
+ """`({code: {id, name, cost}}, problems)` for linked references; search_read only (rule 4)."""
439
+ codes = sorted({c for c in codes if c})
440
+ if not codes:
441
+ return {}, []
442
+ import core.odoo as O
443
+ domain = [("default_code", "in", codes), ("active", "in", [True, False])]
444
+ rows = O.search_read("product.product", domain,
445
+ ["id", "default_code", "name", "standard_price"], limit=len(codes) * 4 + 50)
446
+ expected = O.get_odoo().search_count("product.product", domain)
447
+ if len(rows) != expected:
448
+ raise SourceUnavailable(f"Odoo returned {len(rows)} of {expected} linked products; "
449
+ "the cost read is incomplete.")
450
+ found, problems = {}, []
451
+ by_code = {}
452
+ for row in rows:
453
+ by_code.setdefault(str(row.get("default_code") or ""), []).append(row)
454
+ for code in codes:
455
+ matches = by_code.get(code) or []
456
+ if len(matches) == 1:
457
+ row = matches[0]
458
+ found[code] = {"id": row["id"], "name": row.get("name") or "",
459
+ "cost": _num(row.get("standard_price"))}
460
+ elif matches:
461
+ problems.append(f"{code}: {len(matches)} Odoo products share this reference")
462
+ else:
463
+ problems.append(f"{code}: no Odoo product has this reference")
464
+ return found, problems
465
+
466
+
467
+ def bound_cost_reader(runtime):
468
+ """`odoo_costs` inside this tenant's own Odoo binding; no binding means no cost."""
469
+ def read(codes):
470
+ source = runtime.odoo_source() if hasattr(runtime, "odoo_source") else None
471
+ if source is None:
472
+ return {}, [f"{code}: this workspace has no Odoo connection" for code in sorted(codes)]
473
+ with source._bound():
474
+ return odoo_costs(codes)
475
+ return read
476
+
477
+
478
+ def _odoo_binding(runtime):
479
+ source = runtime.odoo_source() if hasattr(runtime, "odoo_source") else None
480
+ if source is None:
481
+ raise SourceUnavailable("This workspace has no Odoo connection.")
482
+ return source._bound()
483
+
484
+
485
+ # ---------------------------------------------------------------- suggested matches (R13)
486
+
487
+ #: Rule labels a `match_rule` cell stores, in the order the matcher tries them.
488
+ RULE_CODE = "Odoo code"
489
+ RULE_PREFIX = "Odoo code without prefix"
490
+ RULE_PACK = "Odoo code for the pack"
491
+ RULE_AMAZON = "Amazon Odoo code"
492
+ RULE_BARCODE = "Barcode"
493
+ RULE_NAME = "Name"
494
+ RULES = (RULE_CODE, RULE_PREFIX, RULE_PACK, RULE_AMAZON, RULE_BARCODE, RULE_NAME)
495
+ #: Listing report product id types that carry a barcode: 3 is UPC, 4 is EAN.
496
+ BARCODE_ID_TYPES = ("3", "4")
497
+ _NAME_STOP = frozenset("a an and the of for with per in x h to by or on inch inches set pack "
498
+ "piece pieces box bag roll count pcs".split())
499
+ _PACK = re.compile(r"(.+?)_(\d{1,4})")
500
+ _SELLER_PREFIX = re.compile(r"[A-Za-z]{2,3}[-_ ](?=.)")
501
+ _ODOO_PACK = re.compile(r"(\d+)\s*-?\s*pieces?\s+per\s+(?:box|pack|case|bag)", re.I)
502
+ _TITLE_PACK = re.compile(r"\b(?:set|pack)\s+of\s+(\d+)\b|\b(\d+)\s*-?\s*(?:pack|pcs|pieces|count)\b", re.I)
503
+
504
+
505
+ def title_pack(title):
506
+ """Pieces in one Amazon unit as the listing title states them ("Set of 12", "100 Pack"), or None."""
507
+ match = _TITLE_PACK.search(str(title or ""))
508
+ n = int(match.group(1) or match.group(2)) if match else 0
509
+ return n if n > 0 else None
510
+
511
+
512
+ def odoo_pack(name):
513
+ """Pieces in one Odoo unit from its name (`24-Piece Per Box` is 24), or None."""
514
+ match = _ODOO_PACK.search(str(name or ""))
515
+ return int(match.group(1)) if match and int(match.group(1)) > 0 else None
516
+
517
+
518
+ def odoo_units(n, name):
519
+ """Odoo units in one Amazon unit of `n` pieces: n / k when the Odoo name states k pieces,
520
+ to 4 decimals and never 0; n when it states none."""
521
+ n = max(int(n or 1), 1)
522
+ k = odoo_pack(name)
523
+ if k is None:
524
+ return float(n)
525
+ return max(round(n / k, UNITS_DECIMALS), 10.0 ** -UNITS_DECIMALS)
526
+
527
+
528
+ def _norm_code(value):
529
+ return re.sub(r"[^A-Z0-9]", "", str(value or "").upper())
530
+
531
+
532
+ def _norm_barcode(value):
533
+ return re.sub(r"\D", "", str(value or "")).lstrip("0")
534
+
535
+
536
+ def _name_tokens(text, brand=()):
537
+ text = str(text or "").lower().split("|")[0]
538
+ return {w for w in re.findall(r"[a-z0-9]+(?:\.[0-9]+)?", text)
539
+ if w not in _NAME_STOP and w not in brand and (len(w) > 1 or w.isdigit())}
540
+
541
+
542
+ def odoo_catalogue():
543
+ """Every Odoo product, active and archived, in one read; search_read and search_count only."""
544
+ import core.odoo as O
545
+ domain = [("active", "in", [True, False])]
546
+ expected = O.get_odoo().search_count("product.product", domain)
547
+ rows = O.search_read("product.product", domain,
548
+ ["id", "default_code", "barcode", "name"], limit=expected + 50)
549
+ if len(rows) != expected:
550
+ raise SourceUnavailable(f"Odoo returned {len(rows)} of {expected} products; "
551
+ "the product read is incomplete.")
552
+ return rows
553
+
554
+
555
+ def listing_barcodes(con):
556
+ """`{seller_sku: barcode}` from the newest listing snapshot, UPC and EAN ids only."""
557
+ cols = _columns(con, LISTINGS)
558
+ if not {"seller_sku", "product_id", "product_id_type"} <= cols:
559
+ return {}
560
+ order = "COALESCE(_snapshot_date, '')" if "_snapshot_date" in cols else "1"
561
+ rows = con.execute(f"SELECT seller_sku, arg_max(product_id, {order}), "
562
+ f"arg_max(CAST(TRY_CAST(product_id_type AS BIGINT) AS VARCHAR), {order}) FROM {LISTINGS} "
563
+ "WHERE seller_sku IS NOT NULL GROUP BY seller_sku").fetchall()
564
+ return {r[0]: r[1] for r in rows if r[1] and str(r[2]).strip() in BARCODE_ID_TYPES}
565
+
566
+
567
+ class Matcher:
568
+ """Suggests one Odoo product per Amazon SKU. Only a product whose code is unique can link."""
569
+
570
+ def __init__(self, products, brand=("royal", "imports")):
571
+ codes = {}
572
+ for p in products:
573
+ code = str(p.get("default_code") or "").strip()
574
+ if code and code != "False":
575
+ codes.setdefault(code, []).append(p)
576
+ self.by_code = {code: rows[0] for code, rows in codes.items() if len(rows) == 1}
577
+ self.by_norm, self.by_barcode = {}, {}
578
+ for code, p in self.by_code.items():
579
+ self.by_norm.setdefault(_norm_code(code), []).append(code)
580
+ barcode = p.get("barcode")
581
+ if barcode and barcode is not False and _norm_barcode(barcode):
582
+ self.by_barcode.setdefault(_norm_barcode(barcode), []).append(code)
583
+ self.brand = frozenset(brand)
584
+ self.tokens = {code: _name_tokens(p.get("name"), self.brand) for code, p in self.by_code.items()}
585
+ df = {}
586
+ for toks in self.tokens.values():
587
+ for w in toks:
588
+ df[w] = df.get(w, 0) + 1
589
+ total = max(len(self.tokens), 1)
590
+ self.idf = {w: math.log(total / (1 + n)) + 1.0 for w, n in df.items()}
591
+ self.index = {}
592
+ for code, toks in self.tokens.items():
593
+ for w in toks:
594
+ self.index.setdefault(w, []).append(code)
595
+
596
+ def label(self, code):
597
+ return f"[{code}] {self.by_code[code].get('name') or ''}".strip()
598
+
599
+ def _one(self, codes, rejected):
600
+ codes = [c for c in codes or () if c not in rejected]
601
+ return codes[0] if len(codes) == 1 else None
602
+
603
+ def _by_code(self, candidate, rejected):
604
+ exact = [c for c in self.by_norm.get(_norm_code(candidate), ()) if c.upper() == candidate.upper()]
605
+ return self._one(exact, rejected) or self._one(self.by_norm.get(_norm_code(candidate)), rejected)
606
+
607
+ def code_candidates(self, sku):
608
+ """`[(candidate code, pieces, rule)]` in the order the code rules try them. Pieces is
609
+ the `_n` count for the pack stem, 0 for a pack code (one Odoo unit), None otherwise."""
610
+ raw = str(sku or "").strip()
611
+ out = [(raw, None, RULE_CODE)]
612
+ plain = re.sub(r"\s*\(#?[^)]*\)\s*$", "", raw).lstrip(".#-_ ")
613
+ base = _SELLER_PREFIX.sub("", plain, count=1)
614
+ out += [(plain, None, RULE_PREFIX), (base, None, RULE_PREFIX)]
615
+ pack = _PACK.fullmatch(base)
616
+ if pack:
617
+ stem, n = pack.group(1), int(pack.group(2))
618
+ out += [(f"{stem}-{n:02d}", 0, RULE_PACK), (stem, max(n, 1), RULE_PACK)]
619
+ out += [("AMZ" + c, u, RULE_AMAZON) for c, u, _ in list(out)]
620
+ return [item for item in out if item[0]]
621
+
622
+ def pack_units(self, sku):
623
+ base = _SELLER_PREFIX.sub("", str(sku or "").strip().lstrip(".#-_ "), count=1)
624
+ pack = _PACK.fullmatch(re.sub(r"\s*\(#?[^)]*\)\s*$", "", base))
625
+ return max(int(pack.group(2)), 1) if pack else None
626
+
627
+ def by_name(self, title, rejected):
628
+ """The product whose every name word (three or more) is in the title, with a clear lead
629
+ on the next. A short generic name such as `WEDDING ARCH` matches too many titles."""
630
+ words = _name_tokens(title, self.brand)
631
+ if not words:
632
+ return None
633
+ seen, scored = set(), []
634
+ for w in words:
635
+ for code in self.index.get(w, ()):
636
+ if code in seen or code in rejected:
637
+ continue
638
+ seen.add(code)
639
+ toks = self.tokens[code]
640
+ if len(toks) >= 3 and sum(not t[0].isdigit() for t in toks) >= 2 and toks <= words:
641
+ scored.append((sum(self.idf[t] for t in toks), code))
642
+ scored.sort(reverse=True)
643
+ if not scored or (len(scored) > 1 and scored[0][0] - scored[1][0] < 1.0):
644
+ return None
645
+ return scored[0][1]
646
+
647
+ def _units(self, code, n):
648
+ """Pieces in the Amazon unit become Odoo units; 0 (a pack code) or unknown stays 1."""
649
+ return odoo_units(n, self.by_code[code].get("name")) if n else 1.0
650
+
651
+ def suggest(self, sku, *, title=None, barcode=None, rejected=()):
652
+ """`{code, product, units, rule}` or None."""
653
+ rejected = set(rejected or ())
654
+ suffix = self.pack_units(sku)
655
+ pieces = suffix or title_pack(title)
656
+ for candidate, n, rule in self.code_candidates(sku):
657
+ code = self._by_code(candidate, rejected)
658
+ if code:
659
+ if n is None:
660
+ n = None if suffix else pieces
661
+ return {"code": code, "product": self.label(code), "rule": rule,
662
+ "units": self._units(code, n)}
663
+ if barcode and _norm_barcode(barcode):
664
+ code = self._one(self.by_barcode.get(_norm_barcode(barcode)), rejected)
665
+ if code:
666
+ return {"code": code, "product": self.label(code), "units": self._units(code, pieces),
667
+ "rule": RULE_BARCODE}
668
+ code = self.by_name(title, rejected) if title else None
669
+ if code:
670
+ return {"code": code, "product": self.label(code), "units": self._units(code, pieces),
671
+ "rule": RULE_NAME}
672
+ return None
673
+
674
+
675
+ def _rejected_codes(row):
676
+ return [c for c in (s.strip() for s in str(row.get("match_rejected") or "").split(",")) if c]
677
+
678
+
679
+ def decision_changes(row, state):
680
+ """Cells a person's Confirm or Reject writes on one row; {} when there is nothing to apply."""
681
+ if str(row.get("odoo_product") or "").strip():
682
+ return {}
683
+ suggested = str(row.get("suggested_product") or "").strip()
684
+ if state == CONFIRMED and suggested:
685
+ return {"odoo_product": suggested,
686
+ "units_per_sku": units_text(row.get("suggested_units")),
687
+ "match_state": CONFIRMED}
688
+ if state == REJECTED and suggested:
689
+ rejected = _rejected_codes(row)
690
+ code = odoo_code(suggested)
691
+ if code and code not in rejected:
692
+ rejected.append(code)
693
+ return {"match_state": REJECTED, "match_rejected": ", ".join(rejected),
694
+ **{k: None for k in SUGGESTION_KEYS}}
695
+ return {}
696
+
697
+
698
+ def _apply_cells(row, changes):
699
+ for key, value in changes.items():
700
+ if value is None:
701
+ row.pop(key, None)
702
+ else:
703
+ row[key] = value
704
+
705
+
706
+ def apply_decisions(st, *, by=WRITER, sku=None, state=None):
707
+ """Apply every Confirmed or Rejected match state a person set, or one door's decision on
708
+ `sku`. Returns `{confirmed, rejected}` and, for a door, the row after the change."""
709
+ import core.user_tables as ut
710
+ counts, after = {}, {}
711
+
712
+ def _set(cur):
713
+ counts.clear()
714
+ after.clear()
715
+ counts.update(confirmed=0, rejected=0)
716
+ table = (cur or {}).get(TABLE_KEY)
717
+ if table is None:
718
+ return cur
719
+ for row in (table.get("rows") or {}).values():
720
+ row_sku = str(row.get("sku") or "").strip()
721
+ if sku is not None and row_sku != sku:
722
+ continue
723
+ want = state if sku is not None else str(row.get("match_state") or "").strip()
724
+ changes = decision_changes(row, want)
725
+ if changes:
726
+ _apply_cells(row, changes)
727
+ counts["confirmed" if want == CONFIRMED else "rejected"] += 1
728
+ if sku is not None:
729
+ after.update(row)
730
+ return cur
731
+
732
+ ut.update_with_activity(TABLE_KEY, _set, st=st, by=by or WRITER, via=VIA, row_ids=None)
733
+ return {**counts, "row": dict(after) if sku is not None else None}
734
+
735
+
736
+ def suggest_matches(st, con, products, *, by=WRITER):
737
+ """Suggest an Odoo product for every unlinked SKU, no cap, in one store write. A SKU whose
738
+ Odoo product is set is never touched. Suggestions go to this table only, never to Odoo."""
739
+ import core.user_tables as ut
740
+ matcher = Matcher(products)
741
+ names, barcodes = titles(con), listing_barcodes(con)
742
+ counts = {}
743
+
744
+ def _set(cur):
745
+ counts.clear()
746
+ counts.update(considered=0, suggested=0, unmatched=0, **{rule: 0 for rule in RULES})
747
+ table = (cur or {}).get(TABLE_KEY)
748
+ if table is None:
749
+ return cur
750
+ for row in (table.get("rows") or {}).values():
751
+ sku = str(row.get("sku") or "").strip()
752
+ if not sku or str(row.get("odoo_product") or "").strip():
753
+ continue
754
+ counts["considered"] += 1
755
+ state = str(row.get("match_state") or "").strip()
756
+ found = matcher.suggest(sku, title=names.get(sku) or row.get("title"),
757
+ barcode=barcodes.get(sku), rejected=_rejected_codes(row))
758
+ if found is None:
759
+ counts["unmatched"] += 1
760
+ changes = {k: None for k in SUGGESTION_KEYS}
761
+ if state in (NEEDS_REVIEW, CONFIRMED):
762
+ changes["match_state"] = None
763
+ else:
764
+ counts["suggested"] += 1
765
+ counts[found["rule"]] += 1
766
+ changes = {"suggested_product": found["product"], "match_state": NEEDS_REVIEW,
767
+ "suggested_units": units_text(found["units"]), "match_rule": found["rule"]}
768
+ _apply_cells(row, {k: v for k, v in changes.items()
769
+ if v != row.get(k) and not (v is None and k not in row)})
770
+ return cur
771
+
772
+ ut.update_with_activity(TABLE_KEY, _set, st=st, by=by or WRITER, via=VIA, row_ids=None)
773
+ return dict(counts)
774
+
775
+
776
+ def _log(line):
777
+ try:
778
+ print(f"amazon_profit: {line}", flush=True)
779
+ except Exception: # noqa: BLE001
780
+ pass
781
+
782
+
783
+ def _sync_cursor(tenant_key, rt):
784
+ """`(cursor, close)` on the tenant mirror the sync just wrote, else a fresh stored snapshot."""
785
+ from harness import amazon_store
786
+ path = Path(amazon_store._tenant_mirror_path(tenant_key, rt))
787
+ if path.is_file():
788
+ from harness import datastore
789
+ try:
790
+ shared = Path(datastore.DB_PATH).resolve() == path.resolve()
791
+ except Exception: # noqa: BLE001
792
+ shared = False
793
+ if shared:
794
+ cur = datastore.ro_cursor()
795
+ else:
796
+ import duckdb
797
+ cur = duckdb.connect(str(path), read_only=True)
798
+ if _mirror_has_economics(cur):
799
+ return cur, cur.close
800
+ cur.close()
801
+ for key in [k for k in _SNAPSHOT if k[0] == tenant_key]:
802
+ _SNAPSHOT.pop(key, None)
803
+ cur = snapshot_cursor(tenant_key)
804
+ return cur, cur.close
805
+
806
+
807
+ def sync_matches(tenant_key, synced_tables, *, st=None, con=None, catalogue=None, today=None):
808
+ """Refresh the current period, apply decisions, then suggest for every unlinked SKU.
809
+ Returns the report. It raises on failure; `on_amazon_sync` is the never-raise wrapper."""
810
+ synced = {str(t or "").strip().lower() for t in synced_tables or ()}
811
+ if not synced & {"economics", "listings"}:
812
+ return {"state": "skipped", "synced": sorted(synced)}
813
+ if st is None:
814
+ from harness import amazon_store
815
+ st = amazon_store._runtime_for(tenant_key)
816
+ if st is None:
817
+ raise SourceUnavailable(f"The store for {tenant_key} could not be opened.")
818
+ close = None
819
+ if con is None:
820
+ con, close = _sync_cursor(tenant_key, st)
821
+ try:
822
+ report = {"state": "done"}
823
+ try:
824
+ refreshed = refresh(st, con, by=WRITER, cost_reader=bound_cost_reader(st), today=today,
825
+ tenant=tenant_key)
826
+ report["refresh"] = {k: refreshed.get(k) for k in ("skus", "linked", "refusal")}
827
+ except Exception as exc: # noqa: BLE001
828
+ report["refreshError"] = f"{type(exc).__name__}: {exc}"
829
+ _log(f"{tenant_key}: the profit refresh failed ({report['refreshError']}); "
830
+ "suggesting on the rows already stored.")
831
+ with _LOCK:
832
+ ensure_table(st, WRITER)
833
+ report["decisions"] = apply_decisions(st)
834
+ if catalogue is None:
835
+ with _odoo_binding(st):
836
+ products = odoo_catalogue()
837
+ else:
838
+ products = catalogue()
839
+ with _LOCK:
840
+ report["matches"] = suggest_matches(st, con, products)
841
+ write_settings(st, matchedAt=dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds"),
842
+ matches=report["matches"], matchError=None)
843
+ return report
844
+ finally:
845
+ if close is not None:
846
+ try:
847
+ close()
848
+ except Exception: # noqa: BLE001
849
+ pass
850
+
851
+
852
+ def on_amazon_sync(tenant_key, synced_tables):
853
+ """Contract C2 callback after an Amazon sync. Never raises: a failure logs one line naming
854
+ the cause, links nothing and returns."""
855
+ try:
856
+ return sync_matches(tenant_key, synced_tables)
857
+ except Exception as exc: # noqa: BLE001
858
+ reason = f"{type(exc).__name__}: {exc}"
859
+ _log(f"{tenant_key}: no Odoo matches suggested; every SKU stays unlinked. Cause: {reason}")
860
+ try:
861
+ from harness import amazon_store
862
+ st = amazon_store._runtime_for(tenant_key)
863
+ if st is not None:
864
+ write_settings(st, matchError=reason)
865
+ except Exception: # noqa: BLE001
866
+ pass
867
+ return {"state": "failed", "reason": reason}
868
+
869
+
870
+ # ---------------------------------------------------------------- module-owned table
871
+
872
+ def _definition_fields():
873
+ import core.user_tables as ut
874
+ cleaned = ut.clean_fields([dict(f) for f in COMPUTED_FIELDS + OWNED_FIELDS + TRACK_FIELDS])
875
+ by_key = {f["key"]: f for f in cleaned}
876
+ if set(by_key) != set(ALL_KEYS):
877
+ raise TableRefused("The profit columns failed the table field check.")
878
+ out = []
879
+ for key in ALL_KEYS:
880
+ field = dict(by_key[key])
881
+ # editRole governs the column definition only. Cell values on owned columns follow the
882
+ # database edit grant (`may_edit_database`), so editors edit them and viewers cannot.
883
+ field["editRole"] = "admins"
884
+ if key not in OWNED_KEYS:
885
+ field["automation"] = {"preset": True, "flowId": VIA}
886
+ out.append(field)
887
+ return out
888
+
889
+
890
+ def _format_repairs(fields, wanted):
891
+ """`{key: format}` for module fields an adopted table holds without their format."""
892
+ want = {f["key"]: f["format"] for f in wanted if f.get("format")}
893
+ return {f.get("key"): want[f.get("key")] for f in fields or ()
894
+ if isinstance(f, dict) and f.get("key") in want and not f.get("format")}
895
+
896
+
897
+ def ensure_table(st, username):
898
+ """Create or adopt the module table; add missing columns, never retype one. Returns its key."""
899
+ import core.user_tables as ut
900
+ wanted = _definition_fields()
901
+ have = ut.get_one(TABLE_KEY, st)
902
+ if (have is not None and {f["key"] for f in wanted} <= {f.get("key") for f in have.get("fields") or []}
903
+ and not _format_repairs(have.get("fields"), wanted)):
904
+ return TABLE_KEY
905
+ created = dt.datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
906
+ refused = []
907
+
908
+ def _up(cur):
909
+ cur = cur if isinstance(cur, dict) else {}
910
+ table = cur.get(TABLE_KEY)
911
+ if table is None:
912
+ if ut.capped_table_count(cur) >= ut.MAX_TABLES:
913
+ refused.append("cap")
914
+ return cur
915
+ cur[TABLE_KEY] = {"key": TABLE_KEY, "label": TABLE_LABEL, "source": ut.AUTOMATION_SOURCE,
916
+ "createdBy": username or WRITER, "created": created,
917
+ "fields": [dict(f) for f in wanted], "rows": {}}
918
+ return cur
919
+ present = {f.get("key") for f in table.get("fields") or []}
920
+ repairs = _format_repairs(table.get("fields"), wanted)
921
+ for field in table.get("fields") or []:
922
+ if field.get("key") in repairs:
923
+ field["format"] = dict(repairs[field["key"]])
924
+ table.setdefault("fields", []).extend(dict(f) for f in wanted if f["key"] not in present)
925
+ return cur
926
+
927
+ st.update(ut.STORE_KEY, _up, flush="sync")
928
+ if refused:
929
+ raise TableRefused(f"This workspace already holds {ut.MAX_TABLES} databases, so "
930
+ f"{TABLE_LABEL} cannot be created. Delete an unused database, then refresh.")
931
+ if ut.get_one(TABLE_KEY, st) is None:
932
+ raise TableRefused(f"The store did not keep {TABLE_LABEL}. Refresh again.")
933
+ return TABLE_KEY
934
+
935
+
936
+ def table_rows(st):
937
+ import core.user_tables as ut
938
+ return dict((ut.get_one(TABLE_KEY, st) or {}).get("rows") or {})
939
+
940
+
941
+ def links(rows):
942
+ """`{sku: {code, units_per_sku}}` from the owned columns."""
943
+ out = {}
944
+ for row in rows.values():
945
+ sku = str(row.get("sku") or "").strip()
946
+ if sku:
947
+ out[sku] = {"code": odoo_code(row.get("odoo_product")),
948
+ "units_per_sku": units_per_sku(row.get("units_per_sku"))}
949
+ return out
950
+
951
+
952
+ def _rid_order(rid):
953
+ text = str(rid)
954
+ return (0, int(text), text) if text.isdigit() else (1, 0, text)
955
+
956
+
957
+ def merge_duplicates(st):
958
+ """Keep one row per SKU (R10): the oldest row takes empty owned cells from its copies,
959
+ then the copies go. Returns how many rows were removed."""
960
+ import core.user_tables as ut
961
+ groups = {}
962
+ for rid, row in table_rows(st).items():
963
+ sku = str(row.get("sku") or "").strip()
964
+ if sku:
965
+ groups.setdefault(sku, []).append(str(rid))
966
+ extra = {}
967
+ for rids in groups.values():
968
+ if len(rids) > 1:
969
+ rids.sort(key=_rid_order)
970
+ extra[rids[0]] = rids[1:]
971
+ if not extra:
972
+ return 0
973
+ dropped = [rid for rids in extra.values() for rid in rids]
974
+
975
+ def _merge(cur):
976
+ table = cur.get(TABLE_KEY)
977
+ if table is None:
978
+ return cur
979
+ rows = table.get("rows") or {}
980
+ order = table.get("_rowCreationOrder") or {}
981
+ for keep, copies in extra.items():
982
+ row = rows.get(keep)
983
+ if row is None:
984
+ continue
985
+ for rid in copies:
986
+ copy = rows.pop(rid, None) or {}
987
+ order.pop(rid, None)
988
+ for key in OWNED_KEYS + TRACK_KEYS:
989
+ if not str(row.get(key) or "").strip() and str(copy.get(key) or "").strip():
990
+ row[key] = copy[key]
991
+ return cur
992
+
993
+ ut.update_with_activity(TABLE_KEY, _merge, st=st, by=WRITER, via=VIA,
994
+ row_ids=list(extra) + dropped, flush="sync")
995
+ return len(dropped)
996
+
997
+
998
+ def write_rows(st, computed):
999
+ """Upsert computed cells by SKU in two store writes; owned cells are never touched."""
1000
+ import core.user_tables as ut
1001
+ existing = table_rows(st)
1002
+ seen = {str(r.get("sku") or "").strip() for r in existing.values()}
1003
+ new = [{k: v for k, v in values.items() if v is not None}
1004
+ for sku, values in computed.items() if sku not in seen]
1005
+ limit = ut.row_limit(TABLE_KEY, st)
1006
+ if limit and len(existing) + len(new) > limit:
1007
+ raise TableRefused(
1008
+ f"{TABLE_LABEL} holds at most {limit:,} rows and Amazon has "
1009
+ f"{len(existing) + len(new):,} SKUs. Cause: a user database is capped at {limit:,} "
1010
+ "rows. Fix: read this table through the mirror instead of storing rows.")
1011
+ created = 0
1012
+ if new:
1013
+ made = ut.add_rows(TABLE_KEY, new, username=WRITER, st=st, by=WRITER, via=VIA)
1014
+ if made is None:
1015
+ raise TableRefused(f"The store refused new rows for {TABLE_LABEL}.")
1016
+ created = len(made)
1017
+ updated = []
1018
+
1019
+ def _set(cur):
1020
+ updated.clear()
1021
+ table = cur.get(TABLE_KEY)
1022
+ if table is None:
1023
+ return cur
1024
+ for rid, row in (table.get("rows") or {}).items():
1025
+ sku = str(row.get("sku") or "").strip()
1026
+ values = computed.get(sku)
1027
+ if values is None:
1028
+ values = {k: None for k in _PERIOD_KEYS}
1029
+ changed = False
1030
+ for key, value in values.items():
1031
+ if value is None:
1032
+ changed = row.pop(key, None) is not None or changed
1033
+ elif row.get(key) != value:
1034
+ row[key] = value
1035
+ changed = True
1036
+ if changed:
1037
+ updated.append(rid)
1038
+ return cur
1039
+
1040
+ ut.update_with_activity(TABLE_KEY, _set, st=st, by=WRITER, via=VIA, row_ids=None)
1041
+ return {"created": created, "updated": len(updated)}
1042
+
1043
+
1044
+ # ---------------------------------------------------------------- settings
1045
+
1046
+ def read_settings(st):
1047
+ raw = {}
1048
+ try:
1049
+ raw = st.get(SETTINGS_KEY) or {}
1050
+ except Exception: # noqa: BLE001
1051
+ raw = {}
1052
+ raw = raw if isinstance(raw, dict) else {}
1053
+ period = raw.get("period") or PERIOD_DEFAULT
1054
+ try:
1055
+ period_bounds(period)
1056
+ except ValueError:
1057
+ period = PERIOD_DEFAULT
1058
+ try:
1059
+ thin = clean_thin(raw.get("thin"))
1060
+ except ValueError:
1061
+ thin = THIN_DEFAULT
1062
+ owner = str(raw.get("defaultOwner") or "").strip().lower() or None
1063
+ return {**raw, "period": period, "thin": thin, "defaultOwner": owner}
1064
+
1065
+
1066
+ def write_settings(st, **values):
1067
+ def _up(cur):
1068
+ cur = dict(cur) if isinstance(cur, dict) else {}
1069
+ cur.update(values)
1070
+ return cur
1071
+ st.update(SETTINGS_KEY, _up, flush="sync")
1072
+
1073
+
1074
+ # ---------------------------------------------------------------- default owner (R31)
1075
+
1076
+ #: Accounts that act for the platform, never for the business.
1077
+ SERVICE_ACCOUNTS = ("admin", "automation", "scheduler", "qa-runner", "leadership")
1078
+
1079
+
1080
+ def _accounts(tenant):
1081
+ """`[(username, record)]`: the tenant's active accounts, through the one tenant filter."""
1082
+ from core import users
1083
+ return users._tenant_accounts(tenant)
1084
+
1085
+
1086
+ def _is_service(username, record):
1087
+ name = str(username or "").strip().lower()
1088
+ return (not name or name.startswith("qa") or name in SERVICE_ACCOUNTS
1089
+ or name.endswith("-admin") or bool(record.get("platform_admin")))
1090
+
1091
+
1092
+ def owner_account(tenant=TENANT_ZERO):
1093
+ """The tenant's owner account: no record names one, so the earliest active Administrator
1094
+ that is a person. A person signs in with an email; earliest is the oldest password stamp."""
1095
+ people = [(name, rec) for name, rec in _accounts(tenant)
1096
+ if isinstance(rec, dict) and rec.get("role") == "admin" and not _is_service(name, rec)]
1097
+ if not people:
1098
+ return None
1099
+ people.sort(key=lambda item: ("@" not in item[0], not item[1].get("password_changed_at"),
1100
+ str(item[1].get("password_changed_at") or ""), item[0]))
1101
+ return str(people[0][0]).strip().lower()
1102
+
1103
+
1104
+ def account_name(username, tenant=TENANT_ZERO):
1105
+ """The display name a `user` cell stores for `username`, or None if no active account."""
1106
+ want = str(username or "").strip().lower()
1107
+ for name, rec in _accounts(tenant):
1108
+ if str(name).strip().lower() == want and isinstance(rec, dict):
1109
+ return str(rec.get("name") or name)
1110
+ return None
1111
+
1112
+
1113
+ def set_default_owner(st, username, tenant=TENANT_ZERO, by=""):
1114
+ """Point new owned items at `username`; refuses an account this tenant does not hold."""
1115
+ want = str(username or "").strip().lower()
1116
+ if not want or account_name(want, tenant) is None:
1117
+ raise ValueError("Choose an active account in this workspace.")
1118
+ write_settings(st, defaultOwner=want, defaultOwnerSetBy=by or WRITER)
1119
+ return want
1120
+
1121
+
1122
+ def default_owner(st, tenant=TENANT_ZERO):
1123
+ """`(username, display name)` new owned items get; resolves and stores it on first use."""
1124
+ username = read_settings(st)["defaultOwner"]
1125
+ if not username:
1126
+ username = owner_account(tenant)
1127
+ if username:
1128
+ write_settings(st, defaultOwner=username, defaultOwnerSetBy=WRITER)
1129
+ return username, (account_name(username, tenant) if username else None)
1130
+
1131
+
1132
+ # ---------------------------------------------------------------- seeded views
1133
+
1134
+ def seeded_views():
1135
+ from core import view_templates as vt
1136
+ return list((vt.get(TEMPLATE_KEY) or {}).get("views") or ())
1137
+
1138
+
1139
+ def ensure_views(st, owner):
1140
+ """Write the seeded views once, owned by `owner`, granted to everyone who can open the table.
1141
+
1142
+ A view lives in one personal stratum and reaches others through a `*` view grant, the same
1143
+ residency every shared view has. A view a person deleted stays deleted: `viewsSeeded` in the
1144
+ settings records what was written."""
1145
+ from core import shares
1146
+ from core import view_templates as vt
1147
+ from core.table_store import TableStore
1148
+ done = set(read_settings(st).get("viewsSeeded") or ())
1149
+ ops = TableStore(vt.workspace_key(TABLE_KEY), st)
1150
+ owner = str(owner or WRITER).strip().lower()
1151
+ made = []
1152
+ for view in seeded_views():
1153
+ if view["id"] in done:
1154
+ continue
1155
+ found = ops.find_view(view["id"])
1156
+ holder = found[0] if found else owner
1157
+ if not found:
1158
+ ops.save_view(owner, dict(view, createdBy=owner), actor=WRITER, origin={"client": VIA})
1159
+ made.append(view["id"])
1160
+ held = shares.grants("view", view["id"], st=st)
1161
+ if not any(e["user"] == shares.EVERYONE for e in held["entries"]):
1162
+ shares.set_grants("view", view["id"],
1163
+ held["entries"] + [{"user": shares.EVERYONE, "role": "view"}],
1164
+ owner=held["owner"] or holder, st=st)
1165
+ done.add(view["id"])
1166
+ write_settings(st, viewsSeeded=sorted(done))
1167
+ return made
1168
+
1169
+
1170
+ # ---------------------------------------------------------------- refresh
1171
+
1172
+ def build_rows(con, period, row_links, thin=THIN_DEFAULT, cost_reader=odoo_costs, today=None):
1173
+ """`(computed cells by SKU, report)` for one period. Every SKU in the mirror is present."""
1174
+ bounds = period_bounds(period, today)
1175
+ econ = economics_by_sku(con, bounds["start"], bounds["end"])
1176
+ names = titles(con)
1177
+ codes = {link["code"] for link in row_links.values() if link.get("code")}
1178
+ costs, problems = cost_reader(codes) if codes else ({}, [])
1179
+ computed, linked = {}, 0
1180
+ for item in econ:
1181
+ item = dict(item, title=names.get(item["sku"]))
1182
+ link = row_links.get(item["sku"]) or {}
1183
+ found = costs.get(link.get("code") or "")
1184
+ if found is not None:
1185
+ linked += 1
1186
+ row = compute_row(item, None if found is None else found["cost"],
1187
+ link.get("units_per_sku") or 1, thin)
1188
+ computed[item["sku"]] = cells(row, bounds["label"])
1189
+ report = {"period": bounds, "thin": thin, "skus": len(computed), "linked": linked,
1190
+ "unlinked": len(computed) - linked, "costProblems": problems}
1191
+ return computed, report
1192
+
1193
+
1194
+ def refusal(checks, month):
1195
+ """One plain sentence naming the first failed validate() check, or None if all pass."""
1196
+ label = dt.date.fromisoformat(f"{month}-01").strftime("%B %Y")
1197
+ sentences = (
1198
+ lambda c: (f"Not verified: Amazon net proceeds miss settlements by "
1199
+ f"{c.get('gap') or 0:.1%} in {label}." if math.isfinite(c.get("gap") or 0)
1200
+ else f"Not verified: Amazon has no settlements in {label} to tie to."),
1201
+ lambda c: f"Not verified: the fee check cannot tell a wrong total from a right one in {label}.",
1202
+ lambda c: f"Not verified: {c.get('a')} settlement rows in {label} have no readable date.",
1203
+ lambda c: f"Not verified: SKU net proceeds do not add up to Amazon's total in {label}.",
1204
+ lambda c: "Not verified: the SKU list is incomplete.",
1205
+ )
1206
+ for index, check in enumerate(checks):
1207
+ if not check.get("ok"):
1208
+ if index < len(sentences):
1209
+ return sentences[index](check)
1210
+ return f"Not verified: the Amazon figures do not tie in {label}."
1211
+ return None
1212
+
1213
+
1214
+ def unverified(computed, sentence):
1215
+ """Cells with every period figure blank and the refusal in the period cell. Never a 0."""
1216
+ return {sku: {**values, **{k: None for k in _UNVERIFIED_KEYS}, "period": sentence}
1217
+ for sku, values in computed.items()}
1218
+
1219
+
1220
+ def apply_owned(st, bands, *, today, owner=None):
1221
+ """Open, reopen and stamp owned items in one store write. Returns the counts."""
1222
+ import core.user_tables as ut
1223
+ counts = {}
1224
+
1225
+ def _set(cur):
1226
+ counts.clear()
1227
+ counts.update(opened=0, reopened=0, stamped=0)
1228
+ table = cur.get(TABLE_KEY)
1229
+ if table is None:
1230
+ return cur
1231
+ for row in (table.get("rows") or {}).values():
1232
+ sku = str(row.get("sku") or "").strip()
1233
+ before = str(row.get("status") or "").strip()
1234
+ changes = owned_changes(row, bands.get(sku), today=today, owner=owner)
1235
+ if not changes:
1236
+ continue
1237
+ for key, value in changes.items():
1238
+ if value is None:
1239
+ row.pop(key, None)
1240
+ else:
1241
+ row[key] = value
1242
+ if changes.get("status") == "Open":
1243
+ counts["reopened" if before else "opened"] += 1
1244
+ else:
1245
+ counts["stamped"] += 1
1246
+ return cur
1247
+
1248
+ ut.update_with_activity(TABLE_KEY, _set, st=st, by=WRITER, via=VIA, row_ids=None)
1249
+ return dict(counts)
1250
+
1251
+
1252
+ def refresh(st, con, *, period=None, thin=None, by="", cost_reader=odoo_costs, today=None,
1253
+ tenant=TENANT_ZERO, validator=None):
1254
+ """Recompute every SKU for the period and store it; owned cells stay. Returns the report.
1255
+
1256
+ It runs validate() first for `verification_month`: a picked month that has ended ties itself.
1257
+ A failed tie writes no figures: the report carries `refusal`, and every period cell reads it."""
1258
+ settings = read_settings(st)
1259
+ period = str(period or settings["period"]).strip().lower()
1260
+ period_bounds(period, today)
1261
+ thin = settings["thin"] if thin is None else clean_thin(thin)
1262
+ day = today or _today()
1263
+ month = verification_month(period, day)
1264
+ checks = (validator or (lambda c, m: validate(month=m, con=c)))(con, month)
1265
+ sentence = refusal(checks, month)
1266
+ with _LOCK:
1267
+ ensure_table(st, by)
1268
+ merged = merge_duplicates(st)
1269
+ decisions = apply_decisions(st, by=by or WRITER)
1270
+ owner, owner_label = default_owner(st, tenant)
1271
+ ensure_views(st, owner or by)
1272
+ computed, report = build_rows(con, period, links(table_rows(st)), thin, cost_reader, today)
1273
+ if sentence:
1274
+ computed = unverified(computed, sentence)
1275
+ report.update(write_rows(st, computed), merged=merged,
1276
+ decisions={k: decisions[k] for k in ("confirmed", "rejected")})
1277
+ bands = {sku: values.get("band") for sku, values in computed.items()}
1278
+ report["owned"] = apply_owned(st, bands, today=day, owner=owner_label)
1279
+ stamp = dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds")
1280
+ write_settings(st, period=period, thin=thin, refreshedAt=stamp, refreshedBy=by or WRITER,
1281
+ lastPeriod=report["period"], skus=report["skus"], linked=report["linked"],
1282
+ verifiedMonth=month, refusal=sentence)
1283
+ report.update(tableKey=TABLE_KEY, refreshedAt=stamp, verifiedMonth=month, refusal=sentence,
1284
+ defaultOwner=owner)
1285
+ return report
1286
+
1287
+
1288
+ # ---------------------------------------------------------------- validation source
1289
+
1290
+ _SNAPSHOT = {}
1291
+
1292
+
1293
+ def _mirror_has_economics(con):
1294
+ try:
1295
+ return bool(_columns(con, ECONOMICS))
1296
+ except Exception: # noqa: BLE001
1297
+ return False
1298
+
1299
+
1300
+ def snapshot_cursor(tenant=TENANT_ZERO, tables=(ECONOMICS, SETTLEMENTS, LISTINGS)):
1301
+ """An in-memory DuckDB over the stored mirror snapshot. Downloads only; writes nothing back."""
1302
+ key = (tenant, tuple(tables))
1303
+ if key in _SNAPSHOT:
1304
+ return _SNAPSHOT[key].cursor()
1305
+ import duckdb
1306
+ from harness import runtime as R
1307
+ rt = R.get_runtime(tenant)
1308
+ raw = rt.download_bytes("amazon_mirror/manifest.json")
1309
+ if raw is None:
1310
+ raise SourceUnavailable(f"{tenant} has no stored Amazon mirror.")
1311
+ manifest = json.loads(raw)
1312
+ if manifest.get("tenant") != tenant:
1313
+ raise SourceUnavailable("The stored Amazon mirror names another tenant.")
1314
+ folder = Path(tempfile.mkdtemp(prefix="amazon-profit-"))
1315
+ atexit.register(shutil.rmtree, folder, True)
1316
+ con = duckdb.connect()
1317
+ for name in tables:
1318
+ meta = (manifest.get("tables") or {}).get(name)
1319
+ if not isinstance(meta, dict):
1320
+ continue
1321
+ paths = []
1322
+ for index, part in enumerate(meta.get("parts") or [meta]):
1323
+ blob_key = part.get("key") or f"{name}.parquet"
1324
+ data = rt.download_bytes("amazon_mirror/" + blob_key)
1325
+ if data is None or (part.get("sha256") and hashlib.sha256(data).hexdigest() != part["sha256"]):
1326
+ raise SourceUnavailable(f"The stored {name} snapshot failed its checksum.")
1327
+ path = folder / f"{name}.{index:04d}.parquet"
1328
+ path.write_bytes(data)
1329
+ paths.append(str(path))
1330
+ if paths:
1331
+ listed = ", ".join("'" + p.replace("'", "''") + "'" for p in paths)
1332
+ con.execute(f"CREATE VIEW {name} AS SELECT * FROM read_parquet([{listed}], union_by_name=true)")
1333
+ _SNAPSHOT[key] = con
1334
+ return con.cursor()
1335
+
1336
+
1337
+ def validation_cursor(tenant=TENANT_ZERO):
1338
+ """`(cursor, source)`: the local mirror when it holds economics, else the stored snapshot."""
1339
+ try:
1340
+ from harness import datastore as DS
1341
+ if Path(DS.DB_PATH).is_file():
1342
+ con = DS.ro_cursor()
1343
+ if _mirror_has_economics(con):
1344
+ return con, "local mirror"
1345
+ except Exception: # noqa: BLE001
1346
+ pass
1347
+ return snapshot_cursor(tenant), "stored snapshot"
1348
+
1349
+
1350
+ # ---------------------------------------------------------------- validate
1351
+
1352
+ def _tie(a, b, tolerance=SETTLEMENT_TOLERANCE):
1353
+ gap = abs(a - b) / abs(b) if b else (0.0 if a == b else math.inf)
1354
+ return gap <= tolerance, gap
1355
+
1356
+
1357
+ def validate(pre=None, month=None, con=None):
1358
+ """validate.py convention: net proceeds tie to settlements within 2% for one month."""
1359
+ month = month or last_complete_month()
1360
+ bounds = period_bounds(month)
1361
+ start, end = bounds["start"], bounds["end"]
1362
+ source = "given cursor"
1363
+ if con is None:
1364
+ con, source = validation_cursor()
1365
+ checks = []
1366
+ proceeds = net_proceeds_total(con, start, end)
1367
+ settled = settlements_total(con, start, end, economics_currency(con))
1368
+ ok, gap = _tie(proceeds, settled["total"])
1369
+ checks.append({"check": f"amazon_profit {month}: net proceeds tie to settlements within 2% "
1370
+ f"({gap:.2%} apart, {source})",
1371
+ "ok": ok, "a": round(proceeds, 2), "b": round(settled["total"], 2),
1372
+ "gap": round(gap, 4)})
1373
+ dropped = net_proceeds_total(con, start, end, drop_fees=True)
1374
+ control_ok, control_gap = _tie(dropped, settled["total"])
1375
+ checks.append({"check": f"amazon_profit {month}: NC net proceeds without fees miss settlements "
1376
+ f"({control_gap:.2%} apart)",
1377
+ "ok": not control_ok, "a": round(dropped, 2), "b": round(settled["total"], 2),
1378
+ "gap": round(control_gap, 4)})
1379
+ checks.append({"check": f"amazon_profit {month}: every {settled['currency'] or 'settlement'} "
1380
+ "settlement row carries a readable date",
1381
+ "ok": settled["undated"] == 0, "a": settled["undated"], "b": 0,
1382
+ "gap": settled["undated"]})
1383
+ econ = economics_by_sku(con, start, end)
1384
+ ours = sum(compute_row(item)["net_proceeds"] for item in econ)
1385
+ reported = reported_net_proceeds(con, start, end)
1386
+ checks.append({"check": f"amazon_profit {month}: per SKU net proceeds sum to Amazon's reported total",
1387
+ "ok": reported is not None and abs(ours - reported) <= 0.01,
1388
+ "a": round(ours, 2), "b": None if reported is None else round(reported, 2),
1389
+ "gap": None if reported is None else round(abs(ours - reported), 4)})
1390
+ distinct = con.execute(f"SELECT count(DISTINCT msku) FROM {ECONOMICS} "
1391
+ "WHERE NULLIF(trim(msku), '') IS NOT NULL").fetchone()[0]
1392
+ checks.append({"check": f"amazon_profit: every SKU is present, no cap ({len(econ)} SKUs)",
1393
+ "ok": len(econ) == distinct, "a": len(econ), "b": distinct,
1394
+ "gap": abs(len(econ) - distinct)})
1395
+ return checks
1396
+
1397
+
1398
+ # ---------------------------------------------------------------- semantic validator
1399
+
1400
+ def _v_amazon_sku_net_profit(date_from, date_to, team_id=None, **_kwargs):
1401
+ """Per SKU net proceeds (the profit's revenue side) against Amazon's reported total."""
1402
+ con, _source = validation_cursor()
1403
+ start, end = str(date_from)[:10], str(date_to)[:10]
1404
+ ours = sum(compute_row(item)["net_proceeds"] for item in economics_by_sku(con, start, end))
1405
+ reported = reported_net_proceeds(con, start, end)
1406
+ if reported is None:
1407
+ raise SourceUnavailable("amzn_economics lacks net_proceeds_total_amount.")
1408
+ return round(ours, 2), round(reported, 2)
1409
+
1410
+
1411
+ PROFIT_VALIDATORS = {"amazon_sku_net_profit": _v_amazon_sku_net_profit}
1412
+
1413
+
1414
+ def register_semantic_validators():
1415
+ """Register this module's validator until harness/semantic.py imports it directly."""
1416
+ from harness import semantic
1417
+ semantic._VALIDATORS.update(PROFIT_VALIDATORS)
1418
+ return tuple(PROFIT_VALIDATORS)
1419
+
1420
+
1421
+ try:
1422
+ register_semantic_validators()
1423
+ except Exception: # noqa: BLE001
1424
+ pass
platform/modules/competitor_watch.py ADDED
@@ -0,0 +1,660 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Competitor watch App: watched terms, the weekly top 3 comparison, and owned alerts on four triggers.
2
+
3
+ Store documents (tenant runtime store, App owned, never the mirror and never Amazon):
4
+ competitor_watch_settings {undercut_pct, rank_surge_pct, default_owner}
5
+ competitor_watch_terms {seeded: [...], added: [...], removed: [...], seeded_at}
6
+ competitor_watch_alerts {seq, items: {id: alert}, checks: [check, ...]}
7
+ competitor_watch_weeks {last_compared, comparison: {...}, metrics: {period_start: {asin: metric}}}
8
+
9
+ Top 3 history is read from the connector table `amzn_brand_analytics`, which the store's weekly
10
+ retention keeps for watched terms. Deleting this module and its four documents leaves the
11
+ connector intact (rule 13).
12
+
13
+ Limit (rule 1): each document is one JSON value, and the Postgres store refuses a document over
14
+ `core.store_pg.DOCUMENT_CEILING_BYTES` (128 MB). At about 600 bytes an alert, the alerts document
15
+ reaches it near 200,000 alerts. Nothing here caps terms or alerts. The fix when it nears: split
16
+ `competitor_watch_alerts` by year.
17
+ """
18
+ import contextlib
19
+ import datetime as dt
20
+ from pathlib import Path
21
+
22
+ TRIGGERS = {
23
+ "new_asin": "New ASIN in top 3",
24
+ "lost_spot": "Lost spot",
25
+ "undercut": "Undercut",
26
+ "rank_surge": "Rank surge",
27
+ }
28
+ STATUSES = ("Open", "Repriced", "Ads changed", "Listing improved", "Watching", "Ignore")
29
+ #: A key (term, asin, trigger) is held while its latest alert has one of these statuses.
30
+ HOLDING = ("Open", "Watching", "Ignore")
31
+ DEFAULTS = {"undercut_pct": 5.0, "rank_surge_pct": 50.0}
32
+ DUE_DAYS = 7
33
+ NOT_READY = "Comparison starts after the next weekly pull."
34
+ LIMIT = ("Each competitor watch document is limited to 128 MB by the store. About 200,000 alerts "
35
+ "fit in one. Split the alerts document by year when it nears that size.")
36
+
37
+ KEY_SETTINGS = "competitor_watch_settings"
38
+ KEY_TERMS = "competitor_watch_terms"
39
+ KEY_ALERTS = "competitor_watch_alerts"
40
+ KEY_WEEKS = "competitor_watch_weeks"
41
+
42
+ BA_TABLE = "amzn_brand_analytics"
43
+ SQP_TABLE = "amzn_search_query_performance"
44
+ LISTINGS_TABLE = "amzn_listings"
45
+
46
+
47
+ def _now():
48
+ return dt.datetime.now(dt.timezone.utc)
49
+
50
+
51
+ def _stamp(at):
52
+ return at.strftime("%Y-%m-%dT%H:%M:%SZ")
53
+
54
+
55
+ def _norm(term):
56
+ return " ".join(str(term or "").split()).lower()
57
+
58
+
59
+ def _rt(tenant_key, st=None):
60
+ """The tenant runtime store handle (get and update), or raise when it cannot be resolved."""
61
+ if st is not None:
62
+ return st
63
+ from harness import amazon_store
64
+ rt = amazon_store._runtime_for(tenant_key)
65
+ if rt is None:
66
+ raise RuntimeError(f"The store for tenant {tenant_key!r} could not be opened.")
67
+ return rt
68
+
69
+
70
+ def _doc(st, key):
71
+ value = st.get(key)
72
+ return value if isinstance(value, dict) else {}
73
+
74
+
75
+ # --------------------------------------------------------------------------- mirror reads
76
+
77
+ def _mirror_path(tenant_key, st):
78
+ from harness import amazon_store
79
+ rt = st if hasattr(st, "datastore_path") else None
80
+ return amazon_store._tenant_mirror_path(tenant_key, rt)
81
+
82
+
83
+ @contextlib.contextmanager
84
+ def _reader(tenant_key, st):
85
+ """A read-only cursor on the tenant mirror, or None when the mirror file does not exist."""
86
+ path = Path(_mirror_path(tenant_key, st))
87
+ if not path.exists():
88
+ yield None
89
+ return
90
+ from harness import datastore
91
+ try:
92
+ shared = Path(datastore.DB_PATH).resolve() == path.resolve()
93
+ except Exception: # noqa: BLE001
94
+ shared = False
95
+ # The process holds one writer on its own mirror: a separate read-only connect would refuse.
96
+ if shared:
97
+ cur = datastore.ro_cursor()
98
+ try:
99
+ yield cur
100
+ finally:
101
+ cur.close()
102
+ return
103
+ import duckdb
104
+ con = duckdb.connect(str(path), read_only=True)
105
+ try:
106
+ yield con
107
+ finally:
108
+ con.close()
109
+
110
+
111
+ def _columns(cur, table):
112
+ try:
113
+ return {r[0] for r in cur.execute(
114
+ "SELECT column_name FROM information_schema.columns WHERE table_name = ?", [table]).fetchall()}
115
+ except Exception: # noqa: BLE001
116
+ return set()
117
+
118
+
119
+ def _sqp(cur):
120
+ """SQP rows as (term, asin, impressions, end_date). SQP reports our ASINs only."""
121
+ need = {"search_query_data_search_query", "asin"}
122
+ cols = _columns(cur, SQP_TABLE) if cur is not None else set()
123
+ if not need <= cols:
124
+ return []
125
+ imp = ('TRY_CAST("impression_data_asin_impression_count" AS DOUBLE)'
126
+ if "impression_data_asin_impression_count" in cols else "0")
127
+ end = 'CAST("end_date" AS VARCHAR)' if "end_date" in cols else "''"
128
+ rows = cur.execute(
129
+ f'SELECT "search_query_data_search_query", "asin", {imp}, {end} FROM {SQP_TABLE}').fetchall()
130
+ return [(_norm(t), str(a or "").strip(), float(i or 0), str(e or "")) for t, a, i, e in rows if _norm(t)]
131
+
132
+
133
+ def _our_asins(cur, sqp_rows):
134
+ ours = {a for _t, a, _i, _e in sqp_rows if a}
135
+ if cur is not None and "asin1" in _columns(cur, LISTINGS_TABLE):
136
+ ours |= {str(r[0]).strip() for r in cur.execute(
137
+ f'SELECT DISTINCT "asin1" FROM {LISTINGS_TABLE} WHERE "asin1" IS NOT NULL').fetchall()}
138
+ return {a for a in ours if a}
139
+
140
+
141
+ def _our_asin_for(term, sqp_rows):
142
+ """R23: our ASIN with the most impressions on the term, in the term's newest SQP period."""
143
+ rows = [r for r in sqp_rows if r[0] == term and r[1]]
144
+ if not rows:
145
+ return None
146
+ newest = max(r[3] for r in rows)
147
+ totals = {}
148
+ for _t, asin, imp, end in rows:
149
+ if end == newest:
150
+ totals[asin] = totals.get(asin, 0.0) + imp
151
+ return max(sorted(totals), key=lambda a: totals[a])
152
+
153
+
154
+ def _top3(cur, terms=None):
155
+ """{term: {period_start: {"end": str, "rows": {asin: (rank, click_share, conversion_share)}}}}."""
156
+ cols = _columns(cur, BA_TABLE) if cur is not None else set()
157
+ if not {"search_term", "clicked_asin", "click_share_rank", "_period_start"} <= cols:
158
+ return {}
159
+ cs = 'TRY_CAST("click_share" AS DOUBLE)' if "click_share" in cols else "NULL"
160
+ cv = 'TRY_CAST("conversion_share" AS DOUBLE)' if "conversion_share" in cols else "NULL"
161
+ pe = 'CAST("_period_end" AS VARCHAR)' if "_period_end" in cols else "''"
162
+ rows = cur.execute(
163
+ f'SELECT "search_term", CAST("_period_start" AS VARCHAR), {pe}, "clicked_asin", '
164
+ f'TRY_CAST("click_share_rank" AS INTEGER), {cs}, {cv} FROM {BA_TABLE} '
165
+ f'WHERE TRY_CAST("click_share_rank" AS INTEGER) BETWEEN 1 AND 3').fetchall()
166
+ wanted = None if terms is None else set(terms)
167
+ out = {}
168
+ for term, start, end, asin, rank, share, conv in rows:
169
+ key = _norm(term)
170
+ if wanted is not None and key not in wanted or not asin:
171
+ continue
172
+ week = out.setdefault(key, {}).setdefault(str(start), {"end": str(end or ""), "rows": {}})
173
+ week["rows"][str(asin).strip()] = (int(rank), share, conv)
174
+ return out
175
+
176
+
177
+ def _periods(cur):
178
+ if cur is None or "_period_start" not in _columns(cur, BA_TABLE):
179
+ return []
180
+ rows = cur.execute(f'SELECT DISTINCT CAST("_period_start" AS VARCHAR) FROM {BA_TABLE}').fetchall()
181
+ return sorted((str(r[0]) for r in rows if r[0] is not None), reverse=True)
182
+
183
+
184
+ # --------------------------------------------------------------------------- watched terms
185
+
186
+ def watched_terms(tenant_key, *, st=None):
187
+ """Seeded SQP terms plus terms a person added, minus terms a person removed (store only)."""
188
+ doc = _doc(_rt(tenant_key, st), KEY_TERMS)
189
+ removed = {_norm(t) for t in doc.get("removed") or ()}
190
+ terms = {_norm(t) for t in [*(doc.get("seeded") or ()), *(doc.get("added") or ())]}
191
+ return sorted(t for t in terms if t and t not in removed)
192
+
193
+
194
+ def seed_terms(tenant_key, *, st=None, cur=None):
195
+ """Add every distinct SQP search query to the seeded set. A removed term stays removed."""
196
+ st = _rt(tenant_key, st)
197
+ if cur is None:
198
+ with _reader(tenant_key, st) as reader:
199
+ found = {t for t, _a, _i, _e in _sqp(reader)} if reader is not None else set()
200
+ else:
201
+ found = {t for t, _a, _i, _e in _sqp(cur)}
202
+
203
+ def _seed(doc):
204
+ doc = doc if isinstance(doc, dict) else {}
205
+ seeded = set(doc.get("seeded") or ()) | found
206
+ doc["seeded"] = sorted(seeded)
207
+ doc.setdefault("added", [])
208
+ doc.setdefault("removed", [])
209
+ doc["seeded_at"] = _stamp(_now())
210
+ return doc
211
+ st.update(KEY_TERMS, _seed)
212
+ return watched_terms(tenant_key, st=st)
213
+
214
+
215
+ def _edit_terms(tenant_key, terms, add, st):
216
+ clean = sorted({_norm(t) for t in terms or () if _norm(t)})
217
+ if not clean:
218
+ raise ValueError("Name at least one search term.")
219
+ st = _rt(tenant_key, st)
220
+
221
+ def _apply(doc):
222
+ doc = doc if isinstance(doc, dict) else {}
223
+ added, removed = set(doc.get("added") or ()), set(doc.get("removed") or ())
224
+ if add:
225
+ added |= set(clean)
226
+ removed -= set(clean)
227
+ else:
228
+ removed |= set(clean)
229
+ added -= set(clean)
230
+ doc.setdefault("seeded", [])
231
+ doc["added"], doc["removed"] = sorted(added), sorted(removed)
232
+ return doc
233
+ st.update(KEY_TERMS, _apply)
234
+ return watched_terms(tenant_key, st=st)
235
+
236
+
237
+ def add_terms(tenant_key, terms, *, st=None):
238
+ """Watch these terms. A term a person removed before comes back."""
239
+ return _edit_terms(tenant_key, terms, True, st)
240
+
241
+
242
+ def remove_terms(tenant_key, terms, *, st=None):
243
+ """Stop watching these terms. A later SQP seed does not bring them back."""
244
+ return _edit_terms(tenant_key, terms, False, st)
245
+
246
+
247
+ def terms_summary(tenant_key, *, st=None):
248
+ """Every watched term with its source, newest held period and open alert count. No cap."""
249
+ st = _rt(tenant_key, st)
250
+ doc = _doc(st, KEY_TERMS)
251
+ if not doc.get("seeded_at"):
252
+ # First open before any sync: seed from the SQP terms already in the mirror.
253
+ seed_terms(tenant_key, st=st)
254
+ doc = _doc(st, KEY_TERMS)
255
+ seeded = {_norm(t) for t in doc.get("seeded") or ()}
256
+ terms = watched_terms(tenant_key, st=st)
257
+ with _reader(tenant_key, st) as cur:
258
+ held = _top3(cur, terms)
259
+ open_counts = {}
260
+ for alert in (_doc(st, KEY_ALERTS).get("items") or {}).values():
261
+ if alert.get("status") == "Open":
262
+ open_counts[alert.get("term")] = open_counts.get(alert.get("term"), 0) + 1
263
+ return {"terms": [{"term": t, "source": "seeded" if t in seeded else "added",
264
+ "newestPeriod": max(held.get(t, {}), default=None),
265
+ "openAlerts": open_counts.get(t, 0)} for t in terms]}
266
+
267
+
268
+ # --------------------------------------------------------------------------- settings and owner
269
+
270
+ #: Accounts that sign in for a process, never a person who can own an alert (same list as amazon_profit).
271
+ SERVICE_ACCOUNTS = ("admin", "automation", "scheduler", "qa-runner", "leadership")
272
+
273
+
274
+ def _is_service(name, rec):
275
+ name = str(name or "").strip().lower()
276
+ return (not name or name.startswith("qa") or name in SERVICE_ACCOUNTS
277
+ or name.endswith("-admin") or bool(rec.get("platform_admin")))
278
+
279
+
280
+ def owner_account(st, tenant_key=None):
281
+ """R31: the tenant's earliest active person Administrator by display name, as money-losers use.
282
+
283
+ A tenant with no person Administrator falls back to its `admin` account, else its first Administrator."""
284
+ try:
285
+ users = st.get("users")
286
+ except Exception: # noqa: BLE001
287
+ users = None
288
+ want = str(tenant_key or "").strip().lower()
289
+ admins = [(str(name), rec) for name, rec in (users or {}).items()
290
+ if isinstance(rec, dict) and rec.get("active", True)
291
+ and str(rec.get("role") or "").lower() == "admin"
292
+ and (not want or str(rec.get("tenant") or "royal-imports").strip().lower() == want)]
293
+ people = sorted(((n, r) for n, r in admins if not _is_service(n, r)),
294
+ key=lambda item: ("@" not in item[0], not item[1].get("password_changed_at"),
295
+ str(item[1].get("password_changed_at") or ""), item[0]))
296
+ if people:
297
+ return str(people[0][1].get("name") or people[0][0])
298
+ names = sorted(n for n, _r in admins)
299
+ return "admin" if "admin" in names or not names else names[0]
300
+
301
+
302
+ def settings(tenant_key, *, st=None):
303
+ """Thresholds and the default owner, with defaults filled in."""
304
+ st = _rt(tenant_key, st)
305
+ doc = _doc(st, KEY_SETTINGS)
306
+ out = {k: float(doc.get(k, v)) for k, v in DEFAULTS.items()}
307
+ out["defaultOwnerSetting"] = doc.get("default_owner") or None
308
+ out["defaultOwner"] = out["defaultOwnerSetting"] or owner_account(st, tenant_key)
309
+ out["statuses"] = list(STATUSES)
310
+ out["limit"] = LIMIT
311
+ return out
312
+
313
+
314
+ def set_settings(tenant_key, *, undercut_pct=None, rank_surge_pct=None, default_owner=None, st=None):
315
+ """Set thresholds (percent, above 0 and below 100) or the default owner ('' resets to the owner account)."""
316
+ st = _rt(tenant_key, st)
317
+ changes = {}
318
+ for name, value in (("undercut_pct", undercut_pct), ("rank_surge_pct", rank_surge_pct)):
319
+ if value is None:
320
+ continue
321
+ try:
322
+ number = float(value)
323
+ except (TypeError, ValueError):
324
+ raise ValueError("A threshold must be a number.") from None
325
+ if not 0 < number < 100:
326
+ raise ValueError("A threshold must be above 0 and below 100 percent.")
327
+ changes[name] = number
328
+
329
+ def _apply(doc):
330
+ doc = doc if isinstance(doc, dict) else {}
331
+ doc.update(changes)
332
+ if default_owner is not None:
333
+ doc["default_owner"] = str(default_owner).strip() or None
334
+ return doc
335
+ st.update(KEY_SETTINGS, _apply)
336
+ return settings(tenant_key, st=st)
337
+
338
+
339
+ # --------------------------------------------------------------------------- price and rank reads
340
+
341
+ def _parse_price(response):
342
+ """(price, currency, seller_id, cause) from one getCompetitiveSummary item response."""
343
+ status = ((response or {}).get("status") or {}).get("statusCode")
344
+ body = (response or {}).get("body") or {}
345
+ if status not in (None, 200):
346
+ errors = body.get("errors") or []
347
+ reason = str((errors[0] or {}).get("message") or "") if errors else ""
348
+ return None, None, None, f"Amazon refused the price read ({status}{': ' + reason if reason else ''})."
349
+ options = body.get("featuredBuyingOptions") or []
350
+ options = sorted(options, key=lambda o: 0 if str(o.get("buyingOptionType") or "New") == "New" else 1)
351
+ for option in options:
352
+ for offer in option.get("segmentedFeaturedOffers") or [option]:
353
+ price = (offer.get("listingPrice") or {}).get("amount")
354
+ if isinstance(price, (int, float)):
355
+ return (float(price), (offer.get("listingPrice") or {}).get("currencyCode"),
356
+ offer.get("sellerId"), None)
357
+ return None, None, None, "Amazon returned no Buy Box offer for this ASIN."
358
+
359
+
360
+ def _cause(kind, exc):
361
+ from harness import amazon_client as cx
362
+ name = type(exc).__name__
363
+ if isinstance(exc, cx.AmazonThrottled):
364
+ return f"Amazon throttled the {kind} read ({name}). It runs again after the next weekly pull."
365
+ if isinstance(exc, cx.AmazonOperationRefused):
366
+ return f"The connector refused the {kind} read ({name}): {exc}"
367
+ return f"The {kind} read failed ({name}): {exc}"
368
+
369
+
370
+ def _read_prices(tenant_key, st, asins):
371
+ """{asin: (price, currency, seller_id, cause)}; a refused call writes its cause on every ASIN."""
372
+ from harness import amazon_client as cx, amazon_store
373
+ if not asins:
374
+ return {}
375
+ try:
376
+ fields = amazon_store.credential(tenant_key, st if hasattr(st, "datastore_path") else None)
377
+ if not fields:
378
+ raise cx.AmazonError("no Amazon credential is saved for this tenant")
379
+ responses = cx.competitive_summaries(fields, sorted(asins))
380
+ except Exception as exc: # noqa: BLE001
381
+ cause = _cause("price", exc)
382
+ return {a: (None, None, None, cause) for a in asins}
383
+ by_asin = {str(((r or {}).get("body") or {}).get("asin") or ""): r for r in responses}
384
+ return {a: _parse_price(by_asin[a]) if a in by_asin
385
+ else (None, None, None, "Amazon returned no price for this ASIN.") for a in asins}
386
+
387
+
388
+ def _read_ranks(tenant_key, st, asins):
389
+ """{asin: (rank, cause)}; a refused call writes its cause on every ASIN."""
390
+ from harness import amazon_client as cx, amazon_store
391
+ if not asins:
392
+ return {}
393
+ try:
394
+ fields = amazon_store.credential(tenant_key, st if hasattr(st, "datastore_path") else None)
395
+ if not fields:
396
+ raise cx.AmazonError("no Amazon credential is saved for this tenant")
397
+ ranks = cx.catalog_sales_ranks(fields, sorted(asins))
398
+ except Exception as exc: # noqa: BLE001
399
+ cause = _cause("sales rank", exc)
400
+ return {a: (None, cause) for a in asins}
401
+ out = {}
402
+ for a in asins:
403
+ rank = (ranks.get(a) or {}).get("rank")
404
+ out[a] = (rank, None) if isinstance(rank, int) else (None, "Amazon returned no sales rank for this ASIN.")
405
+ return out
406
+
407
+
408
+ # --------------------------------------------------------------------------- the weekly comparison
409
+
410
+ def on_amazon_sync(tenant_key, synced_tables):
411
+ """Contract C2 callback: seed terms, then compare the newest brand analytics week. Never raises."""
412
+ try:
413
+ compare(tenant_key, synced_tables)
414
+ except Exception as exc: # noqa: BLE001
415
+ try:
416
+ def _note(doc):
417
+ doc = doc if isinstance(doc, dict) else {}
418
+ doc["last_error"] = f"The weekly comparison failed ({type(exc).__name__}): {exc}"
419
+ return doc
420
+ _rt(tenant_key).update(KEY_WEEKS, _note)
421
+ except Exception: # noqa: BLE001
422
+ pass
423
+
424
+
425
+ def compare(tenant_key, synced_tables=("brand_analytics",), *, st=None, now=None):
426
+ """Compare the newest held week with the week before and raise owned alerts. Returns a summary."""
427
+ st = _rt(tenant_key, st)
428
+ now = now or _now()
429
+ synced = set(synced_tables or ())
430
+ with _reader(tenant_key, st) as cur:
431
+ if cur is None:
432
+ return {"state": "no_mirror"}
433
+ sqp = _sqp(cur)
434
+ seed_terms(tenant_key, st=st, cur=cur)
435
+ if "brand_analytics" not in synced:
436
+ return {"state": "seeded"}
437
+ periods = _periods(cur)
438
+ terms = watched_terms(tenant_key, st=st)
439
+ held = _top3(cur, terms)
440
+ ours = _our_asins(cur, sqp)
441
+ weeks = _doc(st, KEY_WEEKS)
442
+ if not periods:
443
+ return {"state": "no_week"}
444
+ newest = periods[0]
445
+ if weeks.get("last_compared") == newest:
446
+ return {"state": "already_compared", "period": newest}
447
+ previous = periods[1] if len(periods) > 1 else None
448
+ conf = settings(tenant_key, st=st)
449
+
450
+ # Read price and rank for every top 3 ASIN of the newest week and our priced ASIN per term.
451
+ our_for = {t: _our_asin_for(t, sqp) for t in terms}
452
+ want = set()
453
+ for term in terms:
454
+ want |= set(((held.get(term) or {}).get(newest) or {}).get("rows", {}))
455
+ if our_for.get(term):
456
+ want.add(our_for[term])
457
+ prices = _read_prices(tenant_key, st, want)
458
+ ranks = _read_ranks(tenant_key, st, want)
459
+ metrics = {a: {"price": prices[a][0], "currency": prices[a][1], "sellerId": prices[a][2],
460
+ "priceCause": prices[a][3], "rank": ranks[a][0], "rankCause": ranks[a][1]}
461
+ for a in sorted(want)}
462
+ prior = ((weeks.get("metrics") or {}).get(previous) or {}) if previous else {}
463
+
464
+ raised, checks = [], []
465
+ if previous is not None:
466
+ undercut = conf["undercut_pct"] / 100.0
467
+ surge = conf["rank_surge_pct"] / 100.0
468
+ for term in terms:
469
+ now_week = (held.get(term) or {}).get(newest)
470
+ was_week = (held.get(term) or {}).get(previous)
471
+ if not now_week or not was_week:
472
+ continue
473
+ top_now, top_was = now_week["rows"], was_week["rows"]
474
+ end = now_week["end"]
475
+
476
+ def found(asin, key, detail, cause=None):
477
+ raised.append({"term": term, "asin": asin, "trigger": key, "periodStart": newest,
478
+ "periodEnd": end, "previousPeriodStart": previous, "detail": detail,
479
+ "cause": cause})
480
+
481
+ def asin_cause(asin):
482
+ m = metrics.get(asin) or {}
483
+ return " ".join(c for c in (m.get("priceCause"), m.get("rankCause")) if c) or None
484
+
485
+ for asin in sorted(set(top_now) - set(top_was)):
486
+ found(asin, "new_asin", {"rank": top_now[asin][0]}, asin_cause(asin))
487
+ for asin in sorted((set(top_was) - set(top_now)) & ours):
488
+ found(asin, "lost_spot", {"previousRank": top_was[asin][0]})
489
+ mine = our_for.get(term)
490
+ mine_m = metrics.get(mine) or {}
491
+ if mine is None and set(top_now) - ours:
492
+ checks.append({"term": term, "asin": None, "trigger": TRIGGERS["undercut"],
493
+ "periodStart": newest,
494
+ "cause": "None of our ASINs has impressions on this term, so there is "
495
+ "no price of ours to compare."})
496
+ for asin in sorted(set(top_now) - ours):
497
+ m = metrics.get(asin) or {}
498
+ if mine is None:
499
+ pass
500
+ elif mine_m.get("price") is None or m.get("price") is None:
501
+ cause = " ".join(c for c in (mine_m.get("priceCause") and f"Our price: {mine_m['priceCause']}",
502
+ m.get("priceCause")) if c)
503
+ checks.append({"term": term, "asin": asin, "trigger": TRIGGERS["undercut"],
504
+ "periodStart": newest, "cause": cause or "No price was read."})
505
+ elif m["price"] <= mine_m["price"] * (1 - undercut):
506
+ found(asin, "undercut", {"ourAsin": mine, "ourPrice": mine_m["price"],
507
+ "price": m["price"],
508
+ "percentUnder": round(100 * (1 - m["price"] / mine_m["price"]), 2)},
509
+ asin_cause(asin))
510
+ old = (prior.get(asin) or {})
511
+ if m.get("rank") is None:
512
+ checks.append({"term": term, "asin": asin, "trigger": TRIGGERS["rank_surge"],
513
+ "periodStart": newest, "cause": m.get("rankCause") or "No sales rank was read."})
514
+ elif old.get("rank") is None:
515
+ if old.get("rankCause"):
516
+ checks.append({"term": term, "asin": asin, "trigger": TRIGGERS["rank_surge"],
517
+ "periodStart": newest,
518
+ "cause": f"The week before: {old['rankCause']}"})
519
+ elif m["rank"] <= old["rank"] * (1 - surge):
520
+ found(asin, "rank_surge", {"rank": m["rank"], "previousRank": old["rank"]},
521
+ asin_cause(asin))
522
+
523
+ owner = conf["defaultOwner"]
524
+ created = []
525
+
526
+ def _alerts(doc):
527
+ doc = doc if isinstance(doc, dict) else {}
528
+ doc.setdefault("seq", 0)
529
+ items = doc.setdefault("items", {})
530
+ latest = {}
531
+ for alert in sorted(items.values(), key=lambda a: int(str(a.get("id", "a0"))[1:] or 0)):
532
+ latest[(alert.get("term"), alert.get("asin"), alert.get("triggerKey"))] = alert
533
+ for hit in raised:
534
+ key = (hit["term"], hit["asin"], hit["trigger"])
535
+ if key in latest and latest[key].get("status") in HOLDING:
536
+ continue
537
+ doc["seq"] += 1
538
+ aid = f"a{doc['seq']}"
539
+ alert = {"id": aid, "term": hit["term"], "asin": hit["asin"], "trigger": TRIGGERS[hit["trigger"]],
540
+ "triggerKey": hit["trigger"], "periodStart": hit["periodStart"],
541
+ "periodEnd": hit["periodEnd"], "previousPeriodStart": hit["previousPeriodStart"],
542
+ "detail": hit["detail"], "cause": hit["cause"], "owner": owner, "status": "Open",
543
+ "due": (now.date() + dt.timedelta(days=DUE_DAYS)).isoformat(),
544
+ "createdAt": _stamp(now), "updatedAt": _stamp(now), "updatedBy": "system",
545
+ "history": [{"at": _stamp(now), "by": "system", "event": "created"}]}
546
+ items[aid] = alert
547
+ latest[key] = alert
548
+ created.append(aid)
549
+ doc["checks"] = [c for c in doc.get("checks") or () if c.get("periodStart") != newest] + checks
550
+ return doc
551
+ if raised or checks:
552
+ st.update(KEY_ALERTS, _alerts)
553
+
554
+ ready = previous is not None
555
+
556
+ def _weeks(doc):
557
+ doc = doc if isinstance(doc, dict) else {}
558
+ doc.setdefault("metrics", {})[newest] = metrics
559
+ doc["last_compared"] = newest
560
+ doc["comparison"] = {"ready": ready, "message": None if ready else NOT_READY,
561
+ "periodStart": newest, "previousPeriodStart": previous,
562
+ "comparedAt": _stamp(now), "alertsRaised": len(created),
563
+ "checks": len(checks)}
564
+ doc.pop("last_error", None)
565
+ return doc
566
+ st.update(KEY_WEEKS, _weeks)
567
+ return {"state": "compared" if ready else "waiting", "period": newest, "previous": previous,
568
+ "created": created, "checks": checks}
569
+
570
+
571
+ # --------------------------------------------------------------------------- alerts
572
+
573
+ def alerts(tenant_key, *, status=None, st=None):
574
+ """Every alert, newest first, plus the newest week's check rows. No cap."""
575
+ st = _rt(tenant_key, st)
576
+ doc = _doc(st, KEY_ALERTS)
577
+ rows = [a for a in (doc.get("items") or {}).values() if status is None or a.get("status") == status]
578
+ rows.sort(key=lambda a: int(str(a.get("id", "a0"))[1:] or 0), reverse=True)
579
+ return {"alerts": rows, "checks": list(doc.get("checks") or ()), "statuses": list(STATUSES)}
580
+
581
+
582
+ def update_alert(tenant_key, alert_id, *, owner=None, status=None, due=None, user="system", st=None):
583
+ """Reassign, move status, or move the due date of one alert. Returns the alert."""
584
+ if status is not None and status not in STATUSES:
585
+ raise ValueError("Status must be one of: " + ", ".join(STATUSES) + ".")
586
+ if due is not None:
587
+ try:
588
+ due = dt.date.fromisoformat(str(due)).isoformat()
589
+ except ValueError:
590
+ raise ValueError("Due must be a date such as 2026-10-27.") from None
591
+ if owner is not None and not str(owner).strip():
592
+ raise ValueError("Owner cannot be empty.")
593
+ st = _rt(tenant_key, st)
594
+ out = {}
595
+
596
+ def _apply(doc):
597
+ doc = doc if isinstance(doc, dict) else {}
598
+ alert = (doc.get("items") or {}).get(alert_id)
599
+ if not alert:
600
+ return doc
601
+ at = _stamp(_now())
602
+ event = {"at": at, "by": user}
603
+ if owner is not None:
604
+ alert["owner"] = event["owner"] = str(owner).strip()
605
+ if status is not None:
606
+ alert["status"] = event["status"] = status
607
+ if due is not None:
608
+ alert["due"] = event["due"] = due
609
+ alert["updatedAt"], alert["updatedBy"] = at, user
610
+ alert.setdefault("history", []).append(event)
611
+ out["alert"] = dict(alert)
612
+ return doc
613
+ st.update(KEY_ALERTS, _apply)
614
+ if "alert" not in out:
615
+ raise KeyError(alert_id)
616
+ return out["alert"]
617
+
618
+
619
+ # --------------------------------------------------------------------------- term detail
620
+
621
+ def term_detail(tenant_key, term, *, st=None):
622
+ """One term's held periods, the newest top 3 with week-over-week change, and the click share trend."""
623
+ st = _rt(tenant_key, st)
624
+ key = _norm(term)
625
+ with _reader(tenant_key, st) as cur:
626
+ sqp = _sqp(cur) if cur is not None else []
627
+ ours = _our_asins(cur, sqp) if cur is not None else set()
628
+ weeks_held = _top3(cur, [key]).get(key, {})
629
+ periods = sorted(weeks_held, reverse=True)
630
+ weeks = _doc(st, KEY_WEEKS)
631
+ top3 = []
632
+ if periods:
633
+ newest = weeks_held[periods[0]]["rows"]
634
+ before = weeks_held[periods[1]]["rows"] if len(periods) > 1 else None
635
+ metric = (weeks.get("metrics") or {}).get(periods[0]) or {}
636
+ for asin, (rank, share, conv) in sorted(newest.items(), key=lambda kv: kv[1][0]):
637
+ change = None
638
+ if before is not None:
639
+ if asin not in before:
640
+ change = {"kind": "new", "previousRank": None, "clickShareDelta": None,
641
+ "conversionShareDelta": None}
642
+ else:
643
+ r0, s0, c0 = before[asin]
644
+ change = {"kind": "up" if rank < r0 else "down" if rank > r0 else "same",
645
+ "previousRank": r0,
646
+ "clickShareDelta": None if share is None or s0 is None else share - s0,
647
+ "conversionShareDelta": None if conv is None or c0 is None else conv - c0}
648
+ m = metric.get(asin) or {}
649
+ top3.append({"asin": asin, "rank": rank, "clickShare": share, "conversionShare": conv,
650
+ "isOurs": asin in ours, "change": change, "buyBoxPrice": m.get("price"),
651
+ "currency": m.get("currency"), "salesRank": m.get("rank"),
652
+ "priceCause": m.get("priceCause"), "rankCause": m.get("rankCause")})
653
+ every = sorted({a for p in periods for a in weeks_held[p]["rows"]})
654
+ trend = [{"asin": a, "isOurs": a in ours,
655
+ "clickShare": [(weeks_held[p]["rows"].get(a) or (None, None, None))[1]
656
+ if a in weeks_held[p]["rows"] else None for p in periods]} for a in every]
657
+ state = weeks.get("comparison") or {}
658
+ ready = len(periods) > 1 and bool(state.get("ready", True))
659
+ return {"term": key, "periods": periods, "top3": top3, "trend": trend,
660
+ "comparison": {"ready": ready, "message": None if ready else NOT_READY}}
web/public/AIOS_DEPLOY_RECEIPT CHANGED
@@ -1 +1 @@
1
- ab085f5030f792659e50e3d9b8cdcdf43af11c641476d39a9f37295134cbeb7d
 
1
+ 26b2b98342f6ecb0f85cab3bd8844f79c1b1d0b2fc0881389ce4e0d8041bec4d
web/public/brand/SOURCES.md CHANGED
@@ -48,6 +48,7 @@ hand-drawn set was built for.
48
  | `shopify` | `shopify.png` | https://www.shopify.com/brand-assets | `shopify-shopping-bag.zip` → `02 - Glyph/png/shopify_glyph.png` (600×683) | trim + fit only |
49
  | `amazon` | `amazon.svg` | the approved lowercase `a` and smile supplied for W58-T08 (owner instruction 19) | vector, no raster cut needed | none — shipped as the vendor SVG. **Its geometry is digest-pinned** in `src/connectors/_directory_render.cjs`, which asserts the served file and `brandMarks.tsx`'s inline fallback are the same artwork |
50
  | `whatsapp` | `whatsapp.svg` | https://www.meta.com/brand/resources/whatsapp/whatsapp-brand/ | Official `WhatsApp-Brand-Resource-Center.zip`, `01_Glyph/01_Digital RGB/03_SVG/Digital_Glyph_Green_RGB_2026.svg`, downloaded from the page's Meta-controlled fbcdn.net link on 2026-10-09 | unchanged vendor artwork; only a final newline added. Archive SVG SHA-256 `f7b1311db718533e671645f57cd94b92f0e006e61d7e6581a80675fc5a478fc4`; repository file `46d8d8acf2cf2bee7618db0924c6b53329cd70c919e763e7c77f0c12d03b53be` |
 
51
 
52
  ## S72-T47 terms checked on 2026-10-09
53
 
 
48
  | `shopify` | `shopify.png` | https://www.shopify.com/brand-assets | `shopify-shopping-bag.zip` → `02 - Glyph/png/shopify_glyph.png` (600×683) | trim + fit only |
49
  | `amazon` | `amazon.svg` | the approved lowercase `a` and smile supplied for W58-T08 (owner instruction 19) | vector, no raster cut needed | none — shipped as the vendor SVG. **Its geometry is digest-pinned** in `src/connectors/_directory_render.cjs`, which asserts the served file and `brandMarks.tsx`'s inline fallback are the same artwork |
50
  | `whatsapp` | `whatsapp.svg` | https://www.meta.com/brand/resources/whatsapp/whatsapp-brand/ | Official `WhatsApp-Brand-Resource-Center.zip`, `01_Glyph/01_Digital RGB/03_SVG/Digital_Glyph_Green_RGB_2026.svg`, downloaded from the page's Meta-controlled fbcdn.net link on 2026-10-09 | unchanged vendor artwork; only a final newline added. Archive SVG SHA-256 `f7b1311db718533e671645f57cd94b92f0e006e61d7e6581a80675fc5a478fc4`; repository file `46d8d8acf2cf2bee7618db0924c6b53329cd70c919e763e7c77f0c12d03b53be` |
51
+ | `google-maps` | `google-maps.svg` | Google product branding on www.gstatic.com (S78-T09) | `https://www.gstatic.com/images/branding/productlogos/maps/v7/192px.svg`, fetched 2026-10-20 | uncut, served as a static file. The hyphen keeps it outside `routes_brand._KEY_RE`, so the connector brand door and `verify_meta` parity never list it |
52
 
53
  ## S72-T47 terms checked on 2026-10-09
54
 
web/public/brand/google-maps.svg ADDED
web/s71_frontend_contracts.py CHANGED
@@ -15,7 +15,10 @@ def catalog_host_faults(grid: str, loader: str, map_view: str, catalog: str) ->
15
  "only registry Routing owns Routes": 'resolvedApplicationMatches && applicationTemplateSurface(resolvedApplication) === "route"' in grid,
16
  "Catalog has no route event listener": bool(re.search(r'useEffect\(\(\) => \{\s*if \(!routeApplicationSurface\) return;\s*const openRoute', grid)),
17
  "cold App lookup precedes row admission": grid.find('const addressedDefinition') < grid.find('} = useCustomerData(scope,')
18
- and 'const legacyRowsEnabled = !isCatalogApplication && (!isApplicationSurface || !!addressedDefinition)' in grid
 
 
 
19
  and 'rowsEnabled: legacyRowsEnabled' in grid,
20
  "Catalog disables legacy rows and subscriptions": 'options.rowsEnabled === false ? EMPTY_APPLICATION_PAYLOAD' in loader
21
  and 'const suppliedPayload = embeddedPayload !== undefined' in loader
 
15
  "only registry Routing owns Routes": 'resolvedApplicationMatches && applicationTemplateSurface(resolvedApplication) === "route"' in grid,
16
  "Catalog has no route event listener": bool(re.search(r'useEffect\(\(\) => \{\s*if \(!routeApplicationSurface\) return;\s*const openRoute', grid)),
17
  "cold App lookup precedes row admission": grid.find('const addressedDefinition') < grid.find('} = useCustomerData(scope,')
18
+ # S78-T17 (C4): a Competitor watch App also reads no source rows.
19
+ and bool(re.search(r'const legacyRowsEnabled = !isCatalogApplication && '
20
+ r'(?:!isCompetitorWatchApplication &&\s+)?'
21
+ r'\(!isApplicationSurface \|\| !!addressedDefinition\)', grid))
22
  and 'rowsEnabled: legacyRowsEnabled' in grid,
23
  "Catalog disables legacy rows and subscriptions": 'options.rowsEnabled === false ? EMPTY_APPLICATION_PAYLOAD' in loader
24
  and 'const suppliedPayload = embeddedPayload !== undefined' in loader
web/src/apps/competitor-watch/CompetitorWatchView.tsx ADDED
@@ -0,0 +1,485 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { lazy, Suspense, useCallback, useEffect, useMemo, useRef, useState } from "react";
2
+ import type { FormEvent } from "react";
3
+ import type { TopLevelSpec } from "vega-lite";
4
+ import { API_V1, CREDENTIALS } from "../../apiContract";
5
+ import { AppFrame } from "../../customer-grid/AppFrame";
6
+ import "../../styles/sdlc78/competitor-watch.css";
7
+
8
+ // S78-T17 (C4, R20): the Competitor watch App. Reads and writes go through the competitor watch
9
+ // routes with the App id, so the server applies may_read and may_edit to this App record.
10
+ const VegaLiteChart = lazy(() => import("../../viz/vega/VegaLiteChart"));
11
+
12
+ /** R19: the six alert statuses, in this order. */
13
+ export const COMPETITOR_WATCH_STATUSES = [
14
+ "Open", "Repriced", "Ads changed", "Listing improved", "Watching", "Ignore",
15
+ ] as const;
16
+
17
+ /** Series slots read existing tokens; slot 0 is always our ASIN (validated palette, adjacent pairs). */
18
+ const SERIES_TOKENS = ["--lp-blue-solid", "--lp-orange-deep", "--lp-teal-deep", "--lp-purple-deep"];
19
+ const SERIES_SHAPES = ["circle", "square", "triangle-up", "diamond"];
20
+
21
+ export interface CompetitorWatchApplication {
22
+ id: string;
23
+ name: string;
24
+ capabilities?: Record<string, boolean>;
25
+ }
26
+
27
+ interface Week { start: string; end: string }
28
+
29
+ interface RankedRow {
30
+ rank: number;
31
+ asin: string;
32
+ title?: string;
33
+ ours: boolean;
34
+ clickShare: number | null;
35
+ conversionShare: number | null;
36
+ previousRank: number | null;
37
+ previousClickShare: number | null;
38
+ previousConversionShare: number | null;
39
+ cause?: string;
40
+ }
41
+
42
+ interface TrendSeries {
43
+ asin: string;
44
+ ours: boolean;
45
+ points: { start: string; clickShare: number | null }[];
46
+ }
47
+
48
+ interface TermScreen {
49
+ canEdit: boolean;
50
+ terms: string[];
51
+ term: string | null;
52
+ week: Week | null;
53
+ previousWeek: Week | null;
54
+ comparisonReady: boolean;
55
+ comparisonMessage: string;
56
+ top3: RankedRow[];
57
+ trend: TrendSeries[];
58
+ problems: string[];
59
+ }
60
+
61
+ interface Alert {
62
+ id: string;
63
+ term: string;
64
+ asin: string;
65
+ trigger: string;
66
+ owner: string;
67
+ status: string;
68
+ due: string;
69
+ cause?: string;
70
+ }
71
+
72
+ interface Check { term: string; asin: string; trigger: string; cause: string }
73
+
74
+ interface AlertScreen { canEdit: boolean; alerts: Alert[]; checks: Check[] }
75
+
76
+ type Load<T> = { phase: "loading" } | { phase: "error"; message: string } | { phase: "ready"; value: T };
77
+
78
+ const text = (value: unknown) => (typeof value === "string" ? value : "");
79
+ const num = (value: unknown) => (typeof value === "number" && Number.isFinite(value) ? value : null);
80
+
81
+ async function readJson(response: Response, fallback: string): Promise<unknown> {
82
+ const body: unknown = await response.json().catch(() => null);
83
+ if (response.ok) return body;
84
+ const error = (body as { detail?: { error?: { message?: unknown } } } | null)?.detail?.error;
85
+ throw new Error(text(error?.message) || fallback);
86
+ }
87
+
88
+ function parseWeek(raw: unknown): Week | null {
89
+ const row = raw as { start?: unknown; end?: unknown } | null;
90
+ return row && text(row.start) && text(row.end) ? { start: text(row.start), end: text(row.end) } : null;
91
+ }
92
+
93
+ function parseTermScreen(raw: unknown): TermScreen {
94
+ const body = (raw ?? {}) as Record<string, unknown>;
95
+ const rows = Array.isArray(body.top3) ? body.top3 : [];
96
+ const trend = Array.isArray(body.trend) ? body.trend : [];
97
+ return {
98
+ canEdit: body.canEdit === true,
99
+ terms: Array.isArray(body.terms) ? body.terms.map(text).filter(Boolean) : [],
100
+ term: text(body.term) || null,
101
+ week: parseWeek(body.week),
102
+ previousWeek: parseWeek(body.previousWeek),
103
+ comparisonReady: body.comparisonReady === true,
104
+ comparisonMessage: text(body.comparisonMessage),
105
+ top3: rows.map((item) => {
106
+ const row = (item ?? {}) as Record<string, unknown>;
107
+ return {
108
+ rank: num(row.rank) ?? 0,
109
+ asin: text(row.asin),
110
+ title: text(row.title) || undefined,
111
+ ours: row.ours === true,
112
+ clickShare: num(row.clickShare),
113
+ conversionShare: num(row.conversionShare),
114
+ previousRank: num(row.previousRank),
115
+ previousClickShare: num(row.previousClickShare),
116
+ previousConversionShare: num(row.previousConversionShare),
117
+ cause: text(row.cause) || undefined,
118
+ };
119
+ }).filter((row) => row.asin),
120
+ trend: trend.map((item) => {
121
+ const series = (item ?? {}) as Record<string, unknown>;
122
+ const points = Array.isArray(series.points) ? series.points : [];
123
+ return {
124
+ asin: text(series.asin),
125
+ ours: series.ours === true,
126
+ points: points.map((point) => {
127
+ const row = (point ?? {}) as Record<string, unknown>;
128
+ return { start: text(row.start), clickShare: num(row.clickShare) };
129
+ }).filter((point) => point.start),
130
+ };
131
+ }).filter((series) => series.asin),
132
+ problems: Array.isArray(body.problems) ? body.problems.map(text).filter(Boolean) : [],
133
+ };
134
+ }
135
+
136
+ function parseAlerts(raw: unknown): AlertScreen {
137
+ const body = (raw ?? {}) as Record<string, unknown>;
138
+ const rows = Array.isArray(body.alerts) ? body.alerts : [];
139
+ const checks = Array.isArray(body.checks) ? body.checks : [];
140
+ return {
141
+ canEdit: body.canEdit === true,
142
+ alerts: rows.map((item) => parseAlert(item)).filter((row): row is Alert => row !== null),
143
+ checks: checks.map((item) => {
144
+ const row = (item ?? {}) as Record<string, unknown>;
145
+ return { term: text(row.term), asin: text(row.asin), trigger: text(row.trigger), cause: text(row.cause) };
146
+ }).filter((row) => row.cause),
147
+ };
148
+ }
149
+
150
+ function parseAlert(item: unknown): Alert | null {
151
+ const row = (item ?? {}) as Record<string, unknown>;
152
+ const id = text(row.id);
153
+ if (!id) return null;
154
+ return {
155
+ id, term: text(row.term), asin: text(row.asin), trigger: text(row.trigger),
156
+ owner: text(row.owner), status: text(row.status), due: text(row.due),
157
+ cause: text(row.cause) || undefined,
158
+ };
159
+ }
160
+
161
+ const shortDate = (iso: string) => {
162
+ const date = new Date(iso.length === 10 ? iso + "T00:00:00Z" : iso);
163
+ return Number.isNaN(date.getTime()) ? iso
164
+ : date.toLocaleDateString(undefined, { month: "short", day: "numeric", timeZone: "UTC" });
165
+ };
166
+ const weekLabel = (week: Week) => `${shortDate(week.start)} to ${shortDate(week.end)}`;
167
+ const pct = (value: number | null) => (value === null ? "Not held" : `${value.toFixed(1)}%`);
168
+
169
+ /** The change chip copy: "New", "Up 1", "Down 2", "Same" for rank; "+1.2 pts" for a share. */
170
+ export function rankChange(rank: number, previous: number | null): { label: string; tone: "new" | "up" | "down" | "flat" } {
171
+ if (previous === null) return { label: "New", tone: "new" };
172
+ if (previous > rank) return { label: `Up ${previous - rank}`, tone: "up" };
173
+ if (previous < rank) return { label: `Down ${rank - previous}`, tone: "down" };
174
+ return { label: "Same", tone: "flat" };
175
+ }
176
+
177
+ export function shareChange(value: number | null, previous: number | null): { label: string; tone: "up" | "down" | "flat" } | null {
178
+ if (value === null || previous === null) return null;
179
+ const delta = Math.round((value - previous) * 10) / 10;
180
+ if (delta > 0) return { label: `+${delta.toFixed(1)} pts`, tone: "up" };
181
+ if (delta < 0) return { label: `-${Math.abs(delta).toFixed(1)} pts`, tone: "down" };
182
+ return { label: "0.0 pts", tone: "flat" };
183
+ }
184
+
185
+ function ChangeChip({ change }: { change: { label: string; tone: string } | null }) {
186
+ if (!change) return null;
187
+ return <span className={`cw-chip is-${change.tone}`}>{change.label}</span>;
188
+ }
189
+
190
+ function chartTokens() {
191
+ const style = getComputedStyle(document.documentElement);
192
+ const read = (token: string) => style.getPropertyValue(token).trim();
193
+ return { series: SERIES_TOKENS.map(read), line: read("--lp-line"), surface: read("--lp-surface"),
194
+ muted: read("--lp-muted") };
195
+ }
196
+
197
+ const seriesName = (series: { asin: string; ours: boolean }) => (series.ours ? `${series.asin} (You)` : series.asin);
198
+
199
+ function trendSpec(trend: TrendSeries[]): TopLevelSpec {
200
+ // Our ASIN takes slot 0; competitors keep the order the server ranked them in.
201
+ const ordered = [...trend.filter((row) => row.ours), ...trend.filter((row) => !row.ours)].slice(0, 4);
202
+ const domain = ordered.map(seriesName);
203
+ const values = ordered.flatMap((series) => series.points
204
+ .filter((point) => point.clickShare !== null)
205
+ .map((point) => ({ series: seriesName(series), week: point.start, share: point.clickShare })));
206
+ const lastPoints = domain.map((name) => values.filter((row) => row.series === name)
207
+ .sort((a, b) => a.week.localeCompare(b.week)).at(-1)).filter(Boolean);
208
+ const tokens = chartTokens();
209
+ const color = { field: "series", type: "nominal" as const, title: null,
210
+ scale: { domain, range: tokens.series.slice(0, domain.length) },
211
+ legend: { orient: "bottom" as const, symbolStrokeWidth: 2 } };
212
+ const x = { field: "week", type: "ordinal" as const, title: null, sort: "ascending" as const,
213
+ axis: { labelAngle: 0, labelExpr: "timeFormat(toDate(datum.value), '%b %-d')" } };
214
+ const y = { field: "share", type: "quantitative" as const, title: "Click share (%)",
215
+ axis: { gridColor: tokens.line, tickCount: 4 } };
216
+ return {
217
+ $schema: "https://vega.github.io/schema/vega-lite/v6.json",
218
+ width: "container",
219
+ height: 220,
220
+ autosize: { type: "fit", contains: "padding" },
221
+ background: "transparent",
222
+ config: { view: { stroke: null }, axis: { domain: false, ticks: false, labelFontSize: 11, titleFontSize: 11,
223
+ titleFontWeight: 500, labelColor: tokens.muted, titleColor: tokens.muted },
224
+ legend: { labelFontSize: 11, labelColor: tokens.muted }, font: "Inter" },
225
+ data: { values },
226
+ layer: [
227
+ { mark: { type: "line", strokeWidth: 2, interpolate: "monotone" }, encoding: { x, y, color } },
228
+ { mark: { type: "point", filled: true, size: 90, stroke: tokens.surface, strokeWidth: 1.5 },
229
+ encoding: { x, y, color,
230
+ shape: { field: "series", type: "nominal", scale: { domain, range: SERIES_SHAPES.slice(0, domain.length) } },
231
+ tooltip: [{ field: "series", title: "ASIN" }, { field: "week", title: "Week of" },
232
+ { field: "share", title: "Click share (%)", format: ".1f" }] } },
233
+ // Direct label at each line's last week, so identity is never colour alone.
234
+ { data: { values: lastPoints }, mark: { type: "text", align: "right", dy: -12, fontSize: 11,
235
+ color: tokens.muted }, encoding: { x, y, text: { field: "series" } } },
236
+ ],
237
+ } as TopLevelSpec;
238
+ }
239
+
240
+ function TrendChart({ trend }: { trend: TrendSeries[] }) {
241
+ const spec = useMemo(() => trendSpec(trend), [trend]);
242
+ const weeks = new Set(trend.flatMap((series) => series.points.map((point) => point.start)));
243
+ if (!trend.length) return null;
244
+ if (weeks.size < 2) return <p className="cw-note" role="status">The trend shows after two weeks.</p>;
245
+ return <Suspense fallback={<div className="cw-skeleton cw-skeleton-chart" aria-hidden="true" />}>
246
+ <VegaLiteChart spec={spec} label="Click share by week for each ASIN in this top 3" />
247
+ </Suspense>;
248
+ }
249
+
250
+ function RankedTable({ rows, compare }: { rows: RankedRow[]; compare: boolean }) {
251
+ // Before a second week is held there is nothing to compare, so no chip shows.
252
+ return <table className="cw-table cw-ranked">
253
+ <thead>
254
+ <tr><th scope="col">Rank</th><th scope="col">ASIN</th><th scope="col" className="is-num">Click share</th>
255
+ <th scope="col" className="is-num">Conversion share</th></tr>
256
+ </thead>
257
+ <tbody>
258
+ {rows.map((row) => <tr key={row.asin} className={row.ours ? "is-ours" : undefined}>
259
+ <td data-label="Rank"><span className="cw-rank">{row.rank}</span>
260
+ <ChangeChip change={compare ? rankChange(row.rank, row.previousRank) : null} /></td>
261
+ <td data-label="ASIN">
262
+ <span className="cw-asin">{row.asin}</span>
263
+ {row.ours && <span className="cw-you">You</span>}
264
+ {row.title && <span className="cw-title">{row.title}</span>}
265
+ {row.cause && <span className="cw-cause">{row.cause}</span>}
266
+ </td>
267
+ <td data-label="Click share" className="is-num">{pct(row.clickShare)}
268
+ <ChangeChip change={compare ? shareChange(row.clickShare, row.previousClickShare) : null} /></td>
269
+ <td data-label="Conversion share" className="is-num">{pct(row.conversionShare)}
270
+ <ChangeChip change={compare ? shareChange(row.conversionShare, row.previousConversionShare) : null} /></td>
271
+ </tr>)}
272
+ </tbody>
273
+ </table>;
274
+ }
275
+
276
+ function useAppQuery(appId: string) {
277
+ return useCallback((path: string, params: Record<string, string> = {}) => {
278
+ const query = new URLSearchParams({ app: appId, ...params });
279
+ return `${API_V1}/competitor-watch${path}?${query.toString()}`;
280
+ }, [appId]);
281
+ }
282
+
283
+ function TermsView({ appId, canEditApp }: { appId: string; canEditApp: boolean }) {
284
+ const url = useAppQuery(appId);
285
+ const [term, setTerm] = useState("");
286
+ const [state, setState] = useState<Load<TermScreen>>({ phase: "loading" });
287
+ const [attempt, setAttempt] = useState(0);
288
+ const [draft, setDraft] = useState("");
289
+ const [termError, setTermError] = useState("");
290
+ const [busy, setBusy] = useState(false);
291
+
292
+ useEffect(() => {
293
+ const controller = new AbortController();
294
+ setState({ phase: "loading" });
295
+ void fetch(url("/screen", term ? { term } : {}), { credentials: CREDENTIALS, signal: controller.signal })
296
+ .then((response) => readJson(response, "The competitor watch could not be loaded."))
297
+ .then((body) => { if (!controller.signal.aborted) setState({ phase: "ready", value: parseTermScreen(body) }); })
298
+ .catch((reason: unknown) => {
299
+ if (!controller.signal.aborted) setState({ phase: "error",
300
+ message: reason instanceof Error ? reason.message : "The competitor watch could not be loaded." });
301
+ });
302
+ return () => controller.abort();
303
+ }, [url, term, attempt]);
304
+
305
+ const screen = state.phase === "ready" ? state.value : null;
306
+ const canEdit = canEditApp && screen?.canEdit === true;
307
+ const selected = screen?.term ?? "";
308
+
309
+ const editTerms = async (action: "add" | "remove", value: string) => {
310
+ setBusy(true);
311
+ setTermError("");
312
+ try {
313
+ const response = await fetch(url(action === "add" ? "/terms" : "/terms/remove"), {
314
+ method: "POST", credentials: CREDENTIALS, headers: { "Content-Type": "application/json" },
315
+ body: JSON.stringify({ terms: [value] }),
316
+ });
317
+ await readJson(response, action === "add" ? "The term was not added." : "The term was not removed.");
318
+ setDraft("");
319
+ if (action === "add") setTerm(value.trim().toLowerCase());
320
+ else setTerm("");
321
+ setAttempt((count) => count + 1);
322
+ } catch (reason) {
323
+ setTermError(reason instanceof Error ? reason.message : "The term was not saved.");
324
+ } finally {
325
+ setBusy(false);
326
+ }
327
+ };
328
+ const submit = (event: FormEvent) => {
329
+ event.preventDefault();
330
+ if (draft.trim()) void editTerms("add", draft.trim());
331
+ };
332
+
333
+ return <div className="cw-view">
334
+ <div className="cw-filters" role="group" aria-label="Term and week">
335
+ <label className="cw-field">
336
+ <span className="cw-field-label">Search term</span>
337
+ <select className="cw-select" value={selected} disabled={!screen || !screen.terms.length}
338
+ onChange={(event) => setTerm(event.target.value)}>
339
+ {!screen?.terms.length && <option value="">No watched terms</option>}
340
+ {screen?.terms.map((option) => <option key={option} value={option}>{option}</option>)}
341
+ </select>
342
+ </label>
343
+ {screen?.week && <span className="cw-period">
344
+ Week of {weekLabel(screen.week)}{screen.previousWeek ? ` against ${weekLabel(screen.previousWeek)}` : ""}
345
+ </span>}
346
+ {canEdit && <form className="cw-term-form" onSubmit={submit}>
347
+ <input className="cw-input" value={draft} onChange={(event) => setDraft(event.target.value)}
348
+ placeholder="Add a term" aria-label="Add a search term" disabled={busy} />
349
+ <button type="submit" className="cw-button" disabled={busy || !draft.trim()}>Add</button>
350
+ {selected && <button type="button" className="cw-button is-quiet" disabled={busy}
351
+ onClick={() => void editTerms("remove", selected)}>Remove term</button>}
352
+ </form>}
353
+ </div>
354
+ {termError && <p className="cw-error" role="alert">{termError}</p>}
355
+ {state.phase === "loading" && <div className="cw-skeleton-rows" aria-busy="true" aria-label="Loading">
356
+ <div className="cw-skeleton" /><div className="cw-skeleton" /><div className="cw-skeleton" />
357
+ </div>}
358
+ {state.phase === "error" && <p className="cw-error" role="alert">{state.message}{" "}
359
+ <button type="button" className="cw-link" onClick={() => setAttempt((count) => count + 1)}>Retry</button></p>}
360
+ {screen && <>
361
+ {screen.problems.map((problem) => <p key={problem} className="cw-cause-line" role="status">{problem}</p>)}
362
+ {!screen.comparisonReady && <p className="cw-note" role="status">
363
+ {screen.comparisonMessage || "Comparison starts after the second weekly pull."}</p>}
364
+ {/* The trend sits beside the ranked list when both fit, and stacks below it when not. */}
365
+ <div className="cw-panels">
366
+ {screen.term && screen.top3.length > 0 && <section className="cw-section" aria-label="Top 3 this week">
367
+ <h2 className="cw-heading">Top 3 this week</h2>
368
+ <RankedTable rows={screen.top3} compare={screen.comparisonReady} />
369
+ </section>}
370
+ {screen.term && screen.top3.length === 0 && <p className="cw-note" role="status">No top 3 is held for this term yet.</p>}
371
+ {screen.trend.length > 0 && <section className="cw-section" aria-label="Trend">
372
+ <h2 className="cw-heading">Trend</h2>
373
+ <TrendChart trend={screen.trend} />
374
+ </section>}
375
+ </div>
376
+ </>}
377
+ </div>;
378
+ }
379
+
380
+ function AlertsView({ appId, canEditApp }: { appId: string; canEditApp: boolean }) {
381
+ const url = useAppQuery(appId);
382
+ const [state, setState] = useState<Load<AlertScreen>>({ phase: "loading" });
383
+ const [attempt, setAttempt] = useState(0);
384
+ const [saving, setSaving] = useState("");
385
+ const [rowError, setRowError] = useState<{ id: string; message: string } | null>(null);
386
+ const alive = useRef(true);
387
+ useEffect(() => () => { alive.current = false; }, []);
388
+
389
+ useEffect(() => {
390
+ const controller = new AbortController();
391
+ setState({ phase: "loading" });
392
+ void fetch(url("/alerts"), { credentials: CREDENTIALS, signal: controller.signal })
393
+ .then((response) => readJson(response, "Alerts could not be loaded."))
394
+ .then((body) => { if (!controller.signal.aborted) setState({ phase: "ready", value: parseAlerts(body) }); })
395
+ .catch((reason: unknown) => {
396
+ if (!controller.signal.aborted) setState({ phase: "error",
397
+ message: reason instanceof Error ? reason.message : "Alerts could not be loaded." });
398
+ });
399
+ return () => controller.abort();
400
+ }, [url, attempt]);
401
+
402
+ const setStatus = async (alert: Alert, status: string) => {
403
+ setSaving(alert.id);
404
+ setRowError(null);
405
+ try {
406
+ const response = await fetch(url(`/alerts/${encodeURIComponent(alert.id)}`), {
407
+ method: "PATCH", credentials: CREDENTIALS, headers: { "Content-Type": "application/json" },
408
+ body: JSON.stringify({ status }),
409
+ });
410
+ // The route answers with the saved alert itself.
411
+ const body = await readJson(response, "The status was not saved.") as { alert?: unknown } | null;
412
+ const saved = parseAlert(body?.alert ?? body);
413
+ if (!alive.current) return;
414
+ setState((current) => current.phase !== "ready" ? current : { phase: "ready", value: {
415
+ ...current.value,
416
+ alerts: current.value.alerts.map((row) => row.id === alert.id ? (saved ?? { ...row, status }) : row),
417
+ } });
418
+ } catch (reason) {
419
+ if (alive.current) setRowError({ id: alert.id,
420
+ message: reason instanceof Error ? reason.message : "The status was not saved." });
421
+ } finally {
422
+ if (alive.current) setSaving("");
423
+ }
424
+ };
425
+
426
+ if (state.phase === "loading") return <div className="cw-skeleton-rows" aria-busy="true" aria-label="Loading">
427
+ <div className="cw-skeleton" /><div className="cw-skeleton" /><div className="cw-skeleton" />
428
+ </div>;
429
+ if (state.phase === "error") return <p className="cw-error" role="alert">{state.message}{" "}
430
+ <button type="button" className="cw-link" onClick={() => setAttempt((count) => count + 1)}>Retry</button></p>;
431
+ const { alerts, checks } = state.value;
432
+ const canEdit = canEditApp && state.value.canEdit;
433
+ const notChecked = checks.length > 0 && <section className="cw-section" aria-label="Not checked">
434
+ <h2 className="cw-heading">Not checked</h2>
435
+ <ul className="cw-checks">
436
+ {checks.map((check, index) => <li key={`${check.term}:${check.asin}:${check.trigger}:${index}`}>
437
+ <span className="cw-check-what">{[check.term, check.asin, check.trigger].filter(Boolean).join(", ")}</span>
438
+ <span className="cw-cause">{check.cause}</span>
439
+ </li>)}
440
+ </ul>
441
+ </section>;
442
+ if (!alerts.length) return <div className="cw-view"><p className="cw-note" role="status">No alerts yet.</p>{notChecked}</div>;
443
+ return <div className="cw-view"><table className="cw-table cw-alerts">
444
+ <thead>
445
+ <tr><th scope="col">Term</th><th scope="col">ASIN</th><th scope="col">Trigger</th><th scope="col">Owner</th>
446
+ <th scope="col">Status</th><th scope="col">Due</th></tr>
447
+ </thead>
448
+ <tbody>
449
+ {alerts.map((alert) => <tr key={alert.id}>
450
+ <td data-label="Term">{alert.term}</td>
451
+ <td data-label="ASIN"><span className="cw-asin">{alert.asin}</span></td>
452
+ <td data-label="Trigger">{alert.trigger}
453
+ {alert.cause && <span className="cw-cause">{alert.cause}</span>}</td>
454
+ <td data-label="Owner">{alert.owner}</td>
455
+ <td data-label="Status">
456
+ {canEdit ? <select className="cw-select" value={alert.status} disabled={saving === alert.id}
457
+ aria-label={`Status for ${alert.asin} on ${alert.term}`}
458
+ onChange={(event) => void setStatus(alert, event.target.value)}>
459
+ {COMPETITOR_WATCH_STATUSES.map((status) => <option key={status} value={status}>{status}</option>)}
460
+ </select> : <span className="cw-status">{alert.status}</span>}
461
+ {rowError?.id === alert.id && <span className="cw-cause" role="alert">{rowError.message}</span>}
462
+ </td>
463
+ <td data-label="Due" className="is-num">{alert.due ? shortDate(alert.due) : "Not set"}</td>
464
+ </tr>)}
465
+ </tbody>
466
+ </table>{notChecked}</div>;
467
+ }
468
+
469
+ export default function CompetitorWatchView({ application }: { application: CompetitorWatchApplication }) {
470
+ const [tab, setTab] = useState<"terms" | "alerts">("terms");
471
+ const canEditApp = application.capabilities?.edit === true;
472
+ const tabs = [["terms", "Terms"], ["alerts", "Alerts"]] as const;
473
+ return <div className="cw-app">
474
+ <AppFrame appName={application.name} actions={<div className="cw-tabs" role="tablist" aria-label="Competitor watch">
475
+ {tabs.map(([key, label]) => <button key={key} type="button" role="tab" aria-selected={tab === key}
476
+ className={tab === key ? "cw-tab is-active" : "cw-tab"} onClick={() => setTab(key)}>{label}</button>)}
477
+ </div>}>
478
+ <div className="cw-body" role="tabpanel" aria-label={tab === "terms" ? "Terms" : "Alerts"}>
479
+ {tab === "terms"
480
+ ? <TermsView appId={application.id} canEditApp={canEditApp} />
481
+ : <AlertsView appId={application.id} canEditApp={canEditApp} />}
482
+ </div>
483
+ </AppFrame>
484
+ </div>;
485
+ }
web/src/customer-grid/AmazonPeriodPicker.tsx ADDED
@@ -0,0 +1,82 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { useCallback, useEffect, useState } from "react";
2
+ import { API_V1, CREDENTIALS, ROWS_STALE_EVENT, signal } from "../apiContract";
3
+ import { clearTopicRowsCache, dropTableRowsCache, refusalMessage } from "./apiBridge";
4
+ import "./amazonPeriodPicker.css";
5
+
6
+ /** The table the period picker belongs to. Every other database renders nothing. */
7
+ export const AMAZON_PROFIT_TABLE = "ut_amazon_sku_profit";
8
+
9
+ type PeriodChoice = { key: string; label: string };
10
+ type ProfitStatus = {
11
+ period: { key: string; label: string };
12
+ periods: PeriodChoice[];
13
+ canEdit: boolean;
14
+ refusal: string | null;
15
+ };
16
+
17
+ /** Period picker for Amazon SKU profit: switching it recomputes every row on the server, keeps
18
+ * every owned cell, then re-reads this grid's rows. A viewer sees the period and cannot change it. */
19
+ export default function AmazonPeriodPicker({ database }: { database: string }) {
20
+ const [status, setStatus] = useState<ProfitStatus | null>(null);
21
+ const [busy, setBusy] = useState(false);
22
+ const [message, setMessage] = useState<string | null>(null);
23
+ const active = database === AMAZON_PROFIT_TABLE;
24
+
25
+ const load = useCallback(async () => {
26
+ const res = await fetch(`${API_V1}/amazon-profit`, { credentials: CREDENTIALS });
27
+ if (!res.ok) return;
28
+ setStatus((await res.json()) as ProfitStatus);
29
+ }, []);
30
+
31
+ useEffect(() => {
32
+ if (active) void load();
33
+ }, [active, load]);
34
+
35
+ if (!active || !status) return null;
36
+
37
+ const choose = async (key: string) => {
38
+ setBusy(true);
39
+ setMessage(null);
40
+ try {
41
+ const res = await fetch(`${API_V1}/amazon-profit/period`, {
42
+ method: "POST", credentials: CREDENTIALS,
43
+ headers: { "Content-Type": "application/json" },
44
+ body: JSON.stringify({ period: key }),
45
+ });
46
+ if (!res.ok) {
47
+ const body: unknown = await res.json().catch(() => null);
48
+ setMessage(refusalMessage(body, res.status, "The period did not change. Try again."));
49
+ }
50
+ // A refused tie still rewrote the rows (blank figures, the refusal in Period), so re-read.
51
+ clearTopicRowsCache(`tables/${AMAZON_PROFIT_TABLE}/rows`);
52
+ dropTableRowsCache(AMAZON_PROFIT_TABLE);
53
+ signal(ROWS_STALE_EVENT);
54
+ await load();
55
+ } finally {
56
+ setBusy(false);
57
+ }
58
+ };
59
+
60
+ const choices = status.periods.some((p) => p.key === status.period.key)
61
+ ? status.periods : [{ key: status.period.key, label: status.period.label }, ...status.periods];
62
+ const note = message ?? status.refusal;
63
+ return (
64
+ <div className="cg-period-picker" data-testid="amazon-period-picker">
65
+ <label>
66
+ <span>Period</span>
67
+ <select
68
+ className="cg-select"
69
+ aria-label="Period"
70
+ value={status.period.key}
71
+ disabled={!status.canEdit || busy}
72
+ title={status.canEdit ? undefined : "Only an editor can change the period."}
73
+ onChange={(event) => void choose(event.target.value)}
74
+ >
75
+ {choices.map((p) => <option key={p.key} value={p.key}>{p.label}</option>)}
76
+ </select>
77
+ </label>
78
+ {busy && <span className="cg-period-busy">Updating</span>}
79
+ {note && <span className="cg-period-note" role="status">{note}</span>}
80
+ </div>
81
+ );
82
+ }
web/src/customer-grid/CustomerGrid.tsx CHANGED
@@ -86,6 +86,7 @@ import { useGetCellContent } from "./useGetCellContent";
86
  import type { GroupRowPlaceholder } from "./useGetCellContent";
87
  import { useGridSelection } from "./useGridSelection";
88
  import Toolbar from "./Toolbar";
 
89
  import { DatePicker } from "./DatePicker";
90
  /**
91
  * ⭐⭐ W51-T03 / OWNER RULING R6 + CONTRACT C8 — THE ONE CONFIRM DIALOG, for every destructive
@@ -175,7 +176,7 @@ import type { ShowAs, SummaryChoice, SummaryMap } from "./types";
175
  import type { FieldStamps } from "./optimism";
176
  import { evalFormula, orderFormulas, parseFormula } from "./formulaEngine";
177
  import type { FormulaAst } from "./formulaEngine";
178
- import { applicationTemplateSurface, CalendarSettings, CalendarView, KanbanView, ListView, MapSettings, ModeSwitch, TimelineSettings } from "./viewModes";
179
  import { SwipeView } from "./SwipeView";
180
  import type { SwipeSpec } from "./SwipeView";
181
  // The chart engine lives in `viz/` since EXIT wave 2 (W2-5/Y3) — the grid is now
@@ -2713,8 +2714,11 @@ function CustomerGridSurface({
2713
  ? addressedApplication.application : null;
2714
  const isCatalogApplication = applicationTemplateSurface(addressedDefinition) === "catalog" ||
2715
  (resolvedApplicationMatches && applicationTemplateSurface(resolvedApplication) === "catalog");
 
 
2716
  // Resolve the registry before allowing an App to use an ordinary row reader.
2717
- const legacyRowsEnabled = !isCatalogApplication && (!isApplicationSurface || !!addressedDefinition);
 
2718
  const catalogReadKey = addressedApplicationKey || applicationRefKey;
2719
  const [catalogRead, setCatalogRead] = useState<{ key: string; fields: Field[]; rows: Row[] }>(
2720
  { key: "", fields: [], rows: [] });
@@ -11286,6 +11290,10 @@ function CustomerGridSurface({
11286
  />
11287
  ) : null;
11288
 
 
 
 
 
11289
  return (
11290
  // `data-today` is the TENANT'S day, exactly as the payload delivered it. It is here so the
11291
  // date every relative condition resolves against is OBSERVABLE rather than inferred: a live
@@ -11722,6 +11730,7 @@ function CustomerGridSurface({
11722
  </span>
11723
  )}
11724
  {!routeApplicationSurface && primaryToolbar}
 
11725
  </div>
11726
  {/* ⭐ R11's SECOND ROW — live, on the pivoted database. It renders only once the pivot has
11727
  actually been SERVED, which is the house posture for a control whose other half may
 
86
  import type { GroupRowPlaceholder } from "./useGetCellContent";
87
  import { useGridSelection } from "./useGridSelection";
88
  import Toolbar from "./Toolbar";
89
+ import AmazonPeriodPicker from "./AmazonPeriodPicker";
90
  import { DatePicker } from "./DatePicker";
91
  /**
92
  * ⭐⭐ W51-T03 / OWNER RULING R6 + CONTRACT C8 — THE ONE CONFIRM DIALOG, for every destructive
 
176
  import type { FieldStamps } from "./optimism";
177
  import { evalFormula, orderFormulas, parseFormula } from "./formulaEngine";
178
  import type { FormulaAst } from "./formulaEngine";
179
+ import { applicationTemplateSurface, CalendarSettings, CalendarView, KanbanView, ListView, MapSettings, ModeSwitch, TemplateApplicationView, TimelineSettings } from "./viewModes";
180
  import { SwipeView } from "./SwipeView";
181
  import type { SwipeSpec } from "./SwipeView";
182
  // The chart engine lives in `viz/` since EXIT wave 2 (W2-5/Y3) — the grid is now
 
2714
  ? addressedApplication.application : null;
2715
  const isCatalogApplication = applicationTemplateSurface(addressedDefinition) === "catalog" ||
2716
  (resolvedApplicationMatches && applicationTemplateSurface(resolvedApplication) === "catalog");
2717
+ // S78-T17 (C4): a Competitor watch App reads its own routes, never the source database rows.
2718
+ const isCompetitorWatchApplication = applicationTemplateSurface(addressedDefinition) === "competitor_watch";
2719
  // Resolve the registry before allowing an App to use an ordinary row reader.
2720
+ const legacyRowsEnabled = !isCatalogApplication && !isCompetitorWatchApplication &&
2721
+ (!isApplicationSurface || !!addressedDefinition);
2722
  const catalogReadKey = addressedApplicationKey || applicationRefKey;
2723
  const [catalogRead, setCatalogRead] = useState<{ key: string; fields: Field[]; rows: Row[] }>(
2724
  { key: "", fields: [], rows: [] });
 
11290
  />
11291
  ) : null;
11292
 
11293
+ if (isCompetitorWatchApplication && addressedDefinition) {
11294
+ return <TemplateApplicationView application={addressedDefinition} />;
11295
+ }
11296
+
11297
  return (
11298
  // `data-today` is the TENANT'S day, exactly as the payload delivered it. It is here so the
11299
  // date every relative condition resolves against is OBSERVABLE rather than inferred: a live
 
11730
  </span>
11731
  )}
11732
  {!routeApplicationSurface && primaryToolbar}
11733
+ {!routeApplicationSurface && <AmazonPeriodPicker database={applicationDatabase} />}
11734
  </div>
11735
  {/* ⭐ R11's SECOND ROW — live, on the pivoted database. It renders only once the pivot has
11736
  actually been SERVED, which is the house posture for a control whose other half may
web/src/customer-grid/DeliveryPhotos.tsx ADDED
@@ -0,0 +1,138 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // customer-grid / DeliveryPhotos.tsx
2
+ // S78-T14 (contract C5): the proof-of-delivery photos of one Odoo picking, in the record drawer.
3
+ // No photos renders nothing. Loading renders nothing. A failed load says so in one sentence.
4
+ // The photo bytes come from the server, which checks the delivery read wall on every request.
5
+
6
+ import { useEffect, useId, useRef, useState } from "react";
7
+ import { BodyPortal, useOverlayLayer } from "./OverlaySurface";
8
+ import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal } from "../apiContract";
9
+
10
+ /** The databases whose row id is a `stock.picking` id. Mirrors `odoo_relational.DELIVERY_KEYS`. */
11
+ export const DELIVERY_SCOPES: ReadonlySet<string> = new Set(["ut_odoo_shipments", "ut_odoo_pickings"]);
12
+
13
+ export interface DeliveryPhoto {
14
+ id: number;
15
+ name: string;
16
+ mimetype: string;
17
+ url: string;
18
+ }
19
+
20
+ type Load =
21
+ | { status: "loading" }
22
+ | { status: "ok"; photos: DeliveryPhoto[] }
23
+ | { status: "error"; message: string };
24
+
25
+ const LOAD_FAILED = "Delivery photos could not load. Reopen the record to try again.";
26
+
27
+ function readPhotos(body: unknown): DeliveryPhoto[] | null {
28
+ if (!Array.isArray(body)) return null;
29
+ const photos: DeliveryPhoto[] = [];
30
+ for (const row of body) {
31
+ const item = row as Partial<DeliveryPhoto> | null;
32
+ if (!item || typeof item.id !== "number" || typeof item.url !== "string") return null;
33
+ photos.push({ id: item.id, name: String(item.name ?? ""), mimetype: String(item.mimetype ?? ""),
34
+ url: item.url });
35
+ }
36
+ return photos;
37
+ }
38
+
39
+ function PhotoView({ photo, index, count, onClose }: {
40
+ photo: DeliveryPhoto; index: number; count: number; onClose: () => void;
41
+ }) {
42
+ const panelRef = useRef<HTMLDivElement>(null);
43
+ const titleId = useId();
44
+ const [shown, setShown] = useState(false);
45
+ useOverlayLayer({ panelRef, onDismiss: onClose, dismissOnOutside: false,
46
+ initialFocus: "first", restoreFocus: true, trapFocus: true });
47
+ useEffect(() => {
48
+ const frame = window.requestAnimationFrame(() => setShown(true));
49
+ return () => window.cancelAnimationFrame(frame);
50
+ }, []);
51
+ const label = `Delivery photo ${index + 1} of ${count}`;
52
+ return (
53
+ <BodyPortal>
54
+ <div className="lp-dialog-scrim">
55
+ <div ref={panelRef} className="lp-dialog" role="dialog" aria-modal="true"
56
+ aria-labelledby={titleId}
57
+ style={{ width: "min(960px, calc(100vw - 32px))", opacity: shown ? 1 : 0,
58
+ transition: "opacity 120ms ease-out" }}>
59
+ <div className="lp-dialog-head">
60
+ <h2 id={titleId} className="lp-dialog-title">{label}</h2>
61
+ <button type="button" className="lp-dialog-x" aria-label="Close photo" onClick={onClose}>×</button>
62
+ </div>
63
+ <img src={photo.url} alt={label}
64
+ style={{ display: "block", maxWidth: "100%", maxHeight: "calc(100vh - 140px)",
65
+ margin: "0 auto", objectFit: "contain" }} />
66
+ </div>
67
+ </div>
68
+ </BodyPortal>
69
+ );
70
+ }
71
+
72
+ export function DeliveryPhotos({ scope, pid }: { scope: string; pid: number }) {
73
+ const [load, setLoad] = useState<Load>({ status: "loading" });
74
+ const [open, setOpen] = useState<number | null>(null);
75
+
76
+ useEffect(() => {
77
+ if (!Number.isInteger(pid) || pid <= 0) {
78
+ setLoad({ status: "ok", photos: [] });
79
+ return;
80
+ }
81
+ const ctrl = new AbortController();
82
+ setLoad({ status: "loading" });
83
+ setOpen(null);
84
+ (async () => {
85
+ try {
86
+ const res = await fetch(`${API_V1}/odoo/deliveries/${pid}/photos`, {
87
+ credentials: CREDENTIALS, signal: ctrl.signal,
88
+ });
89
+ if (checkTenant(res)) return;
90
+ if (res.status === 401) {
91
+ signal(UNAUTHORIZED_EVENT);
92
+ return;
93
+ }
94
+ let body: unknown = null;
95
+ try { body = await res.json(); } catch { body = null; }
96
+ if (ctrl.signal.aborted) return;
97
+ if (!res.ok) {
98
+ const message = (body as { error?: { message?: unknown } } | null)?.error?.message;
99
+ setLoad({ status: "error", message: typeof message === "string" && message ? message : LOAD_FAILED });
100
+ return;
101
+ }
102
+ const photos = readPhotos(body);
103
+ setLoad(photos ? { status: "ok", photos } : { status: "error", message: LOAD_FAILED });
104
+ } catch {
105
+ if (!ctrl.signal.aborted) setLoad({ status: "error", message: LOAD_FAILED });
106
+ }
107
+ })();
108
+ return () => ctrl.abort();
109
+ }, [scope, pid]);
110
+
111
+ if (load.status === "loading") return null;
112
+ if (load.status === "ok" && load.photos.length === 0) return null;
113
+ const photos = load.status === "ok" ? load.photos : [];
114
+ const current = open == null ? null : photos[open] ?? null;
115
+
116
+ return (
117
+ <section className="cg-detail-section cg-docs" data-delivery-photos={photos.length}>
118
+ <div className="cg-detail-section-title">Delivery photos</div>
119
+ {load.status === "error" ? (
120
+ <div className="cg-docs-error" role="status">{load.message}</div>
121
+ ) : (
122
+ <div className="cg-detail-imageslot" style={{ flexWrap: "wrap" }}>
123
+ {photos.map((photo, index) => (
124
+ <button key={photo.id} type="button" className="cg-link-btn"
125
+ style={{ flex: "0 0 auto", height: "auto", padding: 0 }}
126
+ aria-label={`Open delivery photo ${index + 1} of ${photos.length}`}
127
+ onClick={() => setOpen(index)}>
128
+ <img className="cg-detail-image" src={photo.url} alt="" loading="lazy" decoding="async" />
129
+ </button>
130
+ ))}
131
+ </div>
132
+ )}
133
+ {current && open != null && (
134
+ <PhotoView photo={current} index={open} count={photos.length} onClose={() => setOpen(null)} />
135
+ )}
136
+ </section>
137
+ );
138
+ }
web/src/customer-grid/MapView.tsx CHANGED
@@ -41,8 +41,8 @@
41
  // it always drew rather than an empty rectangle.
42
  //
43
  // Honesty rules (rule 8b), carried and extended:
44
- // - rows WITHOUT coordinates are never silently hidden — a chip says
45
- // "N matching records have no location";
46
  // - a pin per row at its geocoded position, no clustering and no jitter (two
47
  // customers at one address overlap rather than being drawn where they are
48
  // not);
@@ -103,7 +103,7 @@ import {
103
  } from "./mapProjection";
104
  import type { GeoStop, Pt, RouteStamp, View } from "./mapProjection";
105
  import { LP_INK, LP_MAP_SELECTED, LP_PURPLE, LP_PURPLE_DEEP, LP_RED, LP_RED_DEEP, LP_ZONE_FILL_OPACITY, LP_ZONE_STROKE_WIDTH } from "./theme";
106
- import { RouteNav } from "./RouteNav";
107
  import { endpointRoutePlan, normalizedRouteMapLinks } from "./routeLinks";
108
  import {
109
  fetchRouteDeliveryRecipients,
@@ -845,6 +845,8 @@ function MapViewSurfaceContent({
845
  const [zones, setZones] = useState<MapZone[] | null>(null);
846
  /** C2 named-route read model. */
847
  const [namedRoutes, setNamedRoutes] = useState<MapRouteDto[]>([]);
 
 
848
  const [routeFolders, setRouteFolders] = useState<MapRouteFolderDto[]>([]);
849
  const [routeDeliveryRecipients, setRouteDeliveryRecipients] = useState<RouteDeliveryRecipientDirectory | null>(null);
850
  const [deliveryRecipientError, setDeliveryRecipientError] = useState<string | null>(null);
@@ -1254,7 +1256,6 @@ function MapViewSurfaceContent({
1254
  }
1255
  return out;
1256
  }, [mapRows, field.key, coordinateFields, coordField, sessionCoordinates, colorField, sizeField]);
1257
- const noCoords = mapRows.length - points.length;
1258
  /**
1259
  * W46-T26 — WHAT EACH STOP IS CALLED. The Route panel used to print a bare ordinal, so the
1260
  * list said nothing about who the driver is visiting. The name lives on the row, not on the
@@ -1344,10 +1345,12 @@ function MapViewSurfaceContent({
1344
  const body = res.ok ? await res.json().catch(() => null) : null;
1345
  if (!routingAlive.current) return;
1346
  if (routeRequestRef.current.generation !== generation) return;
 
1347
  if (Array.isArray(body?.routes)) setNamedRoutes(body.routes);
1348
  if (Array.isArray(body?.folders)) setRouteFolders(body.folders);
1349
  } catch {
1350
  if (controller.signal.aborted) return;
 
1351
  /* Keep the last honest Route navigation when a refresh is temporarily unavailable. */
1352
  }
1353
  }, [routingFetch]);
@@ -3707,8 +3710,6 @@ function MapViewSurfaceContent({
3707
  {geocodeSessionOnly
3708
  ? "No records with a location to map yet."
3709
  : "No records with a location to map yet. Set latitude and longitude fields in View schema to plot records."}
3710
- {noCoords > 0 &&
3711
- ` ${noCoords.toLocaleString()} matching record${noCoords === 1 ? "" : "s"} have no location.`}
3712
  {/* The way OUT of the empty state, offered from inside it. Selecting records and looking
3713
  up their addresses is the one action that turns this screen into a map. */}
3714
  {geoControl && <div className="cg-map-geo-empty">{geoControl}</div>}
@@ -3809,19 +3810,8 @@ function MapViewSurfaceContent({
3809
  row the host geocoded, and a lone "1,402" silently redefines the
3810
  toolbar's 1,550 ([[no-unverifiable-aggregates]]). */}
3811
  <span className="cg-cal-note cg-map-count">
3812
- <span>
3813
- <strong>{points.length.toLocaleString()}</strong> of{" "}
3814
- {mapRows.length.toLocaleString()} mapped · one pin per record that has a location
3815
- </span>
3816
  </span>
3817
- {noCoords > 0 && (
3818
- <span
3819
- className="cg-cal-nodate"
3820
- title={`${noCoords.toLocaleString()} matching record${noCoords === 1 ? "" : "s"} have no geocoded location and are not on the map. They remain in the Grid and List views.`}
3821
- >
3822
- {noCoords.toLocaleString()} matching record{noCoords === 1 ? " has" : "s have"} no location
3823
- </span>
3824
- )}
3825
  {routeSelectionWarning && !routePanelOpen && (
3826
  <aside className="cg-route-popover" aria-label="Route selection notice">
3827
  <span className="cg-w44-route-warning" role="status">{routeSelectionWarning}</span>
@@ -4578,10 +4568,7 @@ function MapViewSurfaceContent({
4578
  title="Open this area in Google Maps (new tab)"
4579
  aria-label="Open this area in Google Maps"
4580
  >
4581
- <svg viewBox="0 0 16 16" aria-hidden="true">
4582
- <path d="M7 3.8H4.3a.9.9 0 0 0-.9.9v6.9a.9.9 0 0 0 .9.9h6.9a.9.9 0 0 0 .9-.9V9.2" />
4583
- <path d="M8.6 3.4h4v4M12.6 3.4 7.4 8.6" />
4584
- </svg>
4585
  </a>
4586
  <button
4587
  type="button"
@@ -4726,6 +4713,7 @@ function MapViewSurfaceContent({
4726
  applicationName={applicationName}
4727
  applicationId={applicationId}
4728
  routes={namedRoutes}
 
4729
  folders={routeFolders}
4730
  selectedIds={selectedRouteIds}
4731
  activeRouteId={activeRouteId}
 
41
  // it always drew rather than an empty rectangle.
42
  //
43
  // Honesty rules (rule 8b), carried and extended:
44
+ // - rows WITHOUT coordinates are never silently hidden: the count line reads
45
+ // "N of M mapped", so the unmapped share is the gap between the two numbers;
46
  // - a pin per row at its geocoded position, no clustering and no jitter (two
47
  // customers at one address overlap rather than being drawn where they are
48
  // not);
 
103
  } from "./mapProjection";
104
  import type { GeoStop, Pt, RouteStamp, View } from "./mapProjection";
105
  import { LP_INK, LP_MAP_SELECTED, LP_PURPLE, LP_PURPLE_DEEP, LP_RED, LP_RED_DEEP, LP_ZONE_FILL_OPACITY, LP_ZONE_STROKE_WIDTH } from "./theme";
106
+ import { GoogleMapsMark, RouteNav } from "./RouteNav";
107
  import { endpointRoutePlan, normalizedRouteMapLinks } from "./routeLinks";
108
  import {
109
  fetchRouteDeliveryRecipients,
 
845
  const [zones, setZones] = useState<MapZone[] | null>(null);
846
  /** C2 named-route read model. */
847
  const [namedRoutes, setNamedRoutes] = useState<MapRouteDto[]>([]);
848
+ // `[]` cannot tell "not read yet" from "none": RouteNav says Loading until the first read answers.
849
+ const [routesLoaded, setRoutesLoaded] = useState(false);
850
  const [routeFolders, setRouteFolders] = useState<MapRouteFolderDto[]>([]);
851
  const [routeDeliveryRecipients, setRouteDeliveryRecipients] = useState<RouteDeliveryRecipientDirectory | null>(null);
852
  const [deliveryRecipientError, setDeliveryRecipientError] = useState<string | null>(null);
 
1256
  }
1257
  return out;
1258
  }, [mapRows, field.key, coordinateFields, coordField, sessionCoordinates, colorField, sizeField]);
 
1259
  /**
1260
  * W46-T26 — WHAT EACH STOP IS CALLED. The Route panel used to print a bare ordinal, so the
1261
  * list said nothing about who the driver is visiting. The name lives on the row, not on the
 
1345
  const body = res.ok ? await res.json().catch(() => null) : null;
1346
  if (!routingAlive.current) return;
1347
  if (routeRequestRef.current.generation !== generation) return;
1348
+ setRoutesLoaded(true);
1349
  if (Array.isArray(body?.routes)) setNamedRoutes(body.routes);
1350
  if (Array.isArray(body?.folders)) setRouteFolders(body.folders);
1351
  } catch {
1352
  if (controller.signal.aborted) return;
1353
+ setRoutesLoaded(true);
1354
  /* Keep the last honest Route navigation when a refresh is temporarily unavailable. */
1355
  }
1356
  }, [routingFetch]);
 
3710
  {geocodeSessionOnly
3711
  ? "No records with a location to map yet."
3712
  : "No records with a location to map yet. Set latitude and longitude fields in View schema to plot records."}
 
 
3713
  {/* The way OUT of the empty state, offered from inside it. Selecting records and looking
3714
  up their addresses is the one action that turns this screen into a map. */}
3715
  {geoControl && <div className="cg-map-geo-empty">{geoControl}</div>}
 
3810
  row the host geocoded, and a lone "1,402" silently redefines the
3811
  toolbar's 1,550 ([[no-unverifiable-aggregates]]). */}
3812
  <span className="cg-cal-note cg-map-count">
3813
+ <span><strong>{points.length.toLocaleString()}</strong> of {mapRows.length.toLocaleString()} mapped</span>
 
 
 
3814
  </span>
 
 
 
 
 
 
 
 
3815
  {routeSelectionWarning && !routePanelOpen && (
3816
  <aside className="cg-route-popover" aria-label="Route selection notice">
3817
  <span className="cg-w44-route-warning" role="status">{routeSelectionWarning}</span>
 
4568
  title="Open this area in Google Maps (new tab)"
4569
  aria-label="Open this area in Google Maps"
4570
  >
4571
+ <GoogleMapsMark />
 
 
 
4572
  </a>
4573
  <button
4574
  type="button"
 
4713
  applicationName={applicationName}
4714
  applicationId={applicationId}
4715
  routes={namedRoutes}
4716
+ routesLoaded={routesLoaded}
4717
  folders={routeFolders}
4718
  selectedIds={selectedRouteIds}
4719
  activeRouteId={activeRouteId}
web/src/customer-grid/RecordDetail.tsx CHANGED
@@ -2,6 +2,7 @@ import { lazy, Suspense, useCallback, useEffect, useId, useLayoutEffect, useMemo
2
  useState } from "react";
3
  import type { ReactNode, TextareaHTMLAttributes } from "react";
4
  import { BodyPortal, useOverlayLayer } from "./OverlaySurface";
 
5
 
6
  /**
7
  * ⭐⭐ W51-T06 (R5, contract C6) — THE GRID A RELATED TAB MOUNTS.
@@ -3395,6 +3396,14 @@ export default function RecordDetail({
3395
  onDelete={onDocDelete}
3396
  />
3397
  )}
 
 
 
 
 
 
 
 
3398
 
3399
  </>
3400
  )}
 
2
  useState } from "react";
3
  import type { ReactNode, TextareaHTMLAttributes } from "react";
4
  import { BodyPortal, useOverlayLayer } from "./OverlaySurface";
5
+ import { DELIVERY_SCOPES, DeliveryPhotos } from "./DeliveryPhotos";
6
 
7
  /**
8
  * ⭐⭐ W51-T06 (R5, contract C6) — THE GRID A RELATED TAB MOUNTS.
 
3396
  onDelete={onDocDelete}
3397
  />
3398
  )}
3399
+ {/* S78-T14 (C5): a delivery's Odoo photos, on the host record only. */}
3400
+ {!frame && scope != null && DELIVERY_SCOPES.has(scope) && (
3401
+ <DeliveryPhotos
3402
+ key={`${scope}:${Number(record.pid)}`}
3403
+ scope={scope}
3404
+ pid={Number(record.pid)}
3405
+ />
3406
+ )}
3407
 
3408
  </>
3409
  )}
web/src/customer-grid/RouteNav.tsx CHANGED
@@ -21,6 +21,7 @@ import {
21
  routeStopIdentity,
22
  } from "./routeZoneApi";
23
  // W51-T28 / R6 + C8 — the wave-51 base kit's ONE confirm dialog. Consumed, never re-implemented.
 
24
  import { ConfirmDialog } from "../ui/ConfirmDialog";
25
  import { useEscapeClose } from "../ui/useEscapeClose";
26
  import type {
@@ -30,6 +31,16 @@ import type {
30
  import "../styles/wave42/route-nav.css";
31
  import "./route-nav.css";
32
  import "../styles/wave46/route-print.css";
 
 
 
 
 
 
 
 
 
 
33
 
34
  type Result = Promise<string | null>;
35
 
@@ -215,7 +226,7 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
215
  onFolderCreate, onFolderUpdate, onFolderDelete, onFolderReorder, onCreateStart, mapLinks, mapLinkRefusal, deliveries, onSchedule,
216
  onDeleteDelivery, deliveryRecipients, deliveryRecipientError, onReloadDeliveryRecipients, zones = [],
217
  roundTrip = false, onRoundTripChange, routeStartPid = null, routeEndPid = null, onRouteStartChange, onRouteEndChange, onStopAdded,
218
- applicationName = "", applicationId }: {
219
  routes: MapRouteDto[];
220
  folders: MapRouteFolderDto[];
221
  selectedIds: ReadonlySet<string>;
@@ -282,6 +293,8 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
282
  /** Present only when this trusted route surface was launched by a saved Application. */
283
  applicationName?: string;
284
  applicationId?: string;
 
 
285
  }) {
286
  /* ⭐⭐ OWNER 2026-08-31 item 3 - THE ROUTES RAIL IS THE VIEWS RAIL, NOT A COUSIN OF IT.
287
  Owner: *"I need the routes LIST navigation and the routes itself to have the exact same
@@ -355,9 +368,9 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
355
  const [addStopQuery, setAddStopQuery] = useState("");
356
  const [titleDraft, setTitleDraft] = useState<string | null>(null);
357
  const [editMapsUrl, setEditMapsUrl] = useState("");
358
- /** D-599 - the Route's Zone, as a draft, saved by the same Save Route button as the Maps URL. */
359
  const [editZoneId, setEditZoneId] = useState("");
360
- /** OWNER 2026-08-31 item 2 - the Route's colour, as a draft, on the same Save Route button.
361
  * Seeded from the record so the swatch a person sees selected is the colour the map draws. */
362
  const [editColor, setEditColor] = useState(ROUTE_SWATCHES[0]);
363
  const [deliveryRecipient, setDeliveryRecipient] = useState("");
@@ -596,6 +609,7 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
596
  void operation.then(setError).finally(() => setBusy(false));
597
  };
598
  const commitStopMove = (target: MapRouteDto, pid: number, raw: string) => {
 
599
  setBusy(true);
600
  setOrderErrors((current) => {
601
  const next = { ...current };
@@ -606,6 +620,7 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
606
  if (result.error) {
607
  const message = result.error;
608
  setOrderErrors((current) => ({ ...current, [pid]: message }));
 
609
  return;
610
  }
611
  setOrderErrors((current) => {
@@ -703,6 +718,16 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
703
  const [dragPid, setDragPid] = useState<number | null>(null);
704
  const [dragOrder, setDragOrder] = useState<number[] | null>(null);
705
  const [dragSeconds, setDragSeconds] = useState<number | null>(null);
 
 
 
 
 
 
 
 
 
 
706
  /** W46-T20 — true only while one print is in flight. The printed sheet is mounted on
707
  * `document.body` for exactly that long, so it costs nothing the rest of the time and can
708
  * never be a second copy of the Route sitting invisibly in the panel. */
@@ -920,6 +945,7 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
920
  }, [timerKey]);
921
 
922
  const beginStopDrag = (pid: number) => {
 
923
  cancelSettle();
924
  setDragPid(pid);
925
  setDragOrder(stopIds);
@@ -953,6 +979,18 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
953
  scheduleSettle(order.filter((pid) => locatedPids.includes(pid)));
954
  };
955
 
 
 
 
 
 
 
 
 
 
 
 
 
956
  /** One click fills only the Route's located slots with the optimized located permutation. */
957
  const applyOptimizedOrder = (target: MapRouteDto) => {
958
  const answer = routeAnswer;
@@ -1091,7 +1129,7 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
1091
  const printStops = routePrintStops(
1092
  stopIds, stopLabels, stopCoords, routeStopIdentity, reversePrintLabels,
1093
  );
1094
- // ⚠ THE NAME HAS EXACTLY ONE WRITER NOW. `Save Route` below sends only the Maps URL, so an
1095
  // abandoned draft in the title can never be committed by a control that says nothing about
1096
  // names, and a saved rename can never be overwritten by a stale copy of the old one.
1097
  const commitRouteRename = () => {
@@ -1142,7 +1180,9 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
1142
  {/* ── W46-T19 / R9: the timer sits at the TOP, above the stops it is about. ─────────
1143
  The figure is muted and says "estimated" until a road answer settles, per C2, and
1144
  every caveat the answer carries is placed here rather than dropped. */}
1145
- <section className="cg-w46-route-timer" aria-label="Route drive time">
 
 
1146
  <div className="cg-w46-timer-head">
1147
  <span className={`cg-w46-timer-time${timerTone === "estimated" ? " is-estimated" : ""}`}>
1148
  {timerLabel || "No drive time yet"}
@@ -1202,32 +1242,32 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
1202
  stay at their current positions and are listed below.
1203
  </p>
1204
  )}
1205
- {!dragging && (
1206
- <div className="cg-w46-timer-saving">
1207
- {timerSaving?.offer && applyActionReason === null && <p>
1208
- Reordering {unlocated.length ? "the located stops" : "these stops"} saves {formatSeconds(timerSaving.seconds)}, about{" "}
1209
- {Math.abs(timerSaving.percent)}% of the drive.
1210
- </p>}
1211
- <button type="button" className="cg-w46-timer-apply"
1212
- disabled={applyActionReason !== null}
1213
- aria-describedby={applyActionReason
1214
- ? applyActionReason === editActionReason
1215
- ? "cg-route-edit-reason"
1216
- : "cg-route-apply-reason"
1217
- : undefined}
1218
- title={applyActionReason || undefined}
1219
- onClick={() => applyOptimizedOrder(stopView)}>
1220
- {applyBusy ? "Applying the faster order" : "Apply the faster order"}
1221
- </button>
1222
- {applyActionReason && applyActionReason !== editActionReason && (
1223
- <span id="cg-route-apply-reason" className="cg-route-action-reason">
1224
- {applyActionReason}
1225
- </span>
1226
- )}
1227
- </div>
1228
- )}
1229
- {!dragging && timerSaving?.costs && (
1230
- <p className="cg-w46-timer-note">
1231
  Reordering {unlocated.length ? "the located stops" : "these stops"} would add {formatSeconds(timerSaving.seconds)} on the road,
1232
  so the current located order is the faster one.
1233
  </p>
@@ -1242,7 +1282,7 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
1242
  disabled={editActionReason !== null} title={editActionReason || undefined}
1243
  onClick={() => finish(onUpdate(route, { mapsUrl: editMapsUrl.trim(),
1244
  zoneId: editZoneId || null, color: editColor }))}>
1245
- Save Route
1246
  </button>
1247
  <button type="button" className="cg-btn" disabled={editActionReason !== null}
1248
  title={editActionReason || undefined} onClick={() => finish(onShare(route))}>
@@ -1250,11 +1290,13 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
1250
  </button>
1251
  <button type="button" className="cg-btn" disabled={editActionReason !== null}
1252
  title={editActionReason || undefined} onClick={() => setDeleteConfirm(true)}>
1253
- Delete Route
1254
  </button>
1255
  </div>
 
1256
  {editActionReason && (
1257
- <span id="cg-route-edit-reason" className="cg-route-action-reason">
 
1258
  {editActionReason}
1259
  </span>
1260
  )}
@@ -1278,12 +1320,19 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
1278
  draggable={canEdit}
1279
  onDragStart={(event) => {
1280
  if (!canEdit) return;
 
 
 
 
1281
  event.dataTransfer.effectAllowed = "move";
1282
  try { event.dataTransfer.setData("text/plain", String(pid)); }
1283
  catch { /* Some browsers refuse a payload; the drag still works. */ }
1284
  beginStopDrag(pid);
1285
  }}
1286
- onDragEnd={() => endStopDrag()}
 
 
 
1287
  onDragOver={(event) => {
1288
  if (dragPid === null) return;
1289
  event.preventDefault();
@@ -1307,7 +1356,6 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
1307
  <button type="button" className="cg-view-main"
1308
  aria-label={`Open stop ${index + 1} record`}
1309
  aria-keyshortcuts={canEdit ? "Alt+ArrowUp Alt+ArrowDown" : undefined}
1310
- title={canEdit ? "Alt + Up or Alt + Down moves this stop" : undefined}
1311
  onKeyDown={(event) => {
1312
  if (!canEdit || !event.altKey || busy) return;
1313
  if (event.key === "ArrowUp" && index > 0) {
@@ -1323,10 +1371,13 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
1323
  accessible name above already carries it, so it is hidden from the reader
1324
  rather than announced twice. */}
1325
  <span className="cg-w46-stop-index" aria-hidden="true">{index + 1}</span>
1326
- <span className="cg-view-text">
1327
- <span className="cg-view-name" id={`cg-route-stop-name-${pid}`}>
 
 
 
1328
  {routeStopIdentity(stopLabels[pid], pid)}
1329
- </span>
1330
  </span>
1331
  </button>
1332
  {/* ⛔ OWNER 2026-08-31, TWICE: *"the < > for the route panel where you can choose
@@ -1438,7 +1489,7 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
1438
  {route.mapsUrl && !mapsUrl && <span className="cg-w44-route-empty">Maps link is unavailable.</span>}
1439
  <section className="cg-w44-route-map-links" aria-labelledby="cg-route-map-links-title">
1440
  <div>
1441
- <h3 id="cg-route-map-links-title">Google Maps</h3>
1442
  <p>Current ordered Route stops, split into links of at most 10 stops.</p>
1443
  </div>
1444
  {shownMapLinkRefusal ? (
@@ -1577,7 +1628,7 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
1577
  {/* ⭐⭐ D-599 / W46-T22 - THE ROUTE'S ZONE. Until wave 46's hotfix no route record
1578
  carried a zone at all, so this control had nothing to write and did not exist:
1579
  Routes and Zones were two separate tables and `__zone__` was a field on a CUSTOMER
1580
- row. It saves through the same Save Route button as the Maps URL beside it,
1581
  because both are properties of the Route and two save buttons on one form is how
1582
  a user loses the edit they did not press.
1583
  ⚠ THE UNAVAILABLE ARM IS DELIBERATE. A Route can hold a zone this reader cannot
@@ -2017,7 +2068,7 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
2017
  title={busy ? "Wait for the Route update to finish." : undefined}
2018
  onClick={() => { setBusy(true); void onShare(createdRoute).then((message) => {
2019
  setError(message); if (!message) onCreatedDismiss();
2020
- }).finally(() => setBusy(false)); }}>Share route</button>
2021
  <button type="button" className="cg-btn" disabled={busy}
2022
  title={busy ? "Wait for the Route update to finish." : undefined}
2023
  onClick={onCreatedDismiss}>Keep private</button>
@@ -2052,7 +2103,8 @@ function RouteNavContent({ routes, folders, selectedIds, activeRouteId, sources,
2052
  <div className="cg-view-list" aria-label="Route folder contents">
2053
  {rows}
2054
  {!rows.length && <p className="cg-w44-route-empty">
2055
- {query ? "No Route matches that search."
 
2056
  : "No routes yet. Create one from selected Zones or records."}
2057
  </p>}
2058
  </div>
 
21
  routeStopIdentity,
22
  } from "./routeZoneApi";
23
  // W51-T28 / R6 + C8 — the wave-51 base kit's ONE confirm dialog. Consumed, never re-implemented.
24
+ import { TruncatedName } from "../home/TruncatedName";
25
  import { ConfirmDialog } from "../ui/ConfirmDialog";
26
  import { useEscapeClose } from "../ui/useEscapeClose";
27
  import type {
 
31
  import "../styles/wave42/route-nav.css";
32
  import "./route-nav.css";
33
  import "../styles/wave46/route-print.css";
34
+ import "../styles/sdlc78/routing.css";
35
+
36
+ /** Google's own Maps mark from `public/brand/`, relative to the document as vite `base: "./"` makes
37
+ * every asset. No `import.meta` here: gates compile this file to CommonJS, where it is an error. */
38
+ export const GOOGLE_MAPS_MARK_SRC = "./brand/google-maps.svg";
39
+
40
+ /** The decorative 16 px Maps mark. The text beside it carries the name. */
41
+ export function GoogleMapsMark({ className = "cg-gmaps-mark" }: { className?: string }) {
42
+ return <img className={className} src={GOOGLE_MAPS_MARK_SRC} alt="" aria-hidden="true" width={16} height={16} draggable={false} />;
43
+ }
44
 
45
  type Result = Promise<string | null>;
46
 
 
226
  onFolderCreate, onFolderUpdate, onFolderDelete, onFolderReorder, onCreateStart, mapLinks, mapLinkRefusal, deliveries, onSchedule,
227
  onDeleteDelivery, deliveryRecipients, deliveryRecipientError, onReloadDeliveryRecipients, zones = [],
228
  roundTrip = false, onRoundTripChange, routeStartPid = null, routeEndPid = null, onRouteStartChange, onRouteEndChange, onStopAdded,
229
+ applicationName = "", applicationId, routesLoaded = true }: {
230
  routes: MapRouteDto[];
231
  folders: MapRouteFolderDto[];
232
  selectedIds: ReadonlySet<string>;
 
293
  /** Present only when this trusted route surface was launched by a saved Application. */
294
  applicationName?: string;
295
  applicationId?: string;
296
+ /** False until the first saved-Route read answers, so an empty list is not read as "none". */
297
+ routesLoaded?: boolean;
298
  }) {
299
  /* ⭐⭐ OWNER 2026-08-31 item 3 - THE ROUTES RAIL IS THE VIEWS RAIL, NOT A COUSIN OF IT.
300
  Owner: *"I need the routes LIST navigation and the routes itself to have the exact same
 
368
  const [addStopQuery, setAddStopQuery] = useState("");
369
  const [titleDraft, setTitleDraft] = useState<string | null>(null);
370
  const [editMapsUrl, setEditMapsUrl] = useState("");
371
+ /** D-599 - the Route's Zone, as a draft, saved by the same Save button as the Maps URL. */
372
  const [editZoneId, setEditZoneId] = useState("");
373
+ /** OWNER 2026-08-31 item 2 - the Route's colour, as a draft, on the same Save button.
374
  * Seeded from the record so the swatch a person sees selected is the colour the map draws. */
375
  const [editColor, setEditColor] = useState(ROUTE_SWATCHES[0]);
376
  const [deliveryRecipient, setDeliveryRecipient] = useState("");
 
609
  void operation.then(setError).finally(() => setBusy(false));
610
  };
611
  const commitStopMove = (target: MapRouteDto, pid: number, raw: string) => {
612
+ holdTimerCard(true);
613
  setBusy(true);
614
  setOrderErrors((current) => {
615
  const next = { ...current };
 
620
  if (result.error) {
621
  const message = result.error;
622
  setOrderErrors((current) => ({ ...current, [pid]: message }));
623
+ setTimerHold(null);
624
  return;
625
  }
626
  setOrderErrors((current) => {
 
718
  const [dragPid, setDragPid] = useState<number | null>(null);
719
  const [dragOrder, setDragOrder] = useState<number[] | null>(null);
720
  const [dragSeconds, setDragSeconds] = useState<number | null>(null);
721
+ /* S78-T08: the timer card keeps its pre-move height from a stop's pickup until the new drive
722
+ time settles, so the stop list below it never jumps on drop or on Alt + Up / Alt + Down. */
723
+ const timerCardRef = useRef<HTMLElement | null>(null);
724
+ const [timerHold, setTimerHold] = useState<
725
+ { height: number; from: RouteAnswer | null; committed: boolean } | null>(null);
726
+ const holdTimerCard = (committed: boolean) => {
727
+ const height = timerCardRef.current?.getBoundingClientRect().height ?? 0;
728
+ setTimerHold((current) => current ? { ...current, committed: current.committed || committed }
729
+ : height > 0 ? { height, from: routeAnswer, committed } : null);
730
+ };
731
  /** W46-T20 — true only while one print is in flight. The printed sheet is mounted on
732
  * `document.body` for exactly that long, so it costs nothing the rest of the time and can
733
  * never be a second copy of the Route sitting invisibly in the panel. */
 
945
  }, [timerKey]);
946
 
947
  const beginStopDrag = (pid: number) => {
948
+ holdTimerCard(false);
949
  cancelSettle();
950
  setDragPid(pid);
951
  setDragOrder(stopIds);
 
979
  scheduleSettle(order.filter((pid) => locatedPids.includes(pid)));
980
  };
981
 
982
+ // A committed hold ends when the move has landed and a new drive time has settled. The timer
983
+ // bounds it when no new answer comes (a refused move, fewer than two located stops).
984
+ useEffect(() => {
985
+ if (!timerHold?.committed) return;
986
+ if (!busy && !timerBusy && routeAnswer !== null && routeAnswer !== timerHold.from) {
987
+ setTimerHold(null);
988
+ return;
989
+ }
990
+ const timer = window.setTimeout(() => setTimerHold(null), 8000);
991
+ return () => window.clearTimeout(timer);
992
+ }, [timerHold, busy, timerBusy, routeAnswer]);
993
+
994
  /** One click fills only the Route's located slots with the optimized located permutation. */
995
  const applyOptimizedOrder = (target: MapRouteDto) => {
996
  const answer = routeAnswer;
 
1129
  const printStops = routePrintStops(
1130
  stopIds, stopLabels, stopCoords, routeStopIdentity, reversePrintLabels,
1131
  );
1132
+ // ⚠ THE NAME HAS EXACTLY ONE WRITER NOW. `Save` below sends only the Maps URL, so an
1133
  // abandoned draft in the title can never be committed by a control that says nothing about
1134
  // names, and a saved rename can never be overwritten by a stale copy of the old one.
1135
  const commitRouteRename = () => {
 
1180
  {/* ── W46-T19 / R9: the timer sits at the TOP, above the stops it is about. ─────────
1181
  The figure is muted and says "estimated" until a road answer settles, per C2, and
1182
  every caveat the answer carries is placed here rather than dropped. */}
1183
+ <section ref={timerCardRef}
1184
+ className={"cg-w46-route-timer" + (dragging ? " is-dragging" : "") + (timerHold ? " is-held" : "")}
1185
+ style={timerHold ? { height: `${timerHold.height}px` } : undefined} aria-label="Route drive time">
1186
  <div className="cg-w46-timer-head">
1187
  <span className={`cg-w46-timer-time${timerTone === "estimated" ? " is-estimated" : ""}`}>
1188
  {timerLabel || "No drive time yet"}
 
1242
  stay at their current positions and are listed below.
1243
  </p>
1244
  )}
1245
+ {/* S78-T08: a drag hides the apply block but keeps its box, so the stop list under the
1246
+ pointer does not jump up when a stop is picked up. */}
1247
+ <div className={"cg-w46-timer-saving" + (dragging ? " is-drag-held" : "")}>
1248
+ {timerSaving?.offer && applyActionReason === null && <p>
1249
+ Reordering {unlocated.length ? "the located stops" : "these stops"} saves {formatSeconds(timerSaving.seconds)}, about{" "}
1250
+ {Math.abs(timerSaving.percent)}% of the drive.
1251
+ </p>}
1252
+ <button type="button" className="cg-w46-timer-apply"
1253
+ disabled={applyActionReason !== null}
1254
+ aria-describedby={applyActionReason
1255
+ ? applyActionReason === editActionReason
1256
+ ? "cg-route-edit-reason"
1257
+ : "cg-route-apply-reason"
1258
+ : undefined}
1259
+ title={applyActionReason || undefined}
1260
+ onClick={() => applyOptimizedOrder(stopView)}>
1261
+ {applyBusy ? "Applying the faster order" : "Apply the faster order"}
1262
+ </button>
1263
+ {applyActionReason && applyActionReason !== editActionReason && (
1264
+ <span id="cg-route-apply-reason" className="cg-route-action-reason">
1265
+ {applyActionReason}
1266
+ </span>
1267
+ )}
1268
+ </div>
1269
+ {timerSaving?.costs && (
1270
+ <p className={"cg-w46-timer-note" + (dragging ? " is-drag-held" : "")}>
1271
  Reordering {unlocated.length ? "the located stops" : "these stops"} would add {formatSeconds(timerSaving.seconds)} on the road,
1272
  so the current located order is the faster one.
1273
  </p>
 
1282
  disabled={editActionReason !== null} title={editActionReason || undefined}
1283
  onClick={() => finish(onUpdate(route, { mapsUrl: editMapsUrl.trim(),
1284
  zoneId: editZoneId || null, color: editColor }))}>
1285
+ Save
1286
  </button>
1287
  <button type="button" className="cg-btn" disabled={editActionReason !== null}
1288
  title={editActionReason || undefined} onClick={() => finish(onShare(route))}>
 
1290
  </button>
1291
  <button type="button" className="cg-btn" disabled={editActionReason !== null}
1292
  title={editActionReason || undefined} onClick={() => setDeleteConfirm(true)}>
1293
+ Delete
1294
  </button>
1295
  </div>
1296
+ {/* During a stop move the busy reason stays announced but takes no line, so the list holds. */}
1297
  {editActionReason && (
1298
+ <span id="cg-route-edit-reason"
1299
+ className={"cg-route-action-reason" + (timerHold?.committed ? " cg-sr-only" : "")}>
1300
  {editActionReason}
1301
  </span>
1302
  )}
 
1320
  draggable={canEdit}
1321
  onDragStart={(event) => {
1322
  if (!canEdit) return;
1323
+ // S78-T08: a name tip opened by the press closes before the row moves.
1324
+ const main = event.currentTarget.querySelector<HTMLElement>(".cg-view-main");
1325
+ main?.dispatchEvent(new PointerEvent("pointerleave"));
1326
+ if (main && document.activeElement === main) main.blur();
1327
  event.dataTransfer.effectAllowed = "move";
1328
  try { event.dataTransfer.setData("text/plain", String(pid)); }
1329
  catch { /* Some browsers refuse a payload; the drag still works. */ }
1330
  beginStopDrag(pid);
1331
  }}
1332
+ onDragEnd={() => {
1333
+ endStopDrag();
1334
+ setTimerHold((current) => current && !current.committed ? null : current);
1335
+ }}
1336
  onDragOver={(event) => {
1337
  if (dragPid === null) return;
1338
  event.preventDefault();
 
1356
  <button type="button" className="cg-view-main"
1357
  aria-label={`Open stop ${index + 1} record`}
1358
  aria-keyshortcuts={canEdit ? "Alt+ArrowUp Alt+ArrowDown" : undefined}
 
1359
  onKeyDown={(event) => {
1360
  if (!canEdit || !event.altKey || busy) return;
1361
  if (event.key === "ArrowUp" && index > 0) {
 
1371
  accessible name above already carries it, so it is hidden from the reader
1372
  rather than announced twice. */}
1373
  <span className="cg-w46-stop-index" aria-hidden="true">{index + 1}</span>
1374
+ {/* S78-T08: a long name ends in an ellipsis and TruncatedName shows it in full on
1375
+ hover and focus. The id moves to the wrapper because TruncatedName takes none. */}
1376
+ <span className="cg-view-text" id={`cg-route-stop-name-${pid}`}>
1377
+ {/* Keyed by seat: a reorder remounts the tip, so it never paints at a stale row. */}
1378
+ <TruncatedName key={index} className="cg-view-name">
1379
  {routeStopIdentity(stopLabels[pid], pid)}
1380
+ </TruncatedName>
1381
  </span>
1382
  </button>
1383
  {/* ⛔ OWNER 2026-08-31, TWICE: *"the < > for the route panel where you can choose
 
1489
  {route.mapsUrl && !mapsUrl && <span className="cg-w44-route-empty">Maps link is unavailable.</span>}
1490
  <section className="cg-w44-route-map-links" aria-labelledby="cg-route-map-links-title">
1491
  <div>
1492
+ <h3 id="cg-route-map-links-title" className="cg-gmaps-heading"><GoogleMapsMark />Google Maps</h3>
1493
  <p>Current ordered Route stops, split into links of at most 10 stops.</p>
1494
  </div>
1495
  {shownMapLinkRefusal ? (
 
1628
  {/* ⭐⭐ D-599 / W46-T22 - THE ROUTE'S ZONE. Until wave 46's hotfix no route record
1629
  carried a zone at all, so this control had nothing to write and did not exist:
1630
  Routes and Zones were two separate tables and `__zone__` was a field on a CUSTOMER
1631
+ row. It saves through the same Save button as the Maps URL beside it,
1632
  because both are properties of the Route and two save buttons on one form is how
1633
  a user loses the edit they did not press.
1634
  ⚠ THE UNAVAILABLE ARM IS DELIBERATE. A Route can hold a zone this reader cannot
 
2068
  title={busy ? "Wait for the Route update to finish." : undefined}
2069
  onClick={() => { setBusy(true); void onShare(createdRoute).then((message) => {
2070
  setError(message); if (!message) onCreatedDismiss();
2071
+ }).finally(() => setBusy(false)); }}>Share</button>
2072
  <button type="button" className="cg-btn" disabled={busy}
2073
  title={busy ? "Wait for the Route update to finish." : undefined}
2074
  onClick={onCreatedDismiss}>Keep private</button>
 
2103
  <div className="cg-view-list" aria-label="Route folder contents">
2104
  {rows}
2105
  {!rows.length && <p className="cg-w44-route-empty">
2106
+ {!routesLoaded ? "Loading routes."
2107
+ : query ? "No Route matches that search."
2108
  : "No routes yet. Create one from selected Zones or records."}
2109
  </p>}
2110
  </div>
web/src/customer-grid/ViewSidebar.tsx CHANGED
@@ -682,6 +682,13 @@ function dataNavigatorLevelKey(level: DataNavigatorLevel): string {
682
  return `database:${level.key}`;
683
  }
684
 
 
 
 
 
 
 
 
685
  /** Windows-style Data path rendered with the same segmented-path anatomy as the View path. */
686
  function DataDatabaseNavigator({
687
  databases,
@@ -697,6 +704,49 @@ function DataDatabaseNavigator({
697
  header,
698
  children,
699
  }: DataDatabaseNavigatorProps) {
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
700
  const [draggedDatabase, setDraggedDatabase] = useState<string | null>(null);
701
  const [folderMenu, setFolderMenu] = useState<{ folderId: string; anchor: HTMLElement } | null>(
702
  null
@@ -732,8 +782,9 @@ function DataDatabaseNavigator({
732
  : {};
733
 
734
  const sourceGroups = useMemo(
735
- () => groupDataDatabases(databases.filter((database) => !database.folderId)),
736
- [databases]
 
737
  );
738
  const parentOfDatabase = (database: DataDatabase): DataNavigatorLevel =>
739
  database.folderId
@@ -844,6 +895,7 @@ function DataDatabaseNavigator({
844
  const pathDatabaseRow = (database: DataDatabase) => {
845
  const active = database.key === activeDatabaseKey;
846
  const draggable = !!onMove && !database.protected && database.managedBy !== "loopable";
 
847
  const content = (
848
  <>
849
  {/* ⭐⭐ W53-T35 / C4 (owner instruction 26) — THE WRAPPER IS THE FIX, and the mark is
@@ -864,7 +916,15 @@ function DataDatabaseNavigator({
864
  <span className="cg-db-mark">
865
  <DatabaseMark size={16} />
866
  </span>
867
- <span className="cg-fold-name">{database.label}</span>
 
 
 
 
 
 
 
 
868
  {database.locked ? (
869
  <span
870
  className="cg-data-database-lock"
@@ -935,7 +995,7 @@ function DataDatabaseNavigator({
935
  const dataNeedle = dataQuery.trim().toLowerCase();
936
  const matchesNeedle = (label: string) =>
937
  !dataNeedle || label.toLowerCase().includes(dataNeedle);
938
- const levelDatabases = (
939
  dataLevel.kind === "origin"
940
  ? sourceGroups.find((group) => group.label === dataLevel.label)?.databases ?? []
941
  : dataLevel.kind === "folder"
@@ -947,6 +1007,25 @@ function DataDatabaseNavigator({
947
  (dataLevel.kind === "root" || dataLevel.kind === "folder")
948
  && (folder.parent ?? null) === (dataLevel.kind === "folder" ? dataLevel.id : null)
949
  && matchesNeedle(folder.name));
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
950
  const pathFolderRow = (folder: DataDatabaseFolder) => {
951
  const members = databases.filter((database) => database.folderId === folder.id);
952
  const childFolders = folders.filter((child) => child.parent === folder.id);
@@ -1081,10 +1160,11 @@ function DataDatabaseNavigator({
1081
  {...dropProps(dataLevel.kind === "folder" ? dataLevel.id : null)}>
1082
  {levelFolders.map(pathFolderRow)}
1083
  {levelDatabases.map(pathDatabaseRow)}
 
1084
  {/* The empty line must say WHY it is empty: under a live query "No databases in this
1085
  folder" is simply false, and a wrong empty state on the control this ticket just
1086
  un-hid is what QA reopens. */}
1087
- {levelDatabases.length === 0 && levelFolders.length === 0 ? (
1088
  <div className="cg-fold-empty">
1089
  {dataNeedle ? "No matches." : "No databases in this folder."}
1090
  </div>
 
682
  return `database:${level.key}`;
683
  }
684
 
685
+ /** S78-T02 (C1): the Amazon nav facts `/nav` serves. Optional, so a row without them is unchanged. */
686
+ type RailDatabase = DataDatabase & {
687
+ group?: string;
688
+ /** `at` null is a read "never synced"; an absent `sync` is unknown and shows nothing. */
689
+ sync?: { at: string | null; empty: boolean | null };
690
+ };
691
+
692
  /** Windows-style Data path rendered with the same segmented-path anatomy as the View path. */
693
  function DataDatabaseNavigator({
694
  databases,
 
704
  header,
705
  children,
706
  }: DataDatabaseNavigatorProps) {
707
+ // S78-T02: declared inside the navigator, because verify_folders runs this function alone in a vm.
708
+ /** C1's group order under the Amazon level. ⛔ A person reads these: no dash, sentence case. */
709
+ const AMAZON_RAIL_GROUPS = ["Sales", "Fees and payouts", "Inventory", "Listings", "Advertising"];
710
+
711
+ /** A table the mirror reads as 0 rows leaves the rail; Fields and Settings still list it. */
712
+ function railListed(database: DataDatabase, activeKey: string): boolean {
713
+ return (database as RailDatabase).sync?.empty !== true || database.key === activeKey;
714
+ }
715
+
716
+ /** The muted second line of an Amazon row, in plain words, or null when the fact is unknown. */
717
+ function railSyncLine(database: DataDatabase): string | null {
718
+ const sync = (database as RailDatabase).sync;
719
+ if (!sync) return null;
720
+ if (sync.at === null) return "Never synced";
721
+ const at = new Date(sync.at);
722
+ if (Number.isNaN(at.getTime())) return null;
723
+ return `Synced ${at.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" })}`;
724
+ }
725
+
726
+ /** The five groups in order, each with its databases, or null when no database has a group. */
727
+ function railGroupSections(
728
+ listed: readonly DataDatabase[]
729
+ ): { sections: { label: string; databases: DataDatabase[] }[]; ungrouped: DataDatabase[] } | null {
730
+ const grouped = new Map<string, DataDatabase[]>();
731
+ const ungrouped: DataDatabase[] = [];
732
+ for (const database of listed) {
733
+ const group = (database as RailDatabase).group;
734
+ if (group && AMAZON_RAIL_GROUPS.includes(group)) {
735
+ grouped.set(group, [...(grouped.get(group) ?? []), database]);
736
+ } else {
737
+ ungrouped.push(database);
738
+ }
739
+ }
740
+ if (grouped.size === 0) return null;
741
+ return {
742
+ sections: AMAZON_RAIL_GROUPS.filter((label) => grouped.has(label)).map((label) => ({
743
+ label,
744
+ databases: grouped.get(label) ?? [],
745
+ })),
746
+ ungrouped,
747
+ };
748
+ }
749
+
750
  const [draggedDatabase, setDraggedDatabase] = useState<string | null>(null);
751
  const [folderMenu, setFolderMenu] = useState<{ folderId: string; anchor: HTMLElement } | null>(
752
  null
 
782
  : {};
783
 
784
  const sourceGroups = useMemo(
785
+ () => groupDataDatabases(databases.filter((database) =>
786
+ !database.folderId && railListed(database, activeDatabaseKey))),
787
+ [databases, activeDatabaseKey]
788
  );
789
  const parentOfDatabase = (database: DataDatabase): DataNavigatorLevel =>
790
  database.folderId
 
895
  const pathDatabaseRow = (database: DataDatabase) => {
896
  const active = database.key === activeDatabaseKey;
897
  const draggable = !!onMove && !database.protected && database.managedBy !== "loopable";
898
+ const syncLine = railSyncLine(database);
899
  const content = (
900
  <>
901
  {/* ⭐⭐ W53-T35 / C4 (owner instruction 26) — THE WRAPPER IS THE FIX, and the mark is
 
916
  <span className="cg-db-mark">
917
  <DatabaseMark size={16} />
918
  </span>
919
+ {syncLine ? (
920
+ // S78-T02 (R11): the true last sync as a quiet second line, the view rows' own pair.
921
+ <span className="cg-view-text">
922
+ <span className="cg-fold-name">{database.label}</span>
923
+ <span className="cg-view-desc" data-rail-sync>{syncLine}</span>
924
+ </span>
925
+ ) : (
926
+ <span className="cg-fold-name">{database.label}</span>
927
+ )}
928
  {database.locked ? (
929
  <span
930
  className="cg-data-database-lock"
 
995
  const dataNeedle = dataQuery.trim().toLowerCase();
996
  const matchesNeedle = (label: string) =>
997
  !dataNeedle || label.toLowerCase().includes(dataNeedle);
998
+ const levelMatches = (
999
  dataLevel.kind === "origin"
1000
  ? sourceGroups.find((group) => group.label === dataLevel.label)?.databases ?? []
1001
  : dataLevel.kind === "folder"
 
1007
  (dataLevel.kind === "root" || dataLevel.kind === "folder")
1008
  && (folder.parent ?? null) === (dataLevel.kind === "folder" ? dataLevel.id : null)
1009
  && matchesNeedle(folder.name));
1010
+ // S78-T02 (C1): only the Amazon level groups by job. Every other origin stays one flat list.
1011
+ const railSections = dataLevel.kind === "origin"
1012
+ && sourceGroups.find((group) => group.label === dataLevel.label)?.connector === "amazon_sp"
1013
+ ? railGroupSections(levelMatches)
1014
+ : null;
1015
+ // The flat list keeps what no group claims, so a grouped database is drawn exactly once.
1016
+ const levelDatabases = railSections ? railSections.ungrouped : levelMatches;
1017
+ // ⛔ A static heading, never a fold: the Data rail is list-replacing (verify_w44 refuses a
1018
+ // disclosure tree), so a group is the rail's existing quiet section, `.cg-rail-section`.
1019
+ const railGroupRow = (section: { label: string; databases: DataDatabase[] }) => (
1020
+ <div key={section.label} className="cg-rail-section cg-data-group" role="group"
1021
+ aria-label={`${section.label}, ${section.databases.length} databases`}
1022
+ data-rail-group={section.label}>
1023
+ <div className="cg-fold-head">
1024
+ <span className="cg-view-desc">{section.label}</span>
1025
+ </div>
1026
+ {section.databases.map(pathDatabaseRow)}
1027
+ </div>
1028
+ );
1029
  const pathFolderRow = (folder: DataDatabaseFolder) => {
1030
  const members = databases.filter((database) => database.folderId === folder.id);
1031
  const childFolders = folders.filter((child) => child.parent === folder.id);
 
1160
  {...dropProps(dataLevel.kind === "folder" ? dataLevel.id : null)}>
1161
  {levelFolders.map(pathFolderRow)}
1162
  {levelDatabases.map(pathDatabaseRow)}
1163
+ {railSections?.sections.map(railGroupRow)}
1164
  {/* The empty line must say WHY it is empty: under a live query "No databases in this
1165
  folder" is simply false, and a wrong empty state on the control this ticket just
1166
  un-hid is what QA reopens. */}
1167
+ {levelMatches.length === 0 && levelFolders.length === 0 ? (
1168
  <div className="cg-fold-empty">
1169
  {dataNeedle ? "No matches." : "No databases in this folder."}
1170
  </div>