fsanyoto commited on
Commit
ea7b176
Β·
verified Β·
1 Parent(s): e9abe24

Deploy AIOS web (React glide grid + FastAPI slice)

Browse files
Files changed (50) hide show
  1. api/automation_engine.py +725 -71
  2. api/deps.py +59 -0
  3. api/main.py +7 -0
  4. api/routes_admin.py +7 -0
  5. api/routes_assets.py +138 -1
  6. api/routes_auth.py +11 -0
  7. api/routes_automation.py +29 -0
  8. api/routes_nav.py +210 -1
  9. api/routes_platform_admin.py +593 -0
  10. api/routes_products.py +94 -19
  11. api/routes_records.py +88 -16
  12. api/routes_tables.py +32 -14
  13. platform/aios_grid.py +26 -6
  14. platform/core/assets.py +89 -4
  15. platform/core/grid_events.py +78 -20
  16. platform/core/platform_admin.py +58 -0
  17. platform/core/record_comments.py +36 -9
  18. platform/core/users.py +147 -3
  19. platform/harness/analyst.py +7 -0
  20. platform/harness/telemetry.py +26 -3
  21. platform/modules/cohort.py +198 -23
  22. web/dist-embed/index.html +0 -0
  23. web/src/automation/AutomationCanvas.tsx +389 -0
  24. web/src/automation/AutomationCreate.tsx +394 -0
  25. web/src/automation/AutomationDetail.tsx +746 -0
  26. web/src/automation/AutomationSurface.tsx +22 -11
  27. web/src/automation/automationApi.ts +77 -1
  28. web/src/automation/canvasLayout.ts +163 -0
  29. web/src/customer-grid/CatalogView.tsx +14 -2
  30. web/src/customer-grid/CustomerGrid.tsx +3 -3
  31. web/src/customer-grid/RecordComments.tsx +18 -4
  32. web/src/customer-grid/RecordDetail.css +81 -0
  33. web/src/customer-grid/RecordDetail.tsx +105 -3
  34. web/src/customer-grid/catalogData.ts +93 -4
  35. web/src/customer-grid/cells.ts +109 -0
  36. web/src/customer-grid/iconShapes.ts +9 -0
  37. web/src/customer-grid/recordCommentsApi.ts +34 -4
  38. web/src/customer-grid/types.ts +34 -1
  39. web/src/index.css +0 -0
  40. web/src/settings/AdminPane.tsx +568 -0
  41. web/src/settings/SettingsModal.tsx +142 -24
  42. web/src/settings/permsModel.ts +20 -1
  43. web/src/settings/platformAdminApi.ts +224 -0
  44. web/src/settings/settingsApi.ts +16 -0
  45. web/src/shell/NavExtras.tsx +301 -22
  46. web/src/shell/Shell.tsx +218 -52
  47. web/src/shell/nav.ts +94 -0
  48. web/src/shell/navExtras.css +77 -0
  49. web/src/viz/seriesData.ts +6 -0
  50. web/src/viz/types.ts +7 -1
api/automation_engine.py CHANGED
@@ -59,9 +59,43 @@ MAX_NAME = 80
59
  MAX_UT_ROWS = 5000 # mirrors core.user_tables.MAX_ROWS
60
  MAX_UT_TABLES = 40
61
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
62
  KINDS = ("scrape_db", "field_instagram")
63
  EXTRACTS = ("table", "jsonld")
64
  STATES = ("idle", "running", "ok", "error", "partial")
 
 
 
 
 
 
 
 
 
65
 
66
  #: Schedule presets the editor offers. Kept here (not in the client) so the vocabulary the UI
67
  #: shows and the vocabulary the parser accepts cannot drift.
@@ -442,7 +476,7 @@ def next_fire(expr, now=None, lookahead_days=400):
442
  # THE UPSERT β€” pure, so the arithmetic is testable without a store or a network
443
  # ---------------------------------------------------------------------------------------------
444
 
445
- def upsert_rows(existing, incoming, key_field):
446
  """Merge scraped rows into a user table's rows BY KEY. Returns `(rows, counts)`.
447
 
448
  THE RULE THAT MATTERS: **an orphan is COUNTED, NEVER DELETED.** A row that has stopped
@@ -452,10 +486,24 @@ def upsert_rows(existing, incoming, key_field):
452
  columns the scrape never touches. So the run reports `orphans: N` and leaves them alone.
453
 
454
  Only MAPPED keys are written: a re-run never clobbers a column a user added by hand.
 
 
 
 
 
 
 
 
 
 
 
 
 
455
  """
 
456
  rows = {str(k): dict(v or {}) for k, v in (existing or {}).items()}
457
  counts = {"inserted": 0, "updated": 0, "unchanged": 0,
458
- "skipped": 0, "duplicates": 0, "orphans": 0}
459
  by_key, dupe_ids = {}, set()
460
  for rid, row in rows.items():
461
  kv = str(row.get(key_field, "") or "").strip()
@@ -478,8 +526,8 @@ def upsert_rows(existing, incoming, key_field):
478
  seen_keys.add(kv)
479
  rid = by_key.get(kv)
480
  if rid is None:
481
- if len(rows) >= MAX_UT_ROWS:
482
- counts["skipped"] += 1
483
  continue
484
  rid = str(next_id)
485
  next_id += 1
@@ -520,6 +568,14 @@ def ut_get(rt, key):
520
  return ut_all(rt).get(str(key))
521
 
522
 
 
 
 
 
 
 
 
 
523
  def ut_ensure(rt, label, fields, username="automation", key=None):
524
  """Create the table if it is missing; return its key. Idempotent β€” a re-run of an automation
525
  that owns a table must not spawn `ut_x_2`, so the key is DERIVED from the label (or given)
@@ -528,9 +584,7 @@ def ut_ensure(rt, label, fields, username="automation", key=None):
528
  Fields are MERGED, never replaced: a user who added a column to an automation's table keeps
529
  it, and a new source column joins on the next run.
530
  """
531
- key = str(key or (UT_PREFIX + _ut_slug(label)))
532
- if not key.startswith(UT_PREFIX):
533
- key = UT_PREFIX + key
534
  wanted = list(fields or [])
535
  created = _iso()
536
 
@@ -604,9 +658,21 @@ def _s(v, n=200):
604
  return str(v if v is not None else "")[:n]
605
 
606
 
607
- def clean_config(kind, raw):
608
- """Validate a kind's config. Returns `(config, error)`; error is a user-facing sentence."""
 
 
 
 
 
 
 
 
609
  raw = raw if isinstance(raw, dict) else {}
 
 
 
 
610
  if kind == "scrape_db":
611
  url = _s(raw.get("url"), 2000).strip()
612
  if not url:
@@ -633,6 +699,7 @@ def clean_config(kind, raw):
633
  "tableIndex": max(0, min(int(raw.get("tableIndex") or 0), 50)),
634
  "fieldMap": fmap, "keyField": key_field,
635
  "targetTable": target,
 
636
  "targetLabel": _s(raw.get("targetLabel"), 60).strip() or "Scraped table"}, None
637
  if kind == "field_instagram":
638
  table = _s(raw.get("targetTable"), 60).strip()
@@ -643,6 +710,14 @@ def clean_config(kind, raw):
643
  return None, "pick the automation column this run writes into"
644
  return {"targetTable": table, "fieldKey": fkey,
645
  "urlField": _s(raw.get("urlField"), 80).strip(),
 
 
 
 
 
 
 
 
646
  "maxPosts": max(1, min(int(raw.get("maxPosts") or 24), 200))}, None
647
  return None, f"unknown automation kind {kind!r}"
648
 
@@ -672,7 +747,7 @@ def clean_definition(raw, previous=None, username=""):
672
  if not name:
673
  return None, "name the automation"
674
  cfg_raw = raw.get("config") if isinstance(raw.get("config"), dict) else prev.get("config")
675
- config, err = clean_config(kind, cfg_raw)
676
  if err:
677
  return None, err
678
  try:
@@ -787,11 +862,18 @@ def _release(tenant, auto_id):
787
  _RUNNING.pop((tenant, str(auto_id)), None)
788
 
789
 
790
- def _commit_run(rt, auto_id, state, summary, counts, ok, affected=None):
791
- """THE ONE store write a run performs on the `automations` bucket."""
 
 
 
 
 
 
792
  entry = {"ts": _iso(), "ok": bool(ok), "summary": _s(summary, 400),
793
  "counts": {k: int(v) for k, v in (counts or {}).items()
794
  if isinstance(v, (int, float))},
 
795
  "affected": list(affected or [])[:200]}
796
 
797
  def _up(cur):
@@ -809,11 +891,18 @@ def _commit_run(rt, auto_id, state, summary, counts, ok, affected=None):
809
 
810
 
811
  # ---------------------------------------------------------------------------------------------
812
- # INSTAGRAM (R7) β€” ANONYMOUS PUBLIC ENDPOINTS ONLY
813
  # ---------------------------------------------------------------------------------------------
814
- # The rails, restated because they are the whole reason this is allowed to exist: **no login, no
815
- # credentials, no session cookie, public data only.** Nothing here authenticates, and nothing
816
- # here should ever be given something to authenticate WITH.
 
 
 
 
 
 
 
817
  #
818
  # ⚠ HONEST STATUSES ARE THE FEATURE. Instagram rate-limits and outright blocks datacenter egress
819
  # (the HF Space and any AWS Lambda are both in that class), and its anonymous surface has been
@@ -835,6 +924,10 @@ SNAPSHOT_FIELDS = [
835
  field_def("full_name", "Name"), field_def("bio", "Bio"),
836
  field_def("verified", "Verified"), field_def("source", "Read via"),
837
  field_def("approx", "Counts are approximate"),
 
 
 
 
838
  ]
839
  POST_FIELDS = [
840
  field_def("shortcode", "Shortcode"), field_def("influencer_key", "Influencer"),
@@ -845,6 +938,9 @@ POST_SNAPSHOT_FIELDS = [
845
  field_def("post_snapshot_key", "Snapshot"), field_def("shortcode", "Shortcode"),
846
  field_def("pulled_at", "Pulled at"), field_def("likes", "Likes"),
847
  field_def("comments", "Comments"),
 
 
 
848
  ]
849
 
850
 
@@ -947,12 +1043,285 @@ def _loose_count(txt):
947
  return None
948
 
949
 
950
- def pull_profile(url, max_posts=24, log=print):
951
- """Everything anonymously readable about one public profile.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
952
 
953
  Returns `{state, profile, posts, via, note}` with state ∈ ok | partial | blocked | error.
954
  `partial` means the identity was read but the media was not β€” which is the outcome the
955
  anonymous surface most often gives, and saying so is the point.
 
 
 
 
 
 
 
 
 
 
 
956
  """
957
  handle = ig_handle(url)
958
  if not handle:
@@ -960,6 +1329,17 @@ def pull_profile(url, max_posts=24, log=print):
960
  "profile": {}, "posts": [], "via": ""}
961
  attempts = []
962
 
 
 
 
 
 
 
 
 
 
 
 
963
  # RUNG 1 β€” the web client's own profile endpoint. Public, no cookie; the one that used to
964
  # carry both the profile AND the first page of media in a single answer.
965
  api = f"https://www.instagram.com/api/v1/users/web_profile_info/?username={handle}"
@@ -1078,14 +1458,33 @@ def _paginate(user_id, cursor, want, log=print):
1078
  # RUNNERS
1079
  # ---------------------------------------------------------------------------------------------
1080
 
 
 
 
 
 
 
 
 
 
 
 
 
1081
  def run_scrape_db(rt, defn, username="automation", log=print):
1082
  """Automation #1 (R6): a public page β†’ a blank database, re-runnable, UPSERT by key."""
1083
  cfg = defn.get("config") or {}
1084
  fmap, key_field = cfg.get("fieldMap") or {}, cfg.get("keyField")
 
 
 
 
 
1085
  status, final, body = fetch(cfg["url"])
1086
  if not (200 <= status < 300):
 
1087
  return ("error", f"{cfg['url']} answered {status} β€” nothing was written",
1088
- {"status": status}, [])
 
1089
  soup = _soup(body)
1090
  if cfg.get("extract") == "jsonld":
1091
  blocks = jsonld(soup)
@@ -1103,7 +1502,10 @@ def run_scrape_db(rt, defn, username="automation", log=print):
1103
  idx = max(0, min(int(cfg.get("tableIndex") or 0), len(found) - 1)) if found else 0
1104
  raw_rows = [r for r in (found[idx] if found else []) if isinstance(r, dict)]
1105
  if not raw_rows:
1106
- return ("error", "the page parsed but the selected table had no rows", {"rows": 0}, [])
 
 
 
1107
 
1108
  incoming = []
1109
  for r in raw_rows:
@@ -1115,85 +1517,139 @@ def run_scrape_db(rt, defn, username="automation", log=print):
1115
  for src, tgt in fmap.items()]
1116
  # the key column leads, so the table opens on the identity it is upserted by
1117
  fields.sort(key=lambda f: 0 if f["key"] == key_field else 1)
1118
- table_key = ut_ensure(rt, cfg.get("targetLabel") or defn.get("name") or "Scraped table",
1119
- fields, username, key=cfg.get("targetTable") or None)
 
 
 
 
 
 
1120
  t = ut_get(rt, table_key) or {}
1121
- rows, counts = upsert_rows(t.get("rows") or {}, incoming, key_field)
1122
- ut_write_rows(rt, table_key, rows)
 
 
1123
  counts["source_rows"] = len(incoming)
1124
  affected = [rid for rid, row in rows.items()
1125
  if str(row.get(key_field, "")) in {str(i.get(key_field)) for i in incoming}][:200]
1126
  summary = (f"{counts['inserted']} new, {counts['updated']} updated, "
1127
  f"{counts['unchanged']} unchanged, {counts['orphans']} no longer on the page "
1128
  f"(kept)")
1129
- state = "partial" if counts["skipped"] else "ok"
 
 
 
 
 
 
 
 
 
 
1130
  log(f"[aios-auto] scrape_db {defn.get('id')} -> {table_key}: {summary}")
1131
- return (state, summary, counts, affected)
1132
 
1133
 
1134
  def run_field_instagram(rt, defn, username="automation", log=print):
1135
- """Automation #2 (R7): for every row of a blank database that carries a profile URL, pull
1136
- the public profile anonymously and write a status string into the automation column."""
 
 
1137
  cfg = defn.get("config") or {}
1138
  table_key, fkey = cfg.get("targetTable"), cfg.get("fieldKey")
 
 
 
 
 
 
 
1139
  t = ut_get(rt, table_key)
1140
  if not t:
1141
- return ("error", f"{table_key} is not a database in this workspace", {}, [])
 
1142
  url_field = cfg.get("urlField") or _auto_url_field(t, fkey)
1143
  if not url_field:
1144
- return ("error", "the automation column has no URL field bound to it", {}, [])
 
 
1145
  rows = dict(t.get("rows") or {})
1146
  # the relational tables the pull lands in (R7): every row timestamped for time-range filters
1147
- snap_key = ut_ensure(rt, "IG snapshots", SNAPSHOT_FIELDS, username, key="ut_ig_snapshots")
1148
- post_key = ut_ensure(rt, "IG posts", POST_FIELDS, username, key="ut_ig_posts")
1149
- ps_key = ut_ensure(rt, "IG post snapshots", POST_SNAPSHOT_FIELDS, username,
1150
- key="ut_ig_post_snapshots")
 
 
 
 
1151
  snaps = dict((ut_get(rt, snap_key) or {}).get("rows") or {})
1152
  posts = dict((ut_get(rt, post_key) or {}).get("rows") or {})
1153
  psnaps = dict((ut_get(rt, ps_key) or {}).get("rows") or {})
1154
 
1155
  counts = {"profiles": 0, "ok": 0, "partial": 0, "blocked": 0, "error": 0,
1156
- "posts": 0, "new_posts": 0}
1157
  cells, affected, notes = {}, [], []
 
 
 
 
 
 
1158
  targets = [(rid, str(r.get(url_field, "") or "").strip())
1159
  for rid, r in rows.items() if str(r.get(url_field, "") or "").strip()]
1160
  for i, (rid, url) in enumerate(targets):
1161
  if i:
1162
  time.sleep(PACE_SECONDS) # β‰₯2 s between profiles (R7)
1163
  counts["profiles"] += 1
1164
- res = pull_profile(url, max_posts=cfg.get("maxPosts") or 24, log=log)
 
1165
  pulled = _iso()
1166
- if res["state"] == "ok" or res["state"] == "partial":
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1167
  counts["ok" if res["state"] == "ok" else "partial"] += 1
1168
  prof = res["profile"]
1169
- snaps, _c = upsert_rows(
1170
- snaps, [{"snapshot_key": f"{prof['username']}@{pulled}",
1171
- "influencer_key": prof["username"], "pulled_at": pulled,
1172
- "followers": _s(prof.get("followers")), "following": _s(prof.get("following")),
1173
- "posts_count": _s(prof.get("posts_count")), "full_name": _s(prof.get("full_name")),
1174
- "bio": _s(prof.get("bio"), 500), "verified": _s(prof.get("verified")),
1175
- "source": _s(res.get("via")), "approx": _s(prof.get("approx"))}],
1176
- "snapshot_key")
1177
- new_posts = 0
1178
  for p in res.get("posts") or []:
1179
- posts, pc = upsert_rows(posts, [{
1180
  "shortcode": p["shortcode"], "influencer_key": prof["username"],
1181
  "posted_at": _s(p.get("posted_at")), "type": _s(p.get("type")),
1182
- "caption": _s(p.get("caption"), 800), "url": _s(p.get("url"), 300),
1183
- }], "shortcode")
1184
- new_posts += pc["inserted"]
1185
- psnaps, _pc = upsert_rows(psnaps, [{
1186
  "post_snapshot_key": f"{p['shortcode']}@{pulled}",
1187
  "shortcode": p["shortcode"], "pulled_at": pulled,
1188
  "likes": _s(p.get("likes")), "comments": _s(p.get("comments")),
1189
- }], "post_snapshot_key")
1190
  counts["posts"] += len(res.get("posts") or [])
1191
- counts["new_posts"] += new_posts
1192
  detail = f"{prof.get('followers') or '?'} followers"
 
 
1193
  if res.get("posts"):
1194
  detail += f", {len(res['posts'])} posts"
1195
  elif res["state"] == "partial":
1196
- detail += ", posts not anonymously readable"
1197
  cells[rid] = f"{res['state']} Β· {_stamp()} Β· {detail}"
1198
  elif res["state"] == "blocked":
1199
  counts["blocked"] += 1
@@ -1205,19 +1661,30 @@ def run_field_instagram(rt, defn, username="automation", log=print):
1205
  notes.append(res.get("note") or "error")
1206
  affected.append(rid)
1207
 
1208
- def _up(cur):
1209
- cur = cur if isinstance(cur, dict) else {}
1210
- tt = cur.get(table_key)
1211
- if tt is not None:
1212
- for rid, val in cells.items():
1213
- tt.setdefault("rows", {}).setdefault(str(rid), {})[fkey] = val
1214
- for k, rws in ((snap_key, snaps), (post_key, posts), (ps_key, psnaps)):
1215
- tgt = cur.get(k)
1216
- if tgt is not None:
1217
- tgt["rows"] = rws
1218
- return cur
 
 
 
 
 
 
 
 
 
 
 
 
1219
 
1220
- rt.update(UT_STORE_KEY, _up, flush="sync") # ONE coalesced update for all four tables
1221
  # ⚠ A RUN IS ONLY 'ok' IF EVERY PROFILE WAS. The first live run rolled up to 'ok' while
1222
  # every CELL said `partial`, because the rollup only asked about blocked/error β€” so the rail
1223
  # showed a green dot over a table with no posts in it. A summary that disagrees with the
@@ -1230,15 +1697,42 @@ def run_field_instagram(rt, defn, username="automation", log=print):
1230
  state = "partial"
1231
  else:
1232
  state = "ok"
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1233
  summary = (f"{read}/{counts['profiles']} profiles read, {counts['posts']} posts "
1234
  f"({counts['new_posts']} new)")
 
 
1235
  if counts["partial"]:
1236
- summary += f", {counts['partial']} profile-only (posts not anonymously readable)"
1237
  if counts["blocked"]:
1238
- summary += f", {counts['blocked']} blocked by Instagram"
 
 
 
 
 
 
 
 
 
 
 
1239
  if notes:
1240
  summary += f" β€” {notes[0][:120]}"
1241
- return (state, summary, counts, affected)
1242
 
1243
 
1244
  def _auto_url_field(table, fkey):
@@ -1258,6 +1752,164 @@ def _auto_url_field(table, fkey):
1258
  RUNNERS = {"scrape_db": run_scrape_db, "field_instagram": run_field_instagram}
1259
 
1260
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1261
  def run_now(rt, tenant, auto_id, username="automation", log=print):
1262
  """Execute one automation SYNCHRONOUSLY. The route wraps this in a thread; the tick calls it
1263
  directly. Returns the run entry, or None when it was already running (the 409)."""
@@ -1273,14 +1925,16 @@ def run_now(rt, tenant, auto_id, username="automation", log=print):
1273
  return _commit_run(rt, auto_id, "error",
1274
  f"unknown automation kind {defn.get('kind')!r}", {}, False)
1275
  try:
1276
- state, summary, counts, affected = runner(rt, defn, username=username, log=log)
 
1277
  except Refused as e:
1278
  return _commit_run(rt, auto_id, "error", f"refused: {e}", {}, False)
1279
  except Exception as e: # noqa: BLE001
1280
  log(f"[aios-auto] run {auto_id} failed: {type(e).__name__}: {e}")
1281
  return _commit_run(rt, auto_id, "error",
1282
  f"{type(e).__name__}: {str(e)[:200]}", {}, False)
1283
- return _commit_run(rt, auto_id, state, summary, counts, state != "error", affected)
 
1284
  finally:
1285
  _release(tenant, auto_id)
1286
 
 
59
  MAX_UT_ROWS = 5000 # mirrors core.user_tables.MAX_ROWS
60
  MAX_UT_TABLES = 40
61
 
62
+ #: ⚠ THE APPEND TABLES NEED A DIFFERENT CAP, and the reason is arithmetic rather than taste.
63
+ #: `MAX_UT_ROWS` was sized for a scraped LIST β€” a page of ~500 companies that is re-read, so the
64
+ #: row count is bounded by the page. The `ut_ig_*` tables are the opposite shape: every pull
65
+ #: INSERTS a timestamped row (see `SNAPSHOT_FIELDS` and the compound keys below), so at R1's
66
+ #: 1k-profiles-daily the snapshot table crosses 5000 rows on **day five** β€” and the old behaviour
67
+ #: was a SILENT `skipped++`, i.e. the table would quietly stop growing and the run would still
68
+ #: report success. A time series that stops after five days without saying so is worse than one
69
+ #: that was never built.
70
+ #: 200k is the owner-directed ceiling (R1's "~200k"). ⚠ IT BUYS VERY DIFFERENT HORIZONS FOR THE
71
+ #: TWO APPEND TABLES, and the difference is worth knowing before anyone plans around it:
72
+ #: ut_ig_snapshots 1 row per profile per pull -> ~200 days at 1k profiles/day
73
+ #: ut_ig_post_snapshots maxPosts rows per pull -> ~8 days at 1k profiles x 24 posts
74
+ #: So the post series is the one that fills, and it fills FAST. That is exactly why the breach had
75
+ #: to become LOUD (a distinct `capped` count -> a `partial` run naming the table): at this rate the
76
+ #: silent version would have flatlined a chart inside a fortnight with a green dot over it.
77
+ #:
78
+ #: ⚠ MEASURED COST AT THE CEILING (2026-08-04, this box): a full `ut_ig_post_snapshots` serialises
79
+ #: to **35.8 MB** of JSON (~1.4 s). `UT_STORE_KEY` is ONE bucket for ALL of a tenant's user tables,
80
+ #: so that cost is paid by every unrelated automation write in the tenant too. Booked for the B-3
81
+ #: Postgres tripwires (R2 clause b) rather than papered over β€” the fix is a row store, not a
82
+ #: smaller number.
83
+ #: (W19-C; the GENERIC loud-breach for every other table stays booked as DEBT D-11.)
84
+ MAX_UT_IG_ROWS = 200_000
85
+ IG_TABLE_PREFIX = "ut_ig_"
86
+
87
  KINDS = ("scrape_db", "field_instagram")
88
  EXTRACTS = ("table", "jsonld")
89
  STATES = ("idle", "running", "ok", "error", "partial")
90
+ #: Which capture rung a `field_instagram` automation is allowed to reach for (R1's hybrid).
91
+ #: `anonymous` = the $0 ladder only. `hiker` = the paid rung FIRST, then the ladder as a fallback
92
+ #: (unless the fallback is switched off β€” see `graph`'s `fallback` toggle).
93
+ TIERS = ("anonymous", "hiker")
94
+
95
+
96
+ def row_cap(table_key):
97
+ """The row ceiling for ONE table. Per-table rather than global β€” see `MAX_UT_IG_ROWS`."""
98
+ return MAX_UT_IG_ROWS if str(table_key or "").startswith(IG_TABLE_PREFIX) else MAX_UT_ROWS
99
 
100
  #: Schedule presets the editor offers. Kept here (not in the client) so the vocabulary the UI
101
  #: shows and the vocabulary the parser accepts cannot drift.
 
476
  # THE UPSERT β€” pure, so the arithmetic is testable without a store or a network
477
  # ---------------------------------------------------------------------------------------------
478
 
479
+ def upsert_rows(existing, incoming, key_field, cap=None):
480
  """Merge scraped rows into a user table's rows BY KEY. Returns `(rows, counts)`.
481
 
482
  THE RULE THAT MATTERS: **an orphan is COUNTED, NEVER DELETED.** A row that has stopped
 
486
  columns the scrape never touches. So the run reports `orphans: N` and leaves them alone.
487
 
488
  Only MAPPED keys are written: a re-run never clobbers a column a user added by hand.
489
+
490
+ ⚠ CALL THIS ONCE PER TABLE PER RUN, NOT ONCE PER ROW. It rebuilds the whole row dict on
491
+ entry, so it is O(existing) per call β€” fine once, quadratic in a loop. The IG runner used to
492
+ call it per POST, which was survivable only because the cap was 5000; against `MAX_UT_IG_ROWS`
493
+ that same loop is hundreds of millions of dict copies and the automation simply never
494
+ finishes. Raising a cap and batching the writer are ONE change, not two. (W19-C.)
495
+
496
+ ⚠ `capped` IS ITS OWN COUNT, deliberately not folded into `skipped`. They are different
497
+ facts: `skipped` means "this row had no key, so it could not be upserted" β€” a property of the
498
+ DATA, and usually benign. `capped` means "this table is full and the run is now losing rows" β€”
499
+ a property of the SYSTEM, and never benign. One number for both meant a table hitting its
500
+ ceiling was indistinguishable from a page with a few blank cells, which is how a time series
501
+ stops silently. The runners turn any `capped` into a `partial` run that NAMES the table.
502
  """
503
+ cap = MAX_UT_ROWS if cap is None else int(cap)
504
  rows = {str(k): dict(v or {}) for k, v in (existing or {}).items()}
505
  counts = {"inserted": 0, "updated": 0, "unchanged": 0,
506
+ "skipped": 0, "duplicates": 0, "orphans": 0, "capped": 0}
507
  by_key, dupe_ids = {}, set()
508
  for rid, row in rows.items():
509
  kv = str(row.get(key_field, "") or "").strip()
 
526
  seen_keys.add(kv)
527
  rid = by_key.get(kv)
528
  if rid is None:
529
+ if len(rows) >= cap:
530
+ counts["capped"] += 1 # LOUD: the runner turns this into a partial run
531
  continue
532
  rid = str(next_id)
533
  next_id += 1
 
568
  return ut_all(rt).get(str(key))
569
 
570
 
571
+ def ut_key_for(label, key=None):
572
+ """The table key a label resolves to. Factored out of `ut_ensure` so the DRY-RUN path (which
573
+ must not create anything) resolves the same key by construction rather than by copying the
574
+ derivation and drifting from it."""
575
+ k = str(key or (UT_PREFIX + _ut_slug(label)))
576
+ return k if k.startswith(UT_PREFIX) else UT_PREFIX + k
577
+
578
+
579
  def ut_ensure(rt, label, fields, username="automation", key=None):
580
  """Create the table if it is missing; return its key. Idempotent β€” a re-run of an automation
581
  that owns a table must not spawn `ut_x_2`, so the key is DERIVED from the label (or given)
 
584
  Fields are MERGED, never replaced: a user who added a column to an automation's table keeps
585
  it, and a new source column joins on the next run.
586
  """
587
+ key = ut_key_for(label, key)
 
 
588
  wanted = list(fields or [])
589
  created = _iso()
590
 
 
658
  return str(v if v is not None else "")[:n]
659
 
660
 
661
+ def clean_config(kind, raw, previous=None):
662
+ """Validate a kind's config. Returns `(config, error)`; error is a user-facing sentence.
663
+
664
+ ⚠ THE NODE-SWITCH FLAGS FALL BACK TO `previous` WHEN THE KEY IS ABSENT, and that is a rail
665
+ rather than a nicety. `patch` replaces the whole config, and the canvas's config panels do not
666
+ edit `tier` / `noFallback` / `dryRun` β€” those are node SWITCHES. So a plain "Save" from a
667
+ panel that never knew about them would silently reset the paid rung to `anonymous` and turn
668
+ off the dry run: a save that quietly changes what the automation costs. Absent β‡’ keep;
669
+ present β‡’ take it, including `false`.
670
+ """
671
  raw = raw if isinstance(raw, dict) else {}
672
+ prev = previous if isinstance(previous, dict) else {}
673
+
674
+ def flag(name):
675
+ return bool(raw[name]) if name in raw else bool(prev.get(name))
676
  if kind == "scrape_db":
677
  url = _s(raw.get("url"), 2000).strip()
678
  if not url:
 
699
  "tableIndex": max(0, min(int(raw.get("tableIndex") or 0), 50)),
700
  "fieldMap": fmap, "keyField": key_field,
701
  "targetTable": target,
702
+ "dryRun": flag("dryRun"),
703
  "targetLabel": _s(raw.get("targetLabel"), 60).strip() or "Scraped table"}, None
704
  if kind == "field_instagram":
705
  table = _s(raw.get("targetTable"), 60).strip()
 
710
  return None, "pick the automation column this run writes into"
711
  return {"targetTable": table, "fieldKey": fkey,
712
  "urlField": _s(raw.get("urlField"), 80).strip(),
713
+ # ⚠ UNKNOWN TIERS FALL BACK TO `anonymous`, NOT to the paid rung. A typo must
714
+ # never be the thing that starts spending money. An ABSENT tier keeps the one
715
+ # already stored (see the `flag` note above).
716
+ "tier": (raw["tier"] if raw.get("tier") in TIERS
717
+ else prev.get("tier") if "tier" not in raw and prev.get("tier") in TIERS
718
+ else "anonymous"),
719
+ "noFallback": flag("noFallback"),
720
+ "dryRun": flag("dryRun"),
721
  "maxPosts": max(1, min(int(raw.get("maxPosts") or 24), 200))}, None
722
  return None, f"unknown automation kind {kind!r}"
723
 
 
747
  if not name:
748
  return None, "name the automation"
749
  cfg_raw = raw.get("config") if isinstance(raw.get("config"), dict) else prev.get("config")
750
+ config, err = clean_config(kind, cfg_raw, prev.get("config"))
751
  if err:
752
  return None, err
753
  try:
 
862
  _RUNNING.pop((tenant, str(auto_id)), None)
863
 
864
 
865
+ def _commit_run(rt, auto_id, state, summary, counts, ok, affected=None, steps=None):
866
+ """THE ONE store write a run performs on the `automations` bucket.
867
+
868
+ `steps` is the per-NODE outcome map the canvas paints its dots from. It is recorded here
869
+ because it is a MEASUREMENT the runner took as it walked β€” see `graph`, which refuses to
870
+ invent a node status when this map is absent (every run stored before W19-C has no `steps`,
871
+ and painting those nodes green from the run's overall state would be a fabrication).
872
+ """
873
  entry = {"ts": _iso(), "ok": bool(ok), "summary": _s(summary, 400),
874
  "counts": {k: int(v) for k, v in (counts or {}).items()
875
  if isinstance(v, (int, float))},
876
+ "steps": {str(k): str(v) for k, v in (steps or {}).items()},
877
  "affected": list(affected or [])[:200]}
878
 
879
  def _up(cur):
 
891
 
892
 
893
  # ---------------------------------------------------------------------------------------------
894
+ # INSTAGRAM (R7, extended by R1) β€” PUBLIC DATA ONLY, NEVER AN INSTAGRAM LOGIN
895
  # ---------------------------------------------------------------------------------------------
896
+ # ⚠ AMENDED W19-C. This section read "ANONYMOUS PUBLIC ENDPOINTS ONLY" and that is no longer the
897
+ # whole truth: R1 added a paid VENDOR rung (HikerAPI, further down) which does authenticate β€” to
898
+ # the vendor. The rail that actually matters is unchanged and is the sharper statement of it:
899
+ #
900
+ # **NOTHING HERE EVER AUTHENTICATES TO INSTAGRAM.** No login, no password, no session cookie,
901
+ # no account to get banned, public data only. The vendor key is a key to a SUPPLIER, and the
902
+ # supplier takes the scraping risk; it is never an Instagram credential and this module must
903
+ # never be given one.
904
+ #
905
+ # The rungs below this line are the ANONYMOUS ladder ($0, no key of any kind).
906
  #
907
  # ⚠ HONEST STATUSES ARE THE FEATURE. Instagram rate-limits and outright blocks datacenter egress
908
  # (the HF Space and any AWS Lambda are both in that class), and its anonymous surface has been
 
924
  field_def("full_name", "Name"), field_def("bio", "Bio"),
925
  field_def("verified", "Verified"), field_def("source", "Read via"),
926
  field_def("approx", "Counts are approximate"),
927
+ # The link in bio β€” the paid rung's field, and commercially the most useful single string an
928
+ # influencer row can carry (it is the shop/affiliate destination). Blank on the anonymous
929
+ # rungs, which do not expose it; a blank here means "not read", never "they have none".
930
+ field_def("external_url", "Link in bio", "url"),
931
  ]
932
  POST_FIELDS = [
933
  field_def("shortcode", "Shortcode"), field_def("influencer_key", "Influencer"),
 
938
  field_def("post_snapshot_key", "Snapshot"), field_def("shortcode", "Shortcode"),
939
  field_def("pulled_at", "Pulled at"), field_def("likes", "Likes"),
940
  field_def("comments", "Comments"),
941
+ # Plays/views move independently of likes on video, so it is its own series rather than a
942
+ # thing to derive. Paid rung only; blank means not read.
943
+ field_def("views", "Views"),
944
  ]
945
 
946
 
 
1043
  return None
1044
 
1045
 
1046
+ # ---------------------------------------------------------------------------------------------
1047
+ # HIKERAPI β€” THE PAID RUNG (owner ruling R1, contract C4)
1048
+ # ---------------------------------------------------------------------------------------------
1049
+ # WHY A VENDOR AT ALL, stated once so nobody re-opens it: the anonymous ladder above is honest but
1050
+ # it is ALSO geographically fenced β€” Instagram blocks datacenter egress, so from the HF Space or a
1051
+ # Lambda the ladder degrades to `blocked` and the whole automation becomes a thing that only works
1052
+ # on the owner's desk. HikerAPI takes the egress risk, returns EXACT counts (not og:description's
1053
+ # "204K") and reaches post-level data the anonymous surface has closed. ~$0.0006/req.
1054
+ #
1055
+ # β›” FOUR RAILS, and each one is a failure mode rather than a preference:
1056
+ # 1. **FAIL-CLOSED on the key.** No `AIOS_HIKERAPI_KEY` β‡’ this rung refuses with an honest
1057
+ # blocked ATTEMPT and the anonymous ladder still runs. Never a crash, never a silent skip.
1058
+ # 2. **The key is never logged, never in a URL, never in an exception.** It travels in the
1059
+ # `x-access-key` header only, and every error below quotes a STATUS, never the request. A
1060
+ # secret that reaches a log line has leaked to everyone who can read logs.
1061
+ # 3. **The base URL is guarded like any other.** `AIOS_HIKERAPI_BASE` is env-provided, so it
1062
+ # goes through the same SSRF rail β€” an env var pointed at the metadata endpoint would
1063
+ # otherwise be a credential-bearing request to it.
1064
+ # 4. **A rung failure is a RUNG failure.** `hiker_get` swallows its own `Refused`/transport
1065
+ # errors, because `run_now` turns a `Refused` into a whole-run error β€” and a mistyped base
1066
+ # URL must not kill a run whose anonymous rung would have answered.
1067
+ #
1068
+ # ⚠ THE KEY IS READ LAZILY, INSIDE THE CALL. A module-level snapshot would be taken at import,
1069
+ # which makes the "key absent β‡’ blocked, not crash" gate untestable (nothing could flip it between
1070
+ # checks) and would also mean a deploy that sets the secret after import silently has no key.
1071
+
1072
+ #: Pinned from the live OpenAPI spec (`https://api.hikerapi.com/openapi.json`, read 2026-08-04) β€”
1073
+ #: see `.claude/wiki/research/instagram-capture.md` for the full mapping and its provenance tags.
1074
+ #: They live in ONE named block so a vendor rename is a one-line fix rather than a hunt.
1075
+ HIKER_BASE_DEFAULT = "https://api.hikerapi.com"
1076
+ HIKER_PATH_USER = "/v1/user/by/username" # -> exact counts + bio. param: username
1077
+ HIKER_PATH_MEDIAS = "/v1/user/medias/chunk" # -> posts. params: user_id, end_cursor
1078
+ HIKER_TIMEOUT = 30.0
1079
+ #: ⚠ NO PAGE-SIZE CONSTANT. The chunk endpoint takes `user_id` and `end_cursor` only β€” the page
1080
+ #: size is the vendor's to choose. A `HIKER_PAGE = 50` sat here unused, which reads as a parameter
1081
+ #: somebody forgot to send rather than one that does not exist.
1082
+
1083
+
1084
+ def hiker_key():
1085
+ """The key, or ''. Read fresh every call β€” see the module note above on why."""
1086
+ return (os.environ.get("AIOS_HIKERAPI_KEY") or "").strip()
1087
+
1088
+
1089
+ def hiker_base():
1090
+ return (os.environ.get("AIOS_HIKERAPI_BASE") or HIKER_BASE_DEFAULT).strip().rstrip("/")
1091
+
1092
+
1093
+ def hiker_ready():
1094
+ """Is the paid rung configured at all? The UI reads this to say so honestly."""
1095
+ return bool(hiker_key())
1096
+
1097
+
1098
+ def hiker_get(path, params=None):
1099
+ """One authenticated GET. Returns `(payload, note)`; a non-empty `note` means it did NOT
1100
+ answer, and the note is safe to show a user and safe to write to a log.
1101
+
1102
+ Never raises. Every refusal shape β€” no key, a guarded base, a 402 out of credit, a 429, a
1103
+ transport error, unparseable JSON β€” comes back as a note so the caller can record the attempt
1104
+ and drop to the next rung.
1105
+ """
1106
+ key = hiker_key()
1107
+ if not key:
1108
+ # β›” THE FAIL-CLOSED PATH (C4). Named precisely, because "blocked" with no reason sends
1109
+ # somebody to read Instagram's status page instead of setting an env var.
1110
+ return None, "AIOS_HIKERAPI_KEY is not configured β€” the paid rung is closed"
1111
+ qs = "&".join(f"{k}={requests.utils.quote(str(v))}"
1112
+ for k, v in (params or {}).items() if v not in (None, ""))
1113
+ url = f"{hiker_base()}{path}" + (f"?{qs}" if qs else "")
1114
+ try:
1115
+ status, _final, body = fetch(url, timeout=HIKER_TIMEOUT, max_kb=8192,
1116
+ headers={"x-access-key": key, "Accept": "application/json"})
1117
+ except Refused as e:
1118
+ # The BASE was refused by the SSRF rail β€” a configuration fault, not a vendor outage.
1119
+ return None, f"the HikerAPI base URL was refused by the URL rail: {e}"
1120
+ except Exception as e: # noqa: BLE001
1121
+ # ⚠ `type(e).__name__` only. A requests exception's str() can carry the full URL, and one
1122
+ # day somebody will move the key into a query param; this line must not be what leaks it.
1123
+ return None, f"HikerAPI did not answer ({type(e).__name__})"
1124
+ if status == 402:
1125
+ return None, "HikerAPI answered 402 β€” the account is out of credit"
1126
+ if status == 401 or status == 403:
1127
+ return None, f"HikerAPI refused the key ({status})"
1128
+ if status == 429:
1129
+ return None, "HikerAPI answered 429 β€” rate limited"
1130
+ if not (200 <= status < 300):
1131
+ return None, f"HikerAPI answered {status}"
1132
+ try:
1133
+ return json.loads(body.decode("utf-8", "replace")), ""
1134
+ except Exception: # noqa: BLE001
1135
+ return None, "HikerAPI answered with something that is not JSON"
1136
+
1137
+
1138
+ def _first(node, *names, default=None):
1139
+ """The first of `names` present on `node` with a real value.
1140
+
1141
+ ⚠ THE TOLERANCE IS THE POINT, not laziness. The vendor's `components/schemas` was not readable
1142
+ on 2026-08-04 (recorded as RECALLED in the digest), so every media field name below is a
1143
+ hypothesis. Reading through a candidate list means a rename costs one more candidate instead
1144
+ of a rung that returns nothing and cannot say why. **A field that matches nothing returns
1145
+ `default` (None), never 0** β€” an invented zero is a measurement, and this module's whole
1146
+ honest-status contract exists to stop those.
1147
+ """
1148
+ if not isinstance(node, dict):
1149
+ return default
1150
+ for n in names:
1151
+ v = node.get(n)
1152
+ if v not in (None, ""):
1153
+ return v
1154
+ return default
1155
+
1156
+
1157
+ def _hiker_profile(node, handle):
1158
+ """The vendor's user object β†’ our snapshot shape. CONFIRMED names (vendor quick-start,
1159
+ 2026-08-04): pk, username, full_name, is_private, is_verified, media_count, follower_count,
1160
+ following_count, biography. `external_url` is RECALLED β€” hence the candidates."""
1161
+ return {
1162
+ "username": _first(node, "username", default=handle),
1163
+ "full_name": _first(node, "full_name", "fullname", default="") or "",
1164
+ "bio": _first(node, "biography", "bio", default="") or "",
1165
+ "followers": _ig_int(_first(node, "follower_count", "followers", "followers_count")),
1166
+ "following": _ig_int(_first(node, "following_count", "following", "followings_count")),
1167
+ "posts_count": _ig_int(_first(node, "media_count", "posts_count", "post_count")),
1168
+ "verified": "1" if _first(node, "is_verified", default=False) else "",
1169
+ "external_url": _first(node, "external_url", "external_link", default="") or "",
1170
+ # β›” NO `approx` KEY. These counts are exact, and carrying the anonymous rung's rounding
1171
+ # tag onto them would be a lie in the other direction (R1: "drop the approx tag when
1172
+ # exact"). Its ABSENCE is what tells the snapshot row it is trustworthy.
1173
+ }
1174
+
1175
+
1176
+ def _hiker_user_id(node):
1177
+ return str(_first(node, "pk", "id", "pk_id", default="") or "")
1178
+
1179
+
1180
+ #: instagrapi-family media_type ints. `product_type == "clips"` is a reel, which is still a video.
1181
+ _HIKER_MEDIA_TYPES = {1: "image", 2: "video", 8: "carousel"}
1182
+
1183
+
1184
+ def _hiker_post(m):
1185
+ """One vendor media object β†’ our post shape (the same shape `_posts_from_edges` returns, so
1186
+ everything downstream is rung-agnostic). Returns None when it has no shortcode β€” a post that
1187
+ cannot be deduped cannot be appended to a time series."""
1188
+ code = _first(m, "code", "shortcode", default="")
1189
+ if not code:
1190
+ return None
1191
+ raw_type = _first(m, "media_type", "type")
1192
+ kind = _HIKER_MEDIA_TYPES.get(raw_type) if isinstance(raw_type, int) else None
1193
+ if kind is None:
1194
+ kind = str(raw_type or "").lower() or "image"
1195
+ if kind not in ("image", "video", "carousel"):
1196
+ kind = "video" if kind in ("clips", "igtv", "reel", "reels") else "image"
1197
+ taken = _first(m, "taken_at", "taken_at_timestamp", "device_timestamp")
1198
+ if isinstance(taken, (int, float)):
1199
+ try:
1200
+ posted = _dt.datetime.fromtimestamp(taken).strftime("%Y-%m-%d %H:%M")
1201
+ except Exception: # noqa: BLE001
1202
+ posted = ""
1203
+ else: # an ISO string ("2026-01-01T00:00:00+00:00")
1204
+ posted = str(taken or "").replace("T", " ")[:16]
1205
+ caption = _first(m, "caption_text", "caption")
1206
+ if isinstance(caption, dict):
1207
+ caption = _first(caption, "text", default="")
1208
+ return {
1209
+ "shortcode": str(code),
1210
+ "posted_at": posted,
1211
+ "type": kind,
1212
+ "caption": str(caption or ""),
1213
+ "url": f"https://www.instagram.com/p/{code}/",
1214
+ # ⚠ NO `like_and_view_counts_disabled` CANDIDATE, however like-shaped its name is: it is
1215
+ # a BOOLEAN in this family of schemas, and `_ig_int(True)` is 1 β€” so a post with likes
1216
+ # hidden would have reported "1 like". A candidate list must only ever contain fields of
1217
+ # the same TYPE as the thing it is reading.
1218
+ "likes": _ig_int(_first(m, "like_count", "likes")),
1219
+ "comments": _ig_int(_first(m, "comment_count", "comments")),
1220
+ "views": _ig_int(_first(m, "play_count", "view_count", "video_play_count", "views")),
1221
+ }
1222
+
1223
+
1224
+ def _hiker_media_items(payload):
1225
+ """Unwrap a chunk answer into `(items, cursor)`.
1226
+
1227
+ The chunk shape is RECALLED (see the digest), so all four plausible envelopes are accepted:
1228
+ a bare list, `[items, cursor]`, `{"response": {"items": [...]}}`, and `{"items": [...]}`.
1229
+ """
1230
+ cursor = ""
1231
+ if isinstance(payload, list):
1232
+ # `[items, next_cursor]` β€” the instagrapi chunk convention β€” vs. a plain list of medias.
1233
+ if (len(payload) == 2 and isinstance(payload[0], list)
1234
+ and isinstance(payload[1], (str, type(None)))):
1235
+ return [x for x in payload[0] if isinstance(x, dict)], str(payload[1] or "")
1236
+ return [x for x in payload if isinstance(x, dict)], ""
1237
+ if isinstance(payload, dict):
1238
+ inner = payload.get("response") if isinstance(payload.get("response"), dict) else payload
1239
+ items = _first(inner, "items", "medias", "data", default=[])
1240
+ # β›” LOOK FOR THE CURSOR AT BOTH LEVELS. It was read from `payload` only, so a
1241
+ # `{"response": {"items": [...], "next_max_id": "..."}}` envelope β€” where the cursor sits
1242
+ # NEXT TO the items, one level in β€” resolved to "", the caller's `if not cursor: break`
1243
+ # fired, and a `maxPosts=200` pull returned ONE chunk and reported `ok`. A green run that
1244
+ # silently fetched a quarter of what was asked for is precisely the failure this module's
1245
+ # honest-status contract exists to prevent, and it arrives through the RECALLED half of
1246
+ # the vendor schema β€” which is the half that has to be read defensively at every level.
1247
+ for src in (inner, payload):
1248
+ cursor = str(_first(src, "next_cursor", "end_cursor", "next_page_id",
1249
+ "next_max_id", default="") or "")
1250
+ if cursor:
1251
+ break
1252
+ if isinstance(items, list):
1253
+ return [x for x in items if isinstance(x, dict)], cursor
1254
+ return [], cursor
1255
+
1256
+
1257
+ def pull_profile_hiker(url, max_posts=24, log=print):
1258
+ """The paid rung: one profile, EXACT counts, and posts the anonymous surface will not give.
1259
+
1260
+ Same return contract as `pull_profile` (`{state, profile, posts, via, note}`) so the runner
1261
+ treats every rung identically. `blocked` here means the VENDOR rung did not answer β€” the
1262
+ caller decides whether to drop to the anonymous ladder.
1263
+ """
1264
+ handle = ig_handle(url)
1265
+ if not handle:
1266
+ return {"state": "error", "note": f"{url!r} is not an Instagram profile URL",
1267
+ "profile": {}, "posts": [], "via": ""}
1268
+ payload, note = hiker_get(HIKER_PATH_USER, {"username": handle})
1269
+ if note:
1270
+ return {"state": "blocked", "profile": {}, "posts": [], "via": "hikerapi",
1271
+ "note": note}
1272
+ node = payload if isinstance(payload, dict) else {}
1273
+ node = node.get("user") if isinstance(node.get("user"), dict) else node
1274
+ profile = _hiker_profile(node, handle)
1275
+ if profile.get("followers") is None and profile.get("posts_count") is None:
1276
+ # It answered 200 with something we could not read. Say THAT β€” not "0 followers".
1277
+ return {"state": "blocked", "profile": {}, "posts": [], "via": "hikerapi",
1278
+ "note": "HikerAPI answered, but no follower/post counts were readable in it "
1279
+ "(the field names may have moved β€” see instagram-capture.md)"}
1280
+ posts, cursor, pages = [], "", 0
1281
+ user_id = _hiker_user_id(node)
1282
+ while user_id and len(posts) < max_posts and pages < 20:
1283
+ pages += 1
1284
+ page, mnote = hiker_get(HIKER_PATH_MEDIAS,
1285
+ {"user_id": user_id, "end_cursor": cursor})
1286
+ if mnote:
1287
+ note = mnote
1288
+ break
1289
+ items, cursor = _hiker_media_items(page)
1290
+ if not items:
1291
+ break
1292
+ for m in items:
1293
+ p = _hiker_post(m)
1294
+ if p:
1295
+ posts.append(p)
1296
+ if not cursor:
1297
+ break
1298
+ time.sleep(min(PACE_SECONDS, 1.0)) # the vendor is paid, but it is still someone's API
1299
+ posts = posts[:max_posts]
1300
+ # IDENTITY WITHOUT MEDIA IS STILL `partial`, on the paid rung too. The rule does not soften
1301
+ # because we are paying: a run that wrote a follower count and no posts must not paint green
1302
+ # over a posts table that did not grow.
1303
+ return {"state": "ok" if posts else "partial", "profile": profile, "posts": posts,
1304
+ "via": "hikerapi",
1305
+ "note": note or ("" if posts else "profile read; HikerAPI returned no medias")}
1306
+
1307
+
1308
+ def pull_profile(url, max_posts=24, log=print, tier="anonymous", fallback=True):
1309
+ """Everything readable about one public profile, cheapest-honest rung last.
1310
 
1311
  Returns `{state, profile, posts, via, note}` with state ∈ ok | partial | blocked | error.
1312
  `partial` means the identity was read but the media was not β€” which is the outcome the
1313
  anonymous surface most often gives, and saying so is the point.
1314
+
1315
+ **RUNG 0 IS THE PAID ONE (R1's hybrid).** With `tier="hiker"` HikerAPI is tried FIRST and,
1316
+ when it answers, this returns exact counts with no `approx` tag. When it does not answer the
1317
+ attempt is RECORDED and the anonymous ladder runs underneath it β€” that is what "fail-closed
1318
+ on the key, and the anonymous rung still works" means in C4.
1319
+
1320
+ `fallback=False` turns that safety net off on purpose: it means *"exact numbers or nothing"*.
1321
+ An influencer table where some rows are exact and some are `og:description` roundings, with
1322
+ no way to tell them apart at a glance, is a table you cannot do arithmetic on β€” so a user who
1323
+ needs the guarantee can have it, and gets an honest `blocked` instead of a quiet downgrade.
1324
+ (The `source`/`approx` columns tell them apart anyway; this makes it impossible to forget.)
1325
  """
1326
  handle = ig_handle(url)
1327
  if not handle:
 
1329
  "profile": {}, "posts": [], "via": ""}
1330
  attempts = []
1331
 
1332
+ if tier == "hiker":
1333
+ paid = pull_profile_hiker(url, max_posts=max_posts, log=log)
1334
+ if paid["state"] in ("ok", "partial"):
1335
+ return paid
1336
+ attempts.append(f"hikerapi:{_s(paid.get('note'), 90)}")
1337
+ if not fallback:
1338
+ return {"state": "blocked", "profile": {}, "posts": [], "via": "hikerapi",
1339
+ "note": "the paid rung did not answer and the anonymous fallback is turned "
1340
+ f"off for this automation ({paid.get('note') or 'blocked'})"}
1341
+ time.sleep(PACE_SECONDS)
1342
+
1343
  # RUNG 1 β€” the web client's own profile endpoint. Public, no cookie; the one that used to
1344
  # carry both the profile AND the first page of media in a single answer.
1345
  api = f"https://www.instagram.com/api/v1/users/web_profile_info/?username={handle}"
 
1458
  # RUNNERS
1459
  # ---------------------------------------------------------------------------------------------
1460
 
1461
+ def cap_note(capped):
1462
+ """The sentence a cap breach adds to a run summary. `capped` = [(table_key, rows_lost), ...].
1463
+
1464
+ β›” IT NAMES THE TABLE. "142 rows skipped" sends somebody to look at the source page; "the
1465
+ ut_ig_post_snapshots database is FULL" sends them to the actual problem. A loud failure that
1466
+ does not say WHERE is only marginally better than a silent one.
1467
+ """
1468
+ return "; ".join(
1469
+ f"⚠ the {k} database is FULL ({row_cap(k):,} rows) β€” {n} row{'' if n == 1 else 's'} "
1470
+ f"from this run were NOT written" for k, n in capped if n)
1471
+
1472
+
1473
  def run_scrape_db(rt, defn, username="automation", log=print):
1474
  """Automation #1 (R6): a public page β†’ a blank database, re-runnable, UPSERT by key."""
1475
  cfg = defn.get("config") or {}
1476
  fmap, key_field = cfg.get("fieldMap") or {}, cfg.get("keyField")
1477
+ dry = bool(cfg.get("dryRun"))
1478
+ # Per-NODE outcomes for the canvas. MEASURED as the run walks, never inferred afterwards from
1479
+ # the rollup β€” inferring is exactly how a green dot ended up over an empty table (see the
1480
+ # rollup comment in `run_field_instagram`).
1481
+ steps = {"trigger": "ok", "fetch": "idle", "extract": "idle", "write": "idle"}
1482
  status, final, body = fetch(cfg["url"])
1483
  if not (200 <= status < 300):
1484
+ steps["fetch"] = "error"
1485
  return ("error", f"{cfg['url']} answered {status} β€” nothing was written",
1486
+ {"status": status}, [], steps)
1487
+ steps["fetch"] = "ok"
1488
  soup = _soup(body)
1489
  if cfg.get("extract") == "jsonld":
1490
  blocks = jsonld(soup)
 
1502
  idx = max(0, min(int(cfg.get("tableIndex") or 0), len(found) - 1)) if found else 0
1503
  raw_rows = [r for r in (found[idx] if found else []) if isinstance(r, dict)]
1504
  if not raw_rows:
1505
+ steps["extract"] = "error"
1506
+ return ("error", "the page parsed but the selected table had no rows", {"rows": 0}, [],
1507
+ steps)
1508
+ steps["extract"] = "ok"
1509
 
1510
  incoming = []
1511
  for r in raw_rows:
 
1517
  for src, tgt in fmap.items()]
1518
  # the key column leads, so the table opens on the identity it is upserted by
1519
  fields.sort(key=lambda f: 0 if f["key"] == key_field else 1)
1520
+ label = cfg.get("targetLabel") or defn.get("name") or "Scraped table"
1521
+ if dry:
1522
+ # THE WRITE NODE IS OFF β€” read, compute, report, touch nothing. Not even `ut_ensure`,
1523
+ # which would create the table: a dry run that leaves a new empty database behind is not
1524
+ # a dry run.
1525
+ table_key = ut_key_for(label, cfg.get("targetTable") or None)
1526
+ else:
1527
+ table_key = ut_ensure(rt, label, fields, username, key=cfg.get("targetTable") or None)
1528
  t = ut_get(rt, table_key) or {}
1529
+ rows, counts = upsert_rows(t.get("rows") or {}, incoming, key_field,
1530
+ cap=row_cap(table_key))
1531
+ if not dry:
1532
+ ut_write_rows(rt, table_key, rows)
1533
  counts["source_rows"] = len(incoming)
1534
  affected = [rid for rid, row in rows.items()
1535
  if str(row.get(key_field, "")) in {str(i.get(key_field)) for i in incoming}][:200]
1536
  summary = (f"{counts['inserted']} new, {counts['updated']} updated, "
1537
  f"{counts['unchanged']} unchanged, {counts['orphans']} no longer on the page "
1538
  f"(kept)")
1539
+ capped = [(table_key, counts.get("capped", 0))]
1540
+ note = cap_note(capped)
1541
+ if note:
1542
+ summary += f" β€” {note}"
1543
+ steps["write"] = "partial"
1544
+ if dry:
1545
+ summary = f"DRY RUN (the Write step is turned off) β€” would have written: {summary}"
1546
+ steps["write"] = "skipped"
1547
+ elif not note:
1548
+ steps["write"] = "ok"
1549
+ state = "partial" if (counts.get("capped") or counts.get("skipped") or dry) else "ok"
1550
  log(f"[aios-auto] scrape_db {defn.get('id')} -> {table_key}: {summary}")
1551
+ return (state, summary, counts, affected, steps)
1552
 
1553
 
1554
  def run_field_instagram(rt, defn, username="automation", log=print):
1555
+ """Automation #2 (R7 + R1's hybrid): for every row of a blank database that carries a profile
1556
+ URL, pull the public profile β€” the PAID rung first when the tier says so, the anonymous
1557
+ ladder underneath it β€” write a status string into the automation column, and append a
1558
+ timestamped row to each of the three IG tables."""
1559
  cfg = defn.get("config") or {}
1560
  table_key, fkey = cfg.get("targetTable"), cfg.get("fieldKey")
1561
+ tier = cfg.get("tier") if cfg.get("tier") in TIERS else "anonymous"
1562
+ fallback = not cfg.get("noFallback")
1563
+ dry = bool(cfg.get("dryRun"))
1564
+ steps = {"trigger": "ok", "source": "idle", "capture": "idle",
1565
+ "capture_hiker": "idle" if tier == "hiker" else "skipped",
1566
+ "capture_anon": "idle" if (tier != "hiker" or fallback) else "skipped",
1567
+ "write": "idle"}
1568
  t = ut_get(rt, table_key)
1569
  if not t:
1570
+ steps["source"] = "error"
1571
+ return ("error", f"{table_key} is not a database in this workspace", {}, [], steps)
1572
  url_field = cfg.get("urlField") or _auto_url_field(t, fkey)
1573
  if not url_field:
1574
+ steps["source"] = "error"
1575
+ return ("error", "the automation column has no URL field bound to it", {}, [], steps)
1576
+ steps["source"] = "ok"
1577
  rows = dict(t.get("rows") or {})
1578
  # the relational tables the pull lands in (R7): every row timestamped for time-range filters
1579
+ if dry:
1580
+ # The Write node is off: resolve the keys, create nothing. (`ut_ensure` writes.)
1581
+ snap_key, post_key, ps_key = ("ut_ig_snapshots", "ut_ig_posts", "ut_ig_post_snapshots")
1582
+ else:
1583
+ snap_key = ut_ensure(rt, "IG snapshots", SNAPSHOT_FIELDS, username, key="ut_ig_snapshots")
1584
+ post_key = ut_ensure(rt, "IG posts", POST_FIELDS, username, key="ut_ig_posts")
1585
+ ps_key = ut_ensure(rt, "IG post snapshots", POST_SNAPSHOT_FIELDS, username,
1586
+ key="ut_ig_post_snapshots")
1587
  snaps = dict((ut_get(rt, snap_key) or {}).get("rows") or {})
1588
  posts = dict((ut_get(rt, post_key) or {}).get("rows") or {})
1589
  psnaps = dict((ut_get(rt, ps_key) or {}).get("rows") or {})
1590
 
1591
  counts = {"profiles": 0, "ok": 0, "partial": 0, "blocked": 0, "error": 0,
1592
+ "posts": 0, "new_posts": 0, "paid": 0, "capped": 0}
1593
  cells, affected, notes = {}, [], []
1594
+ # β›” ACCUMULATE HERE, UPSERT ONCE PER TABLE AFTER THE LOOP. This used to call `upsert_rows`
1595
+ # once per POST, which is O(existing) per call β€” survivable only while the cap was 5000 rows.
1596
+ # `MAX_UT_IG_ROWS` makes the same loop hundreds of millions of dict copies, i.e. an automation
1597
+ # that no longer finishes. **Raising a cap and batching its writer are ONE change.** (W19-C.)
1598
+ in_snaps, in_posts, in_psnaps = [], [], []
1599
+ hiker_tried = hiker_answered = anon_tried = anon_answered = False
1600
  targets = [(rid, str(r.get(url_field, "") or "").strip())
1601
  for rid, r in rows.items() if str(r.get(url_field, "") or "").strip()]
1602
  for i, (rid, url) in enumerate(targets):
1603
  if i:
1604
  time.sleep(PACE_SECONDS) # β‰₯2 s between profiles (R7)
1605
  counts["profiles"] += 1
1606
+ res = pull_profile(url, max_posts=cfg.get("maxPosts") or 24, log=log,
1607
+ tier=tier, fallback=fallback)
1608
  pulled = _iso()
1609
+ via = res.get("via") or ""
1610
+ read_ok = res["state"] in ("ok", "partial")
1611
+ # WHICH RUNG ANSWERED β€” tracked per profile so the canvas's rung dots are a measurement.
1612
+ if tier == "hiker":
1613
+ hiker_tried = True
1614
+ if via == "hikerapi" and read_ok:
1615
+ hiker_answered = True
1616
+ counts["paid"] += 1
1617
+ elif fallback:
1618
+ anon_tried = True
1619
+ anon_answered = anon_answered or read_ok
1620
+ else:
1621
+ anon_tried = True
1622
+ anon_answered = anon_answered or read_ok
1623
+ if read_ok:
1624
  counts["ok" if res["state"] == "ok" else "partial"] += 1
1625
  prof = res["profile"]
1626
+ in_snaps.append({
1627
+ "snapshot_key": f"{prof['username']}@{pulled}",
1628
+ "influencer_key": prof["username"], "pulled_at": pulled,
1629
+ "followers": _s(prof.get("followers")), "following": _s(prof.get("following")),
1630
+ "posts_count": _s(prof.get("posts_count")),
1631
+ "full_name": _s(prof.get("full_name")),
1632
+ "bio": _s(prof.get("bio"), 500), "verified": _s(prof.get("verified")),
1633
+ "source": _s(res.get("via")), "approx": _s(prof.get("approx")),
1634
+ "external_url": _s(prof.get("external_url"), 300)})
1635
  for p in res.get("posts") or []:
1636
+ in_posts.append({
1637
  "shortcode": p["shortcode"], "influencer_key": prof["username"],
1638
  "posted_at": _s(p.get("posted_at")), "type": _s(p.get("type")),
1639
+ "caption": _s(p.get("caption"), 800), "url": _s(p.get("url"), 300)})
1640
+ in_psnaps.append({
 
 
1641
  "post_snapshot_key": f"{p['shortcode']}@{pulled}",
1642
  "shortcode": p["shortcode"], "pulled_at": pulled,
1643
  "likes": _s(p.get("likes")), "comments": _s(p.get("comments")),
1644
+ "views": _s(p.get("views"))})
1645
  counts["posts"] += len(res.get("posts") or [])
 
1646
  detail = f"{prof.get('followers') or '?'} followers"
1647
+ if prof.get("approx"):
1648
+ detail += " (approx)"
1649
  if res.get("posts"):
1650
  detail += f", {len(res['posts'])} posts"
1651
  elif res["state"] == "partial":
1652
+ detail += ", posts not readable on the rung that answered"
1653
  cells[rid] = f"{res['state']} Β· {_stamp()} Β· {detail}"
1654
  elif res["state"] == "blocked":
1655
  counts["blocked"] += 1
 
1661
  notes.append(res.get("note") or "error")
1662
  affected.append(rid)
1663
 
1664
+ # --- THE THREE UPSERTS. Once each, over the whole run's accumulated rows.
1665
+ snaps, c_snap = upsert_rows(snaps, in_snaps, "snapshot_key", cap=row_cap(snap_key))
1666
+ posts, c_post = upsert_rows(posts, in_posts, "shortcode", cap=row_cap(post_key))
1667
+ psnaps, c_ps = upsert_rows(psnaps, in_psnaps, "post_snapshot_key", cap=row_cap(ps_key))
1668
+ counts["new_posts"] = c_post["inserted"]
1669
+ capped = [(snap_key, c_snap["capped"]), (post_key, c_post["capped"]),
1670
+ (ps_key, c_ps["capped"])]
1671
+ counts["capped"] = sum(n for _k, n in capped)
1672
+
1673
+ if not dry:
1674
+ def _up(cur):
1675
+ cur = cur if isinstance(cur, dict) else {}
1676
+ tt = cur.get(table_key)
1677
+ if tt is not None:
1678
+ for rid, val in cells.items():
1679
+ tt.setdefault("rows", {}).setdefault(str(rid), {})[fkey] = val
1680
+ for k, rws in ((snap_key, snaps), (post_key, posts), (ps_key, psnaps)):
1681
+ tgt = cur.get(k)
1682
+ if tgt is not None:
1683
+ tgt["rows"] = rws
1684
+ return cur
1685
+
1686
+ rt.update(UT_STORE_KEY, _up, flush="sync") # ONE coalesced update for all four tables
1687
 
 
1688
  # ⚠ A RUN IS ONLY 'ok' IF EVERY PROFILE WAS. The first live run rolled up to 'ok' while
1689
  # every CELL said `partial`, because the rollup only asked about blocked/error β€” so the rail
1690
  # showed a green dot over a table with no posts in it. A summary that disagrees with the
 
1697
  state = "partial"
1698
  else:
1699
  state = "ok"
1700
+ # --- per-node outcomes for the canvas (see the same note in `run_scrape_db`)
1701
+ if not targets:
1702
+ cap_state = "idle"
1703
+ elif not read:
1704
+ cap_state = "error" if counts["error"] else "blocked"
1705
+ else:
1706
+ cap_state = "partial" if (counts["blocked"] or counts["error"]
1707
+ or counts["partial"]) else "ok"
1708
+ steps["capture"] = cap_state
1709
+ steps["capture_hiker"] = ("ok" if hiker_answered
1710
+ else "blocked" if hiker_tried else "skipped")
1711
+ steps["capture_anon"] = ("ok" if anon_answered
1712
+ else "blocked" if anon_tried else "skipped")
1713
+
1714
  summary = (f"{read}/{counts['profiles']} profiles read, {counts['posts']} posts "
1715
  f"({counts['new_posts']} new)")
1716
+ if counts["paid"]:
1717
+ summary += f", {counts['paid']} exact via HikerAPI"
1718
  if counts["partial"]:
1719
+ summary += f", {counts['partial']} profile-only (posts not readable)"
1720
  if counts["blocked"]:
1721
+ summary += f", {counts['blocked']} blocked"
1722
+ note = cap_note(capped)
1723
+ if note:
1724
+ summary += f" β€” {note}"
1725
+ state = "partial" if state != "error" else state
1726
+ steps["write"] = "partial"
1727
+ elif not dry:
1728
+ steps["write"] = "ok"
1729
+ if dry:
1730
+ summary = f"DRY RUN (the Write step is turned off) β€” would have written: {summary}"
1731
+ steps["write"] = "skipped"
1732
+ state = "partial" if state != "error" else state
1733
  if notes:
1734
  summary += f" β€” {notes[0][:120]}"
1735
+ return (state, summary, counts, affected, steps)
1736
 
1737
 
1738
  def _auto_url_field(table, fkey):
 
1752
  RUNNERS = {"scrape_db": run_scrape_db, "field_instagram": run_field_instagram}
1753
 
1754
 
1755
+ # ---------------------------------------------------------------------------------------------
1756
+ # THE CANVAS GRAPH (R5) β€” topology on the SERVER, pixels on the client
1757
+ # ---------------------------------------------------------------------------------------------
1758
+ # WHY THE TOPOLOGY LIVES HERE. The canvas draws what an automation DOES; the runners above are
1759
+ # what it does. Two descriptions of one thing in two languages drift, and the drift is invisible β€”
1760
+ # a canvas that still shows a step the engine stopped running looks completely fine. So the node
1761
+ # list is derived from the DEFINITION by the same module that executes it, rides on the payload
1762
+ # the way `CRON_PRESETS` and the kind list already do, and is asserted in `verify_automation.py`.
1763
+ # The client owns layout (pixels, pan/zoom, hit targets) and nothing else.
1764
+ #
1765
+ # ⚠ BRANCHES RENDER, THEY DO NOT EXECUTE (R5, accepted at grill; DEBT D-7). The `capture` node is
1766
+ # a real branch in BEHAVIOUR β€” the paid rung answers or the anonymous ladder does β€” but the engine
1767
+ # walks it linearly. Nothing here should be read as a general branching runtime.
1768
+
1769
+ #: A node's dot vocabulary. Deliberately WIDER than the run-level `STATES`: a node can be
1770
+ #: `blocked` or `skipped` in ways a whole run cannot, and folding those into `partial` would throw
1771
+ #: away the only information the dot is there to carry.
1772
+ NODE_STATES = ("idle", "ok", "partial", "error", "blocked", "skipped")
1773
+
1774
+ #: node id -> the switch it flips. A node ABSENT from this map has no switch, and that is a
1775
+ #: deliberate answer rather than an omission: a "Fetch the page" step that can be turned off is
1776
+ #: not an automation with a disabled step, it is a broken automation with a lie on it. The ones
1777
+ #: here are all REAL β€” each changes what the next run does:
1778
+ #: schedule the trigger fires on its cron, or only by hand
1779
+ #: hiker the paid rung is reached for, or it is not (this is the one that spends money)
1780
+ #: fallback the anonymous ladder catches a refused paid rung, or the run says `blocked`
1781
+ #: instead of quietly writing an approximate number
1782
+ #: write DRY RUN β€” read everything, compute the counts, write nothing anywhere
1783
+ NODE_TOGGLES = {"trigger": "schedule", "capture_hiker": "hiker",
1784
+ "capture_anon": "fallback", "write": "write"}
1785
+
1786
+
1787
+ def _cron_label(cron):
1788
+ return next((p["label"] for p in CRON_PRESETS if p["cron"] == cron), cron or "")
1789
+
1790
+
1791
+ def node_status(steps, nid):
1792
+ """A node's dot β€” from the last run's MEASURED step outcome, or `idle`.
1793
+
1794
+ β›” NEVER INFERRED FROM THE RUN'S OVERALL STATE, and this is a module-level function precisely
1795
+ so a negative control can prove that. Every run stored before W19-C has no `steps` map at all,
1796
+ and painting those nodes green because the run said `ok` would manufacture a measurement β€” the
1797
+ same defect as the green dot over the empty posts table recorded in `run_field_instagram`.
1798
+ No data β‡’ `idle`. An unrecognised word β‡’ `idle`, never passed through to the UI.
1799
+ """
1800
+ v = str((steps or {}).get(nid) or "")
1801
+ return v if v in NODE_STATES else "idle"
1802
+
1803
+
1804
+ def graph(defn):
1805
+ """One automation β†’ `{nodes, edges}`, left to right. Pure over the definition."""
1806
+ defn = defn if isinstance(defn, dict) else {}
1807
+ cfg = defn.get("config") or {}
1808
+ sched = defn.get("schedule") or {}
1809
+ runs = defn.get("runs") or []
1810
+ last = runs[0] if runs and isinstance(runs[0], dict) else {}
1811
+ steps = last.get("steps") if isinstance(last.get("steps"), dict) else {}
1812
+
1813
+ def node(nid, kind, title, subtitle, col, row=0, panel="", detail="", on=True):
1814
+ return {"id": nid, "kind": kind, "title": title, "subtitle": subtitle, "detail": detail,
1815
+ "col": col, "row": row, "panel": panel or nid, "enabled": bool(on),
1816
+ "toggle": NODE_TOGGLES.get(nid, ""), "status": node_status(steps, nid)}
1817
+
1818
+ on = bool(sched.get("enabled"))
1819
+ nodes = [node("trigger", "trigger", "Schedule",
1820
+ _cron_label(sched.get("cron")) if on else "Manual only", 0,
1821
+ panel="schedule", on=on,
1822
+ detail="" if on else "It still runs when you press Run now")]
1823
+ edges = []
1824
+
1825
+ if defn.get("kind") == "field_instagram":
1826
+ tier = cfg.get("tier") if cfg.get("tier") in TIERS else "anonymous"
1827
+ paid = tier == "hiker"
1828
+ fb = not cfg.get("noFallback")
1829
+ anon_on = (not paid) or fb
1830
+ nodes += [
1831
+ node("source", "source", "Profile set", cfg.get("targetTable") or "No database", 1,
1832
+ panel="source",
1833
+ detail=f"URL column: {cfg.get('urlField')}" if cfg.get("urlField")
1834
+ else "URL column: the one the field is bound to"),
1835
+ node("capture", "branch", "Capture",
1836
+ "HikerAPI, then anonymous" if paid else "Anonymous only", 2, panel="capture",
1837
+ detail=f"Up to {cfg.get('maxPosts') or 24} posts per profile"),
1838
+ node("capture_hiker", "capture", "HikerAPI",
1839
+ "Exact counts, full posts" if paid else "Off β€” the paid rung is not used",
1840
+ 3, row=-1, panel="capture", on=paid,
1841
+ detail="" if hiker_ready() else "No AIOS_HIKERAPI_KEY is configured"),
1842
+ node("capture_anon", "capture", "Anonymous",
1843
+ "Approximate counts, $0" if anon_on else "Off β€” exact numbers or nothing",
1844
+ 3, row=1, panel="capture", on=anon_on,
1845
+ detail="Local egress only β€” Instagram blocks datacenters"),
1846
+ node("write", "write", "Write",
1847
+ cfg.get("targetTable") or "No database", 4, panel="write",
1848
+ on=not cfg.get("dryRun"),
1849
+ detail="+ ut_ig_snapshots Β· ut_ig_posts Β· ut_ig_post_snapshots"),
1850
+ ]
1851
+ edges = [{"from": "trigger", "to": "source", "label": ""},
1852
+ {"from": "source", "to": "capture", "label": ""},
1853
+ {"from": "capture", "to": "capture_hiker", "label": "paid"},
1854
+ {"from": "capture", "to": "capture_anon", "label": "fallback"},
1855
+ {"from": "capture_hiker", "to": "write", "label": ""},
1856
+ {"from": "capture_anon", "to": "write", "label": ""}]
1857
+ # When there is no paid rung the anonymous one is the ONLY rung, so it must not carry a
1858
+ # switch that would leave the automation with nothing to run.
1859
+ if not paid:
1860
+ for n in nodes:
1861
+ if n["id"] == "capture_anon":
1862
+ n["toggle"] = ""
1863
+ else:
1864
+ url = str(cfg.get("url") or "")
1865
+ host = (urlparse(url).hostname or url or "No URL") if url else "No URL"
1866
+ which = ("Structured data (JSON-LD)" if cfg.get("extract") == "jsonld"
1867
+ else f"HTML table #{int(cfg.get('tableIndex') or 0)}")
1868
+ mapped = len(cfg.get("fieldMap") or {})
1869
+ nodes += [
1870
+ node("fetch", "source", "Fetch page", host, 1, panel="source", detail=url[:90]),
1871
+ node("extract", "capture", "Extract", which, 2, panel="columns",
1872
+ detail=f"{mapped} column{'' if mapped == 1 else 's'} mapped Β· key: "
1873
+ f"{cfg.get('keyField') or 'β€”'}"),
1874
+ node("write", "write", "Write", cfg.get("targetLabel") or "Scraped table", 3,
1875
+ panel="write", on=not cfg.get("dryRun"),
1876
+ detail=cfg.get("targetTable") or "a new database"),
1877
+ ]
1878
+ edges = [{"from": "trigger", "to": "fetch", "label": ""},
1879
+ {"from": "fetch", "to": "extract", "label": ""},
1880
+ {"from": "extract", "to": "write", "label": ""}]
1881
+ return {"nodes": nodes, "edges": edges}
1882
+
1883
+
1884
+ def toggle_node(rt, auto_id, node_id):
1885
+ """Flip ONE node's switch. Returns `(defn, error)`.
1886
+
1887
+ The node β†’ config mapping lives on the SERVER for the reason the whole graph does: a client
1888
+ that knew which field each node writes would be a second copy of that knowledge, free to
1889
+ drift. The canvas just says "this node was clicked".
1890
+ """
1891
+ prev = all_definitions(rt).get(str(auto_id))
1892
+ if prev is None:
1893
+ return None, "no such automation"
1894
+ target = next((n for n in graph(prev)["nodes"] if n["id"] == str(node_id)), None)
1895
+ if target is None:
1896
+ return None, f"there is no {node_id!r} step in this automation"
1897
+ if not target.get("toggle"):
1898
+ return None, (f"the {target['title']} step cannot be turned off β€” it is what this "
1899
+ f"automation is")
1900
+ cfg, sched = dict(prev.get("config") or {}), dict(prev.get("schedule") or {})
1901
+ which = target["toggle"]
1902
+ if which == "schedule":
1903
+ sched["enabled"] = not sched.get("enabled")
1904
+ elif which == "hiker":
1905
+ cfg["tier"] = "anonymous" if cfg.get("tier") == "hiker" else "hiker"
1906
+ elif which == "fallback":
1907
+ cfg["noFallback"] = not cfg.get("noFallback")
1908
+ elif which == "write":
1909
+ cfg["dryRun"] = not cfg.get("dryRun")
1910
+ return patch(rt, auto_id, {"config": cfg, "schedule": sched})
1911
+
1912
+
1913
  def run_now(rt, tenant, auto_id, username="automation", log=print):
1914
  """Execute one automation SYNCHRONOUSLY. The route wraps this in a thread; the tick calls it
1915
  directly. Returns the run entry, or None when it was already running (the 409)."""
 
1925
  return _commit_run(rt, auto_id, "error",
1926
  f"unknown automation kind {defn.get('kind')!r}", {}, False)
1927
  try:
1928
+ state, summary, counts, affected, steps = runner(rt, defn, username=username,
1929
+ log=log)
1930
  except Refused as e:
1931
  return _commit_run(rt, auto_id, "error", f"refused: {e}", {}, False)
1932
  except Exception as e: # noqa: BLE001
1933
  log(f"[aios-auto] run {auto_id} failed: {type(e).__name__}: {e}")
1934
  return _commit_run(rt, auto_id, "error",
1935
  f"{type(e).__name__}: {str(e)[:200]}", {}, False)
1936
+ return _commit_run(rt, auto_id, state, summary, counts, state != "error", affected,
1937
+ steps)
1938
  finally:
1939
  _release(tenant, auto_id)
1940
 
api/deps.py CHANGED
@@ -12,6 +12,8 @@ to mean "you are not allowed" is how a permission bug becomes invisible.
12
  """
13
  import os
14
  import sys
 
 
15
  from dataclasses import dataclass
16
  from pathlib import Path
17
 
@@ -122,6 +124,60 @@ def _user_for(claims):
122
  return None
123
 
124
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
125
  def require_session(request: Request, response: Response) -> Session:
126
  """Verify the cookie, resolve the tenant, and REISSUE the cookie (the 8h idle window is
127
  refreshed on use; the 30-day absolute expiry is carried over, never extended)."""
@@ -143,6 +199,9 @@ def require_session(request: Request, response: Response) -> Session:
143
  fresh, _ = aios_session.mint(claims["t"], user["username"], int(user.get("epoch") or 0),
144
  absolute_expiry=claims["x"])
145
  aios_session.set_cookie(response, request, fresh)
 
 
 
146
  return Session(tenant=claims["t"], user=user, claims=claims, runtime=rt)
147
 
148
 
 
12
  """
13
  import os
14
  import sys
15
+ import time
16
+ from collections import OrderedDict
17
  from dataclasses import dataclass
18
  from pathlib import Path
19
 
 
124
  return None
125
 
126
 
127
+ # --- wave 19 (R4): the LAST-ACTIVE stamp, throttled in this process ------------------------------
128
+ # "Is anyone actually using this account?" is one of the two questions the Loopable admin plane
129
+ # answers, and the only place that can honestly answer it is the session resolver β€” every
130
+ # authenticated request passes through here.
131
+ #
132
+ # β›” THEREFORE IT MUST COST ALMOST NOTHING. A store write per request would put the HF store's
133
+ # 256-commits/hour budget on the critical path of the entire API, and a store READ per request to
134
+ # decide whether to write would be little better. So the staleness decision is made from a
135
+ # PROCESS-LOCAL map: no I/O at all on the 99.97% of requests inside the window, and the write
136
+ # itself (once an hour per account) happens on `core.users`' own background thread, so no request
137
+ # ever waits for a hub round-trip. `core.users` explains why that write is SYNC and not the
138
+ # coalesced async path β€” `users.json` is shared with the Streamlit host and an async flush rebases
139
+ # on this process's cache, which would let a stamp revert somebody else's deactivation.
140
+ #
141
+ # HONEST LIMITS, stated rather than discovered later: the map is per-process, so N workers can each
142
+ # write once per window (still bounded); a restart re-arms every user's first request; and the
143
+ # resolution of `last_active` is therefore "within the last hour", which is exactly what the plane
144
+ # renders it as. Bounded like `routes_auth._FAILS` so it cannot grow into a leak on a deployment
145
+ # with many accounts.
146
+ _ACTIVE_SEEN: "OrderedDict[str, float]" = OrderedDict()
147
+ _ACTIVE_EVERY = float(os.environ.get("AIOS_ACTIVE_STAMP_SECONDS") or 3600)
148
+ _ACTIVE_MAX_TRACKED = 4096
149
+
150
+
151
+ def note_active(uname, when=None):
152
+ """Record that `uname` was just seen β€” WITHOUT writing. The login path calls this because it
153
+ has already stamped `last_active` itself; without it the very next request would find no entry
154
+ and stamp again immediately, making the "at most once an hour" rule false by one write per
155
+ sign-in."""
156
+ key = (uname or "").strip().lower()
157
+ if not key:
158
+ return
159
+ _ACTIVE_SEEN[key] = when if when is not None else time.time()
160
+ _ACTIVE_SEEN.move_to_end(key)
161
+ while len(_ACTIVE_SEEN) > _ACTIVE_MAX_TRACKED:
162
+ _ACTIVE_SEEN.popitem(last=False)
163
+
164
+
165
+ def _touch_active(uname):
166
+ """Stamp `last_active` at most once per window per account, per process. Never raises."""
167
+ try:
168
+ key = (uname or "").strip().lower()
169
+ if not key:
170
+ return
171
+ now = time.time()
172
+ last = _ACTIVE_SEEN.get(key)
173
+ if last is not None and (now - last) < _ACTIVE_EVERY:
174
+ return
175
+ note_active(key, now)
176
+ users.touch_active(key)
177
+ except Exception: # noqa: BLE001 β€” telemetry may never break a request
178
+ pass
179
+
180
+
181
  def require_session(request: Request, response: Response) -> Session:
182
  """Verify the cookie, resolve the tenant, and REISSUE the cookie (the 8h idle window is
183
  refreshed on use; the 30-day absolute expiry is carried over, never extended)."""
 
199
  fresh, _ = aios_session.mint(claims["t"], user["username"], int(user.get("epoch") or 0),
200
  absolute_expiry=claims["x"])
201
  aios_session.set_cookie(response, request, fresh)
202
+ # R4: last AFTER the session is fully resolved β€” a stamp is only true of a request that was
203
+ # actually admitted, and putting it here means no failed-auth path can ever write one.
204
+ _touch_active(user.get("username"))
205
  return Session(tenant=claims["t"], user=user, claims=claims, runtime=rt)
206
 
207
 
api/main.py CHANGED
@@ -63,6 +63,7 @@ import routes_grid # noqa: E402
63
  import routes_keychain # noqa: E402 (wave 18 C7 β€” keychain + connectors admin surfaces)
64
  import routes_nav # noqa: E402
65
  import routes_pages # noqa: E402
 
66
  import routes_products # noqa: E402 (wave 15 C-TOPIC β€” gated, not yet in the nav)
67
  import routes_records # noqa: E402
68
  import routes_tables # noqa: E402 (wave 18 C3-UT β€” user-created databases over the wire)
@@ -178,6 +179,12 @@ app.include_router(routes_pages.router)
178
  app.include_router(routes_admin.router)
179
  app.include_router(routes_automation.router)
180
  app.include_router(routes_keychain.router)
 
 
 
 
 
 
181
 
182
 
183
  # --- DEPRECATED ALIASES (removed when S2's shell flips; kept so the current bundle keeps working)
 
63
  import routes_keychain # noqa: E402 (wave 18 C7 β€” keychain + connectors admin surfaces)
64
  import routes_nav # noqa: E402
65
  import routes_pages # noqa: E402
66
+ import routes_platform_admin # noqa: E402 (wave 19 R3/R4 β€” the Loopable cross-tenant plane)
67
  import routes_products # noqa: E402 (wave 15 C-TOPIC β€” gated, not yet in the nav)
68
  import routes_records # noqa: E402
69
  import routes_tables # noqa: E402 (wave 18 C3-UT β€” user-created databases over the wire)
 
179
  app.include_router(routes_admin.router)
180
  app.include_router(routes_automation.router)
181
  app.include_router(routes_keychain.router)
182
+ # Wave 19 (owner item 13, R3): the LOOPABLE admin plane β€” the platform's own cross-tenant view.
183
+ # Its own prefix (`/api/v1/platform-admin`), never nested under `/admin`, so there is no path
184
+ # ambiguity with `routes_admin`'s `{username}` params and no chance of a tenant-admin route and a
185
+ # platform-operator route ever shadowing each other. Every path it declares is gated by
186
+ # `core.platform_admin.is_platform_admin`, and `verify_api` enumerates this router to prove it.
187
+ app.include_router(routes_platform_admin.router)
188
 
189
 
190
  # --- DEPRECATED ALIASES (removed when S2's shell flips; kept so the current bundle keeps working)
api/routes_admin.py CHANGED
@@ -32,6 +32,7 @@ import re
32
 
33
  from fastapi import APIRouter, Body, Depends, Response
34
 
 
35
  import core.registry as registry
36
  import core.store as store
37
 
@@ -770,4 +771,10 @@ def settings(session: Session = Depends(require_session)):
770
  # CHROME ONLY. Every /admin route re-checks the role server-side; this exists so the client
771
  # does not paint a "Manage users" button that 403s.
772
  "admin": perms.is_admin(session.user),
 
 
 
 
 
 
773
  }
 
32
 
33
  from fastapi import APIRouter, Body, Depends, Response
34
 
35
+ import core.platform_admin as platform_admin # wave 19 R3 β€” the /settings chrome flag
36
  import core.registry as registry
37
  import core.store as store
38
 
 
771
  # CHROME ONLY. Every /admin route re-checks the role server-side; this exists so the client
772
  # does not paint a "Manage users" button that 403s.
773
  "admin": perms.is_admin(session.user),
774
+ # Wave 19 (R3, contract C2): the same courtesy for the LOOPABLE plane β€” the Settings rail
775
+ # paints its entry iff this is true, and `routes_platform_admin` refuses every request
776
+ # that is not, so a client that ignored this would gain exactly nothing. Derived from the
777
+ # ONE predicate rather than restated: a second copy of a two-condition wall is a second
778
+ # place for one of the conditions to go missing.
779
+ "platformAdmin": platform_admin.is_platform_admin(session.user),
780
  }
api/routes_assets.py CHANGED
@@ -28,13 +28,14 @@ import os
28
  import re
29
  import tempfile
30
  import time
 
31
  from pathlib import Path
32
 
33
  from fastapi import Body, Depends
34
  from fastapi import APIRouter
35
  from fastapi.responses import FileResponse
36
 
37
- from deps import Session, err, module_gate
38
  from routes_admin import admin_gate
39
 
40
  router = APIRouter(prefix="/api/v1")
@@ -294,3 +295,139 @@ def editorial_upload(body: dict = Body(default=None),
294
  raise err(503, "asset_repo_unavailable",
295
  "the asset repo did not accept the upload β€” try again")
296
  return {"slug": slug, "source": "repo"}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
28
  import re
29
  import tempfile
30
  import time
31
+ import uuid
32
  from pathlib import Path
33
 
34
  from fastapi import Body, Depends
35
  from fastapi import APIRouter
36
  from fastapi.responses import FileResponse
37
 
38
+ from deps import Session, err, module_gate, require_session
39
  from routes_admin import admin_gate
40
 
41
  router = APIRouter(prefix="/api/v1")
 
295
  raise err(503, "asset_repo_unavailable",
296
  "the asset repo did not accept the upload β€” try again")
297
  return {"slug": slug, "source": "repo"}
298
+
299
+
300
+ # ───────────────────────────────── RECORD IMAGES (wave 19, owner item 5 / R7 / contract C5)
301
+ #
302
+ # The third namespace, and the first one ORDINARY USERS write. An `image` field's cell holds a
303
+ # string reference; `rec:<id>` names a picture uploaded here.
304
+ #
305
+ # β›” THREE WALLS, and each exists because of a specific way this could go wrong:
306
+ #
307
+ # 1. SESSION-GATED, NOT ADMIN-GATED. R7 is explicit β€” a non-admin attaches a picture to their
308
+ # own record. The editorial upload above IS admin-only because it publishes into Royal's
309
+ # shared catalogue library; this writes a per-record attachment, which is the same class of
310
+ # act as typing a note.
311
+ # 2. TENANT FROM THE SESSION, NEVER FROM THE STRING. The stored address is `<tenant>/<id>` and
312
+ # both halves of it are composed server-side. A `rec:` reference pasted from another
313
+ # tenant's cell is looked up under THIS tenant's prefix, finds nothing, and 404s. There is
314
+ # no code path in which a client-supplied string chooses a tenant.
315
+ # 3. IT MUST OPEN AS AN IMAGE. A 2 MB cap on the DECODED bytes (the client checks too, but a
316
+ # client check only spares the user a pointless upload) and Pillow must parse it. Without
317
+ # the parse, "upload an image" is "upload 2 MB of anything to the tenant's dataset".
318
+ #
319
+ # The id is server-minted hex, so a client never names a path component at all β€” traversal is
320
+ # not refused so much as unreachable. The read route re-validates it anyway (defence in depth,
321
+ # and the same closed-charset posture `_CODE_RE` takes for product codes).
322
+
323
+ _REC_MAX_BYTES = 2 * 1024 * 1024 # C5's cap, enforced on the DECODED bytes
324
+ _REC_WEB_EDGE = 1200 # bigger than a SKU thumbnail; smaller than editorial
325
+ _REC_ID_RE = re.compile(r"^[a-f0-9]{8,32}$")
326
+
327
+
328
+ def _rec_dir(tenant, create=False):
329
+ """Dir-mode home for one tenant's record images: `<AIOS_ASSET_DIR>/records/<tenant>/`.
330
+
331
+ Dir mode is MODAL exactly as editorial is (see that section's note): with `AIOS_ASSET_DIR`
332
+ set it is authoritative and the repo is never consulted, so a hermetic gate cannot silently
333
+ read production state and go green on it.
334
+ """
335
+ d = _local_dir()
336
+ if d is None:
337
+ return None
338
+ p = d / "records" / str(tenant or "").strip().lower()
339
+ if create:
340
+ p.mkdir(parents=True, exist_ok=True)
341
+ return p
342
+
343
+
344
+ @router.post("/assets/records", status_code=201)
345
+ def record_upload(body: dict = Body(default=None),
346
+ session: Session = Depends(require_session)):
347
+ """Store one record image and return the REFERENCE to put in the cell.
348
+
349
+ `{data: "<base64 | data: URL>"}` β†’ `{"ref": "rec:<id>"}`. The caller PATCHes that ref onto
350
+ the row through the ordinary overlay wall; this route never writes a cell. That separation is
351
+ deliberate: the per-key `permissions.edit` wall, the pid wall and the hidden-field wall all
352
+ live in `core.grid_events`, and an asset route that wrote cells directly would be a second
353
+ write path with none of them.
354
+ """
355
+ body = body or {}
356
+ raw = str(body.get("data") or "")
357
+ raw = raw.split(",", 1)[1] if raw.startswith("data:") and "," in raw else raw
358
+ try:
359
+ blob = base64.b64decode(raw, validate=True)
360
+ except Exception:
361
+ raise err(400, "bad_image", "data must be base64 image bytes")
362
+ if not blob:
363
+ raise err(400, "bad_image", "the upload is empty")
364
+ if len(blob) > _REC_MAX_BYTES:
365
+ raise err(400, "image_too_large",
366
+ f"record images cap at {_REC_MAX_BYTES // (1024 * 1024)} MB")
367
+ try:
368
+ from PIL import Image
369
+ except ImportError:
370
+ raise err(503, "pillow_missing",
371
+ "image validation needs Pillow β€” `pip install pillow` on this host")
372
+ try:
373
+ with Image.open(io.BytesIO(blob)) as im:
374
+ im.load()
375
+ fmt = (im.format or "").upper()
376
+ if fmt not in ("PNG", "JPEG"):
377
+ raise err(400, "bad_image", "PNG or JPEG only")
378
+ ext = ".png" if fmt == "PNG" else ".jpg"
379
+ web = im.convert("RGB") if im.mode not in ("RGB", "RGBA", "L", "LA") else im.copy()
380
+ web.thumbnail((_REC_WEB_EDGE, _REC_WEB_EDGE))
381
+ buf = io.BytesIO()
382
+ web.save(buf, format="PNG", optimize=True)
383
+ except Exception as e:
384
+ if getattr(e, "status_code", None):
385
+ raise
386
+ raise err(400, "bad_image", "that file does not open as an image")
387
+
388
+ asset_id = uuid.uuid4().hex[:24]
389
+ tenant = session.tenant
390
+ d = _rec_dir(tenant, create=True)
391
+ if d is not None:
392
+ (d / f"{asset_id}{ext}").write_bytes(blob)
393
+ (d / f"{asset_id}.web.png").write_bytes(buf.getvalue())
394
+ return {"ref": f"rec:{asset_id}", "source": "dir"}
395
+ try:
396
+ _assets().put_record(tenant, asset_id, blob, ext, buf.getvalue())
397
+ except Exception:
398
+ raise err(503, "asset_repo_unavailable",
399
+ "the asset repo did not accept the upload β€” try again")
400
+ return {"ref": f"rec:{asset_id}", "source": "repo"}
401
+
402
+
403
+ @router.get("/assets/records/{asset_id}")
404
+ def record_asset(asset_id: str, q: str = "web",
405
+ session: Session = Depends(require_session)):
406
+ """Serve one record image for THIS session's tenant. Any signed-in user of the tenant may
407
+ read it β€” a picture on a row is visible to whoever can open the row, and the row walls
408
+ already decided that."""
409
+ if q not in _QUALITIES:
410
+ raise err(400, "bad_quality", f"q must be one of {', '.join(_QUALITIES)}")
411
+ asset_id = str(asset_id or "").strip().lower()
412
+ if not _REC_ID_RE.match(asset_id):
413
+ raise err(400, "bad_asset_id", "that is not a record image id")
414
+
415
+ tenant = session.tenant
416
+ d = _rec_dir(tenant)
417
+ path = None
418
+ if d is not None:
419
+ # Dir mode is MODAL: this tenant's folder, or nothing. Never a fall-through to the repo.
420
+ cand = (d / f"{asset_id}.web.png") if q == "web" else None
421
+ if cand is None or not cand.is_file():
422
+ cand = next((d / f"{asset_id}{e}" for e in _EXT_MEDIA
423
+ if (d / f"{asset_id}{e}").is_file()), None)
424
+ path = cand if cand is not None and cand.is_file() else None
425
+ else:
426
+ path = _assets().fetch_record(tenant, asset_id, q)
427
+ if path is None or not Path(path).is_file():
428
+ # 404 β€” and it is the SAME answer for "no such picture" and "that picture belongs to
429
+ # another tenant", which is the cross-tenant wall stated as a status code.
430
+ raise err(404, "asset_not_found", "no image for that reference")
431
+ media = _EXT_MEDIA.get(Path(path).suffix.lower(), "application/octet-stream")
432
+ return FileResponse(str(path), media_type=media,
433
+ headers={"Cache-Control": _IMMUTABLE})
api/routes_auth.py CHANGED
@@ -176,6 +176,17 @@ def login(request: Request, response: Response, body: dict = Body(default=None))
176
  _clear_failures(throttle_key)
177
  value, _claims = aios_session.mint(tenant, user["username"], int(user.get("epoch") or 0))
178
  aios_session.set_cookie(response, request, value)
 
 
 
 
 
 
 
 
 
 
 
179
  return {"user": _public_user(user)}
180
 
181
 
 
176
  _clear_failures(throttle_key)
177
  value, _claims = aios_session.mint(tenant, user["username"], int(user.get("epoch") or 0))
178
  aios_session.set_cookie(response, request, value)
179
+ # Wave 19 (R4): the login stamp. THE RESOLVED username, never the posted identifier β€” the
180
+ # person may have typed an email address and `users.verify` resolved it to the registry key;
181
+ # stamping what was typed would write onto a key that does not exist. Fail-silent inside
182
+ # `touch_login` and a no-op for the emergency-master identity (which has no record to stamp),
183
+ # so the one thing this cannot do is turn a good credential into a failed sign-in.
184
+ users.touch_login(user["username"])
185
+ # `touch_login` also sets `last_active`, so tell the session resolver it has been seen β€”
186
+ # otherwise the very next request stamps it again and the hourly throttle is off by one write
187
+ # per sign-in.
188
+ import deps as _deps
189
+ _deps.note_active(user["username"])
190
  return {"user": _public_user(user)}
191
 
192
 
api/routes_automation.py CHANGED
@@ -45,6 +45,10 @@ def _wire(defn, tenant):
45
  "created": defn.get("created"), "createdBy": defn.get("createdBy"),
46
  "nextRunAt": nxt.strftime("%Y-%m-%d %H:%M") if nxt else "",
47
  "running": bool(live),
 
 
 
 
48
  }
49
 
50
 
@@ -62,6 +66,11 @@ def list_automations(session: Session = Depends(_GATE)):
62
  "kinds": [{"key": "scrape_db", "label": "Web page to database"},
63
  {"key": "field_instagram", "label": "Instagram profile column"}],
64
  "cronPresets": engine.CRON_PRESETS,
 
 
 
 
 
65
  "storeAvailable": bool(session.runtime.available())}
66
 
67
 
@@ -160,6 +169,26 @@ def run_automation(auto_id: str, session: Session = Depends(_GATE)):
160
  return {"started": str(auto_id), "startedAt": time.strftime("%Y-%m-%dT%H:%M:%S")}
161
 
162
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
163
  @router.post("/automations/tick")
164
  def tick(request: Request, x_aios_tick_token: str = Header(default="")):
165
  """Fire every due schedule, for every tenant. The durable-cron entry point (R5).
 
45
  "created": defn.get("created"), "createdBy": defn.get("createdBy"),
46
  "nextRunAt": nxt.strftime("%Y-%m-%d %H:%M") if nxt else "",
47
  "running": bool(live),
48
+ # THE CANVAS TOPOLOGY (R5) rides with the automation rather than being rebuilt in the
49
+ # client, for the same reason `cronPresets` does: the engine that RUNS the steps is the
50
+ # only thing entitled to say what the steps are.
51
+ "graph": engine.graph(defn),
52
  }
53
 
54
 
 
66
  "kinds": [{"key": "scrape_db", "label": "Web page to database"},
67
  {"key": "field_instagram", "label": "Instagram profile column"}],
68
  "cronPresets": engine.CRON_PRESETS,
69
+ # ⚠ A BOOLEAN, NEVER THE KEY. The surface needs to say "the paid rung is not
70
+ # configured" honestly instead of offering a tier that will silently refuse β€” and
71
+ # that needs exactly one bit. Shipping the key itself to a browser would put a
72
+ # billable secret in every user's devtools.
73
+ "hikerReady": engine.hiker_ready(),
74
  "storeAvailable": bool(session.runtime.available())}
75
 
76
 
 
169
  return {"started": str(auto_id), "startedAt": time.strftime("%Y-%m-%dT%H:%M:%S")}
170
 
171
 
172
+ @router.post("/automations/{auto_id}/nodes/{node_id}/toggle")
173
+ def toggle_automation_node(auto_id: str, node_id: str, session: Session = Depends(_GATE)):
174
+ """Flip one step on the canvas. The SERVER decides what a node's switch means (see
175
+ `engine.NODE_TOGGLES`) β€” the client only reports which node was clicked.
176
+
177
+ A node with no switch answers 400 with the sentence saying why, rather than silently doing
178
+ nothing: a control that appears to work and does not is worse than one that refuses.
179
+ """
180
+ if not session.runtime.available():
181
+ raise err(503, "store_unavailable", "the tenant store is unavailable β€” nothing was saved")
182
+ if engine.running(session.tenant, auto_id):
183
+ raise err(409, "automation_running", "it is running β€” wait for it to finish")
184
+ defn, error = engine.toggle_node(session.runtime, auto_id, node_id)
185
+ if error:
186
+ raise err(404 if error == "no such automation" else 400,
187
+ "unknown_automation" if error == "no such automation" else "node_not_toggleable",
188
+ error)
189
+ return {"automation": _wire(defn, session.tenant)}
190
+
191
+
192
  @router.post("/automations/tick")
193
  def tick(request: Request, x_aios_tick_token: str = Header(default="")):
194
  """Fire every due schedule, for every tenant. The durable-cron entry point (R5).
api/routes_nav.py CHANGED
@@ -22,6 +22,34 @@ router = APIRouter(prefix="/api/v1")
22
  _NAV_PREFS_KEY = "nav_prefs"
23
  _MAX_NAV_FOLDERS = 16
24
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
25
 
26
  def _clean_nav_prefs(raw, page_keys):
27
  """Validated wholesale replacement, the `clean_folders` posture: prune, never invent.
@@ -58,6 +86,51 @@ def _visible_top_keys(user):
58
  return {p["key"] for p in pages if not p.get("parent")}
59
 
60
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
61
  @router.get("/nav")
62
  def nav(session: Session = Depends(require_session)):
63
  """`{pages: [{key,label,source?,chrome}], landing}`.
@@ -98,12 +171,143 @@ def nav(session: Session = Depends(require_session)):
98
  return {"pages": [], "landing": None, "empty": "no_databases"}
99
  raise err(403, "no_surfaces",
100
  "your account has no dashboards assigned β€” ask an administrator")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
101
  landing = perms.landing_page(session.user)
102
  if landing and not any(p.get("key") == landing for p in pages):
103
  landing = pages[0].get("key")
104
  return {"pages": pages, "landing": landing}
105
 
106
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
107
  @router.get("/nav/prefs")
108
  def nav_prefs(session: Session = Depends(require_session)):
109
  """This user's database-list folders, re-validated at serve time against what they may
@@ -155,7 +359,12 @@ def nav_schema(key: str, session: Session = Depends(require_session)):
155
  if not defn or not user_tables.may_open(key, session.uname, session.admin,
156
  st=session.runtime):
157
  raise err(403, "forbidden", "that database belongs to another user")
158
- return {"key": key, "label": defn.get("label") or key,
 
 
 
 
 
159
  "source": defn.get("source") or "Blank",
160
  "fields": [{"key": f["key"], "label": f["label"], "type": f["type"],
161
  "source": f.get("source") or "overlay", "description": ""}
 
22
  _NAV_PREFS_KEY = "nav_prefs"
23
  _MAX_NAV_FOLDERS = 16
24
 
25
+ #: WAVE 19 (R8 / contract C1): the database's NAME and ICON overrides.
26
+ #:
27
+ #: ⚠ TENANT-WIDE, which is the whole difference from `nav_prefs` above and the reason it is a
28
+ #: separate bucket rather than another field in that one. Folders and placement are one
29
+ #: person's arrangement of their own rail β€” per-user by definition. What a database is CALLED
30
+ #: and what it looks like are facts about the database: a workspace where two people call the
31
+ #: same table different things has no shared vocabulary left to discuss it in. Same store, two
32
+ #: buckets, because they answer to two different owners.
33
+ #:
34
+ #: Shape: {"<pageKey>": {"icon": {"shape": <FolderShape>, "tone": <FolderTone>},
35
+ #: "name": "<override, ut_* keys only>"}}
36
+ _NAV_META_KEY = "nav_meta"
37
+
38
+ #: The grid's folder-icon vocabulary, mirrored β€” 12 shapes x 5 tones. The CLIENT imports these
39
+ #: from `customer-grid/types` rather than redefining them; this end cannot import TypeScript,
40
+ #: so it is the one place the list is written twice.
41
+ #:
42
+ #: β›” WHAT AN UNKNOWN VALUE MUST NOT DO IS BE STORED. `FolderMark` indexes its path table by
43
+ #: shape and maps the result, so a shape this whitelist let through and the renderer does not
44
+ #: know is `undefined.map()` β€” a blank rail, from a stored preference, for every user in the
45
+ #: tenant until somebody edits the store by hand. Refusing at the door is the cheap end of
46
+ #: that. If the two lists ever drift the symptom is an icon that silently reverts to the
47
+ #: default, which is the loudest SAFE failure available here.
48
+ _ICON_SHAPES = frozenset({"folder", "star", "flag", "tag", "bookmark", "grid",
49
+ "chart", "map", "users", "clock", "heart", "bolt"})
50
+ _ICON_TONES = frozenset({"neutral", "blue", "green", "yellow", "red"})
51
+ _MAX_NAV_NAME = 60
52
+
53
 
54
  def _clean_nav_prefs(raw, page_keys):
55
  """Validated wholesale replacement, the `clean_folders` posture: prune, never invent.
 
86
  return {p["key"] for p in pages if not p.get("parent")}
87
 
88
 
89
+ def _clean_icon(raw):
90
+ """A stored/incoming icon, or None. Prune, never invent β€” `clean_folders`' posture."""
91
+ if not isinstance(raw, dict):
92
+ return None
93
+ shape, tone = raw.get("shape"), raw.get("tone")
94
+ if shape not in _ICON_SHAPES or tone not in _ICON_TONES:
95
+ return None
96
+ return {"shape": shape, "tone": tone}
97
+
98
+
99
+ def _read_nav_meta(runtime):
100
+ """The tenant's `nav_meta`, validated on the way OUT as well as in.
101
+
102
+ Re-validating a read looks redundant and is not: the bucket outlives this code, an older
103
+ build may have written a shape this one no longer accepts, and the whitelist is mirrored
104
+ from a vocabulary that lives in another language. A row whose icon does not survive
105
+ validation renders the default mark β€” never a crash, and never a half-drawn glyph.
106
+ """
107
+ try:
108
+ stored = runtime.get(_NAV_META_KEY) or {}
109
+ except Exception:
110
+ return {} # a store blip must not take the nav down with it
111
+ if not isinstance(stored, dict):
112
+ return {}
113
+ out = {}
114
+ for key, meta in stored.items():
115
+ if not isinstance(meta, dict):
116
+ continue
117
+ entry = {}
118
+ icon = _clean_icon(meta.get("icon"))
119
+ if icon:
120
+ entry["icon"] = icon
121
+ # β›” THE `ut_` RULE IS RE-APPLIED ON READ, not trusted from the record. The write
122
+ # route refuses a name for a built-in key, but a record written by an older build (or
123
+ # by hand) could still carry one β€” and honouring it would let the store rename
124
+ # `customer_data` on screen while `core/registry.py` and every other reader went on
125
+ # calling it Customer. A name that could not be written today is not served today.
126
+ name = meta.get("name")
127
+ if str(key).startswith("ut_") and isinstance(name, str) and name.strip():
128
+ entry["name"] = " ".join(name.split())[:_MAX_NAV_NAME]
129
+ if entry:
130
+ out[str(key)] = entry
131
+ return out
132
+
133
+
134
  @router.get("/nav")
135
  def nav(session: Session = Depends(require_session)):
136
  """`{pages: [{key,label,source?,chrome}], landing}`.
 
171
  return {"pages": [], "landing": None, "empty": "no_databases"}
172
  raise err(403, "no_surfaces",
173
  "your account has no dashboards assigned β€” ask an administrator")
174
+ # WAVE 19 (R8 / C1): the tenant's name + icon overrides, merged LAST β€” after the registry
175
+ # rows, after the tenant module filter, after the user tables. Merged HERE rather than
176
+ # applied by the client for one reason: `label` is what every reader of this payload shows,
177
+ # including the Settings modal's `moduleLabels` map, so a client-side merge would put the
178
+ # override in one door and the registry label in the other.
179
+ #
180
+ # β›” THIS MUTATES `pages` IN PLACE, WHICH IS SAFE ONLY BECAUSE `perms.nav_pages` BUILDS A
181
+ # FRESH `row = {...}` PER CALL (perms.py:194) and the ut_ rows are built fresh here. If
182
+ # either ever starts handing back cached or module-level dicts, this loop would write one
183
+ # tenant's chosen label into the object the NEXT tenant's request reads β€” a cross-tenant
184
+ # leak with no symptom until two tenants rename the same registry key. Copy the rows before
185
+ # merging on the day that invariant changes.
186
+ meta = _read_nav_meta(session.runtime)
187
+ for p in pages:
188
+ # `manage` (R14): may THIS session change this row's icon/name? Answered HERE because
189
+ # the server is the only end that knows β€” the client cannot see who created a user
190
+ # table. Additive and FAIL-CLOSED (absent reads as "no"), so the rail offers a control
191
+ # only where the write would actually land, and the route re-checks it regardless.
192
+ #
193
+ # ⚠ A `ut_` row's presence IS the answer: `user_tables.nav_entries` above filters by
194
+ # `may_open`, so a user table this session cannot manage never reached this list. That
195
+ # is why this line needs no second lookup β€” and why it must move if that filter ever
196
+ # widens to include tables a viewer may READ but not own.
197
+ if str(p.get("key", "")).startswith("ut_") or session.admin:
198
+ p["manage"] = True
199
+ entry = meta.get(p.get("key")) if meta else None
200
+ if not entry:
201
+ continue
202
+ if entry.get("icon"):
203
+ p["icon"] = entry["icon"]
204
+ if entry.get("name"):
205
+ p["label"] = entry["name"]
206
  landing = perms.landing_page(session.user)
207
  if landing and not any(p.get("key") == landing for p in pages):
208
  landing = pages[0].get("key")
209
  return {"pages": pages, "landing": landing}
210
 
211
 
212
+ @router.post("/nav/meta")
213
+ def save_nav_meta(body: dict = Body(default=None),
214
+ session: Session = Depends(require_session)):
215
+ """WAVE 19 (R8 / C1) β€” set one database's icon and/or name, tenant-wide.
216
+
217
+ A PATCH OF ONE KEY, not the wholesale replace `/nav/prefs` uses two routes up, and the
218
+ asymmetry is deliberate. Prefs are one user's complete picture of their own rail, so
219
+ replacing the document whole is what makes a deleted folder stay deleted. This bucket is
220
+ shared by every admin in the tenant: a wholesale write here means whoever saves last
221
+ silently erases what the other one named while their tab was open.
222
+
223
+ THREE WALLS, all fail-closed:
224
+ Β· the SESSION must be able to open the key at all (the same predicate the nav uses, so
225
+ the rail and this route cannot disagree about what exists);
226
+ Β· the WRITE is admin-only β€” renaming a database is a change every user in the tenant
227
+ sees, which is the definition of an administrative act here;
228
+ Β· `name` is refused outright for a non-`ut_` key. Built-in labels are compiled registry
229
+ literals: honouring an override would leave this payload and `core/registry.py`
230
+ calling the same module two different things, and the wave-16 lesson is that the
231
+ client must not be the place that decides what a payload meant.
232
+
233
+ `icon: null` CLEARS. An absent field is untouched β€” which is what makes a rename and an
234
+ icon change two independent writes rather than a race between them.
235
+ """
236
+ body = body if isinstance(body, dict) else {}
237
+ key = str(body.get("key") or "").strip()
238
+ if not key:
239
+ raise err(400, "bad_request", "no database was named")
240
+ # ── THE WALL (ruling R14, 2026-08-04) ────────────────────────────────────────────────────
241
+ # TWO DOORS, because a `ut_` database and a built-in module are owned by different people.
242
+ #
243
+ # Β· `ut_*` β€” the table's CREATOR or a tenant admin, which is exactly what
244
+ # `user_tables.may_open` already means. A database you made is yours to name; requiring
245
+ # an admin for that was the C1 consequence B flagged and R14 resolved. `session.require`
246
+ # is deliberately NOT used here: it is the MODULE gate and would 403 every ut_ key,
247
+ # because a user table is not a module. Same split `/nav/schema/{key}` makes.
248
+ # Β· everything else β€” admin only, and icon only. There is no owner of `customer_data` to
249
+ # defer to, and its label is a compiled registry literal (refused below regardless).
250
+ if key.startswith("ut_"):
251
+ import core.user_tables as user_tables
252
+ if not user_tables.get(key, st=session.runtime) or not user_tables.may_open(
253
+ key, session.uname, session.admin, st=session.runtime):
254
+ raise err(403, "forbidden", "that database belongs to another user")
255
+ else:
256
+ if not session.admin:
257
+ raise err(403, "forbidden",
258
+ "only an administrator can change a built-in database's icon")
259
+ session.require(key)
260
+
261
+ patch = {}
262
+ if "icon" in body:
263
+ icon = _clean_icon(body.get("icon"))
264
+ if body.get("icon") is not None and icon is None:
265
+ # Loud, not silent. A shape this build does not know is a CLIENT that has drifted
266
+ # from this whitelist, and answering 200 to a write that stored nothing is how
267
+ # that drift stays invisible until a user reports "my icon keeps resetting".
268
+ raise err(400, "bad_icon", "that icon is not one of the available shapes and tones")
269
+ patch["icon"] = icon
270
+ if "name" in body:
271
+ if not key.startswith("ut_"):
272
+ raise err(400, "name_not_allowed",
273
+ "only a database you created can be renamed β€” this one's name comes "
274
+ "from the module registry")
275
+ name = " ".join(str(body.get("name") or "").split())[:_MAX_NAV_NAME]
276
+ if not name:
277
+ raise err(400, "bad_request", "a database needs a name")
278
+ patch["name"] = name
279
+ if not patch:
280
+ raise err(400, "bad_request", "nothing to change")
281
+
282
+ if not session.runtime.available():
283
+ raise err(503, "store_unavailable",
284
+ "the tenant store is unavailable β€” nothing was saved")
285
+
286
+ def _up(data):
287
+ data = data if isinstance(data, dict) else {}
288
+ entry = dict(data.get(key) or {}) if isinstance(data.get(key), dict) else {}
289
+ for field, value in patch.items():
290
+ if value is None:
291
+ entry.pop(field, None) # an explicit null CLEARS
292
+ else:
293
+ entry[field] = value
294
+ # An entry with nothing left in it is removed rather than stored empty: the read side
295
+ # skips empties anyway, and a bucket that accumulates `{}` per key is a document that
296
+ # grows forever and says nothing.
297
+ if entry:
298
+ data[key] = entry
299
+ else:
300
+ data.pop(key, None)
301
+ return data
302
+
303
+ try:
304
+ session.runtime.update(_NAV_META_KEY, _up)
305
+ except Exception:
306
+ raise err(503, "store_unavailable",
307
+ "the change was not saved β€” the store refused the write")
308
+ return {"key": key, "meta": _read_nav_meta(session.runtime).get(key, {})}
309
+
310
+
311
  @router.get("/nav/prefs")
312
  def nav_prefs(session: Session = Depends(require_session)):
313
  """This user's database-list folders, re-validated at serve time against what they may
 
359
  if not defn or not user_tables.may_open(key, session.uname, session.admin,
360
  st=session.runtime):
361
  raise err(403, "forbidden", "that database belongs to another user")
362
+ # WAVE 19 (R8) β€” the drawer wears the RENAMED name. A rail that says one thing and a
363
+ # schema panel opened from it that says another is the drift a rename is supposed to
364
+ # remove, not create.
365
+ return {"key": key,
366
+ "label": (_read_nav_meta(session.runtime).get(key, {}).get("name")
367
+ or defn.get("label") or key),
368
  "source": defn.get("source") or "Blank",
369
  "fields": [{"key": f["key"], "label": f["label"], "type": f["type"],
370
  "source": f.get("source") or "overlay", "description": ""}
api/routes_platform_admin.py ADDED
@@ -0,0 +1,593 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """routes_platform_admin.py β€” THE LOOPABLE ADMIN PLANE (wave 19, owner item 13 / R3+R4).
2
+
3
+ Every other admin surface in this product answers questions about ONE tenant. This one answers
4
+ questions about the PLATFORM: who our customers are, what they are running, whether their data
5
+ sources are alive, and what the automation fleet costs. It is the first cross-tenant reader that
6
+ has ever existed here, which is why it is also the most carefully walled.
7
+
8
+ β›” THE WALL. `padmin_gate` is `core.platform_admin.is_platform_admin` β€” a DOUBLE lock (the record
9
+ flag AND the `loopable` tenant), fail-closed, applied to every single route in this file through
10
+ one dependency. A tenant admin is NOT admitted: `role: 'admin'` is Royal's or Nurilab's authority
11
+ over their own workspace and it must never widen into a view of each other. `verify_api.py`'s
12
+ W19-ADMIN section proves that by ENUMERATING this router and having a tenant admin try every path
13
+ it declares, so a route added later cannot quietly ship without the wall.
14
+
15
+ β›” CROSS-TENANT READS GO THROUGH EACH TENANT'S OWN RUNTIME. `runtime.get_runtime(slug)` per tenant,
16
+ then `rt.get(...)` β€” never `core.store.get("<raw key>")`. The runtime is what applies the store
17
+ NAMESPACE (`t/<slug>/…`) or binds the tenant's OWN dataset repo (R2), so reading raw keys would
18
+ silently return tenant #0's data labelled as somebody else's β€” a wrong answer that looks right,
19
+ which is the worst failure this plane could have.
20
+
21
+ HONEST DEGRADATION IS THE WHOLE DESIGN, NOT AN ERROR PATH. This plane reads six subsystems across
22
+ N tenants; on any given day one of them can be unreachable (a suspended tenant record, a locked
23
+ keychain, an HF repo hiccup, no AWS credentials in this container). A 500 would take the entire
24
+ dashboard down because one cell could not be filled. So every collector catches, and every row can
25
+ carry an `error` string that the pane RENDERS β€” "unknown" is a real answer and it is never
26
+ rendered as a zero. ([[gate-can-report-green-on-nothing]]: a fabricated 0 and a true 0 must not
27
+ look alike.)
28
+
29
+ EVERY COUNT DRILLS TO ROWS. `/overview`'s per-tenant counts are computed by the SAME collector
30
+ functions the `/users`, `/databases`, `/connectors` and `/automations` routes serve rows from, so
31
+ a number and its drill-down cannot disagree β€” they are one computation, projected twice
32
+ ([[no-unverifiable-aggregates]]).
33
+ """
34
+ import os
35
+ import subprocess
36
+ import sys
37
+ import time
38
+ from pathlib import Path
39
+
40
+ from fastapi import APIRouter, Depends
41
+
42
+ import core.platform_admin as platform_admin
43
+ import core.store as store
44
+ from deps import Session, err, require_session, users
45
+
46
+ router = APIRouter(prefix="/api/v1/platform-admin")
47
+
48
+
49
+ def _now_iso():
50
+ """UTC, offset-bearing β€” the one stamp format anything client-side may subtract from."""
51
+ import datetime as _dt
52
+ return _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds")
53
+
54
+
55
+ def padmin_gate(session: Session = Depends(require_session)) -> Session:
56
+ """401 without a session, 403 unless this account is a Loopable platform operator.
57
+
58
+ ONE dependency for the whole router. A per-route check is a per-route chance to forget, and
59
+ the thing being forgotten here would be every customer's data at once.
60
+
61
+ The message deliberately does not confirm that a platform plane exists for somebody else β€”
62
+ a tenant admin who pokes at this URL learns only that their account cannot open it.
63
+ """
64
+ if not platform_admin.is_platform_admin(session.user):
65
+ raise err(403, "forbidden", "your account does not have access to this surface")
66
+ return session
67
+
68
+
69
+ # ══════════════════════════════════════════════════════════════════════════ tenants
70
+
71
+
72
+ def _tenant_bucket():
73
+ """The control-plane `tenants` records, or {} β€” a platform fact, in the DEFAULT store."""
74
+ from harness import runtime
75
+ try:
76
+ recs = store.get(runtime.TENANTS_KEY) or {}
77
+ return {str(k).strip().lower(): v for k, v in recs.items() if isinstance(v, dict)}
78
+ except Exception:
79
+ return {}
80
+
81
+
82
+ def _slugs():
83
+ """Every tenant this deployment knows: compiled builders + control-plane records.
84
+
85
+ `runtime.known_tenants()` is the union and it is the same list login resolves against, so
86
+ this plane cannot show a customer the door does not recognise (or miss one it does).
87
+ """
88
+ from harness import runtime
89
+ try:
90
+ return list(runtime.known_tenants())
91
+ except Exception:
92
+ return sorted(_tenant_bucket())
93
+
94
+
95
+ def _runtime_for(slug):
96
+ """(runtime, error). A tenant whose runtime will not build is a ROW WITH A NOTE, never a 500.
97
+
98
+ Two real cases produce one: a SUSPENDED record (`get_runtime` raises KeyError by design β€”
99
+ "which tenants exist" is not a question the login path answers), and tenant #0's builder,
100
+ which makes a LIVE Odoo call (`harness.tenants.royal_imports` β†’ `excluded_customer_ids`) and
101
+ therefore fails on a box that cannot reach the ERP. Neither may take the dashboard down.
102
+ """
103
+ from harness import runtime
104
+ try:
105
+ return runtime.get_runtime(slug), ""
106
+ except KeyError:
107
+ return None, "not resolvable (suspended, or no builder and no active record)"
108
+ except Exception as e: # noqa: BLE001
109
+ return None, f"runtime unavailable ({type(e).__name__})"
110
+
111
+
112
+ def _scan(want=""):
113
+ """[(row, runtime)] β€” every tenant (or one), with its runtime RESOLVED EXACTLY ONCE.
114
+
115
+ The one-resolution rule is not tidiness. `get_runtime` is LRU-cached on success, but a tenant
116
+ that FAILS to build is not cached, and tenant #0's builder makes a live Odoo call β€” so a route
117
+ that asked twice would pay the timeout twice, and `/overview` (which asks about six
118
+ subsystems) would pay it six times. Resolve once, pass the handle down.
119
+ """
120
+ bucket = _tenant_bucket()
121
+ want = str(want or "").strip().lower()
122
+ out = []
123
+ for slug in _slugs():
124
+ if want and slug != want:
125
+ continue
126
+ rec = bucket.get(slug) or {}
127
+ rt, error = _runtime_for(slug)
128
+ out.append(({
129
+ "slug": slug,
130
+ # The record's name, else the built runtime's, else the slug. Tenant #0 is compiled
131
+ # and has no record, so without the runtime fallback it would render as "royal-imports".
132
+ "name": str(rec.get("name") or (getattr(rt, "name", "") if rt else "") or slug),
133
+ "source": "record" if rec else "compiled",
134
+ "status": str(rec.get("status") or ("active" if rt else "unknown")),
135
+ "domains": list(rec.get("domains") or []),
136
+ "modules": rec.get("modules", "all" if not rec else []),
137
+ # R2: the isolation shape. "own repo" and "shared repo + prefix" are genuinely
138
+ # different blast radii and an operator should be able to see which is which.
139
+ "storeRepo": rec.get("store_repo") or ("shared (tenant #0 repo)" if not rec else ""),
140
+ "storePrefix": getattr(rt, "store_namespace", "") if rt else "",
141
+ "error": error,
142
+ }, rt))
143
+ return out
144
+
145
+
146
+ # ══════════════════════════════════════════════════════════════════════════ users
147
+
148
+
149
+ def _user_rows(tenant=None):
150
+ """Accounts across every tenant, from the GLOBAL registry (`users.json` is control-plane).
151
+
152
+ β›” NEVER `salt` OR `hash`. This projection is the only one these routes use, mirroring
153
+ `routes_admin._view`'s discipline: one function that can leak, and it does not.
154
+
155
+ R4's two new fields ride here β€” `lastLogin` / `lastActive`, absent on every pre-wave record,
156
+ rendered as "never" rather than as a fabricated date.
157
+ """
158
+ try:
159
+ reg = users.registry() or {}
160
+ except Exception:
161
+ return []
162
+ want = str(tenant or "").strip().lower()
163
+ rows = []
164
+ for uname, rec in sorted(reg.items()):
165
+ if not isinstance(rec, dict):
166
+ continue
167
+ slug = str(rec.get("tenant") or "royal-imports").strip().lower()
168
+ if want and slug != want:
169
+ continue
170
+ rows.append({
171
+ "username": uname,
172
+ "name": rec.get("name") or uname,
173
+ "email": rec.get("email") or "",
174
+ "tenant": slug,
175
+ "role": rec.get("role", "user"),
176
+ "active": bool(rec.get("active", True)),
177
+ "lastLogin": rec.get("last_login") or "",
178
+ "lastActive": rec.get("last_active") or "",
179
+ "platformAdmin": rec.get("platform_admin") is True,
180
+ })
181
+ return rows
182
+
183
+
184
+ # ══════════════════════════════════════════════════════════════════════════ databases
185
+
186
+
187
+ def _database_rows(slug, rt):
188
+ """A tenant's user-created databases (`ut_*`) with their row counts.
189
+
190
+ Via `core.user_tables.all_tables(st=rt)` β€” the TenantRuntime, never the module-global, which
191
+ the engine's own header (`automation_engine.py:49-52`) flags as a cross-tenant defect for
192
+ every R2 tenant. That booked defect is exactly the mistake a cross-tenant reader would make
193
+ most easily, so it is stated at the call site too.
194
+ """
195
+ try:
196
+ import core.user_tables as ut
197
+ tables = ut.all_tables(st=rt) or {}
198
+ except Exception as e: # noqa: BLE001
199
+ return [], f"databases unreadable ({type(e).__name__})"
200
+ rows = []
201
+ for key, t in sorted(tables.items(), key=lambda kv: (kv[1].get("label") or "").lower()):
202
+ if not isinstance(t, dict):
203
+ continue
204
+ rows.append({
205
+ "tenant": slug,
206
+ "key": key,
207
+ "label": t.get("label") or key,
208
+ "source": t.get("source") or "Blank",
209
+ "createdBy": t.get("createdBy") or "",
210
+ "created": t.get("created") or "",
211
+ "fields": len(t.get("fields") or []),
212
+ "rowCount": len(t.get("rows") or {}),
213
+ })
214
+ return rows, ""
215
+
216
+
217
+ # ══════════════════════════════════════════════════════════════════════════ connectors
218
+
219
+
220
+ def _connector_rows(slug, rt):
221
+ """A tenant's data sources and which one is actually RESOLVED (i.e. would serve a query).
222
+
223
+ `_resolved_odoo_key` is imported from `routes_keychain` rather than re-derived. It is the
224
+ route-level mirror of `TenantRuntime.odoo_source()`, it takes a runtime (not a session), and
225
+ a second copy of that resolution here would be a copy that drifts β€” at which point this plane
226
+ would confidently name the wrong live connector. Reused, not restated.
227
+ """
228
+ try:
229
+ import core.keychain as keychain
230
+ from routes_keychain import _CONNECTOR_FLAGS_KEY, _resolved_odoo_key
231
+ entries = keychain.list_entries(rt)
232
+ locked = not keychain.unlocked()
233
+ resolved, _flag = _resolved_odoo_key(rt)
234
+ flags = rt.get(_CONNECTOR_FLAGS_KEY) or {}
235
+ except Exception as e: # noqa: BLE001
236
+ return [], f"connectors unreadable ({type(e).__name__})", False
237
+
238
+ rows = []
239
+ if slug == "royal-imports" and os.environ.get("ODOO_URL"):
240
+ rows.append({"tenant": slug, "key": "odoo-env", "label": "Odoo (environment)",
241
+ "type": "odoo", "source": "env", "active": resolved == "env",
242
+ "paused": bool((flags.get("odoo-env") or {}).get("paused"))})
243
+ for e in entries:
244
+ rows.append({"tenant": slug, "key": e["id"], "label": e["label"], "type": e["type"],
245
+ "source": "keychain",
246
+ "active": e["type"] == "odoo" and resolved == f"keychain:{e['id']}",
247
+ "paused": bool((flags.get(e["id"]) or {}).get("paused"))})
248
+ return rows, "", locked
249
+
250
+
251
+ # ══════════════════════════════════════════════════════════════════════════ automations + cost
252
+
253
+ #: THE UNIT MODEL, from `ops/provision_automation_cron.py` (its cost note at :25-28 and the
254
+ #: function it actually provisions at :211 / :269). Restated as constants rather than as prose so
255
+ #: the arithmetic below is re-checkable against the thing that was really deployed:
256
+ #: EventBridge Scheduler `rate(15 minutes)` β†’ a 128 MB, 30 s-timeout Lambda that POSTs the tick.
257
+ TICK_CADENCE = "rate(15 minutes)"
258
+ TICK_PER_DAY = 96 # 1440 / 15
259
+ LAMBDA_MB = 128
260
+ FREE_LAMBDA_REQUESTS = 1_000_000 # AWS always-free, per month
261
+ FREE_SCHEDULER_INVOCATIONS = 14_000_000
262
+ DAYS_PER_MONTH = 30.4
263
+
264
+
265
+ def _runs_per_day(cron):
266
+ """Scheduled runs/day for the five-field crons this product offers, or None.
267
+
268
+ ⚠ DELIBERATELY NARROW. It answers exactly the shapes `automation_engine.CRON_PRESETS` can
269
+ produce (every-N-minutes, hourly, daily, weekly, monthly) and returns None for anything else
270
+ β€” an unparsed cadence is reported as "custom", never as a guessed number that would then be
271
+ multiplied into a cost. A wrong denominator is worse than an absent one.
272
+
273
+ ⚠ AND IT IS NOT MEASURED FROM HISTORY, on purpose: `automation_engine.MAX_RUNS` trims run
274
+ history to 20 entries, so a 15-minute automation retains ~5 hours of it. Deriving runs/day
275
+ from that window would understate by ~5x. History is reported as what it is β€” the last N runs.
276
+ """
277
+ parts = str(cron or "").split()
278
+ if len(parts) != 5:
279
+ return None
280
+ minute, hour, dom, _mon, dow = parts
281
+ if minute.startswith("*/") and hour == "*":
282
+ try:
283
+ step = int(minute[2:])
284
+ except ValueError:
285
+ return None
286
+ return (1440.0 / step) if step > 0 else None
287
+ if minute.isdigit() and hour == "*":
288
+ return 24.0
289
+ if minute.isdigit() and hour.isdigit():
290
+ if dom.isdigit():
291
+ return 1.0 / DAYS_PER_MONTH # monthly
292
+ if dow.isdigit():
293
+ return 1.0 / 7.0 # weekly
294
+ return 1.0 # daily
295
+ return None
296
+
297
+
298
+ def _automation_rows(slug, rt):
299
+ """A tenant's automations, their schedules, and their retained run history."""
300
+ try:
301
+ import automation_engine as engine
302
+ defs = engine.all_definitions(rt) or {}
303
+ max_runs = int(getattr(engine, "MAX_RUNS", 20))
304
+ except Exception as e: # noqa: BLE001
305
+ return [], f"automations unreadable ({type(e).__name__})", 20
306
+ rows = []
307
+ for auto_id, d in sorted(defs.items(), key=lambda kv: (kv[1].get("name") or "").lower()):
308
+ if not isinstance(d, dict):
309
+ continue
310
+ sched = d.get("schedule") or {}
311
+ status = d.get("status") or {}
312
+ runs = list(d.get("runs") or [])
313
+ cron = sched.get("cron") or ""
314
+ per_day = _runs_per_day(cron) if sched.get("enabled") else 0.0
315
+ rows.append({
316
+ "tenant": slug,
317
+ "id": auto_id,
318
+ "name": d.get("name") or auto_id,
319
+ "kind": d.get("kind") or "",
320
+ "enabled": bool(sched.get("enabled")),
321
+ "cron": cron,
322
+ "runsPerDay": round(per_day, 2) if per_day is not None else None,
323
+ "state": status.get("state") or "idle",
324
+ "lastRunAt": status.get("lastRunAt") or "",
325
+ "lastSummary": status.get("lastSummary") or "",
326
+ # The retained window, named as such β€” see `_runs_per_day`'s second warning.
327
+ "runsRetained": len(runs),
328
+ "failedRetained": sum(1 for r in runs if isinstance(r, dict) and not r.get("ok")),
329
+ "createdBy": d.get("createdBy") or "",
330
+ "created": d.get("created") or "",
331
+ })
332
+ return rows, "", max_runs
333
+
334
+
335
+ def _automation_cost(auto_rows):
336
+ """The estimated monthly cost of running the automation fleet β€” and the honest shape of it.
337
+
338
+ THE POINT THIS BLOCK EXISTS TO MAKE, which is not intuitive: **the external cron does not
339
+ scale with automations or tenants.** One EventBridge schedule fires one Lambda, which POSTs
340
+ one tick, and that tick runs every DUE automation for every tenant (`provision_automation_cron`
341
+ states this as the reason it stays $0 "at ten tenants"). So the AWS bill is a function of the
342
+ CADENCE alone β€” the fleet below adds work inside the API container, which is already paid for.
343
+
344
+ WHAT IS NOT COMPUTED HERE, deliberately: Lambda GB-seconds. That needs the real average
345
+ duration of the function, which only CloudWatch knows; assuming one would be inventing the
346
+ larger half of the free-tier calculation. `/aws` reports the measured figure when credentials
347
+ are available, and this block says so rather than filling the gap with a plausible number.
348
+ """
349
+ invocations = TICK_PER_DAY * DAYS_PER_MONTH
350
+ fleet_runs = sum(r["runsPerDay"] or 0 for r in auto_rows if r.get("enabled"))
351
+ unknown_cadence = sum(1 for r in auto_rows if r.get("enabled") and r.get("runsPerDay") is None)
352
+ return {
353
+ "cadence": TICK_CADENCE,
354
+ "invocationsPerMonth": int(round(invocations)),
355
+ "freeRequestsPct": round(100.0 * invocations / FREE_LAMBDA_REQUESTS, 3),
356
+ "freeSchedulerPct": round(100.0 * invocations / FREE_SCHEDULER_INVOCATIONS, 4),
357
+ "lambdaMb": LAMBDA_MB,
358
+ "usd": 0.0,
359
+ "fleetRunsPerDay": round(fleet_runs, 2),
360
+ "unknownCadence": unknown_cadence,
361
+ "basis": (
362
+ f"One EventBridge schedule ({TICK_CADENCE}) fires one {LAMBDA_MB} MB Lambda that "
363
+ f"POSTs the tick; that ONE tick runs every due automation for every tenant, so the "
364
+ f"AWS cost is set by the cadence and does not grow with the fleet. "
365
+ f"{int(round(invocations)):,} invocations/month is "
366
+ f"{round(100.0 * invocations / FREE_LAMBDA_REQUESTS, 3)}% of the 1,000,000-request "
367
+ f"always-free tier, so the marginal cost of the automations below is $0.00. "
368
+ f"Compute (GB-seconds) depends on measured durations and is NOT estimated here β€” "
369
+ f"the AWS report reads the real figure when credentials are available."
370
+ ),
371
+ }
372
+
373
+
374
+ # ══════════════════════════════════════════════════════════════════════════ the AWS report
375
+
376
+ #: `ops/aws_usage_report.py`, relative to this file: aios-web/api/ -> repo root -> ops/.
377
+ _AWS_REPORT = Path(__file__).resolve().parents[2] / "ops" / "aws_usage_report.py"
378
+ _AWS_TIMEOUT = 60
379
+
380
+
381
+ def _aws_report(days=7):
382
+ """The AWS usage report as text, or an honest block saying why there is none.
383
+
384
+ β›” SUBPROCESS, NEVER `import`. Two concrete reasons, both found by reading that file rather
385
+ than by running it:
386
+ * it reassigns `sys.stdout` to a UTF-8 wrapper AT MODULE IMPORT (a cp1252 fix for this
387
+ box) β€” importing it would mutate the API process's stdout as a side effect;
388
+ * its `main()` calls `argparse.parse_args()` with no argv, so inside a server it would
389
+ parse UVICORN's arguments and can `sys.exit(2)` β€” and `SystemExit` is a `BaseException`,
390
+ which `except Exception` does not catch. A route that "cannot crash" would crash.
391
+
392
+ ⚠ ON THE SPACE THIS IS THE NORMAL PATH, NOT THE ERROR PATH. `deploy_web.py` ships `api/*.py`
393
+ and `web/`; `ops/` is not in the image, and AWS credentials live in a local `.env` that is
394
+ never deployed. So the honest block below is what the deployed plane shows, and it is written
395
+ to be read by an operator as information ("run it here") rather than as a fault.
396
+ """
397
+ if not _AWS_REPORT.is_file():
398
+ return {"available": False, "text": "",
399
+ "note": ("The AWS usage report is not part of this deployment β€” `ops/` ships "
400
+ "with the repository, not with the container image. Run "
401
+ "`python ops/aws_usage_report.py` locally for the live figures.")}
402
+ try:
403
+ proc = subprocess.run(
404
+ [sys.executable, str(_AWS_REPORT), "--days", str(int(days))],
405
+ capture_output=True, text=True, timeout=_AWS_TIMEOUT,
406
+ cwd=str(_AWS_REPORT.parent.parent))
407
+ except subprocess.TimeoutExpired:
408
+ return {"available": False, "text": "",
409
+ "note": (f"The AWS report did not answer within {_AWS_TIMEOUT}s β€” CloudWatch may "
410
+ f"be unreachable from here. Nothing was assumed about usage.")}
411
+ except Exception as e: # noqa: BLE001
412
+ return {"available": False, "text": "",
413
+ "note": f"The AWS report could not be run here ({type(e).__name__})."}
414
+ out = (proc.stdout or "").strip()
415
+ if proc.returncode != 0 or not out:
416
+ detail = (proc.stderr or "").strip().splitlines()
417
+ return {"available": False, "text": out,
418
+ "note": ("AWS credentials are not available here, or boto3 is not installed β€” "
419
+ "no usage could be read, and none is guessed. "
420
+ + (detail[-1][:200] if detail else ""))}
421
+ return {"available": True, "text": out, "note": ""}
422
+
423
+
424
+ # ══════════════════════════════════════════════════════════════════════════ routes
425
+
426
+
427
+ @router.get("/overview")
428
+ def overview(session: Session = Depends(padmin_gate)):
429
+ """THE PLANE'S ONE TABLE: every tenant, with the counts that drill to the rows below.
430
+
431
+ Each count is produced by the same collector its `/…` route serves, so the number and its
432
+ drill-down are one computation projected twice. A subsystem that cannot be read contributes
433
+ an `errors` entry on that tenant's row and a NULL count β€” never a zero, which would read as
434
+ "this customer has no databases" when the truth is "we could not look".
435
+ """
436
+ t0 = time.time()
437
+ all_users = _user_rows()
438
+ users_by_tenant = {}
439
+ for u in all_users:
440
+ users_by_tenant.setdefault(u["tenant"], []).append(u)
441
+
442
+ rows = []
443
+ for t, rt in _scan():
444
+ slug = t["slug"]
445
+ row = dict(t)
446
+ row["users"] = len(users_by_tenant.get(slug, []))
447
+ row["admins"] = sum(1 for u in users_by_tenant.get(slug, []) if u["role"] == "admin")
448
+ errors = [t["error"]] if t["error"] else []
449
+ if rt is None:
450
+ # An unresolvable tenant still shows its ACCOUNTS (they live in the global registry,
451
+ # which is readable regardless) β€” everything tenant-store-shaped is honestly unknown.
452
+ row.update({"databases": None, "rows": None, "connectors": None,
453
+ "automations": None, "keychainLocked": None, "errors": errors})
454
+ rows.append(row)
455
+ continue
456
+ dbs, db_err = _database_rows(slug, rt)
457
+ conns, conn_err, locked = _connector_rows(slug, rt)
458
+ autos, auto_err, _mr = _automation_rows(slug, rt)
459
+ errors += [e for e in (db_err, conn_err, auto_err) if e]
460
+ row.update({
461
+ "databases": None if db_err else len(dbs),
462
+ "rows": None if db_err else sum(d["rowCount"] for d in dbs),
463
+ "connectors": None if conn_err else len(conns),
464
+ "connectorsPaused": None if conn_err else sum(1 for c in conns if c["paused"]),
465
+ "automations": None if auto_err else len(autos),
466
+ "automationsEnabled": None if auto_err else sum(1 for a in autos if a["enabled"]),
467
+ "keychainLocked": None if conn_err else locked,
468
+ "errors": errors,
469
+ })
470
+ rows.append(row)
471
+
472
+ return {
473
+ "tenants": rows,
474
+ "totals": {
475
+ "tenants": len(rows),
476
+ # EVERY account, not the sum of the rows: an account whose `tenant` names a slug this
477
+ # deployment no longer knows belongs in the platform total and would vanish from a
478
+ # per-row sum. `orphanUsers` names that gap instead of hiding it.
479
+ "users": len(all_users),
480
+ "orphanUsers": len(all_users) - sum(r["users"] for r in rows),
481
+ # Sums SKIP unknowns rather than treating them as 0, and say how many were skipped β€”
482
+ # a total that silently absorbs an unreadable tenant is a fabricated total.
483
+ "databases": sum(r["databases"] or 0 for r in rows),
484
+ "rows": sum(r["rows"] or 0 for r in rows),
485
+ "automations": sum(r["automations"] or 0 for r in rows),
486
+ "unknownTenants": sum(1 for r in rows if r["databases"] is None),
487
+ },
488
+ "storeAvailable": bool(_store_ok()),
489
+ # ⚠ OFFSET-BEARING, and that is not pedantry. The client renders this as "read 2 minutes
490
+ # ago" via `Date.parse`, which reads a NAIVE stamp as browser-local β€” so a UTC container
491
+ # and a US viewer would turn "just now" into "5 hours ago", or into a future date that
492
+ # renders as "just now" forever. The stamps written by `core.users` carry an offset for
493
+ # the same reason; anything a browser subtracts from `Date.now()` must say what zone it
494
+ # is in. `verify_api` asserts the offset so this cannot regress to `strftime`.
495
+ "generatedAt": _now_iso(),
496
+ "tookMs": int((time.time() - t0) * 1000),
497
+ }
498
+
499
+
500
+ def _store_ok():
501
+ try:
502
+ return store.available()
503
+ except Exception:
504
+ return False
505
+
506
+
507
+ @router.get("/users")
508
+ def platform_users(tenant: str = "", session: Session = Depends(padmin_gate)):
509
+ """Every account on the platform, or one tenant's β€” the drill behind the Users count.
510
+
511
+ R4's stamps are the columns that did not exist before this wave: `lastLogin` is written by
512
+ `routes_auth.login`, `lastActive` by `deps.require_session` (throttled to once an hour per
513
+ account per process). Absent means never seen, and the pane renders it as "never".
514
+ """
515
+ rows = _user_rows(tenant)
516
+ return {"users": rows, "count": len(rows),
517
+ "stampsNote": ("Login and activity stamps started with this release β€” accounts that "
518
+ "have not signed in since show no date rather than an invented one. "
519
+ "Activity is recorded at most once an hour per account.")}
520
+
521
+
522
+ @router.get("/databases")
523
+ def platform_databases(tenant: str = "", session: Session = Depends(padmin_gate)):
524
+ """Every tenant's user-created databases and row counts β€” the drill behind Databases/Rows."""
525
+ out, errors = [], {}
526
+ for t, rt in _scan(tenant):
527
+ slug = t["slug"]
528
+ if rt is None:
529
+ errors[slug] = t["error"]
530
+ continue
531
+ rows, err = _database_rows(slug, rt)
532
+ if err:
533
+ errors[slug] = err
534
+ continue
535
+ out += rows
536
+ return {"databases": out, "count": len(out),
537
+ "rows": sum(d["rowCount"] for d in out), "errors": errors}
538
+
539
+
540
+ @router.get("/connectors")
541
+ def platform_connectors(tenant: str = "", session: Session = Depends(padmin_gate)):
542
+ """Every tenant's data sources, which one is live, and which are paused.
543
+
544
+ METADATA ONLY β€” `keychain.list_entries` never decrypts, so no credential, and no masked
545
+ preview either: a platform operator needs to know a source EXISTS and whether it serves, not
546
+ what the secret looks like. The tenant's own admin surface is where previews belong.
547
+ """
548
+ out, errors, locked_any = [], {}, {}
549
+ for t, rt in _scan(tenant):
550
+ slug = t["slug"]
551
+ if rt is None:
552
+ errors[slug] = t["error"]
553
+ continue
554
+ rows, err, locked = _connector_rows(slug, rt)
555
+ if err:
556
+ errors[slug] = err
557
+ continue
558
+ locked_any[slug] = locked
559
+ out += rows
560
+ return {"connectors": out, "count": len(out), "keychainLocked": locked_any,
561
+ "errors": errors,
562
+ "note": ("A locked keychain means this container has no `AIOS_KEYCHAIN_KEY` β€” stored "
563
+ "credentials cannot be read, so a tenant's sources fail closed rather than "
564
+ "falling back to anyone else's.")}
565
+
566
+
567
+ @router.get("/automations")
568
+ def platform_automations(tenant: str = "", session: Session = Depends(padmin_gate)):
569
+ """Every tenant's automations, their schedules and run history, plus the fleet cost model."""
570
+ out, errors, retained = [], {}, 20
571
+ for t, rt in _scan(tenant):
572
+ slug = t["slug"]
573
+ if rt is None:
574
+ errors[slug] = t["error"]
575
+ continue
576
+ rows, err, max_runs = _automation_rows(slug, rt)
577
+ if err:
578
+ errors[slug] = err
579
+ continue
580
+ retained = max_runs
581
+ out += rows
582
+ return {"automations": out, "count": len(out),
583
+ "enabled": sum(1 for a in out if a["enabled"]),
584
+ "historyRetained": retained,
585
+ "cost": _automation_cost(out), "errors": errors,
586
+ "tickEnabled": os.environ.get("AIOS_AUTOMATIONS") == "1"}
587
+
588
+
589
+ @router.get("/aws")
590
+ def platform_aws(days: int = 7, session: Session = Depends(padmin_gate)):
591
+ """The AWS cron's usage report, verbatim, or an honest note explaining its absence."""
592
+ days = max(1, min(int(days or 7), 90))
593
+ return {"days": days, "report": _aws_report(days)}
api/routes_products.py CHANGED
@@ -52,23 +52,18 @@ def _pool_for(rt, team_id):
52
  lambda: pd.pool(team_id=team_id))
53
 
54
 
55
- def product_assembly(session: Session, scope: str = "product", storage_key: str = "",
56
- consume_corrections: bool = True):
57
- """The product topic's mirror of `routes_customers.grid_assembly` β€” SAME g-dict keys, so
58
- the /workspace and events routes consume either interchangeably.
59
 
60
- Three deliberate absences, each a topic fact rather than a gap:
61
- * `measures`/`measure_sets` are EMPTY β€” `core.measure_resolve` is CUSTOMER-grain (the
62
- C-TOPIC v1 descope, booked in the wave doc); the events ctx therefore refuses measure
63
- creates on this surface, which is the correct fail-closed shape.
64
- * `lists` is EMPTY and `workspace_wire(with_cohorts=False)` β€” cohorts store PARTNER pids;
65
- resolving them against CRC32 product pids would intersect two unrelated id spaces.
66
- * `derived` is EMPTY β€” it exists to carry cohort + measure cells, and there are neither.
67
  """
68
- import aios_grid
69
  import core.perm_scope as perm_scope
70
- import modules.product_data as pd
71
- from core import grid_events
72
 
73
  team_id, _agent = perm_scope.derive_pool_scope(session.user, MODULE)
74
  try:
@@ -76,13 +71,39 @@ def product_assembly(session: Session, scope: str = "product", storage_key: str
76
  except Exception as e:
77
  raise err(503, "pool_unavailable",
78
  f"the product catalogue could not be built β€” {str(e)[:160]}")
79
-
80
  fields_base = pd_fields(consolidated=team_id is None)
81
  # The SAME wall the customer assembly applies, in the same order: rows first (before pids
82
  # are taken, so an out-of-filter row never enters allowed_pids), then the field closure,
83
  # then the values stripped from the rows as well as the field list.
84
  rows_src = perm_scope.apply_row_scope(rows_src, session.user, MODULE, fields_base)
85
  pids = frozenset(r["pid"] for r in rows_src if r.get("pid") is not None)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
86
 
87
  ctx = grid_events.EventCtx(
88
  uname=session.uname, allowed_pids=pids, fields=[],
@@ -93,7 +114,7 @@ def product_assembly(session: Session, scope: str = "product", storage_key: str
93
  consume_corrections=consume_corrections)
94
  workspace, fields, views, lists = aios_grid.workspace_wire(
95
  ws, session.uname, set(pids), defs={}, scope_key=scope, storage_key=storage_key,
96
- fields_base=fields_base, with_cohorts=False)
97
 
98
  hidden = perm_scope.hidden_keys(session.user, MODULE, fields)
99
  if hidden:
@@ -101,7 +122,10 @@ def product_assembly(session: Session, scope: str = "product", storage_key: str
101
  rows_src = [perm_scope.strip_row(r, hidden) for r in rows_src]
102
 
103
  return {"rows_src": rows_src, "pids": pids, "ws": ws, "workspace": workspace,
104
- "fields": fields, "views": views, "lists": lists, "derived": {},
 
 
 
105
  "measures": [], "measure_sets": {}, "today": time.strftime("%Y-%m-%d"),
106
  "team_id": team_id}
107
 
@@ -119,8 +143,9 @@ def products(session: Session = Depends(module_gate(MODULE))):
119
  import aios_grid
120
 
121
  g = product_assembly(session)
122
- rows = aios_grid.rows_from_pool(
123
- g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"])
 
124
  return {"fields": g["fields"], "rows": rows,
125
  "today": g["today"], "pulled_at": time.strftime("%Y-%m-%d %H:%M"),
126
  "identity": {"pid": "pid", "businessKey": "code"},
@@ -173,6 +198,46 @@ def patch_product(pid: int, body: dict = Body(default=None),
173
  return out
174
 
175
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
176
  def pd_fields(consolidated=True):
177
  """The product field contract, minus the CONSOLIDATED-only columns when the caller is scoped.
178
 
@@ -189,6 +254,16 @@ def pd_fields(consolidated=True):
189
  doc = json.loads((Path(aios_grid.__file__).resolve().parent /
190
  "aios_grid_fields.json").read_text(encoding="utf-8"))
191
  fields = list((doc.get("product_data") or {}).get("fields") or [])
 
 
 
 
 
 
 
 
 
 
192
  if consolidated:
193
  return fields
194
  import modules.product_data as pd
 
52
  lambda: pd.pool(team_id=team_id))
53
 
54
 
55
+ def scoped_pool(session: Session):
56
+ """`(pids, team_id, rows_src, fields_base)` β€” THE PRODUCT WALL, on its own.
 
 
57
 
58
+ Extracted from `product_assembly` (wave 19, item 12) so a caller that needs only "which
59
+ products may this session touch" β€” record comments, say β€” asks the SAME question in the same
60
+ order rather than re-deriving it: pool scope from the permanent filter, rows, THEN the row
61
+ wall, THEN the pids. Re-deriving it is how a second wall drifts from the first, and the
62
+ walls are the whole point of this route.
63
+
64
+ ⚠ The caller is responsible for the GRANT (`session.require(MODULE)`); this is the row half.
65
  """
 
66
  import core.perm_scope as perm_scope
 
 
67
 
68
  team_id, _agent = perm_scope.derive_pool_scope(session.user, MODULE)
69
  try:
 
71
  except Exception as e:
72
  raise err(503, "pool_unavailable",
73
  f"the product catalogue could not be built β€” {str(e)[:160]}")
 
74
  fields_base = pd_fields(consolidated=team_id is None)
75
  # The SAME wall the customer assembly applies, in the same order: rows first (before pids
76
  # are taken, so an out-of-filter row never enters allowed_pids), then the field closure,
77
  # then the values stripped from the rows as well as the field list.
78
  rows_src = perm_scope.apply_row_scope(rows_src, session.user, MODULE, fields_base)
79
  pids = frozenset(r["pid"] for r in rows_src if r.get("pid") is not None)
80
+ return pids, team_id, rows_src, fields_base
81
+
82
+
83
+ def product_assembly(session: Session, scope: str = "product", storage_key: str = "",
84
+ consume_corrections: bool = True):
85
+ """The product topic's mirror of `routes_customers.grid_assembly` β€” SAME g-dict keys, so
86
+ the /workspace and events routes consume either interchangeably.
87
+
88
+ One deliberate absence, a topic fact rather than a gap:
89
+ * `measures`/`measure_sets` are EMPTY β€” `core.measure_resolve` is CUSTOMER-grain (the
90
+ C-TOPIC v1 descope, booked in the wave doc); the events ctx therefore refuses measure
91
+ creates on this surface, which is the correct fail-closed shape.
92
+
93
+ ⭐ WAVE 19 / R9 β€” `lists` IS NO LONGER EMPTY. Wave 16 passed `with_cohorts=False` because
94
+ there was one customer-keyed cohort bucket and product pids are CRC32 hashes of SKU codes;
95
+ intersecting the two id spaces would have printed a plausible, meaningless member count. The
96
+ owner's ruling is that a cohort belongs to its database, so `modules.cohort` grew a bucket
97
+ per topic and the product surface reads `product_cohorts` β€” ids from this pool, resolved
98
+ against this pool. `derived` carries their membership cells (the Cohorts column) for the same
99
+ reason it does on the customer surface; the measure half of that channel stays empty.
100
+ """
101
+ import aios_grid
102
+ import core.perm_scope as perm_scope
103
+ import modules.product_data as pd
104
+ from core import grid_events
105
+
106
+ pids, team_id, rows_src, fields_base = scoped_pool(session)
107
 
108
  ctx = grid_events.EventCtx(
109
  uname=session.uname, allowed_pids=pids, fields=[],
 
114
  consume_corrections=consume_corrections)
115
  workspace, fields, views, lists = aios_grid.workspace_wire(
116
  ws, session.uname, set(pids), defs={}, scope_key=scope, storage_key=storage_key,
117
+ fields_base=fields_base)
118
 
119
  hidden = perm_scope.hidden_keys(session.user, MODULE, fields)
120
  if hidden:
 
122
  rows_src = [perm_scope.strip_row(r, hidden) for r in rows_src]
123
 
124
  return {"rows_src": rows_src, "pids": pids, "ws": ws, "workspace": workspace,
125
+ "fields": fields, "views": views, "lists": lists,
126
+ # R9: the Cohorts column's cells, built from THIS topic's lists. Same read-only
127
+ # `derived` channel the customer assembly uses β€” the measure half stays empty.
128
+ "derived": aios_grid.cohort_cells(lists),
129
  "measures": [], "measure_sets": {}, "today": time.strftime("%Y-%m-%d"),
130
  "team_id": team_id}
131
 
 
143
  import aios_grid
144
 
145
  g = product_assembly(session)
146
+ rows = _seed_image(aios_grid.rows_from_pool(
147
+ g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"]),
148
+ g["fields"])
149
  return {"fields": g["fields"], "rows": rows,
150
  "today": g["today"], "pulled_at": time.strftime("%Y-%m-%d %H:%M"),
151
  "identity": {"pid": "pid", "businessKey": "code"},
 
198
  return out
199
 
200
 
201
+ #: ⭐ WAVE 19 R7 β€” the RI Product table's built-in picture column. `source: 'overlay'` (editable,
202
+ #: so a user can upload a different shot for one SKU) with its DEFAULT supplied per render from
203
+ #: the row's `code` β€” see `_seed_image`. A stamped overlay value would have been the other way to
204
+ #: do it and it is the wrong one twice over: it is a 1,142-row migration that has to be right
205
+ #: once, and it FREEZES the code into the cell, so a re-coded SKU would keep pointing at the old
206
+ #: master with nothing saying why.
207
+ PRODUCT_IMAGE_KEY = "image"
208
+
209
+
210
+ def _seed_image(rows, fields):
211
+ """R7's "auto-seeded from SKU `code`", as a per-render DEFAULT rather than stored data.
212
+
213
+ Royal's 1,142 masters are named for `default_code`, so an untouched product row already names
214
+ its own picture; this is what makes them appear with nothing uploaded. A user's own value is
215
+ NON-EMPTY and therefore wins β€” the fallback only fills a cell nobody has set.
216
+
217
+ ⚠ Clearing the cell restores the SKU's own picture rather than blanking it, and that is the
218
+ documented meaning of empty on this column ("no override"). A product with no master on file
219
+ still shows an empty frame, because the reference resolves to a 404 β€” the honest outcome, and
220
+ the record modal names the failing reference in words.
221
+
222
+ β›” GATED ON THE SERVED FIELD LIST, and that is C-PERM, not tidiness. `product_assembly` strips
223
+ a hidden field from BOTH wires β€” the field list and the row payload β€” because narrowing only
224
+ the first leaves the value sitting in the second where anything can read it. An unconditional
225
+ seed would put the key straight back onto every row AFTER that strip, re-creating exactly the
226
+ shape the rule forbids. (The value here is the visible `code`, so nothing new escapes today;
227
+ the contract is the point, and a future non-code default would escape.)
228
+
229
+ ⚠ STATED CONSEQUENCE: hiding `code` blanks this column, because the reference IS the code.
230
+ That coupling is inherent to seeding from a business key, not a bug β€” and it fails in the safe
231
+ direction (an empty frame, never another row's picture).
232
+ """
233
+ if not any(f.get("key") == PRODUCT_IMAGE_KEY for f in fields or ()):
234
+ return rows
235
+ for row in rows:
236
+ if not row.get(PRODUCT_IMAGE_KEY):
237
+ row[PRODUCT_IMAGE_KEY] = row.get("code") or ""
238
+ return rows
239
+
240
+
241
  def pd_fields(consolidated=True):
242
  """The product field contract, minus the CONSOLIDATED-only columns when the caller is scoped.
243
 
 
254
  doc = json.loads((Path(aios_grid.__file__).resolve().parent /
255
  "aios_grid_fields.json").read_text(encoding="utf-8"))
256
  fields = list((doc.get("product_data") or {}).get("fields") or [])
257
+ # R7: the Image column is BUILT IN on this table, injected here rather than added to
258
+ # `aios_grid_fields.json`. That file is the ODOO-SOURCED contract β€” every key in it is a
259
+ # column `modules.product_data.pool()` reads off a SKU β€” and this one is neither read from
260
+ # Odoo nor written to it. Injected after the JSON so the canonical file stays the answer to
261
+ # "what does Odoo give us", which is the question `verify_fields_contract` referees.
262
+ fields = fields + [{
263
+ "key": PRODUCT_IMAGE_KEY, "label": "Image", "type": "image", "source": "overlay",
264
+ "note": "The product's picture. Empty shows the SKU's own master image; upload one "
265
+ "from the record panel to override it.",
266
+ }]
267
  if consolidated:
268
  return fields
269
  import modules.product_data as pd
api/routes_records.py CHANGED
@@ -1,16 +1,81 @@
1
- """Customer record detail routes: durable comments, scoped to the caller's book."""
2
- from fastapi import APIRouter, Body, Depends
3
-
4
- from deps import Session, err, module_gate
5
- from routes_customers import MODULE, allowed_pids
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
6
 
7
  router = APIRouter(prefix="/api/v1")
8
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9
 
10
- def _in_book(pid, session):
11
- if pid not in allowed_pids(session):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
12
  # 403, not 404: the record may exist, but this session may not inspect it.
13
- raise err(403, "out_of_scope", "that customer is not in your book")
14
 
15
 
16
  def _unavailable():
@@ -22,12 +87,14 @@ def _unavailable():
22
 
23
 
24
  @router.get("/customers/{pid}/comments")
25
- def comments(pid: int, session: Session = Depends(module_gate(MODULE))):
 
26
  from core import record_comments
27
 
28
- _in_book(pid, session)
 
29
  try:
30
- rows = record_comments.list_comments(session.runtime, pid)
31
  except record_comments.CommentsUnavailable:
32
  raise _unavailable()
33
  return {"comments": rows}
@@ -37,11 +104,13 @@ def comments(pid: int, session: Session = Depends(module_gate(MODULE))):
37
  def create_comment(
38
  pid: int,
39
  body: dict = Body(default=None),
40
- session: Session = Depends(module_gate(MODULE)),
 
41
  ):
42
  from core import record_comments
43
 
44
- _in_book(pid, session)
 
45
  try:
46
  comment = record_comments.add_comment(
47
  session.runtime,
@@ -49,6 +118,7 @@ def create_comment(
49
  (body or {}).get("body"),
50
  session.uname,
51
  session.user.get("name") or session.uname,
 
52
  )
53
  except ValueError as exc:
54
  raise err(400, "bad_comment", str(exc))
@@ -61,11 +131,13 @@ def create_comment(
61
  def remove_comment(
62
  pid: int,
63
  comment_id: str,
64
- session: Session = Depends(module_gate(MODULE)),
 
65
  ):
66
  from core import record_comments
67
 
68
- _in_book(pid, session)
 
69
  try:
70
  deleted = record_comments.delete_comment(
71
  session.runtime,
@@ -73,6 +145,7 @@ def remove_comment(
73
  comment_id,
74
  session.uname,
75
  admin=session.admin,
 
76
  )
77
  except record_comments.CommentForbidden:
78
  raise err(403, "comment_forbidden", "only the author may delete this comment")
@@ -81,4 +154,3 @@ def remove_comment(
81
  if not deleted:
82
  raise err(404, "comment_not_found", "that comment no longer exists")
83
  return {"ok": True, "id": comment_id}
84
-
 
1
+ """Record detail routes: durable comments, scoped to the caller's book β€” ON EVERY DATABASE.
2
+
3
+ ⭐ WAVE 19 (owner item 12). This file used to be the CUSTOMER record's comment routes with a
4
+ customer-shaped wall bolted to the module import line: `_in_book` asked
5
+ `routes_customers.allowed_pids` whatever surface the browser was on. Opening a PRODUCT record and
6
+ typing a comment therefore asked the customer book about a CRC32 hash of a SKU code, and the
7
+ panel answered "that customer is not in your book" β€” the owner's report. The dangerous half is
8
+ the one nobody sees: a hash that collides with a real partner id passes the wall, and the comment
9
+ is filed against somebody's customer where the whole team can read it.
10
+
11
+ THE SHAPE NOW: `?scope=` names the database (the same vocabulary `/workspace?scope=` and the
12
+ events route's `scopeKey` already speak), and `_pool_or_refuse` resolves BOTH halves of the wall
13
+ per scope β€” the GRANT and the ROW SET β€” by asking that topic's own route, never by re-deriving
14
+ one here:
15
+
16
+ customer / cohort `routes_customers.allowed_pids` behind the `customer_data` grant
17
+ product `routes_products.scoped_pool` behind the `product_data` grant
18
+ ut_<slug> `routes_tables.scoped_pool`, whose `_defn_or_refuse` IS the wall
19
+ (404 unknown / 403 not yours β€” a user table has no module grant)
20
+
21
+ ⚠ THE PATH KEEPS ITS `/customers/` SEGMENT. It is the shipped URL and `verify_api.py`'s E1a
22
+ section pins it; the scope now travels beside it explicitly. A nicer noun is not worth churning
23
+ another session's gate mid-wave β€” the WALL is the query parameter, not the word.
24
+
25
+ ⚠ NO DEFAULT BEYOND THE LEGACY ONE. An absent `scope` means `customer`, which is what every
26
+ shipped client sent and what keeps the old callers byte-identical; an UNRECOGNISED scope is a
27
+ 400, never a silent fallback to the customer book (`routes_grid._scope_or_400`'s rule, and for
28
+ the same reason: a typo served as `customer` answers a question nobody asked).
29
+ """
30
+ from fastapi import APIRouter, Body, Depends, Query
31
+
32
+ from deps import Session, err, require_session
33
 
34
  router = APIRouter(prefix="/api/v1")
35
 
36
+ #: The customer topic's two names β€” one book, two surfaces (the Cohort page is the customer table
37
+ #: over hand-curated sets). Mirrors `modules.cohort.LEGACY_SCOPES` / `core.record_comments`.
38
+ _CUSTOMER_SCOPES = ("", "customer", "cohort")
39
+
40
+
41
+ def _scope_or_400(raw):
42
+ scope = str(raw or "customer").strip().lower()
43
+ if scope in _CUSTOMER_SCOPES or scope == "product" or scope.startswith("ut_"):
44
+ return "customer" if scope in _CUSTOMER_SCOPES else scope
45
+ raise err(400, "bad_scope",
46
+ "scope must be customer, cohort, product or a ut_ database β€” refusing to guess")
47
+
48
+
49
+ def _pool_or_refuse(session: Session, scope: str):
50
+ """The pids this session may attach comments to ON THIS DATABASE β€” grant wall included.
51
+
52
+ Returns the frozenset. Raises the topic's own 403/404/503, so a caller who may not open the
53
+ surface never learns anything about the row they asked about.
54
+ """
55
+ if scope == "product":
56
+ from routes_products import MODULE as PRODUCT_MODULE, scoped_pool
57
 
58
+ session.require(PRODUCT_MODULE)
59
+ pids, _team, _rows, _fields = scoped_pool(session)
60
+ return pids
61
+ if scope.startswith("ut_"):
62
+ # No module grant exists for a user table β€” `_defn_or_refuse` inside `scoped_pool` IS
63
+ # the wall (creator or admin, fail-closed), and it answers 404 before 403 exactly as the
64
+ # rows routes do.
65
+ from routes_tables import scoped_pool
66
+
67
+ pids, _rows, _fields, _defn = scoped_pool(session, scope)
68
+ return pids
69
+ from routes_customers import MODULE as CUSTOMER_MODULE, allowed_pids
70
+
71
+ session.require(CUSTOMER_MODULE)
72
+ return frozenset(allowed_pids(session))
73
+
74
+
75
+ def _in_book(pid, session, scope):
76
+ if pid not in _pool_or_refuse(session, scope):
77
  # 403, not 404: the record may exist, but this session may not inspect it.
78
+ raise err(403, "out_of_scope", "that record is not in your book")
79
 
80
 
81
  def _unavailable():
 
87
 
88
 
89
  @router.get("/customers/{pid}/comments")
90
+ def comments(pid: int, scope: str = Query(default="customer"),
91
+ session: Session = Depends(require_session)):
92
  from core import record_comments
93
 
94
+ scope = _scope_or_400(scope)
95
+ _in_book(pid, session, scope)
96
  try:
97
+ rows = record_comments.list_comments(session.runtime, pid, scope=scope)
98
  except record_comments.CommentsUnavailable:
99
  raise _unavailable()
100
  return {"comments": rows}
 
104
  def create_comment(
105
  pid: int,
106
  body: dict = Body(default=None),
107
+ scope: str = Query(default="customer"),
108
+ session: Session = Depends(require_session),
109
  ):
110
  from core import record_comments
111
 
112
+ scope = _scope_or_400(scope)
113
+ _in_book(pid, session, scope)
114
  try:
115
  comment = record_comments.add_comment(
116
  session.runtime,
 
118
  (body or {}).get("body"),
119
  session.uname,
120
  session.user.get("name") or session.uname,
121
+ scope=scope,
122
  )
123
  except ValueError as exc:
124
  raise err(400, "bad_comment", str(exc))
 
131
  def remove_comment(
132
  pid: int,
133
  comment_id: str,
134
+ scope: str = Query(default="customer"),
135
+ session: Session = Depends(require_session),
136
  ):
137
  from core import record_comments
138
 
139
+ scope = _scope_or_400(scope)
140
+ _in_book(pid, session, scope)
141
  try:
142
  deleted = record_comments.delete_comment(
143
  session.runtime,
 
145
  comment_id,
146
  session.uname,
147
  admin=session.admin,
148
+ scope=scope,
149
  )
150
  except record_comments.CommentForbidden:
151
  raise err(403, "comment_forbidden", "only the author may delete this comment")
 
154
  if not deleted:
155
  raise err(404, "comment_not_found", "that comment no longer exists")
156
  return {"ok": True, "id": comment_id}
 
api/routes_tables.py CHANGED
@@ -49,16 +49,14 @@ def _defn_or_refuse(session, table_key):
49
  return defn
50
 
51
 
52
- def ut_assembly(session: Session, table_key: str, storage_key: str = "",
53
- consume_corrections: bool = True):
54
- """The user-table mirror of `grid_assembly` / `product_assembly` β€” SAME g-dict keys, so
55
- `/workspace` and the events route consume any of the three interchangeably.
56
-
57
- Honest absences: `measures`/`measure_sets`/`lists`/`derived` are EMPTY β€” measures are
58
- customer-grain and cohorts store partner pids; neither means anything over user rows."""
59
- import aios_grid
60
- from core import grid_events
61
-
62
  defn = _defn_or_refuse(session, table_key)
63
  fields_base = [dict(f) for f in (defn.get("fields") or [])]
64
  field_keys = {f["key"] for f in fields_base}
@@ -70,7 +68,25 @@ def ut_assembly(session: Session, table_key: str, storage_key: str = "",
70
  r["pid"] = int(rid)
71
  rows_src.append(r)
72
  rows_src.sort(key=lambda r: r["pid"])
73
- pids = frozenset(r["pid"] for r in rows_src)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
74
 
75
  ops = _ops(session, table_key)
76
  ctx = grid_events.EventCtx(
@@ -79,12 +95,14 @@ def ut_assembly(session: Session, table_key: str, storage_key: str = "",
79
  scope_key=table_key, table=ops)
80
  ws = grid_events.table_workspace(ctx, allowed_pids=pids,
81
  consume_corrections=consume_corrections)
82
- workspace, fields, views, _lists = aios_grid.workspace_wire(
83
  ws, session.uname, set(pids), defs={}, scope_key=table_key,
84
- storage_key=storage_key, fields_base=fields_base, with_cohorts=False)
85
 
86
  return {"rows_src": rows_src, "pids": pids, "ws": ws, "workspace": workspace,
87
- "fields": fields, "views": views, "lists": [], "derived": {},
 
 
88
  "measures": [], "measure_sets": {}, "today": time.strftime("%Y-%m-%d"),
89
  "defn": defn}
90
 
 
49
  return defn
50
 
51
 
52
+ def scoped_pool(session: Session, table_key: str):
53
+ """`(pids, rows_src, fields_base, defn)` β€” THE USER-TABLE WALL, on its own.
54
+
55
+ `routes_products.scoped_pool`'s sibling, extracted for the same reason (wave 19, item 12): a
56
+ caller that only needs "which rows of this database may this session touch" β€” record comments
57
+ β€” must ask through `_defn_or_refuse` (404/403, the whole wall) rather than growing a second
58
+ idea of what a user table's pool is.
59
+ """
 
 
60
  defn = _defn_or_refuse(session, table_key)
61
  fields_base = [dict(f) for f in (defn.get("fields") or [])]
62
  field_keys = {f["key"] for f in fields_base}
 
68
  r["pid"] = int(rid)
69
  rows_src.append(r)
70
  rows_src.sort(key=lambda r: r["pid"])
71
+ return frozenset(r["pid"] for r in rows_src), rows_src, fields_base, defn
72
+
73
+
74
+ def ut_assembly(session: Session, table_key: str, storage_key: str = "",
75
+ consume_corrections: bool = True):
76
+ """The user-table mirror of `grid_assembly` / `product_assembly` β€” SAME g-dict keys, so
77
+ `/workspace` and the events route consume any of the three interchangeably.
78
+
79
+ Honest absence: `measures`/`measure_sets` are EMPTY β€” `core.measure_resolve` is
80
+ customer-grain, so there is nothing to offer over user rows.
81
+
82
+ ⭐ WAVE 19 / R9 β€” `lists` IS NO LONGER EMPTY. "For ANY database new/old": a user table gets
83
+ cohorts like every other database, out of its OWN bucket (`ut_<slug>_cohorts`), holding its
84
+ own row ids. The wave-18 refusal was correct while there was one customer-keyed bucket and
85
+ wrong the moment the store learned about topics."""
86
+ import aios_grid
87
+ from core import grid_events
88
+
89
+ pids, rows_src, fields_base, defn = scoped_pool(session, table_key)
90
 
91
  ops = _ops(session, table_key)
92
  ctx = grid_events.EventCtx(
 
95
  scope_key=table_key, table=ops)
96
  ws = grid_events.table_workspace(ctx, allowed_pids=pids,
97
  consume_corrections=consume_corrections)
98
+ workspace, fields, views, lists = aios_grid.workspace_wire(
99
  ws, session.uname, set(pids), defs={}, scope_key=table_key,
100
+ storage_key=storage_key, fields_base=fields_base)
101
 
102
  return {"rows_src": rows_src, "pids": pids, "ws": ws, "workspace": workspace,
103
+ "fields": fields, "views": views, "lists": lists,
104
+ # R9: the Cohorts column's cells from this table's own lists.
105
+ "derived": aios_grid.cohort_cells(lists),
106
  "measures": [], "measure_sets": {}, "today": time.strftime("%Y-%m-%d"),
107
  "defn": defn}
108
 
platform/aios_grid.py CHANGED
@@ -101,9 +101,17 @@ def _round(v):
101
  #: `phone` / `email` / `url` (text-family with per-type rendering) Β· `rating` (top-level
102
  #: `max`, SVG stars client-side β€” never emoji) Β· `created_time` (READ-ONLY, renders the row's
103
  #: `_created`) Β· `formula` (READ-ONLY, client-computed from the row's other cells).
 
 
 
 
 
 
 
 
104
  CUSTOM_FIELD_TYPES = {"text", "select", "multiselect", "user", "int", "currency", "pct", "date",
105
  "checkbox", "phone", "email", "url", "rating", "created_time", "formula",
106
- "automation"}
107
  #: User-created types whose CELLS are read-only: their values are computed (formula β€” client
108
  #: side, any error degrades to BLANK) or system-owned (created_time = the row's `_created`).
109
  #: Emitted with the cohort column's read-only mechanism β€” `source: 'odoo'` + `derived` β€” so
@@ -615,7 +623,13 @@ def fields_from_workspace(workspace=None, cohorts=False, scope_key=None, fields_
615
  if ftype == "automation" and _clean_automation(field.get("automation")) else {}),
616
  **_field_extras(field, ftype),
617
  })
618
- if cohorts:
 
 
 
 
 
 
619
  out.append(cohort_field())
620
  return out
621
 
@@ -1647,15 +1661,21 @@ def workspace_wire(ws, uname, pool_pids, defs=None, scope_key='customer', storag
1647
  `cohortMode`/`scopeChoice` (the API stamps its own from `?scope=`).
1648
 
1649
  Wave 16 C-TOPIC: `fields_base` selects the canonical contract (absent = customer,
1650
- byte-identical); `with_cohorts=False` is the PRODUCT surface β€” cohorts are customer
1651
- machinery (`modules/cohort` stores partner pids), and resolving them against product pids
1652
- would intersect two unrelated id spaces and render a plausible, meaningless member count.
 
 
 
 
 
 
1653
  """
1654
  import modules.cohort as cohort_mod
1655
 
1656
  cohort_lists = []
1657
  if with_cohorts:
1658
- for cid, c in sorted(cohort_mod.visible(uname, pool_pids).items(),
1659
  key=lambda kv: (kv[1].get('name') or '').lower()):
1660
  members = [p for p in (c.get('members') or []) if p in pool_pids]
1661
  entry = {'id': cid, 'name': c.get('name') or cid, 'pids': members}
 
101
  #: `phone` / `email` / `url` (text-family with per-type rendering) Β· `rating` (top-level
102
  #: `max`, SVG stars client-side β€” never emoji) Β· `created_time` (READ-ONLY, renders the row's
103
  #: `_created`) Β· `formula` (READ-ONLY, client-computed from the row's other cells).
104
+ #: ⭐ Wave-19 R7 / contract C5: `image` β€” a PICTURE on a record. The cell holds a string
105
+ #: REFERENCE, never bytes: a product `code`, an `ed:<slug>` editorial asset, or `rec:<id>` for
106
+ #: something uploaded through the field (`POST /api/v1/assets/records`). Storing a reference is
107
+ #: what lets Royal's 1,142 existing SKU masters appear with nothing re-uploaded, and it keeps the
108
+ #: overlay stratum the size it is β€” base64 bytes in a JSON blob read on every render would be a
109
+ #: megabyte-per-row tax on the whole store. Editable by NATURE (deliberately NOT in
110
+ #: `READONLY_CUSTOM_TYPES`): the ref is what the upload endpoint hands back, and the client PATCHes
111
+ #: it through the ordinary overlay wall rather than the asset route writing cells behind it.
112
  CUSTOM_FIELD_TYPES = {"text", "select", "multiselect", "user", "int", "currency", "pct", "date",
113
  "checkbox", "phone", "email", "url", "rating", "created_time", "formula",
114
+ "automation", "image"}
115
  #: User-created types whose CELLS are read-only: their values are computed (formula β€” client
116
  #: side, any error degrades to BLANK) or system-owned (created_time = the row's `_created`).
117
  #: Emitted with the cohort column's read-only mechanism β€” `source: 'odoo'` + `derived` β€” so
 
623
  if ftype == "automation" and _clean_automation(field.get("automation")) else {}),
624
  **_field_extras(field, ftype),
625
  })
626
+ if cohorts and not any(f.get('key') == COHORT_COLUMN for f in out):
627
+ # ⚠ The emptiness check is WAVE 19's, and it is about the topics R9 opened this column to.
628
+ # A user table's field keys are slugged from whatever its creator typed, so a column
629
+ # literally called "Cohorts" produces the key `cohorts` β€” and appending here unguarded
630
+ # would put TWO fields with one key on the wire. The client indexes fields by key, so the
631
+ # duplicate does not error: it silently paints one column's values under the other's
632
+ # header. The user's own column wins; the derived one steps aside rather than shadowing it.
633
  out.append(cohort_field())
634
  return out
635
 
 
1661
  `cohortMode`/`scopeChoice` (the API stamps its own from `?scope=`).
1662
 
1663
  Wave 16 C-TOPIC: `fields_base` selects the canonical contract (absent = customer,
1664
+ byte-identical).
1665
+
1666
+ ⭐ WAVE 19 / R9 β€” `with_cohorts` NO LONGER MEANS "customer only". Wave 16 set it False on the
1667
+ product surface because cohorts were a single customer-keyed bucket, so resolving them against
1668
+ product pids would have intersected two unrelated id spaces and printed a plausible,
1669
+ meaningless member count. `modules.cohort` is scope-parameterized now: the lists come from
1670
+ THIS topic's bucket (`cohort_mod.scoped(scope_key)`), so their ids are this topic's ids and
1671
+ the intersection with `pool_pids` is the ordinary one. The flag survives as an honest OFF
1672
+ switch for a surface that wants no membership channel at all β€” it is not a topic wall.
1673
  """
1674
  import modules.cohort as cohort_mod
1675
 
1676
  cohort_lists = []
1677
  if with_cohorts:
1678
+ for cid, c in sorted(cohort_mod.scoped(scope_key).visible(uname, pool_pids).items(),
1679
  key=lambda kv: (kv[1].get('name') or '').lower()):
1680
  members = [p for p in (c.get('members') or []) if p in pool_pids]
1681
  entry = {'id': cid, 'name': c.get('name') or cid, 'pids': members}
platform/core/assets.py CHANGED
@@ -27,7 +27,11 @@ _MANIFEST_TTL = 300
27
  #: (fetched_at, {"CODE": {...}}, {"slug": {...}}) β€” one manifest read per process per TTL.
28
  #: DEBT-5 (2026-08-04): the same manifest.json now carries a second, NON-SKU half under
29
  #: "editorial" β€” full-bleed lifestyle imagery for catalog gallery pages, keyed by slug.
30
- _MANIFEST = {'at': 0.0, 'codes': None, 'editorial': None}
 
 
 
 
31
 
32
 
33
  def repo_id():
@@ -50,9 +54,10 @@ def _load():
50
  man = json.loads(Path(p).read_text(encoding='utf-8')) or {}
51
  codes = man.get('codes') or {}
52
  editorial_ = man.get('editorial') or {}
 
53
  except Exception:
54
- codes, editorial_ = {}, {}
55
- _MANIFEST.update(at=now, codes=codes, editorial=editorial_)
56
 
57
 
58
  def manifest():
@@ -128,6 +133,86 @@ def put_editorial(slug, orig_bytes, ext, web_png):
128
  return True
129
 
130
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
131
  def reset_cache():
132
  """Drop the memoized manifest β€” for gates and for a post-ingest refresh."""
133
- _MANIFEST.update(at=0.0, codes=None, editorial=None)
 
27
  #: (fetched_at, {"CODE": {...}}, {"slug": {...}}) β€” one manifest read per process per TTL.
28
  #: DEBT-5 (2026-08-04): the same manifest.json now carries a second, NON-SKU half under
29
  #: "editorial" β€” full-bleed lifestyle imagery for catalog gallery pages, keyed by slug.
30
+ #: ⭐ WAVE 19 R7 / C5: and a THIRD, under "records" β€” pictures uploaded through an `image` FIELD,
31
+ #: namespaced BY TENANT (`<tenant>/<id>`). The other two namespaces are Royal's catalogue assets
32
+ #: and are tenant-#0 material by nature; this one is written by any signed-in user of any tenant,
33
+ #: so the tenant is part of the address and comes from the SESSION on both write and read.
34
+ _MANIFEST = {'at': 0.0, 'codes': None, 'editorial': None, 'records': None}
35
 
36
 
37
  def repo_id():
 
54
  man = json.loads(Path(p).read_text(encoding='utf-8')) or {}
55
  codes = man.get('codes') or {}
56
  editorial_ = man.get('editorial') or {}
57
+ records_ = man.get('records') or {}
58
  except Exception:
59
+ codes, editorial_, records_ = {}, {}, {}
60
+ _MANIFEST.update(at=now, codes=codes, editorial=editorial_, records=records_)
61
 
62
 
63
  def manifest():
 
133
  return True
134
 
135
 
136
+ # ───────────────────────────────────────── record images (wave 19, R7 / contract C5)
137
+ #
138
+ # A picture attached to ONE ROW through an `image` field, by any signed-in user. Two things make
139
+ # this namespace different from the two above, and both are about who may write it:
140
+ #
141
+ # * it is TENANT-ADDRESSED (`<tenant>/<id>`), because a nurilab user uploading a photo must not
142
+ # land anywhere a royal-imports read can reach. The tenant comes from the SESSION at both
143
+ # ends β€” never from the reference string, which is why a `rec:` ref copied between tenants
144
+ # resolves to a 404 rather than to somebody else's photograph.
145
+ # * the id is SERVER-MINTED hex, so the client never names a path component.
146
+
147
+
148
+ def records():
149
+ """{'<tenant>/<id>': {'ext': ...}} β€” the record-image half of the manifest; {} if unreachable."""
150
+ _load()
151
+ return _MANIFEST['records'] or {}
152
+
153
+
154
+ def record_ref(tenant, asset_id):
155
+ """The manifest key for one tenant's asset. ONE composition point, so read and write cannot
156
+ disagree about where a picture lives."""
157
+ return f"{str(tenant or '').strip().lower()}/{str(asset_id or '').strip().lower()}"
158
+
159
+
160
+ def fetch_record(tenant, asset_id, quality='web'):
161
+ """A local Path to one RECORD image, or None β€” same shape as fetch()/fetch_editorial().
162
+
163
+ β›” Returns None for an id this tenant does not own, and that is the cross-tenant wall: the
164
+ lookup key is composed from the caller's own tenant, so an id belonging to another tenant is
165
+ simply absent from the manifest under this address. Indistinguishable from "no such picture",
166
+ which is exactly what the caller is entitled to know.
167
+ """
168
+ ref = record_ref(tenant, asset_id)
169
+ meta = records().get(ref)
170
+ if not meta:
171
+ return None
172
+ rel = (f'assets/records/{ref}/web.png' if quality == 'web'
173
+ else f"assets/records/{ref}/orig{meta.get('ext', '.png')}")
174
+ try:
175
+ from huggingface_hub import hf_hub_download
176
+ return Path(hf_hub_download(repo_id(), rel, repo_type='dataset', token=_token()))
177
+ except Exception:
178
+ return None
179
+
180
+
181
+ def put_record(tenant, asset_id, orig_bytes, ext, web_png):
182
+ """Store one record image: original, web derivative and the updated manifest in ONE commit
183
+ (a partial upload can never leave a listed-but-unfetchable reference). Raises on failure β€”
184
+ the route turns that into an honest 503, never a silent success.
185
+
186
+ ⚠ Shares `put_editorial`'s read-modify-write caveat on manifest.json: two uploads landing in
187
+ the same second could drop one entry. Uploads through a field are rarer than a scroll but far
188
+ from admin-rare, so this is the first namespace where that will actually bite β€” booked in the
189
+ wave doc rather than quietly inherited.
190
+ """
191
+ import json
192
+
193
+ from huggingface_hub import CommitOperationAdd, HfApi, hf_hub_download
194
+ ref = record_ref(tenant, asset_id)
195
+ api = HfApi(token=_token())
196
+ try:
197
+ p = hf_hub_download(repo_id(), 'manifest.json', repo_type='dataset', token=_token(),
198
+ force_download=True)
199
+ man = json.loads(Path(p).read_text(encoding='utf-8')) or {}
200
+ except Exception:
201
+ man = {}
202
+ man.setdefault('records', {})[ref] = {'ext': ext}
203
+ api.create_commit(
204
+ repo_id(), repo_type='dataset',
205
+ operations=[
206
+ CommitOperationAdd(f'assets/records/{ref}/orig{ext}', orig_bytes),
207
+ CommitOperationAdd(f'assets/records/{ref}/web.png', web_png),
208
+ CommitOperationAdd('manifest.json',
209
+ json.dumps(man, indent=1, sort_keys=True).encode('utf-8')),
210
+ ],
211
+ commit_message=f'record image: {ref}')
212
+ reset_cache()
213
+ return True
214
+
215
+
216
  def reset_cache():
217
  """Drop the memoized manifest β€” for gates and for a post-ingest refresh."""
218
+ _MANIFEST.update(at=0.0, codes=None, editorial=None, records=None)
platform/core/grid_events.py CHANGED
@@ -145,6 +145,35 @@ def _tops(ctx):
145
  return ctx.table if ctx.table is not None else cl_mod.TABLE_OPS
146
 
147
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
148
  # ------------------------------------------------------------------ the workspace family (X1 amd.)
149
  def table_workspace(ctx, allowed_pids=None, consume_corrections=True):
150
  """Durable Airtable-style view/schema/overlay state, with an honest session fallback.
@@ -636,10 +665,11 @@ def handle_one(event, ctx):
636
  # the SET it is, in the store that owns it; the view record must not grow a second title
637
  # that the read side would then have to arbitrate. Routed rather than duplicated.
638
  if _is_locked_view and store.available():
639
- _cur = (cohort_mod.all_for(uname).get(view_id) or {}).get('name')
 
640
  if name and name != _cur:
641
  try:
642
- cohort_mod.rename(uname, view_id, name)
643
  except ValueError as _e:
644
  _tel.error('cohort:rename-via-view', _e)
645
  view = {'id': view_id, 'name': name,
@@ -711,8 +741,8 @@ def handle_one(event, ctx):
711
  # on the very next render: the row would come back, minus the user's sort and columns,
712
  # which reads as a corruption rather than as a refusal. Own sets only (`all_for`), the
713
  # same wall `cohort_delete` rides.
714
- if store.available() and view_id in cohort_mod.all_for(uname):
715
- cohort_mod.delete(uname, view_id)
716
  _tops(ctx).delete_view(uname, view_id)
717
  # True, unlike an ordinary view_delete: the lists payload IS server truth and the
718
  # client cannot know the membership channel changed.
@@ -905,17 +935,18 @@ def handle_one(event, ctx):
905
  # caller's permitted pool β€” the same guard add_to_list rides.
906
  if not store.available():
907
  return False
 
908
  cohort_id = str(event.get('cohortId') or '').strip()[:120]
909
- if not cohort_id or cohort_id not in cohort_mod.all_for(uname):
910
  return False
911
  try:
912
  if kind == 'cohort_rename':
913
  name = str(event.get('name') or '').strip()[:120]
914
  if not name:
915
  return False
916
- cohort_mod.rename(uname, cohort_id, name)
917
  elif kind == 'cohort_delete':
918
- cohort_mod.delete(uname, cohort_id)
919
  else:
920
  raw_pids = event.get('pids')
921
  if not isinstance(raw_pids, list):
@@ -924,9 +955,9 @@ def handle_one(event, ctx):
924
  if not pids:
925
  return False
926
  if kind == 'cohort_add':
927
- cohort_mod.add_members(uname, cohort_id, pids)
928
  else:
929
- cohort_mod.remove_members(uname, cohort_id, pids)
930
  except ValueError as e:
931
  _tel.error('cohort:panel-edit', e)
932
  return False
@@ -935,21 +966,31 @@ def handle_one(event, ctx):
935
  return True
936
 
937
  if kind in ('doc_add', 'doc_delete', 'doc_fetch'):
938
- # DOCUMENTS on a customer row (owner item 12, contract C5). Metadata in the store key
939
  # `customer_docs`; the BYTES live at their own path in the tenant dataset, never in a
940
  # JSON blob β€” see core.store.upload_bytes for why that distinction is load-bearing.
 
 
 
 
 
 
 
 
941
  import base64 as _b64c
942
  import re as _re_mod
943
  if not store.available():
944
  return False
 
 
945
  pid = event.get('pid')
946
  doc_id = str(event.get('docId') or '').strip()[:80]
947
  # The pid wall is the SAME one every other row-scoped event rides: a caller may only
948
- # touch customers inside their own permitted pool. Without it, documents would be the
949
  # one surface where a scoped agent could read another book's rows.
950
  if not isinstance(pid, int) or pid not in allowed_pids or not doc_id:
951
  return False
952
- meta_all = store.get(_DOCS_KEY) or {}
953
  row = list((meta_all.get(str(pid)) or []))
954
 
955
  if kind == 'doc_add':
@@ -969,9 +1010,9 @@ def handle_one(event, ctx):
969
  if len(row) >= _DOC_MAX_PER_ROW or any(d.get('id') == doc_id for d in row):
970
  return False
971
  safe = _re_mod.sub(r'[^A-Za-z0-9._-]', '_', name)[:80] or 'file'
972
- path = f'docs/{pid}/{doc_id}_{safe}'
973
  try:
974
- store.upload_bytes(path, blob, message=f'doc {doc_id} for customer {pid}')
975
  except Exception as _ue:
976
  _tel.error('docs:upload', _ue)
977
  return False
@@ -1008,7 +1049,13 @@ def handle_one(event, ctx):
1008
  def _write(cur):
1009
  cur[str(pid)] = row
1010
  return cur
1011
- store.update(_DOCS_KEY, _write, flush='async')
 
 
 
 
 
 
1012
  return True
1013
 
1014
  if kind in ('folder_create', 'folder_rename', 'folder_delete', 'folder_duplicate',
@@ -1028,7 +1075,7 @@ def handle_one(event, ctx):
1028
  def _own_ids(sfc, cur_ws):
1029
  if sfc == 'views':
1030
  return set((cur_ws.get('views') or {}))
1031
- return set(cohort_mod.all_for(uname))
1032
 
1033
  def _mutate(cur_ws):
1034
  folders = _agf.clean_folders(cur_ws.get('folders'))
@@ -1230,22 +1277,33 @@ def handle_one(event, ctx):
1230
  name = str(event.get('name') or '').strip()[:120]
1231
  if not store.available():
1232
  return False
 
 
 
 
 
 
1233
  try:
1234
  if not cohort_id:
1235
  if not name:
1236
  return False
1237
- cohort_id = cohort_mod.create(uname, name, pids)
1238
  else:
1239
- if cohort_id not in cohort_mod.all_for(uname):
1240
  return False # not this user's cohort β€” fail closed, do not create
1241
- cohort_mod.add_members(uname, cohort_id, pids)
1242
  except ValueError as e:
1243
  _tel.error('cohort:add_to_list', e)
1244
  return False
1245
  # True: the Cohort page's list and counts must reflect this, and the toast below only
1246
  # renders on a fresh run.
 
 
 
 
 
1247
  ctx.out.toast = (
1248
- f"Added {len(pids):,} customer{'' if len(pids) == 1 else 's'} to "
1249
  f"{name or 'the list'}.")
1250
  return True
1251
 
 
145
  return ctx.table if ctx.table is not None else cl_mod.TABLE_OPS
146
 
147
 
148
+ def _cohorts(ctx):
149
+ """The COHORT store this ctx operates on β€” `_tops`'s sibling, and here for the same reason.
150
+
151
+ ⭐ WAVE 19 / R9: a cohort belongs to its database. Every cohort verb below used to name
152
+ `cohort_mod` directly, so a list built on the Product surface landed in `customer_cohorts`
153
+ beside somebody's real customer lists β€” with PRODUCT pids in it (CRC32 hashes of SKU codes),
154
+ which the customer page would then try to resolve against partner ids. Wave 16 answered that
155
+ by REFUSING cohorts on other topics (`with_cohorts=False`); R9 says scope-parameterize
156
+ instead. `modules.cohort.scoped` returns the module itself for the customer topic, so the
157
+ customer path is byte-unchanged.
158
+ """
159
+ return cohort_mod.scoped(ctx.scope_key)
160
+
161
+
162
+ def _docs_key(ctx):
163
+ """The DOCUMENTS bucket this ctx operates on β€” `_cohorts`'s sibling (wave 19, item 12's
164
+ silent third case).
165
+
166
+ β›” `_DOCS_KEY` STAYS the module constant with its shipped value: app.py re-imports it for the
167
+ Streamlit docs payload and `verify_seam.py` asserts the two resolve to the same string. This
168
+ resolves the CUSTOMER topic to exactly that constant and gives every other database its own
169
+ bucket, so the pid keys inside one bucket all come from one id space.
170
+ """
171
+ scope = str(getattr(ctx, 'scope_key', '') or 'customer').strip().lower()
172
+ if scope in cohort_mod.LEGACY_SCOPES:
173
+ return _DOCS_KEY
174
+ return f'{scope}_docs'
175
+
176
+
177
  # ------------------------------------------------------------------ the workspace family (X1 amd.)
178
  def table_workspace(ctx, allowed_pids=None, consume_corrections=True):
179
  """Durable Airtable-style view/schema/overlay state, with an honest session fallback.
 
665
  # the SET it is, in the store that owns it; the view record must not grow a second title
666
  # that the read side would then have to arbitrate. Routed rather than duplicated.
667
  if _is_locked_view and store.available():
668
+ _sets = _cohorts(ctx) # R9: the SET lives in this topic's bucket
669
+ _cur = (_sets.all_for(uname).get(view_id) or {}).get('name')
670
  if name and name != _cur:
671
  try:
672
+ _sets.rename(uname, view_id, name)
673
  except ValueError as _e:
674
  _tel.error('cohort:rename-via-view', _e)
675
  view = {'id': view_id, 'name': name,
 
741
  # on the very next render: the row would come back, minus the user's sort and columns,
742
  # which reads as a corruption rather than as a refusal. Own sets only (`all_for`), the
743
  # same wall `cohort_delete` rides.
744
+ if store.available() and view_id in _cohorts(ctx).all_for(uname):
745
+ _cohorts(ctx).delete(uname, view_id)
746
  _tops(ctx).delete_view(uname, view_id)
747
  # True, unlike an ordinary view_delete: the lists payload IS server truth and the
748
  # client cannot know the membership channel changed.
 
935
  # caller's permitted pool β€” the same guard add_to_list rides.
936
  if not store.available():
937
  return False
938
+ sets = _cohorts(ctx) # R9: this DATABASE's lists, never another's
939
  cohort_id = str(event.get('cohortId') or '').strip()[:120]
940
+ if not cohort_id or cohort_id not in sets.all_for(uname):
941
  return False
942
  try:
943
  if kind == 'cohort_rename':
944
  name = str(event.get('name') or '').strip()[:120]
945
  if not name:
946
  return False
947
+ sets.rename(uname, cohort_id, name)
948
  elif kind == 'cohort_delete':
949
+ sets.delete(uname, cohort_id)
950
  else:
951
  raw_pids = event.get('pids')
952
  if not isinstance(raw_pids, list):
 
955
  if not pids:
956
  return False
957
  if kind == 'cohort_add':
958
+ sets.add_members(uname, cohort_id, pids)
959
  else:
960
+ sets.remove_members(uname, cohort_id, pids)
961
  except ValueError as e:
962
  _tel.error('cohort:panel-edit', e)
963
  return False
 
966
  return True
967
 
968
  if kind in ('doc_add', 'doc_delete', 'doc_fetch'):
969
+ # DOCUMENTS on a row (owner item 12, contract C5). Metadata in the store key
970
  # `customer_docs`; the BYTES live at their own path in the tenant dataset, never in a
971
  # JSON blob β€” see core.store.upload_bytes for why that distinction is load-bearing.
972
+ #
973
+ # ⭐ WAVE 19 / R9 β€” item 1's SILENT THIRD CASE, and the one nobody reported because the
974
+ # React shell cannot reach it yet (`payload.docs` is set only by app.py). Both homes are
975
+ # keyed by pid and both were topic-blind: the metadata bucket AND the byte path
976
+ # `docs/<pid>/…`. Two topics' pid spaces overlap by construction (a CRC32 hash lands
977
+ # anywhere an Odoo partner id can), so a product's file could occupy the path of a
978
+ # customer's β€” one upload silently shadowing another tenant-visible document. Per-topic
979
+ # bucket AND per-topic prefix; the customer topic keeps both of its shipped names.
980
  import base64 as _b64c
981
  import re as _re_mod
982
  if not store.available():
983
  return False
984
+ docs_key = _docs_key(ctx)
985
+ docs_dir = 'docs' if docs_key == _DOCS_KEY else f'docs/{docs_key[:-5]}'
986
  pid = event.get('pid')
987
  doc_id = str(event.get('docId') or '').strip()[:80]
988
  # The pid wall is the SAME one every other row-scoped event rides: a caller may only
989
+ # touch rows inside their own permitted pool. Without it, documents would be the
990
  # one surface where a scoped agent could read another book's rows.
991
  if not isinstance(pid, int) or pid not in allowed_pids or not doc_id:
992
  return False
993
+ meta_all = store.get(docs_key) or {}
994
  row = list((meta_all.get(str(pid)) or []))
995
 
996
  if kind == 'doc_add':
 
1010
  if len(row) >= _DOC_MAX_PER_ROW or any(d.get('id') == doc_id for d in row):
1011
  return False
1012
  safe = _re_mod.sub(r'[^A-Za-z0-9._-]', '_', name)[:80] or 'file'
1013
+ path = f'{docs_dir}/{pid}/{doc_id}_{safe}'
1014
  try:
1015
+ store.upload_bytes(path, blob, message=f'doc {doc_id} for {scope_key} {pid}')
1016
  except Exception as _ue:
1017
  _tel.error('docs:upload', _ue)
1018
  return False
 
1049
  def _write(cur):
1050
  cur[str(pid)] = row
1051
  return cur
1052
+ # ⚠ `docs_key`, NOT `_DOCS_KEY`. The read above and the byte path were both made
1053
+ # per-topic and this line was not β€” so a product document's BYTES landed correctly under
1054
+ # `docs/product/…` while its METADATA went into `customer_docs` beside the customer rows,
1055
+ # keyed by a CRC32 hash. Found by `verify_scopes.py`'s own leg on its first run, which is
1056
+ # the argument for asserting the ABSENCE from the legacy bucket and not just the presence
1057
+ # in the new one: every "it saved" check here was green.
1058
+ store.update(docs_key, _write, flush='async')
1059
  return True
1060
 
1061
  if kind in ('folder_create', 'folder_rename', 'folder_delete', 'folder_duplicate',
 
1075
  def _own_ids(sfc, cur_ws):
1076
  if sfc == 'views':
1077
  return set((cur_ws.get('views') or {}))
1078
+ return set(_cohorts(ctx).all_for(uname))
1079
 
1080
  def _mutate(cur_ws):
1081
  folders = _agf.clean_folders(cur_ws.get('folders'))
 
1277
  name = str(event.get('name') or '').strip()[:120]
1278
  if not store.available():
1279
  return False
1280
+ # ⭐ WAVE 19 / R9 β€” THE BUG THIS RULING NAMES. This branch is where a list is BORN, and it
1281
+ # named `cohort_mod` directly: a list created from the Product surface was written into
1282
+ # `customer_cohorts` with CRC32 product pids in it, then rendered on the Customer page as
1283
+ # a list of customers nobody recognised. The set now belongs to the database it was
1284
+ # created on, and `ctx.scope_key` is the only thing that decides which.
1285
+ sets = _cohorts(ctx)
1286
  try:
1287
  if not cohort_id:
1288
  if not name:
1289
  return False
1290
+ cohort_id = sets.create(uname, name, pids)
1291
  else:
1292
+ if cohort_id not in sets.all_for(uname):
1293
  return False # not this user's cohort β€” fail closed, do not create
1294
+ sets.add_members(uname, cohort_id, pids)
1295
  except ValueError as e:
1296
  _tel.error('cohort:add_to_list', e)
1297
  return False
1298
  # True: the Cohort page's list and counts must reflect this, and the toast below only
1299
  # renders on a fresh run.
1300
+ #
1301
+ # ⚠ The NOUN is the TOPIC's, not the literal "customer" this line carried since wave 2.
1302
+ # "Added 12 customers" over a set of SKUs is the surface stating, in words, that the list
1303
+ # went somewhere it did not β€” the user-visible half of the same leak.
1304
+ _noun = sets.noun
1305
  ctx.out.toast = (
1306
+ f"Added {len(pids):,} {_noun}{'' if len(pids) == 1 else 's'} to "
1307
  f"{name or 'the list'}.")
1308
  return True
1309
 
platform/core/platform_admin.py ADDED
@@ -0,0 +1,58 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """core/platform_admin.py β€” THE PLATFORM-OPERATOR PREDICATE (wave 19, owner item 13 / ruling R3).
2
+
3
+ There are now TWO kinds of administrator in this product and they must never be confused:
4
+
5
+ * a **tenant admin** (`role: 'admin'`) runs ONE company's workspace β€” its accounts, its
6
+ keychains, its databases. Nurilab's admin is one; Royal's is one. `core.perms.is_admin`
7
+ is that wall and it is scoped to the caller's own tenant everywhere it is used.
8
+ * a **platform admin** operates LOOPABLE ITSELF β€” the cross-tenant view of who our customers
9
+ are, what they are running, and what it costs. That is a different question and it needs a
10
+ different key, because every tenant already has an admin and none of them may see the others.
11
+
12
+ β›” THE DOUBLE LOCK, and why it is two conditions and not one (R3, verbatim: "NEW fail-closed
13
+ `platform_admin` server predicate (tenant-scoped `is_admin` does NOT qualify)"):
14
+
15
+ record flag `platform_admin is True` AND `tenant == 'loopable'`
16
+
17
+ Either half alone is a promotion path we do not want to exist. The flag alone would mean a
18
+ tenant admin who can write user records (Y4's `POST /admin/users` is reachable by every tenant
19
+ admin) could mint themselves a cross-tenant reader inside their OWN company. The tenant alone
20
+ would mean every future account in the `loopable` workspace β€” a designer, a contractor β€” reads
21
+ every customer's operational data by virtue of their email domain. Requiring both means the
22
+ promotion needs a write to a record AND membership of a tenant that no customer's admin can
23
+ create accounts in.
24
+
25
+ FAIL-CLOSED IN THE STRICT SENSE: `is True`, not truthiness. A record carrying the string
26
+ "false", a 0, a "yes", or a partially-read dict is NOT a platform admin. The flag is absent on
27
+ every pre-wave record, which is the correct answer for all of them.
28
+
29
+ ⚠ THE FLAG MUST RIDE `users._public()` OR THIS PREDICATE IS BLIND. `deps._user_for` builds every
30
+ API session from that projection, so a field that lives only on the stored record is invisible
31
+ to every route that asks this question β€” the same rule `core.users` states for `perms`/`perms_v`
32
+ ("the wall travels on this projection or it does not travel"), recurring on a new field. Both
33
+ sides land in the same change, and `verify_api.py`'s W19-ADMIN section drives the predicate
34
+ through a real SESSION rather than through a hand-built dict, so a dropped projection is red.
35
+
36
+ This module deliberately holds NO routes, NO store reads and NO imports of the permission layer:
37
+ it is one question, answerable from the session's own user dict, callable from either host.
38
+ """
39
+
40
+ #: The ONE tenant slug a platform administrator may belong to. A constant rather than an env var
41
+ #: on purpose β€” "which company operates this platform" is not a per-deployment setting, and an
42
+ #: env-var reader here would be one misconfigured container away from admitting another slug.
43
+ PLATFORM_TENANT = 'loopable'
44
+
45
+
46
+ def is_platform_admin(user):
47
+ """True iff `user` is a Loopable platform operator. Fail-closed on anything else.
48
+
49
+ `user` is the PUBLIC session projection (`core.users._public`) or a raw record β€” both carry
50
+ the same two keys, so the predicate answers identically wherever it is asked. None, {}, a
51
+ non-dict, a missing flag or a mismatched tenant are all False, and none of them are an error:
52
+ "not a platform admin" is the answer for almost every session the product will ever serve.
53
+ """
54
+ if not isinstance(user, dict):
55
+ return False
56
+ if user.get('platform_admin') is not True:
57
+ return False
58
+ return str(user.get('tenant') or 'royal-imports').strip().lower() == PLATFORM_TENANT
platform/core/record_comments.py CHANGED
@@ -1,9 +1,24 @@
1
- """Durable comments attached to customer records.
2
 
3
  The service is deliberately unaware of HTTP and of the concrete store backend.
4
  It receives a tenant-bound ``TenantRuntime`` handle, so the same logical key can
5
  never cross a tenant boundary. Odoo remains read-only: comments live only in
6
  AIOS's writable tenant store.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7
  """
8
  from __future__ import annotations
9
 
@@ -14,6 +29,17 @@ STORE_KEY = "customer_record_comments"
14
  MAX_BODY = 4000
15
  MAX_PER_RECORD = 500
16
 
 
 
 
 
 
 
 
 
 
 
 
17
 
18
  class CommentsUnavailable(RuntimeError):
19
  """The tenant store cannot currently provide durable comments."""
@@ -50,19 +76,19 @@ def _clean_comment(raw):
50
  }
51
 
52
 
53
- def _read(runtime):
54
  if not runtime.available():
55
  raise CommentsUnavailable("the tenant store is unavailable")
56
  try:
57
- data = runtime.get(STORE_KEY)
58
  except Exception as exc:
59
  raise CommentsUnavailable("comments could not be read") from exc
60
  return data if isinstance(data, dict) else {}
61
 
62
 
63
- def list_comments(runtime, pid):
64
  """Return one record's comments oldest-first, dropping malformed legacy entries."""
65
- rows = _read(runtime).get(_record_key(pid), [])
66
  if not isinstance(rows, list):
67
  return []
68
  cleaned = [comment for raw in rows if (comment := _clean_comment(raw)) is not None]
@@ -70,7 +96,8 @@ def list_comments(runtime, pid):
70
  return cleaned
71
 
72
 
73
- def add_comment(runtime, pid, body, author_key, author_name="", now=None, comment_id=None):
 
74
  """Append one server-authored comment atomically and synchronously."""
75
  text = str(body or "").strip()
76
  if not text:
@@ -104,7 +131,7 @@ def add_comment(runtime, pid, body, author_key, author_name="", now=None, commen
104
  return data
105
 
106
  try:
107
- runtime.update(STORE_KEY, _append, flush="sync")
108
  except ValueError:
109
  raise
110
  except Exception as exc:
@@ -112,7 +139,7 @@ def add_comment(runtime, pid, body, author_key, author_name="", now=None, commen
112
  return dict(comment)
113
 
114
 
115
- def delete_comment(runtime, pid, comment_id, actor_key, admin=False):
116
  """Delete a comment owned by ``actor_key`` (or by an administrator)."""
117
  cid = str(comment_id or "").strip()
118
  actor = str(actor_key or "").strip().lower()
@@ -146,7 +173,7 @@ def delete_comment(runtime, pid, comment_id, actor_key, admin=False):
146
  return data
147
 
148
  try:
149
- runtime.update(STORE_KEY, _delete, flush="sync")
150
  except Exception as exc:
151
  raise CommentsUnavailable("the comment was not deleted") from exc
152
  if state["forbidden"]:
 
1
+ """Durable comments attached to records, ONE BUCKET PER DATABASE.
2
 
3
  The service is deliberately unaware of HTTP and of the concrete store backend.
4
  It receives a tenant-bound ``TenantRuntime`` handle, so the same logical key can
5
  never cross a tenant boundary. Odoo remains read-only: comments live only in
6
  AIOS's writable tenant store.
7
+
8
+ ⭐ WAVE 19 (owner item 12) β€” THE BUCKET IS PER TOPIC. Every entry here is keyed by a bare pid,
9
+ and a pid only identifies a row INSIDE one database: customer pids are Odoo partner ids, product
10
+ pids are CRC32 hashes of SKU codes, a user table's are its own row numbers. One shared bucket
11
+ therefore had two failure modes, and the quiet one is why this changed:
12
+
13
+ * loud β€” a product record asked the customer endpoint about its hash, which is not in the
14
+ caller's book, and the panel said "that customer is not in your book" on a screen
15
+ showing a product. This is what the owner reported.
16
+ * quiet β€” a hash that lands on a real partner id answers 200, and the comment is filed
17
+ against somebody's customer, readable by everyone who can open that customer.
18
+
19
+ ``key_for(scope)`` gives each database its own bucket. THE CUSTOMER TOPIC KEEPS THE LEGACY KEY,
20
+ so nothing that has been written moves; ``STORE_KEY`` stays exported under its old name and value
21
+ for the same reason.
22
  """
23
  from __future__ import annotations
24
 
 
29
  MAX_BODY = 4000
30
  MAX_PER_RECORD = 500
31
 
32
+ #: The scope names that mean THE CUSTOMER BOOK β€” mirrors ``modules.cohort.LEGACY_SCOPES``.
33
+ #: Restated rather than imported: ``core/`` does not import ``modules/`` (ARCHITECTURE Β§1's
34
+ #: one-directional rule), and this file has stayed on the right side of that line.
35
+ LEGACY_SCOPES = frozenset({"", "customer", "cohort"})
36
+
37
+
38
+ def key_for(scope=None):
39
+ """The comments bucket ONE topic's records live in. Customer keeps the shipped key."""
40
+ s = str(scope or "customer").strip().lower()
41
+ return STORE_KEY if s in LEGACY_SCOPES else f"{s}_record_comments"
42
+
43
 
44
  class CommentsUnavailable(RuntimeError):
45
  """The tenant store cannot currently provide durable comments."""
 
76
  }
77
 
78
 
79
+ def _read(runtime, scope=None):
80
  if not runtime.available():
81
  raise CommentsUnavailable("the tenant store is unavailable")
82
  try:
83
+ data = runtime.get(key_for(scope))
84
  except Exception as exc:
85
  raise CommentsUnavailable("comments could not be read") from exc
86
  return data if isinstance(data, dict) else {}
87
 
88
 
89
+ def list_comments(runtime, pid, scope=None):
90
  """Return one record's comments oldest-first, dropping malformed legacy entries."""
91
+ rows = _read(runtime, scope).get(_record_key(pid), [])
92
  if not isinstance(rows, list):
93
  return []
94
  cleaned = [comment for raw in rows if (comment := _clean_comment(raw)) is not None]
 
96
  return cleaned
97
 
98
 
99
+ def add_comment(runtime, pid, body, author_key, author_name="", now=None, comment_id=None,
100
+ scope=None):
101
  """Append one server-authored comment atomically and synchronously."""
102
  text = str(body or "").strip()
103
  if not text:
 
131
  return data
132
 
133
  try:
134
+ runtime.update(key_for(scope), _append, flush="sync")
135
  except ValueError:
136
  raise
137
  except Exception as exc:
 
139
  return dict(comment)
140
 
141
 
142
+ def delete_comment(runtime, pid, comment_id, actor_key, admin=False, scope=None):
143
  """Delete a comment owned by ``actor_key`` (or by an administrator)."""
144
  cid = str(comment_id or "").strip()
145
  actor = str(actor_key or "").strip().lower()
 
173
  return data
174
 
175
  try:
176
+ runtime.update(key_for(scope), _delete, flush="sync")
177
  except Exception as exc:
178
  raise CommentsUnavailable("the comment was not deleted") from exc
179
  if state["forbidden"]:
platform/core/users.py CHANGED
@@ -27,7 +27,7 @@ def _hash(pw, salt):
27
 
28
 
29
  def _record(pw, name, role, bus, active=True, modules='all', agent=None, email=None,
30
- perms=None, tenant='royal-imports'):
31
  salt = secrets.token_hex(16)
32
  rec = {'salt': salt, 'hash': _hash(pw, salt), 'name': name, 'role': role,
33
  'bus': bus, 'active': active, 'modules': modules,
@@ -36,6 +36,12 @@ def _record(pw, name, role, bus, active=True, modules='all', agent=None, email=N
36
  # pre-wave record β€” no migration. Login binds the session to THIS value; the posted
37
  # tenant field can hint but never override it.
38
  'tenant': str(tenant or 'royal-imports').strip().lower()}
 
 
 
 
 
 
39
  if perms is not None:
40
  # Wave 15 C-PERM. A record written WITH perms is migrated by construction β€” the marker
41
  # and the block are set together, here, so no writer can create one without the other.
@@ -100,6 +106,15 @@ def _public(username, u):
100
  # present in three files and is absent in the one that runs.
101
  **({'perms': u['perms']} if isinstance(u.get('perms'), dict) else {}),
102
  **({'perms_v': int(u['perms_v'] or 0)} if u.get('perms_v') else {}),
 
 
 
 
 
 
 
 
 
103
  'epoch': int(u.get('epoch') or 0)}
104
 
105
 
@@ -180,7 +195,7 @@ def verify(username, pw):
180
 
181
 
182
  def create_user(username, pw, name, role='user', bus='all', modules='all',
183
- agent=None, email=None, tenant=None):
184
  """Create β€” or, from app.py's dialog, OVERWRITE β€” an account.
185
 
186
  β›” X3: OVERWRITING AN ACCOUNT MUST NOT RESURRECT ITS OLD SESSIONS. `_record()` builds a fresh
@@ -203,7 +218,14 @@ def create_user(username, pw, name, role='user', bus='all', modules='all',
203
  agent=agent, email=email,
204
  # An overwrite that names no tenant KEEPS the account's company β€” a
205
  # rename must never quietly move a user between tenants.
206
- tenant=(tenant or prior.get('tenant') or 'royal-imports'))
 
 
 
 
 
 
 
207
  if prior:
208
  rec['epoch'] = int(prior.get('epoch') or 0) + 1
209
  reg[username] = rec
@@ -242,6 +264,128 @@ def set_active(username, active):
242
  store.update('users', _set)
243
 
244
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
245
  def set_access(username, role=None, bus=None, modules=None, agent=None, email=None,
246
  name=None, perms=None):
247
  """Update access fields. agent/email: pass '' to clear, None to leave unchanged β€”
 
27
 
28
 
29
  def _record(pw, name, role, bus, active=True, modules='all', agent=None, email=None,
30
+ perms=None, tenant='royal-imports', platform_admin=False):
31
  salt = secrets.token_hex(16)
32
  rec = {'salt': salt, 'hash': _hash(pw, salt), 'name': name, 'role': role,
33
  'bus': bus, 'active': active, 'modules': modules,
 
36
  # pre-wave record β€” no migration. Login binds the session to THIS value; the posted
37
  # tenant field can hint but never override it.
38
  'tenant': str(tenant or 'royal-imports').strip().lower()}
39
+ if platform_admin is True:
40
+ # Wave 19 (R3): the PLATFORM-operator flag β€” half of `core.platform_admin`'s double lock
41
+ # (the other half is `tenant == 'loopable'`). Written ONLY for True, so every record that
42
+ # is not deliberately promoted keeps its pre-wave shape and answers False by absence.
43
+ # There is no UI writer and there never should be: it is set by provisioning, on purpose.
44
+ rec['platform_admin'] = True
45
  if perms is not None:
46
  # Wave 15 C-PERM. A record written WITH perms is migrated by construction β€” the marker
47
  # and the block are set together, here, so no writer can create one without the other.
 
106
  # present in three files and is absent in the one that runs.
107
  **({'perms': u['perms']} if isinstance(u.get('perms'), dict) else {}),
108
  **({'perms_v': int(u['perms_v'] or 0)} if u.get('perms_v') else {}),
109
+ # β›” WAVE 19 R3 β€” THE SAME RULE, ON A NEW FIELD. `deps._user_for` builds every API
110
+ # session from this projection, so the platform-admin flag travels here or
111
+ # `core.platform_admin.is_platform_admin(session.user)` is blind and the Loopable
112
+ # admin plane 403s its own operator. Carried ONLY when the record says True, so a
113
+ # session dict for any other account is byte-identical to its pre-wave shape.
114
+ # Not a client leak: `routes_auth._public_user` is a whitelist projection and does
115
+ # not name this key, so it reaches no browser via /login or /me β€” the client's copy
116
+ # is the separate `platformAdmin` bool on GET /settings, which is derived from this.
117
+ **({'platform_admin': True} if u.get('platform_admin') is True else {}),
118
  'epoch': int(u.get('epoch') or 0)}
119
 
120
 
 
195
 
196
 
197
  def create_user(username, pw, name, role='user', bus='all', modules='all',
198
+ agent=None, email=None, tenant=None, platform_admin=None):
199
  """Create β€” or, from app.py's dialog, OVERWRITE β€” an account.
200
 
201
  β›” X3: OVERWRITING AN ACCOUNT MUST NOT RESURRECT ITS OLD SESSIONS. `_record()` builds a fresh
 
218
  agent=agent, email=email,
219
  # An overwrite that names no tenant KEEPS the account's company β€” a
220
  # rename must never quietly move a user between tenants.
221
+ tenant=(tenant or prior.get('tenant') or 'royal-imports'),
222
+ # Wave 19 (R3): CARRIED, for the same reason `epoch` is carried below β€”
223
+ # `_record` builds a FRESH record, so re-running the provisioner (it is
224
+ # documented as idempotent) or saving an account through this function
225
+ # would silently DEMOTE a platform admin and lock the operator out of
226
+ # their own plane. None = leave as it was; True/False = set it deliberately.
227
+ platform_admin=(prior.get('platform_admin') is True
228
+ if platform_admin is None else platform_admin is True))
229
  if prior:
230
  rec['epoch'] = int(prior.get('epoch') or 0) + 1
231
  reg[username] = rec
 
264
  store.update('users', _set)
265
 
266
 
267
+ def set_platform_admin(username, on):
268
+ """Promote/demote a PLATFORM administrator (wave 19, R3) without touching the password.
269
+
270
+ The narrow write, deliberately: `create_user` is the destructive path (fresh salt, fresh
271
+ hash, bumped epoch) and promoting somebody should not sign them out or rotate a credential.
272
+ Cleared by REMOVING the key, so a demoted record goes back to its pre-wave shape rather than
273
+ carrying a `False` that reads as "somebody considered this".
274
+
275
+ ⚠ This is the flag only. It grants nothing on its own β€” `core.platform_admin` also demands
276
+ the `loopable` tenant, and there is no code path anywhere that moves an account between
277
+ tenants, which is what makes the second lock hold.
278
+ """
279
+ username = (username or '').strip().lower()
280
+
281
+ def _set(reg):
282
+ u = reg.get(username)
283
+ if u:
284
+ if on is True:
285
+ u['platform_admin'] = True
286
+ else:
287
+ u.pop('platform_admin', None)
288
+ return reg
289
+ store.update('users', _set)
290
+
291
+
292
+ # ------------------------------------------------------------------ activity stamps (wave 19 R4)
293
+ # "When did this account last sign in, and is anyone actually using it?" β€” the two questions the
294
+ # Loopable admin plane exists to answer and that NOTHING in the product could answer before this
295
+ # wave (there is no login history, no audit log, no request log anywhere).
296
+ #
297
+ # β›” THIS IS THE FIRST HIGH-FREQUENCY WRITER `users.json` HAS EVER HAD, and that bucket also holds
298
+ # every password hash, `active`, `epoch` and the permission blocks. Three rules follow, and the
299
+ # second one is a correctness rule, not a performance one:
300
+ #
301
+ # 1. **In-place mutation of ONE key.** Never `_record()`, never a whole-record replace: a stamp
302
+ # that rebuilt the record would reset the salt/hash (locking the user out) or the epoch
303
+ # (silently un-revoking every cookie ever minted for them). `set_password`'s docstring
304
+ # explains why that class of bug is worth naming out loud.
305
+ #
306
+ # 2. **SYNCHRONOUS FLUSH β€” deliberately NOT the async path, and this reverses my first draft.**
307
+ # `store.update(flush='async')` rebases on the PROCESS CACHE once a key is `_owned`
308
+ # (`core/store.py:284`) and its worker uploads that whole cached blob. For a
309
+ # table-workspace key, written by one process, that is exactly right. For `users` it is a
310
+ # silent-revert machine: tenant #0's Streamlit host writes the SAME file, so an API process
311
+ # holding a cache from an hour ago would, on its next stamp, upload a blob in which a
312
+ # password rotation or a deactivation performed in the other host simply never happened.
313
+ # A telemetry stamp must not be able to resurrect a disabled account. `flush='sync'` does a
314
+ # FRESH strict read inside the store's lock and then uploads, which is the same discipline
315
+ # every other `users` writer already uses.
316
+ #
317
+ # 3. **OFF THE REQUEST THREAD, so rule 2 costs nothing.** A sync commit is a hub round-trip, and
318
+ # neither a sign-in nor a random request an hour later should wait for it. Each stamp runs on
319
+ # a short-lived daemon thread; `flush_stamps()` is how a test or a shutdown waits for them.
320
+ # Everything is fail-silent: a stamp is telemetry and may never turn a good login into a
321
+ # failed one β€” the plane shows an honest "never" instead.
322
+ def _now_iso():
323
+ import datetime as _dt
324
+ return _dt.datetime.now(_dt.timezone.utc).isoformat(timespec='seconds')
325
+
326
+
327
+ #: Live stamp threads, so `flush_stamps()` can join them. Bounded by construction β€” one thread per
328
+ #: stamp, and a stamp is at most one per login plus one per account per hour per process.
329
+ _STAMPS = []
330
+ _STAMPS_LOCK = __import__('threading').Lock()
331
+
332
+
333
+ def _stamp(username, fields):
334
+ """Merge `fields` into ONE account record, on a background thread, with a fresh read."""
335
+ username = (username or '').strip().lower()
336
+ if not username or not fields:
337
+ return None
338
+
339
+ def _set(reg):
340
+ u = reg.get(username)
341
+ if isinstance(u, dict):
342
+ u.update(fields)
343
+ return reg
344
+
345
+ def _work():
346
+ try:
347
+ store.update('users', _set) # sync: fresh strict read + blocking upload
348
+ except Exception:
349
+ pass # a lost stamp is a lost stamp, never an error
350
+ import threading
351
+ t = threading.Thread(target=_work, daemon=True, name=f'user-stamp:{username}')
352
+ with _STAMPS_LOCK:
353
+ _STAMPS[:] = [x for x in _STAMPS if x.is_alive()]
354
+ _STAMPS.append(t)
355
+ t.start()
356
+ return t
357
+
358
+
359
+ def flush_stamps(timeout=10.0):
360
+ """Block until outstanding stamp writes have been applied. For gates and shutdown hooks β€”
361
+ the app never needs it, exactly like `core.store.flush`."""
362
+ with _STAMPS_LOCK:
363
+ pending = list(_STAMPS)
364
+ for t in pending:
365
+ t.join(timeout=timeout)
366
+ return all(not t.is_alive() for t in pending)
367
+
368
+
369
+ def touch_login(username, when=None):
370
+ """Stamp `last_login` (ISO-8601, UTC, OFFSET-BEARING) on a SUCCESSFUL login.
371
+
372
+ `username` must be the RESOLVED account key, not what the person typed: `verify()` accepts an
373
+ email address and resolves it to the registry key, so stamping the typed identifier would
374
+ write a stamp onto a key that does not exist and create a phantom account in the registry.
375
+
376
+ `last_active` rides along β€” signing in IS activity, and setting both here means the plane's
377
+ two columns agree the moment somebody logs in rather than an hour later.
378
+ """
379
+ stamp = when or _now_iso()
380
+ return _stamp(username, {'last_login': stamp, 'last_active': stamp})
381
+
382
+
383
+ def touch_active(username, when=None):
384
+ """Stamp `last_active` β€” "this session did something". Throttled BY THE CALLER (`deps.py`
385
+ holds a process-local last-seen map), so this is not a store round-trip per request."""
386
+ return _stamp(username, {'last_active': when or _now_iso()})
387
+
388
+
389
  def set_access(username, role=None, bus=None, modules=None, agent=None, email=None,
390
  name=None, perms=None):
391
  """Update access fields. agent/email: pass '' to clear, None to leave unchanged β€”
platform/harness/analyst.py CHANGED
@@ -291,7 +291,14 @@ def ask(question, history=None, chat_fn=None, model=DEFAULT_MODEL, max_iters=MAX
291
  answer = ("(the model returned an empty answer β€” nothing was computed; "
292
  "please rephrase or ask again)")
293
  import harness.telemetry as _tel
 
 
 
 
 
294
  _tel.log(telemetry_kind, question=question[:200],
 
 
295
  model=model or (available_providers() or [{}])[0].get("name", "auto"),
296
  iterations=i + 1,
297
  tools=[t["tool"] for t in trace],
 
291
  answer = ("(the model returned an empty answer β€” nothing was computed; "
292
  "please rephrase or ask again)")
293
  import harness.telemetry as _tel
294
+ # Wave 19 (R4): ATTRIBUTED. The token count was previously logged against nobody, so
295
+ # "which customer is spending model budget, and who inside it?" had no answer even in
296
+ # principle. Read defensively off `user` because this function is deliberately
297
+ # callable WITHOUT one β€” `harness/evals.py` and `harness/routines.py` run as the
298
+ # system, and telemetry omits both keys for them rather than inventing a subject.
299
  _tel.log(telemetry_kind, question=question[:200],
300
+ user=(user or {}).get("username") if isinstance(user, dict) else None,
301
+ tenant=(user or {}).get("tenant") if isinstance(user, dict) else None,
302
  model=model or (available_providers() or [{}])[0].get("name", "auto"),
303
  iterations=i + 1,
304
  tools=[t["tool"] for t in trace],
platform/harness/telemetry.py CHANGED
@@ -16,12 +16,35 @@ PATH = Path(__file__).resolve().parents[1] / "data" / "store" / "usage.jsonl"
16
  ERR_PATH = PATH.parent / "errors.jsonl"
17
 
18
 
19
- def log(kind, **fields):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
20
  try:
21
  PATH.parent.mkdir(parents=True, exist_ok=True)
 
 
 
 
 
 
22
  with PATH.open("a", encoding="utf-8") as f:
23
- f.write(json.dumps({"ts": time.strftime("%Y-%m-%d %H:%M:%S"),
24
- "kind": kind, **fields}, default=str) + "\n")
25
  except Exception:
26
  pass
27
 
 
16
  ERR_PATH = PATH.parent / "errors.jsonl"
17
 
18
 
19
+ def log(kind, user=None, tenant=None, **fields):
20
+ """Append one usage event. Never raises.
21
+
22
+ β­’ WAVE 19 (R4): `user` and `tenant` are FIRST-CLASS PARAMETERS, not just two more `**fields`.
23
+ They already worked as free-form fields β€” the point of naming them is that attribution stops
24
+ being a convention each call site remembers or forgets. The Analyst's token line is the first
25
+ caller to pass them (`harness/analyst.py`), which is what makes "who spent these tokens, for
26
+ which customer?" answerable AT ALL: before this wave the log recorded a token count attached
27
+ to nobody.
28
+
29
+ Both are OPTIONAL and omitted from the line when absent, so a system-initiated run (the eval
30
+ ladder, `harness/routines.py` β€” neither runs on behalf of a person) writes exactly the record
31
+ it wrote before. A missing key is honest; `"user": null` would invite a reader to count it.
32
+
33
+ ⚠ HONEST LIMIT β€” this file is CONTAINER-LOCAL JSONL (`data/store/usage.jsonl`, git-ignored,
34
+ lost on a Space restart). Attribution starts accruing now; it is not yet a durable, queryable
35
+ usage ledger, which is why the per-user token PANEL stays deferred (DEBT D-8) rather than
36
+ being built against a log that a redeploy erases.
37
+ """
38
  try:
39
  PATH.parent.mkdir(parents=True, exist_ok=True)
40
+ rec = {"ts": time.strftime("%Y-%m-%d %H:%M:%S"), "kind": kind}
41
+ if user:
42
+ rec["user"] = str(user)
43
+ if tenant:
44
+ rec["tenant"] = str(tenant)
45
+ rec.update(fields)
46
  with PATH.open("a", encoding="utf-8") as f:
47
+ f.write(json.dumps(rec, default=str) + "\n")
 
48
  except Exception:
49
  pass
50
 
platform/modules/cohort.py CHANGED
@@ -20,16 +20,50 @@ Persistence: HF store key `customer_cohorts`, shaped {username: {cohort_id: {...
20
  like the saved views it sits beside, and written through `store.update` (strict
21
  read-modify-write β€” never get+put around a mutation; that is the restart-wipe bug).
22
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
23
  No validate(): there is no Odoo aggregate to reconcile a hand-picked list against. Its counts
24
  derive from the rows it renders (rule 8b), and the metrics themselves are already validated by
25
  the customers module they come from.
26
  """
27
  import datetime as _dt
 
28
 
29
  import core.store as store
30
 
31
  KEY = 'customer_cohorts'
32
 
 
 
 
 
 
33
  #: A cohort is a list of ids, not a query β€” but ids are cheap and a runaway list would bloat the
34
  #: per-user store blob, which is read on every page render. Generous enough to never bind in
35
  #: practice (the whole book is ~1,550) and small enough to bound the payload.
@@ -37,22 +71,56 @@ MAX_MEMBERS = 5000
37
  MAX_COHORTS = 100
38
 
39
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
40
  def _now():
41
  return _dt.datetime.now().strftime('%Y-%m-%d %H:%M')
42
 
43
 
44
- def all_for(username):
45
- """{cohort_id: {name, members, note, created, updated}} for one user.
46
 
47
  Returns {} when the store is unavailable rather than raising: a cohort list that cannot load
48
  should degrade to "no cohorts", never to a broken page.
49
  """
50
  try:
51
- return dict((store.get(KEY) or {}).get(username, {}) or {})
52
  except Exception:
53
  return {}
54
 
55
 
 
 
 
 
 
56
  def _clean_members(raw, allowed_pids=None):
57
  """Ints only, de-duplicated, ORDER PRESERVED, and intersected with what this user may see.
58
 
@@ -76,25 +144,40 @@ def _clean_members(raw, allowed_pids=None):
76
  return out[:MAX_MEMBERS]
77
 
78
 
79
- def visible(username, allowed_pids=None):
80
- """Every cohort, with membership already scoped to what this user may open."""
81
  return {cid: {**c, 'members': _clean_members(c.get('members'), allowed_pids)}
82
- for cid, c in all_for(username).items()}
 
 
 
 
 
83
 
84
 
85
  def new_id(name):
86
- """A stable id from the name plus a suffix, so two cohorts called "Q3 calls" can coexist."""
 
 
 
 
 
 
87
  slug = ''.join(ch if ch.isalnum() else '_' for ch in str(name).lower()).strip('_')[:40]
88
  return f"cohort_{slug or 'list'}_{_dt.datetime.now().strftime('%H%M%S')}"
89
 
90
 
91
- def create(username, name, members=(), note=''):
92
- """Create a cohort and return its id. Raises ValueError on a blank name or when the per-user
93
- cap is reached β€” refusing loudly beats silently dropping somebody's list."""
 
 
 
 
94
  name = str(name or '').strip()[:120]
95
  if not name:
96
  raise ValueError('a cohort needs a name')
97
- existing = all_for(username)
98
  if len(existing) >= MAX_COHORTS:
99
  raise ValueError(f'you already have {MAX_COHORTS} cohorts β€” delete one first')
100
  cid = new_id(name)
@@ -104,11 +187,16 @@ def create(username, name, members=(), note=''):
104
  def _up(data):
105
  data.setdefault(username, {})[cid] = record
106
  return data
107
- store.update(KEY, _up)
108
  return cid
109
 
110
 
111
- def _mutate(username, cohort_id, change):
 
 
 
 
 
112
  def _up(data):
113
  book = data.setdefault(username, {})
114
  c = book.get(cohort_id)
@@ -117,10 +205,10 @@ def _mutate(username, cohort_id, change):
117
  change(c)
118
  c['updated'] = _now()
119
  return data
120
- store.update(KEY, _up)
121
 
122
 
123
- def add_members(username, cohort_id, pids):
124
  """Union new ids into a cohort, PRESERVING the existing order and appending the new ones.
125
 
126
  Additive on purpose: "add to list" from a view can be clicked twice, and the second click
@@ -128,33 +216,54 @@ def add_members(username, cohort_id, pids):
128
  """
129
  def _change(c):
130
  c['members'] = _clean_members(list(c.get('members') or []) + list(pids or []))
131
- _mutate(username, cohort_id, _change)
132
 
133
 
134
- def remove_members(username, cohort_id, pids):
 
 
 
 
 
135
  drop = {int(p) for p in (pids or []) if str(p).lstrip('-').isdigit()}
136
 
137
  def _change(c):
138
  c['members'] = [p for p in _clean_members(c.get('members')) if p not in drop]
139
- _mutate(username, cohort_id, _change)
140
 
141
 
142
- def rename(username, cohort_id, name):
 
 
 
 
143
  name = str(name or '').strip()[:120]
144
  if not name:
145
  raise ValueError('a cohort needs a name')
146
- _mutate(username, cohort_id, lambda c: c.__setitem__('name', name))
 
 
 
 
 
 
 
 
147
 
148
 
149
  def set_note(username, cohort_id, note):
150
- _mutate(username, cohort_id, lambda c: c.__setitem__('note', str(note or '')[:2000]))
151
 
152
 
153
- def delete(username, cohort_id):
154
  def _up(data):
155
  (data.get(username) or {}).pop(cohort_id, None)
156
  return data
157
- store.update(KEY, _up)
 
 
 
 
158
 
159
 
160
  def rows_for(cohort, pool_rows):
@@ -169,3 +278,69 @@ def rows_for(cohort, pool_rows):
169
  members = _clean_members(cohort.get('members'))
170
  rows = [by_pid[p] for p in members if p in by_pid]
171
  return rows, len(members) - len(rows)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
20
  like the saved views it sits beside, and written through `store.update` (strict
21
  read-modify-write β€” never get+put around a mutation; that is the restart-wipe bug).
22
 
23
+ ⭐ WAVE 19 / OWNER RULING R9 β€” A COHORT BELONGS TO ITS DATABASE. "It should stay in Product
24
+ database … for ANY database new/old": until relational features land, database functionalities
25
+ are purely independent. So this module is now SCOPE-PARAMETERIZED rather than restricted β€” one
26
+ bucket per topic (`<scope>_cohorts`), reached through `scoped(scope)`.
27
+
28
+ β›” THE ID SPACES ARE WHY, not tidiness. A cohort stores the TOPIC's row ids: customer pids are
29
+ Odoo partner ids, product pids are CRC32 hashes of the SKU code, a user table's are its own
30
+ row numbers. One shared bucket and a hash collision silently puts a product in somebody's
31
+ customer list β€” the same argument `routes_products` makes about the overlay bucket, and the
32
+ reason wave 16 answered it with `with_cohorts=False` (a refusal) instead of a bucket.
33
+
34
+ β›” THE CUSTOMER TOPIC KEEPS THE LEGACY KEY β€” zero migration. `customer` and `cohort` are ONE
35
+ topic (the Cohort surface is the customer table over hand-curated sets), so both resolve to
36
+ `customer_cohorts` and every shipped list is found exactly where it already lives.
37
+
38
+ β›” `scoped('customer')` RETURNS THIS MODULE, deliberately, so the module-level functions stay
39
+ the customer implementation rather than becoming a second copy of it. Callers that patch
40
+ `modules.cohort.visible` (the gates do) keep working through the facade, and every existing
41
+ positional call site is byte-unaffected.
42
+
43
+ TENANCY, STATED NOT HIDDEN (booked as DEBT, wave 19): this module writes through the MODULE-LEVEL
44
+ `core.store`, i.e. tenant #0's dataset repo β€” the same place `customer_docs` and the customer /
45
+ product table workspaces already live. It is safe rather than correct: the outer key is the
46
+ USERNAME, and `core/users.py`'s registry is ONE global bucket, so a username belongs to exactly
47
+ one tenant and no cross-tenant READ is reachable. What is wrong is RESIDENCY (tenant B's lists
48
+ sit in tenant #0's repo). Fixing it means threading the runtime handle through `EventCtx`, which
49
+ needs `routes_grid._ctx` β€” another session's file this wave.
50
+
51
  No validate(): there is no Odoo aggregate to reconcile a hand-picked list against. Its counts
52
  derive from the rows it renders (rule 8b), and the metrics themselves are already validated by
53
  the customers module they come from.
54
  """
55
  import datetime as _dt
56
+ import sys as _sys
57
 
58
  import core.store as store
59
 
60
  KEY = 'customer_cohorts'
61
 
62
+ #: The scope names that mean THE CUSTOMER BOOK. `cohort` is the customer table over curated sets
63
+ #: β€” the same rows, the same pids, the same lists β€” so it must resolve to the same bucket, and ''
64
+ #: is what an unset `scope_key` looks like. Anything else is another database.
65
+ LEGACY_SCOPES = frozenset({'', 'customer', 'cohort'})
66
+
67
  #: A cohort is a list of ids, not a query β€” but ids are cheap and a runaway list would bloat the
68
  #: per-user store blob, which is read on every page render. Generous enough to never bind in
69
  #: practice (the whole book is ~1,550) and small enough to bound the payload.
 
71
  MAX_COHORTS = 100
72
 
73
 
74
+ def key_for(scope):
75
+ """The store bucket ONE topic's cohorts live in (R9).
76
+
77
+ Customer (and its `cohort` surface) keep `customer_cohorts` β€” the legacy key, so no shipped
78
+ list moves. Every other database gets `<scope>_cohorts`, which for a user table is
79
+ `ut_<slug>_cohorts`: the same naming the table's own workspace bucket already uses
80
+ (`<scope>_table_workspace`), so one database's durable state reads as one family.
81
+ """
82
+ s = str(scope or 'customer').strip().lower()
83
+ return KEY if s in LEGACY_SCOPES else f'{s}_cohorts'
84
+
85
+
86
+ def noun_for(scope):
87
+ """What ONE row of this topic is called β€” the "Added 12 customers to …" toast's noun.
88
+
89
+ A hardcoded "customer" was the visible half of the leak this ruling closes: adding twelve
90
+ SKUs to a product list said "Added 12 customers", which is the surface telling the user the
91
+ wrong thing about where their list went. Unknown topics say "record" rather than guessing a
92
+ label from a slug β€” a user table is called whatever its creator named it, and inventing a
93
+ singular from `ut_supplier_quotes` would be worse than the honest generic.
94
+ """
95
+ s = str(scope or 'customer').strip().lower()
96
+ if s in LEGACY_SCOPES:
97
+ return 'customer'
98
+ if s == 'product':
99
+ return 'product'
100
+ return 'record'
101
+
102
+
103
  def _now():
104
  return _dt.datetime.now().strftime('%Y-%m-%d %H:%M')
105
 
106
 
107
+ def _all_for(key, username):
108
+ """{cohort_id: {name, members, note, created, updated}} for one user, from ONE bucket.
109
 
110
  Returns {} when the store is unavailable rather than raising: a cohort list that cannot load
111
  should degrade to "no cohorts", never to a broken page.
112
  """
113
  try:
114
+ return dict((store.get(key) or {}).get(username, {}) or {})
115
  except Exception:
116
  return {}
117
 
118
 
119
+ def all_for(username):
120
+ """{cohort_id: {...}} for one user on the CUSTOMER book β€” see `_all_for`."""
121
+ return _all_for(KEY, username)
122
+
123
+
124
  def _clean_members(raw, allowed_pids=None):
125
  """Ints only, de-duplicated, ORDER PRESERVED, and intersected with what this user may see.
126
 
 
144
  return out[:MAX_MEMBERS]
145
 
146
 
147
+ def _visible(key, username, allowed_pids=None):
148
+ """Every cohort in ONE bucket, with membership already scoped to what this user may open."""
149
  return {cid: {**c, 'members': _clean_members(c.get('members'), allowed_pids)}
150
+ for cid, c in _all_for(key, username).items()}
151
+
152
+
153
+ def visible(username, allowed_pids=None):
154
+ """Every CUSTOMER cohort, membership scoped to what this user may open."""
155
+ return _visible(KEY, username, allowed_pids)
156
 
157
 
158
  def new_id(name):
159
+ """A stable id from the name plus a suffix, so two cohorts called "Q3 calls" can coexist.
160
+
161
+ ⚠ Topic-FREE on purpose. The id is a handle stored inside the topic's own bucket, and a saved
162
+ view's `cohortLock` names it β€” so encoding the topic in the string would only add a second
163
+ place for the two to disagree. Two databases may each hold a `cohort_q3_calls_101112`; they
164
+ are different objects in different buckets and neither read can reach the other.
165
+ """
166
  slug = ''.join(ch if ch.isalnum() else '_' for ch in str(name).lower()).strip('_')[:40]
167
  return f"cohort_{slug or 'list'}_{_dt.datetime.now().strftime('%H%M%S')}"
168
 
169
 
170
+ def _create(key, username, name, members=(), note=''):
171
+ """Create a cohort in ONE bucket and return its id. Raises ValueError on a blank name or when
172
+ the per-user cap is reached β€” refusing loudly beats silently dropping somebody's list.
173
+
174
+ The cap is PER BUCKET, i.e. per database, which is the honest reading of R9: a hundred
175
+ product lists must not be spent by a hundred customer lists somebody else's page created.
176
+ """
177
  name = str(name or '').strip()[:120]
178
  if not name:
179
  raise ValueError('a cohort needs a name')
180
+ existing = _all_for(key, username)
181
  if len(existing) >= MAX_COHORTS:
182
  raise ValueError(f'you already have {MAX_COHORTS} cohorts β€” delete one first')
183
  cid = new_id(name)
 
187
  def _up(data):
188
  data.setdefault(username, {})[cid] = record
189
  return data
190
+ store.update(key, _up)
191
  return cid
192
 
193
 
194
+ def create(username, name, members=(), note=''):
195
+ """Create a CUSTOMER cohort and return its id β€” see `_create`."""
196
+ return _create(KEY, username, name, members=members, note=note)
197
+
198
+
199
+ def _mutate(key, username, cohort_id, change):
200
  def _up(data):
201
  book = data.setdefault(username, {})
202
  c = book.get(cohort_id)
 
205
  change(c)
206
  c['updated'] = _now()
207
  return data
208
+ store.update(key, _up)
209
 
210
 
211
+ def _add_members(key, username, cohort_id, pids):
212
  """Union new ids into a cohort, PRESERVING the existing order and appending the new ones.
213
 
214
  Additive on purpose: "add to list" from a view can be clicked twice, and the second click
 
216
  """
217
  def _change(c):
218
  c['members'] = _clean_members(list(c.get('members') or []) + list(pids or []))
219
+ _mutate(key, username, cohort_id, _change)
220
 
221
 
222
+ def add_members(username, cohort_id, pids):
223
+ """Union new ids into a CUSTOMER cohort β€” see `_add_members`."""
224
+ _add_members(KEY, username, cohort_id, pids)
225
+
226
+
227
+ def _remove_members(key, username, cohort_id, pids):
228
  drop = {int(p) for p in (pids or []) if str(p).lstrip('-').isdigit()}
229
 
230
  def _change(c):
231
  c['members'] = [p for p in _clean_members(c.get('members')) if p not in drop]
232
+ _mutate(key, username, cohort_id, _change)
233
 
234
 
235
+ def remove_members(username, cohort_id, pids):
236
+ _remove_members(KEY, username, cohort_id, pids)
237
+
238
+
239
+ def _rename(key, username, cohort_id, name):
240
  name = str(name or '').strip()[:120]
241
  if not name:
242
  raise ValueError('a cohort needs a name')
243
+ _mutate(key, username, cohort_id, lambda c: c.__setitem__('name', name))
244
+
245
+
246
+ def rename(username, cohort_id, name):
247
+ _rename(KEY, username, cohort_id, name)
248
+
249
+
250
+ def _set_note(key, username, cohort_id, note):
251
+ _mutate(key, username, cohort_id, lambda c: c.__setitem__('note', str(note or '')[:2000]))
252
 
253
 
254
  def set_note(username, cohort_id, note):
255
+ _set_note(KEY, username, cohort_id, note)
256
 
257
 
258
+ def _delete(key, username, cohort_id):
259
  def _up(data):
260
  (data.get(username) or {}).pop(cohort_id, None)
261
  return data
262
+ store.update(key, _up)
263
+
264
+
265
+ def delete(username, cohort_id):
266
+ _delete(KEY, username, cohort_id)
267
 
268
 
269
  def rows_for(cohort, pool_rows):
 
278
  members = _clean_members(cohort.get('members'))
279
  rows = [by_pid[p] for p in members if p in by_pid]
280
  return rows, len(members) - len(rows)
281
+
282
+
283
+ # ─────────────────────────────────────────────── R9: ONE topic's cohorts, as an object
284
+ class CohortStore:
285
+ """The cohort verbs for ONE non-customer database, closed over its bucket key.
286
+
287
+ Same method names and same argument order as the module functions above, so a caller written
288
+ against `modules.cohort` reads identically whichever it holds β€” which is the point: the write
289
+ handler resolves the store once (`scoped(ctx.scope_key)`) and every branch below it stays the
290
+ code it already was.
291
+ """
292
+
293
+ __slots__ = ('scope', 'key', 'noun')
294
+
295
+ def __init__(self, scope):
296
+ self.scope = str(scope or 'customer').strip().lower()
297
+ self.key = key_for(self.scope)
298
+ self.noun = noun_for(self.scope)
299
+
300
+ def __repr__(self):
301
+ return f'CohortStore({self.scope!r} -> {self.key!r})'
302
+
303
+ def all_for(self, username):
304
+ return _all_for(self.key, username)
305
+
306
+ def visible(self, username, allowed_pids=None):
307
+ return _visible(self.key, username, allowed_pids)
308
+
309
+ def create(self, username, name, members=(), note=''):
310
+ return _create(self.key, username, name, members=members, note=note)
311
+
312
+ def add_members(self, username, cohort_id, pids):
313
+ _add_members(self.key, username, cohort_id, pids)
314
+
315
+ def remove_members(self, username, cohort_id, pids):
316
+ _remove_members(self.key, username, cohort_id, pids)
317
+
318
+ def rename(self, username, cohort_id, name):
319
+ _rename(self.key, username, cohort_id, name)
320
+
321
+ def set_note(self, username, cohort_id, note):
322
+ _set_note(self.key, username, cohort_id, note)
323
+
324
+ def delete(self, username, cohort_id):
325
+ _delete(self.key, username, cohort_id)
326
+
327
+
328
+ def scoped(scope=None):
329
+ """The cohort store for ONE topic β€” THE resolution point (R9).
330
+
331
+ β›” Returns THIS MODULE for the customer topic, not a `CohortStore(KEY)`. Two reasons, and both
332
+ are about not creating a second implementation of the shipped behaviour:
333
+ 1. the module-level functions ARE the customer store, so the legacy path keeps executing
334
+ exactly the code the gates measure β€” no wrapper to drift from;
335
+ 2. tests patch `modules.cohort.visible` (verify_grid_events' folder legs do), and a facade
336
+ that returned a bound object would silently ignore the patch, leaving a gate green over
337
+ code it is no longer exercising.
338
+ """
339
+ if str(scope or 'customer').strip().lower() in LEGACY_SCOPES:
340
+ return _sys.modules[__name__]
341
+ return CohortStore(scope)
342
+
343
+
344
+ #: What ONE row of the customer topic is called β€” the module facade's answer to `CohortStore.noun`,
345
+ #: so `scoped(x).noun` reads the same whichever object `x` resolved to.
346
+ noun = 'customer'
web/dist-embed/index.html CHANGED
The diff for this file is too large to render. See raw diff
 
web/src/automation/AutomationCanvas.tsx ADDED
@@ -0,0 +1,389 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // automation/AutomationCanvas.tsx β€” the flow, drawn (owner ruling R5).
3
+ //
4
+ // Hand-rolled SVG + CSS, no new dependency: the repo already draws its own
5
+ // charts and maps this way (`web/src/viz/`), and a flow of four to six nodes is
6
+ // not worth a graph library's bundle, its theming fight, or its opinion about
7
+ // where state lives.
8
+ //
9
+ // ⚠ BRANCHES RENDER; THEY DO NOT EXECUTE (R5, accepted at grill β€” DEBT D-7).
10
+ // The capture branch is a real fork in BEHAVIOUR β€” the paid rung answers or the
11
+ // anonymous ladder does β€” and the engine still walks it linearly. Nothing here
12
+ // should be read as a general branching runtime.
13
+ //
14
+ // TWO TRAPS THIS FILE IS BUILT AROUND, both from [[ui-invisible-to-assertions]]
15
+ // (a thing can be painted, asserted, and still not usable):
16
+ // 1. THE EDGE LAYER MUST NOT EAT CLICKS. It is a full-bleed <svg> sitting over
17
+ // the same area as the nodes, so it carries `pointer-events: none` and the
18
+ // node buttons stay hittable. A canvas whose nodes cannot be clicked passes
19
+ // every DOM assertion ever written about it.
20
+ // 2. A PAN MUST NOT FIRE A CLICK. Dragging the background across a node ends
21
+ // with a click event on whatever is under the pointer, so a drag that moved
22
+ // more than a few pixels suppresses the click it would otherwise produce.
23
+ // ---------------------------------------------------------------------------
24
+ import type { PointerEvent as ReactPointerEvent } from "react";
25
+ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
26
+
27
+ import type { AutomationGraph, GraphNode } from "./automationApi";
28
+ import type { Placed, Viewport } from "./canvasLayout";
29
+ import {
30
+ IDENTITY,
31
+ MAX_ZOOM,
32
+ MIN_ZOOM,
33
+ NODE_H,
34
+ NODE_W,
35
+ bounds,
36
+ clampZoom,
37
+ fit,
38
+ place,
39
+ wires,
40
+ zoomAt,
41
+ } from "./canvasLayout";
42
+
43
+ interface Props {
44
+ graph: AutomationGraph;
45
+ selected: string;
46
+ onSelect: (nodeId: string) => void;
47
+ /** Flip a node's switch. Absent (or a node with no `toggle`) = no switch drawn. */
48
+ onToggle?: (nodeId: string) => void;
49
+ busyNode?: string;
50
+ /** Shown on the trigger node when the server knows the next fire time. */
51
+ nextRunAt?: string;
52
+ }
53
+
54
+ /** How far a pointer may travel and still count as a click, not a drag. */
55
+ const DRAG_SLOP = 4;
56
+ /** Room left around the flow for the SVG layer, so a curve never clips. */
57
+ const SVG_PAD = 260;
58
+
59
+ function KindMark({ kind }: { kind: GraphNode["kind"] }) {
60
+ // Drawn paths, never emojis (owner constant). Each mark says what the step DOES
61
+ // at a glance: a clock schedules, a globe reaches out, an arrow brings back, a
62
+ // fork chooses, a cylinder stores.
63
+ const common = {
64
+ width: 15,
65
+ height: 15,
66
+ viewBox: "0 0 16 16",
67
+ fill: "none",
68
+ stroke: "currentColor",
69
+ strokeWidth: 1.4,
70
+ strokeLinecap: "round" as const,
71
+ strokeLinejoin: "round" as const,
72
+ "aria-hidden": true,
73
+ };
74
+ if (kind === "trigger")
75
+ return (
76
+ <svg {...common}>
77
+ <circle cx="8" cy="8" r="5.6" />
78
+ <path d="M8 5.2V8l2 1.4" />
79
+ </svg>
80
+ );
81
+ if (kind === "source")
82
+ return (
83
+ <svg {...common}>
84
+ <circle cx="8" cy="8" r="5.6" />
85
+ <path d="M2.6 8h10.8M8 2.4c1.5 1.7 2.2 3.6 2.2 5.6S9.5 12.3 8 13.6C6.5 12.3 5.8 10 5.8 8s.7-3.9 2.2-5.6z" />
86
+ </svg>
87
+ );
88
+ if (kind === "branch")
89
+ return (
90
+ <svg {...common}>
91
+ <path d="M2.6 8h3.2l2.6-3.6h5M8.4 11.6H5.8m2.6 0h5" />
92
+ <path d="M11.6 2.6 13.4 4.4 11.6 6.2M11.6 9.8l1.8 1.8-1.8 1.8" />
93
+ </svg>
94
+ );
95
+ if (kind === "write")
96
+ return (
97
+ <svg {...common}>
98
+ <ellipse cx="8" cy="4.2" rx="4.8" ry="1.9" />
99
+ <path d="M3.2 4.2v7.6c0 1 2.1 1.9 4.8 1.9s4.8-.9 4.8-1.9V4.2M3.2 8c0 1 2.1 1.9 4.8 1.9s4.8-.9 4.8-1.9" />
100
+ </svg>
101
+ );
102
+ return (
103
+ <svg {...common}>
104
+ <path d="M8 2.6v7.2M5.2 7l2.8 2.8L10.8 7M3 12.4h10" />
105
+ </svg>
106
+ );
107
+ }
108
+
109
+ export default function AutomationCanvas({
110
+ graph,
111
+ selected,
112
+ onSelect,
113
+ onToggle,
114
+ busyNode,
115
+ nextRunAt,
116
+ }: Props) {
117
+ const hostRef = useRef<HTMLDivElement | null>(null);
118
+ const [view, setView] = useState<Viewport>(IDENTITY);
119
+ const drag = useRef<{ px: number; py: number; vx: number; vy: number; moved: boolean } | null>(
120
+ null
121
+ );
122
+
123
+ const placed = useMemo(() => place(graph?.nodes || []), [graph]);
124
+ const lines = useMemo(() => wires(graph, placed), [graph, placed]);
125
+ const box = useMemo(() => bounds(placed), [placed]);
126
+
127
+ const fitNow = useCallback(() => {
128
+ const el = hostRef.current;
129
+ if (!el) return;
130
+ const r = el.getBoundingClientRect();
131
+ setView(fit(placed, r.width, r.height));
132
+ }, [placed]);
133
+
134
+ // Fit on mount and whenever the SHAPE changes. Keyed on the node ids rather
135
+ // than the graph object: a status dot moving from idle to ok is a new object
136
+ // every poll, and re-fitting the canvas under someone mid-inspection because a
137
+ // dot changed colour would be its own small betrayal.
138
+ const shape = placed.map((p) => `${p.id}:${p.col}:${p.row}`).join("|");
139
+ useLayoutEffect(() => {
140
+ fitNow();
141
+ // eslint-disable-next-line react-hooks/exhaustive-deps
142
+ }, [shape]);
143
+
144
+ // ⚠ THE ZERO-SIZE MOUNT. If this lands before the flex parent has a height β€”
145
+ // a collapsed rail animating open, a hidden tab becoming visible β€” the fit
146
+ // above measures 0Γ—0, silently returns the identity viewport, and the flow
147
+ // sits jammed in the top-left corner looking like a layout bug. So: re-fit
148
+ // exactly ONCE, on the transition from no-size to size. Deliberately not a
149
+ // general re-fit-on-resize β€” that would yank the canvas back to centre every
150
+ // time the window moved, fighting a pan the user had just made.
151
+ useEffect(() => {
152
+ const el = hostRef.current;
153
+ if (!el || typeof ResizeObserver === "undefined") return undefined;
154
+ let hadSize = el.getBoundingClientRect().width > 0;
155
+ const ro = new ResizeObserver(() => {
156
+ const wide = el.getBoundingClientRect().width > 0;
157
+ if (wide && !hadSize) fitNow();
158
+ hadSize = wide;
159
+ });
160
+ ro.observe(el);
161
+ return () => ro.disconnect();
162
+ }, [fitNow]);
163
+
164
+ // Wheel zoom, on a NON-PASSIVE native listener. React attaches wheel handlers
165
+ // passively, so `preventDefault()` inside an `onWheel` prop is ignored and the
166
+ // page scrolls behind the canvas instead of the canvas zooming.
167
+ useEffect(() => {
168
+ const el = hostRef.current;
169
+ if (!el) return undefined;
170
+ const onWheel = (e: WheelEvent) => {
171
+ e.preventDefault();
172
+ const r = el.getBoundingClientRect();
173
+ setView((v) =>
174
+ zoomAt(v, v.k * (e.deltaY < 0 ? 1.12 : 1 / 1.12), e.clientX - r.left, e.clientY - r.top)
175
+ );
176
+ };
177
+ el.addEventListener("wheel", onWheel, { passive: false });
178
+ return () => el.removeEventListener("wheel", onWheel);
179
+ }, []);
180
+
181
+ const onPointerDown = (e: ReactPointerEvent<HTMLDivElement>) => {
182
+ if (e.button !== 0) return;
183
+ (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
184
+ drag.current = { px: e.clientX, py: e.clientY, vx: view.x, vy: view.y, moved: false };
185
+ };
186
+
187
+ const onPointerMove = (e: ReactPointerEvent<HTMLDivElement>) => {
188
+ const d = drag.current;
189
+ if (!d) return;
190
+ const dx = e.clientX - d.px;
191
+ const dy = e.clientY - d.py;
192
+ if (!d.moved && Math.abs(dx) + Math.abs(dy) < DRAG_SLOP) return;
193
+ d.moved = true;
194
+ setView((v) => ({ ...v, x: d.vx + dx, y: d.vy + dy }));
195
+ };
196
+
197
+ const endDrag = (e: ReactPointerEvent<HTMLDivElement>) => {
198
+ if (drag.current) {
199
+ try {
200
+ (e.currentTarget as HTMLElement).releasePointerCapture(e.pointerId);
201
+ } catch {
202
+ // The pointer was already released (a lost capture on window blur). Not
203
+ // a failure β€” the drag is over either way.
204
+ }
205
+ }
206
+ // Trap 2: leave the "did it move" flag readable for the click that follows.
207
+ window.setTimeout(() => {
208
+ drag.current = null;
209
+ }, 0);
210
+ };
211
+
212
+ const swallowClick = () => drag.current?.moved === true;
213
+
214
+ const zoomBy = (factor: number) => {
215
+ const el = hostRef.current;
216
+ if (!el) return;
217
+ const r = el.getBoundingClientRect();
218
+ setView((v) => zoomAt(v, v.k * factor, r.width / 2, r.height / 2));
219
+ };
220
+
221
+ return (
222
+ <div className="auto-canvas-wrap">
223
+ <div
224
+ className="auto-canvas"
225
+ ref={hostRef}
226
+ // `group`, NOT `application`. Every node here is a real <button>, so a
227
+ // screen reader should keep browsing them normally; `application` would
228
+ // switch AT into forms mode and hand it a pan/zoom surface it cannot
229
+ // drive instead of the list of steps it can.
230
+ role="group"
231
+ aria-label="Automation flow"
232
+ onPointerDown={onPointerDown}
233
+ onPointerMove={onPointerMove}
234
+ onPointerUp={endDrag}
235
+ onPointerCancel={endDrag}
236
+ >
237
+ <div
238
+ className="auto-scene"
239
+ style={{ transform: `translate(${view.x}px, ${view.y}px) scale(${view.k})` }}
240
+ >
241
+ {/* Trap 1: this layer is decorative and must never intercept a click. */}
242
+ <svg
243
+ className="auto-wires"
244
+ style={{
245
+ left: box.minX - SVG_PAD,
246
+ top: box.minY - SVG_PAD,
247
+ width: box.w + SVG_PAD * 2,
248
+ height: box.h + SVG_PAD * 2,
249
+ }}
250
+ aria-hidden="true"
251
+ >
252
+ <g transform={`translate(${SVG_PAD - box.minX}, ${SVG_PAD - box.minY})`}>
253
+ {lines.map((w) => (
254
+ <g key={`${w.from}->${w.to}`} className={"auto-wire" + (w.dim ? " is-dim" : "")}>
255
+ <path d={w.d} />
256
+ {w.label ? (
257
+ <text x={w.mid[0]} y={w.mid[1]} textAnchor="middle">
258
+ {w.label}
259
+ </text>
260
+ ) : null}
261
+ </g>
262
+ ))}
263
+ </g>
264
+ </svg>
265
+
266
+ {placed.map((p: Placed, i) => (
267
+ <div
268
+ key={p.id}
269
+ className={
270
+ "auto-node" +
271
+ (p.id === selected ? " is-selected" : "") +
272
+ (p.enabled ? "" : " is-off") +
273
+ ` is-${p.kind}`
274
+ }
275
+ style={{ left: p.x, top: p.y, width: NODE_W, height: NODE_H }}
276
+ >
277
+ <button
278
+ type="button"
279
+ className="auto-node-hit"
280
+ aria-pressed={p.id === selected}
281
+ title={`${p.title} β€” ${p.subtitle}`}
282
+ onClick={() => {
283
+ if (swallowClick()) return;
284
+ onSelect(p.id);
285
+ }}
286
+ >
287
+ <span className="auto-node-head">
288
+ <span className="auto-node-mark">
289
+ <KindMark kind={p.kind} />
290
+ </span>
291
+ <span className="auto-node-title">{p.title}</span>
292
+ </span>
293
+ <span className="auto-node-sub">{p.subtitle}</span>
294
+ <span className="auto-node-detail">
295
+ {p.id === "trigger" && nextRunAt && p.enabled ? `Next ${nextRunAt}` : p.detail}
296
+ </span>
297
+ <span className="auto-node-foot">
298
+ <span className="auto-node-step">{i + 1}</span>
299
+ <span
300
+ className={`auto-dot is-${p.status}`}
301
+ title={`Last run: ${p.status}`}
302
+ aria-label={`Last run: ${p.status}`}
303
+ />
304
+ </span>
305
+ </button>
306
+ {p.toggle && onToggle ? (
307
+ <button
308
+ type="button"
309
+ className={"auto-node-switch" + (p.enabled ? " is-on" : "")}
310
+ disabled={busyNode === p.id}
311
+ aria-pressed={p.enabled}
312
+ aria-label={`${p.enabled ? "Turn off" : "Turn on"} ${p.title}`}
313
+ title={`${p.enabled ? "Turn off" : "Turn on"} ${p.title}`}
314
+ onClick={(e) => {
315
+ e.stopPropagation();
316
+ if (swallowClick()) return;
317
+ onToggle(p.id);
318
+ }}
319
+ >
320
+ <span className="auto-node-switch-knob" />
321
+ </button>
322
+ ) : (
323
+ // A step with no honest switch says so, rather than carrying a
324
+ // control that would do nothing (R5's "every node toggleable"
325
+ // ends where a real behaviour change ends).
326
+ <span className="auto-node-always" title="This step is what the automation is">
327
+ Always
328
+ </span>
329
+ )}
330
+ </div>
331
+ ))}
332
+ </div>
333
+ </div>
334
+
335
+ <div className="auto-zoom" role="group" aria-label="Canvas zoom">
336
+ <button type="button" className="auto-zoom-btn" title="Fit the flow" onClick={fitNow}>
337
+ <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
338
+ <path
339
+ d="M2.6 5.8V2.6h3.2M13.4 5.8V2.6h-3.2M2.6 10.2v3.2h3.2M13.4 10.2v3.2h-3.2"
340
+ stroke="currentColor"
341
+ strokeWidth="1.4"
342
+ strokeLinecap="round"
343
+ strokeLinejoin="round"
344
+ />
345
+ </svg>
346
+ </button>
347
+ <button
348
+ type="button"
349
+ className="auto-zoom-btn"
350
+ title="Zoom out"
351
+ aria-label="Zoom out"
352
+ disabled={view.k <= MIN_ZOOM + 0.001}
353
+ onClick={() => zoomBy(1 / 1.2)}
354
+ >
355
+ <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
356
+ <path d="M3.6 8h8.8" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
357
+ </svg>
358
+ </button>
359
+ <button
360
+ type="button"
361
+ className="auto-zoom-pct"
362
+ title="Back to 100%"
363
+ onClick={() => setView((v) => ({ ...v, k: clampZoom(1) }))}
364
+ >
365
+ {Math.round(view.k * 100)}%
366
+ </button>
367
+ <button
368
+ type="button"
369
+ className="auto-zoom-btn"
370
+ title="Zoom in"
371
+ aria-label="Zoom in"
372
+ disabled={view.k >= MAX_ZOOM - 0.001}
373
+ onClick={() => zoomBy(1.2)}
374
+ >
375
+ <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
376
+ <path
377
+ d="M8 3.6v8.8M3.6 8h8.8"
378
+ stroke="currentColor"
379
+ strokeWidth="1.5"
380
+ strokeLinecap="round"
381
+ />
382
+ </svg>
383
+ </button>
384
+ </div>
385
+ </div>
386
+ );
387
+ }
388
+
389
+ export { NODE_H, NODE_W };
web/src/automation/AutomationCreate.tsx ADDED
@@ -0,0 +1,394 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // automation/AutomationCreate.tsx β€” the one form that is NOT a canvas.
3
+ //
4
+ // WHY A FORM AND NOT AN EMPTY CANVAS. The node graph is derived by the server
5
+ // from a stored definition (`engine.graph`), which is what stops the drawing
6
+ // from ever describing a step the engine no longer runs. An automation that does
7
+ // not exist yet has no definition, so drawing it would mean a SECOND, client-side
8
+ // idea of what the steps are β€” exactly the drift the split was built to prevent.
9
+ //
10
+ // So creation is a short form and everything after it is the canvas. That is also
11
+ // how the two kinds actually differ: you cannot map columns you have not seen, so
12
+ // "Read the page" has to happen before a scrape can be created at all.
13
+ // ---------------------------------------------------------------------------
14
+ import { useCallback, useEffect, useState } from "react";
15
+
16
+ import type { AutomationKind, SourcePreview, UserTable } from "./automationApi";
17
+ import {
18
+ AutomationError,
19
+ createAutomation,
20
+ fieldKeyFor,
21
+ listTables,
22
+ previewSource,
23
+ } from "./automationApi";
24
+
25
+ interface Props {
26
+ kinds: { key: AutomationKind; label: string }[];
27
+ onCreated: (id: string) => void | Promise<void>;
28
+ onCancel: () => void;
29
+ }
30
+
31
+ interface ColumnPlan {
32
+ column: string;
33
+ include: boolean;
34
+ key: string;
35
+ }
36
+
37
+ export default function AutomationCreate({ kinds, onCreated, onCancel }: Props) {
38
+ const [name, setName] = useState("");
39
+ const [kind, setKind] = useState<AutomationKind>("scrape_db");
40
+ const [problem, setProblem] = useState("");
41
+ const [message, setMessage] = useState("");
42
+ const [saving, setSaving] = useState(false);
43
+
44
+ const [url, setUrl] = useState("");
45
+ const [extract, setExtract] = useState("table");
46
+ const [tableIndex, setTableIndex] = useState(0);
47
+ const [targetLabel, setTargetLabel] = useState("");
48
+ const [preview, setPreview] = useState<SourcePreview | null>(null);
49
+ const [reading, setReading] = useState(false);
50
+ const [plan, setPlan] = useState<ColumnPlan[]>([]);
51
+ const [keyField, setKeyField] = useState("");
52
+
53
+ const [tables, setTables] = useState<UserTable[]>([]);
54
+ const [targetTable, setTargetTable] = useState("");
55
+ const [fieldKey, setFieldKey] = useState("");
56
+ const [urlField, setUrlField] = useState("");
57
+
58
+ useEffect(() => {
59
+ const ac = new AbortController();
60
+ listTables(ac.signal)
61
+ .then((r) => setTables(r.tables))
62
+ .catch(() => setTables([]));
63
+ return () => ac.abort();
64
+ }, []);
65
+
66
+ const table = tables.find((t) => t.key === targetTable) || null;
67
+
68
+ const readPage = useCallback(async () => {
69
+ setReading(true);
70
+ setProblem("");
71
+ try {
72
+ const p = await previewSource(url, extract, tableIndex);
73
+ setPreview(p);
74
+ if (!p.ok) {
75
+ setProblem(p.note || `That page answered ${p.status}.`);
76
+ return;
77
+ }
78
+ setPlan(
79
+ p.columns.map((column) => ({ column, include: true, key: fieldKeyFor(column) }))
80
+ );
81
+ setKeyField(fieldKeyFor(p.columns[0] || ""));
82
+ if (!targetLabel) setTargetLabel(p.title || "Scraped table");
83
+ setMessage(
84
+ `Read ${p.rowCount} rows and ${p.columns.length} columns` +
85
+ (p.tableCount && p.tableCount > 1 ? ` (of ${p.tableCount} tables on the page)` : "")
86
+ );
87
+ } catch (e) {
88
+ setProblem(e instanceof AutomationError ? e.message : "That page could not be read.");
89
+ } finally {
90
+ setReading(false);
91
+ }
92
+ }, [url, extract, tableIndex, targetLabel]);
93
+
94
+ const create = async () => {
95
+ setSaving(true);
96
+ setProblem("");
97
+ try {
98
+ const fieldMap: Record<string, string> = {};
99
+ for (const c of plan) if (c.include && c.key) fieldMap[c.column] = c.key;
100
+ const res = await createAutomation({
101
+ name,
102
+ kind,
103
+ schedule: { cron: "0 6 * * *", enabled: false },
104
+ config:
105
+ kind === "scrape_db"
106
+ ? { url, extract, tableIndex, fieldMap, keyField, targetLabel }
107
+ : { targetTable, fieldKey, urlField, maxPosts: 24, tier: "anonymous" },
108
+ });
109
+ await onCreated(res.automation.id);
110
+ } catch (e) {
111
+ setProblem(e instanceof AutomationError ? e.message : "That could not be created.");
112
+ } finally {
113
+ setSaving(false);
114
+ }
115
+ };
116
+
117
+ const canCreate =
118
+ !!name.trim() &&
119
+ (kind === "scrape_db"
120
+ ? !!url.trim() && plan.some((c) => c.include && c.key === keyField)
121
+ : !!targetTable && !!fieldKey);
122
+
123
+ return (
124
+ <div className="auto-create-pane">
125
+ <div className="auto-create-card">
126
+ <h1>New automation</h1>
127
+ <p className="auto-hint">
128
+ Pick what it does. Once it exists you configure it on the canvas, one step at a time.
129
+ </p>
130
+
131
+ {problem ? (
132
+ <div className="auto-banner is-error" role="alert">
133
+ {problem}
134
+ </div>
135
+ ) : null}
136
+ {message ? (
137
+ <div className="auto-banner is-ok" role="status">
138
+ {message}
139
+ </div>
140
+ ) : null}
141
+
142
+ <div className="auto-field">
143
+ <label htmlFor="auto-new-name">Name</label>
144
+ <input
145
+ id="auto-new-name"
146
+ className="auto-input"
147
+ value={name}
148
+ placeholder="S&P 500 companies"
149
+ onChange={(e) => setName(e.target.value)}
150
+ />
151
+ </div>
152
+
153
+ <div className="auto-kinds">
154
+ {kinds.map((k) => (
155
+ <label key={k.key} className={"auto-kind" + (kind === k.key ? " is-on" : "")}>
156
+ <input
157
+ type="radio"
158
+ name="auto-kind"
159
+ checked={kind === k.key}
160
+ onChange={() => setKind(k.key)}
161
+ />
162
+ <span>{k.label}</span>
163
+ </label>
164
+ ))}
165
+ </div>
166
+
167
+ {kind === "scrape_db" ? (
168
+ <>
169
+ <div className="auto-field">
170
+ <label htmlFor="auto-new-url">Page URL</label>
171
+ <div className="auto-row-inline">
172
+ <input
173
+ id="auto-new-url"
174
+ className="auto-input"
175
+ value={url}
176
+ placeholder="https://en.wikipedia.org/wiki/List_of_S%26P_500_companies"
177
+ onChange={(e) => setUrl(e.target.value)}
178
+ />
179
+ <button
180
+ type="button"
181
+ className="auto-btn"
182
+ disabled={!url.trim() || reading}
183
+ onClick={() => void readPage()}
184
+ >
185
+ {reading ? "Reading…" : "Read the page"}
186
+ </button>
187
+ </div>
188
+ <p className="auto-hint">
189
+ Public web pages only. Private, loopback and link-local addresses are refused β€”
190
+ including a public URL that redirects to one.
191
+ </p>
192
+ </div>
193
+ <div className="auto-field-row">
194
+ <div className="auto-field">
195
+ <label htmlFor="auto-new-extract">Read</label>
196
+ <select
197
+ id="auto-new-extract"
198
+ className="auto-input"
199
+ value={extract}
200
+ onChange={(e) => setExtract(e.target.value)}
201
+ >
202
+ <option value="table">An HTML table</option>
203
+ <option value="jsonld">Structured data (JSON-LD)</option>
204
+ </select>
205
+ </div>
206
+ {extract === "table" ? (
207
+ <div className="auto-field">
208
+ <label htmlFor="auto-new-tidx">Which table</label>
209
+ <input
210
+ id="auto-new-tidx"
211
+ className="auto-input"
212
+ type="number"
213
+ min={0}
214
+ value={tableIndex}
215
+ onChange={(e) => setTableIndex(Number(e.target.value) || 0)}
216
+ />
217
+ </div>
218
+ ) : null}
219
+ <div className="auto-field">
220
+ <label htmlFor="auto-new-tlabel">Database name</label>
221
+ <input
222
+ id="auto-new-tlabel"
223
+ className="auto-input"
224
+ value={targetLabel}
225
+ placeholder="S&P 500 companies"
226
+ onChange={(e) => setTargetLabel(e.target.value)}
227
+ />
228
+ </div>
229
+ </div>
230
+
231
+ {plan.length ? (
232
+ <div className="auto-map">
233
+ <h3>Columns</h3>
234
+ <p className="auto-hint">
235
+ Pick the key β€” the column that identifies a row. On every re-run, a row whose
236
+ key already exists is updated; a new key is inserted; a key that has stopped
237
+ appearing is counted and kept.
238
+ </p>
239
+ <div className="auto-drill-scroll">
240
+ <table className="auto-table">
241
+ <thead>
242
+ <tr>
243
+ <th>Use</th>
244
+ <th>Source column</th>
245
+ <th>Field key</th>
246
+ <th>Key</th>
247
+ {preview?.sample?.length ? <th>First value</th> : null}
248
+ </tr>
249
+ </thead>
250
+ <tbody>
251
+ {plan.map((c, i) => (
252
+ <tr key={c.column}>
253
+ <td>
254
+ <input
255
+ type="checkbox"
256
+ checked={c.include}
257
+ aria-label={`Include ${c.column}`}
258
+ onChange={(e) =>
259
+ setPlan((p) =>
260
+ p.map((x, j) =>
261
+ j === i ? { ...x, include: e.target.checked } : x
262
+ )
263
+ )
264
+ }
265
+ />
266
+ </td>
267
+ <td className="auto-cell-name">{c.column}</td>
268
+ <td>
269
+ <input
270
+ className="auto-input is-small"
271
+ value={c.key}
272
+ aria-label={`Field key for ${c.column}`}
273
+ onChange={(e) =>
274
+ setPlan((p) =>
275
+ p.map((x, j) =>
276
+ j === i ? { ...x, key: fieldKeyFor(e.target.value) } : x
277
+ )
278
+ )
279
+ }
280
+ />
281
+ </td>
282
+ <td>
283
+ <input
284
+ type="radio"
285
+ name="auto-new-keyfield"
286
+ checked={keyField === c.key && c.include}
287
+ disabled={!c.include}
288
+ aria-label={`Use ${c.column} as the key`}
289
+ onChange={() => setKeyField(c.key)}
290
+ />
291
+ </td>
292
+ {preview?.sample?.length ? (
293
+ <td className="auto-cell-sample">
294
+ {String(preview.sample[0]?.[c.column] ?? "")}
295
+ </td>
296
+ ) : null}
297
+ </tr>
298
+ ))}
299
+ </tbody>
300
+ </table>
301
+ </div>
302
+ </div>
303
+ ) : (
304
+ <p className="auto-note">Read the page to see what columns it offers.</p>
305
+ )}
306
+ </>
307
+ ) : (
308
+ <>
309
+ <div className="auto-field-row">
310
+ <div className="auto-field">
311
+ <label htmlFor="auto-new-table">Database</label>
312
+ <select
313
+ id="auto-new-table"
314
+ className="auto-input"
315
+ value={targetTable}
316
+ onChange={(e) => {
317
+ setTargetTable(e.target.value);
318
+ setFieldKey("");
319
+ setUrlField("");
320
+ }}
321
+ >
322
+ <option value="">Choose a database…</option>
323
+ {tables.map((t) => (
324
+ <option key={t.key} value={t.key}>
325
+ {t.label} ({t.rowCount} {t.rowCount === 1 ? "row" : "rows"})
326
+ </option>
327
+ ))}
328
+ </select>
329
+ </div>
330
+ <div className="auto-field">
331
+ <label htmlFor="auto-new-fieldkey">Automation column</label>
332
+ <select
333
+ id="auto-new-fieldkey"
334
+ className="auto-input"
335
+ value={fieldKey}
336
+ onChange={(e) => setFieldKey(e.target.value)}
337
+ >
338
+ <option value="">Choose a column…</option>
339
+ {(table?.fields || [])
340
+ .filter((f) => f.type === "automation")
341
+ .map((f) => (
342
+ <option key={f.key} value={f.key}>
343
+ {f.label}
344
+ </option>
345
+ ))}
346
+ </select>
347
+ </div>
348
+ <div className="auto-field">
349
+ <label htmlFor="auto-new-urlfield">Profile URL column</label>
350
+ <select
351
+ id="auto-new-urlfield"
352
+ className="auto-input"
353
+ value={urlField}
354
+ onChange={(e) => setUrlField(e.target.value)}
355
+ >
356
+ <option value="">The column the field is bound to</option>
357
+ {(table?.fields || []).map((f) => (
358
+ <option key={f.key} value={f.key}>
359
+ {f.label}
360
+ </option>
361
+ ))}
362
+ </select>
363
+ </div>
364
+ </div>
365
+ <p className="auto-hint">
366
+ It starts on the free anonymous rung. The canvas&rsquo;s HikerAPI step turns on the
367
+ paid one, which returns exact counts and full post data and works from a datacenter.
368
+ </p>
369
+ {table && !(table.fields || []).some((f) => f.type === "automation") ? (
370
+ <p className="auto-note">
371
+ That database has no automation column yet. Add one from the grid&rsquo;s column
372
+ menu, then choose it here.
373
+ </p>
374
+ ) : null}
375
+ </>
376
+ )}
377
+
378
+ <div className="auto-head-actions">
379
+ <button
380
+ type="button"
381
+ className="auto-btn is-primary"
382
+ disabled={!canCreate || saving}
383
+ onClick={() => void create()}
384
+ >
385
+ {saving ? "Creating…" : "Create"}
386
+ </button>
387
+ <button type="button" className="auto-btn" onClick={onCancel}>
388
+ Cancel
389
+ </button>
390
+ </div>
391
+ </div>
392
+ </div>
393
+ );
394
+ }
web/src/automation/AutomationDetail.tsx ADDED
@@ -0,0 +1,746 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // automation/AutomationDetail.tsx β€” one automation, as a flow you can walk.
3
+ //
4
+ // THE SHAPE, and what changed from the stacked-cards editor it replaces (R5):
5
+ // the automation is now a CANVAS of nodes, and the right-hand panel shows the
6
+ // configuration of whichever node you clicked. The two halves answer different
7
+ // questions and neither used to be answerable at a glance β€” the canvas answers
8
+ // "what does this thing do, in what order, and which step went wrong last
9
+ // night", the panel answers "what exactly is step 3 configured to do".
10
+ //
11
+ // ONE CONTROL PER FACT. A node's SWITCH is the only way to turn that step on or
12
+ // off; the panel never carries a second checkbox for the same flag. The schedule
13
+ // panel therefore edits the cron STRING and nothing else β€” whether the schedule
14
+ // is live is the Trigger node's switch. Two controls for one boolean is how a UI
15
+ // starts disagreeing with itself.
16
+ //
17
+ // EVERY COUNT DRILLS TO ROWS. A run that says "412 updated" opens the 412
18
+ // ([[no-unverifiable-aggregates]]) β€” a number with no way back to its records is
19
+ // what this codebase treats as a defect rather than a summary.
20
+ // ---------------------------------------------------------------------------
21
+ import { useCallback, useEffect, useMemo, useState } from "react";
22
+
23
+ import AutomationCanvas from "./AutomationCanvas";
24
+ import type {
25
+ Automation,
26
+ AutomationKind,
27
+ GraphNode,
28
+ RunEntry,
29
+ RunRows,
30
+ SourcePreview,
31
+ UserTable,
32
+ } from "./automationApi";
33
+ import {
34
+ AutomationError,
35
+ COUNT_LABELS,
36
+ deleteAutomation,
37
+ fieldKeyFor,
38
+ listTables,
39
+ patchAutomation,
40
+ previewSource,
41
+ runAutomation,
42
+ runRows,
43
+ toggleNode,
44
+ } from "./automationApi";
45
+
46
+ interface Props {
47
+ automation: Automation;
48
+ kinds: { key: AutomationKind; label: string }[];
49
+ cronPresets: { cron: string; label: string }[];
50
+ hikerReady: boolean;
51
+ onSaved: (id?: string) => void | Promise<void>;
52
+ onDeleted: () => void | Promise<void>;
53
+ }
54
+
55
+ interface ColumnPlan {
56
+ column: string;
57
+ include: boolean;
58
+ key: string;
59
+ }
60
+
61
+ export default function AutomationDetail({
62
+ automation,
63
+ kinds,
64
+ cronPresets,
65
+ hikerReady,
66
+ onSaved,
67
+ onDeleted,
68
+ }: Props) {
69
+ const cfg = (automation.config || {}) as Record<string, string | number | boolean>;
70
+ const kind = automation.kind;
71
+
72
+ const [name, setName] = useState(automation.name || "");
73
+ const [cron, setCron] = useState(automation.schedule?.cron || "0 6 * * *");
74
+ const [message, setMessage] = useState("");
75
+ const [problem, setProblem] = useState("");
76
+ const [saving, setSaving] = useState(false);
77
+ const [touched, setTouched] = useState(false);
78
+ const [busyNode, setBusyNode] = useState("");
79
+ const [selected, setSelected] = useState("");
80
+
81
+ // --- scrape_db half
82
+ const [url, setUrl] = useState(String(cfg.url || ""));
83
+ const [extract, setExtract] = useState(String(cfg.extract || "table"));
84
+ const [tableIndex, setTableIndex] = useState(Number(cfg.tableIndex || 0));
85
+ const [targetLabel, setTargetLabel] = useState(String(cfg.targetLabel || ""));
86
+ const [preview, setPreview] = useState<SourcePreview | null>(null);
87
+ const [reading, setReading] = useState(false);
88
+ const [plan, setPlan] = useState<ColumnPlan[]>(() =>
89
+ Object.entries((automation.config as { fieldMap?: Record<string, string> })?.fieldMap || {})
90
+ .map(([column, key]) => ({ column, include: true, key }))
91
+ );
92
+ const [keyField, setKeyField] = useState(String(cfg.keyField || ""));
93
+
94
+ // --- field_instagram half
95
+ const [tables, setTables] = useState<UserTable[]>([]);
96
+ const [targetTable, setTargetTable] = useState(String(cfg.targetTable || ""));
97
+ const [fieldKey, setFieldKey] = useState(String(cfg.fieldKey || ""));
98
+ const [urlField, setUrlField] = useState(String(cfg.urlField || ""));
99
+ const [maxPosts, setMaxPosts] = useState(Number(cfg.maxPosts || 24));
100
+
101
+ // --- run history drill
102
+ const [drill, setDrill] = useState<RunRows | null>(null);
103
+ const [drillFor, setDrillFor] = useState("");
104
+
105
+ useEffect(() => {
106
+ const ac = new AbortController();
107
+ listTables(ac.signal)
108
+ .then((r) => setTables(r.tables))
109
+ .catch(() => setTables([]));
110
+ return () => ac.abort();
111
+ }, []);
112
+
113
+ const table = tables.find((t) => t.key === targetTable) || null;
114
+ const node: GraphNode | null =
115
+ (automation.graph?.nodes || []).find((n) => n.id === selected) || null;
116
+
117
+ const edit = <T,>(set: (v: T) => void) => (v: T) => {
118
+ setTouched(true);
119
+ set(v);
120
+ };
121
+
122
+ const readPage = useCallback(async () => {
123
+ setReading(true);
124
+ setProblem("");
125
+ try {
126
+ const p = await previewSource(url, extract, tableIndex);
127
+ setPreview(p);
128
+ if (!p.ok) {
129
+ setProblem(p.note || `That page answered ${p.status}.`);
130
+ return;
131
+ }
132
+ // Seed the plan from what the page ACTUALLY offers, keeping any mapping the
133
+ // user already made for a column that is still there β€” re-reading a page
134
+ // must not throw away the work of mapping it.
135
+ setPlan((prev) => {
136
+ const had = new Map(prev.map((c) => [c.column, c]));
137
+ return p.columns.map((column) => {
138
+ const before = had.get(column);
139
+ return {
140
+ column,
141
+ include: before ? before.include : true,
142
+ key: before ? before.key : fieldKeyFor(column),
143
+ };
144
+ });
145
+ });
146
+ setKeyField((k) =>
147
+ k && p.columns.some((c) => fieldKeyFor(c) === k) ? k : fieldKeyFor(p.columns[0] || "")
148
+ );
149
+ if (!targetLabel) setTargetLabel(p.title || "Scraped table");
150
+ setTouched(true);
151
+ setMessage(
152
+ `Read ${p.rowCount} rows and ${p.columns.length} columns` +
153
+ (p.tableCount && p.tableCount > 1 ? ` (of ${p.tableCount} tables on the page)` : "")
154
+ );
155
+ } catch (e) {
156
+ setProblem(e instanceof AutomationError ? e.message : "That page could not be read.");
157
+ } finally {
158
+ setReading(false);
159
+ }
160
+ }, [url, extract, tableIndex, targetLabel]);
161
+
162
+ /**
163
+ * ⚠ The switch flags (`tier`, `noFallback`, `dryRun`) are DELIBERATELY absent.
164
+ * They are node switches, not panel fields, and the server keeps the stored
165
+ * value for any flag a config omits β€” so a Save from here can never quietly
166
+ * turn the paid rung off. (`clean_config`'s `flag()`, asserted in section N.)
167
+ */
168
+ const buildConfig = (): Record<string, unknown> => {
169
+ if (kind === "scrape_db") {
170
+ const fieldMap: Record<string, string> = {};
171
+ for (const c of plan) if (c.include && c.key) fieldMap[c.column] = c.key;
172
+ return {
173
+ url,
174
+ extract,
175
+ tableIndex,
176
+ fieldMap,
177
+ keyField,
178
+ targetTable: String(cfg.targetTable || ""),
179
+ targetLabel,
180
+ };
181
+ }
182
+ return { targetTable, fieldKey, urlField, maxPosts };
183
+ };
184
+
185
+ const persist = async (announce = true) => {
186
+ const res = await patchAutomation(automation.id, {
187
+ name,
188
+ kind,
189
+ config: buildConfig(),
190
+ schedule: { cron, enabled: !!automation.schedule?.enabled },
191
+ });
192
+ setTouched(false);
193
+ if (announce) setMessage("Saved.");
194
+ return res.automation.id;
195
+ };
196
+
197
+ const save = async () => {
198
+ setSaving(true);
199
+ setProblem("");
200
+ setMessage("");
201
+ try {
202
+ const id = await persist();
203
+ await onSaved(id);
204
+ } catch (e) {
205
+ setProblem(e instanceof AutomationError ? e.message : "That could not be saved.");
206
+ } finally {
207
+ setSaving(false);
208
+ }
209
+ };
210
+
211
+ /**
212
+ * A node switch is immediate β€” a switch that needs a separate Save is not a
213
+ * switch. Unsaved panel edits are persisted FIRST rather than being discarded
214
+ * by the reload that follows, which is the one way this could lose work.
215
+ */
216
+ const flip = async (nodeId: string) => {
217
+ setBusyNode(nodeId);
218
+ setProblem("");
219
+ setMessage("");
220
+ try {
221
+ if (touched) await persist(false);
222
+ await toggleNode(automation.id, nodeId);
223
+ await onSaved(automation.id);
224
+ } catch (e) {
225
+ setProblem(e instanceof AutomationError ? e.message : "That step was not changed.");
226
+ } finally {
227
+ setBusyNode("");
228
+ }
229
+ };
230
+
231
+ const start = async () => {
232
+ setProblem("");
233
+ try {
234
+ await runAutomation(automation.id);
235
+ setMessage("Started. The node dots follow it.");
236
+ await onSaved(automation.id);
237
+ } catch (e) {
238
+ setProblem(e instanceof AutomationError ? e.message : "It did not start.");
239
+ }
240
+ };
241
+
242
+ const remove = async () => {
243
+ setProblem("");
244
+ try {
245
+ await deleteAutomation(automation.id);
246
+ await onDeleted();
247
+ } catch (e) {
248
+ setProblem(e instanceof AutomationError ? e.message : "It was not deleted.");
249
+ }
250
+ };
251
+
252
+ const openDrill = async (entry: RunEntry) => {
253
+ if (drillFor === entry.ts) {
254
+ setDrill(null);
255
+ setDrillFor("");
256
+ return;
257
+ }
258
+ try {
259
+ const rows = await runRows(automation.id);
260
+ setDrill(rows);
261
+ setDrillFor(entry.ts);
262
+ } catch (e) {
263
+ setProblem(e instanceof AutomationError ? e.message : "Those rows could not be read.");
264
+ }
265
+ };
266
+
267
+ const presetMatch = useMemo(
268
+ () => cronPresets.find((p) => p.cron === cron)?.cron || "",
269
+ [cronPresets, cron]
270
+ );
271
+ const state = automation.running ? "running" : automation.status?.state || "idle";
272
+
273
+ return (
274
+ <div className="auto-detail">
275
+ <header className="auto-head">
276
+ <div className="auto-head-title">
277
+ <input
278
+ className="auto-name"
279
+ value={name}
280
+ placeholder="Name this automation"
281
+ aria-label="Automation name"
282
+ onChange={(e) => edit(setName)(e.target.value)}
283
+ />
284
+ <span className={`auto-chip is-${state}`}>
285
+ {automation.running ? "Running" : state}
286
+ </span>
287
+ <span className="auto-kindtag">
288
+ {kinds.find((k) => k.key === kind)?.label || kind}
289
+ </span>
290
+ </div>
291
+ <div className="auto-head-actions">
292
+ <button
293
+ type="button"
294
+ className="auto-btn"
295
+ disabled={!!automation.running}
296
+ onClick={() => void start()}
297
+ >
298
+ {automation.running ? "Running…" : "Run now"}
299
+ </button>
300
+ <button
301
+ type="button"
302
+ className="auto-btn is-primary"
303
+ disabled={saving || !name.trim()}
304
+ onClick={() => void save()}
305
+ >
306
+ {saving ? "Saving…" : "Save"}
307
+ </button>
308
+ <button type="button" className="auto-btn is-danger" onClick={() => void remove()}>
309
+ Delete
310
+ </button>
311
+ </div>
312
+ </header>
313
+
314
+ {problem ? (
315
+ <div className="auto-banner is-error" role="alert">
316
+ {problem}
317
+ </div>
318
+ ) : null}
319
+ {message ? (
320
+ <div className="auto-banner is-ok" role="status">
321
+ {message}
322
+ </div>
323
+ ) : null}
324
+
325
+ <div className="auto-work">
326
+ <AutomationCanvas
327
+ graph={automation.graph}
328
+ selected={selected}
329
+ onSelect={setSelected}
330
+ onToggle={(id) => void flip(id)}
331
+ busyNode={busyNode}
332
+ nextRunAt={automation.nextRunAt}
333
+ />
334
+
335
+ <aside className="auto-panel" aria-label={node ? `${node.title} settings` : "Run history"}>
336
+ {node ? (
337
+ <>
338
+ <div className="auto-panel-head">
339
+ <h2>{node.title}</h2>
340
+ <button
341
+ type="button"
342
+ className="auto-panel-close"
343
+ aria-label="Back to run history"
344
+ title="Back to run history"
345
+ onClick={() => setSelected("")}
346
+ >
347
+ <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
348
+ <path
349
+ d="M4 4l8 8M12 4l-8 8"
350
+ stroke="currentColor"
351
+ strokeWidth="1.5"
352
+ strokeLinecap="round"
353
+ />
354
+ </svg>
355
+ </button>
356
+ </div>
357
+ {!node.enabled ? (
358
+ <p className="auto-note is-off">
359
+ This step is switched off. Its card on the canvas carries the switch that turns
360
+ it back on.
361
+ </p>
362
+ ) : null}
363
+
364
+ {node.panel === "schedule" ? (
365
+ <>
366
+ <div className="auto-field">
367
+ <label htmlFor="auto-preset">Schedule</label>
368
+ <select
369
+ id="auto-preset"
370
+ className="auto-input"
371
+ value={presetMatch}
372
+ onChange={(e) => e.target.value && edit(setCron)(e.target.value)}
373
+ >
374
+ <option value="">Custom…</option>
375
+ {cronPresets.map((p) => (
376
+ <option key={p.cron} value={p.cron}>
377
+ {p.label}
378
+ </option>
379
+ ))}
380
+ </select>
381
+ </div>
382
+ <div className="auto-field">
383
+ <label htmlFor="auto-cron">Cron (minute hour day month weekday)</label>
384
+ <input
385
+ id="auto-cron"
386
+ className="auto-input is-mono"
387
+ value={cron}
388
+ onChange={(e) => edit(setCron)(e.target.value)}
389
+ />
390
+ </div>
391
+ <p className="auto-hint">
392
+ {automation.nextRunAt
393
+ ? `Next run ${automation.nextRunAt}.`
394
+ : automation.schedule?.enabled
395
+ ? "Schedules start from the moment they are switched on β€” turning on a daily job after today's time does not fire it immediately."
396
+ : "Not scheduled. It still runs when you press Run now, and the node's switch turns the schedule on."}
397
+ </p>
398
+ </>
399
+ ) : null}
400
+
401
+ {node.panel === "source" && kind === "scrape_db" ? (
402
+ <>
403
+ <div className="auto-field">
404
+ <label htmlFor="auto-url">Page URL</label>
405
+ <input
406
+ id="auto-url"
407
+ className="auto-input"
408
+ value={url}
409
+ placeholder="https://en.wikipedia.org/wiki/List_of_S%26P_500_companies"
410
+ onChange={(e) => edit(setUrl)(e.target.value)}
411
+ />
412
+ </div>
413
+ <button
414
+ type="button"
415
+ className="auto-btn"
416
+ disabled={!url.trim() || reading}
417
+ onClick={() => void readPage()}
418
+ >
419
+ {reading ? "Reading…" : "Read the page"}
420
+ </button>
421
+ <div className="auto-field">
422
+ <label htmlFor="auto-extract">Read</label>
423
+ <select
424
+ id="auto-extract"
425
+ className="auto-input"
426
+ value={extract}
427
+ onChange={(e) => edit(setExtract)(e.target.value)}
428
+ >
429
+ <option value="table">An HTML table</option>
430
+ <option value="jsonld">Structured data (JSON-LD)</option>
431
+ </select>
432
+ </div>
433
+ {extract === "table" ? (
434
+ <div className="auto-field">
435
+ <label htmlFor="auto-tidx">Which table</label>
436
+ <input
437
+ id="auto-tidx"
438
+ className="auto-input"
439
+ type="number"
440
+ min={0}
441
+ value={tableIndex}
442
+ onChange={(e) => edit(setTableIndex)(Number(e.target.value) || 0)}
443
+ />
444
+ </div>
445
+ ) : null}
446
+ <p className="auto-hint">
447
+ Public web pages only. Private, loopback and link-local addresses are refused
448
+ β€” including a public URL that redirects to one.
449
+ </p>
450
+ </>
451
+ ) : null}
452
+
453
+ {node.panel === "columns" ? (
454
+ plan.length ? (
455
+ <>
456
+ <p className="auto-hint">
457
+ Pick the key β€” the column that identifies a row. On every re-run, a row
458
+ whose key already exists is updated; a new key is inserted; a key that has
459
+ stopped appearing is counted and kept.
460
+ </p>
461
+ <div className="auto-panel-scroll">
462
+ <table className="auto-table">
463
+ <thead>
464
+ <tr>
465
+ <th>Use</th>
466
+ <th>Source column</th>
467
+ <th>Field key</th>
468
+ <th>Key</th>
469
+ </tr>
470
+ </thead>
471
+ <tbody>
472
+ {plan.map((c, i) => (
473
+ <tr key={c.column}>
474
+ <td>
475
+ <input
476
+ type="checkbox"
477
+ checked={c.include}
478
+ aria-label={`Include ${c.column}`}
479
+ onChange={(e) =>
480
+ edit(setPlan)(
481
+ plan.map((x, j) =>
482
+ j === i ? { ...x, include: e.target.checked } : x
483
+ )
484
+ )
485
+ }
486
+ />
487
+ </td>
488
+ <td className="auto-cell-name">{c.column}</td>
489
+ <td>
490
+ <input
491
+ className="auto-input is-small"
492
+ value={c.key}
493
+ aria-label={`Field key for ${c.column}`}
494
+ onChange={(e) =>
495
+ edit(setPlan)(
496
+ plan.map((x, j) =>
497
+ j === i
498
+ ? { ...x, key: fieldKeyFor(e.target.value) }
499
+ : x
500
+ )
501
+ )
502
+ }
503
+ />
504
+ </td>
505
+ <td>
506
+ <input
507
+ type="radio"
508
+ name="auto-keyfield"
509
+ checked={keyField === c.key && c.include}
510
+ disabled={!c.include}
511
+ aria-label={`Use ${c.column} as the key`}
512
+ onChange={() => edit(setKeyField)(c.key)}
513
+ />
514
+ </td>
515
+ </tr>
516
+ ))}
517
+ </tbody>
518
+ </table>
519
+ </div>
520
+ {preview?.sample?.length ? (
521
+ <p className="auto-hint">
522
+ First row read: {Object.values(preview.sample[0]).slice(0, 4).join(" Β· ")}
523
+ </p>
524
+ ) : null}
525
+ </>
526
+ ) : (
527
+ <p className="auto-note">
528
+ Open the Fetch step and read the page to see what columns it offers.
529
+ </p>
530
+ )
531
+ ) : null}
532
+
533
+ {node.panel === "source" && kind === "field_instagram" ? (
534
+ <>
535
+ <div className="auto-field">
536
+ <label htmlFor="auto-table">Database</label>
537
+ <select
538
+ id="auto-table"
539
+ className="auto-input"
540
+ value={targetTable}
541
+ onChange={(e) => {
542
+ edit(setTargetTable)(e.target.value);
543
+ setFieldKey("");
544
+ setUrlField("");
545
+ }}
546
+ >
547
+ <option value="">Choose a database…</option>
548
+ {tables.map((t) => (
549
+ <option key={t.key} value={t.key}>
550
+ {t.label} ({t.rowCount} {t.rowCount === 1 ? "row" : "rows"})
551
+ </option>
552
+ ))}
553
+ </select>
554
+ </div>
555
+ <div className="auto-field">
556
+ <label htmlFor="auto-urlfield">Profile URL column</label>
557
+ <select
558
+ id="auto-urlfield"
559
+ className="auto-input"
560
+ value={urlField}
561
+ onChange={(e) => edit(setUrlField)(e.target.value)}
562
+ >
563
+ <option value="">The column the field is bound to</option>
564
+ {(table?.fields || []).map((f) => (
565
+ <option key={f.key} value={f.key}>
566
+ {f.label}
567
+ </option>
568
+ ))}
569
+ </select>
570
+ </div>
571
+ <div className="auto-field">
572
+ <label htmlFor="auto-fieldkey">Automation column</label>
573
+ <select
574
+ id="auto-fieldkey"
575
+ className="auto-input"
576
+ value={fieldKey}
577
+ onChange={(e) => edit(setFieldKey)(e.target.value)}
578
+ >
579
+ <option value="">Choose a column…</option>
580
+ {(table?.fields || [])
581
+ .filter((f) => f.type === "automation")
582
+ .map((f) => (
583
+ <option key={f.key} value={f.key}>
584
+ {f.label}
585
+ </option>
586
+ ))}
587
+ </select>
588
+ </div>
589
+ {table && !(table.fields || []).some((f) => f.type === "automation") ? (
590
+ <p className="auto-note">
591
+ That database has no automation column yet. Add one from the grid&rsquo;s
592
+ column menu, then choose it here.
593
+ </p>
594
+ ) : null}
595
+ </>
596
+ ) : null}
597
+
598
+ {node.panel === "capture" ? (
599
+ <>
600
+ <div className="auto-field">
601
+ <label htmlFor="auto-maxposts">Posts per pull</label>
602
+ <input
603
+ id="auto-maxposts"
604
+ className="auto-input"
605
+ type="number"
606
+ min={1}
607
+ max={200}
608
+ value={maxPosts}
609
+ onChange={(e) => edit(setMaxPosts)(Number(e.target.value) || 24)}
610
+ />
611
+ </div>
612
+ <h3>HikerAPI β€” the paid rung</h3>
613
+ <p className="auto-hint">
614
+ Exact follower counts and post-level data, and it works from a datacenter.
615
+ Roughly $0.0006 a request. Its node&rsquo;s switch turns it on.
616
+ {hikerReady
617
+ ? " A key is configured on this deployment."
618
+ : " No key is configured on this deployment yet, so it will report itself blocked and the anonymous rung will answer instead."}
619
+ </p>
620
+ <h3>Anonymous β€” the free rung</h3>
621
+ <p className="auto-hint">
622
+ No login and no credentials. Instagram blocks datacenter addresses and has
623
+ closed most of its anonymous surface, so this rung is honest rather than
624
+ reliable: counts come from the page&rsquo;s own abbreviations (204K, not
625
+ 204,312) and are marked approximate. Turning it off means{" "}
626
+ <strong>exact numbers or nothing</strong> β€” a run reports blocked rather than
627
+ quietly writing a rounded number.
628
+ </p>
629
+ <p className="auto-hint">
630
+ A pull reports what it actually got: <strong>ok</strong> (profile and posts),{" "}
631
+ <strong>partial</strong> (profile only), or <strong>blocked</strong>. It never
632
+ reports success on nothing.
633
+ </p>
634
+ </>
635
+ ) : null}
636
+
637
+ {node.panel === "write" ? (
638
+ <>
639
+ {kind === "scrape_db" ? (
640
+ <div className="auto-field">
641
+ <label htmlFor="auto-tlabel">Database name</label>
642
+ <input
643
+ id="auto-tlabel"
644
+ className="auto-input"
645
+ value={targetLabel}
646
+ placeholder="S&P 500 companies"
647
+ onChange={(e) => edit(setTargetLabel)(e.target.value)}
648
+ />
649
+ </div>
650
+ ) : (
651
+ <p className="auto-hint">
652
+ Each pull appends a timestamped row to <code>ut_ig_snapshots</code> and, for
653
+ every post, to <code>ut_ig_post_snapshots</code> β€” so the history is a time
654
+ series you can filter by date rather than a single current value.{" "}
655
+ <code>ut_ig_posts</code> holds one row per post, ever.
656
+ </p>
657
+ )}
658
+ <p className="auto-hint">
659
+ Turning this step off makes the automation a <strong>dry run</strong>: it
660
+ reads everything and reports exactly what it would have written, without
661
+ creating or changing a single row.
662
+ </p>
663
+ <p className="auto-hint">
664
+ A row that stops appearing at the source is counted and kept, never deleted.
665
+ </p>
666
+ </>
667
+ ) : null}
668
+ </>
669
+ ) : (
670
+ <>
671
+ <div className="auto-panel-head">
672
+ <h2>Run history</h2>
673
+ </div>
674
+ {!automation.runs?.length ? (
675
+ <p className="auto-note">
676
+ It has not run yet. Press Run now, or switch on the Trigger step.
677
+ </p>
678
+ ) : (
679
+ <ol className="auto-runs">
680
+ {automation.runs.map((r) => (
681
+ <li key={r.ts} className={"auto-run is-" + (r.ok ? "ok" : "error")}>
682
+ <button
683
+ type="button"
684
+ className="auto-run-head"
685
+ onClick={() => void openDrill(r)}
686
+ aria-expanded={drillFor === r.ts}
687
+ >
688
+ <span className="auto-run-ts">{r.ts.replace("T", " ")}</span>
689
+ <span className="auto-run-summary">{r.summary}</span>
690
+ </button>
691
+ <div className="auto-counts">
692
+ {COUNT_LABELS.filter(([k]) => typeof r.counts?.[k] === "number").map(
693
+ ([k, label]) => (
694
+ <span
695
+ key={k}
696
+ className={
697
+ "auto-count" + (k === "capped" && r.counts[k] ? " is-warn" : "")
698
+ }
699
+ >
700
+ <b>{r.counts[k]}</b> {label}
701
+ </span>
702
+ )
703
+ )}
704
+ </div>
705
+ {drillFor === r.ts && drill ? (
706
+ <div className="auto-drill">
707
+ <p className="auto-hint">
708
+ The rows this run touched in {drill.label}
709
+ {drill.truncated ? " (first 200)" : ""}.
710
+ </p>
711
+ <div className="auto-drill-scroll">
712
+ <table className="auto-table">
713
+ <thead>
714
+ <tr>
715
+ {drill.fields.map((f) => (
716
+ <th key={f.key}>{f.label}</th>
717
+ ))}
718
+ </tr>
719
+ </thead>
720
+ <tbody>
721
+ {drill.rows.slice(0, 50).map((row) => (
722
+ <tr key={String(row.id)}>
723
+ {drill.fields.map((f) => (
724
+ <td key={f.key}>{String(row[f.key] ?? "")}</td>
725
+ ))}
726
+ </tr>
727
+ ))}
728
+ </tbody>
729
+ </table>
730
+ </div>
731
+ </div>
732
+ ) : null}
733
+ </li>
734
+ ))}
735
+ </ol>
736
+ )}
737
+ <p className="auto-hint">
738
+ Click any step on the canvas to see and change what it does.
739
+ </p>
740
+ </>
741
+ )}
742
+ </aside>
743
+ </div>
744
+ </div>
745
+ );
746
+ }
web/src/automation/AutomationSurface.tsx CHANGED
@@ -16,7 +16,8 @@
16
  import type { KeyboardEvent as ReactKeyboardEvent } from "react";
17
  import { useCallback, useEffect, useRef, useState } from "react";
18
 
19
- import AutomationEditor from "./AutomationEditor";
 
20
  import type { Automation, AutomationList } from "./automationApi";
21
  import {
22
  AutomationError,
@@ -240,30 +241,39 @@ export default function AutomationSurface() {
240
  </div>
241
  ) : null}
242
 
243
- {creating || active ? (
244
- <AutomationEditor
245
- key={active?.id || "new"}
 
 
 
 
 
 
 
 
 
 
246
  automation={active}
247
  kinds={data?.kinds || []}
248
  cronPresets={data?.cronPresets || []}
 
249
  onSaved={async (id) => {
250
- setCreating(false);
251
  const next = await load();
252
  if (id && next) setActiveId(id);
253
  }}
254
  onDeleted={async () => {
255
  setActiveId("");
256
- setCreating(false);
257
  await load();
258
  }}
259
- onCancel={() => setCreating(false)}
260
  />
261
  ) : (
262
  <div className="auto-empty">
263
  <h1>Automations</h1>
264
  <p>
265
  An automation is a job this workspace runs for you β€” on demand, or on a
266
- schedule. Pick one on the left, or create a new one.
 
267
  </p>
268
  <ul className="auto-empty-kinds">
269
  <li>
@@ -274,9 +284,10 @@ export default function AutomationSurface() {
274
  </li>
275
  <li>
276
  <strong>Instagram profile column.</strong> For every record carrying a
277
- public profile URL, read what is anonymously available and write the result
278
- into an automation column, with each pull timestamped so the history is
279
- filterable by date.
 
280
  </li>
281
  </ul>
282
  </div>
 
16
  import type { KeyboardEvent as ReactKeyboardEvent } from "react";
17
  import { useCallback, useEffect, useRef, useState } from "react";
18
 
19
+ import AutomationCreate from "./AutomationCreate";
20
+ import AutomationDetail from "./AutomationDetail";
21
  import type { Automation, AutomationList } from "./automationApi";
22
  import {
23
  AutomationError,
 
241
  </div>
242
  ) : null}
243
 
244
+ {creating ? (
245
+ <AutomationCreate
246
+ kinds={data?.kinds || []}
247
+ onCreated={async (id) => {
248
+ setCreating(false);
249
+ const next = await load();
250
+ if (id && next) setActiveId(id);
251
+ }}
252
+ onCancel={() => setCreating(false)}
253
+ />
254
+ ) : active ? (
255
+ <AutomationDetail
256
+ key={active.id}
257
  automation={active}
258
  kinds={data?.kinds || []}
259
  cronPresets={data?.cronPresets || []}
260
+ hikerReady={!!data?.hikerReady}
261
  onSaved={async (id) => {
 
262
  const next = await load();
263
  if (id && next) setActiveId(id);
264
  }}
265
  onDeleted={async () => {
266
  setActiveId("");
 
267
  await load();
268
  }}
 
269
  />
270
  ) : (
271
  <div className="auto-empty">
272
  <h1>Automations</h1>
273
  <p>
274
  An automation is a job this workspace runs for you β€” on demand, or on a
275
+ schedule. Each one is a flow: a trigger, the steps it walks, and the database
276
+ it writes. Pick one on the left, or create a new one.
277
  </p>
278
  <ul className="auto-empty-kinds">
279
  <li>
 
284
  </li>
285
  <li>
286
  <strong>Instagram profile column.</strong> For every record carrying a
287
+ public profile URL, read the profile β€” exactly, through HikerAPI, or
288
+ approximately on the free anonymous rung β€” and append a timestamped row per
289
+ pull, so followers and post engagement become a series you can filter by
290
+ date rather than a single current number.
291
  </li>
292
  </ul>
293
  </div>
web/src/automation/automationApi.ts CHANGED
@@ -18,12 +18,57 @@ import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, signal } from "../apiContract"
18
 
19
  export type AutomationKind = "scrape_db" | "field_instagram";
20
  export type RunState = "idle" | "running" | "ok" | "error" | "partial";
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
21
 
22
  export interface RunEntry {
23
  ts: string;
24
  ok: boolean;
25
  summary: string;
26
  counts: Record<string, number>;
 
 
27
  affected?: string[];
28
  }
29
 
@@ -39,12 +84,19 @@ export interface Automation {
39
  createdBy?: string;
40
  nextRunAt?: string;
41
  running?: boolean;
 
42
  }
43
 
44
  export interface AutomationList {
45
  automations: Automation[];
46
  kinds: { key: AutomationKind; label: string }[];
47
  cronPresets: { cron: string; label: string }[];
 
 
 
 
 
 
48
  storeAvailable: boolean;
49
  }
50
 
@@ -142,6 +194,24 @@ export function runAutomation(id: string): Promise<{ started: string }> {
142
  return send(`/automations/${encodeURIComponent(id)}/run`, { method: "POST" });
143
  }
144
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
145
  export function getAutomation(id: string): Promise<{ automation: Automation }> {
146
  return send(`/automations/${encodeURIComponent(id)}`);
147
  }
@@ -192,7 +262,12 @@ export const COUNT_LABELS: [string, string][] = [
192
  ["unchanged", "Unchanged"],
193
  ["orphans", "No longer on the page (kept)"],
194
  ["duplicates", "Duplicate keys"],
195
- ["skipped", "Skipped"],
 
 
 
 
 
196
  ["source_rows", "Rows read"],
197
  ["profiles", "Profiles"],
198
  ["ok", "Read in full"],
@@ -203,6 +278,7 @@ export const COUNT_LABELS: [string, string][] = [
203
  ["partial", "Profile only"],
204
  ["blocked", "Blocked"],
205
  ["error", "Errors"],
 
206
  ["posts", "Posts"],
207
  ["new_posts", "New posts"],
208
  ];
 
18
 
19
  export type AutomationKind = "scrape_db" | "field_instagram";
20
  export type RunState = "idle" | "running" | "ok" | "error" | "partial";
21
+ export type CaptureTier = "anonymous" | "hiker";
22
+
23
+ /**
24
+ * A node's dot. Deliberately WIDER than `RunState` β€” a single step can be
25
+ * `blocked` (a rung refused) or `skipped` (a switch is off) in ways a whole run
26
+ * cannot, and folding those into `partial` would throw away the only thing the
27
+ * dot is there to say.
28
+ */
29
+ export type NodeState = "idle" | "ok" | "partial" | "error" | "blocked" | "skipped";
30
+
31
+ /**
32
+ * ⚠ THE GRAPH IS THE SERVER'S, not this client's. `engine.graph()` derives it
33
+ * from the definition, in the same module that RUNS the steps β€” so the canvas
34
+ * cannot draw a step the engine stopped executing. This file only types it and
35
+ * `canvasLayout.ts` only positions it; nothing here decides what the nodes are.
36
+ * (Same rule as `cronPresets` and `kinds`, for the same reason.)
37
+ */
38
+ export interface GraphNode {
39
+ id: string;
40
+ kind: "trigger" | "source" | "capture" | "branch" | "write";
41
+ title: string;
42
+ subtitle: string;
43
+ detail: string;
44
+ col: number;
45
+ row: number;
46
+ /** Which config panel this node opens. */
47
+ panel: string;
48
+ enabled: boolean;
49
+ /** Non-empty = this node has a REAL switch. Empty = it is always on, by nature. */
50
+ toggle: string;
51
+ status: NodeState;
52
+ }
53
+
54
+ export interface GraphEdge {
55
+ from: string;
56
+ to: string;
57
+ label: string;
58
+ }
59
+
60
+ export interface AutomationGraph {
61
+ nodes: GraphNode[];
62
+ edges: GraphEdge[];
63
+ }
64
 
65
  export interface RunEntry {
66
  ts: string;
67
  ok: boolean;
68
  summary: string;
69
  counts: Record<string, number>;
70
+ /** Per-node outcomes, MEASURED as the run walked. Absent on runs stored before W19-C. */
71
+ steps?: Record<string, NodeState>;
72
  affected?: string[];
73
  }
74
 
 
84
  createdBy?: string;
85
  nextRunAt?: string;
86
  running?: boolean;
87
+ graph: AutomationGraph;
88
  }
89
 
90
  export interface AutomationList {
91
  automations: Automation[];
92
  kinds: { key: AutomationKind; label: string }[];
93
  cronPresets: { cron: string; label: string }[];
94
+ /**
95
+ * Is `AIOS_HIKERAPI_KEY` configured on the server? A BOOLEAN, never the key β€”
96
+ * the surface needs to say "the paid rung is not configured" honestly rather
97
+ * than offering a tier that will silently refuse.
98
+ */
99
+ hikerReady: boolean;
100
  storeAvailable: boolean;
101
  }
102
 
 
194
  return send(`/automations/${encodeURIComponent(id)}/run`, { method: "POST" });
195
  }
196
 
197
+ /**
198
+ * Flip one canvas node's switch.
199
+ *
200
+ * The client says WHICH NODE was clicked and nothing else β€” the server owns what
201
+ * each switch means (`engine.NODE_TOGGLES`). A client that knew "the HikerAPI
202
+ * node writes config.tier" would be a second copy of that knowledge, free to
203
+ * drift from the engine that reads it.
204
+ */
205
+ export function toggleNode(
206
+ id: string,
207
+ nodeId: string
208
+ ): Promise<{ automation: Automation }> {
209
+ return send(
210
+ `/automations/${encodeURIComponent(id)}/nodes/${encodeURIComponent(nodeId)}/toggle`,
211
+ { method: "POST" }
212
+ );
213
+ }
214
+
215
  export function getAutomation(id: string): Promise<{ automation: Automation }> {
216
  return send(`/automations/${encodeURIComponent(id)}`);
217
  }
 
262
  ["unchanged", "Unchanged"],
263
  ["orphans", "No longer on the page (kept)"],
264
  ["duplicates", "Duplicate keys"],
265
+ ["skipped", "Skipped (no key)"],
266
+ // ⚠ ITS OWN CHIP, next to `skipped` but never merged with it. "Skipped" is a
267
+ // property of the data and usually benign; "not written β€” the database is
268
+ // full" is a property of the system and never is. One chip for both is how a
269
+ // time series stops growing without anybody being told.
270
+ ["capped", "Not written β€” the database is full"],
271
  ["source_rows", "Rows read"],
272
  ["profiles", "Profiles"],
273
  ["ok", "Read in full"],
 
278
  ["partial", "Profile only"],
279
  ["blocked", "Blocked"],
280
  ["error", "Errors"],
281
+ ["paid", "Exact via HikerAPI"],
282
  ["posts", "Posts"],
283
  ["new_posts", "New posts"],
284
  ];
web/src/automation/canvasLayout.ts ADDED
@@ -0,0 +1,163 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // automation/canvasLayout.ts β€” pixels for the node canvas, and NOTHING else.
3
+ //
4
+ // THE DIVISION OF LABOUR, stated once: the SERVER owns the topology (which nodes
5
+ // exist, what they are called, which edges join them, what each node's dot says
6
+ // β€” `engine.graph()`), and this file owns where they land on screen. That split
7
+ // is why the canvas cannot describe a step the engine stopped running: there is
8
+ // no second opinion about what the steps are, only about their coordinates.
9
+ //
10
+ // Pure functions over plain data β€” no React, no DOM, no measurement. Everything
11
+ // here is deterministic from `col`/`row`, which is what makes fit-to-view and
12
+ // zoom-about-the-cursor arithmetic rather than layout thrash.
13
+ // ---------------------------------------------------------------------------
14
+ import type { AutomationGraph, GraphEdge, GraphNode } from "./automationApi";
15
+
16
+ /** One node's box. Tuned against `reference/Sola 1.png`: wide enough for a
17
+ * sentence-case title plus two muted lines, short enough that a four-node flow
18
+ * fits a laptop viewport at 100%. */
19
+ export const NODE_W = 208;
20
+ export const NODE_H = 96;
21
+ /** The gap a `col` step costs. The edge draws in it, so it must fit a label. */
22
+ export const COL_GAP = 104;
23
+ /** The gap a `row` step costs. Rows are βˆ’1 / 0 / +1 around the spine. */
24
+ export const ROW_GAP = 132;
25
+ /** Breathing room around the whole flow when fitting it to the viewport. */
26
+ export const PAD = 56;
27
+
28
+ export const MIN_ZOOM = 0.35;
29
+ export const MAX_ZOOM = 2;
30
+
31
+ export interface Placed extends GraphNode {
32
+ x: number;
33
+ y: number;
34
+ }
35
+
36
+ export interface Viewport {
37
+ /** Scene-space translation, in screen pixels (applied before scale). */
38
+ x: number;
39
+ y: number;
40
+ /** Scale. `1` = 100%. */
41
+ k: number;
42
+ }
43
+
44
+ export const IDENTITY: Viewport = { x: 0, y: 0, k: 1 };
45
+
46
+ /** Grid coordinates β†’ pixels. The only place the two are related. */
47
+ export function place(nodes: GraphNode[]): Placed[] {
48
+ return nodes.map((n) => ({
49
+ ...n,
50
+ x: n.col * (NODE_W + COL_GAP),
51
+ y: n.row * ROW_GAP,
52
+ }));
53
+ }
54
+
55
+ export interface Box {
56
+ minX: number;
57
+ minY: number;
58
+ maxX: number;
59
+ maxY: number;
60
+ w: number;
61
+ h: number;
62
+ }
63
+
64
+ export function bounds(placed: Placed[]): Box {
65
+ if (!placed.length) return { minX: 0, minY: 0, maxX: NODE_W, maxY: NODE_H, w: NODE_W, h: NODE_H };
66
+ const minX = Math.min(...placed.map((p) => p.x));
67
+ const minY = Math.min(...placed.map((p) => p.y));
68
+ const maxX = Math.max(...placed.map((p) => p.x + NODE_W));
69
+ const maxY = Math.max(...placed.map((p) => p.y + NODE_H));
70
+ return { minX, minY, maxX, maxY, w: maxX - minX, h: maxY - minY };
71
+ }
72
+
73
+ export function clampZoom(k: number): number {
74
+ return Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, k));
75
+ }
76
+
77
+ /**
78
+ * The viewport that centres the whole flow in a `w Γ— h` viewport.
79
+ *
80
+ * Capped at 1: a two-node automation blown up to 200% looks broken, not roomy.
81
+ * Zooming IN past 100% is something a user asks for; it is never a default.
82
+ */
83
+ export function fit(placed: Placed[], w: number, h: number): Viewport {
84
+ const b = bounds(placed);
85
+ if (w <= 0 || h <= 0) return IDENTITY;
86
+ const k = clampZoom(Math.min(1, (w - PAD * 2) / b.w, (h - PAD * 2) / b.h));
87
+ return {
88
+ k,
89
+ x: (w - b.w * k) / 2 - b.minX * k,
90
+ y: (h - b.h * k) / 2 - b.minY * k,
91
+ };
92
+ }
93
+
94
+ /**
95
+ * Zoom about a fixed screen point β€” the pixel under the cursor stays under the
96
+ * cursor. Without this a wheel-zoom walks the flow off screen and every zoom
97
+ * needs a pan to undo it.
98
+ */
99
+ export function zoomAt(v: Viewport, k: number, px: number, py: number): Viewport {
100
+ const next = clampZoom(k);
101
+ const ratio = next / v.k;
102
+ return { k: next, x: px - (px - v.x) * ratio, y: py - (py - v.y) * ratio };
103
+ }
104
+
105
+ /** A node's output port, in scene space. */
106
+ export function outPort(p: Placed): [number, number] {
107
+ return [p.x + NODE_W, p.y + NODE_H / 2];
108
+ }
109
+
110
+ /** A node's input port, in scene space. */
111
+ export function inPort(p: Placed): [number, number] {
112
+ return [p.x, p.y + NODE_H / 2];
113
+ }
114
+
115
+ /**
116
+ * The wire between two nodes.
117
+ *
118
+ * A cubic with HORIZONTAL control handles, so an edge always leaves a node
119
+ * sideways and arrives sideways β€” that is what makes a branch read as one thing
120
+ * splitting rather than two unrelated lines crossing. Same-row edges come out
121
+ * straight because both control points sit on the same y.
122
+ */
123
+ export function edgePath(from: Placed, to: Placed): string {
124
+ const [x1, y1] = outPort(from);
125
+ const [x2, y2] = inPort(to);
126
+ const bend = Math.max(36, Math.abs(x2 - x1) * 0.45);
127
+ return `M ${x1} ${y1} C ${x1 + bend} ${y1}, ${x2 - bend} ${y2}, ${x2} ${y2}`;
128
+ }
129
+
130
+ /** The midpoint of an edge, for its label. */
131
+ export function edgeMid(from: Placed, to: Placed): [number, number] {
132
+ const [x1, y1] = outPort(from);
133
+ const [x2, y2] = inPort(to);
134
+ return [(x1 + x2) / 2, (y1 + y2) / 2 - 8];
135
+ }
136
+
137
+ export interface Wire extends GraphEdge {
138
+ d: string;
139
+ mid: [number, number];
140
+ /** An edge is dim when EITHER end is switched off β€” a wire into a disabled
141
+ * step is not a path this automation takes. */
142
+ dim: boolean;
143
+ }
144
+
145
+ export function wires(graph: AutomationGraph, placed: Placed[]): Wire[] {
146
+ const by = new Map(placed.map((p) => [p.id, p]));
147
+ const out: Wire[] = [];
148
+ for (const e of graph.edges || []) {
149
+ const a = by.get(e.from);
150
+ const b = by.get(e.to);
151
+ // An edge naming a node that is not there is dropped rather than drawn to
152
+ // (0,0) β€” a wire into the corner looks like a bug in the flow, when it is a
153
+ // bug in the payload.
154
+ if (!a || !b) continue;
155
+ out.push({
156
+ ...e,
157
+ d: edgePath(a, b),
158
+ mid: edgeMid(a, b),
159
+ dim: !a.enabled || !b.enabled,
160
+ });
161
+ }
162
+ return out;
163
+ }
web/src/customer-grid/CatalogView.tsx CHANGED
@@ -74,6 +74,9 @@ import {
74
  uploadEditorial,
75
  } from "./catalogData";
76
  import type { CatalogItem } from "./catalogData";
 
 
 
77
  import { applyPrintCss, awaitImages, printOnce } from "./catalogPrint";
78
  import { formatDisplay } from "./display";
79
 
@@ -199,10 +202,13 @@ function ProductCard({
199
  layout: ReturnType<typeof sectionLayout>;
200
  hasAsset: (code: string) => boolean | null;
201
  }) {
202
- const known = hasAsset(item.code);
 
 
 
203
  return (
204
  <div className="cg-cat-card">
205
- <Shot code={item.code} quality={quality} missing={known === false} />
206
  {/* CAPS in CSS (`text-transform`), never by upper-casing the string: the
207
  value stays the value, so a copy of it is not shouting. */}
208
  <div className="cg-cat-desc">{item.name ?? (item.known ? "" : "Not in this table")}</div>
@@ -491,6 +497,12 @@ export const CatalogView = memo(function CatalogView({
491
  // quiet, same as the product manifest's own rule.
492
  const slug = editorialSlug(code);
493
  if (slug !== null) return editorialSlugs ? editorialSlugs.has(slug) : null;
 
 
 
 
 
 
494
  return assetCodes ? assetCodes.has(code) : null;
495
  },
496
  [assetCodes, editorialSlugs]
 
74
  uploadEditorial,
75
  } from "./catalogData";
76
  import type { CatalogItem } from "./catalogData";
77
+ // Wave-19 R7 β€” the record-image namespace, so the gap report can say "I do not know" about an
78
+ // upload rather than marking every one of them missing.
79
+ import { RECORD_IMAGE_PREFIX } from "./types";
80
  import { applyPrintCss, awaitImages, printOnce } from "./catalogPrint";
81
  import { formatDisplay } from "./display";
82
 
 
202
  layout: ReturnType<typeof sectionLayout>;
203
  hasAsset: (code: string) => boolean | null;
204
  }) {
205
+ // ⭐ Wave-19 R7 β€” the picture is the ITEM'S image reference, which equals the code on every
206
+ // row nobody has overridden. Both the tile and the gap report read the SAME string, or the
207
+ // designer could mark a product "no master" while printing a picture it does have.
208
+ const known = hasAsset(item.image);
209
  return (
210
  <div className="cg-cat-card">
211
+ <Shot code={item.image} quality={quality} missing={known === false} />
212
  {/* CAPS in CSS (`text-transform`), never by upper-casing the string: the
213
  value stays the value, so a copy of it is not shouting. */}
214
  <div className="cg-cat-desc">{item.name ?? (item.known ? "" : "Not in this table")}</div>
 
497
  // quiet, same as the product manifest's own rule.
498
  const slug = editorialSlug(code);
499
  if (slug !== null) return editorialSlugs ? editorialSlugs.has(slug) : null;
500
+ // ⭐ Wave-19 R7 β€” a `rec:` upload has NO manifest to check against, and inventing one
501
+ // would be a per-tenant listing endpoint built for a designer badge. `null` is the
502
+ // vocabulary this function already has for "I do not know", and it is the truthful
503
+ // answer: an uploaded picture was validated at upload, so the far likelier state is that
504
+ // it is there. Marking it missing would send the user hunting for a file that exists.
505
+ if (code.startsWith(RECORD_IMAGE_PREFIX)) return null;
506
  return assetCodes ? assetCodes.has(code) : null;
507
  },
508
  [assetCodes, editorialSlugs]
web/src/customer-grid/CustomerGrid.tsx CHANGED
@@ -66,8 +66,8 @@ import type { CatalogSpec } from "./types";
66
  /* ═══ end W18-C CATALOG ═══ */
67
  import { lightTheme, STATUS_ROW_THEME, HOVER_ROW_THEME, HOVER_NEUTRAL,
68
  ACTIVE_ROW_NEUTRAL, CUSTOM_FIELD_MARK } from "./theme";
69
- import { avatarInitials, formatDisplay, ratingCellRenderer, setAvatarRepaint, userCellRenderer }
70
- from "./cells";
71
  import { optionTint, pickTint } from "./choiceColors";
72
  import {
73
  EMPTY_GRID_COPY_PROVENANCE,
@@ -3363,7 +3363,7 @@ function CustomerGrid({ scope = "customer" }: { scope?: SurfaceScope } = {}) {
3363
  smoothScrollY
3364
  width={gridSize.width}
3365
  height={gridSize.height}
3366
- customRenderers={[ratingCellRenderer, userCellRenderer]}
3367
  headerIcons={HEADER_ICONS}
3368
  rightElement={
3369
  // Wave-6 item 4 β€” the far-right "+" of the header row: the create-field
 
66
  /* ═══ end W18-C CATALOG ═══ */
67
  import { lightTheme, STATUS_ROW_THEME, HOVER_ROW_THEME, HOVER_NEUTRAL,
68
  ACTIVE_ROW_NEUTRAL, CUSTOM_FIELD_MARK } from "./theme";
69
+ import { avatarInitials, formatDisplay, imageCellRenderer, ratingCellRenderer, setAvatarRepaint,
70
+ userCellRenderer } from "./cells";
71
  import { optionTint, pickTint } from "./choiceColors";
72
  import {
73
  EMPTY_GRID_COPY_PROVENANCE,
 
3363
  smoothScrollY
3364
  width={gridSize.width}
3365
  height={gridSize.height}
3366
+ customRenderers={[ratingCellRenderer, userCellRenderer, imageCellRenderer]}
3367
  headerIcons={HEADER_ICONS}
3368
  rightElement={
3369
  // Wave-6 item 4 β€” the far-right "+" of the header row: the create-field
web/src/customer-grid/RecordComments.tsx CHANGED
@@ -1,5 +1,6 @@
1
  import { useEffect, useReducer, useRef } from "react";
2
  import type { FormEvent } from "react";
 
3
  import type { Viewer } from "./types";
4
  import {
5
  deleteRecordComment,
@@ -33,9 +34,18 @@ function when(value: string): string {
33
  }
34
 
35
  export default function RecordComments({
 
36
  pid,
37
  viewer,
38
  }: {
 
 
 
 
 
 
 
 
39
  pid: number;
40
  viewer?: Viewer;
41
  }) {
@@ -50,7 +60,7 @@ export default function RecordComments({
50
  useEffect(() => {
51
  const controller = new AbortController();
52
  dispatch({ type: "record", pid });
53
- fetchRecordComments(pid, controller.signal)
54
  .then((comments) => dispatch({ type: "loaded", pid, comments }))
55
  .catch((reason: unknown) => {
56
  if (reason instanceof DOMException && reason.name === "AbortError") return;
@@ -61,7 +71,11 @@ export default function RecordComments({
61
  });
62
  });
63
  return () => controller.abort();
64
- }, [pid]);
 
 
 
 
65
 
66
  const post = async (event: FormEvent) => {
67
  event.preventDefault();
@@ -70,7 +84,7 @@ export default function RecordComments({
70
  const requestPid = pid;
71
  dispatch({ type: "posting", pid: requestPid });
72
  try {
73
- const comment = await postRecordComment(requestPid, body);
74
  dispatch({ type: "posted", pid: requestPid, comment });
75
  if (requestPid === pid) textareaRef.current?.focus();
76
  } catch (reason) {
@@ -85,7 +99,7 @@ export default function RecordComments({
85
  const remove = async (comment: RecordComment) => {
86
  const requestPid = pid;
87
  try {
88
- await deleteRecordComment(requestPid, comment.id);
89
  dispatch({ type: "deleted", pid: requestPid, commentId: comment.id });
90
  } catch (reason) {
91
  dispatch({
 
1
  import { useEffect, useReducer, useRef } from "react";
2
  import type { FormEvent } from "react";
3
+ import type { SurfaceScope } from "./apiBridge";
4
  import type { Viewer } from "./types";
5
  import {
6
  deleteRecordComment,
 
34
  }
35
 
36
  export default function RecordComments({
37
+ scope,
38
  pid,
39
  viewer,
40
  }: {
41
+ /**
42
+ * ⭐ WAVE 19 (owner item 12) β€” WHICH DATABASE THIS RECORD BELONGS TO. Required, with no
43
+ * default, for the reason the Insights tab states at `RecordDetail.tsx`'s `scope` prop: a pid
44
+ * is only meaningful inside one topic, and asking the customer endpoint about a product's
45
+ * CRC32 hash either 403s on a screen showing a product (the reported bug) or β€” on a
46
+ * collision β€” answers 200 and files the comment against somebody's customer.
47
+ */
48
+ scope: SurfaceScope;
49
  pid: number;
50
  viewer?: Viewer;
51
  }) {
 
60
  useEffect(() => {
61
  const controller = new AbortController();
62
  dispatch({ type: "record", pid });
63
+ fetchRecordComments(scope, pid, controller.signal)
64
  .then((comments) => dispatch({ type: "loaded", pid, comments }))
65
  .catch((reason: unknown) => {
66
  if (reason instanceof DOMException && reason.name === "AbortError") return;
 
71
  });
72
  });
73
  return () => controller.abort();
74
+ // ⚠ `scope` is in the deps beside `pid`: the reducer's stale-completion guard keys on the
75
+ // PID alone, so a surface switch that landed on the same pid would otherwise accept the old
76
+ // topic's feed. The mount is also keyed by scope+pid (RecordDetail), which makes this belt
77
+ // and braces β€” kept because the guard here is the one that survives a host that forgets.
78
+ }, [scope, pid]);
79
 
80
  const post = async (event: FormEvent) => {
81
  event.preventDefault();
 
84
  const requestPid = pid;
85
  dispatch({ type: "posting", pid: requestPid });
86
  try {
87
+ const comment = await postRecordComment(scope, requestPid, body);
88
  dispatch({ type: "posted", pid: requestPid, comment });
89
  if (requestPid === pid) textareaRef.current?.focus();
90
  } catch (reason) {
 
99
  const remove = async (comment: RecordComment) => {
100
  const requestPid = pid;
101
  try {
102
+ await deleteRecordComment(scope, requestPid, comment.id);
103
  dispatch({ type: "deleted", pid: requestPid, commentId: comment.id });
104
  } catch (reason) {
105
  dispatch({
web/src/customer-grid/RecordDetail.css CHANGED
@@ -370,6 +370,87 @@
370
  outline-offset: 1px;
371
  }
372
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
373
  /* Rating: the stars ARE the picker. Clicking the lit star clears the value β€”
374
  without it a rating could be changed here but never removed. */
375
  .cg-record-main .cg-detail-stars {
 
370
  outline-offset: 1px;
371
  }
372
 
373
+ /* ⭐ Wave-19 R7 β€” the IMAGE slot: the picture, then its reference and controls.
374
+ The thumbnail is `object-fit: contain` for the reason the grid cell is: a
375
+ product photo cropped to a square loses the thing being sold. Letterboxing
376
+ inside a bounded frame is the honest fit for a catalogue picture. */
377
+ .cg-record-main .cg-detail-imageslot {
378
+ display: flex;
379
+ align-items: flex-start;
380
+ gap: 10px;
381
+ }
382
+
383
+ .cg-record-main .cg-detail-image,
384
+ .cg-record-main .cg-detail-imageempty {
385
+ flex: 0 0 auto;
386
+ width: 72px;
387
+ height: 72px;
388
+ border: 1px solid var(--lp-line);
389
+ border-radius: var(--lp-r-sm);
390
+ background: var(--lp-surface-2);
391
+ object-fit: contain;
392
+ }
393
+
394
+ .cg-record-main .cg-detail-imagemeta {
395
+ display: flex;
396
+ flex-direction: column;
397
+ align-items: flex-start;
398
+ gap: 5px;
399
+ min-width: 0;
400
+ }
401
+
402
+ /* The reference itself, in the mono face: it is an identifier (a SKU code, a
403
+ slug, a minted id), and identifiers are read character by character. The
404
+ stack is spelled out rather than tokenised because there is no `--lp-mono`
405
+ token β€” the three existing monospace sites in index.css all spell it too, and
406
+ C6 says NO new tokens this wave. */
407
+ .cg-record-main .cg-detail-imageref {
408
+ max-width: 100%;
409
+ overflow: hidden;
410
+ text-overflow: ellipsis;
411
+ white-space: nowrap;
412
+ color: var(--lp-muted);
413
+ font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
414
+ font-size: var(--lp-fs-2xs);
415
+ }
416
+
417
+ .cg-record-main .cg-detail-imageacts {
418
+ display: inline-flex;
419
+ gap: 6px;
420
+ }
421
+
422
+ /* The `<label>` and the `<button>` are one control visually β€” the file input
423
+ inside the label is hidden, which is the only way to style a file picker. */
424
+ .cg-record-main .cg-detail-imagebtn {
425
+ display: inline-flex;
426
+ align-items: center;
427
+ height: 22px;
428
+ padding: 0 9px;
429
+ border: 1px solid var(--lp-line);
430
+ border-radius: var(--lp-r-pill);
431
+ background: var(--lp-surface-2);
432
+ color: var(--lp-muted);
433
+ font-family: inherit;
434
+ font-size: var(--lp-fs-2xs);
435
+ line-height: 1;
436
+ white-space: nowrap;
437
+ cursor: pointer;
438
+ }
439
+
440
+ .cg-record-main .cg-detail-imagebtn:hover {
441
+ border-color: var(--lp-blue-deep);
442
+ color: var(--lp-blue-deep);
443
+ }
444
+
445
+ .cg-record-main .cg-detail-imagebtn input[type="file"] {
446
+ display: none;
447
+ }
448
+
449
+ .cg-record-main .cg-detail-imageerr {
450
+ color: var(--lp-red-deep);
451
+ font-size: var(--lp-fs-2xs);
452
+ }
453
+
454
  /* Rating: the stars ARE the picker. Clicking the lit star clears the value β€”
455
  without it a rating could be changed here but never removed. */
456
  .cg-record-main .cg-detail-stars {
web/src/customer-grid/RecordDetail.tsx CHANGED
@@ -28,6 +28,9 @@ import {
28
  userInitials,
29
  } from "./recordFields";
30
  import { pickTint } from "./choiceColors";
 
 
 
31
  // C-EMBED β€” the ONLY thing item 13 takes from the grid's side of the house. Not a hook, not a
32
  // context, not a slice of CustomerGrid's state: the panel was written to receive every input
33
  // as a prop precisely so it could be mounted twice, and importing anything else from over
@@ -256,7 +259,16 @@ export default function RecordDetail({
256
  const titleId = useId();
257
  const tabsId = useId();
258
  const title = String(record[titleKey] ?? "Untitled");
259
- const showComments = !isStreamlitComponent();
 
 
 
 
 
 
 
 
 
260
  const overlayFields = fields.filter((field) => field.source === "overlay");
261
  // ⚠ These five buckets are the DEFAULT ORDER of the interleaved list (C-LAYOUT) and NOTHING
262
  // ELSE. They used to double as the editability split β€” picked/rating fields rendered
@@ -459,6 +471,10 @@ export default function RecordDetail({
459
  field.type !== "date" &&
460
  field.type !== "int" &&
461
  field.type !== "currency" &&
 
 
 
 
462
  field.type !== "pct";
463
  const isControl = editable && !isEdit;
464
  const cls =
@@ -517,6 +533,83 @@ export default function RecordDetail({
517
  }
518
  />
519
  );
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
520
  } else if (isControl && field.type === "rating") {
521
  // Item 9 β€” the stars ARE the picker now. Clicking the lit star clears the field
522
  // (`composeRatingValue`): without it a rating could be changed here but never removed,
@@ -930,9 +1023,18 @@ export default function RecordDetail({
930
  )}
931
  </div>
932
  </main>
933
- {showComments && (
 
 
 
 
 
 
 
 
934
  <RecordComments
935
- key={Number(record.pid)}
 
936
  pid={Number(record.pid)}
937
  viewer={viewer}
938
  />
 
28
  userInitials,
29
  } from "./recordFields";
30
  import { pickTint } from "./choiceColors";
31
+ // Wave-19 R7 β€” ONE asset resolver and ONE upload path, shared with the catalog. A second URL
32
+ // builder here is how the modal and the printed page would disagree about a row's picture.
33
+ import { assetUrl, uploadRecordImage } from "./catalogData";
34
  // C-EMBED β€” the ONLY thing item 13 takes from the grid's side of the house. Not a hook, not a
35
  // context, not a slice of CustomerGrid's state: the panel was written to receive every input
36
  // as a prop precisely so it could be mounted twice, and importing anything else from over
 
259
  const titleId = useId();
260
  const tabsId = useId();
261
  const title = String(record[titleKey] ?? "Untitled");
262
+ // Wave 19 (item 12): `scope` joins the predicate β€” the comments rail addresses a server
263
+ // endpoint per topic now, so a host that names no surface gets no rail rather than a rail
264
+ // pointed at a guess. In practice CustomerGrid always names one; this is the fail-closed edge.
265
+ const showComments = !isStreamlitComponent() && scope != null;
266
+ // Wave 19 (R7): which image field is mid-upload, and the last upload failure. ONE pair for the
267
+ // whole modal rather than per field β€” a record has at most a handful of picture columns and
268
+ // only one file dialog can be open at a time, so per-field state would be bookkeeping with no
269
+ // reachable second case.
270
+ const [imageBusy, setImageBusy] = useState("");
271
+ const [imageError, setImageError] = useState("");
272
  const overlayFields = fields.filter((field) => field.source === "overlay");
273
  // ⚠ These five buckets are the DEFAULT ORDER of the interleaved list (C-LAYOUT) and NOTHING
274
  // ELSE. They used to double as the editability split β€” picked/rating fields rendered
 
471
  field.type !== "date" &&
472
  field.type !== "int" &&
473
  field.type !== "currency" &&
474
+ // Wave-19 R7 β€” an `image` cell holds a REFERENCE, and a textarea over a reference invites
475
+ // somebody to type `rec:` by hand at a picture that does not exist. Its slot is a
476
+ // thumbnail plus an upload control, so it joins the constrained-control family.
477
+ field.type !== "image" &&
478
  field.type !== "pct";
479
  const isControl = editable && !isEdit;
480
  const cls =
 
533
  }
534
  />
535
  );
536
+ } else if (field.type === "image") {
537
+ // ⭐ Wave-19 R7 / C5 β€” the PICTURE slot: what is there, and (when editable) a way to
538
+ // replace or remove it. Read-only rows still get the thumbnail, because seeing the image
539
+ // is the whole point of the column and permission to edit is a separate question.
540
+ //
541
+ // ⚠ The `<img>` is deliberately plain. Its `onError` hides it rather than painting a
542
+ // broken glyph, and the caption below says WHICH reference failed β€” the grid cell can
543
+ // only show an empty frame, so this modal is where "that SKU has no master on file" gets
544
+ // said in words.
545
+ const ref = String(record[field.key] ?? "").trim();
546
+ slot = (
547
+ <span className="cg-detail-value cg-detail-value--live cg-detail-imageslot">
548
+ {ref ? (
549
+ <img
550
+ className="cg-detail-image"
551
+ src={assetUrl(ref, "web")}
552
+ alt={`${field.label} for ${title}`}
553
+ onError={(event) => {
554
+ event.currentTarget.style.display = "none";
555
+ }}
556
+ />
557
+ ) : (
558
+ <span className="cg-detail-imageempty" aria-hidden />
559
+ )}
560
+ <span className="cg-detail-imagemeta">
561
+ <span className="cg-detail-imageref">{ref || "No image"}</span>
562
+ {editable && (
563
+ <span className="cg-detail-imageacts">
564
+ <label className="cg-detail-imagebtn">
565
+ {ref ? "Replace" : "Upload"}
566
+ <input
567
+ type="file"
568
+ accept="image/png,image/jpeg"
569
+ onChange={(event) => {
570
+ const file = event.target.files?.[0];
571
+ // Reset the input BEFORE the await: picking the same file twice in a row
572
+ // fires no change event otherwise, so a failed upload could not be retried
573
+ // with the same picture.
574
+ event.target.value = "";
575
+ if (!file) return;
576
+ setImageBusy(field.key);
577
+ void uploadRecordImage(file)
578
+ .then((newRef) => {
579
+ setImageError("");
580
+ onNotesCommit(field.key, newRef);
581
+ })
582
+ .catch((reason: unknown) =>
583
+ setImageError(
584
+ reason instanceof Error
585
+ ? reason.message
586
+ : "That image was not saved."
587
+ )
588
+ )
589
+ .finally(() => setImageBusy(""));
590
+ }}
591
+ />
592
+ </label>
593
+ {ref && (
594
+ <button
595
+ type="button"
596
+ className="cg-detail-imagebtn"
597
+ onClick={() => onNotesCommit(field.key, "")}
598
+ >
599
+ Remove
600
+ </button>
601
+ )}
602
+ </span>
603
+ )}
604
+ {imageBusy === field.key && (
605
+ <span className="lp-spin" role="status" aria-label="Uploading" />
606
+ )}
607
+ {imageError && imageBusy !== field.key && (
608
+ <span className="cg-detail-imageerr">{imageError}</span>
609
+ )}
610
+ </span>
611
+ </span>
612
+ );
613
  } else if (isControl && field.type === "rating") {
614
  // Item 9 β€” the stars ARE the picker now. Clicking the lit star clears the field
615
  // (`composeRatingValue`): without it a rating could be changed here but never removed,
 
1023
  )}
1024
  </div>
1025
  </main>
1026
+ {/* ⭐ WAVE 19 (owner item 12) β€” the rail finally gets the SCOPE this modal has held
1027
+ since wave 13 and never passed on. `scope != null` gates it for exactly the
1028
+ reason it gates Insights (see the prop's own note): a pid means nothing without
1029
+ the topic it belongs to, and a guessed topic answers a question nobody asked.
1030
+ ⚠ The key is scope+pid, not pid: two databases can hold the same numeric id, and
1031
+ a key that only changed on the number would REUSE this component across a surface
1032
+ switch, painting one record's comments under another's name until the fetch
1033
+ returned. */}
1034
+ {showComments && scope != null && (
1035
  <RecordComments
1036
+ key={`${scope}:${Number(record.pid)}`}
1037
+ scope={scope}
1038
  pid={Number(record.pid)}
1039
  viewer={viewer}
1040
  />
web/src/customer-grid/catalogData.ts CHANGED
@@ -22,6 +22,7 @@ import {
22
  CATALOG_CODE_MAX,
23
  MAX_CATALOG_CODES,
24
  MAX_CATALOG_PAGES,
 
25
  } from "./types";
26
  import type {
27
  CatalogOrientation,
@@ -73,10 +74,25 @@ export interface CatalogItem {
73
  pack?: string;
74
  color?: string;
75
  price?: string;
 
 
 
 
 
 
 
76
  /** False when the row is not in the pool at all β€” drawn as a stated gap. */
77
  known: boolean;
78
  }
79
 
 
 
 
 
 
 
 
 
80
  export function resolveItems(
81
  codes: string[],
82
  byCode: Map<string, Row>,
@@ -91,12 +107,16 @@ export function resolveItems(
91
  const text = format(field, row[key]);
92
  return text ? text : undefined;
93
  };
 
94
  return codes.map((code) => {
95
  const row = byCode.get(code);
96
- if (!row) return { code, known: false };
 
 
97
  return {
98
  code,
99
  known: true,
 
100
  name: line(row, binds?.name),
101
  pack: line(row, binds?.pack),
102
  color: line(row, binds?.color),
@@ -160,9 +180,38 @@ export function editorialSlug(code: string): string | null {
160
 
161
  export function assetUrl(code: string, quality: CatalogQuality): string {
162
  const slug = editorialSlug(code);
163
- return slug !== null
164
- ? `${API_V1}/assets/editorial/${encodeURIComponent(slug)}?q=${quality}`
165
- : `${API_V1}/assets/products/${encodeURIComponent(code)}?q=${quality}`;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
166
  }
167
 
168
  /** C2-ASSET's manifest β€” which codes HAVE an image, so the designer can mark
@@ -224,6 +273,46 @@ export async function uploadEditorial(slug: string, file: Blob): Promise<string>
224
  return body.slug ?? slug;
225
  }
226
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
227
  /** A slug guessed from a filename: lowercased, non-alphanumerics folded to
228
  * hyphens, trimmed β€” mirrors the server's charset so the guess is accepted. */
229
  export function slugFromFilename(name: string): string {
 
22
  CATALOG_CODE_MAX,
23
  MAX_CATALOG_CODES,
24
  MAX_CATALOG_PAGES,
25
+ RECORD_IMAGE_PREFIX,
26
  } from "./types";
27
  import type {
28
  CatalogOrientation,
 
74
  pack?: string;
75
  color?: string;
76
  price?: string;
77
+ /**
78
+ * ⭐ Wave-19 R7 β€” WHICH PICTURE this item prints, resolved from the table's `image` column
79
+ * with the code as the fallback. Always a non-empty string when `known`; equal to `code` on
80
+ * every row nobody has overridden, which is why the ruling could keep the fallback and still
81
+ * call the field authoritative.
82
+ */
83
+ image: string;
84
  /** False when the row is not in the pool at all β€” drawn as a stated gap. */
85
  known: boolean;
86
  }
87
 
88
+ /** The table's picture column, if it has one. FIRST `image`-typed field: a table with two is
89
+ * ambiguous and picking the first is at least stable, where picking "none" would silently
90
+ * disable the feature for the user who added a second one. */
91
+ export function imageFieldKey(fieldByKey: Map<string, Field>): string | undefined {
92
+ for (const [key, field] of fieldByKey) if (field.type === "image") return key;
93
+ return undefined;
94
+ }
95
+
96
  export function resolveItems(
97
  codes: string[],
98
  byCode: Map<string, Row>,
 
107
  const text = format(field, row[key]);
108
  return text ? text : undefined;
109
  };
110
+ const imageKey = imageFieldKey(fieldByKey);
111
  return codes.map((code) => {
112
  const row = byCode.get(code);
113
+ // An unknown code still prints its own frame under its own name β€” the gap is STATED, and
114
+ // stating it needs the code as the reference it would have used.
115
+ if (!row) return { code, image: code, known: false };
116
  return {
117
  code,
118
  known: true,
119
+ image: rowImageRef(row, imageKey) || code,
120
  name: line(row, binds?.name),
121
  pack: line(row, binds?.pack),
122
  color: line(row, binds?.color),
 
180
 
181
  export function assetUrl(code: string, quality: CatalogQuality): string {
182
  const slug = editorialSlug(code);
183
+ if (slug !== null)
184
+ return `${API_V1}/assets/editorial/${encodeURIComponent(slug)}?q=${quality}`;
185
+ // ⭐ Wave-19 R7 / C5 β€” the THIRD namespace: a picture uploaded through an `image` field. The
186
+ // tenant is NOT in the URL and never will be: the route takes it from the session, so a
187
+ // reference copied out of one tenant's cell resolves to nothing in another's (a 404, not
188
+ // somebody else's photograph).
189
+ if (code.startsWith(RECORD_IMAGE_PREFIX)) {
190
+ const id = code.slice(RECORD_IMAGE_PREFIX.length).trim();
191
+ return `${API_V1}/assets/records/${encodeURIComponent(id)}?q=${quality}`;
192
+ }
193
+ return `${API_V1}/assets/products/${encodeURIComponent(code)}?q=${quality}`;
194
+ }
195
+
196
+ /**
197
+ * ⭐ Wave-19 R7 β€” WHICH REFERENCE A ROW'S PICTURE IS, given the catalog's bound image column.
198
+ *
199
+ * The ruling is "catalog reads the field (code fallback kept)", and the fallback is the half
200
+ * that matters: Royal's 1,142 masters are named for `default_code`, so a product nobody has
201
+ * touched already names its own picture. Reading the field FIRST is what lets one SKU be
202
+ * overridden β€” a lifestyle shot for the cover product, say β€” without uploading 1,141 others.
203
+ *
204
+ * `imageKey` absent (a catalog bound before this field existed, or a table with no image
205
+ * column) collapses to exactly the old behaviour: the code IS the reference.
206
+ */
207
+ export function rowImageRef(row: Row | undefined, imageKey?: string): string {
208
+ if (!row) return "";
209
+ if (imageKey) {
210
+ const v = row[imageKey];
211
+ if (typeof v === "string" && v.trim()) return v.trim();
212
+ }
213
+ const code = row[CATALOG_CODE_FIELD];
214
+ return typeof code === "string" ? code.trim() : "";
215
  }
216
 
217
  /** C2-ASSET's manifest β€” which codes HAVE an image, so the designer can mark
 
273
  return body.slug ?? slug;
274
  }
275
 
276
+ /**
277
+ * ⭐ Wave-19 R7 / C5 β€” upload one RECORD image and get back the reference to store in the cell.
278
+ *
279
+ * Session-gated, not admin-gated: attaching a picture to your own row is the same class of act
280
+ * as typing a note. The tenant is never sent β€” the server takes it from the session, which is
281
+ * what makes a `rec:` reference meaningless outside the tenant that minted it.
282
+ *
283
+ * ⚠ The client checks the size FIRST purely to spare a doomed 2 MB round trip. The server
284
+ * re-checks the DECODED bytes and re-parses the image; this is a courtesy, not the wall.
285
+ */
286
+ export const RECORD_IMAGE_MAX_BYTES = 2 * 1024 * 1024;
287
+ export const RECORD_ASSET_URL = `${API_V1}/assets/records`;
288
+
289
+ export async function uploadRecordImage(file: Blob): Promise<string> {
290
+ if (file.size > RECORD_IMAGE_MAX_BYTES)
291
+ throw new Error(
292
+ `Images cap at ${RECORD_IMAGE_MAX_BYTES / (1024 * 1024)} MB β€” that one is ` +
293
+ `${(file.size / (1024 * 1024)).toFixed(1)} MB.`
294
+ );
295
+ const data = await new Promise<string>((resolve, reject) => {
296
+ const r = new FileReader();
297
+ r.onload = () => resolve(String(r.result ?? ""));
298
+ r.onerror = () => reject(new Error("could not read the file"));
299
+ r.readAsDataURL(file);
300
+ });
301
+ const res = await fetch(RECORD_ASSET_URL, {
302
+ method: "POST",
303
+ credentials: "same-origin",
304
+ headers: { "Content-Type": "application/json" },
305
+ body: JSON.stringify({ data }),
306
+ });
307
+ const body = (await res.json().catch(() => ({}))) as {
308
+ ref?: string;
309
+ error?: { message?: string };
310
+ };
311
+ if (!res.ok) throw new Error(body.error?.message ?? `upload failed (${res.status})`);
312
+ if (!body.ref) throw new Error("the server accepted the image but named no reference");
313
+ return body.ref;
314
+ }
315
+
316
  /** A slug guessed from a filename: lowercased, non-alphanumerics folded to
317
  * hyphens, trimmed β€” mirrors the server's charset so the guess is accepted. */
318
  export function slugFromFilename(name: string): string {
web/src/customer-grid/cells.ts CHANGED
@@ -32,6 +32,7 @@ import type {
32
  GridCell,
33
  Theme,
34
  } from "@glideapps/glide-data-grid";
 
35
  import type { Field } from "./types";
36
  import { ratingMax } from "./types";
37
  import {
@@ -264,6 +265,97 @@ export const userCellRenderer: CustomRenderer<UserCell> = {
264
  },
265
  };
266
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
267
  /** Registered once on the DataEditor (customRenderers). Pure canvas paths. */
268
  export const ratingCellRenderer: CustomRenderer<RatingCell> = {
269
  kind: GridCellKind.Custom,
@@ -399,6 +491,23 @@ export function makeCell(
399
  hoverEffect: true,
400
  ...ro,
401
  };
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
402
  case "rating": {
403
  const max = ratingMax(field);
404
  const n = Math.max(0, Math.min(max, Math.round(num(v))));
 
32
  GridCell,
33
  Theme,
34
  } from "@glideapps/glide-data-grid";
35
+ import { assetUrl } from "./catalogData";
36
  import type { Field } from "./types";
37
  import { ratingMax } from "./types";
38
  import {
 
265
  },
266
  };
267
 
268
+ // --- image: the record THUMBNAIL (wave-19 R7 / contract C5) -------------------
269
+ //
270
+ // The cell holds a REFERENCE, never bytes (`types.ts: imageRefKind`), so what paints here is an
271
+ // <img> the browser fetches from the asset routes and caches like any other image. Same
272
+ // module-scoped decode cache and same repaint hook as the avatar above, and for the same reason:
273
+ // glide repaints on `getCellContent` identity, and knows nothing about an `onload` three frames
274
+ // later. Without the hook the placeholder paints once and stays β€” a deliberate-looking empty
275
+ // frame over a picture that did arrive.
276
+
277
+ export interface ImageCellData {
278
+ kind: "aios-image";
279
+ /** The resolved URL, or "" when the cell is empty (paints the placeholder frame). */
280
+ url: string;
281
+ /** The raw cell value β€” the copy/export payload, so a picture column is not invisible in a CSV. */
282
+ ref: string;
283
+ }
284
+ export type ImageCell = CustomCell<ImageCellData>;
285
+
286
+ const _cellImgs = new Map<string, HTMLImageElement | null>();
287
+
288
+ function cellImage(url: string): HTMLImageElement | null {
289
+ const hit = _cellImgs.get(url);
290
+ if (hit !== undefined) return hit;
291
+ if (typeof Image === "undefined") {
292
+ _cellImgs.set(url, null);
293
+ return null;
294
+ }
295
+ const img = new Image();
296
+ _cellImgs.set(url, img);
297
+ img.onload = () => _avatarRepaint?.();
298
+ img.onerror = () => {
299
+ // A reference that does not resolve is NOT retried: an unknown SKU code is the ordinary
300
+ // state of a product with no master on file, and retrying it every repaint would be a
301
+ // 404 per scroll tick per row.
302
+ _cellImgs.set(url, null);
303
+ _avatarRepaint?.();
304
+ };
305
+ img.src = url;
306
+ return img;
307
+ }
308
+
309
+ /** Registered once on the DataEditor (customRenderers), beside rating and user. */
310
+ export const imageCellRenderer: CustomRenderer<ImageCell> = {
311
+ kind: GridCellKind.Custom,
312
+ isMatch: (cell): cell is ImageCell =>
313
+ (cell.data as ImageCellData | undefined)?.kind === "aios-image",
314
+ draw: (args, cell) => {
315
+ const { ctx, rect, theme } = args;
316
+ const { url } = cell.data;
317
+ const pad = theme.cellHorizontalPadding;
318
+ // Square, inset by 3px top and bottom so a tall row shows a bigger picture and a short one
319
+ // still leaves the grid line visible.
320
+ const size = Math.max(0, Math.min(rect.height - 6, rect.width - pad * 2));
321
+ if (size <= 2) return true; // column dragged too narrow: paint nothing, never bleed
322
+ const x = rect.x + pad;
323
+ const y = rect.y + (rect.height - size) / 2;
324
+ const img = url ? cellImage(url) : null;
325
+ ctx.save();
326
+ ctx.beginPath();
327
+ // A 3px radius, matching the choice pills β€” one rounding vocabulary across the canvas.
328
+ const r = Math.min(3, size / 2);
329
+ ctx.moveTo(x + r, y);
330
+ ctx.arcTo(x + size, y, x + size, y + size, r);
331
+ ctx.arcTo(x + size, y + size, x, y + size, r);
332
+ ctx.arcTo(x, y + size, x, y, r);
333
+ ctx.arcTo(x, y, x + size, y, r);
334
+ ctx.closePath();
335
+ // `complete` alone is not enough β€” a FAILED decode is also complete, with a zero natural size.
336
+ if (img && img.complete && img.naturalWidth > 0) {
337
+ ctx.clip();
338
+ // CONTAIN, not cover: a product photo cropped to a square loses the thing being sold.
339
+ // Letterboxing inside the frame is the honest fit for a catalogue picture.
340
+ const scale = Math.min(size / img.naturalWidth, size / img.naturalHeight);
341
+ const w = img.naturalWidth * scale;
342
+ const h = img.naturalHeight * scale;
343
+ ctx.drawImage(img, x + (size - w) / 2, y + (size - h) / 2, w, h);
344
+ } else {
345
+ // The empty frame: a quiet outline, never a broken-image glyph and never a coloured block
346
+ // that would read as content. Identical whether the cell is empty or the fetch failed β€”
347
+ // the record modal is where a user finds out which, in words.
348
+ ctx.fillStyle = LP_BLUE_TINT;
349
+ ctx.fill();
350
+ ctx.strokeStyle = "rgba(118, 143, 182, 0.45)";
351
+ ctx.lineWidth = 1;
352
+ ctx.stroke();
353
+ }
354
+ ctx.restore();
355
+ return true;
356
+ },
357
+ };
358
+
359
  /** Registered once on the DataEditor (customRenderers). Pure canvas paths. */
360
  export const ratingCellRenderer: CustomRenderer<RatingCell> = {
361
  kind: GridCellKind.Custom,
 
491
  hoverEffect: true,
492
  ...ro,
493
  };
494
+ case "image": {
495
+ // Wave-19 R7 / C5. `allowOverlay:false` for the same reason `select` has it: the value is
496
+ // a REFERENCE that is picked or uploaded, never typed into a cell β€” the record modal owns
497
+ // the picker and the upload. `copyData` carries the raw ref so the column is not invisible
498
+ // in a copy or an export (the lesson the avatar cell booked one wave earlier).
499
+ const ref = String(v ?? "").trim();
500
+ return {
501
+ kind: GridCellKind.Custom,
502
+ data: {
503
+ kind: "aios-image",
504
+ url: ref ? assetUrl(ref, "web") : "",
505
+ ref,
506
+ } satisfies ImageCellData,
507
+ copyData: ref,
508
+ allowOverlay: false,
509
+ };
510
+ }
511
  case "rating": {
512
  const max = ratingMax(field);
513
  const n = Math.max(0, Math.min(max, Math.round(num(v))));
web/src/customer-grid/iconShapes.ts CHANGED
@@ -105,6 +105,13 @@ export const TYPE_SHAPES: Record<FieldType, IconShape[]> = {
105
  { d: "M4.2 6L5.3 4.1 3.1 4.5" },
106
  { d: "M6.9 6.1L9.8 8 6.9 9.9z", fill: true },
107
  ],
 
 
 
 
 
 
 
108
  };
109
 
110
  /**
@@ -399,6 +406,8 @@ export const TYPE_LABELS: Record<FieldType, string> = {
399
  formula: "Formula",
400
  // Wave-18 C5-AUTOFIELD (D's spec, applied by C).
401
  automation: "Automation",
 
 
402
  status: "Lifecycle status (Odoo)", // never creatable; present so the map stays total
403
  };
404
 
 
105
  { d: "M4.2 6L5.3 4.1 3.1 4.5" },
106
  { d: "M6.9 6.1L9.8 8 6.9 9.9z", fill: true },
107
  ],
108
+ // Wave-19 R7 β€” a framed picture: the mount, a sun, and the hill line every photo glyph
109
+ // resolves to at 16px. Drawn on the same 16-unit grid as its neighbours.
110
+ image: [
111
+ { d: "M2.6 3.4h10.8v9.2H2.6z" },
112
+ { d: circle(6, 6.3, 1.1) },
113
+ { d: "M2.6 10.6L6.1 7.6l2.5 2.1 2.2-1.8 2.6 2.2" },
114
+ ],
115
  };
116
 
117
  /**
 
406
  formula: "Formula",
407
  // Wave-18 C5-AUTOFIELD (D's spec, applied by C).
408
  automation: "Automation",
409
+ // Wave-19 R7 β€” the picture column.
410
+ image: "Image",
411
  status: "Lifecycle status (Odoo)", // never creatable; present so the map stays total
412
  };
413
 
web/src/customer-grid/recordCommentsApi.ts CHANGED
@@ -4,6 +4,30 @@ import {
4
  UNAUTHORIZED_EVENT,
5
  signal,
6
  } from "../apiContract";
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7
 
8
  export interface RecordComment {
9
  id: string;
@@ -42,10 +66,11 @@ async function result<T>(response: Response): Promise<T> {
42
  }
43
 
44
  export async function fetchRecordComments(
 
45
  pid: number,
46
  abortSignal?: AbortSignal
47
  ): Promise<RecordComment[]> {
48
- const response = await fetch(`${API_V1}/customers/${pid}/comments`, {
49
  credentials: CREDENTIALS,
50
  signal: abortSignal,
51
  });
@@ -54,10 +79,11 @@ export async function fetchRecordComments(
54
  }
55
 
56
  export async function postRecordComment(
 
57
  pid: number,
58
  body: string
59
  ): Promise<RecordComment> {
60
- const response = await fetch(`${API_V1}/customers/${pid}/comments`, {
61
  method: "POST",
62
  credentials: CREDENTIALS,
63
  headers: { "Content-Type": "application/json" },
@@ -67,9 +93,13 @@ export async function postRecordComment(
67
  return payload.comment;
68
  }
69
 
70
- export async function deleteRecordComment(pid: number, commentId: string): Promise<void> {
 
 
 
 
71
  const response = await fetch(
72
- `${API_V1}/customers/${pid}/comments/${encodeURIComponent(commentId)}`,
73
  {
74
  method: "DELETE",
75
  credentials: CREDENTIALS,
 
4
  UNAUTHORIZED_EVENT,
5
  signal,
6
  } from "../apiContract";
7
+ import type { SurfaceScope } from "./apiBridge";
8
+
9
+ /**
10
+ * ⭐ WAVE 19 (owner item 12) β€” EVERY VERB CARRIES ITS SURFACE.
11
+ *
12
+ * The three URLs were hardcoded `/customers/{pid}/comments`, so opening a PRODUCT record and
13
+ * typing a comment asked the customer endpoint about a CRC32 hash of a SKU code. The honest
14
+ * failures read "that customer is not in your book" on a screen showing a product β€” the bug the
15
+ * owner reported. The dishonest failure is the one that made this worth a wave: a product pid
16
+ * that happens to collide with a real partner id answers 200, and the comment lands on somebody
17
+ * else's customer.
18
+ *
19
+ * `?scope=` rather than a path segment, because that is what the surrounding API already speaks
20
+ * for reads (`/workspace?scope=`) and what `scopeKey` does for writes β€” one vocabulary, not two.
21
+ *
22
+ * ⚠ THE PATH STAYS `/customers/…` and that is deliberate, not an oversight. It is the shipped
23
+ * URL, pinned by `verify_api.py`'s E1a section, and the scope is now carried explicitly beside
24
+ * it β€” so renaming the segment would buy a nicer noun in exchange for churning another session's
25
+ * gate mid-wave. Booked as a cosmetic debt in the wave doc; the WALL is `?scope=`, not the noun.
26
+ */
27
+ function commentsUrl(scope: SurfaceScope, pid: number, suffix = ""): string {
28
+ return `${API_V1}/customers/${encodeURIComponent(String(pid))}/comments${suffix}` +
29
+ `?scope=${encodeURIComponent(scope)}`;
30
+ }
31
 
32
  export interface RecordComment {
33
  id: string;
 
66
  }
67
 
68
  export async function fetchRecordComments(
69
+ scope: SurfaceScope,
70
  pid: number,
71
  abortSignal?: AbortSignal
72
  ): Promise<RecordComment[]> {
73
+ const response = await fetch(commentsUrl(scope, pid), {
74
  credentials: CREDENTIALS,
75
  signal: abortSignal,
76
  });
 
79
  }
80
 
81
  export async function postRecordComment(
82
+ scope: SurfaceScope,
83
  pid: number,
84
  body: string
85
  ): Promise<RecordComment> {
86
+ const response = await fetch(commentsUrl(scope, pid), {
87
  method: "POST",
88
  credentials: CREDENTIALS,
89
  headers: { "Content-Type": "application/json" },
 
93
  return payload.comment;
94
  }
95
 
96
+ export async function deleteRecordComment(
97
+ scope: SurfaceScope,
98
+ pid: number,
99
+ commentId: string
100
+ ): Promise<void> {
101
  const response = await fetch(
102
+ commentsUrl(scope, pid, `/${encodeURIComponent(commentId)}`),
103
  {
104
  method: "DELETE",
105
  credentials: CREDENTIALS,
web/src/customer-grid/types.ts CHANGED
@@ -37,7 +37,13 @@ export type FieldType =
37
  // Wave-18 C5-AUTOFIELD β€” `automation` is a column that a scheduled job WRITES. The cell holds
38
  // a machine-written status string (never user input); the column's behaviour is configured
39
  // through the field's gear, like `formula` carries its expression.
40
- | "automation";
 
 
 
 
 
 
41
 
42
  export type FieldSource = "odoo" | "overlay";
43
 
@@ -47,8 +53,35 @@ export type FieldSource = "odoo" | "overlay";
47
  export const CREATABLE_TYPES: readonly FieldType[] = [
48
  "text", "select", "multiselect", "user", "int", "currency", "pct", "date",
49
  "checkbox", "phone", "email", "url", "rating", "created_time", "formula", "automation",
 
50
  ];
51
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
52
  /**
53
  * Types whose CELLS never accept input, whoever the viewer is. A `formula` cell is computed
54
  * (editing it would mean editing arithmetic through a value box) and `created_time` is a fact
 
37
  // Wave-18 C5-AUTOFIELD β€” `automation` is a column that a scheduled job WRITES. The cell holds
38
  // a machine-written status string (never user input); the column's behaviour is configured
39
  // through the field's gear, like `formula` carries its expression.
40
+ | "automation"
41
+ // ⭐ Wave-19 R7 / C5 β€” `image` is a PICTURE on a record. The cell holds a STRING REFERENCE,
42
+ // never bytes (see `imageRef`): a SKU code, an `ed:` editorial slug, or a `rec:` upload. That
43
+ // is what lets Royal's 1,142 existing SKU masters appear with nothing uploaded, and it keeps
44
+ // the row payload the same size it was β€” a base64 image per row would be a megabyte tax on
45
+ // every scroll.
46
+ | "image";
47
 
48
  export type FieldSource = "odoo" | "overlay";
49
 
 
53
  export const CREATABLE_TYPES: readonly FieldType[] = [
54
  "text", "select", "multiselect", "user", "int", "currency", "pct", "date",
55
  "checkbox", "phone", "email", "url", "rating", "created_time", "formula", "automation",
56
+ "image",
57
  ];
58
 
59
+ /**
60
+ * ⭐ Wave-19 R7 / C5 β€” THE THREE THINGS AN `image` CELL MAY HOLD, and how each resolves.
61
+ *
62
+ * `rec:<id>` an upload made through this field (POST /api/v1/assets/records). Per TENANT,
63
+ * and the tenant is taken from the session on both write and read β€” never from
64
+ * the string β€” so one tenant's id can never address another's picture.
65
+ * `ed:<slug>` the editorial (non-SKU) library the catalog already addresses this way.
66
+ * anything a PRODUCT CODE. The plain form is the legacy one on purpose: Royal's masters
67
+ * else are named for `default_code`, so an untouched product row already names its
68
+ * own picture and no migration or re-upload is needed (R7).
69
+ *
70
+ * ⚠ ONE resolver, in `catalogData.assetUrl`. The catalog reached the product and editorial
71
+ * namespaces before this field existed; growing a second URL builder here is how the grid and
72
+ * the printed page would start disagreeing about which picture a row means.
73
+ */
74
+ export type ImageRefKind = "record" | "editorial" | "code";
75
+
76
+ export const RECORD_IMAGE_PREFIX = "rec:";
77
+
78
+ export function imageRefKind(value: string): ImageRefKind {
79
+ const s = value.trim();
80
+ if (s.startsWith(RECORD_IMAGE_PREFIX)) return "record";
81
+ if (s.startsWith("ed:")) return "editorial";
82
+ return "code";
83
+ }
84
+
85
  /**
86
  * Types whose CELLS never accept input, whoever the viewer is. A `formula` cell is computed
87
  * (editing it would mean editing arithmetic through a value box) and `created_time` is a fact
web/src/index.css CHANGED
The diff for this file is too large to render. See raw diff
 
web/src/settings/AdminPane.tsx ADDED
@@ -0,0 +1,568 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // settings / AdminPane.tsx β€” THE LOOPABLE ADMIN PLANE (wave 19, owner item 13 /
3
+ // R3+R4, contract C2).
4
+ //
5
+ // The one surface in this product that looks ACROSS tenants: who our customers
6
+ // are, how many people use each workspace, what they have built in it, whether
7
+ // their data sources are alive, and what the automation fleet costs.
8
+ //
9
+ // SELF-CONTAINED BY CONTRACT (C2). It fetches its own data via
10
+ // `platformAdminApi` and takes ONE prop, so mounting it is a rail entry plus a
11
+ // line in the pane switch β€” `SettingsModal.tsx` is another session's file this
12
+ // wave and must not have to learn anything about this pane's data.
13
+ //
14
+ // ⚠ THE PROP IS TYPED STRUCTURALLY, not as `SessionUser` from `../shell/session`.
15
+ // The mount site passes the shell's session user (a wider object), which
16
+ // satisfies this shape by structural typing β€” and this pane therefore imports
17
+ // nothing from the shell, which is what the wave's cross-fence rule asks for
18
+ // while `session.ts` is open on another desk.
19
+ //
20
+ // β›” EVERY NUMBER HERE IS THE SERVER'S, AND EVERY NUMBER DRILLS. Clicking a count
21
+ // opens the rows it was computed from β€” the same collector, projected twice
22
+ // ([[no-unverifiable-aggregates]]). A count that could not be READ renders as an
23
+ // em dash with the reason, never as a zero: "this customer has no databases" and
24
+ // "we could not look" are different facts and the pane refuses to conflate them.
25
+ //
26
+ // DESIGN: sentence-case micro-labels (R6 β€” no caps in app chrome), short noun
27
+ // headers, tabular figures right-aligned, hairlines not shadows, tokens only,
28
+ // no emojis (DESIGN.md Β§2–§4).
29
+ // ---------------------------------------------------------------------------
30
+
31
+ import { useCallback, useEffect, useState } from "react";
32
+ import type {
33
+ AutomationRow,
34
+ ConnectorRow,
35
+ DatabaseRow,
36
+ FleetCost,
37
+ Overview,
38
+ PlatformUser,
39
+ } from "./platformAdminApi";
40
+ import {
41
+ getAutomations,
42
+ getAws,
43
+ getConnectors,
44
+ getDatabases,
45
+ getOverview,
46
+ getUsers,
47
+ } from "./platformAdminApi";
48
+
49
+ // --- formatting -------------------------------------------------------------
50
+
51
+ const int = (n: number) => n.toLocaleString();
52
+
53
+ /** A count that may be unknown. `null` is NOT zero β€” see the api module's header. */
54
+ function Count({ n, why }: { n: number | null | undefined; why?: string }) {
55
+ if (n === null || n === undefined)
56
+ return (
57
+ <span className="padmin-unknown" title={why || "This could not be read just now"}>
58
+ β€”
59
+ </span>
60
+ );
61
+ return <>{int(n)}</>;
62
+ }
63
+
64
+ /** "3 days ago" for a stamp, "never" for an absent one. Never a fabricated date.
65
+ *
66
+ * β›” ONLY FOR OFFSET-BEARING STAMPS. `Date.parse` reads a stamp with no zone as
67
+ * BROWSER-LOCAL, so running a container-local timestamp through this reports the
68
+ * viewer's UTC offset as elapsed time β€” hours of error in a column people scan,
69
+ * and a future-dated stamp that renders as "just now" indefinitely. Everything
70
+ * this pane passes here (`last_login`, `last_active`, `generatedAt`) is written
71
+ * with an explicit offset; the automation engine's `lastRunAt` is NOT, so it is
72
+ * rendered verbatim instead. */
73
+ function ago(stamp: string): string {
74
+ if (!stamp) return "never";
75
+ const t = Date.parse(stamp.includes("T") ? stamp : stamp.replace(" ", "T"));
76
+ if (Number.isNaN(t)) return stamp;
77
+ const mins = Math.floor((Date.now() - t) / 60000);
78
+ if (mins < 2) return "just now";
79
+ if (mins < 60) return `${mins} minutes ago`;
80
+ const hours = Math.floor(mins / 60);
81
+ if (hours < 24) return `${hours} hour${hours === 1 ? "" : "s"} ago`;
82
+ const days = Math.floor(hours / 24);
83
+ if (days < 60) return `${days} day${days === 1 ? "" : "s"} ago`;
84
+ return `${Math.floor(days / 30)} months ago`;
85
+ }
86
+
87
+ type DrillKind = "users" | "databases" | "connectors" | "automations";
88
+
89
+ const DRILL_NOUN: Record<DrillKind, string> = {
90
+ users: "People",
91
+ databases: "Databases",
92
+ connectors: "Data sources",
93
+ automations: "Automations",
94
+ };
95
+
96
+ /** The loading shape β€” a skeleton, not a spinner (DESIGN.md Β§4). */
97
+ function Skeleton({ rows = 3 }: { rows?: number }) {
98
+ return (
99
+ <div className="padmin-skel" aria-hidden="true">
100
+ {Array.from({ length: rows }, (_, i) => (
101
+ <div key={i} className="padmin-skel-row" />
102
+ ))}
103
+ </div>
104
+ );
105
+ }
106
+
107
+ // --- the pane ---------------------------------------------------------------
108
+
109
+ export function AdminPane({ user }: { user: { username: string; name: string; role: string } }) {
110
+ const [ov, setOv] = useState<Overview | null>(null);
111
+ const [err, setErr] = useState("");
112
+ const [fleet, setFleet] = useState<{ rows: AutomationRow[]; cost: FleetCost } | null>(null);
113
+
114
+ const [drill, setDrill] = useState<{ kind: DrillKind; tenant: string } | null>(null);
115
+ const [drillRows, setDrillRows] = useState<unknown[] | null>(null);
116
+ const [drillNote, setDrillNote] = useState("");
117
+
118
+ const [aws, setAws] = useState<{ text: string; note: string; available: boolean } | null>(null);
119
+ const [awsBusy, setAwsBusy] = useState(false);
120
+
121
+ const load = useCallback(() => {
122
+ setOv(null);
123
+ void getOverview().then((r) => {
124
+ if (r.ok) {
125
+ setOv(r.data);
126
+ setErr("");
127
+ } else setErr(r.message);
128
+ });
129
+ void getAutomations().then((r) => {
130
+ if (r.ok) setFleet({ rows: r.data.automations, cost: r.data.cost });
131
+ });
132
+ }, []);
133
+ useEffect(load, [load]);
134
+
135
+ const openDrill = useCallback((kind: DrillKind, tenant: string) => {
136
+ setDrill({ kind, tenant });
137
+ setDrillRows(null);
138
+ setDrillNote("");
139
+ const fetcher =
140
+ kind === "users"
141
+ ? getUsers
142
+ : kind === "databases"
143
+ ? getDatabases
144
+ : kind === "connectors"
145
+ ? getConnectors
146
+ : getAutomations;
147
+ void fetcher(tenant || undefined).then((r) => {
148
+ if (!r.ok) {
149
+ setDrillRows([]);
150
+ setDrillNote(r.message);
151
+ return;
152
+ }
153
+ const d = r.data as Record<string, unknown>;
154
+ setDrillRows((d[kind] as unknown[]) ?? []);
155
+ // The server's own honest note travels with the rows rather than being
156
+ // re-invented here: it is the one that knows WHY a tenant is missing.
157
+ const errors = (d.errors as Record<string, string>) ?? {};
158
+ const words = Object.entries(errors).map(([t, e]) => `${t}: ${e}`);
159
+ setDrillNote(
160
+ [typeof d.stampsNote === "string" ? d.stampsNote : "", ...words]
161
+ .filter(Boolean)
162
+ .join(" Β· ")
163
+ );
164
+ });
165
+ }, []);
166
+
167
+ const loadAws = useCallback(() => {
168
+ setAwsBusy(true);
169
+ void getAws(7).then((r) => {
170
+ setAwsBusy(false);
171
+ if (r.ok) setAws(r.data.report);
172
+ else setAws({ text: "", note: r.message, available: false });
173
+ });
174
+ }, []);
175
+
176
+ return (
177
+ <div className="set-pane">
178
+ <h3 className="set-h">Loopable admin</h3>
179
+ <p className="set-help set-pane-intro">
180
+ Every workspace on the platform, signed in as {user.name}. Counts open the rows they were
181
+ computed from; anything that could not be read shows a dash and says why, rather than a
182
+ zero.
183
+ </p>
184
+ {err ? <p className="set-error">{err}</p> : null}
185
+
186
+ {!ov ? (
187
+ <Skeleton rows={4} />
188
+ ) : (
189
+ <>
190
+ <div className="padmin-totals">
191
+ <Total label="Workspaces" value={int(ov.totals.tenants)} />
192
+ <Total label="People" value={int(ov.totals.users)} />
193
+ <Total label="Databases" value={int(ov.totals.databases)} />
194
+ <Total label="Records" value={int(ov.totals.rows)} />
195
+ <Total
196
+ label="Automation cost"
197
+ value={fleet ? `$${fleet.cost.usd.toFixed(2)}` : "β€”"}
198
+ hint={fleet?.cost.basis}
199
+ />
200
+ </div>
201
+ {ov.totals.unknownTenants > 0 ? (
202
+ <p className="set-help padmin-caveat">
203
+ {ov.totals.unknownTenants} workspace
204
+ {ov.totals.unknownTenants === 1 ? "" : "s"} could not be read, so the totals above
205
+ exclude {ov.totals.unknownTenants === 1 ? "it" : "them"}.
206
+ </p>
207
+ ) : null}
208
+
209
+ <div className="padmin-tablewrap">
210
+ <table className="padmin-table">
211
+ <thead>
212
+ <tr>
213
+ <th>Workspace</th>
214
+ <th>Storage</th>
215
+ <th className="padmin-num">People</th>
216
+ <th className="padmin-num">Databases</th>
217
+ <th className="padmin-num">Records</th>
218
+ <th className="padmin-num">Sources</th>
219
+ <th className="padmin-num">Automations</th>
220
+ </tr>
221
+ </thead>
222
+ <tbody>
223
+ {ov.tenants.map((t) => (
224
+ <tr key={t.slug}>
225
+ <td>
226
+ <span className="padmin-name">{t.name}</span>
227
+ <span className="padmin-meta">
228
+ {t.slug}
229
+ {t.status !== "active" ? ` Β· ${t.status}` : ""}
230
+ {t.errors && t.errors.length ? ` Β· ${t.errors[0]}` : ""}
231
+ </span>
232
+ </td>
233
+ <td>
234
+ <span className="padmin-meta">
235
+ {t.storeRepo && t.storeRepo.includes("/")
236
+ ? "own repository"
237
+ : t.storePrefix
238
+ ? "shared repository"
239
+ : "tenant #0 repository"}
240
+ {t.keychainLocked ? " Β· keychain locked" : ""}
241
+ </span>
242
+ </td>
243
+ <DrillCell
244
+ n={t.users}
245
+ onOpen={() => openDrill("users", t.slug)}
246
+ title={`${t.admins} administrator${t.admins === 1 ? "" : "s"}`}
247
+ />
248
+ <DrillCell
249
+ n={t.databases}
250
+ onOpen={() => openDrill("databases", t.slug)}
251
+ why={t.errors?.[0]}
252
+ />
253
+ <DrillCell
254
+ n={t.rows}
255
+ onOpen={() => openDrill("databases", t.slug)}
256
+ why={t.errors?.[0]}
257
+ />
258
+ <DrillCell
259
+ n={t.connectors}
260
+ onOpen={() => openDrill("connectors", t.slug)}
261
+ why={t.errors?.[0]}
262
+ title={
263
+ t.connectorsPaused ? `${t.connectorsPaused} paused` : "none paused"
264
+ }
265
+ />
266
+ <DrillCell
267
+ n={t.automations}
268
+ onOpen={() => openDrill("automations", t.slug)}
269
+ why={t.errors?.[0]}
270
+ title={
271
+ t.automationsEnabled != null
272
+ ? `${t.automationsEnabled} scheduled`
273
+ : undefined
274
+ }
275
+ />
276
+ </tr>
277
+ ))}
278
+ </tbody>
279
+ </table>
280
+ </div>
281
+
282
+ <p className="set-help padmin-caveat">
283
+ Read {ago(ov.generatedAt)} in {ov.tookMs} ms.{" "}
284
+ {ov.totals.orphanUsers > 0
285
+ ? `${ov.totals.orphanUsers} account${
286
+ ov.totals.orphanUsers === 1 ? "" : "s"
287
+ } belong to a workspace this deployment no longer knows. `
288
+ : ""}
289
+ <button type="button" className="padmin-link" onClick={load}>
290
+ Refresh
291
+ </button>
292
+ </p>
293
+
294
+ {drill ? (
295
+ <section className="padmin-drill">
296
+ <div className="padmin-drill-head">
297
+ <h4 className="padmin-h4">
298
+ {DRILL_NOUN[drill.kind]}
299
+ {drill.tenant ? ` β€” ${drill.tenant}` : ""}
300
+ </h4>
301
+ <button type="button" className="padmin-link" onClick={() => setDrill(null)}>
302
+ Close
303
+ </button>
304
+ </div>
305
+ {drillRows === null ? (
306
+ <Skeleton rows={2} />
307
+ ) : drillRows.length === 0 ? (
308
+ <p className="set-help">Nothing here yet.</p>
309
+ ) : (
310
+ <DrillTable kind={drill.kind} rows={drillRows} />
311
+ )}
312
+ {drillNote ? <p className="set-help padmin-caveat">{drillNote}</p> : null}
313
+ </section>
314
+ ) : null}
315
+
316
+ {fleet ? (
317
+ <section className="padmin-block">
318
+ {/* Named for what it SHOWS. The fleet's rows live one level down,
319
+ behind the Automations count β€” this section is the cost and the
320
+ reasoning behind it, so calling it "fleet" would promise a
321
+ table that is deliberately not here. */}
322
+ <h4 className="padmin-h4">Automation cost</h4>
323
+ <p className="set-help">
324
+ {fleet.rows.filter((a) => a.enabled).length} scheduled of {fleet.rows.length}
325
+ {fleet.cost.fleetRunsPerDay
326
+ ? `, about ${fleet.cost.fleetRunsPerDay} runs a day`
327
+ : ""}
328
+ {fleet.cost.unknownCadence
329
+ ? ` (${fleet.cost.unknownCadence} on a custom cadence, not counted)`
330
+ : ""}
331
+ . {fleet.cost.basis}
332
+ </p>
333
+ </section>
334
+ ) : null}
335
+
336
+ <section className="padmin-block">
337
+ <h4 className="padmin-h4">AWS cron</h4>
338
+ {!aws ? (
339
+ <p className="set-help">
340
+ The external tick that wakes this app on schedule. Reading its usage runs a live
341
+ CloudWatch query and takes a few seconds.{" "}
342
+ <button
343
+ type="button"
344
+ className="padmin-link"
345
+ onClick={loadAws}
346
+ disabled={awsBusy}
347
+ >
348
+ {awsBusy ? "Reading…" : "Check usage"}
349
+ </button>
350
+ </p>
351
+ ) : aws.available ? (
352
+ <pre className="padmin-pre">{aws.text}</pre>
353
+ ) : (
354
+ <p className="set-help">{aws.note}</p>
355
+ )}
356
+ </section>
357
+ </>
358
+ )}
359
+ </div>
360
+ );
361
+ }
362
+
363
+ function Total({ label, value, hint }: { label: string; value: string; hint?: string }) {
364
+ // A tooltip nobody can see is a tooltip nobody reads: the label carries a
365
+ // dotted underline exactly when there is something behind it.
366
+ return (
367
+ <div className={"padmin-total" + (hint ? " has-hint" : "")} title={hint || undefined}>
368
+ <span className="padmin-total-label">{label}</span>
369
+ <span className="padmin-total-value">{value}</span>
370
+ </div>
371
+ );
372
+ }
373
+
374
+ /** A numeric cell that opens its own rows. Unknown counts are not clickable β€”
375
+ * there is nothing to drill INTO when the read failed, and a button that opens
376
+ * an empty table would read as "none". */
377
+ function DrillCell({
378
+ n,
379
+ onOpen,
380
+ why,
381
+ title,
382
+ }: {
383
+ n: number | null | undefined;
384
+ onOpen: () => void;
385
+ why?: string;
386
+ title?: string;
387
+ }) {
388
+ if (n === null || n === undefined)
389
+ return (
390
+ <td className="padmin-num">
391
+ <Count n={n} why={why} />
392
+ </td>
393
+ );
394
+ return (
395
+ <td className="padmin-num">
396
+ <button type="button" className="padmin-drill-btn" onClick={onOpen} title={title}>
397
+ {int(n)}
398
+ </button>
399
+ </td>
400
+ );
401
+ }
402
+
403
+ function DrillTable({ kind, rows }: { kind: DrillKind; rows: unknown[] }) {
404
+ if (kind === "users") {
405
+ const rs = rows as PlatformUser[];
406
+ return (
407
+ <div className="padmin-tablewrap">
408
+ <table className="padmin-table">
409
+ <thead>
410
+ <tr>
411
+ <th>Person</th>
412
+ <th>Workspace</th>
413
+ <th>Role</th>
414
+ <th>Last sign-in</th>
415
+ <th>Last active</th>
416
+ </tr>
417
+ </thead>
418
+ <tbody>
419
+ {rs.map((u) => (
420
+ <tr key={`${u.tenant}/${u.username}`}>
421
+ <td>
422
+ <span className="padmin-name">{u.name}</span>
423
+ <span className="padmin-meta">
424
+ {u.username}
425
+ {u.email ? ` Β· ${u.email}` : ""}
426
+ {u.active ? "" : " Β· deactivated"}
427
+ </span>
428
+ </td>
429
+ <td>{u.tenant}</td>
430
+ <td>
431
+ {u.role}
432
+ {u.platformAdmin ? " Β· platform" : ""}
433
+ </td>
434
+ <td>{ago(u.lastLogin)}</td>
435
+ <td>{ago(u.lastActive)}</td>
436
+ </tr>
437
+ ))}
438
+ </tbody>
439
+ </table>
440
+ </div>
441
+ );
442
+ }
443
+ if (kind === "databases") {
444
+ const rs = rows as DatabaseRow[];
445
+ return (
446
+ <div className="padmin-tablewrap">
447
+ <table className="padmin-table">
448
+ <thead>
449
+ <tr>
450
+ <th>Database</th>
451
+ <th>Workspace</th>
452
+ <th>Built from</th>
453
+ <th className="padmin-num">Fields</th>
454
+ <th className="padmin-num">Records</th>
455
+ </tr>
456
+ </thead>
457
+ <tbody>
458
+ {rs.map((d) => (
459
+ <tr key={`${d.tenant}/${d.key}`}>
460
+ <td>
461
+ <span className="padmin-name">{d.label}</span>
462
+ <span className="padmin-meta">
463
+ {d.key}
464
+ {d.createdBy ? ` Β· ${d.createdBy}` : ""}
465
+ </span>
466
+ </td>
467
+ <td>{d.tenant}</td>
468
+ <td>{d.source}</td>
469
+ <td className="padmin-num">{int(d.fields)}</td>
470
+ <td className="padmin-num">{int(d.rowCount)}</td>
471
+ </tr>
472
+ ))}
473
+ </tbody>
474
+ </table>
475
+ </div>
476
+ );
477
+ }
478
+ if (kind === "connectors") {
479
+ const rs = rows as ConnectorRow[];
480
+ return (
481
+ <div className="padmin-tablewrap">
482
+ <table className="padmin-table">
483
+ <thead>
484
+ <tr>
485
+ <th>Source</th>
486
+ <th>Workspace</th>
487
+ <th>Kind</th>
488
+ <th>Status</th>
489
+ </tr>
490
+ </thead>
491
+ <tbody>
492
+ {rs.map((c) => (
493
+ <tr key={`${c.tenant}/${c.key}`}>
494
+ <td>
495
+ <span className="padmin-name">{c.label}</span>
496
+ <span className="padmin-meta">
497
+ {c.source === "env" ? "environment credentials" : "keychain"}
498
+ </span>
499
+ </td>
500
+ <td>{c.tenant}</td>
501
+ <td>{c.type}</td>
502
+ <td>
503
+ <span
504
+ className={
505
+ "padmin-dot " +
506
+ (c.paused ? "is-paused" : c.active ? "is-live" : "is-idle")
507
+ }
508
+ />
509
+ {c.paused ? "paused" : c.active ? "serving" : "stored"}
510
+ </td>
511
+ </tr>
512
+ ))}
513
+ </tbody>
514
+ </table>
515
+ </div>
516
+ );
517
+ }
518
+ const rs = rows as AutomationRow[];
519
+ return (
520
+ <div className="padmin-tablewrap">
521
+ <table className="padmin-table">
522
+ <thead>
523
+ <tr>
524
+ <th>Automation</th>
525
+ <th>Workspace</th>
526
+ <th>Schedule</th>
527
+ <th className="padmin-num">Runs a day</th>
528
+ <th>Last run</th>
529
+ </tr>
530
+ </thead>
531
+ <tbody>
532
+ {rs.map((a) => (
533
+ <tr key={`${a.tenant}/${a.id}`}>
534
+ <td>
535
+ <span className="padmin-name">{a.name}</span>
536
+ <span className="padmin-meta">
537
+ {a.kind}
538
+ {a.failedRetained
539
+ ? ` Β· ${a.failedRetained} of the last ${a.runsRetained} runs failed`
540
+ : ""}
541
+ </span>
542
+ </td>
543
+ <td>{a.tenant}</td>
544
+ <td>{a.enabled ? a.cron || "scheduled" : "paused"}</td>
545
+ <td className="padmin-num">
546
+ {a.enabled ? (a.runsPerDay === null ? "custom" : a.runsPerDay) : "β€”"}
547
+ </td>
548
+ <td>
549
+ <span
550
+ className={
551
+ "padmin-dot " +
552
+ (a.state === "error" ? "is-error" : a.state === "ok" ? "is-live" : "is-idle")
553
+ }
554
+ />
555
+ {/* Verbatim, not relative: the engine writes this stamp with no
556
+ zone (`automation_engine._iso()` is naive local-to-container),
557
+ so "x hours ago" would be wrong by the viewer's offset. */}
558
+ {a.lastRunAt ? a.lastRunAt.replace("T", " ") : "never"}
559
+ </td>
560
+ </tr>
561
+ ))}
562
+ </tbody>
563
+ </table>
564
+ </div>
565
+ );
566
+ }
567
+
568
+ export default AdminPane;
web/src/settings/SettingsModal.tsx CHANGED
@@ -7,12 +7,19 @@
7
  // that exact thing for when we click Settings and Manage User, where the
8
  // background is clearly blurred too."*
9
  //
10
- // ⚠ WAVE 15 R12 β€” THE SURFACE IS CALLED "PROFILE" NOW, in this shell only. The
11
- // file, the export and the `SettingsSection` type keep their names deliberately:
12
- // the ruling renames a LABEL, and renaming the module would ripple through the
13
- // shell, the gate's source list and every import for no user-visible gain. The
14
- // Streamlit host keeps "Settings" β€” the two runtimes are allowed to disagree
15
- // about a word while one of them is being deleted.
 
 
 
 
 
 
 
16
  //
17
  // A MODAL, NOT A PAGE, and the shipped version's reasoning holds here too:
18
  // settings are a detour, not a destination β€” you change a toggle and go back to
@@ -27,6 +34,7 @@
27
  // ---------------------------------------------------------------------------
28
 
29
  import { useCallback, useEffect, useRef, useState } from "react";
 
30
  import type { SessionUser } from "../shell/session";
31
  import { isAdmin, parseUserEnvelope } from "../shell/session";
32
  import type { AdminUser, SettingsPayload } from "./settingsApi";
@@ -46,6 +54,8 @@ import {
46
  } from "./settingsApi";
47
  import type { ConnectorRow, KeyEntry, UnsyncedInfo } from "./settingsApi";
48
  import { PermsEditor } from "./PermsEditor";
 
 
49
  import { moduleSummary, parseEntry, reachableSection } from "./permsModel";
50
 
51
  // The vocabulary lives beside the rule that gates it (permsModel), and is
@@ -79,6 +89,74 @@ function ChevIcon() {
79
  );
80
  }
81
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
82
  function UsersPane() {
83
  const [users, setUsers] = useState<AdminUser[] | null>(null);
84
  const [error, setError] = useState("");
@@ -175,7 +253,12 @@ function UsersPane() {
175
 
176
  return (
177
  <div className="set-pane">
178
- <h3 className="set-h">Accounts</h3>
 
 
 
 
 
179
  {error ? <p className="set-error">{error}</p> : null}
180
  {notice ? <p className="set-notice">{notice}</p> : null}
181
 
@@ -604,6 +687,8 @@ export function SettingsModal({
604
  }) {
605
  const [settings, setSettings] = useState<SettingsPayload | null>(null);
606
  const admin = isAdmin(user);
 
 
607
 
608
  useEffect(() => {
609
  void getSettings().then((r) => {
@@ -621,23 +706,44 @@ export function SettingsModal({
621
  return () => window.removeEventListener("keydown", onKey);
622
  }, [onClose]);
623
 
624
- const rail: Array<[SettingsSection, string]> = [
625
- ["account", "Account"],
626
- ["scope", "Your access"],
 
 
627
  ...(admin
628
  ? ([
629
- ["users", "Manage users"],
630
  // Wave 18 (C7): the tenant's credential store + data-source status board.
631
- ["keychains", "Keychains"],
632
- ["connectors", "Connectors"],
633
- ] as Array<[SettingsSection, string]>)
 
 
 
 
 
 
 
 
 
634
  : []),
635
  ];
636
  // A non-admin deep-linked to the users pane lands on Account rather than on
637
  // an empty frame. The server would refuse the data anyway; this just avoids
638
  // showing a room with nothing in it. The rule is a NAMED function so the gate
639
  // can negative-control it β€” see `permsModel.reachableSection`.
640
- const active = reachableSection(section, admin);
 
 
 
 
 
 
 
 
 
 
641
 
642
  return (
643
  <div
@@ -646,33 +752,45 @@ export function SettingsModal({
646
  if (e.target === e.currentTarget) onClose();
647
  }}
648
  >
649
- {/* ⚠ WAVE 15 R12 β€” the modal is "Profile" in the staging shell. The
650
- accessible name tracks the visible one on purpose: a dialog a screen
651
- reader announces as "Settings" while the rail reads "Profile" is the
652
- same drift as a stale comment, only harder to notice. Manage users is
653
- still a SECTION inside it (R12 is a rename, not a re-architecture). */}
654
- <div className="set-modal" role="dialog" aria-modal="true" aria-label="Profile">
 
655
  <nav className="set-rail">
656
- <span className="set-rail-cap">Profile</span>
657
- {rail.map(([key, label]) => (
658
  <button
659
  key={key}
660
  type="button"
661
  className={"set-rail-item" + (active === key ? " is-active" : "")}
662
  onClick={() => onSection(key)}
663
  >
 
664
  {label}
665
  </button>
666
  ))}
667
  </nav>
668
 
669
  <div className="set-body">
670
- <button type="button" className="set-close" onClick={onClose} aria-label="Close profile">
671
  Γ—
672
  </button>
673
 
674
  {active === "keychains" ? <KeychainPane /> : null}
675
  {active === "connectors" ? <ConnectorsPane /> : null}
 
 
 
 
 
 
 
 
 
 
676
 
677
  {active === "account" ? (
678
  <div className="set-pane">
 
7
  // that exact thing for when we click Settings and Manage User, where the
8
  // background is clearly blurred too."*
9
  //
10
+ // ⚠ WAVE 19 R12 β€” THE SURFACE IS CALLED "SETTINGS" AGAIN, and this note replaces
11
+ // the wave-15 one that said the opposite ("the surface is called PROFILE now, in
12
+ // this shell only"). The owner has ruled the rename back: one account-menu row,
13
+ // called Settings, with a gear, shown to everyone, landing on Account. The file,
14
+ // the export and the `SettingsSection` type were never renamed in either
15
+ // direction β€” which is exactly why the wave-15 trade was the right one to make
16
+ // and the cheap one to undo. A LABEL moved twice; no import ever did.
17
+ //
18
+ // β›” `verify_ui.py`'s naming check enforced the wave-15 wording, so the correct
19
+ // edit would have turned it red. It is inverted in the same change (bare
20
+ // "Profile" must not survive as copy; bare "Settings" must be PRESENT) and
21
+ // booked as wave-19 amendment 1. A gate that pins a superseded ruling is not a
22
+ // gate, it is a second place the old decision lives.
23
  //
24
  // A MODAL, NOT A PAGE, and the shipped version's reasoning holds here too:
25
  // settings are a detour, not a destination β€” you change a toggle and go back to
 
34
  // ---------------------------------------------------------------------------
35
 
36
  import { useCallback, useEffect, useRef, useState } from "react";
37
+ import type { ReactNode } from "react";
38
  import type { SessionUser } from "../shell/session";
39
  import { isAdmin, parseUserEnvelope } from "../shell/session";
40
  import type { AdminUser, SettingsPayload } from "./settingsApi";
 
54
  } from "./settingsApi";
55
  import type { ConnectorRow, KeyEntry, UnsyncedInfo } from "./settingsApi";
56
  import { PermsEditor } from "./PermsEditor";
57
+ // Wave 19 contract C2 β€” session D's self-contained plane; see the mount below.
58
+ import { AdminPane } from "./AdminPane";
59
  import { moduleSummary, parseEntry, reachableSection } from "./permsModel";
60
 
61
  // The vocabulary lives beside the rule that gates it (permsModel), and is
 
89
  );
90
  }
91
 
92
+ // ── WAVE 19 R13: one mark per rail tab ───────────────────────────────────────
93
+ //
94
+ // The rail was five words in a column, and at a glance five words in a column is
95
+ // a list you read rather than a place you navigate. A mark per row is what makes
96
+ // "Keychains" findable without reading "Connectors" first.
97
+ //
98
+ // ⚠ PURE FUNCTIONS OF NOTHING, and that is a requirement here rather than a
99
+ // style: `verify_ui.py` renders this module through `react-dom/server`, where
100
+ // `window` and `document` do not exist. An icon that measured anything, or read
101
+ // a theme off the DOM at module scope, would take the whole gate down with it β€”
102
+ // and the failure would look like a broken gate rather than a broken icon.
103
+ // SVG only, never emoji (the platform's own standing rule).
104
+ function RailIcon({ children }: { children: ReactNode }) {
105
+ return (
106
+ <svg className="set-rail-icon" viewBox="0 0 16 16" aria-hidden="true">
107
+ {children}
108
+ </svg>
109
+ );
110
+ }
111
+
112
+ /** Account β€” the person whose settings these are. */
113
+ const IconAccount = (
114
+ <RailIcon>
115
+ <circle cx="8" cy="5.6" r="2.7" />
116
+ <path d="M2.9 13.4c0-2.5 2.3-4.1 5.1-4.1s5.1 1.6 5.1 4.1" />
117
+ </RailIcon>
118
+ );
119
+ /** Your access β€” a closed padlock: what this account may open, and what narrows it. */
120
+ const IconAccess = (
121
+ <RailIcon>
122
+ <rect x="3.3" y="7.1" width="9.4" height="6.3" rx="1.3" />
123
+ <path d="M5.6 7.1V5.3a2.4 2.4 0 0 1 4.8 0v1.8" />
124
+ </RailIcon>
125
+ );
126
+ /** Manage users β€” more than one person. */
127
+ const IconUsers = (
128
+ <RailIcon>
129
+ <circle cx="6.2" cy="5.9" r="2.3" />
130
+ <path d="M1.9 13.2c0-2.2 1.9-3.5 4.3-3.5s4.3 1.3 4.3 3.5" />
131
+ <path d="M10.7 4.1a2.3 2.3 0 0 1 0 4.3M11.6 9.9c1.5.4 2.5 1.5 2.5 3.3" />
132
+ </RailIcon>
133
+ );
134
+ /** Keychains β€” a key. */
135
+ const IconKey = (
136
+ <RailIcon>
137
+ <circle cx="5.4" cy="10.6" r="2.6" />
138
+ <path d="M7.3 8.8 13.1 3M11 5.1l1.5 1.5M9.4 6.7l1.4 1.4" />
139
+ </RailIcon>
140
+ );
141
+ /** Connectors β€” two links joined: where the data comes from. */
142
+ const IconPlug = (
143
+ <RailIcon>
144
+ <path d="M6.6 9.4 4.5 11.5a2.6 2.6 0 0 1-3.7-3.7l2.1-2.1" />
145
+ <path d="M9.4 6.6l2.1-2.1a2.6 2.6 0 0 1 3.7 3.7l-2.1 2.1" />
146
+ <path d="M6.2 9.8l3.6-3.6" />
147
+ </RailIcon>
148
+ );
149
+ /** Loopable admin β€” stacked plates, i.e. MANY tenants. Deliberately not another
150
+ * lock or shield: "Your access" already wears a padlock, and two authority
151
+ * glyphs in one rail would read as two grades of the same thing rather than as
152
+ * a different scope entirely. */
153
+ const IconTenants = (
154
+ <RailIcon>
155
+ <path d="M8 1.9 14.3 5 8 8.1 1.7 5z" />
156
+ <path d="M2.4 8.1 8 10.9l5.6-2.8M2.4 11.2 8 14l5.6-2.8" />
157
+ </RailIcon>
158
+ );
159
+
160
  function UsersPane() {
161
  const [users, setUsers] = useState<AdminUser[] | null>(null);
162
  const [error, setError] = useState("");
 
253
 
254
  return (
255
  <div className="set-pane">
256
+ {/* ⚠ WAVE 19 (owner item 9) β€” THE HEADING MATCHES THE RAIL ENTRY THAT
257
+ OPENS IT. It said "Accounts" while the only way in was a tab reading
258
+ "Manage users", so the pane appeared to be somewhere other than the
259
+ place that was clicked β€” the cheapest kind of "am I in the right
260
+ screen?" there is. The rail is the name; the body agrees with it. */}
261
+ <h3 className="set-h">Manage users</h3>
262
  {error ? <p className="set-error">{error}</p> : null}
263
  {notice ? <p className="set-notice">{notice}</p> : null}
264
 
 
687
  }) {
688
  const [settings, setSettings] = useState<SettingsPayload | null>(null);
689
  const admin = isAdmin(user);
690
+ // Wave 19 (C2) β€” `=== true`, not truthy: absent or malformed reads as NO.
691
+ const platformAdmin = settings?.platformAdmin === true;
692
 
693
  useEffect(() => {
694
  void getSettings().then((r) => {
 
706
  return () => window.removeEventListener("keydown", onKey);
707
  }, [onClose]);
708
 
709
+ // WAVE 19 R13 β€” the tuple grew a third member: the tab's mark. ONE data change
710
+ // and one line in the render loop below, which is the whole of the ruling.
711
+ const rail: Array<[SettingsSection, string, ReactNode]> = [
712
+ ["account", "Account", IconAccount],
713
+ ["scope", "Your access", IconAccess],
714
  ...(admin
715
  ? ([
716
+ ["users", "Manage users", IconUsers],
717
  // Wave 18 (C7): the tenant's credential store + data-source status board.
718
+ ["keychains", "Keychains", IconKey],
719
+ ["connectors", "Connectors", IconPlug],
720
+ ] as Array<[SettingsSection, string, ReactNode]>)
721
+ : []),
722
+ // Wave 19 (R3 / C2): the Loopable admin plane. Gated on the SERVER's
723
+ // `platformAdmin`, never on `admin` β€” R3 is explicit that a tenant-scoped
724
+ // admin does not qualify, so this entry appears for exactly one account and
725
+ // is invisible to every tenant admin in the product.
726
+ ...(platformAdmin
727
+ ? ([["padmin", "Loopable admin", IconTenants]] as Array<
728
+ [SettingsSection, string, ReactNode]
729
+ >)
730
  : []),
731
  ];
732
  // A non-admin deep-linked to the users pane lands on Account rather than on
733
  // an empty frame. The server would refuse the data anyway; this just avoids
734
  // showing a room with nothing in it. The rule is a NAMED function so the gate
735
  // can negative-control it β€” see `permsModel.reachableSection`.
736
+ //
737
+ // β›” `padmin` IS GATED HERE, NOT IN THAT FUNCTION, and the reason is that its
738
+ // input does not exist there. `reachableSection` takes `admin` β€” a boolean off
739
+ // the user record β€” while `platformAdmin` arrives asynchronously on the
740
+ // settings payload and (per R3) is NOT implied by tenant admin. Passing it
741
+ // through `reachableSection` would have meant either widening that function's
742
+ // signature and re-aiming a negative control that guards a different rule, or
743
+ // conflating the two admin concepts the ruling exists to keep apart. Composed
744
+ // instead: the section falls back to Account until the server has said yes.
745
+ const active =
746
+ section === "padmin" && !platformAdmin ? "account" : reachableSection(section, admin);
747
 
748
  return (
749
  <div
 
752
  if (e.target === e.currentTarget) onClose();
753
  }}
754
  >
755
+ {/* ⚠ WAVE 19 R12 β€” the modal is "Settings", and the ACCESSIBLE name tracks
756
+ the visible one, which is the half that is easy to forget. A dialog a
757
+ screen reader announces as "Profile" while the rail reads "Settings" is
758
+ the same drift as a stale comment, only harder to notice: nobody
759
+ looking at the screen can see it. Manage users is still a SECTION
760
+ inside it (R12 is a rename, not a re-architecture). */}
761
+ <div className="set-modal" role="dialog" aria-modal="true" aria-label="Settings">
762
  <nav className="set-rail">
763
+ <span className="set-rail-cap">Settings</span>
764
+ {rail.map(([key, label, icon]) => (
765
  <button
766
  key={key}
767
  type="button"
768
  className={"set-rail-item" + (active === key ? " is-active" : "")}
769
  onClick={() => onSection(key)}
770
  >
771
+ {icon}
772
  {label}
773
  </button>
774
  ))}
775
  </nav>
776
 
777
  <div className="set-body">
778
+ <button type="button" className="set-close" onClick={onClose} aria-label="Close settings">
779
  Γ—
780
  </button>
781
 
782
  {active === "keychains" ? <KeychainPane /> : null}
783
  {active === "connectors" ? <ConnectorsPane /> : null}
784
+ {/* Wave 19 contract C2 β€” the wiring record, verified at the MOUNT SITE
785
+ (the wave-14 lesson: an occurrence-grep proves an import, not a
786
+ render): `settings/AdminPane.tsx β†’ SettingsModal.tsx pane switch β†’
787
+ prop user`. The pane is session D's, self-contained: it fetches its
788
+ own data and owns its loading/empty/error states, so mounting it
789
+ cannot fail on plumbing. Its prop is typed STRUCTURALLY on D's side
790
+ ({username; name; role}), so the shell's `SessionUser` satisfies it
791
+ by structural typing β€” no cast here, and no import from `shell/`
792
+ there. `active` cannot be "padmin" unless the server said so. */}
793
+ {active === "padmin" ? <AdminPane user={user} /> : null}
794
 
795
  {active === "account" ? (
796
  <div className="set-pane">
web/src/settings/permsModel.ts CHANGED
@@ -43,7 +43,21 @@ export type SettingsSection =
43
  | "users"
44
  // Wave 18 (C7): the tenant's credential store and its data-source status board.
45
  | "keychains"
46
- | "connectors";
 
 
 
 
 
 
 
 
 
 
 
 
 
 
47
 
48
  /**
49
  * A non-admin never LANDS on the users pane β€” and therefore never reaches the
@@ -121,6 +135,11 @@ const FIELD_TYPE_TABLE: Record<FieldType, true> = {
121
  select: true, user: true, multiselect: true, checkbox: true, phone: true,
122
  email: true, url: true, rating: true, created_time: true, formula: true,
123
  automation: true,
 
 
 
 
 
124
  };
125
 
126
  export const KNOWN_FIELD_TYPES: ReadonlySet<string> = new Set(Object.keys(FIELD_TYPE_TABLE));
 
43
  | "users"
44
  // Wave 18 (C7): the tenant's credential store and its data-source status board.
45
  | "keychains"
46
+ | "connectors"
47
+ /**
48
+ * Wave 19 (R3 / contract C2): the Loopable admin plane β€” the cross-TENANT
49
+ * console, visible only to a `platform_admin` account.
50
+ *
51
+ * β›” DELIBERATELY ABSENT FROM `reachableSection` BELOW, and that is not an
52
+ * oversight. Every other admin room is gated on `admin`, a boolean the shell
53
+ * already holds on the user record. `platform_admin` is a different predicate
54
+ * that arrives ASYNCHRONOUSLY on the settings payload β€” and R3 is explicit
55
+ * that a tenant-scoped `is_admin` does NOT qualify for it. Folding it into a
56
+ * function whose only input is `admin` would either grant the section to every
57
+ * tenant admin or deny it to the one account that has it. It is gated where
58
+ * the flag actually lives, at the render site in `SettingsModal`.
59
+ */
60
+ | "padmin";
61
 
62
  /**
63
  * A non-admin never LANDS on the users pane β€” and therefore never reaches the
 
135
  select: true, user: true, multiselect: true, checkbox: true, phone: true,
136
  email: true, url: true, rating: true, created_time: true, formula: true,
137
  automation: true,
138
+ // Wave-19 R7 (added by session A β€” see the dated amendment in the split doc). This ONE key is
139
+ // the whole edit: the exhaustiveness alarm above did exactly what it promises, and the fix it
140
+ // names is a listing here. Nowhere near `SettingsSection` / the rail, which is B's half of
141
+ // this file.
142
+ image: true,
143
  };
144
 
145
  export const KNOWN_FIELD_TYPES: ReadonlySet<string> = new Set(Object.keys(FIELD_TYPE_TABLE));
web/src/settings/platformAdminApi.ts ADDED
@@ -0,0 +1,224 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // settings / platformAdminApi.ts β€” the Loopable admin plane's client half
3
+ // (wave 19, owner item 13 / R3+R4, contract C2).
4
+ //
5
+ // β›” THE CLIENT HIDES; THE SERVER FORBIDS. Every route here is walled by
6
+ // `core.platform_admin.is_platform_admin` β€” a double lock (the record flag AND
7
+ // the `loopable` tenant), fail-closed, proven by `verify_api.py` enumerating the
8
+ // router and having a tenant admin try every path. The `platformAdmin` flag on
9
+ // `GET /settings` exists so the rail does not paint a door that would 403; it is
10
+ // never the permission ([[aios-permissioning]]).
11
+ //
12
+ // SELF-CONTAINED BY CONTRACT (C2). This module and `AdminPane.tsx` are the only
13
+ // two files the admin plane owns on the client, and they import nothing from the
14
+ // rest of `settings/` β€” the pane fetches its own data, so mounting it is one line
15
+ // in the rail and one line in the pane switch.
16
+ //
17
+ // ⚠ NULL IS A REAL VALUE HERE, AND IT IS NOT ZERO. Any per-tenant count can come
18
+ // back `null`, meaning "that subsystem could not be read for this customer" β€” a
19
+ // suspended tenant record, a locked keychain, an HF repo that did not answer.
20
+ // Rendering it as 0 would tell an operator a customer has no databases when the
21
+ // truth is that we did not look. The types say `number | null` for exactly that
22
+ // reason and the pane renders the difference.
23
+ // ---------------------------------------------------------------------------
24
+
25
+ import { API_V1, CREDENTIALS } from "../apiContract";
26
+
27
+ export type ApiResult<T> = { ok: true; data: T } | { ok: false; status: number; message: string };
28
+
29
+ async function call<T>(path: string): Promise<ApiResult<T>> {
30
+ try {
31
+ const res = await fetch(`${API_V1}/platform-admin${path}`, { credentials: CREDENTIALS });
32
+ let body: unknown = null;
33
+ try {
34
+ body = await res.json();
35
+ } catch {
36
+ /* an unreadable body is handled below, never thrown at the pane */
37
+ }
38
+ if (!res.ok) {
39
+ const err = (body as { error?: { message?: string } } | null)?.error;
40
+ const message =
41
+ res.status >= 500
42
+ ? "Something went wrong on our side. Try again in a moment."
43
+ : err?.message ||
44
+ (res.status === 403
45
+ ? "This surface is not available to your account."
46
+ : "That could not be loaded.");
47
+ return { ok: false, status: res.status, message };
48
+ }
49
+ return { ok: true, data: body as T };
50
+ } catch {
51
+ return { ok: false, status: 0, message: "The server could not be reached." };
52
+ }
53
+ }
54
+
55
+ /** One customer. `error` / `errors` carry the honest reason a count is null. */
56
+ export interface TenantRow {
57
+ slug: string;
58
+ name: string;
59
+ /** `record` = provisioned into the control-plane bucket; `compiled` = tenant #0. */
60
+ source: string;
61
+ status: string;
62
+ domains: string[];
63
+ modules: string[] | "all";
64
+ /** R2: a dedicated dataset repo, or the shared repo. The isolation shape. */
65
+ storeRepo: string;
66
+ storePrefix: string;
67
+ error: string;
68
+ users: number;
69
+ admins: number;
70
+ databases: number | null;
71
+ rows: number | null;
72
+ connectors: number | null;
73
+ connectorsPaused?: number | null;
74
+ automations: number | null;
75
+ automationsEnabled?: number | null;
76
+ keychainLocked?: boolean | null;
77
+ errors?: string[];
78
+ }
79
+
80
+ export interface Overview {
81
+ tenants: TenantRow[];
82
+ totals: {
83
+ tenants: number;
84
+ users: number;
85
+ orphanUsers: number;
86
+ databases: number;
87
+ rows: number;
88
+ automations: number;
89
+ unknownTenants: number;
90
+ };
91
+ storeAvailable: boolean;
92
+ generatedAt: string;
93
+ tookMs: number;
94
+ }
95
+
96
+ export interface PlatformUser {
97
+ username: string;
98
+ name: string;
99
+ email: string;
100
+ tenant: string;
101
+ role: string;
102
+ active: boolean;
103
+ /** R4 β€” absent means never, and the pane says "never" rather than inventing a date. */
104
+ lastLogin: string;
105
+ lastActive: string;
106
+ platformAdmin: boolean;
107
+ }
108
+
109
+ export interface DatabaseRow {
110
+ tenant: string;
111
+ key: string;
112
+ label: string;
113
+ source: string;
114
+ createdBy: string;
115
+ created: string;
116
+ fields: number;
117
+ rowCount: number;
118
+ }
119
+
120
+ export interface ConnectorRow {
121
+ tenant: string;
122
+ key: string;
123
+ label: string;
124
+ type: string;
125
+ source: string;
126
+ active: boolean;
127
+ paused: boolean;
128
+ }
129
+
130
+ export interface AutomationRow {
131
+ tenant: string;
132
+ id: string;
133
+ name: string;
134
+ kind: string;
135
+ enabled: boolean;
136
+ cron: string;
137
+ /** null = a cadence the server would not parse; shown as "custom", never as a number. */
138
+ runsPerDay: number | null;
139
+ state: string;
140
+ lastRunAt: string;
141
+ lastSummary: string;
142
+ runsRetained: number;
143
+ failedRetained: number;
144
+ createdBy: string;
145
+ created: string;
146
+ }
147
+
148
+ export interface FleetCost {
149
+ cadence: string;
150
+ invocationsPerMonth: number;
151
+ freeRequestsPct: number;
152
+ freeSchedulerPct: number;
153
+ lambdaMb: number;
154
+ usd: number;
155
+ fleetRunsPerDay: number;
156
+ unknownCadence: number;
157
+ basis: string;
158
+ }
159
+
160
+ export interface AwsReport {
161
+ available: boolean;
162
+ text: string;
163
+ note: string;
164
+ }
165
+
166
+ export function getOverview(): Promise<ApiResult<Overview>> {
167
+ return call<Overview>("/overview");
168
+ }
169
+
170
+ /** `tenant` narrows every drill; omitted, they answer for the whole platform. */
171
+ const q = (tenant?: string) => (tenant ? `?tenant=${encodeURIComponent(tenant)}` : "");
172
+
173
+ export function getUsers(
174
+ tenant?: string
175
+ ): Promise<ApiResult<{ users: PlatformUser[]; count: number; stampsNote: string }>> {
176
+ return call(`/users${q(tenant)}`);
177
+ }
178
+
179
+ export function getDatabases(
180
+ tenant?: string
181
+ ): Promise<
182
+ ApiResult<{
183
+ databases: DatabaseRow[];
184
+ count: number;
185
+ rows: number;
186
+ errors: Record<string, string>;
187
+ }>
188
+ > {
189
+ return call(`/databases${q(tenant)}`);
190
+ }
191
+
192
+ export function getConnectors(
193
+ tenant?: string
194
+ ): Promise<
195
+ ApiResult<{
196
+ connectors: ConnectorRow[];
197
+ count: number;
198
+ keychainLocked: Record<string, boolean>;
199
+ errors: Record<string, string>;
200
+ note: string;
201
+ }>
202
+ > {
203
+ return call(`/connectors${q(tenant)}`);
204
+ }
205
+
206
+ export function getAutomations(
207
+ tenant?: string
208
+ ): Promise<
209
+ ApiResult<{
210
+ automations: AutomationRow[];
211
+ count: number;
212
+ enabled: number;
213
+ historyRetained: number;
214
+ cost: FleetCost;
215
+ errors: Record<string, string>;
216
+ tickEnabled: boolean;
217
+ }>
218
+ > {
219
+ return call(`/automations${q(tenant)}`);
220
+ }
221
+
222
+ export function getAws(days = 7): Promise<ApiResult<{ days: number; report: AwsReport }>> {
223
+ return call(`/aws?days=${encodeURIComponent(String(days))}`);
224
+ }
web/src/settings/settingsApi.ts CHANGED
@@ -61,6 +61,22 @@ export interface SettingsPayload {
61
  perms?: Record<string, unknown>;
62
  };
63
  tenant?: Record<string, unknown>;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
64
  }
65
 
66
  export type ApiResult<T> =
 
61
  perms?: Record<string, unknown>;
62
  };
63
  tenant?: Record<string, unknown>;
64
+ /**
65
+ * Wave 19 (R3 / contract C2) β€” is this account the LOOPABLE PLATFORM ADMIN?
66
+ *
67
+ * β›” NOT `admin`, AND THE DISTINCTION IS THE WHOLE RULING. `admin` is
68
+ * tenant-scoped: every tenant has them, and R3 says in as many words that a
69
+ * tenant-scoped `is_admin` does NOT qualify for this. This flag comes from a
70
+ * separate fail-closed server predicate (record flag AND `tenant == "loopable"`,
71
+ * a double lock) and is true for exactly one account.
72
+ *
73
+ * ⚠ CHROME, NEVER THE WALL. It decides whether a rail entry is drawn. Every
74
+ * route behind that entry 403s a non-platform-admin on its own, so a client
75
+ * that forged this flag would reach a pane whose every fetch is refused.
76
+ * Optional on purpose: a server that predates the field, or one that omits it,
77
+ * reads as `false` β€” fail-closed by absence, like every other flag here.
78
+ */
79
+ platformAdmin?: boolean;
80
  }
81
 
82
  export type ApiResult<T> =
web/src/shell/NavExtras.tsx CHANGED
@@ -14,6 +14,23 @@ import { useEffect, useRef, useState } from "react";
14
  import type { ReactNode } from "react";
15
  import { fetchSchema } from "./nav";
16
  import type { NavFolder, SchemaPayload } from "./nav";
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
17
  import "./navExtras.css";
18
 
19
  function DotsIcon() {
@@ -83,20 +100,122 @@ function MenuShell({
83
  );
84
  }
85
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
86
  export function RowMenu({
87
  entryLabel,
88
  canSchema,
89
  onSchema,
 
 
 
 
 
 
90
  }: {
91
  entryLabel: string;
92
  canSchema: boolean;
93
  onSchema: () => void;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
94
  }) {
95
- // Wave 14 C-NAVFOLD (ruling R10): the three-dots keeps "View schema" ONLY. Folder
96
- // placement is a DRAG now (the Views-rail gesture, items 4/6), folder ops live on the
97
- // folder rows, and "New folder" is the quiet + at the list's bottom.
98
  const { at, ref, openFrom, close } = useMenu();
99
- if (!canSchema) return null;
 
 
 
 
 
 
 
 
 
 
 
100
  return (
101
  <>
102
  <button
@@ -107,6 +226,8 @@ export function RowMenu({
107
  onClick={(e) => {
108
  e.preventDefault();
109
  e.stopPropagation();
 
 
110
  openFrom(e.currentTarget);
111
  }}
112
  >
@@ -114,45 +235,203 @@ export function RowMenu({
114
  </button>
115
  {at && (
116
  <MenuShell at={at} menuRef={ref}>
117
- <button
118
- type="button"
119
- className="shell-navmenu-item"
120
- onClick={() => {
121
- close();
122
- onSchema();
123
- }}
124
- >
125
- View schema
126
- </button>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
127
  </MenuShell>
128
  )}
129
  </>
130
  );
131
  }
132
 
133
- /** Wave 14 C-NAVFOLD β€” the quiet "+ New folder" affordance at the list's bottom (the
134
- * Views-rail precedent), replacing the RowMenu's creator. */
135
- export function NewFolderRow({ onCreate }: { onCreate: (name: string) => void }) {
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
136
  const [naming, setNaming] = useState(false);
137
  const [name, setName] = useState("");
138
  const submit = () => {
139
  const clean = name.trim().replace(/\s+/g, " ");
140
  if (!clean) return;
141
- onCreate(clean);
142
  setName("");
143
  setNaming(false);
144
  };
145
- if (!naming) {
 
 
 
146
  return (
147
  <button
148
  type="button"
149
- className="shell-newfolder"
150
- onClick={() => setNaming(true)}
 
 
151
  >
152
- + New folder
153
  </button>
154
  );
155
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
156
  return (
157
  <form
158
  className="shell-navmenu-form shell-newfolder-form"
 
14
  import type { ReactNode } from "react";
15
  import { fetchSchema } from "./nav";
16
  import type { NavFolder, SchemaPayload } from "./nav";
17
+ // ⚠ WAVE 19 R8 / C1 β€” IMPORTED, NEVER REDEFINED, and the contract says so in as
18
+ // many words ("Shapes/tones = the grid's existing vocabulary verbatim (12
19
+ // shapes, 5 tones); B imports, never redefines"). A second copy of this
20
+ // vocabulary in the shell is a whitelist that can drift by one member from the
21
+ // one the host validates against β€” and a tone the server does not recognise
22
+ // degrades to the default, so the user's choice disappears on reload with
23
+ // nothing on screen to say why. These are READ-ONLY imports across the session
24
+ // fence: `customer-grid/**` is another session's tree this wave (HARD RULE 3).
25
+ import { FolderMark } from "../customer-grid/icons";
26
+ import { FOLDER_SHAPE_LABELS, FOLDER_TONE_LABELS } from "../customer-grid/iconShapes";
27
+ import {
28
+ DEFAULT_FOLDER_SHAPE,
29
+ DEFAULT_FOLDER_TONE,
30
+ FOLDER_SHAPES,
31
+ FOLDER_TONES,
32
+ } from "../customer-grid/types";
33
+ import type { FolderIcon } from "../customer-grid/types";
34
  import "./navExtras.css";
35
 
36
  function DotsIcon() {
 
100
  );
101
  }
102
 
103
+ /**
104
+ * WAVE 19 R8 / C1 β€” the 12x5 swatch picker, the grid's own pattern
105
+ * (`ViewSidebar.tsx`'s folder form) rendered inside the nav's popover.
106
+ *
107
+ * TWO ROWS, NOT A GRID OF 60. Shape and tone are independent choices, so the
108
+ * shape row previews in the CURRENT tone and the tone row previews in the
109
+ * CURRENT shape β€” every swatch shows what that one click would actually
110
+ * produce, which is why picking is one glance rather than a search.
111
+ */
112
+ function IconPicker({
113
+ value,
114
+ onPick,
115
+ onClear,
116
+ }: {
117
+ value?: FolderIcon;
118
+ onPick: (icon: FolderIcon) => void;
119
+ /** Absent β‡’ nothing to clear (the row is already on the default mark). */
120
+ onClear?: () => void;
121
+ }) {
122
+ const shape = value?.shape ?? DEFAULT_FOLDER_SHAPE;
123
+ const tone = value?.tone ?? DEFAULT_FOLDER_TONE;
124
+ return (
125
+ <div className="shell-navmenu-pick" role="group" aria-label="Database icon">
126
+ <div className="shell-navmenu-pickrow">
127
+ {FOLDER_SHAPES.map((s) => (
128
+ <button
129
+ key={s}
130
+ type="button"
131
+ className={"shell-navmenu-swatch" + (value && shape === s ? " is-on" : "")}
132
+ aria-pressed={!!value && shape === s}
133
+ aria-label={FOLDER_SHAPE_LABELS[s]}
134
+ title={FOLDER_SHAPE_LABELS[s]}
135
+ onClick={() => onPick({ shape: s, tone })}
136
+ >
137
+ <FolderMark icon={{ shape: s, tone }} size={15} />
138
+ </button>
139
+ ))}
140
+ </div>
141
+ <div className="shell-navmenu-pickrow">
142
+ {FOLDER_TONES.map((t) => (
143
+ <button
144
+ key={t}
145
+ type="button"
146
+ className={"shell-navmenu-swatch" + (value && tone === t ? " is-on" : "")}
147
+ aria-pressed={!!value && tone === t}
148
+ aria-label={FOLDER_TONE_LABELS[t]}
149
+ title={FOLDER_TONE_LABELS[t]}
150
+ onClick={() => onPick({ shape, tone: t })}
151
+ >
152
+ <FolderMark icon={{ shape, tone: t }} size={15} />
153
+ </button>
154
+ ))}
155
+ </div>
156
+ {/* β›” AN EXPLICIT WAY BACK, because this picker deliberately does NOT copy
157
+ `cleanFolderIcon`'s "a fully-default icon is no icon" rule. That rule is
158
+ right for a FOLDER, whose default mark IS the folder shape; a database's
159
+ default mark is the cylinder, so dropping folder+neutral would answer a
160
+ user who picked "Folder" with a picture of a database β€” the silent
161
+ disappearance the tone whitelist's own note warns about. Absent = the
162
+ cylinder, chosen = exactly what was chosen, and clearing is a click that
163
+ says what it does. */}
164
+ {onClear ? (
165
+ <button type="button" className="shell-navmenu-item is-quiet" onClick={onClear}>
166
+ Use the default icon
167
+ </button>
168
+ ) : null}
169
+ </div>
170
+ );
171
+ }
172
+
173
  export function RowMenu({
174
  entryLabel,
175
  canSchema,
176
  onSchema,
177
+ canRename,
178
+ onRename,
179
+ canIcon,
180
+ icon,
181
+ onIcon,
182
+ onIconClear,
183
  }: {
184
  entryLabel: string;
185
  canSchema: boolean;
186
  onSchema: () => void;
187
+ /**
188
+ * WAVE 19 R8 β€” rename is `ut_*` (custom) DATABASES ONLY, and this flag is how
189
+ * the row says so. A built-in label is a compiled registry literal: renaming
190
+ * `customer_data` would mean the nav and every other reader of
191
+ * `core/registry.py` disagreeing about what the module is called. The SERVER
192
+ * refuses a `name` for a non-`ut_` key regardless (C1, fail-closed) β€” this
193
+ * only spares the user a control whose write would bounce.
194
+ */
195
+ canRename?: boolean;
196
+ onRename?: (name: string) => void;
197
+ /** Icons ride ALL databases (R8), unlike rename. */
198
+ canIcon?: boolean;
199
+ icon?: FolderIcon;
200
+ onIcon?: (icon: FolderIcon) => void;
201
+ onIconClear?: () => void;
202
  }) {
203
+ // Wave 14 C-NAVFOLD (ruling R10): the three-dots kept "View schema" ONLY.
204
+ // Wave 19 (R8/C1) adds Rename and Change icon β€” the first two things a
205
+ // database the USER made should have been able to do.
206
  const { at, ref, openFrom, close } = useMenu();
207
+ // Which face the popover is showing. Reset on every open, so a menu that was
208
+ // left mid-rename does not reopen into somebody else's half-typed name.
209
+ const [mode, setMode] = useState<"menu" | "rename" | "icon">("menu");
210
+ const [name, setName] = useState(entryLabel);
211
+ const renameOn = !!canRename && !!onRename;
212
+ const iconOn = !!canIcon && !!onIcon;
213
+ if (!canSchema && !renameOn && !iconOn) return null;
214
+ const submitRename = () => {
215
+ const clean = name.trim().replace(/\s+/g, " ");
216
+ if (clean && clean !== entryLabel) onRename?.(clean);
217
+ close();
218
+ };
219
  return (
220
  <>
221
  <button
 
226
  onClick={(e) => {
227
  e.preventDefault();
228
  e.stopPropagation();
229
+ setMode("menu");
230
+ setName(entryLabel);
231
  openFrom(e.currentTarget);
232
  }}
233
  >
 
235
  </button>
236
  {at && (
237
  <MenuShell at={at} menuRef={ref}>
238
+ {mode === "rename" && renameOn ? (
239
+ <form
240
+ className="shell-navmenu-form"
241
+ onSubmit={(e) => {
242
+ e.preventDefault();
243
+ submitRename();
244
+ }}
245
+ >
246
+ <input
247
+ className="shell-navmenu-input"
248
+ autoFocus
249
+ maxLength={60}
250
+ value={name}
251
+ aria-label={`Rename ${entryLabel}`}
252
+ onChange={(e) => setName(e.target.value)}
253
+ onKeyDown={(e) => {
254
+ if (e.key === "Escape") close();
255
+ }}
256
+ />
257
+ <button type="submit" className="shell-navmenu-go" disabled={!name.trim()}>
258
+ Save
259
+ </button>
260
+ </form>
261
+ ) : mode === "icon" && iconOn ? (
262
+ /* ⚠ PICKING DOES NOT CLOSE THE MENU, and that is not a convenience.
263
+ Shape and tone are two independent choices: a picker that closed
264
+ on the first click would make "a green bolt" a two-open job, and
265
+ the second open would have to find the row again. Each click
266
+ commits (they are cheap and rare), the rail repaints from the
267
+ server, and the swatch marks follow what was actually stored β€” so
268
+ a refused write shows up as a mark that does not move, beside the
269
+ toast that says why. Clearing DOES close: "use the default" is a
270
+ terminal action, and the control removes itself once taken. */
271
+ <IconPicker
272
+ value={icon}
273
+ onPick={(next) => onIcon?.(next)}
274
+ {...(icon && onIconClear
275
+ ? {
276
+ onClear: () => {
277
+ close();
278
+ onIconClear();
279
+ },
280
+ }
281
+ : {})}
282
+ />
283
+ ) : (
284
+ <>
285
+ {renameOn ? (
286
+ <button
287
+ type="button"
288
+ className="shell-navmenu-item"
289
+ onClick={() => setMode("rename")}
290
+ >
291
+ Rename
292
+ </button>
293
+ ) : null}
294
+ {iconOn ? (
295
+ <button
296
+ type="button"
297
+ className="shell-navmenu-item"
298
+ onClick={() => setMode("icon")}
299
+ >
300
+ Change icon
301
+ </button>
302
+ ) : null}
303
+ {canSchema ? (
304
+ <button
305
+ type="button"
306
+ className="shell-navmenu-item"
307
+ onClick={() => {
308
+ close();
309
+ onSchema();
310
+ }}
311
+ >
312
+ View schema
313
+ </button>
314
+ ) : null}
315
+ </>
316
+ )}
317
  </MenuShell>
318
  )}
319
  </>
320
  );
321
  }
322
 
323
+ function PlusIcon() {
324
+ return (
325
+ <svg viewBox="0 0 16 16" aria-hidden="true" className="shell-newthing-plus">
326
+ <path d="M8 3.4v9.2M3.4 8h9.2" />
327
+ </svg>
328
+ );
329
+ }
330
+
331
+ /**
332
+ * Wave 14 C-NAVFOLD gave the list's bottom a quiet "+ New folder" (the Views-rail
333
+ * precedent). WAVE 19 R11 makes it "+ Create new…" and puts BOTH creatable things
334
+ * behind it β€” Folder | Database β€” folding away the standalone "+ New database"
335
+ * button that used to sit below the rail with its own odd chrome.
336
+ *
337
+ * ⚠ IT RENDERS FOR A TENANT WITH NO DATABASES AT ALL, which the row it replaced
338
+ * did and the row it grew out of did not. "+ New folder" was gated on
339
+ * `entries.length > 0` (folders over nothing are pointless); "+ New database" was
340
+ * not, deliberately β€” a freshly provisioned tenant's rail has nothing else to
341
+ * offer, and Shell.tsx's own note calls it "the honest affordance in the tenant
342
+ * case". Folding the second into the first without moving that gate would have
343
+ * left a brand-new workspace with a rail you cannot create anything from.
344
+ */
345
+ export function CreateNewRow({
346
+ collapsed,
347
+ onExpand,
348
+ onCreateFolder,
349
+ onNewDatabase,
350
+ canFolder,
351
+ }: {
352
+ collapsed: boolean;
353
+ /** Collapsed, the row's one honest behaviour is "open the rail first". */
354
+ onExpand: () => void;
355
+ onCreateFolder: (name: string) => void;
356
+ onNewDatabase: () => void;
357
+ /** Folders over an empty list are an empty gesture β€” Database only, then. */
358
+ canFolder: boolean;
359
+ }) {
360
+ const { at, ref, openFrom, close } = useMenu();
361
  const [naming, setNaming] = useState(false);
362
  const [name, setName] = useState("");
363
  const submit = () => {
364
  const clean = name.trim().replace(/\s+/g, " ");
365
  if (!clean) return;
366
+ onCreateFolder(clean);
367
  setName("");
368
  setNaming(false);
369
  };
370
+ // β›” The 56px strip cannot hold a popover β€” the same reason the account row
371
+ // expands instead of opening its menu. Preserved from the button this row
372
+ // replaced, which did exactly this before opening its dialog.
373
+ if (collapsed) {
374
  return (
375
  <button
376
  type="button"
377
+ className="shell-newfolder is-collapsed"
378
+ aria-label="Create new"
379
+ title="Create new"
380
+ onClick={onExpand}
381
  >
382
+ <PlusIcon />
383
  </button>
384
  );
385
  }
386
+ if (!naming) {
387
+ return (
388
+ <>
389
+ {/* ⚠ THE ROW SAYS WHAT IT WILL DO. With no databases yet there is nothing
390
+ to file, so the chooser has one real branch β€” and "+ Create new…"
391
+ beside a `aria-haspopup` that opens a dialog instead of a menu is a
392
+ control promising a choice it is not about to offer. The label and the
393
+ popup hint both follow `canFolder`. */}
394
+ <button
395
+ type="button"
396
+ className="shell-newfolder"
397
+ {...(canFolder ? { "aria-haspopup": "menu" as const } : {})}
398
+ onClick={(e) => {
399
+ if (!canFolder) {
400
+ onNewDatabase();
401
+ return;
402
+ }
403
+ openFrom(e.currentTarget);
404
+ }}
405
+ >
406
+ {canFolder ? "+ Create new…" : "+ New database"}
407
+ </button>
408
+ {at && (
409
+ <MenuShell at={at} menuRef={ref}>
410
+ <button
411
+ type="button"
412
+ className="shell-navmenu-item"
413
+ onClick={() => {
414
+ close();
415
+ setNaming(true);
416
+ }}
417
+ >
418
+ New folder
419
+ </button>
420
+ <button
421
+ type="button"
422
+ className="shell-navmenu-item"
423
+ onClick={() => {
424
+ close();
425
+ onNewDatabase();
426
+ }}
427
+ >
428
+ New database
429
+ </button>
430
+ </MenuShell>
431
+ )}
432
+ </>
433
+ );
434
+ }
435
  return (
436
  <form
437
  className="shell-navmenu-form shell-newfolder-form"
web/src/shell/Shell.tsx CHANGED
@@ -42,9 +42,12 @@ import { SettingsModal } from "../settings/SettingsModal";
42
  import type { SettingsSection } from "../settings/SettingsModal";
43
  import { Brand } from "./Brand";
44
  import LoginPage from "./LoginPage";
45
- import { EMPTY_NAV_PREFS, ENVELOPE_KEYS, MAX_NAV_FOLDERS, appLink, defaultRoute, fetchNav, fetchNavPrefs, foldNav, resolveRoute, saveNavPrefs, shapeNav, splitChrome } from "./nav";
46
- import type { NavEntry, NavPage, NavPrefs } from "./nav";
47
- import { FolderHead, NewFolderRow, RowMenu, SchemaDrawer } from "./NavExtras";
 
 
 
48
  import { isAdmin, logout, me } from "./session";
49
  import type { SessionUser } from "./session";
50
 
@@ -148,6 +151,32 @@ function DotsIcon() {
148
  );
149
  }
150
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
151
  /** Owner item 11 β€” the rail toggle: three horizontal bars. One glyph for both rails (the
152
  * views rail draws the same geometry), so "minimize a panel" reads as one idea. */
153
  function RailToggleIcon() {
@@ -212,15 +241,23 @@ function AccountMenu({
212
  <div className="shell-account-wrap" ref={wrap}>
213
  {open ? (
214
  <div className="shell-menu" role="menu">
215
- {/* Two entry points, ONE modal β€” "Manage users" just lands on a
216
- different rail entry. Admin-only is a courtesy here; the server
217
- refuses `/admin/*` to a member regardless.
 
 
 
 
 
 
 
 
 
 
218
 
219
- ⚠ WAVE 15 R12 β€” "Settings" is "Profile" HERE AND NOWHERE ELSE. The
220
- Streamlit host keeps its own "Settings", deliberately: the rename
221
- is about what THIS door calls the page you reach from your own
222
- account row, and a strangler period is not the moment to make two
223
- runtimes disagree about a registry key. */}
224
  <button
225
  type="button"
226
  className="shell-menu-item"
@@ -230,21 +267,9 @@ function AccountMenu({
230
  onSettings("account");
231
  }}
232
  >
233
- Profile
 
234
  </button>
235
- {isAdmin(user) ? (
236
- <button
237
- type="button"
238
- className="shell-menu-item"
239
- role="menuitem"
240
- onClick={() => {
241
- setOpen(false);
242
- onSettings("users");
243
- }}
244
- >
245
- Manage users
246
- </button>
247
- ) : null}
248
  {extras.length ? <div className="shell-menu-rule" role="separator" /> : null}
249
  {extras.map((p) => (
250
  <a
@@ -318,7 +343,11 @@ export default function Shell() {
318
  const [session, setSession] = useState<Session>({ phase: "checking" });
319
  const [nav, setNav] = useState<Nav>({ phase: "idle" });
320
  // Wave 18 (C3-UT): bumped after "+ New database" so the rail refetches and the new ut_ key
321
- // appears without a reload. Nothing else may bump it β€” the nav stays server-driven.
 
 
 
 
322
  const [navEpoch, setNavEpoch] = useState(0);
323
  const [dataError, setDataError] = useState("");
324
  const [toast, setToast] = useState("");
@@ -412,7 +441,25 @@ export default function Shell() {
412
  return;
413
  }
414
  let dead = false;
415
- setNav({ phase: "loading" });
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
416
  // ⚠ Clear the last session's failures. Without this, a read error survives
417
  // a sign-out/sign-in and the freshly authenticated user lands on an error
418
  // panel describing something that happened to somebody else's session.
@@ -537,6 +584,21 @@ export default function Shell() {
537
  [commitPrefs]
538
  );
539
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
540
  // Keep the URL honest in both directions: an anonymous shell sits on
541
  // `#/login`, and a signed-in one never does.
542
  useEffect(() => {
@@ -666,6 +728,26 @@ export default function Shell() {
666
  const active = resolveRoute(entries, route);
667
  const utility = nav.phase === "ready" ? nav.utility : NO_UTILITY;
668
  const analyst = utility.find((p) => p.key === "analyst");
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
669
 
670
  return (
671
  <div className="shell-root">
@@ -722,6 +804,43 @@ export default function Shell() {
722
  </button>
723
  ) : null}
724
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
725
  <div
726
  className={
727
  "shell-nav-list" + (dropTarget === "__root__" ? " is-drop-root" : "")
@@ -748,7 +867,7 @@ export default function Shell() {
748
  {/* C-SCHEMA: the list folds under the user's folders. The collapsed
749
  rail renders FLAT (folder chrome has no room at 44px) β€” members
750
  stay reachable, the folders wait for the rail to open. */}
751
- {foldNav(entries, navCollapsed ? EMPTY_NAV_PREFS : navPrefs, closedFolders).map(
752
  (row) => {
753
  if (row.kind === "folder") {
754
  return (
@@ -795,7 +914,22 @@ export default function Shell() {
795
  (isActive ? " is-active" : "");
796
  const inner = (
797
  <>
798
- <DbIcon />
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
799
  <span className="shell-nav-label">{item.label}</span>
800
  {/* A hand-off opens the current application in a new tab; the
801
  arrow declares that before the click finds out. */}
@@ -865,15 +999,55 @@ export default function Shell() {
865
  entryLabel={item.label}
866
  canSchema
867
  onSchema={() => setSchemaFor(item.key)}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
868
  />
869
  )}
870
  </div>
871
  );
872
  }
873
  )}
874
- {/* Wave 14 C-NAVFOLD β€” the folder creator moved here from the row menu (R10). */}
875
- {!navCollapsed && nav.phase === "ready" && entries.length > 0 ? (
876
- <NewFolderRow onCreate={createFolder} />
 
 
 
 
 
 
 
 
 
 
 
 
 
877
  ) : null}
878
  </div>
879
  {/* Wave 17 item 3 (R6) β€” the mark, never the word. "Loading…" under an
@@ -898,25 +1072,15 @@ export default function Shell() {
898
  {nav.phase === "ready" && entries.length === 0 && !tenantEmptyState ? (
899
  <div className="shell-nav-note">No surfaces are available to this account.</div>
900
  ) : null}
901
- {/* Wave 18 (C3-UT / R4): a database the USER creates β€” the second branch of the
902
- owner's "+ New" flow (connectors are Settings' half). Collapsed rail expands
903
- first: a modal opened from a 56px strip reads as coming from nowhere. */}
904
- <button
905
- type="button"
906
- className="shell-nav-item shell-nav-newdb"
907
- onClick={() => {
908
- if (navCollapsed) setNavCollapsed(false);
909
- setNewDb({ name: "", busy: false, err: "" });
910
- }}
911
- onMouseEnter={navCollapsed ? tipEnter("New database") : undefined}
912
- onMouseLeave={navCollapsed ? tipLeave : undefined}
913
- >
914
- <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true">
915
- <path d="M8 3.4v9.2M3.4 8h9.2" stroke="currentColor" strokeWidth="1.5"
916
- strokeLinecap="round" fill="none" />
917
- </svg>
918
- <span className="shell-nav-label">New database</span>
919
- </button>
920
  </nav>
921
 
922
  <div
@@ -1036,8 +1200,10 @@ export default function Shell() {
1036
  <div className="shell-placeholder shell-tenant-hero">
1037
  <h1>Welcome</h1>
1038
  <p>
 
 
1039
  This workspace has no databases yet. Create your first one below, or store a
1040
- data source's keys under Profile β†’ Keychains to connect one later.
1041
  </p>
1042
  <button
1043
  className="login-submit shell-hero-create"
 
42
  import type { SettingsSection } from "../settings/SettingsModal";
43
  import { Brand } from "./Brand";
44
  import LoginPage from "./LoginPage";
45
+ import { EMPTY_NAV_PREFS, ENVELOPE_KEYS, MAX_NAV_FOLDERS, appLink, defaultRoute, fetchNav, fetchNavPrefs, foldNav, resolveRoute, saveNavMeta, saveNavPrefs, shapeNav, splitChrome } from "./nav";
46
+ import type { NavEntry, NavMetaPatch, NavPage, NavPrefs } from "./nav";
47
+ import { CreateNewRow, FolderHead, RowMenu, SchemaDrawer } from "./NavExtras";
48
+ // WAVE 19 R8 β€” the chosen database mark. Read-only across the session fence.
49
+ import { FolderMark } from "../customer-grid/icons";
50
+ import type { FolderIcon } from "../customer-grid/types";
51
  import { isAdmin, logout, me } from "./session";
52
  import type { SessionUser } from "./session";
53
 
 
151
  );
152
  }
153
 
154
+ /** WAVE 19 R12 β€” the gear beside the account menu's one Settings row. Drawn in
155
+ * the same 16x16 stroke vocabulary as the rest of this file (SVG, never an
156
+ * emoji β€” the platform's own rule), so it sits beside `DbIcon` and `SparkIcon`
157
+ * as one family rather than as an icon borrowed from somewhere else. */
158
+ function GearIcon() {
159
+ return (
160
+ <svg className="shell-menu-icon" viewBox="0 0 16 16" aria-hidden="true">
161
+ <circle cx="8" cy="8" r="2.15" />
162
+ <path d="M8 1.9l.9 1.5 1.7-.4.5 1.7 1.7.5-.4 1.7 1.2 1.1-1.2 1.1.4 1.7-1.7.5-.5 1.7-1.7-.4-.9 1.5-.9-1.5-1.7.4-.5-1.7-1.7-.5.4-1.7L1.7 8l1.2-1.1-.4-1.7 1.7-.5.5-1.7 1.7.4z" />
163
+ </svg>
164
+ );
165
+ }
166
+
167
+ /** WAVE 19 R10 β€” Automation's own mark, now that it is a standalone rail button
168
+ * rather than a row in the database list. Two nodes and the edge between them:
169
+ * a flow, which is what the surface actually is, and visibly not a database. */
170
+ function AutoIcon() {
171
+ return (
172
+ <svg className="shell-nav-icon" viewBox="0 0 16 16" aria-hidden="true">
173
+ <rect x="1.9" y="5.4" width="4.6" height="5.2" rx="1.1" />
174
+ <rect x="9.5" y="5.4" width="4.6" height="5.2" rx="1.1" />
175
+ <path d="M6.5 8h3" />
176
+ </svg>
177
+ );
178
+ }
179
+
180
  /** Owner item 11 β€” the rail toggle: three horizontal bars. One glyph for both rails (the
181
  * views rail draws the same geometry), so "minimize a panel" reads as one idea. */
182
  function RailToggleIcon() {
 
241
  <div className="shell-account-wrap" ref={wrap}>
242
  {open ? (
243
  <div className="shell-menu" role="menu">
244
+ {/* ⚠ WAVE 19 R12 SUPERSEDES WAVE 15 R12, IN BOTH HALVES.
245
+ Wave 15 renamed this row "Settings" β†’ "Profile" and kept a second,
246
+ admin-only "Manage users" beside it. The owner has now ruled the
247
+ opposite: ONE row, called **Settings**, with a gear, shown to
248
+ EVERYONE, landing on Account β€” and admins meet "Manage users" where
249
+ it always really lived, as a tab in the modal's own rail.
250
+
251
+ The two rows were the problem, not either label. They opened the
252
+ SAME modal at two different tabs, so the account menu was quietly
253
+ acting as a second navigation for a surface that already has one;
254
+ an admin had to decide which door to use before knowing which tab
255
+ they wanted. Landing everyone on Account and letting the rail do
256
+ the rest removes the decision.
257
 
258
+ β›” `verify_ui.py`'s naming gate was inverted in the same change
259
+ (its R12 check asserted the wave-15 wording, so it would have gone
260
+ red on the correct edit). Wave-19 amendment 1 in the wave doc. */}
 
 
261
  <button
262
  type="button"
263
  className="shell-menu-item"
 
267
  onSettings("account");
268
  }}
269
  >
270
+ <GearIcon />
271
+ Settings
272
  </button>
 
 
 
 
 
 
 
 
 
 
 
 
 
273
  {extras.length ? <div className="shell-menu-rule" role="separator" /> : null}
274
  {extras.map((p) => (
275
  <a
 
343
  const [session, setSession] = useState<Session>({ phase: "checking" });
344
  const [nav, setNav] = useState<Nav>({ phase: "idle" });
345
  // Wave 18 (C3-UT): bumped after "+ New database" so the rail refetches and the new ut_ key
346
+ // appears without a reload. Wave 19 (R8/C1) adds the second and only other bumper β€” a
347
+ // rename or an icon change, for the same reason: the override lives in the SERVER's nav
348
+ // payload, so the rail re-asks rather than the client inventing what the answer will be.
349
+ // Both bumps are "the server changed, ask it again"; nothing may bump this to paint state
350
+ // the server does not hold β€” the nav stays server-driven.
351
  const [navEpoch, setNavEpoch] = useState(0);
352
  const [dataError, setDataError] = useState("");
353
  const [toast, setToast] = useState("");
 
441
  return;
442
  }
443
  let dead = false;
444
+ // ⚠ WAVE 19 β€” STALE-WHILE-REFRESH, and this line is why the icon picker works
445
+ // at all. This effect re-runs on every `navEpoch` bump, and it used to blank
446
+ // the nav to `loading` each time: `entries` reads as `NO_ENTRIES` whenever the
447
+ // phase is not `ready`, so the whole database list unmounted behind a spinner
448
+ // and remounted a round trip later. Every row's `RowMenu` went with it β€”
449
+ // taking the OPEN icon picker's state with it, so "pick a shape, then pick a
450
+ // tone" was impossible and every click flashed the rail. "+ Create new…"
451
+ // (gated on `ready`) disappeared too.
452
+ //
453
+ // It was invisible before because the only bumper was "+ New database", which
454
+ // navigates away in the same beat. R8 made the bump a frequent, EXPLORATORY
455
+ // action, which is what turned a flash into a broken control.
456
+ //
457
+ // β›” SAFE ACROSS ACCOUNTS, which is the only thing that could make it
458
+ // dangerous: an account switch always passes through `anon` (sign-out, or the
459
+ // 401 event), so `who` becomes null, this effect takes the branch above and
460
+ // sets `idle` β€” a stale nav can never survive into a different session's
461
+ // render. Same stale-while-refresh doctrine the data cache already follows.
462
+ setNav((cur) => (cur.phase === "ready" ? cur : { phase: "loading" }));
463
  // ⚠ Clear the last session's failures. Without this, a read error survives
464
  // a sign-out/sign-in and the freshly authenticated user lands on an error
465
  // panel describing something that happened to somebody else's session.
 
584
  [commitPrefs]
585
  );
586
 
587
+ // ── WAVE 19 R8 / C1: the tenant-wide name + icon overrides (`nav_meta`) ──────
588
+ //
589
+ // ⚠ NOT OPTIMISTIC, unlike `commitPrefs` two blocks up, and the asymmetry is
590
+ // the point. Prefs are this user's own arrangement held in this component's
591
+ // state, so the rail can move now and revert if the write is refused.
592
+ // `nav_meta` is TENANT-WIDE and lives in the SERVER's nav payload β€” the shell
593
+ // holds no copy to update. Painting a new name locally would mean rendering a
594
+ // label from one source while every other reader of the nav still had the old
595
+ // one; re-asking is one cheap round trip and it cannot disagree with itself.
596
+ const commitNavMeta = useCallback(async (key: string, patch: NavMetaPatch) => {
597
+ const ok = await saveNavMeta(key, patch);
598
+ if (ok) setNavEpoch((e) => e + 1);
599
+ else setToast("That change was not saved β€” the store refused the write.");
600
+ }, []);
601
+
602
  // Keep the URL honest in both directions: an anonymous shell sits on
603
  // `#/login`, and a signed-in one never does.
604
  useEffect(() => {
 
728
  const active = resolveRoute(entries, route);
729
  const utility = nav.phase === "ready" ? nav.utility : NO_UTILITY;
730
  const analyst = utility.find((p) => p.key === "analyst");
731
+ // ── WAVE 19 R10 / C3: Automation LEAVES THE DATABASE LIST ────────────────────
732
+ //
733
+ // Strategy A, chosen at the grill: a CLIENT-SIDE relocation. The registry row,
734
+ // `NATIVE_KEYS`, the API payload and the `#/automation` render branch below are
735
+ // all untouched β€” Automation is still a granted surface the server decides on,
736
+ // it simply stops being drawn among the databases, because it is not one.
737
+ //
738
+ // ⚠ THE FILTER FEEDS `foldNav`, IT IS NOT APPLIED INSIDE THE `.map()`, and the
739
+ // difference is a bug you would find weeks later. `foldNav` counts a folder's
740
+ // members from `prefs.placement`, so a user who had already dragged Automation
741
+ // into a folder would get a folder head reading "1" with nothing underneath it
742
+ // β€” the count derived from a list that still had the row, the rows drawn from
743
+ // one that did not.
744
+ //
745
+ // β›” AND `entries` STAYS WHOLE. `resolveRoute`, `active`, `defaultRoute`, the
746
+ // empty-nav note and `tenantEmptyState` all read it: filtering there would
747
+ // break the hash route this button navigates to, and would tell a tenant whose
748
+ // only granted surface is Automation that it has no surfaces at all.
749
+ const automation = entries.find((e) => e.key === "automation" && e.kind === "native");
750
+ const dbEntries = automation ? entries.filter((e) => e.key !== "automation") : entries;
751
 
752
  return (
753
  <div className="shell-root">
 
804
  </button>
805
  ) : null}
806
 
807
+ {/* WAVE 19 R10 / C3 β€” Automation, directly under "AI assistant" and
808
+ above the hairline that opens the database band. An `<a>` to the
809
+ route it already had: the surface, its rail and its editor are
810
+ another session's tree this wave and are not touched by any of
811
+ this. The LABEL comes off the payload, never a literal here β€” the
812
+ registry owns what this surface is called, and a client that
813
+ hard-codes the word is the drift that outlives the row. */}
814
+ {automation ? (
815
+ <a
816
+ className={
817
+ "shell-nav-item shell-nav-auto" +
818
+ (active && active.key === automation.key ? " is-active" : "")
819
+ }
820
+ href={automation.href}
821
+ onMouseEnter={navCollapsed ? tipEnter(automation.label) : undefined}
822
+ onMouseLeave={navCollapsed ? tipLeave : undefined}
823
+ >
824
+ {/* ⚠ R8 lists Automation among the databases that get an icon
825
+ ("Customer/Product/Automation/custom"); R10 moves it out of the
826
+ list where the β‹― that SETS one lives. So it DISPLAYS a chosen
827
+ mark β€” the store and the route already accept `automation` as a
828
+ key β€” while the entry point to choose one is the open question
829
+ booked as amendment 6 for the integrator. Rendering the default
830
+ glyph unconditionally would have made this the one database
831
+ that could never show an icon, which is the half of R8 a client
832
+ has no business deciding. */}
833
+ {automation.icon ? (
834
+ <span className="shell-nav-mark" aria-hidden="true">
835
+ <FolderMark icon={automation.icon} size={16} />
836
+ </span>
837
+ ) : (
838
+ <AutoIcon />
839
+ )}
840
+ <span className="shell-nav-label">{automation.label}</span>
841
+ </a>
842
+ ) : null}
843
+
844
  <div
845
  className={
846
  "shell-nav-list" + (dropTarget === "__root__" ? " is-drop-root" : "")
 
867
  {/* C-SCHEMA: the list folds under the user's folders. The collapsed
868
  rail renders FLAT (folder chrome has no room at 44px) β€” members
869
  stay reachable, the folders wait for the rail to open. */}
870
+ {foldNav(dbEntries, navCollapsed ? EMPTY_NAV_PREFS : navPrefs, closedFolders).map(
871
  (row) => {
872
  if (row.kind === "folder") {
873
  return (
 
914
  (isActive ? " is-active" : "");
915
  const inner = (
916
  <>
917
+ {/* WAVE 19 R8 β€” the tenant's chosen mark, or the cylinder.
918
+ ⚠ `FolderMark` paints its OWN pastel fill and `-deep`
919
+ stroke, so it must not wear `.shell-nav-icon` (which sets
920
+ `stroke: currentColor` and dims to 0.55 β€” that rule would
921
+ repaint a deliberately-coloured glyph in the row's ink and
922
+ then half-erase it). The wrapper span carries only the
923
+ box, which is why the class is the shell's own and not the
924
+ grid's `.cg-folder-mark`: that one belongs to another
925
+ session's CSS region this wave. */}
926
+ {item.icon ? (
927
+ <span className="shell-nav-mark" aria-hidden="true">
928
+ <FolderMark icon={item.icon} size={16} />
929
+ </span>
930
+ ) : (
931
+ <DbIcon />
932
+ )}
933
  <span className="shell-nav-label">{item.label}</span>
934
  {/* A hand-off opens the current application in a new tab; the
935
  arrow declares that before the click finds out. */}
 
999
  entryLabel={item.label}
1000
  canSchema
1001
  onSchema={() => setSchemaFor(item.key)}
1002
+ // ── WAVE 19 R8 / C1, walled by R14 ──────────────────
1003
+ // RENAME is `ut_*` only: a built-in label is a compiled
1004
+ // registry literal, and renaming one would leave the nav
1005
+ // and every other reader of `core/registry.py` calling
1006
+ // the same module two different things. ICONS ride every
1007
+ // database β€” that half of R8 is explicitly "ALL".
1008
+ //
1009
+ // β›” WHO MAY IS THE SERVER'S ANSWER, NOT A ROLE CHECK
1010
+ // HERE. R14 put the `ut_` half on `user_tables.may_open`
1011
+ // β€” the table's CREATOR or a tenant admin β€” and this
1012
+ // client cannot see who created a user table. So the nav
1013
+ // payload carries `manage` per row and the rail simply
1014
+ // obeys it. Absent reads as NO (fail-closed), and
1015
+ // `POST /nav/meta` re-checks regardless: this is the
1016
+ // courtesy half of "the client hides, the server
1017
+ // forbids", the same one `reachableSection` pays in
1018
+ // Settings. An earlier build gated on `isAdmin` here and
1019
+ // was wrong in the direction that matters β€” it hid a
1020
+ // control from the person who owned the thing.
1021
+ canRename={!!item.manage && item.key.startsWith("ut_")}
1022
+ onRename={(name) => void commitNavMeta(item.key, { name })}
1023
+ canIcon={!!item.manage}
1024
+ {...(item.icon ? { icon: item.icon } : {})}
1025
+ onIcon={(icon: FolderIcon) =>
1026
+ void commitNavMeta(item.key, { icon })
1027
+ }
1028
+ onIconClear={() => void commitNavMeta(item.key, { icon: null })}
1029
  />
1030
  )}
1031
  </div>
1032
  );
1033
  }
1034
  )}
1035
+ {/* Wave 14 C-NAVFOLD β€” the folder creator moved here from the row menu (R10).
1036
+ WAVE 19 R11 β€” and "+ New database" moved INTO it: one "+ Create new…" row
1037
+ offering Folder | Database, replacing two affordances that sat in different
1038
+ places and looked like different kinds of thing.
1039
+ ⚠ The `entries.length > 0` gate that used to guard this row is now the
1040
+ `canFolder` PROP, not a reason to hide the row: a tenant with no databases
1041
+ has nothing to file in a folder but is exactly the tenant who needs to make
1042
+ a database. It renders whenever the nav has answered. */}
1043
+ {nav.phase === "ready" ? (
1044
+ <CreateNewRow
1045
+ collapsed={navCollapsed}
1046
+ onExpand={() => setNavCollapsed(false)}
1047
+ onCreateFolder={createFolder}
1048
+ onNewDatabase={() => setNewDb({ name: "", busy: false, err: "" })}
1049
+ canFolder={entries.length > 0}
1050
+ />
1051
  ) : null}
1052
  </div>
1053
  {/* Wave 17 item 3 (R6) β€” the mark, never the word. "Loading…" under an
 
1072
  {nav.phase === "ready" && entries.length === 0 && !tenantEmptyState ? (
1073
  <div className="shell-nav-note">No surfaces are available to this account.</div>
1074
  ) : null}
1075
+ {/* β›” THE STANDALONE "+ New database" BUTTON WAS HERE, AND WAVE 19 R11 FOLDED
1076
+ IT INTO "+ Create new…" at the bottom of the database list above. It was the
1077
+ louder half of the owner's complaint about this rail: a `<button>` wearing the
1078
+ user agent's border and grey fill (this class never reset either β€” see the
1079
+ index.css note), sitting BELOW the list's own quiet "+ New folder" and offering
1080
+ a sibling action in a completely different visual register. One row, one place,
1081
+ two things to create. The collapsed-rail behaviour it carried survives inside
1082
+ `CreateNewRow`: from the 56px strip the "+" opens the rail rather than a
1083
+ popover that would read as coming from nowhere. */}
 
 
 
 
 
 
 
 
 
 
1084
  </nav>
1085
 
1086
  <div
 
1200
  <div className="shell-placeholder shell-tenant-hero">
1201
  <h1>Welcome</h1>
1202
  <p>
1203
+ {/* WAVE 19 R12 β€” the pointer follows the rename. A sentence naming a
1204
+ door by its old label is a wrong instruction, not a stale comment. */}
1205
  This workspace has no databases yet. Create your first one below, or store a
1206
+ data source's keys under Settings β†’ Keychains to connect one later.
1207
  </p>
1208
  <button
1209
  className="login-submit shell-hero-create"
web/src/shell/nav.ts CHANGED
@@ -20,6 +20,16 @@
20
  // ---------------------------------------------------------------------------
21
 
22
  import { API_V1, CREDENTIALS } from "../apiContract";
 
 
 
 
 
 
 
 
 
 
23
 
24
  /** One entry of X2's nav payload. `source` is the registry's connector fact
25
  * (wave-9 I8: "Sales Β· Odoo"); `parent` names a sub-module's family head. */
@@ -46,6 +56,45 @@ export interface NavPage {
46
  * `nav_pages`' docstring says "the client places them where the host does".
47
  */
48
  chrome?: "main" | "utility";
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
49
  }
50
 
51
  /**
@@ -70,6 +119,8 @@ export function parsePages(body: unknown): NavPage[] {
70
  ...(typeof p.parent === "string" && p.parent ? { parent: p.parent } : {}),
71
  ...(p.group_only === true ? { group_only: true } : {}),
72
  ...(p.chrome === "main" || p.chrome === "utility" ? { chrome: p.chrome } : {}),
 
 
73
  });
74
  }
75
  return out;
@@ -186,6 +237,42 @@ export async function saveNavPrefs(prefs: NavPrefs): Promise<boolean> {
186
  }
187
  }
188
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
189
  /** One rendered row of the folded nav: a folder head, or an entry (optionally inside one). */
190
  export type NavRow =
191
  | { kind: "folder"; folder: NavFolder; count: number; open: boolean }
@@ -329,6 +416,11 @@ export interface NavEntry {
329
  depth: number;
330
  /** Absent for a group head β€” there is nowhere to go. */
331
  href?: string;
 
 
 
 
 
332
  }
333
 
334
  /**
@@ -418,6 +510,8 @@ export function shapeNav(pages: NavPage[], appBase: string): NavEntry[] {
418
  key: p.key,
419
  label: p.label,
420
  ...(p.source ? { source: p.source } : {}),
 
 
421
  kind,
422
  depth,
423
  ...(kind === "group"
 
20
  // ---------------------------------------------------------------------------
21
 
22
  import { API_V1, CREDENTIALS } from "../apiContract";
23
+ // ⚠ WAVE 19 R8 / C1 β€” the icon vocabulary is the GRID's, imported not redefined.
24
+ // A VALUE import (not type-only) because the whitelist has to exist at runtime:
25
+ // `FolderMark` indexes `FOLDER_SHAPE_PATHS[shape]` and maps the result, so one
26
+ // unrecognised shape off the wire is `undefined.map` β€” a white screen, from a
27
+ // stored preference. `customer-grid/types` imports only `./windows`, which
28
+ // imports nothing, so this stays runnable under plain node (verify_login
29
+ // compiles this module and executes it there β€” see the header note on
30
+ // `appBase` being a parameter for exactly that reason).
31
+ import { FOLDER_SHAPES, FOLDER_TONES } from "../customer-grid/types";
32
+ import type { FolderIcon } from "../customer-grid/types";
33
 
34
  /** One entry of X2's nav payload. `source` is the registry's connector fact
35
  * (wave-9 I8: "Sales Β· Odoo"); `parent` names a sub-module's family head. */
 
56
  * `nav_pages`' docstring says "the client places them where the host does".
57
  */
58
  chrome?: "main" | "utility";
59
+ /**
60
+ * WAVE 19 R8 / C1 β€” the mark this database wears, from the tenant-wide
61
+ * `nav_meta` bucket. Absent β‡’ the default cylinder, which is every database
62
+ * that has never been given one.
63
+ *
64
+ * ⚠ TENANT-WIDE, not per-user, and that is the whole difference between this
65
+ * and `nav_prefs` two fields down. Folders and placement are one person's
66
+ * arrangement of their own rail; an icon and a name are what the DATABASE is
67
+ * called, and a workspace where two people call the same table different
68
+ * things has no shared vocabulary to hold a conversation in.
69
+ */
70
+ icon?: FolderIcon;
71
+ /**
72
+ * WAVE 19 R14 β€” may THIS session change this row's icon (and, for a `ut_` key,
73
+ * its name)? The SERVER answers, because it is the only end that can: the
74
+ * client cannot see who created a user table.
75
+ *
76
+ * β›” FAIL-CLOSED BY ABSENCE, like every other flag on this payload. A row that
77
+ * does not say `manage: true` offers no rename and no icon picker β€” and the
78
+ * route re-checks regardless, so this is the courtesy half of "the client
79
+ * hides, the server forbids", never the wall.
80
+ */
81
+ manage?: boolean;
82
+ }
83
+
84
+ /**
85
+ * The wire's icon, validated against the vocabulary the renderer can actually
86
+ * draw. Anything unrecognised reads as ABSENT (the default mark) rather than as
87
+ * an error: a stored preference is not worth a broken rail, and the server
88
+ * applies the same whitelist on the way in, so a mismatch here means the two
89
+ * ends have drifted β€” which shows up as an icon quietly reverting, the loudest
90
+ * safe symptom available.
91
+ */
92
+ export function parseNavIcon(raw: unknown): FolderIcon | undefined {
93
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
94
+ const r = raw as { shape?: unknown; tone?: unknown };
95
+ if (!(FOLDER_SHAPES as readonly string[]).includes(String(r.shape))) return undefined;
96
+ if (!(FOLDER_TONES as readonly string[]).includes(String(r.tone))) return undefined;
97
+ return { shape: r.shape as FolderIcon["shape"], tone: r.tone as FolderIcon["tone"] };
98
  }
99
 
100
  /**
 
119
  ...(typeof p.parent === "string" && p.parent ? { parent: p.parent } : {}),
120
  ...(p.group_only === true ? { group_only: true } : {}),
121
  ...(p.chrome === "main" || p.chrome === "utility" ? { chrome: p.chrome } : {}),
122
+ ...(parseNavIcon(p.icon) ? { icon: parseNavIcon(p.icon)! } : {}),
123
+ ...(p.manage === true ? { manage: true } : {}),
124
  });
125
  }
126
  return out;
 
237
  }
238
  }
239
 
240
+ // ── WAVE 19 R8 / C1: `nav_meta` β€” the TENANT-WIDE name + icon overrides ────────────────────
241
+
242
+ /** One database's overrides. `name` is `ut_*`-only and the SERVER enforces that
243
+ * (a built-in label is a compiled registry literal); `icon` rides every key. */
244
+ export interface NavMetaPatch {
245
+ icon?: FolderIcon | null;
246
+ name?: string;
247
+ }
248
+
249
+ /**
250
+ * `POST /api/v1/nav/meta`. A PATCH of ONE key, not a wholesale replace β€” the
251
+ * opposite posture to `saveNavPrefs` above, and deliberately so. Prefs are one
252
+ * user's complete picture of their own rail, so replacing it whole is how a
253
+ * deleted folder stays deleted. `nav_meta` is TENANT-WIDE and every admin edits
254
+ * the same document: sending a whole picture there means the last writer erases
255
+ * whatever the previous one named while their tab was open. Explicit `null`
256
+ * clears the icon; an absent field is untouched, which is what makes a
257
+ * rename-and-an-icon two independent writes instead of a race.
258
+ *
259
+ * Resolves false on any failure so the caller reverts its optimistic copy and
260
+ * says so, rather than leaving a name on screen that the store never took.
261
+ */
262
+ export async function saveNavMeta(key: string, patch: NavMetaPatch): Promise<boolean> {
263
+ try {
264
+ const res = await fetch(`${API_V1}/nav/meta`, {
265
+ method: "POST",
266
+ credentials: CREDENTIALS,
267
+ headers: { "Content-Type": "application/json" },
268
+ body: JSON.stringify({ key, ...patch }),
269
+ });
270
+ return res.ok;
271
+ } catch {
272
+ return false;
273
+ }
274
+ }
275
+
276
  /** One rendered row of the folded nav: a folder head, or an entry (optionally inside one). */
277
  export type NavRow =
278
  | { kind: "folder"; folder: NavFolder; count: number; open: boolean }
 
416
  depth: number;
417
  /** Absent for a group head β€” there is nowhere to go. */
418
  href?: string;
419
+ /** WAVE 19 R8 β€” the tenant's chosen mark; absent β‡’ the default cylinder. */
420
+ icon?: FolderIcon;
421
+ /** WAVE 19 R14 β€” the server's answer to "may this session rename/re-icon it".
422
+ * Absent β‡’ no, and the route refuses independently. */
423
+ manage?: boolean;
424
  }
425
 
426
  /**
 
510
  key: p.key,
511
  label: p.label,
512
  ...(p.source ? { source: p.source } : {}),
513
+ ...(p.icon ? { icon: p.icon } : {}),
514
+ ...(p.manage ? { manage: true } : {}),
515
  kind,
516
  depth,
517
  ...(kind === "group"
web/src/shell/navExtras.css CHANGED
@@ -172,6 +172,23 @@
172
  color: var(--lp-ink);
173
  }
174
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
175
  .shell-newfolder-form {
176
  padding: 4px 2px 2px;
177
  }
@@ -221,6 +238,66 @@
221
  color: var(--lp-red-deep);
222
  }
223
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
224
  .shell-navmenu-tick {
225
  margin-left: auto;
226
  font-size: var(--lp-fs-3xs);
 
172
  color: var(--lp-ink);
173
  }
174
 
175
+ /* WAVE 19 R11 β€” the same row in the folded rail: the "+" alone, centred in the
176
+ 56px strip, opening the rail rather than a popover it has no room for. */
177
+ .shell-newfolder.is-collapsed {
178
+ display: grid;
179
+ place-items: center;
180
+ padding: 6px 0;
181
+ }
182
+
183
+ .shell-newthing-plus {
184
+ width: 16px;
185
+ height: 16px;
186
+ fill: none;
187
+ stroke: currentColor;
188
+ stroke-width: 1.5;
189
+ stroke-linecap: round;
190
+ }
191
+
192
  .shell-newfolder-form {
193
  padding: 4px 2px 2px;
194
  }
 
238
  color: var(--lp-red-deep);
239
  }
240
 
241
+ /* A secondary action inside a picker, not a menu row in its own right. */
242
+ .shell-navmenu-item.is-quiet {
243
+ margin-top: 2px;
244
+ font-size: var(--lp-fs-3xs);
245
+ color: var(--lp-muted);
246
+ }
247
+
248
+ /* ── WAVE 19 R8 / C1: the database icon picker ─────────────────────────────── */
249
+
250
+ .shell-navmenu-pick {
251
+ padding: 4px 3px 3px;
252
+ }
253
+
254
+ /* WRAPS on purpose: twelve 26px swatches is ~312px and the menu is capped at
255
+ 240 (a popover wider than the rail it hangs off reads as a panel that has
256
+ come loose). Two rows of six is the shape that falls out of the cap, and the
257
+ tone row below it is five β€” so the block reads as "shape, then colour"
258
+ without a heading having to say so. */
259
+ .shell-navmenu-pickrow {
260
+ display: flex;
261
+ flex-wrap: wrap;
262
+ gap: 2px;
263
+ }
264
+
265
+ .shell-navmenu-pickrow + .shell-navmenu-pickrow {
266
+ margin-top: 4px;
267
+ padding-top: 5px;
268
+ border-top: 1px solid color-mix(in srgb, var(--lp-line) 55%, transparent);
269
+ }
270
+
271
+ .shell-navmenu-swatch {
272
+ flex: 0 0 auto;
273
+ display: grid;
274
+ place-items: center;
275
+ width: 26px;
276
+ height: 26px;
277
+ border: 1px solid transparent;
278
+ border-radius: 6px;
279
+ background: transparent;
280
+ padding: 0;
281
+ font: inherit;
282
+ cursor: pointer;
283
+ }
284
+
285
+ .shell-navmenu-swatch:hover {
286
+ background: var(--lp-wash);
287
+ }
288
+
289
+ /* The current choice is marked by its OUTLINE, never by a fill: the swatch's
290
+ whole job is to show the mark in its real colours, and a tinted plate behind
291
+ a pastel glyph changes the thing it is previewing. */
292
+ .shell-navmenu-swatch.is-on {
293
+ border-color: var(--lp-blue-deep);
294
+ }
295
+
296
+ .shell-navmenu-swatch:focus-visible {
297
+ outline: 2px solid var(--lp-blue-deep);
298
+ outline-offset: -2px;
299
+ }
300
+
301
  .shell-navmenu-tick {
302
  margin-left: auto;
303
  font-size: var(--lp-fs-3xs);
web/src/viz/seriesData.ts CHANGED
@@ -32,6 +32,12 @@ export const VIZ_FIELD_TYPES: ReadonlySet<string> = new Set([
32
  // compiler stays green when this goes stale and `asFields` silently downgrades the column
33
  // to text. When a `FieldType` joins the union, this line moves WITH the batch.
34
  "automation",
 
 
 
 
 
 
35
  ]);
36
 
37
  /**
 
32
  // compiler stays green when this goes stale and `asFields` silently downgrades the column
33
  // to text. When a `FieldType` joins the union, this line moves WITH the batch.
34
  "automation",
35
+ // Wave 19 R7 β€” `image`. Listed for the reason the comment above gives, not because a chart
36
+ // plots pictures: it does not. `isNumericFieldType` leaves it categorical, so it groups like
37
+ // any other reference string. What listing it BUYS is honesty β€” without it `asFields` would
38
+ // report the column as `text`, and the one thing a viz field type decides is what the surface
39
+ // is allowed to claim about the column.
40
+ "image",
41
  ]);
42
 
43
  /**
web/src/viz/types.ts CHANGED
@@ -34,7 +34,13 @@ export type FieldType =
34
  | "text" | "status" | "currency" | "int" | "date" | "pct" | "select" | "user"
35
  | "multiselect"
36
  | "checkbox" | "phone" | "email" | "url" | "rating" | "created_time" | "formula"
37
- | "automation";
 
 
 
 
 
 
38
 
39
  export type FieldSource = "odoo" | "overlay";
40
 
 
34
  | "text" | "status" | "currency" | "int" | "date" | "pct" | "select" | "user"
35
  | "multiselect"
36
  | "checkbox" | "phone" | "email" | "url" | "rating" | "created_time" | "formula"
37
+ | "automation"
38
+ // Wave-19 R7 β€” `image`. Added here because `GridFieldFitsViz` below went red the moment the
39
+ // grid's union grew, which is this file's own stated alarm working. A chart never PLOTS a
40
+ // picture (it is a reference string, so `isNumericFieldType` leaves it categorical and the
41
+ // shared formatter prints the ref) β€” the vocabulary has to know the word regardless, or the
42
+ // grid cannot hand its own fields to `<DashboardView>` at all.
43
+ | "image";
44
 
45
  export type FieldSource = "odoo" | "overlay";
46