fsanyoto commited on
Commit
37d92f0
Β·
verified Β·
1 Parent(s): b965aa0

Deploy AIOS web (React glide grid + FastAPI slice)

Browse files
RELEASES.json CHANGED
@@ -1,6 +1,12 @@
1
  {
2
- "current": "v9 (2e26f57)",
3
  "releases": [
 
 
 
 
 
 
4
  {
5
  "version": "v9",
6
  "sha": "2e26f57",
 
1
  {
2
+ "current": "v10 (43f8042)",
3
  "releases": [
4
+ {
5
+ "version": "v10",
6
+ "sha": "43f8042",
7
+ "date": "2026-08-05",
8
+ "subject": "release v10"
9
+ },
10
  {
11
  "version": "v9",
12
  "sha": "2e26f57",
VERSION CHANGED
@@ -1 +1 @@
1
- v9 (2e26f57)
 
1
+ v10 (43f8042)
api/automation_engine.py CHANGED
@@ -672,6 +672,50 @@ def ut_get(rt, key):
672
  return ut_all(rt).get(str(key))
673
 
674
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
675
  def ut_key_for(label, key=None):
676
  """The table key a label resolves to. Factored out of `ut_ensure` so the DRY-RUN path (which
677
  must not create anything) resolves the same key by construction rather than by copying the
@@ -686,7 +730,7 @@ def ut_key_for(label, key=None):
686
  MACHINE_OWNERS = ("automation", "scheduler")
687
 
688
 
689
- def ut_ensure(rt, label, fields, username="automation", key=None):
690
  """Create the table if it is missing; return its key. Idempotent β€” a re-run of an automation
691
  that owns a table must not spawn `ut_x_2`, so the key is DERIVED from the label (or given)
692
  and an existing table with that key is adopted, not duplicated.
@@ -694,6 +738,12 @@ def ut_ensure(rt, label, fields, username="automation", key=None):
694
  Fields are MERGED, never replaced: a user who added a column to an automation's table keeps
695
  it, and a new source column joins on the next run.
696
 
 
 
 
 
 
 
697
  β›” AND IT STAMPS A HUMAN OWNER, WHICH IT DID NOT (wave 20, item 3). `createdBy` was whoever
698
  or WHATEVER ran the automation, so the same table belonged to a person if its first run was
699
  manual and to `"scheduler"` if the schedule got there first β€” and `user_tables.may_open`
@@ -704,7 +754,9 @@ def ut_ensure(rt, label, fields, username="automation", key=None):
704
  for the table in the first place.
705
  """
706
  key = ut_key_for(label, key)
707
- wanted = list(fields or [])
 
 
708
  created = _iso()
709
  human = username if username and username not in MACHINE_OWNERS else ""
710
 
@@ -819,11 +871,15 @@ def clean_config(kind, raw, previous=None):
819
  target = _s(raw.get("targetTable"), 60).strip()
820
  if target and not target.startswith(UT_PREFIX):
821
  target = UT_PREFIX + target
 
 
 
822
  return {"url": url, "extract": extract,
823
  "tableIndex": max(0, min(int(raw.get("tableIndex") or 0), 50)),
824
  "fieldMap": fmap, "keyField": key_field,
825
  "targetTable": target,
826
  "dryRun": flag("dryRun"),
 
827
  "targetLabel": _s(raw.get("targetLabel"), 60).strip() or "Scraped table"}, None
828
  if kind == "field_instagram":
829
  table = _s(raw.get("targetTable"), 60).strip()
@@ -839,6 +895,9 @@ def clean_config(kind, raw, previous=None):
839
  tier = clean_tier(raw["tier"]) if "tier" in raw else ""
840
  if not tier and "tier" not in raw:
841
  tier = clean_tier(prev.get("tier"))
 
 
 
842
  return {"targetTable": table, "fieldKey": fkey,
843
  "urlField": _s(raw.get("urlField"), 80).strip(),
844
  "tier": tier or "anonymous",
@@ -848,6 +907,7 @@ def clean_config(kind, raw, previous=None):
848
  # (measured 2026-08-05), so likes/comments cost one extra vendor record PER POST.
849
  "postMetrics": flag("postMetrics"),
850
  "dryRun": flag("dryRun"),
 
851
  "maxPosts": max(1, min(int(raw.get("maxPosts") or 24), 200))}, None
852
  if kind == "discover_instagram":
853
  limit = int(raw.get("recordsLimit") or 0)
@@ -859,6 +919,11 @@ def clean_config(kind, raw, previous=None):
859
  preds, perr = clean_predicates(raw.get("predicates"))
860
  if perr:
861
  return None, perr
 
 
 
 
 
862
  target = _s(raw.get("targetTable"), 60).strip() or DISCOVER_TABLE
863
  if not target.startswith(UT_PREFIX):
864
  target = UT_PREFIX + target
@@ -904,11 +969,19 @@ def clean_definition(raw, previous=None, username=""):
904
  else prev.get("schedule"), prev.get("schedule"))
905
  except ValueError as e:
906
  return None, str(e)
 
 
 
 
907
  return {
908
  "id": _s(prev.get("id") or raw.get("id"), 40),
909
  "name": name, "kind": kind, "config": config, "schedule": schedule,
 
910
  "status": prev.get("status") or {"state": "idle", "lastRunAt": "", "lastSummary": ""},
911
  "runs": list(prev.get("runs") or [])[:MAX_RUNS],
 
 
 
912
  # ⚠ ENGINE-OWNED CONTINUATION STATE, and it is NOT config. A discovery snapshot takes ~20
913
  # minutes to build, so a run persists its id here and the NEXT run collects it. It is
914
  # carried through `patch` untouched because a user pressing Save must not silently orphan
@@ -969,6 +1042,9 @@ def create(rt, raw, username=""):
969
  return cur
970
 
971
  rt.update(STORE_KEY, _up, flush="sync")
 
 
 
972
  return defn, None
973
 
974
 
@@ -978,7 +1054,7 @@ def patch(rt, auto_id, raw, username=""):
978
  if prev is None:
979
  return None, "no such automation"
980
  merged = dict(prev)
981
- for k in ("name", "config", "schedule", "kind"):
982
  if k in (raw or {}):
983
  merged[k] = raw[k]
984
  defn, err = clean_definition(merged, prev, username)
@@ -992,15 +1068,50 @@ def patch(rt, auto_id, raw, username=""):
992
  return cur
993
 
994
  rt.update(STORE_KEY, _up, flush="sync")
 
 
 
 
 
995
  return defn, None
996
 
997
 
 
 
 
 
 
 
 
 
 
 
998
  def remove(rt, auto_id):
 
 
999
  def _up(cur):
1000
  cur = cur if isinstance(cur, dict) else {}
1001
- cur.pop(str(auto_id), None)
1002
  return cur
1003
  rt.update(STORE_KEY, _up, flush="sync")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1004
 
1005
 
1006
  # ---------------------------------------------------------------------------------------------
@@ -1058,6 +1169,22 @@ def _commit_run(rt, auto_id, state, summary, counts, ok, affected=None, steps=No
1058
  d["status"] = {"state": state, "lastRunAt": entry["ts"],
1059
  "lastSummary": entry["summary"]}
1060
  d["runs"] = ([entry] + list(d.get("runs") or []))[:MAX_RUNS]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1061
  return cur
1062
 
1063
  rt.update(STORE_KEY, _up, flush="sync")
@@ -1860,6 +1987,58 @@ BD_FILTER_FIELDS = ("followers", "following", "posts_count", "avg_engagement", "
1860
  #: on an unpopulated field returns nothing and looks exactly like "no such influencers exist".
1861
  BD_FILTER_LEAD = ("followers", "biography", "avg_engagement")
1862
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1863
  CANDIDATE_FIELDS = [
1864
  field_def("handle", "Handle"), field_def("profile_url", "Profile", "url"),
1865
  field_def("full_name", "Name"), field_def("followers", "Followers"),
@@ -1868,6 +2047,11 @@ CANDIDATE_FIELDS = [
1868
  field_def("verified", "Verified"), field_def("category", "Category"),
1869
  field_def("found_count", "Times found"), field_def("first_found", "First found"),
1870
  field_def("last_found", "Last found"),
 
 
 
 
 
1871
  # β›” WRITTEN BY A HUMAN, NEVER BY THIS ENGINE (R7). It is declared here so the column exists
1872
  # and can be ticked; `_candidate_row` never emits the key, and `upsert_rows` only writes the
1873
  # keys it is given β€” so a re-find can never un-tick somebody's decision either.
@@ -1903,6 +2087,11 @@ def clean_predicates(raw):
1903
  if not out:
1904
  return None, ("add at least one condition β€” an empty filter matches the whole 620-million"
1905
  "-record corpus, which is the query the vendor refuses")
 
 
 
 
 
1906
  return out, None
1907
 
1908
 
@@ -2242,14 +2431,34 @@ def run_scrape_db(rt, defn, username="automation", log=print):
2242
  t = ut_get(rt, table_key) or {}
2243
  rows, counts = upsert_rows(t.get("rows") or {}, incoming, key_field,
2244
  cap=row_cap(table_key))
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2245
  if not dry:
2246
  ut_write_rows(rt, table_key, rows)
 
 
2247
  counts["source_rows"] = len(incoming)
2248
- affected = [rid for rid, row in rows.items()
2249
- if str(row.get(key_field, "")) in {str(i.get(key_field)) for i in incoming}][:200]
2250
  summary = (f"{counts['inserted']} new, {counts['updated']} updated, "
2251
  f"{counts['unchanged']} unchanged, {counts['orphans']} no longer on the page "
2252
  f"(kept)")
 
 
2253
  capped = [(table_key, counts.get("capped", 0))]
2254
  missing = [] if dry else ut_missing(rt, table_key)
2255
  counts["missing_tables"] = len(missing)
@@ -2300,10 +2509,12 @@ def run_field_instagram(rt, defn, username="automation", log=print):
2300
  # The Write node is off: resolve the keys, create nothing. (`ut_ensure` writes.)
2301
  snap_key, post_key, ps_key = ("ut_ig_snapshots", "ut_ig_posts", "ut_ig_post_snapshots")
2302
  else:
2303
- snap_key = ut_ensure(rt, "IG snapshots", SNAPSHOT_FIELDS, username, key="ut_ig_snapshots")
2304
- post_key = ut_ensure(rt, "IG posts", POST_FIELDS, username, key="ut_ig_posts")
 
 
2305
  ps_key = ut_ensure(rt, "IG post snapshots", POST_SNAPSHOT_FIELDS, username,
2306
- key="ut_ig_post_snapshots")
2307
  missing = [] if dry else ut_missing(rt, snap_key, post_key, ps_key)
2308
  snaps = dict((ut_get(rt, snap_key) or {}).get("rows") or {})
2309
  posts = dict((ut_get(rt, post_key) or {}).get("rows") or {})
@@ -2417,6 +2628,24 @@ def run_field_instagram(rt, defn, username="automation", log=print):
2417
  (ps_key, c_ps["capped"])]
2418
  counts["capped"] = sum(n for _k, n in capped)
2419
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2420
  if not dry:
2421
  def _up(cur):
2422
  cur = cur if isinstance(cur, dict) else {}
@@ -2424,6 +2653,8 @@ def run_field_instagram(rt, defn, username="automation", log=print):
2424
  if tt is not None:
2425
  for rid, val in cells.items():
2426
  tt.setdefault("rows", {}).setdefault(str(rid), {})[fkey] = val
 
 
2427
  for k, rws in ((snap_key, snaps), (post_key, posts), (ps_key, psnaps)):
2428
  tgt = cur.get(k)
2429
  if tgt is not None:
@@ -2431,6 +2662,23 @@ def run_field_instagram(rt, defn, username="automation", log=print):
2431
  return cur
2432
 
2433
  rt.update(UT_STORE_KEY, _up, flush="sync") # ONE coalesced update for all four tables
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2434
 
2435
  # ⚠ A RUN IS ONLY 'ok' IF EVERY PROFILE WAS. The first live run rolled up to 'ok' while
2436
  # every CELL said `partial`, because the rollup only asked about blocked/error β€” so the rail
@@ -2469,6 +2717,8 @@ def run_field_instagram(rt, defn, username="automation", log=print):
2469
 
2470
  summary = (f"{read}/{counts['profiles']} profiles read, {counts['posts']} posts "
2471
  f"({counts['new_posts']} new)")
 
 
2472
  if counts["paid"]:
2473
  summary += f", {counts['paid']} exact via Bright Data"
2474
  if counts["metrics"]:
@@ -2488,12 +2738,22 @@ def run_field_instagram(rt, defn, username="automation", log=print):
2488
  steps["write"] = "partial"
2489
  elif not dry:
2490
  steps["write"] = "ok"
 
 
 
 
2491
  if dry:
2492
  summary = f"DRY RUN (the Write step is turned off) β€” would have written: {summary}"
2493
  steps["write"] = "skipped"
2494
  state = "partial" if state != "error" else state
2495
  if notes:
2496
  summary += f" β€” {notes[0][:120]}"
 
 
 
 
 
 
2497
  return (state, summary, counts, affected, steps)
2498
 
2499
 
@@ -2536,6 +2796,12 @@ def run_discover_instagram(rt, defn, username="automation", log=print):
2536
 
2537
  pending = str((defn.get("state") or {}).get("pendingSnapshot") or "")
2538
  if not pending:
 
 
 
 
 
 
2539
  if dry:
2540
  est = discover_estimate(limit)
2541
  steps["find"] = steps["write"] = "skipped"
@@ -2608,14 +2874,34 @@ def run_discover_instagram(rt, defn, username="automation", log=print):
2608
  label = cfg.get("targetLabel") or "IG candidates"
2609
  table_key = (ut_key_for(label, cfg.get("targetTable") or DISCOVER_TABLE) if dry
2610
  else ut_ensure(rt, label, CANDIDATE_FIELDS, username,
2611
- key=cfg.get("targetTable") or DISCOVER_TABLE))
 
2612
  existing = dict((ut_get(rt, table_key) or {}).get("rows") or {})
2613
- # `found_count` is ARITHMETIC OVER WHAT IS STORED, not a value from the vendor β€” re-finding a
2614
- # profile is the signal that it keeps matching, so the counter grows instead of resetting.
2615
- # `first_found` is written only when the handle is new, so it never moves.
2616
- seen = {str((r or {}).get("handle") or "").strip(): r for r in existing.values()}
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2617
  for c in incoming:
2618
- prev_row = seen.get(c["handle"])
 
 
2619
  if prev_row:
2620
  counts["seen_again"] += 1
2621
  c["found_count"] = str((_ig_int(prev_row.get("found_count")) or 0) + 1)
@@ -2623,12 +2909,20 @@ def run_discover_instagram(rt, defn, username="automation", log=print):
2623
  counts["new"] += 1
2624
  c["found_count"] = "1"
2625
  c["first_found"] = stamp
2626
- merged, mc = upsert_rows(existing, incoming, "handle", cap=row_cap(table_key))
 
 
 
 
 
 
 
2627
  counts["capped"] = mc["capped"]
2628
  missing = [] if dry else ut_missing(rt, table_key)
2629
  counts["missing_tables"] = len(missing)
2630
  if not dry and not missing:
2631
  ut_write_rows(rt, table_key, merged)
 
2632
  steps["write"] = "ok"
2633
  elif dry:
2634
  steps["write"] = "skipped"
@@ -2650,6 +2944,11 @@ def run_discover_instagram(rt, defn, username="automation", log=print):
2650
  if dry:
2651
  summary = f"DRY RUN (the Write step is turned off) β€” would have written: {summary}"
2652
  state = "partial" if (dry or counts["capped"] or missing or not counts["found"]) else "ok"
 
 
 
 
 
2653
  log(f"[aios-auto] discover {auto_id} -> {table_key}: {summary}")
2654
  return (state, summary, counts, affected, steps)
2655
 
@@ -2782,10 +3081,25 @@ def graph(defn):
2782
  "toggle": NODE_TOGGLES.get(nid, ""), "status": node_status(steps, nid)}
2783
 
2784
  on = bool(sched.get("enabled"))
2785
- nodes = [node("trigger", "trigger", "Schedule",
2786
- _cron_label(sched.get("cron")) if on else "Manual only", 0,
2787
- panel="schedule", on=on,
2788
- detail="" if on else "It still runs when you press Run now")]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2789
  edges = []
2790
 
2791
  if defn.get("kind") == "field_instagram":
@@ -2901,6 +3215,14 @@ def toggle_node(rt, auto_id, node_id):
2901
  f"automation is")
2902
  cfg, sched = dict(prev.get("config") or {}), dict(prev.get("schedule") or {})
2903
  which = target["toggle"]
 
 
 
 
 
 
 
 
2904
  if which == "schedule":
2905
  sched["enabled"] = not sched.get("enabled")
2906
  elif which == "paid":
@@ -2915,6 +3237,1132 @@ def toggle_node(rt, auto_id, node_id):
2915
  return patch(rt, auto_id, {"config": cfg, "schedule": sched})
2916
 
2917
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2918
  def run_now(rt, tenant, auto_id, username="automation", log=print):
2919
  """Execute one automation SYNCHRONOUSLY. The route wraps this in a thread; the tick calls it
2920
  directly. Returns the run entry, or None when it was already running (the 409)."""
@@ -2971,11 +4419,26 @@ def due_ids(rt, now=None):
2971
 
2972
 
2973
  def tick(rt, tenant, now=None, log=print):
2974
- """Fire every due automation for ONE tenant. Returns the ids started."""
 
 
2975
  started = []
2976
  for aid in due_ids(rt, now):
2977
  if run_async(rt, tenant, aid, username="scheduler", log=log):
2978
  started.append(aid)
 
 
 
 
 
 
 
 
 
 
 
 
 
2979
  if started:
2980
  log(f"[aios-auto] tick {tenant}: started {', '.join(started)}")
2981
  return started
 
672
  return ut_all(rt).get(str(key))
673
 
674
 
675
+ def bind_unbound_fields(rt):
676
+ """C8's migration (wave 22, stated choice): existing automation bags WITHOUT a `flowId`
677
+ are bound to the definition that already writes them β€” matched on the (targetTable,
678
+ fieldKey) pair the definition carries, which is the binding W21-C2 established. A bag no
679
+ definition references is DISABLED with the reason on it rather than deleted or guessed:
680
+ the column was already dead (nothing runs a column no flow names), and now it says so.
681
+ Returns `(bound, disabled)`; costs zero store commits when there is nothing to migrate."""
682
+ by_binding = {}
683
+ for aid, d in all_definitions(rt).items():
684
+ cfg = d.get("config") or {}
685
+ if cfg.get("fieldKey") and cfg.get("targetTable"):
686
+ by_binding[(str(cfg["targetTable"]), str(cfg["fieldKey"]))] = str(aid)
687
+ plan = {}
688
+ for tk, t in ut_all(rt).items():
689
+ for f in (t.get("fields") or []):
690
+ a = f.get("automation")
691
+ # An already-DISABLED bag is a decision this migration made on a previous pass β€”
692
+ # re-planning it every call would turn the once-per-process sweep into a write
693
+ # per read.
694
+ if isinstance(a, dict) and not a.get("flowId") and not a.get("stageField") \
695
+ and not a.get("disabled"):
696
+ plan[(tk, str(f.get("key")))] = by_binding.get((tk, str(f.get("key"))))
697
+ if not plan:
698
+ return 0, 0
699
+
700
+ def _up(cur):
701
+ cur = cur if isinstance(cur, dict) else {}
702
+ for (tk, fk), aid in plan.items():
703
+ for f in ((cur.get(tk) or {}).get("fields") or []):
704
+ if f.get("key") == fk and isinstance(f.get("automation"), dict):
705
+ if aid:
706
+ f["automation"]["flowId"] = aid
707
+ else:
708
+ f["automation"]["disabled"] = True
709
+ f["automation"]["statusNote"] = (
710
+ "not bound to any flow β€” create an automation for this column "
711
+ "or delete it")
712
+ return cur
713
+
714
+ rt.update(UT_STORE_KEY, _up, flush="sync")
715
+ bound = sum(1 for v in plan.values() if v)
716
+ return bound, len(plan) - bound
717
+
718
+
719
  def ut_key_for(label, key=None):
720
  """The table key a label resolves to. Factored out of `ut_ensure` so the DRY-RUN path (which
721
  must not create anything) resolves the same key by construction rather than by copying the
 
730
  MACHINE_OWNERS = ("automation", "scheduler")
731
 
732
 
733
+ def ut_ensure(rt, label, fields, username="automation", key=None, flow_tag=""):
734
  """Create the table if it is missing; return its key. Idempotent β€” a re-run of an automation
735
  that owns a table must not spawn `ut_x_2`, so the key is DERIVED from the label (or given)
736
  and an existing table with that key is adopted, not duplicated.
 
738
  Fields are MERGED, never replaced: a user who added a column to an automation's table keeps
739
  it, and a new source column joins on the next run.
740
 
741
+ `flow_tag` (wave 22, C7/item 5): every field THIS call adds is stamped
742
+ `automation: {flowId: <tag>}` β€” the pre-set columns an IG automation spawns carry their
743
+ provenance. Fields already on the table keep whatever tag they have (first flow wins;
744
+ shared tables like ut_ig_snapshots are fed by many flows and the tag is provenance, not
745
+ ownership).
746
+
747
  β›” AND IT STAMPS A HUMAN OWNER, WHICH IT DID NOT (wave 20, item 3). `createdBy` was whoever
748
  or WHATEVER ran the automation, so the same table belonged to a person if its first run was
749
  manual and to `"scheduler"` if the schedule got there first β€” and `user_tables.may_open`
 
754
  for the table in the first place.
755
  """
756
  key = ut_key_for(label, key)
757
+ wanted = [({**f, "automation": {"flowId": str(flow_tag)}}
758
+ if flow_tag and not f.get("automation") else dict(f))
759
+ for f in (fields or [])]
760
  created = _iso()
761
  human = username if username and username not in MACHINE_OWNERS else ""
762
 
 
871
  target = _s(raw.get("targetTable"), 60).strip()
872
  if target and not target.startswith(UT_PREFIX):
873
  target = UT_PREFIX + target
874
+ lanes, lerr = clean_lanes(raw.get("lanes") if "lanes" in raw else prev.get("lanes"))
875
+ if lerr:
876
+ return None, lerr
877
  return {"url": url, "extract": extract,
878
  "tableIndex": max(0, min(int(raw.get("tableIndex") or 0), 50)),
879
  "fieldMap": fmap, "keyField": key_field,
880
  "targetTable": target,
881
  "dryRun": flag("dryRun"),
882
+ "lanes": lanes,
883
  "targetLabel": _s(raw.get("targetLabel"), 60).strip() or "Scraped table"}, None
884
  if kind == "field_instagram":
885
  table = _s(raw.get("targetTable"), 60).strip()
 
895
  tier = clean_tier(raw["tier"]) if "tier" in raw else ""
896
  if not tier and "tier" not in raw:
897
  tier = clean_tier(prev.get("tier"))
898
+ lanes, lerr = clean_lanes(raw.get("lanes") if "lanes" in raw else prev.get("lanes"))
899
+ if lerr:
900
+ return None, lerr
901
  return {"targetTable": table, "fieldKey": fkey,
902
  "urlField": _s(raw.get("urlField"), 80).strip(),
903
  "tier": tier or "anonymous",
 
907
  # (measured 2026-08-05), so likes/comments cost one extra vendor record PER POST.
908
  "postMetrics": flag("postMetrics"),
909
  "dryRun": flag("dryRun"),
910
+ "lanes": lanes,
911
  "maxPosts": max(1, min(int(raw.get("maxPosts") or 24), 200))}, None
912
  if kind == "discover_instagram":
913
  limit = int(raw.get("recordsLimit") or 0)
 
919
  preds, perr = clean_predicates(raw.get("predicates"))
920
  if perr:
921
  return None, perr
922
+ if raw.get("lanes") if "lanes" in raw else prev.get("lanes"):
923
+ # R6: discovery's one path is the human gate β€” Review, then Tracked. A lane after
924
+ # the gate would be a second router over a set a person is already routing.
925
+ return None, ("a discovery automation routes through Review β€” its path is the "
926
+ "human gate; lanes belong on scrape and column automations")
927
  target = _s(raw.get("targetTable"), 60).strip() or DISCOVER_TABLE
928
  if not target.startswith(UT_PREFIX):
929
  target = UT_PREFIX + target
 
969
  else prev.get("schedule"), prev.get("schedule"))
970
  except ValueError as e:
971
  return None, str(e)
972
+ trigger, terr = clean_trigger(raw.get("trigger") if "trigger" in raw
973
+ else prev.get("trigger"), prev.get("trigger"))
974
+ if terr:
975
+ return None, terr
976
  return {
977
  "id": _s(prev.get("id") or raw.get("id"), 40),
978
  "name": name, "kind": kind, "config": config, "schedule": schedule,
979
+ "trigger": trigger,
980
  "status": prev.get("status") or {"state": "idle", "lastRunAt": "", "lastSummary": ""},
981
  "runs": list(prev.get("runs") or [])[:MAX_RUNS],
982
+ # C3-A2(5): the review-decision audit survives a Save the way `state` does β€” an
983
+ # ordinary patch must not amnesty every recorded approve/decline.
984
+ "reviews": list(prev.get("reviews") or [])[:100],
985
  # ⚠ ENGINE-OWNED CONTINUATION STATE, and it is NOT config. A discovery snapshot takes ~20
986
  # minutes to build, so a run persists its id here and the NEXT run collects it. It is
987
  # carried through `patch` untouched because a user pressing Save must not silently orphan
 
1042
  return cur
1043
 
1044
  rt.update(STORE_KEY, _up, flush="sync")
1045
+ _stage_field_after_write(rt, defn, username)
1046
+ if defn.get("trigger"):
1047
+ _seed_event_state(rt, defn)
1048
  return defn, None
1049
 
1050
 
 
1054
  if prev is None:
1055
  return None, "no such automation"
1056
  merged = dict(prev)
1057
+ for k in ("name", "config", "schedule", "kind", "trigger"):
1058
  if k in (raw or {}):
1059
  merged[k] = raw[k]
1060
  defn, err = clean_definition(merged, prev, username)
 
1068
  return cur
1069
 
1070
  rt.update(STORE_KEY, _up, flush="sync")
1071
+ _stage_field_after_write(rt, defn, username)
1072
+ # A2(1): a NEW or CHANGED condition trigger starts with everything currently matching
1073
+ # DISARMED β€” enabling never fires for records already in the state.
1074
+ if (defn.get("trigger") or {}) != ((prev.get("trigger")) or {}):
1075
+ _seed_event_state(rt, defn)
1076
  return defn, None
1077
 
1078
 
1079
+ def _stage_field_after_write(rt, defn, username):
1080
+ """C2's 'at automation create (or first bind)': when the target database already exists,
1081
+ the stage field appears/refreshes with the definition write β€” a patch that adds a lane
1082
+ grows the select's vocabulary in the same breath. A table that does not exist yet gets its
1083
+ field from the first RUN instead (the runner ensures after `ut_ensure`)."""
1084
+ tgt = str((defn.get("config") or {}).get("targetTable") or "")
1085
+ if tgt and ut_get(rt, tgt) is not None:
1086
+ ensure_stage_field(rt, tgt, defn, username)
1087
+
1088
+
1089
  def remove(rt, auto_id):
1090
+ aid = str(auto_id)
1091
+
1092
  def _up(cur):
1093
  cur = cur if isinstance(cur, dict) else {}
1094
+ cur.pop(aid, None)
1095
  return cur
1096
  rt.update(STORE_KEY, _up, flush="sync")
1097
+ # C8 β€” the fields this flow tagged are DISABLED with the reason on them, never orphaned
1098
+ # silently: the column keeps its values and its config, and says why it stopped. Scanned
1099
+ # first so a delete with no tagged fields costs no store commit.
1100
+ hit = any(str((f.get("automation") or {}).get("flowId") or "") == aid
1101
+ for t in ut_all(rt).values() for f in (t.get("fields") or []))
1102
+ if not hit:
1103
+ return
1104
+
1105
+ def _disable(cur):
1106
+ cur = cur if isinstance(cur, dict) else {}
1107
+ for t in cur.values():
1108
+ for f in (t.get("fields") or []):
1109
+ a = f.get("automation")
1110
+ if isinstance(a, dict) and str(a.get("flowId") or "") == aid:
1111
+ a["disabled"] = True
1112
+ a["statusNote"] = f"its automation was deleted {_stamp()}"
1113
+ return cur
1114
+ rt.update(UT_STORE_KEY, _disable, flush="sync")
1115
 
1116
 
1117
  # ---------------------------------------------------------------------------------------------
 
1169
  d["status"] = {"state": state, "lastRunAt": entry["ts"],
1170
  "lastSummary": entry["summary"]}
1171
  d["runs"] = ([entry] + list(d.get("runs") or []))[:MAX_RUNS]
1172
+ # Wave 22 (airtable-brief rec 6): K consecutive FAILURES auto-pause the automation with
1173
+ # the reason on it β€” a dead credential must not burn quota (or a paid vendor's records)
1174
+ # 96 times a day while a green toggle sits over a buried error log. Errors only:
1175
+ # `partial` is the honest-progress state and pausing on it would punish honesty.
1176
+ runs = d.get("runs") or []
1177
+ if state == "error" and len(runs) >= CONSECUTIVE_FAILURE_PAUSE and all(
1178
+ not r.get("ok") for r in runs[:CONSECUTIVE_FAILURE_PAUSE]):
1179
+ sch = d.get("schedule")
1180
+ if isinstance(sch, dict) and sch.get("enabled"):
1181
+ sch["enabled"] = False
1182
+ trg = d.get("trigger")
1183
+ if isinstance(trg, dict):
1184
+ trg["paused"] = True
1185
+ d["statusNote"] = (f"auto-paused after {CONSECUTIVE_FAILURE_PAUSE} consecutive "
1186
+ f"failures β€” fix the cause, then re-enable: "
1187
+ f"{entry['summary'][:120]}")
1188
  return cur
1189
 
1190
  rt.update(STORE_KEY, _up, flush="sync")
 
1987
  #: on an unpopulated field returns nothing and looks exactly like "no such influencers exist".
1988
  BD_FILTER_LEAD = ("followers", "biography", "avg_engagement")
1989
 
1990
+ #: β›” C4 (wave 22) β€” THE TOO-BIG GUARD, and its unit is the PREDICATE, not the row count.
1991
+ #: MEASURED (2026-08-04): `records_limit: 10` over a bare `followers > 10000` was still
1992
+ #: `building` 50 minutes later β€” scan time tracks PREDICATE BREADTH; bounding the rows does not
1993
+ #: bound the scan. What actually narrows a 620M-row corpus is CONTENT: a text/array match on a
1994
+ #: field that discriminates. Numeric ranges and booleans partition the corpus into slabs the
1995
+ #: scanner still has to walk, so they refine a search and cannot BE one.
1996
+ BD_NARROWING_FIELDS = frozenset({
1997
+ "biography", "account", "full_name", "profile_name", "category_name",
1998
+ "business_category_name", "external_url", "bio_hashtags", "post_hashtags",
1999
+ "related_accounts", "id", "fbid", "profile_url"})
2000
+ #: The ops that actually pin content β€” `!=`/`not_includes` on a text field matches nearly the
2001
+ #: whole corpus, which is breadth wearing a condition's clothes.
2002
+ BD_NARROWING_OPS = frozenset({"=", "in", "includes", "array_includes"})
2003
+ #: Fields MEASURED carrying values on real corpus rows β€” D-25's fill-rate table, 50 mixed
2004
+ #: profiles (snapshot `snap_msfrlbmt7qvej8uby`, collected 2026-08-05). The bar is β‰₯60%
2005
+ #: populated: below it a filter misses more corpus than it matches, and the surface should
2006
+ #: say so. MEASURED AND EXCLUDED: category_name 48%, business_category_name 34%,
2007
+ #: related_accounts 22%, post_hashtags 18%, bio_hashtags 10% β€” and the PII trio the map never
2008
+ #: carries anyway read 2%/0%/0%, so even the thing R3 forbids would barely have worked.
2009
+ #: ⚠ posts_count was 100% populated on CORPUS rows β€” the fabricated-zero finding
2010
+ #: (`_bd_posts_count`) is a SCRAPE-path fact and both stay true.
2011
+ BD_POPULATED_FIELDS = frozenset({
2012
+ "account", "followers", "following", "posts_count", "avg_engagement", "biography",
2013
+ "external_url", "is_business_account", "is_professional_account", "is_verified",
2014
+ "full_name", "profile_name", "highlights_count", "id", "fbid", "profile_url"})
2015
+ BD_MIN_NARROWING = 1
2016
+
2017
+
2018
+ def predicate_narrows(p):
2019
+ """Does ONE predicate narrow the corpus scan? Content field + content op, nothing else."""
2020
+ return (str((p or {}).get("name") or "") in BD_NARROWING_FIELDS
2021
+ and str((p or {}).get("operator") or "") in BD_NARROWING_OPS)
2022
+
2023
+
2024
+ def narrowing_refusal(preds):
2025
+ """C4's server law: the sentence when a predicate set has ZERO narrowing predicates, else
2026
+ ''. One function so create/patch (via `clean_predicates`) and RUN (legacy stored configs
2027
+ predate the law) refuse in the same words."""
2028
+ if any(predicate_narrows(p) for p in preds or []):
2029
+ return ""
2030
+ return ("add at least one CONTENT condition (biography includes …, account =, a hashtag) β€” "
2031
+ "number and yes/no filters alone make the vendor scan the whole 620-million-row "
2032
+ "corpus, and breadth is what costs: the measured `followers > 10000` search was "
2033
+ "still building 50 minutes in")
2034
+
2035
+
2036
+ def filter_meta():
2037
+ """C4's per-field flags for the Find surface: `[{name, populated, narrowing}]` over the
2038
+ same 21 names `BD_FILTER_FIELDS` offers (the 3 PII fields stay structurally absent, R3)."""
2039
+ return [{"name": n, "populated": n in BD_POPULATED_FIELDS,
2040
+ "narrowing": n in BD_NARROWING_FIELDS} for n in BD_FILTER_FIELDS]
2041
+
2042
  CANDIDATE_FIELDS = [
2043
  field_def("handle", "Handle"), field_def("profile_url", "Profile", "url"),
2044
  field_def("full_name", "Name"), field_def("followers", "Followers"),
 
2047
  field_def("verified", "Verified"), field_def("category", "Category"),
2048
  field_def("found_count", "Times found"), field_def("first_found", "First found"),
2049
  field_def("last_found", "Last found"),
2050
+ # C6 (wave 22): the candidate pool is PER-USER β€” the upsert key is the COMPOUND
2051
+ # (handle, created_by), so two people discovering the same profile each get their own row,
2052
+ # their own found_count and their own review card. Stamped by the RUNNER (the automation's
2053
+ # creator), never by `_candidate_row`.
2054
+ field_def("created_by", "Found by"),
2055
  # β›” WRITTEN BY A HUMAN, NEVER BY THIS ENGINE (R7). It is declared here so the column exists
2056
  # and can be ticked; `_candidate_row` never emits the key, and `upsert_rows` only writes the
2057
  # keys it is given β€” so a re-find can never un-tick somebody's decision either.
 
2087
  if not out:
2088
  return None, ("add at least one condition β€” an empty filter matches the whole 620-million"
2089
  "-record corpus, which is the query the vendor refuses")
2090
+ # C4 (wave 22): breadth is refused at WRITE time too β€” see `narrowing_refusal` for the
2091
+ # measured hang this guards against. Same sentence at create/patch and at run.
2092
+ guard_err = narrowing_refusal(out)
2093
+ if guard_err:
2094
+ return None, guard_err
2095
  return out, None
2096
 
2097
 
 
2431
  t = ut_get(rt, table_key) or {}
2432
  rows, counts = upsert_rows(t.get("rows") or {}, incoming, key_field,
2433
  cap=row_cap(table_key))
2434
+ touched = [rid for rid, row in rows.items()
2435
+ if str(row.get(key_field, "")) in {str(i.get(key_field)) for i in incoming}]
2436
+ # R5 β€” the engine moves each record down its winning lane, over the row's FINAL values.
2437
+ # Blank β‡’ no lane matched: the record shows in the derived Write bucket, never a guess.
2438
+ lanes = cfg.get("lanes") or []
2439
+ if lanes:
2440
+ skey = stage_field_key(defn.get("id"))
2441
+ stamp = _iso()
2442
+ counts["routed"] = 0
2443
+ for rid in touched:
2444
+ row = rows.get(rid) or {}
2445
+ label = route_record(lanes, row)
2446
+ if label:
2447
+ counts["routed"] += 1
2448
+ if str(row.get(skey) or "") != label:
2449
+ row[skey] = label
2450
+ row[skey + "_at"] = stamp if label else ""
2451
  if not dry:
2452
  ut_write_rows(rt, table_key, rows)
2453
+ if lanes:
2454
+ ensure_stage_field(rt, table_key, defn, username)
2455
  counts["source_rows"] = len(incoming)
2456
+ affected = touched[:200]
 
2457
  summary = (f"{counts['inserted']} new, {counts['updated']} updated, "
2458
  f"{counts['unchanged']} unchanged, {counts['orphans']} no longer on the page "
2459
  f"(kept)")
2460
+ if lanes:
2461
+ summary += f", {counts['routed']}/{len(touched)} routed to lanes"
2462
  capped = [(table_key, counts.get("capped", 0))]
2463
  missing = [] if dry else ut_missing(rt, table_key)
2464
  counts["missing_tables"] = len(missing)
 
2509
  # The Write node is off: resolve the keys, create nothing. (`ut_ensure` writes.)
2510
  snap_key, post_key, ps_key = ("ut_ig_snapshots", "ut_ig_posts", "ut_ig_post_snapshots")
2511
  else:
2512
+ snap_key = ut_ensure(rt, "IG snapshots", SNAPSHOT_FIELDS, username,
2513
+ key="ut_ig_snapshots", flow_tag=str(defn.get("id") or ""))
2514
+ post_key = ut_ensure(rt, "IG posts", POST_FIELDS, username, key="ut_ig_posts",
2515
+ flow_tag=str(defn.get("id") or ""))
2516
  ps_key = ut_ensure(rt, "IG post snapshots", POST_SNAPSHOT_FIELDS, username,
2517
+ key="ut_ig_post_snapshots", flow_tag=str(defn.get("id") or ""))
2518
  missing = [] if dry else ut_missing(rt, snap_key, post_key, ps_key)
2519
  snaps = dict((ut_get(rt, snap_key) or {}).get("rows") or {})
2520
  posts = dict((ut_get(rt, post_key) or {}).get("rows") or {})
 
2628
  (ps_key, c_ps["capped"])]
2629
  counts["capped"] = sum(n for _k, n in capped)
2630
 
2631
+ # R5 β€” route each processed record down its winning lane, judged over the row's FINAL
2632
+ # values (the fresh status cell included, so a lane on the cell itself is answerable).
2633
+ lanes = cfg.get("lanes") or []
2634
+ stage_writes = {}
2635
+ if lanes:
2636
+ skey = stage_field_key(defn.get("id"))
2637
+ stamp = _iso()
2638
+ counts["routed"] = 0
2639
+ for rid, _url in targets:
2640
+ merged = dict(rows.get(rid) or {})
2641
+ if rid in cells:
2642
+ merged[fkey] = cells[rid]
2643
+ label = route_record(lanes, merged)
2644
+ if label:
2645
+ counts["routed"] += 1
2646
+ if str((rows.get(rid) or {}).get(skey) or "") != label:
2647
+ stage_writes[rid] = {skey: label, skey + "_at": stamp if label else ""}
2648
+
2649
  if not dry:
2650
  def _up(cur):
2651
  cur = cur if isinstance(cur, dict) else {}
 
2653
  if tt is not None:
2654
  for rid, val in cells.items():
2655
  tt.setdefault("rows", {}).setdefault(str(rid), {})[fkey] = val
2656
+ for rid, vals in stage_writes.items():
2657
+ tt.setdefault("rows", {}).setdefault(str(rid), {}).update(vals)
2658
  for k, rws in ((snap_key, snaps), (post_key, posts), (ps_key, psnaps)):
2659
  tgt = cur.get(k)
2660
  if tgt is not None:
 
2662
  return cur
2663
 
2664
  rt.update(UT_STORE_KEY, _up, flush="sync") # ONE coalesced update for all four tables
2665
+ if lanes:
2666
+ ensure_stage_field(rt, table_key, defn, username)
2667
+
2668
+ # --- C6 (R2): WRITE-THROUGH to the platform master. Three postures, never conflated:
2669
+ # `ok` silent, `off` an honest aside (the tenant copy IS the story on this deployment),
2670
+ # `error` a LOUD partial β€” a pooled history with silent holes is worse than none.
2671
+ master_note = ""
2672
+ if not dry and (in_snaps or in_posts or in_psnaps):
2673
+ import ig_master
2674
+ m_status, m_note = ig_master.append_run(getattr(rt, "key", ""),
2675
+ in_snaps, in_posts, in_psnaps)
2676
+ if m_status == "error":
2677
+ master_note = f"⚠ the platform master copy FAILED β€” {m_note}; the tenant copy " \
2678
+ f"is complete and the next run re-appends"
2679
+ counts["master_failed"] = 1
2680
+ elif m_status == "ok":
2681
+ counts["master"] = len(in_snaps) + len(in_psnaps)
2682
 
2683
  # ⚠ A RUN IS ONLY 'ok' IF EVERY PROFILE WAS. The first live run rolled up to 'ok' while
2684
  # every CELL said `partial`, because the rollup only asked about blocked/error β€” so the rail
 
2717
 
2718
  summary = (f"{read}/{counts['profiles']} profiles read, {counts['posts']} posts "
2719
  f"({counts['new_posts']} new)")
2720
+ if lanes:
2721
+ summary += f", {counts['routed']}/{len(targets)} routed to lanes"
2722
  if counts["paid"]:
2723
  summary += f", {counts['paid']} exact via Bright Data"
2724
  if counts["metrics"]:
 
2738
  steps["write"] = "partial"
2739
  elif not dry:
2740
  steps["write"] = "ok"
2741
+ if master_note:
2742
+ summary += f" β€” {master_note}"
2743
+ state = "partial" if state != "error" else state
2744
+ steps["write"] = "partial"
2745
  if dry:
2746
  summary = f"DRY RUN (the Write step is turned off) β€” would have written: {summary}"
2747
  steps["write"] = "skipped"
2748
  state = "partial" if state != "error" else state
2749
  if notes:
2750
  summary += f" β€” {notes[0][:120]}"
2751
+ if not dry:
2752
+ # C7: the fresh master rows are exactly what the table's metric cells summarise.
2753
+ try:
2754
+ compute_metric_cells(rt, table_key)
2755
+ except Exception as e: # noqa: BLE001
2756
+ log(f"[aios-auto] metric compute {table_key} failed: {type(e).__name__}: {e}")
2757
  return (state, summary, counts, affected, steps)
2758
 
2759
 
 
2796
 
2797
  pending = str((defn.get("state") or {}).get("pendingSnapshot") or "")
2798
  if not pending:
2799
+ # C4 (wave 22): the guard holds at RUN too β€” a stored config can predate the law, and
2800
+ # the vendor bills for breadth whether the filter was saved yesterday or last month.
2801
+ guard_err = narrowing_refusal(preds)
2802
+ if guard_err:
2803
+ steps["find"] = "blocked"
2804
+ return ("error", f"the search was not started β€” {guard_err}", counts, [], steps)
2805
  if dry:
2806
  est = discover_estimate(limit)
2807
  steps["find"] = steps["write"] = "skipped"
 
2874
  label = cfg.get("targetLabel") or "IG candidates"
2875
  table_key = (ut_key_for(label, cfg.get("targetTable") or DISCOVER_TABLE) if dry
2876
  else ut_ensure(rt, label, CANDIDATE_FIELDS, username,
2877
+ key=cfg.get("targetTable") or DISCOVER_TABLE,
2878
+ flow_tag=str(defn.get("id") or "")))
2879
  existing = dict((ut_get(rt, table_key) or {}).get("rows") or {})
2880
+ # --- C6: the upsert key is the COMPOUND (handle, created_by) β€” per-user rows, per-user
2881
+ # found_counts ("each user only works with their own data" without breaking the upsert
2882
+ # law). Implemented as a synthesised key column that exists only inside this merge, so
2883
+ # `upsert_rows` keeps its one-field contract and its id/cap arithmetic runs over the WHOLE
2884
+ # table. A pre-wave row with no owner is ADOPTED by the first user who re-finds its handle
2885
+ # (the `ut_ensure` owner-adoption move) rather than duplicated beside itself.
2886
+ def _ck(handle, owner):
2887
+ return f"{str(handle or '').strip()}\n{str(owner or '').strip()}"
2888
+
2889
+ incoming_handles = {c["handle"] for c in incoming}
2890
+ for r in existing.values():
2891
+ if not str(r.get("created_by") or "").strip() and \
2892
+ str(r.get("handle") or "").strip() in incoming_handles:
2893
+ r["created_by"] = username
2894
+ existing2 = {rid: {**r, "_ckey": _ck(r.get("handle"), r.get("created_by"))}
2895
+ for rid, r in existing.items()}
2896
+ # `found_count` is ARITHMETIC OVER WHAT IS STORED, not a value from the vendor β€” re-finding
2897
+ # a profile is the signal that it keeps matching, so the counter grows instead of
2898
+ # resetting. `first_found` is written only when the pair is new, so it never moves.
2899
+ seen = {r["_ckey"]: r for r in existing2.values()}
2900
+ skey = stage_field_key(auto_id)
2901
  for c in incoming:
2902
+ c["created_by"] = username
2903
+ c["_ckey"] = _ck(c["handle"], username)
2904
+ prev_row = seen.get(c["_ckey"])
2905
  if prev_row:
2906
  counts["seen_again"] += 1
2907
  c["found_count"] = str((_ig_int(prev_row.get("found_count")) or 0) + 1)
 
2909
  counts["new"] += 1
2910
  c["found_count"] = "1"
2911
  c["first_found"] = stamp
2912
+ # C2/R6 β€” a NEW candidate's card starts at the human gate. Stamped only at birth:
2913
+ # a re-find must never pull a card somebody has already moved back into Review,
2914
+ # for the same reason it never un-ticks `tracked`.
2915
+ c[skey] = "Review"
2916
+ c[skey + "_at"] = stamp
2917
+ merged, mc = upsert_rows(existing2, incoming, "_ckey", cap=row_cap(table_key))
2918
+ merged = {rid: {k: v for k, v in r.items() if k != "_ckey"}
2919
+ for rid, r in merged.items()}
2920
  counts["capped"] = mc["capped"]
2921
  missing = [] if dry else ut_missing(rt, table_key)
2922
  counts["missing_tables"] = len(missing)
2923
  if not dry and not missing:
2924
  ut_write_rows(rt, table_key, merged)
2925
+ ensure_stage_field(rt, table_key, defn, username)
2926
  steps["write"] = "ok"
2927
  elif dry:
2928
  steps["write"] = "skipped"
 
2944
  if dry:
2945
  summary = f"DRY RUN (the Write step is turned off) β€” would have written: {summary}"
2946
  state = "partial" if (dry or counts["capped"] or missing or not counts["found"]) else "ok"
2947
+ if not dry and not missing:
2948
+ try:
2949
+ compute_metric_cells(rt, table_key) # C7 β€” see the field runner
2950
+ except Exception as e: # noqa: BLE001
2951
+ log(f"[aios-auto] metric compute {table_key} failed: {type(e).__name__}: {e}")
2952
  log(f"[aios-auto] discover {auto_id} -> {table_key}: {summary}")
2953
  return (state, summary, counts, affected, steps)
2954
 
 
3081
  "toggle": NODE_TOGGLES.get(nid, ""), "status": node_status(steps, nid)}
3082
 
3083
  on = bool(sched.get("enabled"))
3084
+ trg = defn.get("trigger") or {}
3085
+ if trg.get("key") in ("event_field", "record_created", "webhook", "email"):
3086
+ # C3 (wave 22): the trigger node SAYS which trigger this flow has β€” the board and rail
3087
+ # read the same node, so an event-triggered flow must not read "Schedule".
3088
+ t_on = bool(trg.get("enabled", True)) and not trg.get("paused")
3089
+ sub = TRIGGER_LABELS.get(trg["key"], trg["key"])
3090
+ det = {"event_field": f"{trg.get('table', '')}.{trg.get('field', '')}",
3091
+ "record_created": str(trg.get("table") or ""),
3092
+ "webhook": "POST the hook URL to fire it",
3093
+ "email": str(trg.get("query") or "")}.get(trg["key"], "")
3094
+ if trg.get("paused"):
3095
+ det = str(defn.get("statusNote") or "paused")
3096
+ nodes = [node("trigger", "trigger", sub,
3097
+ "On" if t_on else "Off", 0, panel="trigger", on=t_on, detail=det)]
3098
+ else:
3099
+ nodes = [node("trigger", "trigger", "Schedule",
3100
+ _cron_label(sched.get("cron")) if on else "Manual only", 0,
3101
+ panel="schedule", on=on,
3102
+ detail="" if on else "It still runs when you press Run now")]
3103
  edges = []
3104
 
3105
  if defn.get("kind") == "field_instagram":
 
3215
  f"automation is")
3216
  cfg, sched = dict(prev.get("config") or {}), dict(prev.get("schedule") or {})
3217
  which = target["toggle"]
3218
+ if which == "schedule" and (prev.get("trigger") or {}).get("key") in (
3219
+ "event_field", "record_created", "webhook", "email"):
3220
+ # The trigger node's switch flips THE TRIGGER when the flow has an event one β€” flipping
3221
+ # the cron under a node labelled "When a field changes" would be a switch that lies.
3222
+ trg = dict(prev.get("trigger") or {})
3223
+ trg["enabled"] = not (bool(trg.get("enabled", True)) and not trg.get("paused"))
3224
+ trg["paused"] = False # a deliberate flip clears an auto-pause: human wins
3225
+ return patch(rt, auto_id, {"trigger": trg})
3226
  if which == "schedule":
3227
  sched["enabled"] = not sched.get("enabled")
3228
  elif which == "paid":
 
3237
  return patch(rt, auto_id, {"config": cfg, "schedule": sched})
3238
 
3239
 
3240
+ # ---------------------------------------------------------------------------------------------
3241
+ # THE BOARD (wave 22, contracts C1/C2 β€” owner ruling R1: RECORDS AS CARDS)
3242
+ # ---------------------------------------------------------------------------------------------
3243
+ # The automation detail IS a kanban board: columns = the flow's stages, cards = records of the
3244
+ # target database, each record's position stored in a single-select STAGE FIELD auto-created on
3245
+ # that database β€” so the same field drives a plain Kanban view with no board code at all.
3246
+ #
3247
+ # TWO KINDS OF STAGE, and conflating them is the mistake this section is built around:
3248
+ #
3249
+ # * RUN stages (trigger/fetch/find/collect/capture/write) are MACHINERY β€” a record passes
3250
+ # through them but can never sit in one, the way a parcel is never "at" the conveyor belt.
3251
+ # They come straight off `graph()` so the board and the runner cannot drift.
3252
+ # * RECORD stages hold cards. They are the REVIEW gate (R6: discovery's review IS the
3253
+ # `tracked` promotion), its terminal, and the R5 IF-routing lanes. Only these are choices
3254
+ # of the stage field β€” a select offering "Fetch page" as a place to PUT a record would be
3255
+ # offering a lie.
3256
+ #
3257
+ # β›” WHO WRITES THE STAGE FIELD (C2): the ENGINE, everywhere β€” except a review stage, where a
3258
+ # HUMAN may advance a card to a member of the review stage's `next` and nothing else. That wall
3259
+ # is enforced twice, once per door: `move_card` below (the board's own POST) and
3260
+ # `grid_events.overlay_patch` (the plain grid/kanban door), which reads the law OUT OF THE FIELD
3261
+ # DEFINITION (`automation.humanMoves` / `automation.arrive`) because platform code must not
3262
+ # import this module. The engine STATES the law; the grid ENFORCES it mechanically.
3263
+ #
3264
+ # R7's approval-posture vocabulary rides every stage: `strict` = holds for a human,
3265
+ # `auto` = the engine advances. Today review⇒strict and everything else⇒auto BY DERIVATION —
3266
+ # the vocabulary is on the wire so a later wave can flip a stage without a client change.
3267
+
3268
+ STAGE_FIELD_PREFIX = "stage_"
3269
+ STAGE_KINDS = ("trigger", "action", "review", "branch")
3270
+ POSTURES = ("auto", "strict")
3271
+ #: One board answer carries at most this many cards PER STAGE; `counts` always carries the
3272
+ #: true totals and `truncated` names the stages that overflowed β€” a cap nobody can see is the
3273
+ #: silent-[:N] defect ([[no-unverifiable-aggregates]]), so this one is disclosed on the wire.
3274
+ BOARD_CARD_CAP = 200
3275
+
3276
+ #: R5 lanes β€” the per-record IF-routing vocabulary. Enumerated HERE (and shipped on the wire)
3277
+ #: so the client can never grow its own union of operators (the wave-9 silent-drop class).
3278
+ MAX_LANES = 6
3279
+ LANE_OPS = ("=", "!=", ">", ">=", "<", "<=", "includes", "not_includes",
3280
+ "is_empty", "is_not_empty")
3281
+ LANE_NULLARY_OPS = ("is_empty", "is_not_empty")
3282
+ #: Lane labels a flow already uses for its fixed stages. A lane literally called "Review" would
3283
+ #: collide with the stage the label is a choice FOR, and the board could no longer tell a
3284
+ #: routed card from a gated one.
3285
+ _RESERVED_STAGE_LABELS = frozenset({"review", "tracked", "declined", "write", "profile set",
3286
+ "schedule", "stage"})
3287
+
3288
+
3289
+ def stage_field_key(auto_id):
3290
+ """The stage field's key on the target database. Derived, never chosen β€” two automations on
3291
+ one table must mint two distinct fields, and a rename must never move the key."""
3292
+ return STAGE_FIELD_PREFIX + re.sub(r"[^a-z0-9_]+", "_", str(auto_id or "").lower())[:40]
3293
+
3294
+
3295
+ def clean_lanes(raw):
3296
+ """Validate the R5 lane list. Returns `(lanes, error)` β€” refuses, never coerces
3297
+ (the `clean_predicates` discipline: a condition we cannot answer is refused at WRITE time
3298
+ with the reason named, because dropping or bending it would route records nobody asked to
3299
+ route)."""
3300
+ if raw in (None, ""):
3301
+ return [], None
3302
+ if not isinstance(raw, list):
3303
+ return None, "lanes must be a list"
3304
+ if len(raw) > MAX_LANES:
3305
+ return None, f"an automation may have at most {MAX_LANES} lanes"
3306
+ out, seen_ids, defaults = [], set(), 0
3307
+ for entry in raw:
3308
+ if not isinstance(entry, dict):
3309
+ return None, "each lane must be an object with a label and an optional condition"
3310
+ label = " ".join(_s(entry.get("label"), 60).split())
3311
+ if not label:
3312
+ return None, "every lane needs a label"
3313
+ if label.strip().lower() in _RESERVED_STAGE_LABELS:
3314
+ return None, (f"{label!r} is the name of a fixed stage β€” pick another label for "
3315
+ f"the lane")
3316
+ lid = "lane_" + (re.sub(r"[^a-z0-9]+", "_", label.lower()).strip("_") or "x")[:40]
3317
+ base, n = lid, 2
3318
+ while lid in seen_ids:
3319
+ lid = f"{base}_{n}"
3320
+ n += 1
3321
+ seen_ids.add(lid)
3322
+ cond_raw = entry.get("when")
3323
+ cond = None
3324
+ if cond_raw not in (None, ""):
3325
+ if not isinstance(cond_raw, dict):
3326
+ return None, f"the condition on {label!r} must be an object"
3327
+ field = _s(cond_raw.get("field"), 80).strip()
3328
+ op = _s(cond_raw.get("op") or cond_raw.get("operator"), 20).strip()
3329
+ if not field:
3330
+ return None, f"the condition on {label!r} names no field"
3331
+ if op not in LANE_OPS:
3332
+ return None, (f"{op or 'that comparison'!r} is not one of: "
3333
+ + ", ".join(LANE_OPS))
3334
+ cond = {"field": field, "op": op}
3335
+ if op not in LANE_NULLARY_OPS:
3336
+ v = cond_raw.get("value")
3337
+ if v is None or (isinstance(v, str) and not v.strip()):
3338
+ return None, f"give a value to compare {field!r} against on {label!r}"
3339
+ cond["value"] = v.strip() if isinstance(v, str) else v
3340
+ else:
3341
+ defaults += 1
3342
+ if defaults > 1:
3343
+ return None, ("only one lane may have no condition β€” it is the catch-all, "
3344
+ "and two catch-alls would race for every record")
3345
+ out.append({"id": lid, "label": label, "when": cond})
3346
+ return out, None
3347
+
3348
+
3349
+ def _lane_num(v):
3350
+ try:
3351
+ return float(str(v).replace(",", ""))
3352
+ except (TypeError, ValueError):
3353
+ return None
3354
+
3355
+
3356
+ def lane_match(cond, row):
3357
+ """Does `row` satisfy one lane condition? None-condition matches everything (the catch-all).
3358
+
3359
+ β›” REFUSE-NEVER-COERCE, per record: an ordering comparison whose either side does not parse
3360
+ as a number answers False β€” the record simply does not enter the lane β€” never "treat blank
3361
+ as 0", which is the `toNum(null)=0` widening the 2026-08-03 owner wave was about. A blank
3362
+ cell is an unknown, and an unknown cannot be less than 10,000.
3363
+ """
3364
+ if cond is None:
3365
+ return True
3366
+ raw = (row or {}).get(cond.get("field"))
3367
+ op = cond.get("op")
3368
+ if op == "is_empty":
3369
+ return raw in (None, "")
3370
+ if op == "is_not_empty":
3371
+ return raw not in (None, "")
3372
+ want = cond.get("value")
3373
+ if op in (">", ">=", "<", "<="):
3374
+ a, b = _lane_num(raw), _lane_num(want)
3375
+ if a is None or b is None:
3376
+ return False
3377
+ return {"<": a < b, "<=": a <= b, ">": a > b, ">=": a >= b}[op]
3378
+ have_s, want_s = str(raw if raw is not None else ""), str(want if want is not None else "")
3379
+ if op == "includes":
3380
+ return want_s.lower() in have_s.lower()
3381
+ if op == "not_includes":
3382
+ return want_s.lower() not in have_s.lower()
3383
+ a, b = _lane_num(raw), _lane_num(want)
3384
+ same = (a is not None and b is not None and a == b) or have_s == want_s
3385
+ return same if op == "=" else (not same) if op == "!=" else False
3386
+
3387
+
3388
+ def route_record(lanes, row):
3389
+ """The winning lane's LABEL for one record, or '' when nothing matches.
3390
+
3391
+ First declared match wins β€” declaration order is the priority order, the same rule every
3392
+ rule engine the owner has used applies, and the catch-all (condition None) is simply the
3393
+ first lane nothing above it beat.
3394
+ """
3395
+ for lane in lanes or []:
3396
+ if lane_match(lane.get("when"), row):
3397
+ return lane["label"]
3398
+ return ""
3399
+
3400
+
3401
+ def stages_for(defn):
3402
+ """One automation β†’ `(stages, routes)` β€” C1's vocabulary, derived from `graph()` so the
3403
+ board can never disagree with the runner about what the flow does.
3404
+
3405
+ Stage extras beyond the graph node: `posture` (R7), `record` (may this stage HOLD cards),
3406
+ `assignable` (may a card be PLACED here β€” i.e. is its label a choice of the stage field).
3407
+ `record` without `assignable` marks the derived entry buckets (Profile set / Write): a card
3408
+ shows there because of what is true about the row, not because anything stamped it.
3409
+ """
3410
+ defn = defn if isinstance(defn, dict) else {}
3411
+ cfg = defn.get("config") or {}
3412
+ g = graph(defn)
3413
+ kind_map = {"trigger": "trigger", "branch": "branch"}
3414
+ stages, routes = [], []
3415
+ for n in g["nodes"]:
3416
+ stages.append({
3417
+ "id": n["id"], "label": n["title"],
3418
+ "kind": kind_map.get(n["kind"], "action"),
3419
+ "col": n["col"], "row": n["row"], "enabled": n["enabled"],
3420
+ "toggle": n["toggle"], "status": n["status"], "detail": n["detail"],
3421
+ # C1 amendment (2026-08-05): the node's `panel` rides VERBATIM β€” B joins stage β†’
3422
+ # config face on this key, never by guessing that ids match.
3423
+ "panel": n.get("panel") or n["id"],
3424
+ "posture": "auto", "record": False, "assignable": False,
3425
+ })
3426
+ for e in g["edges"]:
3427
+ routes.append({"from": e["from"], "to": e["to"], "label": e.get("label") or "",
3428
+ "condition": None})
3429
+ maxcol = max((s["col"] for s in stages), default=0)
3430
+
3431
+ def _mark(sid, record=True, assignable=False):
3432
+ for s in stages:
3433
+ if s["id"] == sid:
3434
+ s["record"], s["assignable"] = record, assignable
3435
+
3436
+ if defn.get("kind") == "discover_instagram":
3437
+ # R6: the review gate lives at the END of discovery, and the human card-move IS the
3438
+ # `tracked` promotion β€” R7-W20's tick, become a gesture. Nothing here auto-promotes.
3439
+ # C3-A2(5): the gate has TWO exits β€” Approve (β†’ Tracked) and Decline (β†’ Declined, a
3440
+ # TERMINAL state, never a delete: a candidate somebody rejected is a decision worth
3441
+ # keeping, and deleting the row would un-decide it on the next re-find).
3442
+ stages.append({"id": "review", "label": "Review", "kind": "review",
3443
+ "col": maxcol + 1, "row": 0, "enabled": True, "toggle": "",
3444
+ "status": "idle", "panel": "review", "posture": "strict",
3445
+ "record": True, "assignable": True,
3446
+ "detail": "Cards wait here for a person β€” moving one on IS the "
3447
+ "tracked promotion"})
3448
+ stages.append({"id": "tracked", "label": "Tracked", "kind": "action",
3449
+ "col": maxcol + 2, "row": 0, "enabled": True, "toggle": "",
3450
+ "status": "idle", "panel": "tracked", "posture": "auto",
3451
+ "record": True, "assignable": True,
3452
+ "detail": "The set the Instagram column automation enriches"})
3453
+ stages.append({"id": "declined", "label": "Declined", "kind": "action",
3454
+ "col": maxcol + 2, "row": 1, "enabled": True, "toggle": "",
3455
+ "status": "idle", "panel": "declined", "posture": "auto",
3456
+ "record": True, "assignable": True,
3457
+ "detail": "Rejected candidates stay here β€” a kept decision, not a "
3458
+ "delete"})
3459
+ routes.append({"from": "write", "to": "review", "label": "", "condition": None})
3460
+ routes.append({"from": "review", "to": "tracked", "label": "Approve",
3461
+ "condition": None})
3462
+ routes.append({"from": "review", "to": "declined", "label": "Decline",
3463
+ "condition": None})
3464
+ else:
3465
+ entry = "source" if defn.get("kind") == "field_instagram" else "write"
3466
+ _mark(entry)
3467
+ _mark("write")
3468
+ for i, lane in enumerate(cfg.get("lanes") or []):
3469
+ cond = lane.get("when")
3470
+ stages.append({"id": lane["id"], "label": lane["label"], "kind": "branch",
3471
+ "col": maxcol + 1, "row": i, "enabled": True, "toggle": "",
3472
+ "status": "idle", "panel": "lanes", "posture": "auto",
3473
+ "record": True, "assignable": True,
3474
+ "detail": _lane_sentence(cond)})
3475
+ routes.append({"from": "write", "to": lane["id"],
3476
+ "label": lane["label"] if cond is None else _lane_sentence(cond),
3477
+ "condition": dict(cond) if cond else None})
3478
+ return stages, routes
3479
+
3480
+
3481
+ def _lane_sentence(cond):
3482
+ if cond is None:
3483
+ return "Everything else"
3484
+ v = cond.get("value")
3485
+ return f"{cond.get('field')} {cond.get('op')}" + ("" if v is None else f" {v}")
3486
+
3487
+
3488
+ def _stage_choices(stages):
3489
+ """The stage field's select vocabulary: the ASSIGNABLE stage labels, in board order."""
3490
+ return [s["label"] for s in sorted(stages, key=lambda s: (s["col"], s["row"]))
3491
+ if s.get("assignable")]
3492
+
3493
+
3494
+ def ensure_stage_field(rt, table_key, defn, username="automation"):
3495
+ """C2: the stage field on the target database β€” created/refreshed idempotently, skipped
3496
+ entirely when the flow has nothing a record can be PLACED in (a select with an empty
3497
+ vocabulary is a column that can hold no value; it appears when the first lane or review
3498
+ stage does).
3499
+
3500
+ The field carries the WHOLE law the grid door needs (`automation.humanMoves` β€” from-label β†’
3501
+ admissible to-labels β€” and `automation.arrive` β€” to-label β†’ extra cell writes, which is how
3502
+ the kanban drag Review→Tracked also sets `tracked`), because `grid_events` may not import
3503
+ this module: the engine states the law where the enforcer can read it.
3504
+ """
3505
+ key = str(table_key or "")
3506
+ if not key or ut_get(rt, key) is None:
3507
+ return ""
3508
+ stages, _routes = stages_for(defn)
3509
+ choices = _stage_choices(stages)
3510
+ if not choices:
3511
+ return ""
3512
+ fkey = stage_field_key(defn.get("id"))
3513
+ review_next = {}
3514
+ for s in stages:
3515
+ if s["kind"] != "review":
3516
+ continue
3517
+ nxt = [r["to"] for r in _routes if r["from"] == s["id"]]
3518
+ labels = [t["label"] for t in stages if t["id"] in nxt and t.get("assignable")]
3519
+ if labels:
3520
+ review_next[s["label"]] = labels
3521
+ auto = {"flowId": str(defn.get("id") or ""), "stageField": True,
3522
+ "humanMoves": review_next}
3523
+ if defn.get("kind") == "discover_instagram":
3524
+ # Leaving Tracked is a human decision too (an admin demoting a mistake), so the flag
3525
+ # follows the CARD in both directions β€” the engine itself still never writes it (R7).
3526
+ auto["arrive"] = {"Tracked": {"tracked": "1"}, "Review": {"tracked": ""},
3527
+ "Declined": {"tracked": ""}}
3528
+ field = {"key": fkey, "label": f"Stage β€” {defn.get('name') or defn.get('id')}"[:80],
3529
+ "type": "select", "source": "overlay", "options": choices, "automation": auto}
3530
+
3531
+ have = None
3532
+ for f in (ut_get(rt, key) or {}).get("fields") or []:
3533
+ if f.get("key") == fkey:
3534
+ have = f
3535
+ break
3536
+ if have is not None and have.get("options") == choices and \
3537
+ (have.get("automation") or {}) == auto:
3538
+ return fkey # nothing would change β€” save the commit
3539
+
3540
+ def _up(cur):
3541
+ cur = cur if isinstance(cur, dict) else {}
3542
+ t = cur.get(key)
3543
+ if t is None:
3544
+ return cur
3545
+ for f in t.setdefault("fields", []):
3546
+ if f.get("key") == fkey:
3547
+ f["options"] = choices
3548
+ f["automation"] = auto
3549
+ f["type"] = "select"
3550
+ return cur
3551
+ t["fields"].append(field)
3552
+ return cur
3553
+
3554
+ rt.update(UT_STORE_KEY, _up, flush="sync")
3555
+ return fkey
3556
+
3557
+
3558
+ def _rid_num(rid):
3559
+ return int(rid) if str(rid).isdigit() else 10 ** 9
3560
+
3561
+
3562
+ def _card_stage(defn, stages, row, skey):
3563
+ """Which stage holds this record. The STAMPED label wins; a blank or unrecognised value
3564
+ falls to the DERIVED bucket β€” what is true about the row, not what anything wrote:
3565
+ discovery splits on the human `tracked` decision, an Instagram column on whether its cell
3566
+ has ever been written, and a scrape lands where its rows are born (Write)."""
3567
+ val = str((row or {}).get(skey) or "").strip()
3568
+ if val:
3569
+ for s in stages:
3570
+ if s.get("assignable") and s["label"] == val:
3571
+ return s["id"]
3572
+ kind = defn.get("kind")
3573
+ if kind == "discover_instagram":
3574
+ return "tracked" if str((row or {}).get("tracked") or "").strip() in ("1", "true", "True") \
3575
+ else "review"
3576
+ if kind == "field_instagram":
3577
+ fkey = (defn.get("config") or {}).get("fieldKey") or ""
3578
+ return "write" if str((row or {}).get(fkey) or "").strip() else "source"
3579
+ return "write"
3580
+
3581
+
3582
+ def _card_next(stages, routes, row, sid):
3583
+ """Where THIS card may go from `sid` β€” every outgoing route whose condition the record
3584
+ satisfies (declaration order kept, null = catch-all), targets limited to assignable stages.
3585
+ Evaluated per record so R5's winning path is decided on the SERVER, once."""
3586
+ assignable = {s["id"] for s in stages if s.get("assignable")}
3587
+ out = []
3588
+ for r in routes:
3589
+ if r["from"] != sid or r["to"] not in assignable or r["to"] == sid:
3590
+ continue
3591
+ cond = r.get("condition")
3592
+ if cond is not None and not lane_match(cond, row):
3593
+ continue
3594
+ if r["to"] not in out:
3595
+ out.append(r["to"])
3596
+ return out
3597
+
3598
+
3599
+ def _card_title(defn, row):
3600
+ kind = defn.get("kind")
3601
+ cfg = defn.get("config") or {}
3602
+ if kind == "discover_instagram":
3603
+ return str(row.get("handle") or row.get("full_name") or "?")
3604
+ if kind == "scrape_db":
3605
+ return str(row.get(cfg.get("keyField") or "") or "?")
3606
+ url_f = cfg.get("urlField") or ""
3607
+ return str(row.get("name") or row.get("handle") or row.get(url_f) or "?")
3608
+
3609
+
3610
+ def _card_sub(defn, row):
3611
+ kind = defn.get("kind")
3612
+ if kind == "discover_instagram":
3613
+ f = str(row.get("followers") or "").strip()
3614
+ nm = str(row.get("full_name") or "").strip()
3615
+ return f"{nm} Β· {f} followers" if (nm and f) else (nm or (f and f + " followers") or "")
3616
+ if kind == "field_instagram":
3617
+ return _s(row.get((defn.get("config") or {}).get("fieldKey") or ""), 90)
3618
+ fmap = (defn.get("config") or {}).get("fieldMap") or {}
3619
+ keys = [k for k in fmap.values() if k != (defn.get("config") or {}).get("keyField")]
3620
+ return _s(row.get(keys[0]) if keys else "", 90)
3621
+
3622
+
3623
+ def board(rt, defn, admin=False):
3624
+ """C1's whole payload: `{stages, routes, cards, stageField, counts, truncated}`.
3625
+
3626
+ `counts` carries the TRUE per-stage totals for every record stage (zeros included);
3627
+ `cards` is capped per stage at `BOARD_CARD_CAP` and any stage that overflowed is NAMED in
3628
+ `truncated` β€” the cap is disclosed, never silent. Cards ride in row-id order so the board
3629
+ is stable across polls.
3630
+ """
3631
+ stages, routes = stages_for(defn)
3632
+ cfg = defn.get("config") or {}
3633
+ table_key = str(cfg.get("targetTable") or "")
3634
+ skey = stage_field_key(defn.get("id"))
3635
+ t = ut_get(rt, table_key)
3636
+ counts = {s["id"]: 0 for s in stages if s.get("record")}
3637
+ # C1 amendment (2026-08-05): an automation with NO BOUND STAGE FIELD answers
3638
+ # `stageField: null, cards: []` β€” the stages still ride (they come from the definition),
3639
+ # and an empty board is a state, never an error. Bound = the field exists on the table.
3640
+ bound = any(f.get("key") == skey for f in ((t or {}).get("fields") or []))
3641
+ if t is None or not bound:
3642
+ return {"stages": stages, "routes": routes, "cards": [], "stageField": None,
3643
+ "counts": counts, "truncated": []}
3644
+ rows = t.get("rows") or {}
3645
+ cards, truncated, per = [], [], {}
3646
+ for rid in sorted(rows, key=_rid_num):
3647
+ row = rows.get(rid) or {}
3648
+ sid = _card_stage(defn, stages, row, skey)
3649
+ counts[sid] = counts.get(sid, 0) + 1
3650
+ if per.get(sid, 0) >= BOARD_CARD_CAP:
3651
+ if sid not in truncated:
3652
+ truncated.append(sid)
3653
+ continue
3654
+ per[sid] = per.get(sid, 0) + 1
3655
+ stage = next((s for s in stages if s["id"] == sid), None)
3656
+ nxt = _card_next(stages, routes, row, sid)
3657
+ cards.append({
3658
+ "rowId": str(rid), "stageId": sid,
3659
+ "title": _s(_card_title(defn, row), 80),
3660
+ "sub": _s(_card_sub(defn, row), 90),
3661
+ "movedAt": str(row.get(skey + "_at") or ""),
3662
+ "canAdvance": bool(stage and stage["kind"] == "review" and nxt),
3663
+ "next": nxt,
3664
+ })
3665
+ return {"stages": stages, "routes": routes, "cards": cards,
3666
+ "stageField": {"table": table_key, "key": skey},
3667
+ "counts": counts, "truncated": truncated}
3668
+
3669
+
3670
+ def move_card(rt, auto_id, row_id, to, username="", admin=False):
3671
+ """One card move, SERVER-decided (C1): a review-stage card advances only to a member of its
3672
+ per-record `next`; every other move is an admin repair onto an assignable stage. Returns
3673
+ `(fresh_board, None)` or `(None, (status, code, sentence))` β€” the route maps the tuple.
3674
+
3675
+ The write lands in the DEFINITION rows (the shared truth the engine and every viewer read),
3676
+ stamped with `movedAt`; on a discovery board arriving at Tracked sets `tracked` and leaving
3677
+ it clears it β€” the human decision travelling with the card (R6/R7)."""
3678
+ defn = all_definitions(rt).get(str(auto_id))
3679
+ if defn is None:
3680
+ return None, (404, "unknown_automation", "no automation with that id")
3681
+ stages, routes = stages_for(defn)
3682
+ cfg = defn.get("config") or {}
3683
+ table_key = str(cfg.get("targetTable") or "")
3684
+ t = ut_get(rt, table_key)
3685
+ if t is None:
3686
+ return None, (404, "no_target", f"{table_key or 'the target database'} does not exist "
3687
+ f"yet β€” run the automation once")
3688
+ skey = stage_field_key(defn.get("id"))
3689
+ if not any(f.get("key") == skey for f in (t.get("fields") or [])):
3690
+ return None, (400, "unbound",
3691
+ "this automation has no stage field on its database yet β€” save or run "
3692
+ "it once to bind the board")
3693
+ row = (t.get("rows") or {}).get(str(row_id))
3694
+ if row is None:
3695
+ return None, (404, "unknown_row", "that record is not in the target database")
3696
+ target = next((s for s in stages if s["id"] == str(to or "")), None)
3697
+ if target is None or not target.get("assignable"):
3698
+ return None, (400, "bad_stage",
3699
+ "cards can only be placed in a review, lane or terminal stage β€” the "
3700
+ "run stages are machinery a record passes through")
3701
+ cur_id = _card_stage(defn, stages, row, skey)
3702
+ cur = next((s for s in stages if s["id"] == cur_id), None)
3703
+ from_review = cur is not None and cur["kind"] == "review"
3704
+ if from_review:
3705
+ allowed = _card_next(stages, routes, row, cur_id)
3706
+ if target["id"] not in allowed and not admin:
3707
+ return None, (400, "not_next",
3708
+ "a review card advances only to its listed next stage")
3709
+ elif not admin:
3710
+ return None, (403, "admin_only",
3711
+ "only a review card can be advanced by hand β€” moving anything else is "
3712
+ "an admin repair")
3713
+ values = {skey: target["label"], skey + "_at": _iso()}
3714
+ if defn.get("kind") == "discover_instagram":
3715
+ values["tracked"] = "1" if target["id"] == "tracked" else ""
3716
+
3717
+ def _up(cur_b):
3718
+ cur_b = cur_b if isinstance(cur_b, dict) else {}
3719
+ tt = cur_b.get(table_key)
3720
+ if tt is not None:
3721
+ tt.setdefault("rows", {}).setdefault(str(row_id), {}).update(values)
3722
+ return cur_b
3723
+
3724
+ rt.update(UT_STORE_KEY, _up, flush="sync")
3725
+ if from_review:
3726
+ review_audit(rt, defn.get("id"), row_id, cur["label"], target["label"], username)
3727
+ return board(rt, defn, admin=admin), None
3728
+
3729
+
3730
+ #: How many review decisions an automation remembers. Bounded like `runs` β€” an audit that can
3731
+ #: grow a definition without limit is a serialisation cost wearing a compliance hat.
3732
+ MAX_REVIEWS = 100
3733
+
3734
+
3735
+ def review_audit(rt, auto_id, row_id, from_label, to_label, username):
3736
+ """C3-A2(5): a review decision is AUDITED β€” who moved which card where, when. Appended to
3737
+ the definition (newest first, bounded) by BOTH doors: `move_card` here, and the grid door
3738
+ in `core.grid_events`, which writes the same shape mechanically off the field's `flowId`."""
3739
+ entry = {"ts": _iso(), "user": _s(username, 80), "rowId": str(row_id),
3740
+ "from": _s(from_label, 60), "to": _s(to_label, 60)}
3741
+
3742
+ def _up(cur):
3743
+ cur = cur if isinstance(cur, dict) else {}
3744
+ d = cur.get(str(auto_id))
3745
+ if d is not None:
3746
+ d["reviews"] = ([entry] + list(d.get("reviews") or []))[:MAX_REVIEWS]
3747
+ return cur
3748
+
3749
+ rt.update(STORE_KEY, _up, flush="sync")
3750
+
3751
+
3752
+ # ---------------------------------------------------------------------------------------------
3753
+ # METRIC FIELDS (wave 22, contract C7) + THE SUBJECT PURGE (D-24)
3754
+ # ---------------------------------------------------------------------------------------------
3755
+ # A metric field is `{measure, window, agg}` over the MASTER series (C6's pooling benefit β€”
3756
+ # the value reflects every pull the platform has, not just this tenant's). Computed by the
3757
+ # ENGINE and stored as machine cells (C7 amendment: run+tick time β€” the ut wire lives in files
3758
+ # no session owns this wave), human-write-refused at the grid door, and every number drills to
3759
+ # the exact snapshot rows behind it.
3760
+ #
3761
+ # β›” NO DATA IS BLANK, NEVER ZERO. A handle the master has never seen, a window with no
3762
+ # snapshots in it, a post series with no measured engagement β€” all read as an EMPTY cell. Zero
3763
+ # is a measurement ("they have none"); blank is an admission ("we have not looked / it was not
3764
+ # readable") β€” the `_bd_posts_count` law, one layer up.
3765
+
3766
+ METRIC_MEASURES = ("followers", "avg_engagement", "likes", "comments")
3767
+ METRIC_WINDOWS = ("latest", "last_3_posts", "last_7d", "last_30d")
3768
+ #: Which measures read the PROFILE series vs the POST series β€” and which windows/aggs each
3769
+ #: side can answer. A profile count over `last_3_posts` is a question the data cannot answer;
3770
+ #: refused at clean time, never bent (mirrored in `core.user_tables`, gate-pinned).
3771
+ PROFILE_MEASURES = ("followers", "avg_engagement")
3772
+ METRIC_AGGS = ("avg", "sum", "latest")
3773
+
3774
+
3775
+ def metric_value(series, measure, window, agg="", today=None):
3776
+ """One metric over one handle's master series β†’ `(value_string_or_None, drill_rows)`.
3777
+
3778
+ `today` is a PARAMETER ([[date-window-vocabulary]]) β€” the caller decides the reference
3779
+ day; post-count windows count back from the newest post. `drill_rows` are the exact rows
3780
+ the number came from, so the route can honour [[no-unverifiable-aggregates]] without
3781
+ recomputing differently."""
3782
+ series = series or {}
3783
+ today = today or _now()
3784
+ if measure in PROFILE_MEASURES:
3785
+ rows = [r for r in series.get("snapshots") or []
3786
+ if str(r.get(measure) if r.get(measure) is not None else "").strip() != ""]
3787
+ if window in ("last_7d", "last_30d"):
3788
+ days = 7 if window == "last_7d" else 30
3789
+ floor = today - _dt.timedelta(days=days)
3790
+ rows = [r for r in rows
3791
+ if (_parse_iso(r.get("pulled_at")) or _dt.datetime.min) >= floor]
3792
+ if not rows:
3793
+ return None, []
3794
+ if window == "latest" or agg == "latest":
3795
+ picked = [rows[-1]]
3796
+ else:
3797
+ picked = rows
3798
+ vals = [_lane_num(r.get(measure)) for r in picked]
3799
+ vals = [v for v in vals if v is not None]
3800
+ if not vals:
3801
+ return None, []
3802
+ out = vals[-1] if (window == "latest" or agg == "latest") else \
3803
+ (sum(vals) if agg == "sum" else sum(vals) / len(vals))
3804
+ if measure == "avg_engagement":
3805
+ # The vendor's rate is 0-1; the pct cell renders POINTS (the semantic-pct vs
3806
+ # transform-pct scar) β€” scaled exactly once, here.
3807
+ return f"{out * 100:.2f}", picked
3808
+ return (f"{out:.0f}" if float(out).is_integer() else f"{out:.2f}"), picked
3809
+ # --- post measures: select POSTS by window, then each post's LATEST measured snapshot.
3810
+ posts = [p for p in series.get("posts") or [] if str(p.get("posted_at") or "").strip()]
3811
+ posts.sort(key=lambda p: str(p.get("posted_at")))
3812
+ if window == "latest":
3813
+ picked_posts = posts[-1:]
3814
+ elif window == "last_3_posts":
3815
+ picked_posts = posts[-3:]
3816
+ else:
3817
+ days = 7 if window == "last_7d" else 30
3818
+ floor = today - _dt.timedelta(days=days)
3819
+ picked_posts = [p for p in posts
3820
+ if (_parse_iso(str(p.get("posted_at")).replace(" ", "T"))
3821
+ or _dt.datetime.min) >= floor]
3822
+ vals, drill = [], []
3823
+ for p in picked_posts:
3824
+ snaps = (series.get("postSnapshots") or {}).get(str(p.get("shortcode") or "")) or []
3825
+ for snap in reversed(snaps):
3826
+ raw = snap.get(measure)
3827
+ v = _lane_num(raw)
3828
+ if v is not None and str(raw).strip() != "":
3829
+ vals.append(v)
3830
+ drill.append(snap)
3831
+ break
3832
+ if not vals:
3833
+ return None, []
3834
+ out = sum(vals) if (agg or "sum") == "sum" else \
3835
+ (vals[-1] if agg == "latest" else sum(vals) / len(vals))
3836
+ return (f"{out:.0f}" if float(out).is_integer() else f"{out:.2f}"), drill
3837
+
3838
+
3839
+ def metric_fields_of_table(t):
3840
+ return [f for f in ((t or {}).get("fields") or []) if isinstance(f.get("metric"), dict)]
3841
+
3842
+
3843
+ def _table_handle(row, url_field):
3844
+ return str(row.get("handle") or ig_handle(str(row.get(url_field or "") or ""))
3845
+ or "").strip().lower()
3846
+
3847
+
3848
+ def compute_metric_cells(rt, table_key, today=None):
3849
+ """Recompute every metric cell on ONE table from the master series. One coalesced write,
3850
+ only when something actually changed (the flush-ceiling law); zero reads when the table
3851
+ has no metric fields or the master is off. Returns the number of rows touched."""
3852
+ t = ut_get(rt, table_key)
3853
+ mfields = metric_fields_of_table(t)
3854
+ if not mfields:
3855
+ return 0
3856
+ import ig_master
3857
+ if not ig_master.configured():
3858
+ return 0
3859
+ url_field = next((f.get("key") for f in (t.get("fields") or [])
3860
+ if f.get("type") == "url"), "")
3861
+ rows = t.get("rows") or {}
3862
+ handles = {rid: _table_handle(row or {}, url_field) for rid, row in rows.items()}
3863
+ series = ig_master.series_for({h for h in handles.values() if h})
3864
+ changes = {}
3865
+ for rid, row in rows.items():
3866
+ s = series.get(handles.get(rid) or "")
3867
+ for f in mfields:
3868
+ bag = f["metric"]
3869
+ val, _drill = (metric_value(s, bag.get("measure"), bag.get("window"),
3870
+ bag.get("agg") or "", today=today)
3871
+ if s else (None, []))
3872
+ want = "" if val is None else str(val)
3873
+ if str((row or {}).get(f["key"], "")) != want:
3874
+ changes.setdefault(str(rid), {})[f["key"]] = want
3875
+ if not changes:
3876
+ return 0
3877
+
3878
+ def _up(cur):
3879
+ cur = cur if isinstance(cur, dict) else {}
3880
+ tt = cur.get(table_key)
3881
+ if tt is not None:
3882
+ for rid, vals in changes.items():
3883
+ tt.setdefault("rows", {}).setdefault(rid, {}).update(vals)
3884
+ return cur
3885
+
3886
+ rt.update(UT_STORE_KEY, _up, flush="sync")
3887
+ return len(changes)
3888
+
3889
+
3890
+ def refresh_metrics(rt, today=None, log=print):
3891
+ """The tick half of the C7 amendment: `today` advances at tick cadence, so a date-window
3892
+ metric can never go staler than one tick while a scheduler exists. Cheap by construction β€”
3893
+ a table without metric fields costs a dict scan and nothing else."""
3894
+ touched = 0
3895
+ for tk, t in ut_all(rt).items():
3896
+ if metric_fields_of_table(t):
3897
+ try:
3898
+ touched += compute_metric_cells(rt, tk, today=today)
3899
+ except Exception as e: # noqa: BLE001
3900
+ log(f"[aios-auto] metric refresh {tk} failed: {type(e).__name__}: {e}")
3901
+ return touched
3902
+
3903
+
3904
+ def purge_subject(rt, handle):
3905
+ """D-24: right-to-erasure for ONE Instagram subject β€” every row about them leaves the
3906
+ tenant's four `ut_ig_*` tables AND the platform master (R2 made the master half
3907
+ non-optional: a purge that missed the pooled copy would not be erasure). Returns
3908
+ `{table: removed}` counts, master rows prefixed `master:` β€” every count drills to what is
3909
+ now ABSENT, which is the one aggregate whose drill is emptiness."""
3910
+ subject = str(handle or "").strip().lstrip("@").lower()
3911
+ if not subject:
3912
+ return {}
3913
+ counts = {}
3914
+ tables = ut_all(rt)
3915
+ post_rows = (tables.get("ut_ig_posts") or {}).get("rows") or {}
3916
+ codes = {str(r.get("shortcode") or "") for r in post_rows.values()
3917
+ if str((r or {}).get("influencer_key") or "").strip().lower() == subject}
3918
+
3919
+ keeps = {
3920
+ "ut_ig_snapshots": lambda r: str((r or {}).get("influencer_key")
3921
+ or "").strip().lower() != subject,
3922
+ "ut_ig_posts": lambda r: str((r or {}).get("influencer_key")
3923
+ or "").strip().lower() != subject,
3924
+ "ut_ig_post_snapshots": lambda r: str((r or {}).get("shortcode") or "") not in codes,
3925
+ DISCOVER_TABLE: lambda r: str((r or {}).get("handle")
3926
+ or "").strip().lower() != subject,
3927
+ }
3928
+
3929
+ def _up(cur):
3930
+ cur = cur if isinstance(cur, dict) else {}
3931
+ for tk, keep in keeps.items():
3932
+ t = cur.get(tk)
3933
+ if t is None:
3934
+ continue
3935
+ rows = t.get("rows") or {}
3936
+ nxt = {rid: r for rid, r in rows.items() if keep(r)}
3937
+ counts[tk] = len(rows) - len(nxt)
3938
+ t["rows"] = nxt
3939
+ return cur
3940
+
3941
+ rt.update(UT_STORE_KEY, _up, flush="sync")
3942
+ import ig_master
3943
+ for bucket, n in (ig_master.purge_handle(subject) or {}).items():
3944
+ counts[f"master:{bucket}"] = n
3945
+ return counts
3946
+
3947
+
3948
+ # ---------------------------------------------------------------------------------------------
3949
+ # TRIGGERS (wave 22, contract C3 + amendment A2 β€” owner ruling R4; closes D-33)
3950
+ # ---------------------------------------------------------------------------------------------
3951
+ # Six ways an automation starts, exactly: manual | schedule | event_field | record_created |
3952
+ # webhook | email. The first two are what always existed (Run now; cron via the tick). The four
3953
+ # new ones are EVENTS, and A2 makes their discipline LAW rather than taste:
3954
+ #
3955
+ # * **EDGE, NEVER LEVEL (A2(1)).** A condition trigger fires on entering the matching state,
3956
+ # not for being in it. Implemented as per-record ARMED state over successive evaluations
3957
+ # (`state.eventDisarmed`): a record fires when it matches while armed, DISARMS, and re-arms
3958
+ # only by evaluating False β€” Airtable's documented leave-and-re-enter rule, without needing
3959
+ # a before-image of a row whose truth is spread over strata. Enabling a trigger SEEDS the
3960
+ # disarmed set with everything currently matching, so already-matching records do not fire
3961
+ # (`_seed_event_state`). A settle window coalesces write bursts (the per-keystroke scar).
3962
+ # * **LOOP PREVENTION IS STRUCTURAL (A2(2)).** The hooks live on the HUMAN doors only
3963
+ # (`grid_events.overlay_patch`, `user_tables.add_row`); the engine's own writers
3964
+ # (`ut_write_rows`, the runners' coalesced updates, `patch_cells` from `move_card`) never
3965
+ # emit β€” so an automation's write cannot fire event triggers, its own or a sibling's, by
3966
+ # construction. The circuit breaker on top (>60 fires/5 min auto-pauses with the reason as
3967
+ # a statusNote) catches whatever construction did not foresee.
3968
+ # * **FLOOD HOLD (A2(3)).** One evaluation yielding more than 100 candidate records holds
3969
+ # instead of running β€” a partial run entry names the count and the deliberate way through
3970
+ # (Run now). C4's discovery guard is this rule's special case.
3971
+ # * **REFIRE DEFAULTS (A2(4)), hard-coded this wave:** record_created fires once per record
3972
+ # EVER (a high-water mark over row ids, so an undo-restored row cannot re-fire);
3973
+ # event_field fires every transition.
3974
+
3975
+ TRIGGER_KEYS = ("manual", "schedule", "event_field", "record_created", "webhook", "email")
3976
+ TRIGGER_LABELS = {
3977
+ "manual": "Manual", "schedule": "On a schedule",
3978
+ "event_field": "When a field changes", "record_created": "When a record is created",
3979
+ "webhook": "When the webhook is called", "email": "When an email arrives",
3980
+ }
3981
+ #: The settle window for field-change bursts (A2(1)). 0 evaluates INLINE β€” the gates run there,
3982
+ #: and so would a deployment that prefers immediacy over coalescing.
3983
+ EVENT_SETTLE_SECONDS = float(os.environ.get("AIOS_EVENT_SETTLE_SECONDS") or 15)
3984
+ FIRE_LIMIT = 60 # A2(2): fires per window before the breaker pauses
3985
+ FIRE_WINDOW_SECONDS = 300
3986
+ FLOOD_LIMIT = 100 # A2(3): candidate records one evaluation may act on
3987
+ EMAIL_SEEN_CAP = 500 # message-id dedupe memory per automation
3988
+ EMAIL_MAX_PER_POLL = 25 # bounded by construction β€” a poll is a tick guest
3989
+ CONSECUTIVE_FAILURE_PAUSE = 5 # airtable-brief rec 6: a dead credential must not burn quota
3990
+
3991
+ EMAIL_FIELDS = [
3992
+ field_def("email_id", "Email id"), field_def("email_from", "From"),
3993
+ field_def("email_subject", "Subject"), field_def("email_date", "Date"),
3994
+ field_def("email_snippet", "Snippet"), field_def("email_seen_at", "Seen at"),
3995
+ ]
3996
+
3997
+
3998
+ def clean_trigger(raw, previous=None):
3999
+ """Validate a definition's `trigger`. Returns `(trigger|None, error)` β€” None is legal and
4000
+ means what it always meant: manual + whatever `schedule` says.
4001
+
4002
+ ⚠ A3 (2026-08-05): the stored/wire name is `key` (`kind` accepted on input for symmetry
4003
+ with the definition's own vocabulary). And an INCOMPLETE event trigger is STORED INERT
4004
+ rather than refused β€” the picker writes `{key}` first and the table/field after, the
4005
+ wave-18 unconfigured-automation-column precedent exactly; `configured: false` rides the
4006
+ wire so the surface says "finish setting this up" instead of snapping back to Manual. It
4007
+ cannot fire while incomplete (the hooks match on the table it does not name), which is the
4008
+ fail-closed direction. MALFORMED parts (an unknown comparison, a valueless compare, a
4009
+ condition on a field the trigger does not watch) are still refused with the sentence β€”
4010
+ incomplete is a state, wrong is not.
4011
+ """
4012
+ if raw in (None, "", {}):
4013
+ return (dict(previous) if isinstance(previous, dict) and previous else None), None
4014
+ if not isinstance(raw, dict):
4015
+ return None, "the trigger must be an object"
4016
+ prev = previous if isinstance(previous, dict) else {}
4017
+ key = _s(raw.get("key") or raw.get("kind") or prev.get("key") or prev.get("kind"),
4018
+ 30).strip()
4019
+ if key not in TRIGGER_KEYS:
4020
+ return None, (f"{key or 'that trigger'!r} is not one of: " + ", ".join(TRIGGER_KEYS))
4021
+ if key in ("manual", "schedule"):
4022
+ # Not stored: `schedule` already owns the cron and Run now always works. Storing a
4023
+ # no-op trigger would be a second copy of that fact, free to disagree with it.
4024
+ return None, None
4025
+ out = {"key": key,
4026
+ "enabled": bool(raw["enabled"]) if "enabled" in raw else
4027
+ bool(prev.get("enabled", True)),
4028
+ "paused": bool(raw["paused"]) if "paused" in raw else bool(prev.get("paused"))}
4029
+ if key in ("event_field", "record_created"):
4030
+ table = _s(raw.get("table") if "table" in raw else prev.get("table"), 60).strip()
4031
+ if table and not table.startswith(UT_PREFIX):
4032
+ return None, ("event triggers watch blank databases (ut_*) this wave β€” "
4033
+ f"{table!r} is not one")
4034
+ out["table"] = table
4035
+ if key == "event_field":
4036
+ fkey = _s(raw.get("field") if "field" in raw else prev.get("field"), 80).strip()
4037
+ out["field"] = fkey
4038
+ when_raw = raw.get("when") if "when" in raw else prev.get("when")
4039
+ if when_raw in (None, ""):
4040
+ out["when"] = None
4041
+ else:
4042
+ if not isinstance(when_raw, dict):
4043
+ return None, "the trigger condition must be an object"
4044
+ if not fkey:
4045
+ return None, "name the watched field before adding a condition on it"
4046
+ cf = _s(when_raw.get("field"), 80).strip() or fkey
4047
+ if cf != fkey:
4048
+ # The edge is evaluated over the WRITTEN value (see the section header); a
4049
+ # condition on a different field would need a row image this evaluation does
4050
+ # not have β€” refused with the reason, never quietly evaluated wrong.
4051
+ return None, ("this wave a trigger condition tests the WATCHED field itself β€” "
4052
+ f"the condition names {cf!r} but the trigger watches {fkey!r}")
4053
+ op = _s(when_raw.get("op") or when_raw.get("operator"), 20).strip()
4054
+ if op not in LANE_OPS:
4055
+ return None, f"{op or 'that comparison'!r} is not one of: " + ", ".join(LANE_OPS)
4056
+ cond = {"field": fkey, "op": op}
4057
+ if op not in LANE_NULLARY_OPS:
4058
+ v = when_raw.get("value")
4059
+ if v is None or (isinstance(v, str) and not v.strip()):
4060
+ return None, f"give a value to compare {fkey!r} against"
4061
+ cond["value"] = v.strip() if isinstance(v, str) else v
4062
+ out["when"] = cond
4063
+ if key == "webhook":
4064
+ # The token is MINTED here, once, and survives every later patch β€” rotating it on
4065
+ # every Save would silently break the external caller the URL was given to.
4066
+ out["token"] = _s(prev.get("token"), 64) or _secrets_token()
4067
+ if key == "email":
4068
+ out["query"] = _s(raw.get("query") if "query" in raw else prev.get("query"),
4069
+ 200).strip() or "in:inbox is:unread"
4070
+ out["configured"] = bool(
4071
+ out.get("table")) if key == "record_created" else bool(
4072
+ out.get("table") and out.get("field")) if key == "event_field" else True
4073
+ return out, None
4074
+
4075
+
4076
+ def _secrets_token():
4077
+ import secrets as _sec
4078
+ return _sec.token_urlsafe(24)
4079
+
4080
+
4081
+ # --- the circuit breaker (A2(2)) β€” process memory, like _RUNNING: a counter that outlives the
4082
+ # process would keep punishing an automation for a storm that ended with the restart.
4083
+ _FIRES = {}
4084
+ _FIRES_LOCK = threading.Lock()
4085
+
4086
+
4087
+ def _breaker_trips(tenant, auto_id, now=None):
4088
+ now = now if now is not None else time.time()
4089
+ key = (tenant, str(auto_id))
4090
+ with _FIRES_LOCK:
4091
+ log = [t for t in _FIRES.get(key, []) if now - t < FIRE_WINDOW_SECONDS]
4092
+ log.append(now)
4093
+ _FIRES[key] = log
4094
+ return len(log) > FIRE_LIMIT
4095
+
4096
+
4097
+ def _pause_trigger(rt, auto_id, note):
4098
+ def _up(cur):
4099
+ cur = cur if isinstance(cur, dict) else {}
4100
+ d = cur.get(str(auto_id))
4101
+ if d is not None:
4102
+ trg = d.get("trigger")
4103
+ if isinstance(trg, dict):
4104
+ trg["paused"] = True
4105
+ d["statusNote"] = _s(note, 200)
4106
+ return cur
4107
+ rt.update(STORE_KEY, _up, flush="sync")
4108
+
4109
+
4110
+ def trigger_fire(rt, tenant, auto_id, log=print):
4111
+ """One trigger firing β€” breaker first, then the ordinary async run. False when it did not
4112
+ start (breaker, or already running β€” both are answers, not errors)."""
4113
+ if _breaker_trips(tenant, auto_id):
4114
+ note = (f"auto-paused: more than {FIRE_LIMIT} trigger fires in "
4115
+ f"{FIRE_WINDOW_SECONDS // 60} minutes β€” something is writing this trigger's "
4116
+ f"subject in a loop")
4117
+ _pause_trigger(rt, auto_id, note)
4118
+ log(f"[aios-auto] breaker: {auto_id} {note}")
4119
+ return False
4120
+ return run_async(rt, tenant, auto_id, username="automation", log=log)
4121
+
4122
+
4123
+ # --- the settle buffer (A2(1)) β€” per (tenant, automation), coalescing a burst into ONE
4124
+ # evaluation. With EVENT_SETTLE_SECONDS == 0 the evaluation is INLINE (deterministic for gates).
4125
+ _SETTLE = {}
4126
+ _SETTLE_LOCK = threading.Lock()
4127
+
4128
+
4129
+ def _settle_buffer(rt, tenant, auto_id, row_id, after, log=print):
4130
+ key = (tenant, str(auto_id))
4131
+ if EVENT_SETTLE_SECONDS <= 0:
4132
+ with _SETTLE_LOCK:
4133
+ buf = _SETTLE.setdefault(key, {"rows": {}})
4134
+ buf["rows"][str(row_id)] = after
4135
+ _settle_eval(rt, tenant, auto_id, log=log)
4136
+ return
4137
+ with _SETTLE_LOCK:
4138
+ buf = _SETTLE.setdefault(key, {"rows": {}})
4139
+ buf["rows"][str(row_id)] = after
4140
+ timer = buf.get("timer")
4141
+ if timer is not None:
4142
+ timer.cancel() # the burst continues β€” push the window out
4143
+ timer = threading.Timer(EVENT_SETTLE_SECONDS, _settle_eval,
4144
+ args=(rt, tenant, auto_id), kwargs={"log": log})
4145
+ timer.daemon = True
4146
+ buf["timer"] = timer
4147
+ timer.start()
4148
+
4149
+
4150
+ def _settle_eval(rt, tenant, auto_id, log=print):
4151
+ """Evaluate one settled burst: edge over per-record armed state, flood hold, then fire."""
4152
+ with _SETTLE_LOCK:
4153
+ buf = _SETTLE.pop((tenant, str(auto_id)), None)
4154
+ rows = (buf or {}).get("rows") or {}
4155
+ if not rows:
4156
+ return
4157
+ d = all_definitions(rt).get(str(auto_id))
4158
+ trg = (d or {}).get("trigger") or {}
4159
+ if trg.get("key") != "event_field" or trg.get("paused") or not trg.get("enabled", True):
4160
+ return
4161
+ when = trg.get("when")
4162
+ fired = []
4163
+ if when:
4164
+ disarmed = set((d.get("state") or {}).get("eventDisarmed") or [])
4165
+ nxt = set(disarmed)
4166
+ for rid, after in rows.items():
4167
+ if lane_match(when, {when.get("field"): after}):
4168
+ if rid not in disarmed:
4169
+ fired.append(rid) # false→true THIS evaluation: the edge
4170
+ nxt.add(rid)
4171
+ else:
4172
+ nxt.discard(rid) # left the state β€” re-armed (Airtable's rule)
4173
+ if nxt != disarmed:
4174
+ set_state(rt, auto_id, {"eventDisarmed": sorted(nxt)[:5000]})
4175
+ if not fired:
4176
+ return
4177
+ else:
4178
+ fired = list(rows) # "the field changed" β€” the burst is the edge
4179
+ if len(fired) > FLOOD_LIMIT:
4180
+ _commit_run(rt, auto_id, "partial",
4181
+ f"the trigger matched {len(fired)} records in one evaluation β€” more than "
4182
+ f"the {FLOOD_LIMIT}-record flood hold, so nothing ran. Press Run now to "
4183
+ f"process them deliberately", {"held": len(fired)}, True)
4184
+ return
4185
+ trigger_fire(rt, tenant, auto_id, log=log)
4186
+
4187
+
4188
+ def _seed_event_state(rt, defn):
4189
+ """A2(1)'s enable rule: records ALREADY matching when the trigger is set start DISARMED, so
4190
+ turning the trigger on fires nothing — the first fire needs a real false→true transition.
4191
+ Evaluated over the definition rows (the machine-written truth this trigger class watches)."""
4192
+ trg = (defn or {}).get("trigger") or {}
4193
+ if trg.get("key") != "event_field" or not trg.get("when") or not trg.get("configured"):
4194
+ return
4195
+ when = trg.get("when")
4196
+ t = ut_get(rt, trg.get("table") or "")
4197
+ matching = sorted(str(rid) for rid, row in ((t or {}).get("rows") or {}).items()
4198
+ if lane_match(when, {when.get("field"): (row or {}).get(trg.get("field"))}))
4199
+ set_state(rt, defn.get("id"), {"eventDisarmed": matching[:5000]})
4200
+
4201
+
4202
+ def grid_hook(evt):
4203
+ """THE listener the human write doors emit into (registered onto
4204
+ `core.user_tables.ROW_HOOKS` by `routes_automation` at import β€” the one place that may
4205
+ import both sides). Never raises into a write path; a broken trigger listener must not
4206
+ break typing into a cell."""
4207
+ try:
4208
+ st = evt.get("st")
4209
+ if st is None:
4210
+ return
4211
+ tenant = str(getattr(st, "key", "") or "royal-imports")
4212
+ table = str(evt.get("table") or "")
4213
+ kind = str(evt.get("type") or "")
4214
+ defs = all_definitions(st)
4215
+ for aid, d in defs.items():
4216
+ trg = (d or {}).get("trigger") or {}
4217
+ if trg.get("paused") or not trg.get("enabled", True):
4218
+ continue
4219
+ if kind == "record_created" and trg.get("key") == "record_created" \
4220
+ and str(trg.get("table") or "") == table:
4221
+ rid = str(evt.get("rowId") or "")
4222
+ hw = _ig_int((d.get("state") or {}).get("rcHighwater")) or 0
4223
+ ridn = int(rid) if rid.isdigit() else None
4224
+ if ridn is None or ridn <= hw:
4225
+ continue # once per record EVER (A2(4)) β€” undo-proof
4226
+ set_state(st, aid, {"rcHighwater": ridn})
4227
+ trigger_fire(st, tenant, aid)
4228
+ elif kind == "event_field" and trg.get("key") == "event_field" \
4229
+ and str(trg.get("table") or "") == table \
4230
+ and str(trg.get("field") or "") == str(evt.get("field") or ""):
4231
+ _settle_buffer(st, tenant, aid, str(evt.get("rowId") or ""), evt.get("after"))
4232
+ except Exception as e: # noqa: BLE001
4233
+ print(f"[aios-auto] trigger hook failed: {type(e).__name__}: {e}")
4234
+
4235
+
4236
+ def hook_fire(rt, tenant, auto_id, token):
4237
+ """The webhook trigger's decision, separated from FastAPI so the gate can drive it.
4238
+ Returns `(status, payload)` β€” 404 unknown, 403 wrong/missing token or wrong trigger kind,
4239
+ 409 already running, 200 started."""
4240
+ import hmac as _hmac
4241
+ defn = all_definitions(rt).get(str(auto_id))
4242
+ if defn is None:
4243
+ return 404, {"error": "unknown_automation"}
4244
+ trg = defn.get("trigger") or {}
4245
+ want = str(trg.get("token") or "")
4246
+ if trg.get("key") != "webhook" or not want:
4247
+ return 403, {"error": "no_webhook", "message":
4248
+ "this automation has no webhook trigger"}
4249
+ if trg.get("paused") or not trg.get("enabled", True):
4250
+ return 403, {"error": "webhook_off", "message": "the webhook trigger is turned off"}
4251
+ if not _hmac.compare_digest(want, str(token or "")):
4252
+ return 403, {"error": "bad_token", "message": "that token is not valid"}
4253
+ started = trigger_fire(rt, tenant, auto_id)
4254
+ return 200, {"started": bool(started), "at": _iso()}
4255
+
4256
+
4257
+ def email_poll(rt, tenant, auto_id, defn, log=print, _list=None, _read=None):
4258
+ """The email trigger's tick half (C3): poll the CREATOR's Gmail through C5's seam, write a
4259
+ row per NEW matching message, fire the flow. `_list`/`_read` are injection points so the
4260
+ gate drives this without a network; production leaves them None.
4261
+
4262
+ Fail-closed and QUIET when unconnected: the statusNote says so ONCE (not a run entry per
4263
+ tick β€” 96 identical failures a day is a klaxon, not a status). Bounded everywhere: at most
4264
+ `EMAIL_MAX_PER_POLL` new messages per tick, the flood hold above that, one coalesced write.
4265
+ """
4266
+ trg = defn.get("trigger") or {}
4267
+ if trg.get("key") != "email" or trg.get("paused") or not trg.get("enabled", True):
4268
+ return None
4269
+ import oauth_connect
4270
+ creator = str(defn.get("createdBy") or "").strip() or "admin"
4271
+ token, err = oauth_connect.google_creds(rt, creator)
4272
+ if err:
4273
+ if (defn.get("statusNote") or "") != err:
4274
+ def _note(cur):
4275
+ cur = cur if isinstance(cur, dict) else {}
4276
+ dd = cur.get(str(auto_id))
4277
+ if dd is not None:
4278
+ dd["statusNote"] = _s(err, 200)
4279
+ return cur
4280
+ rt.update(STORE_KEY, _note, flush="sync")
4281
+ return None
4282
+ lister = _list or (lambda q, n: oauth_connect.gmail_list(token, q, n))
4283
+ reader = _read or (lambda mid: oauth_connect.gmail_message(token, mid))
4284
+ ids, lerr = lister(trg.get("query") or "", EMAIL_MAX_PER_POLL + FLOOD_LIMIT)
4285
+ if lerr:
4286
+ return _commit_run(rt, auto_id, "partial", f"the Gmail poll did not answer β€” {lerr}",
4287
+ {}, True)
4288
+ seen = set((defn.get("state") or {}).get("emailSeen") or [])
4289
+ fresh = [m for m in ids if m not in seen]
4290
+ if not fresh:
4291
+ return None # nothing new is not a run β€” no history spam
4292
+ if len(fresh) > FLOOD_LIMIT:
4293
+ return _commit_run(rt, auto_id, "partial",
4294
+ f"{len(fresh)} new emails matched in one poll β€” more than the "
4295
+ f"{FLOOD_LIMIT}-record flood hold, so nothing was written. Narrow "
4296
+ f"the query, or press Run now after adjusting it",
4297
+ {"held": len(fresh)}, True)
4298
+ fresh = fresh[:EMAIL_MAX_PER_POLL]
4299
+ rows_in, notes = [], []
4300
+ for mid in fresh:
4301
+ row, rerr = reader(mid)
4302
+ if row:
4303
+ rows_in.append(row)
4304
+ elif rerr:
4305
+ notes.append(rerr)
4306
+ table_key = (defn.get("config") or {}).get("targetTable") or ""
4307
+ if not table_key:
4308
+ return _commit_run(rt, auto_id, "error",
4309
+ "the email trigger has nowhere to write β€” the automation names no "
4310
+ "target database", {}, False)
4311
+ ut_ensure(rt, (defn.get("config") or {}).get("targetLabel") or defn.get("name") or "Inbox",
4312
+ EMAIL_FIELDS, username=str(defn.get("createdBy") or "automation"), key=table_key)
4313
+ skey = stage_field_key(auto_id)
4314
+ stamp = _iso()
4315
+ for r in rows_in:
4316
+ r[skey + "_at"] = stamp
4317
+ existing = dict((ut_get(rt, table_key) or {}).get("rows") or {})
4318
+ merged, counts = upsert_rows(existing, rows_in, "email_id", cap=row_cap(table_key))
4319
+ ut_write_rows(rt, table_key, merged)
4320
+ new_seen = (list(seen) + fresh)[-EMAIL_SEEN_CAP:]
4321
+ set_state(rt, auto_id, {"emailSeen": new_seen})
4322
+ summary = (f"{len(fresh)} new email{'' if len(fresh) == 1 else 's'} matched β€” "
4323
+ f"{counts['inserted']} row{'' if counts['inserted'] == 1 else 's'} written")
4324
+ if notes:
4325
+ summary += f" β€” {notes[0][:100]}"
4326
+ entry = _commit_run(rt, auto_id, "ok" if not notes else "partial", summary, counts,
4327
+ True, affected=list(merged)[:200])
4328
+ trigger_fire(rt, tenant, auto_id, log=log)
4329
+ return entry
4330
+
4331
+
4332
+ def compose_sentence(defn):
4333
+ """The one-sentence server-composed summary (airtable-brief rec 7): rendered from the
4334
+ definition so it cannot lie about what runs."""
4335
+ cfg = defn.get("config") or {}
4336
+ trg = defn.get("trigger") or {}
4337
+ sched = defn.get("schedule") or {}
4338
+ kind = defn.get("kind")
4339
+ if trg.get("key") == "event_field":
4340
+ head = f"When {trg.get('field')} changes on {trg.get('table')}"
4341
+ elif trg.get("key") == "record_created":
4342
+ head = f"When a record is created in {trg.get('table')}"
4343
+ elif trg.get("key") == "webhook":
4344
+ head = "When the webhook is called"
4345
+ elif trg.get("key") == "email":
4346
+ head = f"When an email matches {trg.get('query')}"
4347
+ elif sched.get("enabled"):
4348
+ head = f"{_cron_label(sched.get('cron'))}"
4349
+ else:
4350
+ head = "When you press Run now"
4351
+ if kind == "scrape_db":
4352
+ host = urlparse(str(cfg.get("url") or "")).hostname or "the page"
4353
+ body = f"read {host} and upsert rows into {cfg.get('targetTable') or 'a new database'}"
4354
+ elif kind == "field_instagram":
4355
+ body = (f"capture Instagram profiles for {cfg.get('targetTable') or 'the database'}"
4356
+ + (", exact counts first" if clean_tier(cfg.get("tier")) == "brightdata"
4357
+ else ", anonymous only"))
4358
+ else:
4359
+ body = (f"search Instagram for up to {cfg.get('recordsLimit') or 0} profiles into "
4360
+ f"{cfg.get('targetTable') or DISCOVER_TABLE}")
4361
+ lanes = cfg.get("lanes") or []
4362
+ tail = f", then route each record across {len(lanes)} lanes" if lanes else ""
4363
+ return f"{head}, {body}{tail}."
4364
+
4365
+
4366
  def run_now(rt, tenant, auto_id, username="automation", log=print):
4367
  """Execute one automation SYNCHRONOUSLY. The route wraps this in a thread; the tick calls it
4368
  directly. Returns the run entry, or None when it was already running (the 409)."""
 
4419
 
4420
 
4421
  def tick(rt, tenant, now=None, log=print):
4422
+ """Fire every due automation for ONE tenant + poll every email trigger (C3). Returns the
4423
+ ids started. The email polls are bounded and fail-quiet per automation β€” one broken
4424
+ mailbox connection must not stop the tenant's schedules."""
4425
  started = []
4426
  for aid in due_ids(rt, now):
4427
  if run_async(rt, tenant, aid, username="scheduler", log=log):
4428
  started.append(aid)
4429
+ for aid, d in all_definitions(rt).items():
4430
+ if (d.get("trigger") or {}).get("key") == "email":
4431
+ try:
4432
+ if email_poll(rt, tenant, aid, d, log=log) is not None:
4433
+ started.append(aid)
4434
+ except Exception as e: # noqa: BLE001
4435
+ log(f"[aios-auto] email poll {tenant}/{aid} failed: {type(e).__name__}: {e}")
4436
+ # C7's amendment: date-window metrics advance with the tick, so `today` is never staler
4437
+ # than one tick while a scheduler exists. A tenant without metric fields pays a dict scan.
4438
+ try:
4439
+ refresh_metrics(rt, log=log)
4440
+ except Exception as e: # noqa: BLE001
4441
+ log(f"[aios-auto] metric refresh {tenant} failed: {type(e).__name__}: {e}")
4442
  if started:
4443
  log(f"[aios-auto] tick {tenant}: started {', '.join(started)}")
4444
  return started
api/ig_master.py ADDED
@@ -0,0 +1,169 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """ig_master.py β€” the PLATFORM-WIDE Instagram master store (wave 22, contract C6 / ruling R2).
2
+
3
+ WHY A MASTER AT ALL. History is unbuyable: no vendor sells "followers on 1 January", so the
4
+ series starts the day capture starts β€” and a profile two tenants both track was, until this
5
+ wave, two separate paid pulls writing two private copies. R2 pools the SNAPSHOT HISTORY on the
6
+ operator plane: every pull WRITE-THROUGHS here as well as to the tenant's own `ut_ig_*` tables,
7
+ and the time-window metric fields (C7) read THIS series β€” so a handle any tenant tracks has one
8
+ continuous history, and nobody re-bills for what the platform already knows.
9
+
10
+ RESIDENCY (C6 + amendment): its OWN private dataset repo β€” `royal-imports/aios-ig-master`, env
11
+ `AIOS_IG_MASTER_REPO` β€” reached through the `core/store.py::handle()` seam so R9's Postgres
12
+ flip carries it unchanged. β›” NEVER the tenant `user_tables` bucket: that bucket serialises
13
+ whole (MEASURED 35.8 MB at the append-table ceiling), so parking a platform-wide series inside
14
+ any tenant's bucket would tax every unrelated write in that tenant. Three buckets of its own:
15
+
16
+ master_snapshots append key `<handle>@<pulled_at>` profile counts over time
17
+ master_posts upsert key `<shortcode>` post identity (handle, when)
18
+ master_post_snapshots append key `<shortcode>@<pulled_at>` engagement over time
19
+
20
+ TENANT ATTRIBUTION IS FOR AUDIT/ERASURE ONLY (C6, verbatim): every row carries the tenant slug
21
+ that paid for the pull, and NOTHING reads it to answer a data question β€” the pooling benefit
22
+ is exactly that reads are attribution-blind. D-24's subject purge walks these buckets too
23
+ (`purge_handle`), because a right-to-erasure that missed the pooled copy would not be erasure.
24
+
25
+ FAILURE POSTURE: three states, never conflated. `off` = no repo configured on this deployment
26
+ (local dev, the gates) β€” the tenant copy is the whole story and the run says so WITHOUT going
27
+ partial; `ok` = written; `error` = configured and the write failed β€” a LOUD partial in the run
28
+ summary, never a silent skip (C6, verbatim).
29
+ """
30
+ from __future__ import annotations
31
+
32
+ import os
33
+
34
+ ENV_REPO = "AIOS_IG_MASTER_REPO"
35
+ SNAP_BUCKET = "master_snapshots"
36
+ POST_BUCKET = "master_posts"
37
+ PSNAP_BUCKET = "master_post_snapshots"
38
+ #: One bucket's row ceiling. The append tables grow forever by design; the cap exists so a
39
+ #: runaway writer is a LOUD partial long before a bucket becomes unserialisable. At ~1k
40
+ #: profiles/day this is ~16 months of profile snapshots β€” re-derive before raising.
41
+ MASTER_MAX_ROWS = 500_000
42
+
43
+
44
+ def repo_id():
45
+ return (os.environ.get(ENV_REPO) or "").strip()
46
+
47
+
48
+ def configured():
49
+ return bool(repo_id())
50
+
51
+
52
+ def _handle():
53
+ """The store handle β€” THE seam (C6): `core.store.handle` picks the backend, so the pg flip
54
+ (R9) moves this store the day it moves every other one. Monkeypatched by the gate."""
55
+ import core.store as store
56
+ return store.handle(repo_id=repo_id(), slug="ig_master")
57
+
58
+
59
+ def _upsert():
60
+ # Lazy: the engine imports this module, so a top-level engine import would be a cycle.
61
+ import automation_engine as engine
62
+ return engine.upsert_rows
63
+
64
+
65
+ def append_run(tenant, snaps, posts, psnaps):
66
+ """Write-through one run's accumulated rows. Returns `(status, note)`,
67
+ status ∈ ok | off | error β€” see the module header for what each obliges the caller to say.
68
+
69
+ One coalesced update PER BUCKET per run (the 256-commits/hr law travels β€” this repo has its
70
+ own budget, and a per-row writer would spend it the same way). Empty inputs cost nothing.
71
+ """
72
+ if not configured():
73
+ return "off", "no master store on this deployment β€” tenant copy only"
74
+ slug = str(tenant or "").strip() or "unknown"
75
+ stamped = {
76
+ SNAP_BUCKET: ([{**r, "tenant": slug} for r in snaps or []], "snapshot_key"),
77
+ POST_BUCKET: ([{**r, "tenant": slug} for r in posts or []], "shortcode"),
78
+ PSNAP_BUCKET: ([{**r, "tenant": slug} for r in psnaps or []], "post_snapshot_key"),
79
+ }
80
+ upsert = _upsert()
81
+ capped = []
82
+ try:
83
+ h = _handle()
84
+ for bucket, (rows_in, key_field) in stamped.items():
85
+ if not rows_in:
86
+ continue
87
+ existing = dict(h.get(bucket) or {})
88
+ merged, counts = upsert(existing, rows_in, key_field, cap=MASTER_MAX_ROWS)
89
+ if counts.get("capped"):
90
+ capped.append(f"{bucket} is FULL ({MASTER_MAX_ROWS:,}) β€” "
91
+ f"{counts['capped']} rows lost")
92
+ h.update(bucket, lambda cur, m=merged: m, flush="sync")
93
+ except Exception as e: # noqa: BLE001
94
+ return "error", f"the master store did not take the write ({type(e).__name__})"
95
+ if capped:
96
+ return "error", "; ".join(capped)
97
+ return "ok", ""
98
+
99
+
100
+ def series_for(handles):
101
+ """The C7 read seam: `{handle: {snapshots: [...], posts: [...], postSnapshots:
102
+ {shortcode: [...]}}}` for the handles asked about, each series sorted ascending by its
103
+ time key. Attribution-blind by design (the pooling benefit). `{}` when unconfigured β€”
104
+ a metric over no master reads BLANK, never zero."""
105
+ if not configured():
106
+ return {}
107
+ want = {str(x or "").strip().lower() for x in handles or [] if str(x or "").strip()}
108
+ if not want:
109
+ return {}
110
+ try:
111
+ h = _handle()
112
+ snaps = h.get(SNAP_BUCKET) or {}
113
+ posts = h.get(POST_BUCKET) or {}
114
+ psnaps = h.get(PSNAP_BUCKET) or {}
115
+ except Exception: # noqa: BLE001
116
+ return {}
117
+ out = {w: {"snapshots": [], "posts": [], "postSnapshots": {}} for w in want}
118
+ code_owner = {}
119
+ for r in posts.values():
120
+ hkey = str((r or {}).get("influencer_key") or "").strip().lower()
121
+ if hkey in out:
122
+ out[hkey]["posts"].append(dict(r))
123
+ code_owner[str(r.get("shortcode") or "")] = hkey
124
+ for r in snaps.values():
125
+ hkey = str((r or {}).get("influencer_key") or "").strip().lower()
126
+ if hkey in out:
127
+ out[hkey]["snapshots"].append(dict(r))
128
+ for r in psnaps.values():
129
+ code = str((r or {}).get("shortcode") or "")
130
+ hkey = code_owner.get(code)
131
+ if hkey:
132
+ out[hkey]["postSnapshots"].setdefault(code, []).append(dict(r))
133
+ for w in out.values():
134
+ w["snapshots"].sort(key=lambda r: str(r.get("pulled_at") or ""))
135
+ w["posts"].sort(key=lambda r: str(r.get("posted_at") or ""))
136
+ for series in w["postSnapshots"].values():
137
+ series.sort(key=lambda r: str(r.get("pulled_at") or ""))
138
+ return out
139
+
140
+
141
+ def purge_handle(handle):
142
+ """D-24's master half: remove EVERY row about one subject from all three buckets.
143
+ Returns `{bucket: removed}`; `{}` when unconfigured (nothing exists to purge). The tenant
144
+ half lives in the engine (`purge_subject`) β€” the two run together, and the gate proves a
145
+ purged handle leaves no row on either side."""
146
+ if not configured():
147
+ return {}
148
+ subject = str(handle or "").strip().lower()
149
+ if not subject:
150
+ return {}
151
+ h = _handle()
152
+ removed = {}
153
+ posts = h.get(POST_BUCKET) or {}
154
+ codes = {str(r.get("shortcode") or "") for r in posts.values()
155
+ if str((r or {}).get("influencer_key") or "").strip().lower() == subject}
156
+
157
+ def _sweep(bucket, keep):
158
+ cur = h.get(bucket) or {}
159
+ nxt = {k: v for k, v in cur.items() if keep(v)}
160
+ removed[bucket] = len(cur) - len(nxt)
161
+ if removed[bucket]:
162
+ h.update(bucket, lambda c, m=nxt: m, flush="sync")
163
+
164
+ _sweep(SNAP_BUCKET,
165
+ lambda r: str((r or {}).get("influencer_key") or "").strip().lower() != subject)
166
+ _sweep(POST_BUCKET,
167
+ lambda r: str((r or {}).get("influencer_key") or "").strip().lower() != subject)
168
+ _sweep(PSNAP_BUCKET, lambda r: str((r or {}).get("shortcode") or "") not in codes)
169
+ return removed
api/oauth_connect.py ADDED
@@ -0,0 +1,382 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """oauth_connect.py β€” the generic OAuth CONNECTOR framework (wave 22, contract C5 + A2 / R12).
2
+
3
+ WHAT THIS IS, and what it is deliberately not. This connects a data scope to a PERSON β€”
4
+ "read *my* Gmail" β€” which is a different animal from `core/auth_google.py` (LOGIN β€” proving who
5
+ you are). The two share one Google Cloud app (one client id, per R12) and nothing else: login
6
+ stays the untouched template it has been since wave 7, and this module never mints a session.
7
+
8
+ ⭐ REGISTRY-DRIVEN (C5 amendment A2 β€” the SOURCES-registry law applied to auth). A provider is
9
+ declared ONCE in `PROVIDERS` β€” endpoints, scopes, env names, the authorize extras β€” and the
10
+ generic flow below reads the declaration. Google is the only entry THIS wave; Slack/Airtable/
11
+ Outlook/QuickBooks later are one entry + secrets each, zero new code paths. β›” Nango is the
12
+ STUDY reference for this shape and is Elastic-licensed: no line of `providers.yaml` is copied β€”
13
+ every entry here sources from the provider's own public documentation.
14
+
15
+ THE FOUR RULES, each load-bearing:
16
+
17
+ 1. **PER-USER SLOTS (R7, the QM seam).** A refresh token is identity, not infrastructure β€”
18
+ it lands in `core.keychain`'s `user_secrets` sub-bucket keyed by USERNAME under the slot
19
+ `oauth_<provider>`, Fernet at rest, invisible to the admin keychain table. An automation
20
+ polls through its CREATOR's slot, nobody else's.
21
+ 2. **FAIL-CLOSED, never an error page.** No client id β‡’ the provider is not `configured` β‡’
22
+ the email trigger reads `ready: false` and the connect door answers a sentence β€” the flow
23
+ is simply not offered. Same in every failure direction: an expired/revoked refresh token
24
+ becomes a LOUD `reconnect: true` on the status (Google's Testing-mode refresh tokens die
25
+ every ~7 days β€” silence here would read as a trigger that just stopped).
26
+ 3. **PKCE + state, single-use, short-lived, user-bound.** The authorize URL carries
27
+ S256(code_verifier) and an unguessable `state`; the callback consumes the state exactly
28
+ once, checks it was minted for THIS user, and refuses anything older than ten minutes.
29
+ The state also carries the RETURN PATH (A3: the user lands back where they left, never at
30
+ the root) β€” relative paths only, so the callback can never be walked off-origin.
31
+ 4. **Tokens travel in headers/bodies to the provider's REGISTERED endpoints only** β€” never a
32
+ URL derived from input β€” and nothing here logs one: errors quote a STATUS and a sentence,
33
+ the `bd_call` discipline.
34
+ """
35
+ from __future__ import annotations
36
+
37
+ import base64
38
+ import datetime as _dt
39
+ import hashlib
40
+ import json
41
+ import os
42
+ import re
43
+ import secrets
44
+ import threading
45
+ import time
46
+ from urllib.parse import urlencode
47
+
48
+ import requests
49
+
50
+ #: ⭐ THE PROVIDER REGISTRY (C5-A2). Everything the generic flow needs to speak one provider,
51
+ #: declared as data. `authorize_extra` is the per-provider consent dialect β€” Google's
52
+ #: `access_type=offline&prompt=consent` is what makes a REFRESH token arrive on every connect;
53
+ #: without it a re-connect answers access-only and the poll dies within the hour, which reads
54
+ #: exactly like a broken trigger.
55
+ PROVIDERS = {
56
+ "google": {
57
+ "label": "Google",
58
+ "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth",
59
+ "token_url": "https://oauth2.googleapis.com/token",
60
+ "userinfo_url": "https://openidconnect.googleapis.com/v1/userinfo",
61
+ "scopes": "openid email https://www.googleapis.com/auth/gmail.readonly",
62
+ "authorize_extra": {"access_type": "offline", "prompt": "consent"},
63
+ "env_id": "GOOGLE_OAUTH_CLIENT_ID",
64
+ "env_secret": "GOOGLE_OAUTH_CLIENT_SECRET",
65
+ },
66
+ }
67
+
68
+ GMAIL_BASE = "https://gmail.googleapis.com/gmail/v1/users/me"
69
+ STATE_TTL_SECONDS = 600
70
+ HTTP_TIMEOUT = 12.0
71
+
72
+
73
+ def _kc():
74
+ import core.keychain as keychain
75
+ return keychain
76
+
77
+
78
+ def provider_def(provider):
79
+ return PROVIDERS.get(str(provider or "").strip().lower())
80
+
81
+
82
+ def slot_name(provider):
83
+ return f"oauth_{str(provider or '').strip().lower()}"
84
+
85
+
86
+ def client(provider):
87
+ """`(client_id, client_secret)` from the env names the registry declares."""
88
+ p = provider_def(provider) or {}
89
+ return ((os.environ.get(p.get("env_id", "")) or "").strip(),
90
+ (os.environ.get(p.get("env_secret", "")) or "").strip())
91
+
92
+
93
+ def configured(provider="google"):
94
+ cid, secret = client(provider)
95
+ return bool(cid and secret)
96
+
97
+
98
+ def safe_next(raw):
99
+ """A RETURN PATH the callback may redirect to: same-origin RELATIVE only. Anything absolute,
100
+ protocol-relative or unparseable degrades to the shell root β€” a redirect target that
101
+ arrived in a query string is exactly the thing an open-redirect rides in on."""
102
+ nxt = str(raw or "").strip()
103
+ if not nxt or not nxt.startswith(("/", "#")) or nxt.startswith("//") or "\\" in nxt \
104
+ or ":" in nxt.split("?", 1)[0].split("#", 1)[0]:
105
+ return "/#/"
106
+ return nxt[:300]
107
+
108
+
109
+ # ---------------------------------------------------------------------------------------------
110
+ # PKCE + state
111
+ # ---------------------------------------------------------------------------------------------
112
+
113
+ _STATE_LOCK = threading.Lock()
114
+ _STATES = {} # state -> {"provider", "verifier", "uname", "redirect", "next", "ts"}
115
+
116
+
117
+ def _prune_states(now=None):
118
+ now = now if now is not None else time.time()
119
+ with _STATE_LOCK:
120
+ for k in [k for k, v in _STATES.items() if now - v.get("ts", 0) > STATE_TTL_SECONDS]:
121
+ _STATES.pop(k, None)
122
+
123
+
124
+ def _challenge(verifier):
125
+ """S256: BASE64URL(SHA256(verifier)), no padding β€” RFC 7636's one worthwhile method."""
126
+ digest = hashlib.sha256(verifier.encode("ascii")).digest()
127
+ return base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
128
+
129
+
130
+ def start(provider, uname, redirect_uri, next_path=""):
131
+ """Mint state+verifier for THIS user and return the provider's consent URL.
132
+
133
+ Returns `(url, error)` β€” an unknown or unconfigured provider is a sentence, never an
134
+ exception (rule 2)."""
135
+ p = provider_def(provider)
136
+ if p is None:
137
+ return "", f"{provider!r} is not a connectable provider"
138
+ if not configured(provider):
139
+ return "", (f"{p['label']} OAuth is not configured on this deployment β€” the owner adds "
140
+ f"{p['env_id']} / {p['env_secret']} first")
141
+ _prune_states()
142
+ cid, _secret = client(provider)
143
+ state = secrets.token_urlsafe(24)
144
+ verifier = secrets.token_urlsafe(64) # 86 chars β€” inside RFC 7636's 43..128
145
+ with _STATE_LOCK:
146
+ _STATES[state] = {"provider": str(provider), "verifier": verifier,
147
+ "uname": str(uname or ""), "redirect": str(redirect_uri or ""),
148
+ "next": safe_next(next_path), "ts": time.time()}
149
+ q = {
150
+ "client_id": cid,
151
+ "redirect_uri": redirect_uri,
152
+ "response_type": "code",
153
+ "scope": p["scopes"],
154
+ "state": state,
155
+ "code_challenge": _challenge(verifier),
156
+ "code_challenge_method": "S256",
157
+ }
158
+ q.update(p.get("authorize_extra") or {})
159
+ return f"{p['authorize_url']}?{urlencode(q)}", ""
160
+
161
+
162
+ def _post_token(url, body):
163
+ """One POST to a REGISTERED token endpoint. `(payload, error_sentence)` β€” never raises,
164
+ never echoes a secret; a non-200 quotes the status and the provider's `error` field only."""
165
+ try:
166
+ r = requests.post(url, data=body, timeout=HTTP_TIMEOUT,
167
+ headers={"Accept": "application/json"})
168
+ except Exception as e: # noqa: BLE001
169
+ return None, f"the token endpoint did not answer ({type(e).__name__})"
170
+ try:
171
+ payload = r.json() if r.content else {}
172
+ except Exception: # noqa: BLE001
173
+ payload = {}
174
+ if r.status_code != 200:
175
+ why = str((payload or {}).get("error") or r.status_code)
176
+ return None, f"the token exchange was refused ({why})"
177
+ return payload or {}, ""
178
+
179
+
180
+ def _userinfo_email(provider, access_token):
181
+ p = provider_def(provider) or {}
182
+ url = p.get("userinfo_url")
183
+ if not url:
184
+ return ""
185
+ try:
186
+ r = requests.get(url, timeout=HTTP_TIMEOUT,
187
+ headers={"Authorization": f"Bearer {access_token}"})
188
+ if r.status_code == 200:
189
+ return str((r.json() or {}).get("email") or "")
190
+ except Exception: # noqa: BLE001
191
+ pass
192
+ return ""
193
+
194
+
195
+ def callback(rt, uname, state, code):
196
+ """The exchange half: verify the state belongs to THIS user, trade the code for tokens,
197
+ store `{access, refresh, expiry, email}` in the user's per-provider slot. Returns
198
+ `(email, next_path, error)` β€” `next_path` is where the browser goes home to (A3)."""
199
+ _prune_states()
200
+ with _STATE_LOCK:
201
+ entry = _STATES.pop(str(state or ""), None) # single-use, whatever happens next
202
+ home = safe_next((entry or {}).get("next"))
203
+ if not entry:
204
+ return "", home, "that connect attempt is unknown or expired β€” start again"
205
+ if entry.get("uname") != str(uname or ""):
206
+ # A state minted for one session consumed by another is exactly the CSRF the state
207
+ # exists to refuse. Fail closed; the honest user just clicks Connect again.
208
+ return "", home, "that connect attempt belongs to a different session β€” start again"
209
+ provider = entry.get("provider") or "google"
210
+ p = provider_def(provider)
211
+ if p is None or not configured(provider):
212
+ return "", home, f"{provider!r} is not connectable on this deployment"
213
+ cid, secret = client(provider)
214
+ payload, err = _post_token(p["token_url"], {
215
+ "client_id": cid, "client_secret": secret,
216
+ "grant_type": "authorization_code", "code": str(code or ""),
217
+ "redirect_uri": entry.get("redirect") or "",
218
+ "code_verifier": entry.get("verifier") or "",
219
+ })
220
+ if err:
221
+ return "", home, err
222
+ access = str(payload.get("access_token") or "")
223
+ refresh = str(payload.get("refresh_token") or "")
224
+ if not access:
225
+ return "", home, "the provider answered without an access token β€” nothing was stored"
226
+ if not refresh:
227
+ # Google answers access-only when consent was silently reused β€” an access-only slot
228
+ # dies within the hour, silently, so it is refused with the way out named.
229
+ return "", home, ("no refresh token came back β€” disconnect the app on the provider's "
230
+ "permissions page and connect again")
231
+ expiry = time.time() + float(payload.get("expires_in") or 3600) - 60
232
+ email = _userinfo_email(provider, access)
233
+ _kc().put_user_secret(rt, uname, slot_name(provider), {
234
+ "access": access, "refresh": refresh,
235
+ "expiry": f"{expiry:.0f}", "email": email,
236
+ })
237
+ return email, home, ""
238
+
239
+
240
+ def _refresh(rt, uname, provider, slot):
241
+ """Trade the refresh token for a fresh access token and re-store. `(slot|None, error)`.
242
+
243
+ A refused refresh marks the slot `reconnect` LOUDLY rather than deleting it β€” the status
244
+ endpoint then says "reconnect" instead of "not connected", which are different instructions
245
+ to a person (the Testing-mode 7-day expiry makes this path ROUTINE, not rare)."""
246
+ p = provider_def(provider) or {}
247
+ cid, secret = client(provider)
248
+ payload, err = _post_token(p.get("token_url", ""), {
249
+ "client_id": cid, "client_secret": secret,
250
+ "grant_type": "refresh_token", "refresh_token": str(slot.get("refresh") or ""),
251
+ })
252
+ if err:
253
+ marked = dict(slot)
254
+ marked["reconnect"] = "1"
255
+ try:
256
+ _kc().put_user_secret(rt, uname, slot_name(provider), marked)
257
+ except Exception: # noqa: BLE001
258
+ pass
259
+ return None, err
260
+ fresh = dict(slot)
261
+ fresh["access"] = str(payload.get("access_token") or slot.get("access") or "")
262
+ fresh["expiry"] = f"{time.time() + float(payload.get('expires_in') or 3600) - 60:.0f}"
263
+ fresh.pop("reconnect", None)
264
+ _kc().put_user_secret(rt, uname, slot_name(provider), fresh)
265
+ return fresh, ""
266
+
267
+
268
+ def creds(rt, uname, provider="google"):
269
+ """THE seam a poller reads through: a live access token for this user, refreshed
270
+ transparently on expiry. Returns `(access_token, error_sentence)` β€” `("", why)` covers
271
+ not-connected, locked keychain and reconnect-needed alike, each with its own sentence."""
272
+ kc = _kc()
273
+ p = provider_def(provider) or {"label": str(provider)}
274
+ try:
275
+ slot = kc.read_user_secret(rt, uname, slot_name(provider))
276
+ except kc.KeychainLocked as e:
277
+ return "", f"the keychain is locked ({e}) β€” no token can be read"
278
+ if not slot:
279
+ return "", (f"no {p['label']} connection for this user β€” connect it in Settings")
280
+ if slot.get("reconnect"):
281
+ return "", f"the {p['label']} connection expired β€” reconnect it in Settings"
282
+ try:
283
+ expiry = float(slot.get("expiry") or 0)
284
+ except (TypeError, ValueError):
285
+ expiry = 0.0
286
+ if time.time() >= expiry:
287
+ slot, err = _refresh(rt, uname, provider, slot)
288
+ if err:
289
+ return "", f"the {p['label']} connection could not refresh β€” {err}"
290
+ return str(slot.get("access") or ""), ""
291
+
292
+
293
+ def google_creds(rt, uname):
294
+ """The email trigger's named seam (contract C5's original spelling) β€” `creds` on the one
295
+ provider this wave ships."""
296
+ return creds(rt, uname, "google")
297
+
298
+
299
+ def status(rt, uname):
300
+ """C5's status shape, registry-driven: `{<provider>: {connected, email, reconnect,
301
+ configured}}` for the session user β€” one entry per registry row, so today it reads exactly
302
+ `{google: {...}}`. Never raises β€” a locked keychain reads as not-connected WITH the note."""
303
+ kc = _kc()
304
+ out = {}
305
+ for slug in PROVIDERS:
306
+ row = {"connected": False, "email": "", "reconnect": False,
307
+ "configured": configured(slug)}
308
+ try:
309
+ slot = kc.read_user_secret(rt, uname, slot_name(slug))
310
+ except kc.KeychainLocked as e:
311
+ row["note"] = str(e)
312
+ out[slug] = row
313
+ continue
314
+ if slot:
315
+ row["connected"] = True
316
+ row["email"] = str(slot.get("email") or "")
317
+ row["reconnect"] = bool(slot.get("reconnect"))
318
+ out[slug] = row
319
+ return out
320
+
321
+
322
+ def disconnect(rt, uname, provider="google"):
323
+ _kc().drop_user_secret(rt, uname, slot_name(provider))
324
+ return True
325
+
326
+
327
+ # ---------------------------------------------------------------------------------------------
328
+ # GMAIL READS β€” the one data surface this wave (the email trigger's substrate)
329
+ # ---------------------------------------------------------------------------------------------
330
+
331
+ def gmail_list(access_token, query, max_results=25):
332
+ """Message ids matching `query`, newest first. `(ids, error)` β€” bounded, timeboxed, and a
333
+ non-200 is a sentence (the poll runs on the tick thread; it may be slow ONCE, never hung)."""
334
+ q = urlencode({"q": str(query or "").strip() or "in:inbox", "maxResults": int(max_results)})
335
+ try:
336
+ r = requests.get(f"{GMAIL_BASE}/messages?{q}", timeout=HTTP_TIMEOUT,
337
+ headers={"Authorization": f"Bearer {access_token}"})
338
+ except Exception as e: # noqa: BLE001
339
+ return [], f"Gmail did not answer ({type(e).__name__})"
340
+ if r.status_code != 200:
341
+ return [], f"Gmail answered {r.status_code}"
342
+ try:
343
+ msgs = (r.json() or {}).get("messages") or []
344
+ except Exception: # noqa: BLE001
345
+ return [], "Gmail answered with something that is not JSON"
346
+ return [str(m.get("id")) for m in msgs if isinstance(m, dict) and m.get("id")], ""
347
+
348
+
349
+ def gmail_message(access_token, message_id):
350
+ """One message's headers + snippet β†’ our row shape. `(row|None, error)`."""
351
+ try:
352
+ r = requests.get(
353
+ f"{GMAIL_BASE}/messages/{message_id}"
354
+ f"?format=metadata&metadataHeaders=From&metadataHeaders=Subject"
355
+ f"&metadataHeaders=Date",
356
+ timeout=HTTP_TIMEOUT,
357
+ headers={"Authorization": f"Bearer {access_token}"})
358
+ except Exception as e: # noqa: BLE001
359
+ return None, f"Gmail did not answer ({type(e).__name__})"
360
+ if r.status_code != 200:
361
+ return None, f"Gmail answered {r.status_code}"
362
+ try:
363
+ payload = r.json() or {}
364
+ except Exception: # noqa: BLE001
365
+ return None, "Gmail answered with something that is not JSON"
366
+ headers = {str(h.get("name") or "").lower(): str(h.get("value") or "")
367
+ for h in ((payload.get("payload") or {}).get("headers") or [])
368
+ if isinstance(h, dict)}
369
+ stamp = _dt.datetime.now().astimezone().isoformat(timespec="seconds")
370
+ return {
371
+ "email_id": str(payload.get("id") or message_id),
372
+ "email_from": headers.get("from", "")[:200],
373
+ "email_subject": headers.get("subject", "")[:300],
374
+ "email_date": headers.get("date", "")[:80],
375
+ "email_snippet": str(payload.get("snippet") or "")[:500],
376
+ "email_seen_at": stamp,
377
+ }, ""
378
+
379
+
380
+ #: `re` is imported for the slot-name law in core.keychain (see USER_SECRET_PROVIDERS there);
381
+ #: keeping the reference here so a linter cannot 'clean up' what the registry contract uses.
382
+ _SLOT_SHAPE = re.compile(r"^oauth_[a-z0-9_]{1,24}$")
api/routes_automation.py CHANGED
@@ -17,10 +17,16 @@ import time
17
  from fastapi import APIRouter, Body, Depends, Header, Request
18
 
19
  import automation_engine as engine
 
 
20
  from deps import Session, err, module_gate, require_session
21
 
22
  router = APIRouter(prefix="/api/v1")
23
 
 
 
 
 
24
  #: The registry key this surface carries (C-AUTONAV β€” A adds the row; the gate is live now, so
25
  #: the day the row lands the wall is already the one that was tested).
26
  MODULE = "automation"
@@ -42,9 +48,20 @@ def _wire(defn, tenant):
42
  "id": defn.get("id"), "name": defn.get("name"), "kind": defn.get("kind"),
43
  "config": defn.get("config") or {}, "schedule": sched, "status": status,
44
  "runs": list(defn.get("runs") or [])[:engine.MAX_RUNS],
 
 
 
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.
@@ -52,6 +69,38 @@ def _wire(defn, tenant):
52
  }
53
 
54
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
55
  def _tick_state():
56
  """⭐ WAVE 21 (C6 amendment A1) β€” can a SCHEDULE fire on this deployment?
57
 
@@ -99,8 +148,25 @@ def list_automations(session: Session = Depends(_GATE)):
99
  "operators": list(engine.BD_FILTER_OPS),
100
  "nullaryOperators": list(engine.BD_NULLARY_OPS),
101
  "maxRecords": engine.BD_MAX_RECORDS,
 
 
 
 
 
 
 
102
  "table": engine.DISCOVER_TABLE},
103
  "storeAvailable": bool(session.runtime.available()),
 
 
 
 
 
 
 
 
 
 
104
  # Wave 21 C6-A1: {"enabled": bool, "source": "in-process"|"external"|""} β€” see
105
  # `_tick_state` for why one boolean off AIOS_AUTOMATIONS alone would lie.
106
  "tick": _tick_state()}
@@ -119,6 +185,11 @@ def discover_estimate(body: dict = Body(default=None), session: Session = Depend
119
  return engine.discover_estimate((body or {}).get("recordsLimit"))
120
 
121
 
 
 
 
 
 
122
  @router.get("/automations/tables")
123
  def automation_tables(session: Session = Depends(_GATE)):
124
  """The blank databases an automation can target, with their fields.
@@ -137,6 +208,17 @@ def automation_tables(session: Session = Depends(_GATE)):
137
  """
138
  import core.user_tables as user_tables
139
 
 
 
 
 
 
 
 
 
 
 
 
140
  out = []
141
  for key, t in sorted(engine.ut_all(session.runtime).items(),
142
  key=lambda kv: (kv[1].get("label") or "").lower()):
@@ -211,6 +293,38 @@ def preview_source(body: dict = Body(default=None), session: Session = Depends(_
211
  f"{str(e)[:160]}")
212
 
213
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
214
  @router.post("/automations/{auto_id}/run")
215
  def run_automation(auto_id: str, session: Session = Depends(_GATE)):
216
  """Start a run on a background thread. 409 when one is already in flight."""
@@ -242,6 +356,31 @@ def toggle_automation_node(auto_id: str, node_id: str, session: Session = Depend
242
  return {"automation": _wire(defn, session.tenant)}
243
 
244
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
245
  @router.post("/automations/tick")
246
  def tick(request: Request, x_aios_tick_token: str = Header(default="")):
247
  """Fire every due schedule, for every tenant. The durable-cron entry point (R5).
@@ -259,6 +398,58 @@ def tick(request: Request, x_aios_tick_token: str = Header(default="")):
259
  return {"started": started, "at": time.strftime("%Y-%m-%dT%H:%M:%S")}
260
 
261
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
262
  @router.get("/automations/{auto_id}/rows")
263
  def run_rows(auto_id: str, session: Session = Depends(_GATE)):
264
  """The rows the LAST run touched β€” the drill-down behind a run's counts.
@@ -297,3 +488,12 @@ def run_rows(auto_id: str, session: Session = Depends(_GATE)):
297
  # only ever fire from the external cron POSTing /automations/tick. Both paths work; neither is
298
  # implicit. Booked in the session-D mailbox.
299
  engine.start_scheduler()
 
 
 
 
 
 
 
 
 
 
17
  from fastapi import APIRouter, Body, Depends, Header, Request
18
 
19
  import automation_engine as engine
20
+ import oauth_connect
21
+ import routes_oauth
22
  from deps import Session, err, module_gate, require_session
23
 
24
  router = APIRouter(prefix="/api/v1")
25
 
26
+ # C5 (wave 22): the OAuth connector surface rides INSIDE this router β€” main.py belongs to no
27
+ # session this wave, and this router is already mounted there. `/api/v1` + `/oauth/...`.
28
+ router.include_router(routes_oauth.router)
29
+
30
  #: The registry key this surface carries (C-AUTONAV β€” A adds the row; the gate is live now, so
31
  #: the day the row lands the wall is already the one that was tested).
32
  MODULE = "automation"
 
48
  "id": defn.get("id"), "name": defn.get("name"), "kind": defn.get("kind"),
49
  "config": defn.get("config") or {}, "schedule": sched, "status": status,
50
  "runs": list(defn.get("runs") or [])[:engine.MAX_RUNS],
51
+ # C3-A2(5): the review-decision audit (who moved which card where, when) β€” newest
52
+ # first, bounded server-side; both doors (board move + kanban drag) write it.
53
+ "reviews": list(defn.get("reviews") or [])[:engine.MAX_REVIEWS],
54
  "created": defn.get("created"), "createdBy": defn.get("createdBy"),
55
  "nextRunAt": nxt.strftime("%Y-%m-%d %H:%M") if nxt else "",
56
  "running": bool(live),
57
+ # C3 (wave 22): the trigger config rides whole β€” the webhook token included, because
58
+ # the person configuring the external caller has to be shown the URL somewhere, and
59
+ # this payload is session-gated behind the same wall as everything else here.
60
+ "trigger": defn.get("trigger") or None,
61
+ "statusNote": defn.get("statusNote") or "",
62
+ # The one-sentence summary (airtable-brief rec 7), composed from the definition so it
63
+ # cannot describe steps the engine does not run.
64
+ "sentence": engine.compose_sentence(defn),
65
  # THE CANVAS TOPOLOGY (R5) rides with the automation rather than being rebuilt in the
66
  # client, for the same reason `cronPresets` does: the engine that RUNS the steps is the
67
  # only thing entitled to say what the steps are.
 
69
  }
70
 
71
 
72
+ def _triggers_vocab(session):
73
+ """C3's server-owned trigger list: `[{key, label, ready, needs}]`, keys EXACTLY
74
+ `engine.TRIGGER_KEYS`. `ready:false` + `needs` renders as a not-configured state β€” never a
75
+ dead control, never a client-side union."""
76
+ tick_on = _tick_state()["enabled"]
77
+ g = oauth_connect.status(session.runtime, session.uname).get("google") or {}
78
+ email_ready = bool(g.get("configured")) and bool(g.get("connected")) \
79
+ and not g.get("reconnect")
80
+ email_needs = "" if email_ready else (
81
+ "connect_gmail" if g.get("configured") else "configure_google")
82
+ per = {
83
+ "manual": (True, ""),
84
+ "schedule": (tick_on, "" if tick_on else "arm_tick"),
85
+ "event_field": (True, ""),
86
+ "record_created": (True, ""),
87
+ "webhook": (True, ""),
88
+ "email": (email_ready, email_needs),
89
+ }
90
+ out = []
91
+ for k in engine.TRIGGER_KEYS:
92
+ ready, needs = per[k]
93
+ row = {"key": k, "label": engine.TRIGGER_LABELS[k], "ready": ready, "needs": needs,
94
+ # A3(3): the connect affordance is SERVER-COMPOSED β€” the client never maps a
95
+ # `needs` token to a route, so B's CONNECT_PROVIDERS shim deletes itself.
96
+ "connect": None}
97
+ if not ready and needs == "connect_gmail":
98
+ row["connect"] = {"provider": "google",
99
+ "startUrl": "/api/v1/oauth/google/start"}
100
+ out.append(row)
101
+ return out
102
+
103
+
104
  def _tick_state():
105
  """⭐ WAVE 21 (C6 amendment A1) β€” can a SCHEDULE fire on this deployment?
106
 
 
148
  "operators": list(engine.BD_FILTER_OPS),
149
  "nullaryOperators": list(engine.BD_NULLARY_OPS),
150
  "maxRecords": engine.BD_MAX_RECORDS,
151
+ # Wave 22 C4 β€” ADDITIVE: per-field flags for the toggle rows (the 3
152
+ # PII fields stay structurally absent, R3) + the too-big guard's
153
+ # numbers, so the surface can say WHY a filter is refused before the
154
+ # server has to.
155
+ "filterMeta": engine.filter_meta(),
156
+ "guard": {"minNarrowing": engine.BD_MIN_NARROWING,
157
+ "maxRecords": engine.BD_MAX_RECORDS},
158
  "table": engine.DISCOVER_TABLE},
159
  "storeAvailable": bool(session.runtime.available()),
160
+ # Wave 22 C3 β€” the trigger vocabulary, session-scoped because email readiness is a
161
+ # per-USER fact (the poll runs through the creator's own Gmail connection).
162
+ "triggers": _triggers_vocab(session),
163
+ # Wave 22 C1/R5 β€” the BOARD vocabulary, server-owned like every other list here:
164
+ # the lane-condition operators the engine can actually answer, so the lane editor
165
+ # can never offer a comparison `lane_match` would refuse.
166
+ "board": {"laneOps": list(engine.LANE_OPS),
167
+ "nullaryLaneOps": list(engine.LANE_NULLARY_OPS),
168
+ "maxLanes": engine.MAX_LANES,
169
+ "cardCap": engine.BOARD_CARD_CAP},
170
  # Wave 21 C6-A1: {"enabled": bool, "source": "in-process"|"external"|""} β€” see
171
  # `_tick_state` for why one boolean off AIOS_AUTOMATIONS alone would lie.
172
  "tick": _tick_state()}
 
185
  return engine.discover_estimate((body or {}).get("recordsLimit"))
186
 
187
 
188
+ #: C8's migration ran, per tenant, this process. Once is the point: the sweep only writes when
189
+ #: an unbound bag exists, so after the first pass this is a read that finds nothing.
190
+ _C8_MIGRATED = set()
191
+
192
+
193
  @router.get("/automations/tables")
194
  def automation_tables(session: Session = Depends(_GATE)):
195
  """The blank databases an automation can target, with their fields.
 
208
  """
209
  import core.user_tables as user_tables
210
 
211
+ # C8 (wave 22): bind pre-law automation bags to the definitions that write them β€” once
212
+ # per tenant per process, and a no-op read after the first real pass. A write-on-read,
213
+ # stated out loud: this is the surface whose stale bags mislead (the column picker), so
214
+ # it is where the truth gets repaired.
215
+ if session.tenant not in _C8_MIGRATED and session.runtime.available():
216
+ _C8_MIGRATED.add(session.tenant)
217
+ try:
218
+ engine.bind_unbound_fields(session.runtime)
219
+ except Exception: # noqa: BLE001
220
+ pass
221
+
222
  out = []
223
  for key, t in sorted(engine.ut_all(session.runtime).items(),
224
  key=lambda kv: (kv[1].get("label") or "").lower()):
 
293
  f"{str(e)[:160]}")
294
 
295
 
296
+ @router.get("/automations/{auto_id}/board")
297
+ def automation_board(auto_id: str, session: Session = Depends(_GATE)):
298
+ """C1 (wave 22): the RECORDS-AS-CARDS board β€” stages + routes + every record's position.
299
+
300
+ Enumerated entirely by the engine (`engine.board`); this client renders ONLY what rides the
301
+ payload, so the board can never show a stage the runner does not have."""
302
+ defn = engine.all_definitions(session.runtime).get(str(auto_id))
303
+ if defn is None:
304
+ raise err(404, "unknown_automation", "no automation with that id")
305
+ return {"board": engine.board(session.runtime, defn, admin=session.admin)}
306
+
307
+
308
+ @router.post("/automations/{auto_id}/cards/{row_id}/move")
309
+ def move_automation_card(auto_id: str, row_id: str, body: dict = Body(default=None),
310
+ session: Session = Depends(_GATE)):
311
+ """C1's card move β€” `{to: <stageId>}`. The SERVER decides legality: a review-stage card
312
+ advances only to a member of its per-record `next` (any user this gate admits β€” the click
313
+ IS the human decision, R6); every other move is an admin repair. Answers the fresh board."""
314
+ if not session.runtime.available():
315
+ raise err(503, "store_unavailable", "the tenant store is unavailable β€” nothing was saved")
316
+ if engine.running(session.tenant, auto_id):
317
+ raise err(409, "automation_running",
318
+ "it is running β€” a move now would race the engine's own writes")
319
+ out, problem = engine.move_card(session.runtime, auto_id, row_id,
320
+ (body or {}).get("to"),
321
+ username=session.uname, admin=session.admin)
322
+ if problem:
323
+ status, code, sentence = problem
324
+ raise err(status, code, sentence)
325
+ return {"board": out}
326
+
327
+
328
  @router.post("/automations/{auto_id}/run")
329
  def run_automation(auto_id: str, session: Session = Depends(_GATE)):
330
  """Start a run on a background thread. 409 when one is already in flight."""
 
356
  return {"automation": _wire(defn, session.tenant)}
357
 
358
 
359
+ @router.post("/automations/{auto_id}/hook/{token}")
360
+ def automation_hook(auto_id: str, token: str):
361
+ """C3's webhook trigger β€” the tick-endpoint pattern one level down: unauthenticated BY
362
+ DESIGN (the external caller has no cookie), gated on a per-automation token minted when the
363
+ trigger was configured, constant-time compared. The tenant is FOUND by the (id, token)
364
+ pair β€” a wrong token answers 403 for every tenant, so the route confirms nothing about
365
+ which slugs exist."""
366
+ from harness import runtime as _rt
367
+
368
+ last = (404, {"error": "unknown_automation",
369
+ "message": "no automation with that id and token"})
370
+ for slug in _rt.known_tenants():
371
+ try:
372
+ rt = _rt.get_runtime(slug)
373
+ except Exception: # noqa: BLE001
374
+ continue
375
+ status, payload = engine.hook_fire(rt, slug, auto_id, token)
376
+ if status == 200:
377
+ return payload
378
+ if status != 404:
379
+ last = (status, payload)
380
+ raise err(last[0], str(last[1].get("error") or "refused"),
381
+ str(last[1].get("message") or "refused"))
382
+
383
+
384
  @router.post("/automations/tick")
385
  def tick(request: Request, x_aios_tick_token: str = Header(default="")):
386
  """Fire every due schedule, for every tenant. The durable-cron entry point (R5).
 
398
  return {"started": started, "at": time.strftime("%Y-%m-%dT%H:%M:%S")}
399
 
400
 
401
+ @router.post("/automations/ig/purge")
402
+ def purge_ig_subject(body: dict = Body(default=None), session: Session = Depends(_GATE)):
403
+ """D-24 (wave 22): the right-to-erasure door for ONE Instagram subject β€” walks the
404
+ tenant's four `ut_ig_*` tables AND the platform master (R2 pooled a copy there, so a purge
405
+ that skipped it would not be erasure). Admin-only: erasure is a compliance act, not a
406
+ grid gesture. Answers the per-table removal counts β€” the one aggregate whose drill is the
407
+ rows' ABSENCE."""
408
+ if not session.admin:
409
+ raise err(403, "admin_only", "erasing a subject is an admin action")
410
+ if not session.runtime.available():
411
+ raise err(503, "store_unavailable", "the tenant store is unavailable β€” nothing was "
412
+ "purged")
413
+ handle = str((body or {}).get("handle") or "").strip()
414
+ if not handle:
415
+ raise err(400, "no_handle", "name the Instagram handle to erase")
416
+ counts = engine.purge_subject(session.runtime, handle)
417
+ return {"handle": handle.lstrip("@").lower(), "removed": counts,
418
+ "total": sum(counts.values())}
419
+
420
+
421
+ @router.get("/automations/metrics/{table_key}/{field_key}/{row_id}/rows")
422
+ def metric_drill(table_key: str, field_key: str, row_id: str,
423
+ session: Session = Depends(_GATE)):
424
+ """C7's drill: the EXACT master snapshot rows behind one metric cell
425
+ ([[no-unverifiable-aggregates]]) β€” recomputed on ask with the same function that filled
426
+ the cell, so the drill can never disagree with the number by construction."""
427
+ import core.user_tables as user_tables
428
+
429
+ if not user_tables.may_open(table_key, session.uname, session.admin, st=session.runtime):
430
+ raise err(404, "unknown_table", "no such database")
431
+ t = engine.ut_get(session.runtime, table_key) or {}
432
+ fdef = next((f for f in (t.get("fields") or []) if f.get("key") == field_key), None)
433
+ if not fdef or not isinstance(fdef.get("metric"), dict):
434
+ raise err(404, "not_a_metric", "that column is not a metric field")
435
+ row = (t.get("rows") or {}).get(str(row_id))
436
+ if row is None:
437
+ raise err(404, "unknown_row", "that record is not in the database")
438
+ import ig_master
439
+ url_field = next((f.get("key") for f in (t.get("fields") or [])
440
+ if f.get("type") == "url"), "")
441
+ handle = engine._table_handle(row, url_field)
442
+ bag = fdef["metric"]
443
+ series = ig_master.series_for({handle}) if handle else {}
444
+ value, rows = engine.metric_value(series.get(handle), bag.get("measure"),
445
+ bag.get("window"), bag.get("agg") or "")
446
+ return {"table": table_key, "field": field_key, "rowId": str(row_id), "handle": handle,
447
+ "measure": bag.get("measure"), "window": bag.get("window"),
448
+ "value": value, "rows": rows[:200],
449
+ "note": "" if value is not None else
450
+ "no master data answers this window β€” the cell is honestly blank"}
451
+
452
+
453
  @router.get("/automations/{auto_id}/rows")
454
  def run_rows(auto_id: str, session: Session = Depends(_GATE)):
455
  """The rows the LAST run touched β€” the drill-down behind a run's counts.
 
488
  # only ever fire from the external cron POSTing /automations/tick. Both paths work; neither is
489
  # implicit. Booked in the session-D mailbox.
490
  engine.start_scheduler()
491
+
492
+ # C3 (wave 22): register the trigger listener onto the platform's row-event seam. THIS module
493
+ # is where the registration belongs β€” it is the one place that already imports both sides, so
494
+ # neither the engine nor platform/core grows a dependency on the other. Idempotent: a reimport
495
+ # must not double-fire every trigger.
496
+ import core.user_tables as _ut_hooks # noqa: E402
497
+
498
+ if engine.grid_hook not in _ut_hooks.ROW_HOOKS:
499
+ _ut_hooks.ROW_HOOKS.append(engine.grid_hook)
api/routes_oauth.py ADDED
@@ -0,0 +1,84 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """routes_oauth.py β€” the OAuth connector surface (wave 22, contract C5 + A2/A3 / R12).
2
+
3
+ Thin over `oauth_connect`, the way `routes_automation` is thin over the engine: sessions,
4
+ shapes and status codes here; every decision that could be wrong lives in the module a gate
5
+ can drive without a server. GENERIC over `{provider}` (C5-A2): the routes read the registry,
6
+ so the day a second provider lands here is the day nothing in this file changes.
7
+
8
+ MOUNTED FROM `routes_automation` (not `main.py`): this wave's ownership fence gives no session
9
+ `main.py`, and `routes_automation` is already included there β€” so this router rides inside it
10
+ (`/api/v1` + `/oauth/...`). Lifting the include into `main.py` later is a two-line change that
11
+ alters no path.
12
+
13
+ ⚠ THE TWO REDIRECT LAWS (A3): `/{provider}/start` answers **302 to the provider's consent
14
+ screen** β€” it is a top-level navigation the client reaches by `<a href>`, never JSON. The
15
+ callback 302s BACK to the return path the `state` carried (relative-only, sanitised by
16
+ `oauth_connect.safe_next`), so the user lands where they left β€” connected or not, whatever
17
+ went wrong rides in the query string; a dead-end error page where the app used to be reads as
18
+ "the product broke", not "the connect failed".
19
+ """
20
+ import os
21
+
22
+ from fastapi import APIRouter, Depends, Request
23
+ from fastapi.responses import RedirectResponse
24
+
25
+ import oauth_connect
26
+ from deps import Session, err, require_session
27
+
28
+ router = APIRouter(prefix="/oauth")
29
+
30
+
31
+ def _redirect_uri(request: Request, provider: str) -> str:
32
+ """The redirect URI this deployment registers at the provider β€” env-pinned when the
33
+ container sits behind a proxy that rewrites the scheme (the HF Space), else derived from
34
+ the request. MUST match a console-registered URI verbatim, so it is computed in exactly
35
+ one place."""
36
+ base = (os.environ.get("AIOS_PUBLIC_BASE") or "").strip().rstrip("/")
37
+ if not base:
38
+ base = f"{request.url.scheme}://{request.url.netloc}"
39
+ return f"{base}/api/v1/oauth/{provider}/callback"
40
+
41
+
42
+ @router.get("/status")
43
+ def oauth_status(session: Session = Depends(require_session)):
44
+ """C5's status shape for the SESSION user, one entry per registry provider:
45
+ `{google: {connected, email, reconnect, configured}}` today. The bit the email trigger's
46
+ `ready` reads through."""
47
+ return oauth_connect.status(session.runtime, session.uname)
48
+
49
+
50
+ @router.get("/{provider}/start")
51
+ def oauth_start(provider: str, request: Request, next: str = "",
52
+ session: Session = Depends(require_session)):
53
+ """302 to the provider's consent screen (A3 β€” a navigation, never JSON). `?next=` is the
54
+ RELATIVE path the callback returns the browser to; it rides inside the single-use state,
55
+ sanitised, so the round trip cannot be steered off-origin."""
56
+ url, problem = oauth_connect.start(provider, session.uname,
57
+ _redirect_uri(request, provider), next_path=next)
58
+ if problem:
59
+ raise err(503 if "not configured" in problem else 404, "oauth_unavailable", problem)
60
+ return RedirectResponse(url, status_code=302)
61
+
62
+
63
+ @router.get("/{provider}/callback")
64
+ def oauth_callback(provider: str, request: Request,
65
+ session: Session = Depends(require_session),
66
+ state: str = "", code: str = "", error: str = ""):
67
+ """The provider's redirect target. Exchanges the code, stores the per-user slot, and sends
68
+ the browser back to the state's return path β€” connected or not (see module header)."""
69
+ if error:
70
+ home = "/#/"
71
+ return RedirectResponse(f"{home}?oauthError={error[:80]}", status_code=302)
72
+ email, home, problem = oauth_connect.callback(session.runtime, session.uname, state, code)
73
+ sep = "&" if "?" in home else "?"
74
+ if problem:
75
+ return RedirectResponse(f"{home}{sep}oauthError=connect_failed", status_code=302)
76
+ return RedirectResponse(f"{home}{sep}connected={provider}", status_code=302)
77
+
78
+
79
+ @router.post("/{provider}/disconnect")
80
+ def oauth_disconnect(provider: str, session: Session = Depends(require_session)):
81
+ if oauth_connect.provider_def(provider) is None:
82
+ raise err(404, "unknown_provider", f"{provider!r} is not a connectable provider")
83
+ oauth_connect.disconnect(session.runtime, session.uname, provider)
84
+ return {"disconnected": provider}
platform/aios_grid.py CHANGED
@@ -269,9 +269,18 @@ AUTOMATION_SOURCES = {"record_url_field", "self"}
269
  MAX_AUTOMATION_SETTINGS = 12
270
 
271
 
272
- def _clean_automation(raw, valid_keys=None):
273
  """Validate an `automation` config bag. Returns the clean dict, or None when there is
274
- nothing valid to store (the column then renders as unconfigured β€” never invented)."""
 
 
 
 
 
 
 
 
 
275
  if not isinstance(raw, dict):
276
  return None
277
  kind = str(raw.get('kind') or '').strip()
@@ -281,6 +290,11 @@ def _clean_automation(raw, valid_keys=None):
281
  if source not in AUTOMATION_SOURCES:
282
  source = 'record_url_field'
283
  out = {'kind': kind, 'source': source}
 
 
 
 
 
284
  url_field = str(raw.get('urlField') or '').strip()[:80]
285
  # fail closed on a ref that does not exist, exactly as _clean_formula does at WRITE time
286
  if url_field and (valid_keys is None or url_field in valid_keys):
 
269
  MAX_AUTOMATION_SETTINGS = 12
270
 
271
 
272
+ def _clean_automation(raw, valid_keys=None, flow_ids=None):
273
  """Validate an `automation` config bag. Returns the clean dict, or None when there is
274
+ nothing valid to store (the column then renders as unconfigured β€” never invented).
275
+
276
+ β›” WAVE 22 (contract C8, owner item 5) β€” NO FIELD WITHOUT A FLOW. With `flow_ids` given
277
+ (the WRITE path: grid_events / user_tables pass the tenant's automation-definition ids),
278
+ the bag MUST carry a `flowId` naming one of them β€” absent or naming a deleted flow is
279
+ refused, the same fail-closed direction as a formula ref that names no field. With
280
+ `flow_ids=None` (the READ path, `fields_from_workspace`) the law is NOT applied: a column
281
+ stored before the law must keep projecting β€” enforcement at read time would vaporise it,
282
+ which is the `_clean_formula` write/read split exactly.
283
+ """
284
  if not isinstance(raw, dict):
285
  return None
286
  kind = str(raw.get('kind') or '').strip()
 
290
  if source not in AUTOMATION_SOURCES:
291
  source = 'record_url_field'
292
  out = {'kind': kind, 'source': source}
293
+ flow = str(raw.get('flowId') or '').strip()[:40]
294
+ if flow_ids is not None and (not flow or flow not in flow_ids):
295
+ return None
296
+ if flow:
297
+ out['flowId'] = flow
298
  url_field = str(raw.get('urlField') or '').strip()[:80]
299
  # fail closed on a ref that does not exist, exactly as _clean_formula does at WRITE time
300
  if url_field and (valid_keys is None or url_field in valid_keys):
platform/core/grid_events.py CHANGED
@@ -938,8 +938,21 @@ def handle_one(event, ctx):
938
  # C5-AUTOFIELD (wave 18): persist the validated config bag. No `return False`
939
  # when absent β€” an unconfigured automation column is a legitimate intermediate
940
  # state (create the column, then configure it in the gear).
941
- auto = _ag2._clean_automation(raw.get('automation'), valid_keys)
942
- if auto:
 
 
 
 
 
 
 
 
 
 
 
 
 
943
  field['automation'] = auto
944
  fmt = _ag2._clean_format(raw.get('format'), ftype)
945
  if fmt:
@@ -1560,6 +1573,8 @@ def handle_one(event, ctx):
1560
  return False
1561
  updates = {}
1562
  refused = False
 
 
1563
  raw_updates = event.get('updates') if isinstance(event.get('updates'), dict) else {}
1564
  for key, value in raw_updates.items():
1565
  if key not in overlay_keys or not isinstance(value, (str, int, float)):
@@ -1592,6 +1607,64 @@ def handle_one(event, ctx):
1592
  if (field_by_key.get(key) or {}).get('type') == 'automation':
1593
  refused = True
1594
  continue
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1595
  clean = str(value)[:10000]
1596
  if isinstance(value, str) and clean != value:
1597
  # Truncated: the stored truth is shorter than the client's copy. (An
@@ -1632,8 +1705,19 @@ def handle_one(event, ctx):
1632
  else:
1633
  _session_ready()
1634
  ws['overlays'].setdefault(str(pid), {}).update(updates)
 
 
 
 
 
 
 
 
 
1635
  # Wave-6 item 3: the client's cell already shows the typed value β€” rerun ONLY when
1636
  # some of what it shows was refused or clamped and must be repainted to the truth.
1637
- return refused
 
 
1638
 
1639
  return False
 
938
  # C5-AUTOFIELD (wave 18): persist the validated config bag. No `return False`
939
  # when absent β€” an unconfigured automation column is a legitimate intermediate
940
  # state (create the column, then configure it in the gear).
941
+ # β›” C8 (wave 22): a CONFIGURED bag must name an existing flow β€” the write door
942
+ # reads the tenant's definition ids and `_clean_automation` refuses a bag
943
+ # without one (or naming a deleted one). Refused = the whole field write is
944
+ # refused, loudly (repaint), because storing the field while dropping its bag
945
+ # would be a column that silently never runs.
946
+ if isinstance(raw.get('automation'), dict):
947
+ try:
948
+ _flow_ids = frozenset((ctx.table.st if ctx.table is not None
949
+ else _tops(ctx).st).get('automations') or {})
950
+ except Exception:
951
+ _flow_ids = frozenset()
952
+ auto = _ag2._clean_automation(raw.get('automation'), valid_keys,
953
+ flow_ids=_flow_ids)
954
+ if auto is None:
955
+ return False
956
  field['automation'] = auto
957
  fmt = _ag2._clean_format(raw.get('format'), ftype)
958
  if fmt:
 
1573
  return False
1574
  updates = {}
1575
  refused = False
1576
+ stage_moved = False
1577
+ row_events = [] # C3 (wave 22): admitted writes, emitted AFTER they apply
1578
  raw_updates = event.get('updates') if isinstance(event.get('updates'), dict) else {}
1579
  for key, value in raw_updates.items():
1580
  if key not in overlay_keys or not isinstance(value, (str, int, float)):
 
1607
  if (field_by_key.get(key) or {}).get('type') == 'automation':
1608
  refused = True
1609
  continue
1610
+ # C2 (wave 22): a STAGE FIELD is engine-written EXCEPT at a review gate, where a
1611
+ # human may advance a card to a member of the review stage's `next` and nothing
1612
+ # else. The law rides the field definition (`automation.humanMoves` / `arrive`,
1613
+ # stamped by the engine that derives the stages) because this module must not
1614
+ # import the engine β€” the engine states the law, this door enforces it
1615
+ # mechanically. An ADMITTED move writes THROUGH to the definition row, the shared
1616
+ # truth the engine and every viewer read: parked in this user's overlay stratum it
1617
+ # would be a board position only its author could see. Everything else about the
1618
+ # field is refused β€” the same wall the automation-cell type gets, extended, not
1619
+ # replaced.
1620
+ if str(ctx.scope_key or '').startswith('ut_'):
1621
+ import core.user_tables as _ut_mod
1622
+ _tdef = _ut_mod.get(ctx.scope_key, st=ctx.table.st) if ctx.table is not None \
1623
+ else None
1624
+ _fdef = next((f for f in ((_tdef or {}).get('fields') or [])
1625
+ if f.get('key') == key), None)
1626
+ # C7 (wave 22): a METRIC cell is engine-computed from the master series β€” a
1627
+ # human write would be an invented measurement, refused the way an automation
1628
+ # cell is (the wall, not the courtesy).
1629
+ if isinstance((_fdef or {}).get('metric'), dict):
1630
+ refused = True
1631
+ continue
1632
+ _auto = (_fdef or {}).get('automation')
1633
+ if isinstance(_auto, dict) and _auto.get('stageField'):
1634
+ _row = ((_tdef or {}).get('rows') or {}).get(str(pid)) or {}
1635
+ _cur = str(_row.get(key) or '').strip()
1636
+ _want = str(value).strip()
1637
+ if _want in ((_auto.get('humanMoves') or {}).get(_cur) or []):
1638
+ import datetime as _dt_sf
1639
+ _stamp_sf = _dt_sf.datetime.now().astimezone().isoformat(
1640
+ timespec='seconds')
1641
+ _ut_mod.patch_cells(
1642
+ ctx.scope_key, pid,
1643
+ {key: _want, key + '_at': _stamp_sf,
1644
+ **(((_auto.get('arrive') or {}).get(_want)) or {})},
1645
+ st=ctx.table.st)
1646
+ # C3-A2(5): the decision is AUDITED from this door too β€” same shape
1647
+ # `move_card` writes, appended mechanically off the field's flowId.
1648
+ _flow = str(_auto.get('flowId') or '')
1649
+
1650
+ def _audit_sf(cur_a, _f=_flow, _e={'ts': _stamp_sf, 'user': uname,
1651
+ 'rowId': str(pid), 'from': _cur,
1652
+ 'to': _want}):
1653
+ cur_a = cur_a if isinstance(cur_a, dict) else {}
1654
+ d = cur_a.get(_f)
1655
+ if isinstance(d, dict):
1656
+ d['reviews'] = ([_e] + list(d.get('reviews') or []))[:100]
1657
+ return cur_a
1658
+ if _flow:
1659
+ try:
1660
+ ctx.table.st.update('automations', _audit_sf, flush='async')
1661
+ except Exception:
1662
+ pass # the move stands; a lost audit line is not a veto
1663
+ stage_moved = True
1664
+ row_events.append((key, _want))
1665
+ else:
1666
+ refused = True
1667
+ continue
1668
  clean = str(value)[:10000]
1669
  if isinstance(value, str) and clean != value:
1670
  # Truncated: the stored truth is shorter than the client's copy. (An
 
1705
  else:
1706
  _session_ready()
1707
  ws['overlays'].setdefault(str(pid), {}).update(updates)
1708
+ # C3 (wave 22): the admitted writes become ROW EVENTS β€” emitted AFTER they applied, on
1709
+ # the ut scopes the event triggers watch this wave, through the seam in user_tables so
1710
+ # this module never imports the engine. Human door only, which IS the loop law.
1711
+ if str(ctx.scope_key or '').startswith('ut_') and ctx.table is not None:
1712
+ import core.user_tables as _ut_ev
1713
+ for _k, _v in list(updates.items()) + row_events:
1714
+ _ut_ev.emit_row_event({'type': 'event_field', 'table': str(ctx.scope_key),
1715
+ 'rowId': str(pid), 'field': _k, 'after': _v,
1716
+ 'st': ctx.table.st, 'user': uname})
1717
  # Wave-6 item 3: the client's cell already shows the typed value β€” rerun ONLY when
1718
  # some of what it shows was refused or clamped and must be repainted to the truth.
1719
+ # A stage move reruns too: its `arrive` side-effects (the tracked flag) changed cells
1720
+ # the client never typed.
1721
+ return refused or stage_moved
1722
 
1723
  return False
platform/core/keychain.py CHANGED
@@ -151,6 +151,84 @@ def odoo_creds(rt):
151
  return None
152
 
153
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
154
  def test_entry(rt, entry_id, timeout=8):
155
  """A cheap, READ-ONLY liveness probe. odoo: xmlrpc `common.version()` (no auth, no data);
156
  generic: shape-only. Always answers {ok, message} β€” an exception here is a result, not a
 
151
  return None
152
 
153
 
154
+ # ---------------------------------------------------------------------------------------------
155
+ # PER-USER SECRET SLOTS (wave 22, contract C5 β€” the R7 seam adopted from QM)
156
+ # ---------------------------------------------------------------------------------------------
157
+ # A connector credential that belongs to a PERSON, not to the tenant: *my* Gmail refresh token,
158
+ # never "the workspace's". Stored in a SEPARATE sub-bucket (`user_secrets`) beside `entries`,
159
+ # deliberately: `list_entries` walks `entries` only, so a user's OAuth tokens never show up in
160
+ # the admin keychain table β€” they are identity, not shared infrastructure β€” and the addition is
161
+ # migration-free (existing entries and their readers are untouched). Same Fernet, same
162
+ # fail-closed law: no AIOS_KEYCHAIN_KEY β‡’ writes refuse, reads raise, nothing plaintext.
163
+
164
+ #: Slot names are SHAPE-validated rather than enumerated (wave 22, C5 amendment A2): the OAuth
165
+ #: provider registry lives API-side and grows one entry per provider β€” a platform-side copy of
166
+ #: its keys would be the client-union defect one layer down. The shape is the law instead.
167
+ import re as _re_slots
168
+
169
+ USER_SECRET_SLOT = _re_slots.compile(r'^oauth_[a-z0-9_]{1,24}$')
170
+
171
+
172
+ def put_user_secret(rt, username, provider, fields):
173
+ """Encrypt + store ONE user's credential slot for `provider` (upsert β€” a reconnect
174
+ replaces). Raises ValueError on shape problems, KeychainLocked when there is no key."""
175
+ username = str(username or '').strip()
176
+ provider = str(provider or '').strip().lower()
177
+ if not username:
178
+ raise ValueError('no username for the secret slot')
179
+ if not USER_SECRET_SLOT.fullmatch(provider):
180
+ raise ValueError('a secret slot is named oauth_<provider>')
181
+ if not isinstance(fields, dict) or not fields:
182
+ raise ValueError('fields must be a non-empty object')
183
+ clean = {}
184
+ for k, v in list(fields.items())[:16]:
185
+ k = str(k).strip()[:40]
186
+ if k and isinstance(v, (str, int, float, bool)):
187
+ clean[k] = str(v)[:2000] # a Google refresh token is ~100 chars; JWTs more
188
+ if not clean:
189
+ raise ValueError('no usable fields')
190
+ token = _fernet().encrypt(json.dumps(clean, ensure_ascii=False).encode('utf-8'))
191
+ row = {'enc': token.decode('ascii'),
192
+ 'updated': _dt.datetime.now().strftime('%Y-%m-%dT%H:%M:%S')}
193
+
194
+ def _up(cur):
195
+ cur.setdefault('user_secrets', {}).setdefault(username, {})[provider] = row
196
+ return cur
197
+
198
+ rt.update(KEY, _up, flush='sync')
199
+ return True
200
+
201
+
202
+ def read_user_secret(rt, username, provider):
203
+ """Decrypt ONE user's slot β€” None when absent; KeychainLocked stays LOUD (a wrong key must
204
+ never read as 'not connected')."""
205
+ slot = ((_bucket(rt).get('user_secrets') or {}).get(str(username)) or {}).get(
206
+ str(provider or '').lower())
207
+ if not isinstance(slot, dict) or not slot.get('enc'):
208
+ return None
209
+ try:
210
+ raw = _fernet().decrypt(str(slot['enc']).encode('ascii'))
211
+ except KeychainLocked:
212
+ raise
213
+ except Exception:
214
+ raise KeychainLocked('this slot does not decrypt under the configured key')
215
+ try:
216
+ data = json.loads(raw.decode('utf-8'))
217
+ return data if isinstance(data, dict) else None
218
+ except Exception:
219
+ return None
220
+
221
+
222
+ def drop_user_secret(rt, username, provider):
223
+ def _drop(cur):
224
+ slots = (cur.get('user_secrets') or {}).get(str(username))
225
+ if isinstance(slots, dict):
226
+ slots.pop(str(provider or '').lower(), None)
227
+ return cur
228
+ rt.update(KEY, _drop, flush='sync')
229
+ return True
230
+
231
+
232
  def test_entry(rt, entry_id, timeout=8):
233
  """A cheap, READ-ONLY liveness probe. odoo: xmlrpc `common.version()` (no auth, no data);
234
  generic: shape-only. Always answers {ok, message} β€” an exception here is a result, not a
platform/core/user_tables.py CHANGED
@@ -66,6 +66,25 @@ def _st(st):
66
  return st if st is not None else store
67
 
68
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
69
  def _slug(label):
70
  s = re.sub(r'[^a-z0-9]+', '_', str(label or '').strip().lower()).strip('_')
71
  return (s or 'table')[:40]
@@ -264,6 +283,10 @@ def add_row(table_key, values=None, username=None, st=None, rid=None):
264
  return cur
265
 
266
  _st(st).update(STORE_KEY, _add, flush='async')
 
 
 
 
267
  return rid
268
 
269
 
@@ -323,6 +346,35 @@ def set_label(table_key, label, st=None):
323
  #: Who may edit ONE field's definition. Fail-closed default: admins (= creator or admin).
324
  FIELD_EDIT_ROLES = ('admins', 'everyone')
325
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
326
 
327
  def _clean_field(raw, previous=None):
328
  """One field dict β†’ the stored shape, or None. The single validator for create AND patch, so
@@ -351,6 +403,14 @@ def _clean_field(raw, previous=None):
351
  auto = raw.get('automation') if 'automation' in raw else prev.get('automation')
352
  if isinstance(auto, dict):
353
  out['automation'] = auto
 
 
 
 
 
 
 
 
354
  return out
355
 
356
 
@@ -366,6 +426,23 @@ def may_edit_field(table_key, fkey, viewer, is_admin=False, st=None):
366
  return False
367
 
368
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
369
  def add_field(table_key, raw, st=None):
370
  """Append one column to the shared schema. Returns the stored field, or None if refused."""
371
  if not is_user_table(table_key, st):
@@ -377,6 +454,8 @@ def add_field(table_key, raw, st=None):
377
  field = _clean_field(raw)
378
  if not field or any(f.get('key') == field['key'] for f in have):
379
  return None
 
 
380
 
381
  def _add(cur):
382
  t = cur.get(str(table_key))
@@ -406,6 +485,8 @@ def patch_field(table_key, fkey, raw, st=None):
406
  field = _clean_field(merged, fields[idx])
407
  if not field:
408
  return None
 
 
409
 
410
  def _set(cur):
411
  t = cur.get(str(table_key))
@@ -511,6 +592,30 @@ def rename_choice_values(table_key, fkey, renames, st=None):
511
  return counts
512
 
513
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
514
  def delete_row(table_key, row_id, st=None):
515
  if not is_user_table(table_key, st):
516
  return False
 
66
  return st if st is not None else store
67
 
68
 
69
+ #: Wave 22 (contract C3) β€” the ROW-EVENT seam. The API layer APPENDS listeners (the automation
70
+ #: engine's trigger hook, registered by `routes_automation` β€” the one module that imports both
71
+ #: sides); platform code only ever EMITS. This is what keeps the Notion loop-prevention law
72
+ #: structural: the emit sites are the HUMAN write doors (`add_row` here, `overlay_patch` in
73
+ #: grid_events) and nothing the engine itself writes through, so an automation's write cannot
74
+ #: fire an event trigger β€” its own or a sibling's β€” by construction.
75
+ ROW_HOOKS = []
76
+
77
+
78
+ def emit_row_event(evt):
79
+ """Fan one row event out to every registered listener. A listener failure is swallowed β€”
80
+ a broken trigger must never break typing into a cell β€” but it is swallowed LOUDLY."""
81
+ for hook in list(ROW_HOOKS):
82
+ try:
83
+ hook(evt)
84
+ except Exception as e: # noqa: BLE001
85
+ print(f'[user-tables] row hook failed: {type(e).__name__}: {e}')
86
+
87
+
88
  def _slug(label):
89
  s = re.sub(r'[^a-z0-9]+', '_', str(label or '').strip().lower()).strip('_')
90
  return (s or 'table')[:40]
 
283
  return cur
284
 
285
  _st(st).update(STORE_KEY, _add, flush='async')
286
+ # C3 (wave 22): a HUMAN-door insert is a row event β€” the record_created trigger's whole
287
+ # substrate. The engine's own writers never come through here, which is the loop law.
288
+ emit_row_event({'type': 'record_created', 'table': str(table_key), 'rowId': rid,
289
+ 'st': _st(st), 'user': str(username or '')})
290
  return rid
291
 
292
 
 
346
  #: Who may edit ONE field's definition. Fail-closed default: admins (= creator or admin).
347
  FIELD_EDIT_ROLES = ('admins', 'everyone')
348
 
349
+ #: Wave 22 (C7) β€” the metric-field vocabulary, MIRRORED from `automation_engine` as local
350
+ #: literals for the boot-path reason `MACHINE_OWNERS` states; the pair is held in step by a
351
+ #: verify_automation parity check, the same discipline.
352
+ METRIC_MEASURES = ('followers', 'avg_engagement', 'likes', 'comments')
353
+ METRIC_WINDOWS = ('latest', 'last_3_posts', 'last_7d', 'last_30d')
354
+ METRIC_PROFILE_MEASURES = ('followers', 'avg_engagement')
355
+ METRIC_AGGS = ('avg', 'sum', 'latest')
356
+
357
+
358
+ def _clean_metric(raw):
359
+ """One `metric` bag β†’ the stored shape, or None (refused). A profile count over a
360
+ post-count window β€” or a SUM of a follower count β€” is a question the series cannot
361
+ answer; refused at write, never bent into a number that looks plausible (C7)."""
362
+ if not isinstance(raw, dict):
363
+ return None
364
+ measure = str(raw.get('measure') or '').strip()
365
+ window = str(raw.get('window') or '').strip()
366
+ agg = str(raw.get('agg') or '').strip()
367
+ if measure not in METRIC_MEASURES or window not in METRIC_WINDOWS:
368
+ return None
369
+ if measure in METRIC_PROFILE_MEASURES and (window == 'last_3_posts' or agg == 'sum'):
370
+ return None
371
+ if agg and agg not in METRIC_AGGS:
372
+ return None
373
+ out = {'source': 'ig', 'measure': measure, 'window': window}
374
+ if agg:
375
+ out['agg'] = agg
376
+ return out
377
+
378
 
379
  def _clean_field(raw, previous=None):
380
  """One field dict β†’ the stored shape, or None. The single validator for create AND patch, so
 
403
  auto = raw.get('automation') if 'automation' in raw else prev.get('automation')
404
  if isinstance(auto, dict):
405
  out['automation'] = auto
406
+ # C7 (wave 22): a metric bag is validated or the FIELD is refused β€” a mis-shaped metric
407
+ # column stored anyway would be a column of invented blanks wearing a number's name.
408
+ metric_raw = raw.get('metric') if 'metric' in raw else prev.get('metric')
409
+ if metric_raw is not None:
410
+ m = _clean_metric(metric_raw)
411
+ if m is None:
412
+ return None
413
+ out['metric'] = m
414
  return out
415
 
416
 
 
426
  return False
427
 
428
 
429
+ def flow_bound(bag, st=None):
430
+ """C8 (wave 22, owner item 5) β€” may this `automation` bag be STORED? Only when its
431
+ `flowId` names an automation definition that exists in this tenant's `automations` bucket.
432
+ Fail-closed both ways: no flowId is a column that silently never runs, and a flowId naming
433
+ a deleted flow is the same thing one delete later. (Read tolerance for pre-law fields
434
+ lives in `aios_grid._clean_automation` β€” this guards the WRITE doors only.)"""
435
+ if not isinstance(bag, dict):
436
+ return True # no bag, no law β€” an ordinary column
437
+ flow = str(bag.get('flowId') or '').strip()
438
+ if not flow:
439
+ return False
440
+ try:
441
+ return flow in (_st(st).get('automations') or {})
442
+ except Exception:
443
+ return False
444
+
445
+
446
  def add_field(table_key, raw, st=None):
447
  """Append one column to the shared schema. Returns the stored field, or None if refused."""
448
  if not is_user_table(table_key, st):
 
454
  field = _clean_field(raw)
455
  if not field or any(f.get('key') == field['key'] for f in have):
456
  return None
457
+ if not flow_bound(field.get('automation'), st):
458
+ return None # C8: no field without a flow (400 at the route)
459
 
460
  def _add(cur):
461
  t = cur.get(str(table_key))
 
485
  field = _clean_field(merged, fields[idx])
486
  if not field:
487
  return None
488
+ if 'automation' in merged and not flow_bound(field.get('automation'), st):
489
+ return None # C8: a patch cannot un-bind a column either
490
 
491
  def _set(cur):
492
  t = cur.get(str(table_key))
 
592
  return counts
593
 
594
 
595
+ def patch_cells(table_key, row_id, values, st=None):
596
+ """Write cells into the DEFINITION row β€” the shared truth every viewer and the automation
597
+ engine read (wave 22, C2). Exists for the stage-field door in `core.grid_events`: a stage
598
+ position written into the editor's personal overlay stratum would be a board only its
599
+ author could see. Values are stringified; keys are taken as given because the CALLER is the
600
+ wall (grid_events admits exactly the transition the field's own `automation.humanMoves`
601
+ law allows, plus its `arrive` side-effects). Returns True when the row existed."""
602
+ if not is_user_table(table_key, st):
603
+ return False
604
+ rows = (get(table_key, st) or {}).get('rows') or {}
605
+ if str(row_id) not in rows:
606
+ return False
607
+
608
+ def _set(cur):
609
+ t = cur.get(str(table_key))
610
+ if t is not None:
611
+ t.setdefault('rows', {}).setdefault(str(row_id), {}).update(
612
+ {str(k): str(v) for k, v in (values or {}).items()})
613
+ return cur
614
+
615
+ _st(st).update(STORE_KEY, _set, flush='sync')
616
+ return True
617
+
618
+
619
  def delete_row(table_key, row_id, st=None):
620
  if not is_user_table(table_key, st):
621
  return False
web/src/automation/AutomationBoard.tsx ADDED
@@ -0,0 +1,402 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // automation/AutomationBoard.tsx β€” the automation AS A BOARD (owner ruling R1).
3
+ //
4
+ // THE MODEL, and it is the whole point of the wave: the columns are the flow's
5
+ // stages and THE CARDS ARE RECORDS. A record walks left to right; where it
6
+ // currently is lives in a single-select stage field on the target database, so
7
+ // the same field drives an ordinary Kanban view of that database and this board
8
+ // is not a second, private opinion about where anything is. A REVIEW stage holds
9
+ // its cards until a person clicks them along, and that click IS the promotion β€”
10
+ // on the discovery flow it is literally the `tracked` tick (R6, R7-W20), not a
11
+ // UI gesture that later gets synced.
12
+ //
13
+ // β›” IT RENDERS ONLY WHAT RIDES THE PAYLOAD (C1). Stages, their order, their
14
+ // switches, their dots, the routes between them, which cards exist, which of
15
+ // them may move and where to β€” all of it is `GET /automations/{id}/board`. This
16
+ // file decides pixels. It cannot show a stage the engine stopped running, and it
17
+ // does not decide whether a move is legal: it posts the drop it was given and
18
+ // prints the server's refusal verbatim.
19
+ //
20
+ // WHAT IT COPIES AND WHAT IT DOES NOT. The look is `customer-grid`'s KanbanView
21
+ // β€” tinted lane pill, count beside it, a column of quiet cards, drag with
22
+ // post-drag click suppression β€” because two boards in one product that look like
23
+ // two products is the defect DESIGN.md calls variety. It copies the LOOK and
24
+ // shares no code: the grid tree is the asset that also ships inside the embed,
25
+ // and an automation surface must not grow an edge into it (the same rule
26
+ // `automationApi.ts` is built on).
27
+ //
28
+ // TWO TRAPS, both paid for already ([[ui-invisible-to-assertions]]):
29
+ // 1. A FINISHED DRAG MUST NOT FIRE A CLICK. Browsers can deliver a click after
30
+ // `dragend`, and the thing under the pointer here is an advance button β€”
31
+ // i.e. a promotion nobody asked for. One drag suppresses exactly one click.
32
+ // 2. A CAPPED LANE MUST SAY SO. `counts` is the true per-stage total and
33
+ // `cards` may be shorter β€” server-side or by this file's own page size β€” so
34
+ // a lane whose list is shorter than its count discloses the difference. A
35
+ // silent `[:N]` is a defect, not a rendering detail
36
+ // ([[no-unverifiable-aggregates]]).
37
+ // ---------------------------------------------------------------------------
38
+ import type { DragEvent as ReactDragEvent } from "react";
39
+ import { useRef, useState } from "react";
40
+
41
+ import type { Board, BoardCard, BoardStage } from "./automationApi";
42
+
43
+ /** How many cards a lane paints before it offers the rest. Disclosed, never silent. */
44
+ const LANE_PAGE = 25;
45
+
46
+ interface Props {
47
+ board: Board;
48
+ /** The selected STAGE id β€” the right-hand panel shows that stage's config. */
49
+ selected: string;
50
+ onSelect: (stageId: string) => void;
51
+ onToggle: (stageId: string) => void;
52
+ busyStage: string;
53
+ /** Post a card move. The caller answers with a fresh board (or a refusal). */
54
+ onMove: (rowId: string, to: string) => void;
55
+ movingRow: string;
56
+ }
57
+
58
+ /**
59
+ * A stage's tint class.
60
+ *
61
+ * DESIGN.md 3's fixed semantics, applied: yellow = attention, and a review stage
62
+ * is the one that is WAITING FOR A PERSON; purple = group/routing controls, which
63
+ * is what a branch is; blue = the ordinary interactive body of the flow. Anything
64
+ * the server names that this file has never heard of lands on the neutral face
65
+ * and is still drawn β€” a stage that renders plainly is visible, a stage that
66
+ * renders as nothing is the silent drop this codebase keeps paying for.
67
+ */
68
+ function tintOf(stage: BoardStage): string {
69
+ if (stage.kind === "review" || stage.posture === "strict") return " is-review";
70
+ if (stage.kind === "branch") return " is-branch";
71
+ if (stage.kind === "action") return " is-action";
72
+ return "";
73
+ }
74
+
75
+ function postureTitle(stage: BoardStage): string {
76
+ if (stage.posture === "strict")
77
+ return `${stage.label} β€” holds each record until a person moves it along`;
78
+ if (stage.posture === "auto") return `${stage.label} β€” the automation moves records through`;
79
+ return stage.label;
80
+ }
81
+
82
+ /** A timestamp trimmed to the minute. Never a record VALUE β€” those arrive composed (C1). */
83
+ function whenText(iso: string): string {
84
+ const raw = String(iso || "");
85
+ return raw ? raw.replace("T", " ").slice(0, 16) : "";
86
+ }
87
+
88
+ export default function AutomationBoard({
89
+ board,
90
+ selected,
91
+ onSelect,
92
+ onToggle,
93
+ busyStage,
94
+ onMove,
95
+ movingRow,
96
+ }: Props) {
97
+ const [expanded, setExpanded] = useState<Set<string>>(new Set());
98
+ const [dragging, setDragging] = useState<BoardCard | null>(null);
99
+ const draggedRef = useRef(false);
100
+
101
+ const stages = board?.stages || [];
102
+ const labels = new Map(stages.map((s) => [s.id, s.label]));
103
+ // ⚠ NOT EVERY STAGE IS A PLACE. Two kinds of stage cannot hold a record and must not
104
+ // be drawn as lanes:
105
+ // Β· the TRIGGER β€” a record is never "at" the trigger; the trigger is what puts one
106
+ // on the board. Its configuration lives in the trigger face above this component.
107
+ // Β· anything the server marks `record: false` β€” the things the automation DOES
108
+ // (find, collect, write). On a real discovery flow that is three of six stages, so
109
+ // drawing them as lanes puts three permanently empty columns between the trigger
110
+ // and the first column that ever holds anything.
111
+ // They render as the PROCESS STRIP: still clickable, still switchable, still carrying
112
+ // their own dot β€” everything except a column of cards they can never contain.
113
+ //
114
+ // `record` is OPTIONAL and absent means LANE (see its note in automationApi): only an
115
+ // explicit `false` moves a stage into the strip, so a server that ships C1's contract
116
+ // text and not this field still draws the board it describes.
117
+ const boardStages = stages.filter((s) => s.kind !== "trigger");
118
+ const stripStages = boardStages.filter((s) => s.record === false);
119
+ const laneStages = boardStages.filter((s) => s.record !== false);
120
+ const cols = [...new Set(laneStages.map((s) => s.col))].sort((a, b) => a - b);
121
+
122
+ const byStage = new Map<string, BoardCard[]>();
123
+ for (const c of board?.cards || []) {
124
+ const list = byStage.get(c.stageId);
125
+ if (list) list.push(c);
126
+ else byStage.set(c.stageId, [c]);
127
+ }
128
+
129
+ const advance = (card: BoardCard, to: string) => {
130
+ // Trap 1: swallow the click a finished drag can produce.
131
+ if (draggedRef.current) return;
132
+ onMove(card.rowId, to);
133
+ };
134
+
135
+ const onDrop = (stage: BoardStage) => (e: ReactDragEvent<HTMLDivElement>) => {
136
+ e.preventDefault();
137
+ const rowId = e.dataTransfer.getData("text/plain");
138
+ setDragging(null);
139
+ if (!rowId) return;
140
+ const card = (board.cards || []).find((c) => c.rowId === rowId);
141
+ if (!card || card.stageId === stage.id) return;
142
+ onMove(rowId, stage.id);
143
+ };
144
+
145
+ const cardBox = (card: BoardCard) => {
146
+ const moving = movingRow === card.rowId;
147
+ const nexts = card.canAdvance ? card.next || [] : [];
148
+ return (
149
+ <div
150
+ key={card.rowId}
151
+ className={
152
+ "autob-card" +
153
+ (card.canAdvance ? " is-draggable" : "") +
154
+ (moving ? " is-moving" : "")
155
+ }
156
+ draggable={card.canAdvance && !moving}
157
+ title={
158
+ card.canAdvance
159
+ ? undefined
160
+ : "The server does not allow you to move this card."
161
+ }
162
+ onDragStart={
163
+ card.canAdvance
164
+ ? (e) => {
165
+ draggedRef.current = true;
166
+ setDragging(card);
167
+ e.dataTransfer.setData("text/plain", card.rowId);
168
+ }
169
+ : undefined
170
+ }
171
+ onDragEnd={() => {
172
+ setDragging(null);
173
+ // Cleared a tick later: the post-drag click arrives before this fires.
174
+ window.setTimeout(() => {
175
+ draggedRef.current = false;
176
+ }, 0);
177
+ }}
178
+ >
179
+ <span className="autob-card-title">{card.title}</span>
180
+ {card.sub ? <span className="autob-card-sub">{card.sub}</span> : null}
181
+ {card.movedAt ? (
182
+ <span className="autob-card-when">{whenText(card.movedAt)}</span>
183
+ ) : null}
184
+ {nexts.length ? (
185
+ <div className="autob-card-moves">
186
+ {nexts.map((to) => (
187
+ <button
188
+ key={to}
189
+ type="button"
190
+ className="autob-card-advance"
191
+ disabled={moving}
192
+ title={`Move ${card.title} to ${labels.get(to) || to}`}
193
+ onClick={() => advance(card, to)}
194
+ >
195
+ {nexts.length === 1 ? "Move on" : labels.get(to) || to}
196
+ <svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden="true">
197
+ <path
198
+ d="M3.4 8h9.2M9 4.4 12.6 8 9 11.6"
199
+ stroke="currentColor"
200
+ strokeWidth="1.5"
201
+ strokeLinecap="round"
202
+ strokeLinejoin="round"
203
+ />
204
+ </svg>
205
+ </button>
206
+ ))}
207
+ </div>
208
+ ) : null}
209
+ </div>
210
+ );
211
+ };
212
+
213
+ const lane = (stage: BoardStage) => {
214
+ const all = byStage.get(stage.id) || [];
215
+ const open = expanded.has(stage.id);
216
+ const shown = open ? all : all.slice(0, LANE_PAGE);
217
+ // The TRUE total is the server's count; the list may be shorter for two
218
+ // independent reasons, and the disclosure covers both without pretending to
219
+ // know which one applied.
220
+ const total = typeof board.counts?.[stage.id] === "number"
221
+ ? board.counts[stage.id]
222
+ : all.length;
223
+ // TWO independent caps, and they need different controls. This file hiding
224
+ // cards it HAS is expandable; the server not having SENT them is not β€” and an
225
+ // expander offered for the second case is a control that lies.
226
+ const clientCapped = shown.length < all.length;
227
+ // A DERIVED bucket takes no drop: `record && !assignable` means cards appear there
228
+ // from what is true about the row, and nothing may stamp one in. The server would
229
+ // refuse it anyway β€” this just stops the board from inviting the refusal.
230
+ const droppable = stage.assignable !== false;
231
+ const legal = droppable && !!dragging && (dragging.next || []).includes(stage.id);
232
+ const outgoing = (board.routes || []).filter((r) => r.from === stage.id && r.condition);
233
+
234
+ return (
235
+ <div
236
+ key={stage.id}
237
+ className={
238
+ "autob-lane" +
239
+ tintOf(stage) +
240
+ (stage.id === selected ? " is-selected" : "") +
241
+ (stage.enabled ? "" : " is-off") +
242
+ (legal ? " is-target" : "")
243
+ }
244
+ onDragOver={droppable ? (e) => e.preventDefault() : undefined}
245
+ onDrop={droppable ? onDrop(stage) : undefined}
246
+ >
247
+ <div className="autob-lane-head">
248
+ <button
249
+ type="button"
250
+ className="autob-lane-hit"
251
+ aria-pressed={stage.id === selected}
252
+ title={postureTitle(stage)}
253
+ onClick={() => onSelect(stage.id)}
254
+ >
255
+ <span className="autob-lane-pill">{stage.label}</span>
256
+ <span className="autob-lane-count">{total.toLocaleString()}</span>
257
+ <span
258
+ className={`auto-dot is-${stage.status}`}
259
+ title={`Last run: ${stage.status}`}
260
+ aria-label={`Last run: ${stage.status}`}
261
+ />
262
+ </button>
263
+ {stage.toggle ? (
264
+ <button
265
+ type="button"
266
+ className={"auto-step-switch autob-lane-switch" + (stage.enabled ? " is-on" : "")}
267
+ disabled={busyStage === stage.id}
268
+ aria-pressed={stage.enabled}
269
+ aria-label={`${stage.enabled ? "Turn off" : "Turn on"} ${stage.label}`}
270
+ title={`${stage.enabled ? "Turn off" : "Turn on"} ${stage.label}`}
271
+ onClick={() => onToggle(stage.id)}
272
+ >
273
+ <span className="auto-step-switch-knob" />
274
+ </button>
275
+ ) : null}
276
+ </div>
277
+
278
+ <div className="autob-lane-cards">{shown.map(cardBox)}</div>
279
+
280
+ {clientCapped ? (
281
+ <button
282
+ type="button"
283
+ className="autob-lane-more"
284
+ onClick={() => setExpanded((prev) => new Set(prev).add(stage.id))}
285
+ >
286
+ Showing {shown.length.toLocaleString()} of {total.toLocaleString()} β€” show all
287
+ </button>
288
+ ) : shown.length < total ? (
289
+ // The rest were never sent, so there is nothing here to expand. `truncated` is
290
+ // the server saying so in its own words; the arithmetic agrees either way, and
291
+ // the field is what makes the sentence a quotation rather than a deduction.
292
+ <p
293
+ className="autob-lane-more is-flat"
294
+ title={
295
+ (board.truncated || []).includes(stage.id)
296
+ ? "The server sent the first batch for this stage; the count is the true total."
297
+ : undefined
298
+ }
299
+ >
300
+ Showing {shown.length.toLocaleString()} of {total.toLocaleString()}
301
+ </p>
302
+ ) : null}
303
+
304
+ {outgoing.length ? (
305
+ <div className="autob-lane-routes">
306
+ {outgoing.map((r) => (
307
+ <span key={`${r.from}-${r.to}`} className="autob-route" title="Records matching this go there next">
308
+ {r.label ||
309
+ `${r.condition?.field} ${r.condition?.op} ${r.condition?.value ?? ""}`.trim()}
310
+ {" β†’ "}
311
+ {labels.get(r.to) || r.to}
312
+ </span>
313
+ ))}
314
+ </div>
315
+ ) : null}
316
+ </div>
317
+ );
318
+ };
319
+
320
+ if (!boardStages.length) {
321
+ return (
322
+ <div className="autob-board">
323
+ <p className="autob-board-note">This automation has no stages yet.</p>
324
+ </div>
325
+ );
326
+ }
327
+
328
+ return (
329
+ <div className="autob-board">
330
+ {!board.stageField ? (
331
+ <p className="autob-board-note">
332
+ Records appear here once this flow is bound to a database.
333
+ </p>
334
+ ) : null}
335
+ {stripStages.length ? (
336
+ <div className="autob-strip">
337
+ {stripStages.map((st) => (
338
+ /*
339
+ ⚠ A WRAPPER, NOT ONE BUTTON, and the switch is the reason. `write` carries a
340
+ toggle β€” it is the DRY-RUN control, the difference between a run that writes
341
+ and a run that only reports what it would have written β€” and the strip is now
342
+ the only place that stage appears. A chip that dropped it would have deleted a
343
+ shipped control from the product while every gate stayed green. (Nesting the
344
+ switch inside the chip's own button is not the fix: a button inside a button
345
+ is invalid, and browsers un-nest it in ways that lose the inner click.)
346
+ */
347
+ <div
348
+ key={st.id}
349
+ className={
350
+ "autob-strip-step" +
351
+ (st.id === selected ? " is-selected" : "") +
352
+ (st.enabled ? "" : " is-off")
353
+ }
354
+ >
355
+ <button
356
+ type="button"
357
+ className="autob-strip-hit"
358
+ aria-pressed={st.id === selected}
359
+ title={st.detail || st.label}
360
+ onClick={() => onSelect(st.id)}
361
+ >
362
+ <span className="autob-strip-label">{st.label}</span>
363
+ <span
364
+ className={`auto-dot is-${st.status}`}
365
+ title={`Last run: ${st.status}`}
366
+ aria-label={`Last run: ${st.status}`}
367
+ />
368
+ </button>
369
+ {st.toggle ? (
370
+ <button
371
+ type="button"
372
+ className={"auto-step-switch autob-strip-switch" + (st.enabled ? " is-on" : "")}
373
+ disabled={busyStage === st.id}
374
+ aria-pressed={st.enabled}
375
+ aria-label={`${st.enabled ? "Turn off" : "Turn on"} ${st.label}`}
376
+ title={`${st.enabled ? "Turn off" : "Turn on"} ${st.label}`}
377
+ onClick={() => onToggle(st.id)}
378
+ >
379
+ <span className="auto-step-switch-knob" />
380
+ </button>
381
+ ) : null}
382
+ </div>
383
+ ))}
384
+ </div>
385
+ ) : null}
386
+ <div className="autob-cols">
387
+ {cols.map((col) => (
388
+ <div className="autob-col" key={col}>
389
+ {/* STACKED LANES ARE THE BRANCH PATHS (R5). Two stages at the same column
390
+ are two places a record can be at the same point in the flow β€” the
391
+ routing decides which β€” so they stack rather than sitting side by side,
392
+ which would read as "then". */}
393
+ {laneStages
394
+ .filter((s) => s.col === col)
395
+ .sort((a, b) => a.row - b.row)
396
+ .map(lane)}
397
+ </div>
398
+ ))}
399
+ </div>
400
+ </div>
401
+ );
402
+ }
web/src/automation/AutomationDetail.tsx CHANGED
@@ -1,1025 +1,1148 @@
1
- // ---------------------------------------------------------------------------
2
- // automation/AutomationDetail.tsx β€” one automation, as a flow you can walk.
3
- //
4
- // THE SHAPE (wave-21 R9, replacing the W19 canvas): the automation is a column of
5
- // NUMBERED STEPS, trigger first, and the right-hand panel shows the configuration
6
- // of whichever step you clicked. The two halves answer different questions and
7
- // neither used to be answerable at a glance β€” the steps answer "what does this
8
- // thing do, in what order, and which step went wrong last night", the panel
9
- // answers "what exactly is step 3 configured to do". The canvas answered the
10
- // first question as a SHAPE; the engine executes a list, and a list is what the
11
- // owner asked to read.
12
- //
13
- // ONE CONTROL PER FACT. A step's SWITCH is the only way to turn it on or off; the
14
- // panel never carries a second checkbox for the same flag. STEP 1 IS THE ONE
15
- // EXCEPTION AND IT IS THE SAME RULE: the trigger's picker IS its on/off, so the
16
- // panel has no schedule face at all any more. Two controls for one boolean is how
17
- // a UI starts disagreeing with itself.
18
- //
19
- // EVERY COUNT DRILLS TO ROWS. A run that says "412 updated" opens the 412
20
- // ([[no-unverifiable-aggregates]]) β€” a number with no way back to its records is
21
- // what this codebase treats as a defect rather than a summary.
22
- // ---------------------------------------------------------------------------
23
- import { useCallback, useEffect, useState } from "react";
24
-
25
- import AutomationSteps from "./AutomationSteps";
26
- import type {
27
- Automation,
28
- AutomationKind,
29
- GraphNode,
30
- RunEntry,
31
- RunRows,
32
- DiscoverEstimate,
33
- DiscoverVocab,
34
- SourcePreview,
35
- TickState,
36
- UserTable,
37
- } from "./automationApi";
38
- import {
39
- AutomationError,
40
- COUNT_LABELS,
41
- deleteAutomation,
42
- discoverEstimate,
43
- fieldKeyFor,
44
- listTables,
45
- patchAutomation,
46
- previewSource,
47
- runAutomation,
48
- runRows,
49
- toggleNode,
50
- } from "./automationApi";
51
-
52
- interface Props {
53
- automation: Automation;
54
- kinds: { key: AutomationKind; label: string }[];
55
- /** The server's schedule vocabulary, forwarded to Step 1's Custom face. */
56
- cronPresets: { cron: string; label: string }[];
57
- paidReady: boolean;
58
- /** The server-declared discovery vocabulary (absent until the list loads). */
59
- discover?: DiscoverVocab;
60
- /**
61
- * Can a schedule fire here? `null` = the server did not say (C6 amendment #1 is not live
62
- * yet) β€” a REQUIRED key so an unmounted prop fails `tsc` rather than silently reading as
63
- * "off", which would make Step 1 state a measurement nobody made.
64
- */
65
- tick: TickState | null;
66
- onSaved: (id?: string) => void | Promise<void>;
67
- onDeleted: () => void | Promise<void>;
68
- }
69
-
70
- interface ColumnPlan {
71
- column: string;
72
- include: boolean;
73
- key: string;
74
- }
75
-
76
- /** One condition of a corpus search. Mirrors the server's `clean_predicates`. */
77
- interface Predicate {
78
- name: string;
79
- operator: string;
80
- value?: string | number;
81
- }
82
-
83
- export default function AutomationDetail({
84
- automation,
85
- kinds,
86
- cronPresets,
87
- paidReady,
88
- discover,
89
- tick,
90
- onSaved,
91
- onDeleted,
92
- }: Props) {
93
- const cfg = (automation.config || {}) as Record<string, string | number | boolean>;
94
- const kind = automation.kind;
95
-
96
- const [name, setName] = useState(automation.name || "");
97
- const [cron, setCron] = useState(automation.schedule?.cron || "0 6 * * *");
98
- const [message, setMessage] = useState("");
99
- const [problem, setProblem] = useState("");
100
- const [saving, setSaving] = useState(false);
101
- const [touched, setTouched] = useState(false);
102
- const [busyNode, setBusyNode] = useState("");
103
- const [triggerBusy, setTriggerBusy] = useState(false);
104
- const [selected, setSelected] = useState("");
105
-
106
- // --- scrape_db half
107
- const [url, setUrl] = useState(String(cfg.url || ""));
108
- const [extract, setExtract] = useState(String(cfg.extract || "table"));
109
- const [tableIndex, setTableIndex] = useState(Number(cfg.tableIndex || 0));
110
- const [targetLabel, setTargetLabel] = useState(String(cfg.targetLabel || ""));
111
- const [preview, setPreview] = useState<SourcePreview | null>(null);
112
- const [reading, setReading] = useState(false);
113
- const [plan, setPlan] = useState<ColumnPlan[]>(() =>
114
- Object.entries((automation.config as { fieldMap?: Record<string, string> })?.fieldMap || {})
115
- .map(([column, key]) => ({ column, include: true, key }))
116
- );
117
- const [keyField, setKeyField] = useState(String(cfg.keyField || ""));
118
-
119
- // --- field_instagram half
120
- const [tables, setTables] = useState<UserTable[]>([]);
121
- const [targetTable, setTargetTable] = useState(String(cfg.targetTable || ""));
122
- const [fieldKey, setFieldKey] = useState(String(cfg.fieldKey || ""));
123
- const [urlField, setUrlField] = useState(String(cfg.urlField || ""));
124
- const [maxPosts, setMaxPosts] = useState(Number(cfg.maxPosts || 24));
125
-
126
- // --- discover_instagram half (R7)
127
- const [recordsLimit, setRecordsLimit] = useState(Number(cfg.recordsLimit || 25));
128
- const [joinOp, setJoinOp] = useState(String(cfg.operator || "and"));
129
- const [preds, setPreds] = useState<Predicate[]>(() => {
130
- const stored = (automation.config as { predicates?: Predicate[] })?.predicates;
131
- return stored && stored.length
132
- ? stored.map((p) => ({ ...p }))
133
- : [{ name: "followers", operator: ">=", value: 10000 }];
134
- });
135
- const [estimate, setEstimate] = useState<DiscoverEstimate | null>(null);
136
-
137
- // --- run history drill
138
- const [drill, setDrill] = useState<RunRows | null>(null);
139
- const [drillFor, setDrillFor] = useState("");
140
-
141
- useEffect(() => {
142
- const ac = new AbortController();
143
- listTables(ac.signal)
144
- .then((r) => setTables(r.tables))
145
- .catch(() => setTables([]));
146
- return () => ac.abort();
147
- }, []);
148
-
149
- const table = tables.find((t) => t.key === targetTable) || null;
150
- const node: GraphNode | null =
151
- (automation.graph?.nodes || []).find((n) => n.id === selected) || null;
152
-
153
- const edit = <T,>(set: (v: T) => void) => (v: T) => {
154
- setTouched(true);
155
- set(v);
156
- };
157
-
158
- const readPage = useCallback(async () => {
159
- setReading(true);
160
- setProblem("");
161
- try {
162
- const p = await previewSource(url, extract, tableIndex);
163
- setPreview(p);
164
- if (!p.ok) {
165
- setProblem(p.note || `That page answered ${p.status}.`);
166
- return;
167
- }
168
- // Seed the plan from what the page ACTUALLY offers, keeping any mapping the
169
- // user already made for a column that is still there β€” re-reading a page
170
- // must not throw away the work of mapping it.
171
- setPlan((prev) => {
172
- const had = new Map(prev.map((c) => [c.column, c]));
173
- return p.columns.map((column) => {
174
- const before = had.get(column);
175
- return {
176
- column,
177
- include: before ? before.include : true,
178
- key: before ? before.key : fieldKeyFor(column),
179
- };
180
- });
181
- });
182
- setKeyField((k) =>
183
- k && p.columns.some((c) => fieldKeyFor(c) === k) ? k : fieldKeyFor(p.columns[0] || "")
184
- );
185
- if (!targetLabel) setTargetLabel(p.title || "Scraped table");
186
- setTouched(true);
187
- setMessage(
188
- `Read ${p.rowCount} rows and ${p.columns.length} columns` +
189
- (p.tableCount && p.tableCount > 1 ? ` (of ${p.tableCount} tables on the page)` : "")
190
- );
191
- } catch (e) {
192
- setProblem(e instanceof AutomationError ? e.message : "That page could not be read.");
193
- } finally {
194
- setReading(false);
195
- }
196
- }, [url, extract, tableIndex, targetLabel]);
197
-
198
- /**
199
- * ⚠ The switch flags (`tier`, `noFallback`, `dryRun`) are DELIBERATELY absent.
200
- * They are node switches, not panel fields, and the server keeps the stored
201
- * value for any flag a config omits β€” so a Save from here can never quietly
202
- * turn the paid rung off. (`clean_config`'s `flag()`, asserted in section N.)
203
- */
204
- const buildConfig = (): Record<string, unknown> => {
205
- if (kind === "scrape_db") {
206
- const fieldMap: Record<string, string> = {};
207
- for (const c of plan) if (c.include && c.key) fieldMap[c.column] = c.key;
208
- return {
209
- url,
210
- extract,
211
- tableIndex,
212
- fieldMap,
213
- keyField,
214
- targetTable: String(cfg.targetTable || ""),
215
- targetLabel,
216
- };
217
- }
218
- if (kind === "discover_instagram") {
219
- return {
220
- recordsLimit,
221
- operator: joinOp,
222
- predicates: preds.filter((p) => p.name && p.operator),
223
- targetTable: String(cfg.targetTable || ""),
224
- };
225
- }
226
- return { targetTable, fieldKey, urlField, maxPosts };
227
- };
228
-
229
- const persist = async (announce = true, sched?: { cron: string; enabled: boolean }) => {
230
- const res = await patchAutomation(automation.id, {
231
- name,
232
- kind,
233
- config: buildConfig(),
234
- schedule: sched || { cron, enabled: !!automation.schedule?.enabled },
235
- });
236
- setTouched(false);
237
- if (announce) setMessage("Saved.");
238
- return res.automation.id;
239
- };
240
-
241
- /**
242
- * Step 1's controls persist IMMEDIATELY (R9). A trigger you have to remember to Save is the
243
- * same defect as a switch you have to remember to Save β€” the node switches next to it are
244
- * immediate, and two save disciplines in one column is how a user ends up with an automation
245
- * that says "every Monday" and runs every day.
246
- *
247
- * ⚠ The CUSTOM CRON STRING is the exception, and deliberately: it is free text, so persisting
248
- * per keystroke would PATCH a half-typed schedule five times. It marks the editor touched and
249
- * rides the header's Save β€” and because every immediate write goes through `persist()`, an
250
- * unsaved cron edit is written with it rather than being discarded by the reload.
251
- */
252
- const saveTrigger = async (next: { cron: string; enabled: boolean }) => {
253
- setTriggerBusy(true);
254
- setProblem("");
255
- setMessage("");
256
- setCron(next.cron);
257
- try {
258
- await patchAutomation(automation.id, {
259
- name,
260
- kind,
261
- config: buildConfig(),
262
- schedule: { cron: next.cron, enabled: next.enabled },
263
- });
264
- setTouched(false);
265
- await onSaved(automation.id);
266
- } catch (e) {
267
- setProblem(e instanceof AutomationError ? e.message : "That schedule was not saved.");
268
- } finally {
269
- setTriggerBusy(false);
270
- }
271
- };
272
-
273
- const save = async () => {
274
- setSaving(true);
275
- setProblem("");
276
- setMessage("");
277
- try {
278
- const id = await persist();
279
- await onSaved(id);
280
- } catch (e) {
281
- setProblem(e instanceof AutomationError ? e.message : "That could not be saved.");
282
- } finally {
283
- setSaving(false);
284
- }
285
- };
286
-
287
- /**
288
- * A node switch is immediate β€” a switch that needs a separate Save is not a
289
- * switch. Unsaved panel edits are persisted FIRST rather than being discarded
290
- * by the reload that follows, which is the one way this could lose work.
291
- */
292
- const flip = async (nodeId: string) => {
293
- setBusyNode(nodeId);
294
- setProblem("");
295
- setMessage("");
296
- try {
297
- if (touched) await persist(false);
298
- await toggleNode(automation.id, nodeId);
299
- await onSaved(automation.id);
300
- } catch (e) {
301
- setProblem(e instanceof AutomationError ? e.message : "That step was not changed.");
302
- } finally {
303
- setBusyNode("");
304
- }
305
- };
306
-
307
- const start = async () => {
308
- setProblem("");
309
- try {
310
- await runAutomation(automation.id);
311
- setMessage("Started. The node dots follow it.");
312
- await onSaved(automation.id);
313
- } catch (e) {
314
- setProblem(e instanceof AutomationError ? e.message : "It did not start.");
315
- }
316
- };
317
-
318
- const remove = async () => {
319
- setProblem("");
320
- try {
321
- await deleteAutomation(automation.id);
322
- await onDeleted();
323
- } catch (e) {
324
- setProblem(e instanceof AutomationError ? e.message : "It was not deleted.");
325
- }
326
- };
327
-
328
- const openDrill = async (entry: RunEntry) => {
329
- if (drillFor === entry.ts) {
330
- setDrill(null);
331
- setDrillFor("");
332
- return;
333
- }
334
- try {
335
- const rows = await runRows(automation.id);
336
- setDrill(rows);
337
- setDrillFor(entry.ts);
338
- } catch (e) {
339
- setProblem(e instanceof AutomationError ? e.message : "Those rows could not be read.");
340
- }
341
- };
342
-
343
- const state = automation.running ? "running" : automation.status?.state || "idle";
344
-
345
- return (
346
- <div className="auto-detail">
347
- <header className="auto-head">
348
- <div className="auto-head-title">
349
- <input
350
- className="auto-name"
351
- value={name}
352
- placeholder="Name this automation"
353
- aria-label="Automation name"
354
- onChange={(e) => edit(setName)(e.target.value)}
355
- />
356
- <span className={`auto-chip is-${state}`}>
357
- {automation.running ? "Running" : state}
358
- </span>
359
- <span className="auto-kindtag">
360
- {kinds.find((k) => k.key === kind)?.label || kind}
361
- </span>
362
- </div>
363
- <div className="auto-head-actions">
364
- <button
365
- type="button"
366
- className="auto-btn"
367
- disabled={!!automation.running}
368
- onClick={() => void start()}
369
- >
370
- {automation.running ? "Running…" : "Run now"}
371
- </button>
372
- <button
373
- type="button"
374
- className="auto-btn is-primary"
375
- disabled={saving || !name.trim()}
376
- onClick={() => void save()}
377
- >
378
- {saving ? "Saving…" : "Save"}
379
- </button>
380
- <button type="button" className="auto-btn is-danger" onClick={() => void remove()}>
381
- Delete
382
- </button>
383
- </div>
384
- </header>
385
-
386
- {problem ? (
387
- <div className="auto-banner is-error" role="alert">
388
- {problem}
389
- </div>
390
- ) : null}
391
- {message ? (
392
- <div className="auto-banner is-ok" role="status">
393
- {message}
394
- </div>
395
- ) : null}
396
-
397
- <div className="auto-work">
398
- <AutomationSteps
399
- graph={automation.graph}
400
- selected={selected}
401
- onSelect={setSelected}
402
- onToggle={(id) => void flip(id)}
403
- busyNode={busyNode}
404
- nextRunAt={automation.nextRunAt}
405
- cron={cron}
406
- enabled={!!automation.schedule?.enabled}
407
- tick={tick}
408
- onTrigger={(next) => void saveTrigger(next)}
409
- onCronText={(next) => edit(setCron)(next)}
410
- cronPresets={cronPresets}
411
- triggerBusy={triggerBusy}
412
- />
413
-
414
- <aside className="auto-panel" aria-label={node ? `${node.title} settings` : "Run history"}>
415
- {node ? (
416
- <>
417
- <div className="auto-panel-head">
418
- <h2>{node.title}</h2>
419
- <button
420
- type="button"
421
- className="auto-panel-close"
422
- aria-label="Back to run history"
423
- title="Back to run history"
424
- onClick={() => setSelected("")}
425
- >
426
- <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
427
- <path
428
- d="M4 4l8 8M12 4l-8 8"
429
- stroke="currentColor"
430
- strokeWidth="1.5"
431
- strokeLinecap="round"
432
- />
433
- </svg>
434
- </button>
435
- </div>
436
- {!node.enabled ? (
437
- <p className="auto-note is-off">
438
- This step is switched off. Its own card carries the switch that turns it back on.
439
- </p>
440
- ) : null}
441
-
442
- {/*
443
- β›” THE SCHEDULE FACE IS GONE FROM THIS PANEL (R9), and its absence is the
444
- point. Step 1 now carries the trigger's on/off AND its shape, so a second
445
- cron control here would be two controls for one fact β€” the thing this file's
446
- header forbids, and the way a UI starts disagreeing with itself. The trigger
447
- step is not selectable for the same reason: there is nothing left to show
448
- here that the card does not already say.
449
- */}
450
-
451
- {node.panel === "source" && kind === "scrape_db" ? (
452
- <>
453
- <div className="auto-field">
454
- <label htmlFor="auto-url">Page URL</label>
455
- <input
456
- id="auto-url"
457
- className="auto-input"
458
- value={url}
459
- placeholder="https://en.wikipedia.org/wiki/List_of_S%26P_500_companies"
460
- onChange={(e) => edit(setUrl)(e.target.value)}
461
- />
462
- </div>
463
- <button
464
- type="button"
465
- className="auto-btn"
466
- disabled={!url.trim() || reading}
467
- onClick={() => void readPage()}
468
- >
469
- {reading ? "Reading…" : "Read the page"}
470
- </button>
471
- <div className="auto-field">
472
- <label htmlFor="auto-extract">Read</label>
473
- <select
474
- id="auto-extract"
475
- className="auto-input"
476
- value={extract}
477
- onChange={(e) => edit(setExtract)(e.target.value)}
478
- >
479
- <option value="table">An HTML table</option>
480
- <option value="jsonld">Structured data (JSON-LD)</option>
481
- </select>
482
- </div>
483
- {extract === "table" ? (
484
- <div className="auto-field">
485
- <label htmlFor="auto-tidx">Which table</label>
486
- <input
487
- id="auto-tidx"
488
- className="auto-input"
489
- type="number"
490
- min={0}
491
- value={tableIndex}
492
- onChange={(e) => edit(setTableIndex)(Number(e.target.value) || 0)}
493
- />
494
- </div>
495
- ) : null}
496
- <p className="auto-hint">
497
- Public web pages only. Private, loopback and link-local addresses are refused
498
- β€” including a public URL that redirects to one.
499
- </p>
500
- </>
501
- ) : null}
502
-
503
- {node.panel === "columns" ? (
504
- plan.length ? (
505
- <>
506
- <p className="auto-hint">
507
- Pick the key β€” the column that identifies a row. On every re-run, a row
508
- whose key already exists is updated; a new key is inserted; a key that has
509
- stopped appearing is counted and kept.
510
- </p>
511
- <div className="auto-panel-scroll">
512
- <table className="auto-table">
513
- <thead>
514
- <tr>
515
- <th>Use</th>
516
- <th>Source column</th>
517
- <th>Field key</th>
518
- <th>Key</th>
519
- </tr>
520
- </thead>
521
- <tbody>
522
- {plan.map((c, i) => (
523
- <tr key={c.column}>
524
- <td>
525
- <input
526
- type="checkbox"
527
- checked={c.include}
528
- aria-label={`Include ${c.column}`}
529
- onChange={(e) =>
530
- edit(setPlan)(
531
- plan.map((x, j) =>
532
- j === i ? { ...x, include: e.target.checked } : x
533
- )
534
- )
535
- }
536
- />
537
- </td>
538
- <td className="auto-cell-name">{c.column}</td>
539
- <td>
540
- <input
541
- className="auto-input is-small"
542
- value={c.key}
543
- aria-label={`Field key for ${c.column}`}
544
- onChange={(e) =>
545
- edit(setPlan)(
546
- plan.map((x, j) =>
547
- j === i
548
- ? { ...x, key: fieldKeyFor(e.target.value) }
549
- : x
550
- )
551
- )
552
- }
553
- />
554
- </td>
555
- <td>
556
- <input
557
- type="radio"
558
- name="auto-keyfield"
559
- checked={keyField === c.key && c.include}
560
- disabled={!c.include}
561
- aria-label={`Use ${c.column} as the key`}
562
- onChange={() => edit(setKeyField)(c.key)}
563
- />
564
- </td>
565
- </tr>
566
- ))}
567
- </tbody>
568
- </table>
569
- </div>
570
- {preview?.sample?.length ? (
571
- <p className="auto-hint">
572
- First row read: {Object.values(preview.sample[0]).slice(0, 4).join(" Β· ")}
573
- </p>
574
- ) : null}
575
- </>
576
- ) : (
577
- <p className="auto-note">
578
- Open the Fetch step and read the page to see what columns it offers.
579
- </p>
580
- )
581
- ) : null}
582
-
583
- {node.panel === "source" && kind === "field_instagram" ? (
584
- <>
585
- <div className="auto-field">
586
- <label htmlFor="auto-table">Database</label>
587
- <select
588
- id="auto-table"
589
- className="auto-input"
590
- value={targetTable}
591
- onChange={(e) => {
592
- edit(setTargetTable)(e.target.value);
593
- setFieldKey("");
594
- setUrlField("");
595
- }}
596
- >
597
- <option value="">Choose a database…</option>
598
- {targetTable && !tables.some((t) => t.key === targetTable) ? (
599
- <option value={targetTable}>{targetTable} (not visible to you)</option>
600
- ) : null}
601
- {tables.map((t) => (
602
- <option key={t.key} value={t.key}>
603
- {t.label} ({t.rowCount} {t.rowCount === 1 ? "row" : "rows"})
604
- </option>
605
- ))}
606
- </select>
607
- </div>
608
- <div className="auto-field">
609
- <label htmlFor="auto-urlfield">Profile URL column</label>
610
- <select
611
- id="auto-urlfield"
612
- className="auto-input"
613
- value={urlField}
614
- onChange={(e) => edit(setUrlField)(e.target.value)}
615
- >
616
- <option value="">The column the field is bound to</option>
617
- {(table?.fields || []).map((f) => (
618
- <option key={f.key} value={f.key}>
619
- {f.label}
620
- </option>
621
- ))}
622
- </select>
623
- </div>
624
- <div className="auto-field">
625
- <label htmlFor="auto-fieldkey">Automation column</label>
626
- <select
627
- id="auto-fieldkey"
628
- className="auto-input"
629
- value={fieldKey}
630
- onChange={(e) => edit(setFieldKey)(e.target.value)}
631
- >
632
- <option value="">Choose a column…</option>
633
- {/*
634
- ⚠ THE STORED VALUE IS ALWAYS AN OPTION, even when the list
635
- below does not contain it. A <select> whose `value` matches
636
- no <option> renders the FIRST one β€” so a column the server
637
- knows about but this list has not caught up with would look
638
- like a DIFFERENT column, and the next Save would write that
639
- different column without anybody choosing it. Showing it as
640
- "(not in this database)" is the honest version.
641
- */}
642
- {fieldKey && !(table?.fields || []).some((f) => f.key === fieldKey) ? (
643
- <option value={fieldKey}>{fieldKey} (not in this database)</option>
644
- ) : null}
645
- {(table?.fields || [])
646
- .filter((f) => f.type === "automation")
647
- .map((f) => (
648
- <option key={f.key} value={f.key}>
649
- {f.label}
650
- </option>
651
- ))}
652
- </select>
653
- </div>
654
- {table && !(table.fields || []).some((f) => f.type === "automation") ? (
655
- <p className="auto-note">
656
- That database has no automation column yet. Add one from the grid&rsquo;s
657
- column menu, then choose it here.
658
- </p>
659
- ) : null}
660
- </>
661
- ) : null}
662
-
663
- {node.panel === "capture" ? (
664
- <>
665
- <div className="auto-field">
666
- <label htmlFor="auto-maxposts">Posts per pull</label>
667
- <input
668
- id="auto-maxposts"
669
- className="auto-input"
670
- type="number"
671
- min={1}
672
- max={200}
673
- value={maxPosts}
674
- onChange={(e) => edit(setMaxPosts)(Number(e.target.value) || 24)}
675
- />
676
- </div>
677
- <h3>Bright Data β€” the paid rung</h3>
678
- <p className="auto-hint">
679
- Exact follower counts and the profile&rsquo;s top posts, and it works from a
680
- datacenter. Its node&rsquo;s switch turns it on.
681
- {paidReady
682
- ? " A key is configured on this deployment."
683
- : " No key is configured on this deployment yet, so it will report itself blocked and the anonymous rung will answer instead."}
684
- </p>
685
- <h3>Post engagement β€” the per-post rung</h3>
686
- <p className="auto-hint">
687
- Likes and comments for each post. It is a separate step because it is a
688
- separate bill: the profile read costs one record, and engagement costs{" "}
689
- <strong>one record per post</strong>. With it off, the posts database still
690
- grows but the engagement series does not β€” and no empty rows are appended to
691
- stand in for the numbers nobody bought.
692
- </p>
693
- <h3>Anonymous β€” the free rung</h3>
694
- <p className="auto-hint">
695
- No login and no credentials. Instagram blocks datacenter addresses and has
696
- closed most of its anonymous surface, so this rung is honest rather than
697
- reliable: counts come from the page&rsquo;s own abbreviations (204K, not
698
- 204,312) and are marked approximate. Turning it off means{" "}
699
- <strong>exact numbers or nothing</strong> β€” a run reports blocked rather than
700
- quietly writing a rounded number.
701
- </p>
702
- <p className="auto-hint">
703
- A pull reports what it actually got: <strong>ok</strong> (profile and posts),{" "}
704
- <strong>partial</strong> (profile only), or <strong>blocked</strong>. It never
705
- reports success on nothing.
706
- </p>
707
- </>
708
- ) : null}
709
-
710
- {node.panel === "find" ? (
711
- <>
712
- <div className="auto-field">
713
- <label htmlFor="auto-records">How many profiles to fetch</label>
714
- <input
715
- id="auto-records"
716
- className="auto-input"
717
- type="number"
718
- min={1}
719
- max={discover?.maxRecords || 1000}
720
- value={recordsLimit}
721
- onChange={(e) => {
722
- edit(setRecordsLimit)(Number(e.target.value) || 1);
723
- setEstimate(null);
724
- }}
725
- />
726
- </div>
727
- <p className="auto-hint">
728
- A search must be bounded. An unbounded one matches a share of a corpus of
729
- hundreds of millions of profiles, and the vendor refuses it outright rather
730
- than delivering it.
731
- </p>
732
-
733
- <h3>Conditions</h3>
734
- {preds.map((pr, i) => (
735
- <div className="auto-field-row" key={i}>
736
- <div className="auto-field">
737
- <label htmlFor={"auto-pred-f-" + i}>Field</label>
738
- <select
739
- id={"auto-pred-f-" + i}
740
- className="auto-input"
741
- value={pr.name}
742
- onChange={(e) =>
743
- edit(setPreds)(
744
- preds.map((q, j) => (j === i ? { ...q, name: e.target.value } : q))
745
- )
746
- }
747
- >
748
- {/*
749
- The stored value is ALWAYS an option β€” see the note on the
750
- automation-column picker. A select whose value matches no option
751
- renders the first one, which silently changes what a Save writes.
752
- */}
753
- {pr.name && !(discover?.fields || []).includes(pr.name) ? (
754
- <option value={pr.name}>{pr.name}</option>
755
- ) : null}
756
- {(discover?.fields || []).map((f) => (
757
- <option key={f} value={f}>
758
- {f}
759
- {(discover?.lead || []).includes(f) ? " (has values)" : ""}
760
- </option>
761
- ))}
762
- </select>
763
- </div>
764
- <div className="auto-field">
765
- <label htmlFor={"auto-pred-o-" + i}>Comparison</label>
766
- <select
767
- id={"auto-pred-o-" + i}
768
- className="auto-input"
769
- value={pr.operator}
770
- onChange={(e) =>
771
- edit(setPreds)(
772
- preds.map((q, j) =>
773
- j === i ? { ...q, operator: e.target.value } : q
774
- )
775
- )
776
- }
777
- >
778
- {pr.operator && !(discover?.operators || []).includes(pr.operator) ? (
779
- <option value={pr.operator}>{pr.operator}</option>
780
- ) : null}
781
- {(discover?.operators || []).map((o) => (
782
- <option key={o} value={o}>
783
- {o}
784
- </option>
785
- ))}
786
- </select>
787
- </div>
788
- {(discover?.nullaryOperators || []).includes(pr.operator) ? null : (
789
- <div className="auto-field">
790
- <label htmlFor={"auto-pred-v-" + i}>Value</label>
791
- <input
792
- id={"auto-pred-v-" + i}
793
- className="auto-input"
794
- value={pr.value === undefined ? "" : String(pr.value)}
795
- onChange={(e) =>
796
- edit(setPreds)(
797
- preds.map((q, j) => (j === i ? { ...q, value: e.target.value } : q))
798
- )
799
- }
800
- />
801
- </div>
802
- )}
803
- <div className="auto-field">
804
- <label htmlFor={"auto-pred-x-" + i}>&nbsp;</label>
805
- <button
806
- id={"auto-pred-x-" + i}
807
- type="button"
808
- className="auto-btn"
809
- disabled={preds.length < 2}
810
- onClick={() => edit(setPreds)(preds.filter((_q, j) => j !== i))}
811
- >
812
- Remove
813
- </button>
814
- </div>
815
- </div>
816
- ))}
817
- <div className="auto-head-actions">
818
- <button
819
- type="button"
820
- className="auto-btn"
821
- onClick={() =>
822
- edit(setPreds)([
823
- ...preds,
824
- // ⚠ A NEW CONDITION MUST BE SAVEABLE THE MOMENT IT APPEARS (item 8,
825
- // same defect as the create form's hardcoded default). This appended
826
- // `{biography includes ""}` β€” a value-less comparison that
827
- // `clean_predicates` refuses outright β€” so adding a condition and
828
- // pressing Save returned "give a value to compare 'biography'
829
- // against" for a condition the user had not finished writing. A
830
- // NULLARY operator needs no value, so the row is valid on arrival
831
- // and narrows the search rather than blocking it.
832
- { name: "biography", operator: "is_not_null" },
833
- ])
834
- }
835
- >
836
- Add a condition
837
- </button>
838
- <div className="auto-field">
839
- <label htmlFor="auto-joinop">Match</label>
840
- <select
841
- id="auto-joinop"
842
- className="auto-input"
843
- value={joinOp}
844
- onChange={(e) => edit(setJoinOp)(e.target.value)}
845
- >
846
- <option value="and">All of them</option>
847
- <option value="or">Any of them</option>
848
- </select>
849
- </div>
850
- </div>
851
- <p className="auto-hint">
852
- Fields marked <em>has values</em> are the ones we have actually seen carrying
853
- data. The others can be searched, but were empty on every profile we have
854
- looked at β€” and a condition on an empty field returns nothing while looking
855
- exactly like &ldquo;no such accounts exist&rdquo;.
856
- </p>
857
- <p className="auto-hint">
858
- Narrow conditions matter more than a small limit. The search reads the whole
859
- corpus either way, so a broad condition is slow and expensive however few rows
860
- you ask to keep. A search normally takes about twenty minutes; a run that
861
- finds one still going says so and the next run collects it.
862
- </p>
863
-
864
- <h3>What it costs</h3>
865
- <div className="auto-head-actions">
866
- <button
867
- type="button"
868
- className="auto-btn"
869
- onClick={() => {
870
- void discoverEstimate(recordsLimit)
871
- .then(setEstimate)
872
- .catch(() => setEstimate(null));
873
- }}
874
- >
875
- Estimate this search
876
- </button>
877
- </div>
878
- {estimate ? (
879
- <p className="auto-hint">
880
- About <strong>${estimate.usd}</strong> for {estimate.records} profiles, at $
881
- {estimate.unitUsd} each.{" "}
882
- {/*
883
- THE CAVEAT IS NOT OPTIONAL. The vendor never quotes a price before a run
884
- and this deployment cannot read its own balance, so presenting this as a
885
- billed figure would be inventing a measurement.
886
- */}
887
- <strong>This is an estimate</strong> β€” {estimate.note}.
888
- </p>
889
- ) : null}
890
- </>
891
- ) : null}
892
-
893
- {node.panel === "write" ? (
894
- <>
895
- {kind === "scrape_db" ? (
896
- <div className="auto-field">
897
- <label htmlFor="auto-tlabel">Database name</label>
898
- <input
899
- id="auto-tlabel"
900
- className="auto-input"
901
- value={targetLabel}
902
- placeholder="S&P 500 companies"
903
- onChange={(e) => edit(setTargetLabel)(e.target.value)}
904
- />
905
- </div>
906
- ) : kind === "discover_instagram" ? (
907
- <p className="auto-hint">
908
- Matches are collected into{" "}
909
- <code>{discover?.table || "ut_ig_candidates"}</code>, upserted by handle β€” so
910
- re-finding an account costs nothing and its <em>Times found</em> count grows.{" "}
911
- <strong>Nothing found is ever tracked automatically.</strong> Tick the ones
912
- you want; a later search can never un-tick them.
913
- </p>
914
- ) : (
915
- <p className="auto-hint">
916
- Each pull appends a timestamped row to <code>ut_ig_snapshots</code> and, when
917
- the post-engagement step is on, one per post to{" "}
918
- <code>ut_ig_post_snapshots</code> β€” so the history is a time series you can
919
- filter by date rather than a single current value.{" "}
920
- <code>ut_ig_posts</code> holds one row per post, ever.
921
- </p>
922
- )}
923
- <p className="auto-hint">
924
- Turning this step off makes the automation a <strong>dry run</strong>: it
925
- reads everything and reports exactly what it would have written, without
926
- creating or changing a single row.
927
- </p>
928
- {kind === "field_instagram" ? (
929
- <p className="auto-hint">
930
- {/*
931
- ⚠ "Writes nothing" and "costs nothing" are DIFFERENT CLAIMS, and only the
932
- first one is true. A dry run still READS β€” so with the paid steps on it
933
- bills exactly what a real run bills. Saying so here is the only place a
934
- user finds out before the invoice.
935
- */}
936
- A dry run still <strong>reads</strong>. With the Bright Data step on it
937
- costs what a real run costs, and with post engagement on that is one
938
- charged record per post. Turn those steps off too if you want a free
939
- rehearsal.
940
- </p>
941
- ) : null}
942
- <p className="auto-hint">
943
- A row that stops appearing at the source is counted and kept, never deleted.
944
- </p>
945
- </>
946
- ) : null}
947
- </>
948
- ) : (
949
- <>
950
- <div className="auto-panel-head">
951
- <h2>Run history</h2>
952
- </div>
953
- {!automation.runs?.length ? (
954
- <p className="auto-note">
955
- It has not run yet. Press Run now, or switch on the Trigger step.
956
- </p>
957
- ) : (
958
- <ol className="auto-runs">
959
- {automation.runs.map((r) => (
960
- <li key={r.ts} className={"auto-run is-" + (r.ok ? "ok" : "error")}>
961
- <button
962
- type="button"
963
- className="auto-run-head"
964
- onClick={() => void openDrill(r)}
965
- aria-expanded={drillFor === r.ts}
966
- >
967
- <span className="auto-run-ts">{r.ts.replace("T", " ")}</span>
968
- <span className="auto-run-summary">{r.summary}</span>
969
- </button>
970
- <div className="auto-counts">
971
- {COUNT_LABELS.filter(([k]) => typeof r.counts?.[k] === "number").map(
972
- ([k, label]) => (
973
- <span
974
- key={k}
975
- className={
976
- "auto-count" + (k === "capped" && r.counts[k] ? " is-warn" : "")
977
- }
978
- >
979
- <b>{r.counts[k]}</b> {label}
980
- </span>
981
- )
982
- )}
983
- </div>
984
- {drillFor === r.ts && drill ? (
985
- <div className="auto-drill">
986
- <p className="auto-hint">
987
- The rows this run touched in {drill.label}
988
- {drill.truncated ? " (first 200)" : ""}.
989
- </p>
990
- <div className="auto-drill-scroll">
991
- <table className="auto-table">
992
- <thead>
993
- <tr>
994
- {drill.fields.map((f) => (
995
- <th key={f.key}>{f.label}</th>
996
- ))}
997
- </tr>
998
- </thead>
999
- <tbody>
1000
- {drill.rows.slice(0, 50).map((row) => (
1001
- <tr key={String(row.id)}>
1002
- {drill.fields.map((f) => (
1003
- <td key={f.key}>{String(row[f.key] ?? "")}</td>
1004
- ))}
1005
- </tr>
1006
- ))}
1007
- </tbody>
1008
- </table>
1009
- </div>
1010
- </div>
1011
- ) : null}
1012
- </li>
1013
- ))}
1014
- </ol>
1015
- )}
1016
- <p className="auto-hint">
1017
- Click any step to see and change what it does.
1018
- </p>
1019
- </>
1020
- )}
1021
- </aside>
1022
- </div>
1023
- </div>
1024
- );
1025
- }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // automation/AutomationDetail.tsx β€” one automation, as a flow you can walk.
3
+ //
4
+ // THE SHAPE (wave-21 R9, replacing the W19 canvas): the automation is a column of
5
+ // NUMBERED STEPS, trigger first, and the right-hand panel shows the configuration
6
+ // of whichever step you clicked. The two halves answer different questions and
7
+ // neither used to be answerable at a glance β€” the steps answer "what does this
8
+ // thing do, in what order, and which step went wrong last night", the panel
9
+ // answers "what exactly is step 3 configured to do". The canvas answered the
10
+ // first question as a SHAPE; the engine executes a list, and a list is what the
11
+ // owner asked to read.
12
+ //
13
+ // ONE CONTROL PER FACT. A step's SWITCH is the only way to turn it on or off; the
14
+ // panel never carries a second checkbox for the same flag. STEP 1 IS THE ONE
15
+ // EXCEPTION AND IT IS THE SAME RULE: the trigger's picker IS its on/off, so the
16
+ // panel has no schedule face at all any more. Two controls for one boolean is how
17
+ // a UI starts disagreeing with itself.
18
+ //
19
+ // EVERY COUNT DRILLS TO ROWS. A run that says "412 updated" opens the 412
20
+ // ([[no-unverifiable-aggregates]]) β€” a number with no way back to its records is
21
+ // what this codebase treats as a defect rather than a summary.
22
+ // ---------------------------------------------------------------------------
23
+ import { useCallback, useEffect, useState } from "react";
24
+
25
+ import AutomationBoard from "./AutomationBoard";
26
+ import AutomationFind from "./AutomationFind";
27
+ import AutomationSteps from "./AutomationSteps";
28
+ import AutomationTrigger from "./AutomationTrigger";
29
+ import type {
30
+ Automation,
31
+ AutomationKind,
32
+ Board,
33
+ BoardStage,
34
+ GraphNode,
35
+ OAuthStatus,
36
+ Predicate,
37
+ RunEntry,
38
+ RunRows,
39
+ DiscoverEstimate,
40
+ DiscoverVocab,
41
+ SourcePreview,
42
+ TickState,
43
+ TriggerOption,
44
+ UserTable,
45
+ } from "./automationApi";
46
+ import {
47
+ AutomationError,
48
+ COUNT_LABELS,
49
+ deleteAutomation,
50
+ discoverEstimate,
51
+ fieldKeyFor,
52
+ getBoard,
53
+ listTables,
54
+ moveCard,
55
+ oauthStatus,
56
+ patchAutomation,
57
+ previewSource,
58
+ runAutomation,
59
+ runRows,
60
+ toggleNode,
61
+ } from "./automationApi";
62
+
63
+ interface Props {
64
+ automation: Automation;
65
+ kinds: { key: AutomationKind; label: string }[];
66
+ /** The server's schedule vocabulary, forwarded to Step 1's Custom face. */
67
+ cronPresets: { cron: string; label: string }[];
68
+ paidReady: boolean;
69
+ /** The server-declared discovery vocabulary (absent until the list loads). */
70
+ discover?: DiscoverVocab;
71
+ /** The server's trigger vocabulary (C3). Absent until the engine ships it. */
72
+ triggers?: TriggerOption[];
73
+ /**
74
+ * Can a schedule fire here? `null` = the server did not say (C6 amendment #1 is not live
75
+ * yet) β€” a REQUIRED key so an unmounted prop fails `tsc` rather than silently reading as
76
+ * "off", which would make Step 1 state a measurement nobody made.
77
+ */
78
+ tick: TickState | null;
79
+ onSaved: (id?: string) => void | Promise<void>;
80
+ onDeleted: () => void | Promise<void>;
81
+ }
82
+
83
+ /**
84
+ * The run-state chip's WORDS. The chip printed the stored enum straight β€” a header
85
+ * reading "ok" beside the automation's name, which is a value from a state machine
86
+ * rather than a sentence anybody would write. Sentence case, and "Succeeded"/"Failed"
87
+ * rather than "ok"/"error" so the chip agrees with the rail's own tooltip, which has
88
+ * always said "Last run succeeded".
89
+ */
90
+ const STATE_LABELS: Record<string, string> = {
91
+ idle: "Not run yet",
92
+ running: "Running",
93
+ ok: "Succeeded",
94
+ partial: "Partial",
95
+ error: "Failed",
96
+ };
97
+
98
+ interface ColumnPlan {
99
+ column: string;
100
+ include: boolean;
101
+ key: string;
102
+ }
103
+
104
+ export default function AutomationDetail({
105
+ automation,
106
+ kinds,
107
+ cronPresets,
108
+ paidReady,
109
+ discover,
110
+ triggers,
111
+ tick,
112
+ onSaved,
113
+ onDeleted,
114
+ }: Props) {
115
+ const cfg = (automation.config || {}) as Record<string, string | number | boolean>;
116
+ const kind = automation.kind;
117
+
118
+ const [name, setName] = useState(automation.name || "");
119
+ const [cron, setCron] = useState(automation.schedule?.cron || "0 6 * * *");
120
+ const [message, setMessage] = useState("");
121
+ const [problem, setProblem] = useState("");
122
+ const [saving, setSaving] = useState(false);
123
+ const [touched, setTouched] = useState(false);
124
+ const [busyNode, setBusyNode] = useState("");
125
+ const [triggerBusy, setTriggerBusy] = useState(false);
126
+ const [selected, setSelected] = useState("");
127
+
128
+ // --- the board (C1)
129
+ const [board, setBoard] = useState<Board | null>(null);
130
+ const [movingRow, setMovingRow] = useState("");
131
+ const [oauth, setOauth] = useState<OAuthStatus | null>(null);
132
+ /**
133
+ * ⚠ "SHOW ME THE CRON" IS A VIEW CHOICE, NOT A SCHEDULE CHANGE β€” and forgetting that once
134
+ * made the Custom option DEAD. Everything else on the trigger face is derived from the
135
+ * stored cron, so picking "Custom (cron)" wrote… the same cron, which `readCron` read back
136
+ * as "every Wednesday" and the select snapped straight back. It lives HERE, above the two
137
+ * frames, so switching between board and steps does not lose it.
138
+ */
139
+ const [showCron, setShowCron] = useState(false);
140
+
141
+ // --- scrape_db half
142
+ const [url, setUrl] = useState(String(cfg.url || ""));
143
+ const [extract, setExtract] = useState(String(cfg.extract || "table"));
144
+ const [tableIndex, setTableIndex] = useState(Number(cfg.tableIndex || 0));
145
+ const [targetLabel, setTargetLabel] = useState(String(cfg.targetLabel || ""));
146
+ const [preview, setPreview] = useState<SourcePreview | null>(null);
147
+ const [reading, setReading] = useState(false);
148
+ const [plan, setPlan] = useState<ColumnPlan[]>(() =>
149
+ Object.entries((automation.config as { fieldMap?: Record<string, string> })?.fieldMap || {})
150
+ .map(([column, key]) => ({ column, include: true, key }))
151
+ );
152
+ const [keyField, setKeyField] = useState(String(cfg.keyField || ""));
153
+
154
+ // --- field_instagram half
155
+ const [tables, setTables] = useState<UserTable[]>([]);
156
+ const [targetTable, setTargetTable] = useState(String(cfg.targetTable || ""));
157
+ const [fieldKey, setFieldKey] = useState(String(cfg.fieldKey || ""));
158
+ const [urlField, setUrlField] = useState(String(cfg.urlField || ""));
159
+ const [maxPosts, setMaxPosts] = useState(Number(cfg.maxPosts || 24));
160
+
161
+ // --- discover_instagram half (R7)
162
+ const [recordsLimit, setRecordsLimit] = useState(Number(cfg.recordsLimit || 25));
163
+ const [joinOp, setJoinOp] = useState(String(cfg.operator || "and"));
164
+ const [preds, setPreds] = useState<Predicate[]>(() => {
165
+ const stored = (automation.config as { predicates?: Predicate[] })?.predicates;
166
+ return stored && stored.length
167
+ ? stored.map((p) => ({ ...p }))
168
+ : [{ name: "followers", operator: ">=", value: 10000 }];
169
+ });
170
+ const [estimate, setEstimate] = useState<DiscoverEstimate | null>(null);
171
+
172
+ // --- run history drill
173
+ const [drill, setDrill] = useState<RunRows | null>(null);
174
+ const [drillFor, setDrillFor] = useState("");
175
+
176
+ useEffect(() => {
177
+ const ac = new AbortController();
178
+ listTables(ac.signal)
179
+ .then((r) => setTables(r.tables))
180
+ .catch(() => setTables([]));
181
+ return () => ac.abort();
182
+ }, []);
183
+
184
+ /**
185
+ * The board, refetched whenever the automation itself is reloaded.
186
+ *
187
+ * ⚠ A RUN MOVES CARDS, so the board is polled while one is in flight β€” the same
188
+ * `anyRunning` reasoning the surface's rail uses: a fixed interval would be a
189
+ * request every few seconds forever for a page whose contents change a handful of
190
+ * times a day, and no polling at all would leave a finished run's promotions
191
+ * invisible until somebody clicked away and back.
192
+ */
193
+ const loadBoard = useCallback(
194
+ async (abort?: AbortSignal) => {
195
+ try {
196
+ const r = await getBoard(automation.id, abort);
197
+ setBoard(r.board);
198
+ } catch (e) {
199
+ if ((e as Error)?.name === "AbortError") return;
200
+ // ⚠ NOT A BANNER. `/board` is absent on a server older than this client, and
201
+ // the honest answer to that is the numbered steps β€” which are a complete
202
+ // surface, not a degraded one. An error card here would announce a fault to
203
+ // a user who has nothing to do about it and can see the flow anyway.
204
+ setBoard(null);
205
+ }
206
+ },
207
+ [automation.id]
208
+ );
209
+
210
+ /**
211
+ * ⚠ SCALAR DEPENDENCIES ONLY, and this cost a real defect. The first version also
212
+ * depended on `automation.graph`, which is a fresh OBJECT on every list reload β€” so every
213
+ * save, every switch and every poll re-ran this effect, and a card move raced its own
214
+ * refetch: `moveOne` set the server's fresh board, `onSaved` reloaded the list, the new
215
+ * `graph` identity fired this effect, and the pre-move board landed back on screen. The
216
+ * lane count went back to what it had been, which reads exactly like "the move did not
217
+ * work". Caught by the probe asserting the count AFTER the click.
218
+ *
219
+ * So this effect owns mount and identity; every mutation asks for the board EXPLICITLY,
220
+ * where the ordering is visible.
221
+ */
222
+ useEffect(() => {
223
+ const ac = new AbortController();
224
+ void loadBoard(ac.signal);
225
+ return () => ac.abort();
226
+ }, [loadBoard, automation.status?.lastRunAt]);
227
+
228
+ useEffect(() => {
229
+ if (!automation.running) return undefined;
230
+ const t = window.setInterval(() => void loadBoard(), 2500);
231
+ return () => window.clearInterval(t);
232
+ }, [automation.running, loadBoard]);
233
+
234
+ useEffect(() => {
235
+ const ac = new AbortController();
236
+ oauthStatus(ac.signal)
237
+ .then(setOauth)
238
+ // Unconfigured OAuth is FAIL-CLOSED, not an error (C5): no status means no
239
+ // connection, which the trigger face already states as "not set up yet".
240
+ .catch(() => setOauth(null));
241
+ return () => ac.abort();
242
+ }, []);
243
+
244
+ const table = tables.find((t) => t.key === targetTable) || null;
245
+
246
+ /**
247
+ * WHICH CONFIG PANEL IS OPEN β€” and the join is on `panel`, never on id equality.
248
+ *
249
+ * C1's amendment (2026-08-05) is explicit: a stage backed by an engine node
250
+ * carries that node's `panel` VERBATIM, review stages carry `"review"`. Reading
251
+ * the key off whichever surface is mounted keeps ONE panel implementation for
252
+ * both frames, and keeps the board from having to know what a "capture" panel is.
253
+ */
254
+ const boardStage: BoardStage | null =
255
+ (board?.stages || []).find((s) => s.id === selected) || null;
256
+ const graphNode: GraphNode | null =
257
+ (automation.graph?.nodes || []).find((n) => n.id === selected) || null;
258
+ const panelOpen = !!(boardStage || graphNode);
259
+ const panelKey = boardStage ? boardStage.panel : graphNode?.panel || "";
260
+ const panelTitle = boardStage ? boardStage.label : graphNode?.title || "";
261
+ const panelOn = boardStage ? boardStage.enabled : !!graphNode?.enabled;
262
+ /**
263
+ * ⭐ THE STAGE'S OWN SENTENCE, from the server. A's board composes a `detail` for every
264
+ * stage ("Cards wait here for a person β€” moving one on IS the tracked promotion",
265
+ * "Rejected candidates stay here β€” a kept decision, not a delete"), and it is the
266
+ * engine's description of its own behaviour β€” which is both better than a client
267
+ * paraphrase and incapable of going stale against it. It is also what gives the appended
268
+ * stages (`tracked`, `declined`, `lanes`) a panel at all without this file inventing one
269
+ * per key: a stage with no dedicated face still says what it is.
270
+ */
271
+ const panelDetail = boardStage ? boardStage.detail : graphNode?.detail || "";
272
+
273
+ /**
274
+ * WHAT STARTS THIS ONE, as a key. The server's stored trigger when it ships one;
275
+ * otherwise derived from the only two shapes a definition can express today.
276
+ * Derived rather than defaulted: `schedule.enabled` IS the answer on today's
277
+ * engine, so this is a reading of stored state, not a guess about it.
278
+ */
279
+ const triggerKey =
280
+ automation.trigger?.key || (automation.schedule?.enabled ? "schedule" : "manual");
281
+
282
+ const edit = <T,>(set: (v: T) => void) => (v: T) => {
283
+ setTouched(true);
284
+ set(v);
285
+ };
286
+
287
+ const readPage = useCallback(async () => {
288
+ setReading(true);
289
+ setProblem("");
290
+ try {
291
+ const p = await previewSource(url, extract, tableIndex);
292
+ setPreview(p);
293
+ if (!p.ok) {
294
+ setProblem(p.note || `That page answered ${p.status}.`);
295
+ return;
296
+ }
297
+ // Seed the plan from what the page ACTUALLY offers, keeping any mapping the
298
+ // user already made for a column that is still there β€” re-reading a page
299
+ // must not throw away the work of mapping it.
300
+ setPlan((prev) => {
301
+ const had = new Map(prev.map((c) => [c.column, c]));
302
+ return p.columns.map((column) => {
303
+ const before = had.get(column);
304
+ return {
305
+ column,
306
+ include: before ? before.include : true,
307
+ key: before ? before.key : fieldKeyFor(column),
308
+ };
309
+ });
310
+ });
311
+ setKeyField((k) =>
312
+ k && p.columns.some((c) => fieldKeyFor(c) === k) ? k : fieldKeyFor(p.columns[0] || "")
313
+ );
314
+ if (!targetLabel) setTargetLabel(p.title || "Scraped table");
315
+ setTouched(true);
316
+ setMessage(
317
+ `Read ${p.rowCount} rows and ${p.columns.length} columns` +
318
+ (p.tableCount && p.tableCount > 1 ? ` (of ${p.tableCount} tables on the page)` : "")
319
+ );
320
+ } catch (e) {
321
+ setProblem(e instanceof AutomationError ? e.message : "That page could not be read.");
322
+ } finally {
323
+ setReading(false);
324
+ }
325
+ }, [url, extract, tableIndex, targetLabel]);
326
+
327
+ /**
328
+ * ⚠ The switch flags (`tier`, `noFallback`, `dryRun`) are DELIBERATELY absent.
329
+ * They are node switches, not panel fields, and the server keeps the stored
330
+ * value for any flag a config omits β€” so a Save from here can never quietly
331
+ * turn the paid rung off. (`clean_config`'s `flag()`, asserted in section N.)
332
+ */
333
+ const buildConfig = (): Record<string, unknown> => {
334
+ if (kind === "scrape_db") {
335
+ const fieldMap: Record<string, string> = {};
336
+ for (const c of plan) if (c.include && c.key) fieldMap[c.column] = c.key;
337
+ return {
338
+ url,
339
+ extract,
340
+ tableIndex,
341
+ fieldMap,
342
+ keyField,
343
+ targetTable: String(cfg.targetTable || ""),
344
+ targetLabel,
345
+ };
346
+ }
347
+ if (kind === "discover_instagram") {
348
+ return {
349
+ recordsLimit,
350
+ operator: joinOp,
351
+ predicates: preds.filter((p) => p.name && p.operator),
352
+ targetTable: String(cfg.targetTable || ""),
353
+ };
354
+ }
355
+ return { targetTable, fieldKey, urlField, maxPosts };
356
+ };
357
+
358
+ const persist = async (announce = true, sched?: { cron: string; enabled: boolean }) => {
359
+ const res = await patchAutomation(automation.id, {
360
+ name,
361
+ kind,
362
+ config: buildConfig(),
363
+ schedule: sched || { cron, enabled: !!automation.schedule?.enabled },
364
+ });
365
+ setTouched(false);
366
+ if (announce) setMessage("Saved.");
367
+ return res.automation.id;
368
+ };
369
+
370
+ /**
371
+ * Step 1's controls persist IMMEDIATELY (R9). A trigger you have to remember to Save is the
372
+ * same defect as a switch you have to remember to Save β€” the node switches next to it are
373
+ * immediate, and two save disciplines in one column is how a user ends up with an automation
374
+ * that says "every Monday" and runs every day.
375
+ *
376
+ * ⚠ The CUSTOM CRON STRING is the exception, and deliberately: it is free text, so persisting
377
+ * per keystroke would PATCH a half-typed schedule five times. It marks the editor touched and
378
+ * rides the header's Save β€” and because every immediate write goes through `persist()`, an
379
+ * unsaved cron edit is written with it rather than being discarded by the reload.
380
+ */
381
+ const saveTrigger = async (next: { cron: string; enabled: boolean }) => {
382
+ setTriggerBusy(true);
383
+ setProblem("");
384
+ setMessage("");
385
+ setCron(next.cron);
386
+ try {
387
+ await patchAutomation(automation.id, {
388
+ name,
389
+ kind,
390
+ config: buildConfig(),
391
+ schedule: { cron: next.cron, enabled: next.enabled },
392
+ });
393
+ setTouched(false);
394
+ await onSaved(automation.id);
395
+ await loadBoard();
396
+ } catch (e) {
397
+ setProblem(e instanceof AutomationError ? e.message : "That schedule was not saved.");
398
+ } finally {
399
+ setTriggerBusy(false);
400
+ }
401
+ };
402
+
403
+ /**
404
+ * Pick WHAT STARTS this automation (C3).
405
+ *
406
+ * ⚠ TWO WRITES IN ONE PATCH, on purpose. `trigger: {key}` is the shape this wave
407
+ * introduces; `schedule.enabled` is what today's engine actually reads, and the
408
+ * two must agree or a picker that says "manual" would leave a live cron behind
409
+ * it. The schedule half is derived from the key rather than remembered β€” the
410
+ * trigger IS the on/off, which is the one-control-per-fact rule this file's
411
+ * header states.
412
+ *
413
+ * ⚠ ASSUMPTION, STATED: the engine session confirms the write shape in the wave
414
+ * mailbox. An engine that ignores an unknown `trigger` key still gets the
415
+ * schedule half right, so the fallback is correct rather than merely harmless.
416
+ */
417
+ const pickTrigger = async (key: string) => {
418
+ setTriggerBusy(true);
419
+ setProblem("");
420
+ setMessage("");
421
+ if (key !== "schedule") setShowCron(false);
422
+ try {
423
+ await patchAutomation(automation.id, {
424
+ name,
425
+ kind,
426
+ config: buildConfig(),
427
+ trigger: { key },
428
+ schedule: { cron, enabled: key === "schedule" },
429
+ });
430
+ setTouched(false);
431
+ await onSaved(automation.id);
432
+ await loadBoard();
433
+ } catch (e) {
434
+ setProblem(e instanceof AutomationError ? e.message : "That trigger was not saved.");
435
+ } finally {
436
+ setTriggerBusy(false);
437
+ }
438
+ };
439
+
440
+ /**
441
+ * Move ONE record along the flow β€” R1's promotion, and on the discovery flow it
442
+ * IS the `tracked` tick.
443
+ *
444
+ * β›” THE SERVER DECIDES, and its refusal is printed VERBATIM. This posts the drop
445
+ * it was given; a client that pre-judged legality would be a second copy of a
446
+ * permission rule, and the two copies disagreeing leaves a card that will not
447
+ * move for a reason nobody can read.
448
+ */
449
+ const moveOne = async (rowId: string, to: string) => {
450
+ setMovingRow(rowId);
451
+ setProblem("");
452
+ setMessage("");
453
+ try {
454
+ const r = await moveCard(automation.id, rowId, to);
455
+ setBoard(r.board);
456
+ // The move writes a record, and a run's counts/history follow it β€” so the
457
+ // automation itself is reloaded too rather than leaving the header stale.
458
+ await onSaved(automation.id);
459
+ } catch (e) {
460
+ setProblem(e instanceof AutomationError ? e.message : "That card was not moved.");
461
+ // ⚠ RE-READ AFTER A REFUSAL. The card did not move, and the surest way to
462
+ // show that is the server's own answer rather than this client's memory of
463
+ // where things were.
464
+ await loadBoard();
465
+ } finally {
466
+ setMovingRow("");
467
+ }
468
+ };
469
+
470
+ const save = async () => {
471
+ setSaving(true);
472
+ setProblem("");
473
+ setMessage("");
474
+ try {
475
+ const id = await persist();
476
+ await onSaved(id);
477
+ await loadBoard();
478
+ } catch (e) {
479
+ setProblem(e instanceof AutomationError ? e.message : "That could not be saved.");
480
+ } finally {
481
+ setSaving(false);
482
+ }
483
+ };
484
+
485
+ /**
486
+ * A node switch is immediate β€” a switch that needs a separate Save is not a
487
+ * switch. Unsaved panel edits are persisted FIRST rather than being discarded
488
+ * by the reload that follows, which is the one way this could lose work.
489
+ */
490
+ const flip = async (nodeId: string) => {
491
+ setBusyNode(nodeId);
492
+ setProblem("");
493
+ setMessage("");
494
+ try {
495
+ if (touched) await persist(false);
496
+ await toggleNode(automation.id, nodeId);
497
+ await onSaved(automation.id);
498
+ // A switch can add or remove a stage, so the board is asked for by name β€” the
499
+ // effect above deliberately no longer watches the graph object (see its note).
500
+ await loadBoard();
501
+ } catch (e) {
502
+ setProblem(e instanceof AutomationError ? e.message : "That step was not changed.");
503
+ } finally {
504
+ setBusyNode("");
505
+ }
506
+ };
507
+
508
+ const start = async () => {
509
+ setProblem("");
510
+ try {
511
+ await runAutomation(automation.id);
512
+ setMessage("Started. The node dots follow it.");
513
+ await onSaved(automation.id);
514
+ } catch (e) {
515
+ setProblem(e instanceof AutomationError ? e.message : "It did not start.");
516
+ }
517
+ };
518
+
519
+ const remove = async () => {
520
+ setProblem("");
521
+ try {
522
+ await deleteAutomation(automation.id);
523
+ await onDeleted();
524
+ } catch (e) {
525
+ setProblem(e instanceof AutomationError ? e.message : "It was not deleted.");
526
+ }
527
+ };
528
+
529
+ const openDrill = async (entry: RunEntry) => {
530
+ if (drillFor === entry.ts) {
531
+ setDrill(null);
532
+ setDrillFor("");
533
+ return;
534
+ }
535
+ try {
536
+ const rows = await runRows(automation.id);
537
+ setDrill(rows);
538
+ setDrillFor(entry.ts);
539
+ } catch (e) {
540
+ setProblem(e instanceof AutomationError ? e.message : "Those rows could not be read.");
541
+ }
542
+ };
543
+
544
+ const state = automation.running ? "running" : automation.status?.state || "idle";
545
+
546
+ /**
547
+ * The trigger controls, built ONCE and rendered by whichever frame is mounted.
548
+ * `AutomationTrigger` owns the vocabulary (C3), the cron round-trip and the tick
549
+ * honesty note; this file owns only what a change should WRITE.
550
+ */
551
+ const triggerFace = (
552
+ <AutomationTrigger
553
+ triggers={triggers}
554
+ current={triggerKey}
555
+ cron={cron}
556
+ enabled={!!automation.schedule?.enabled}
557
+ tick={tick}
558
+ nextRunAt={automation.nextRunAt}
559
+ cronPresets={cronPresets}
560
+ busy={triggerBusy}
561
+ onPick={(key) => void pickTrigger(key)}
562
+ onSchedule={(next) => void saveTrigger(next)}
563
+ onCronText={(next) => edit(setCron)(next)}
564
+ oauth={oauth}
565
+ showCron={showCron}
566
+ onShowCron={setShowCron}
567
+ />
568
+ );
569
+
570
+ return (
571
+ <div className="auto-detail">
572
+ <header className="auto-head">
573
+ <div className="auto-head-title">
574
+ <input
575
+ className="auto-name"
576
+ value={name}
577
+ placeholder="Name this automation"
578
+ aria-label="Automation name"
579
+ onChange={(e) => edit(setName)(e.target.value)}
580
+ />
581
+ <span className={`auto-chip is-${state}`}>
582
+ {STATE_LABELS[state] || state}
583
+ </span>
584
+ <span className="auto-kindtag">
585
+ {kinds.find((k) => k.key === kind)?.label || kind}
586
+ </span>
587
+ </div>
588
+ <div className="auto-head-actions">
589
+ <button
590
+ type="button"
591
+ className="auto-btn"
592
+ disabled={!!automation.running}
593
+ onClick={() => void start()}
594
+ >
595
+ {automation.running ? "Running…" : "Run now"}
596
+ </button>
597
+ <button
598
+ type="button"
599
+ className="auto-btn is-primary"
600
+ disabled={saving || !name.trim()}
601
+ onClick={() => void save()}
602
+ >
603
+ {saving ? "Saving…" : "Save"}
604
+ </button>
605
+ <button type="button" className="auto-btn is-danger" onClick={() => void remove()}>
606
+ Delete
607
+ </button>
608
+ </div>
609
+ </header>
610
+
611
+ {problem ? (
612
+ <div className="auto-banner is-error" role="alert">
613
+ {problem}
614
+ </div>
615
+ ) : null}
616
+ {message ? (
617
+ <div className="auto-banner is-ok" role="status">
618
+ {message}
619
+ </div>
620
+ ) : null}
621
+
622
+ <div className="auto-work">
623
+ {/*
624
+ TWO FRAMES, ONE TRIGGER FACE. The board is what the owner asked for (R1) and
625
+ the numbered steps are what a server that does not answer `/board` can still
626
+ describe honestly β€” neither is a degraded version of the other, and the
627
+ trigger controls are the SAME ELEMENT in both, so the cron round-trip and the
628
+ tick honesty note exist exactly once.
629
+ */}
630
+ {board ? (
631
+ <div className="autob-flow">
632
+ <div className="autob-triggerbar">
633
+ <span className="autob-triggerbar-tag">Trigger</span>
634
+ {triggerFace}
635
+ </div>
636
+ <AutomationBoard
637
+ board={board}
638
+ selected={selected}
639
+ onSelect={setSelected}
640
+ onToggle={(id) => void flip(id)}
641
+ busyStage={busyNode}
642
+ onMove={(rowId, to) => void moveOne(rowId, to)}
643
+ movingRow={movingRow}
644
+ />
645
+ </div>
646
+ ) : (
647
+ <AutomationSteps
648
+ graph={automation.graph}
649
+ selected={selected}
650
+ onSelect={setSelected}
651
+ onToggle={(id) => void flip(id)}
652
+ busyNode={busyNode}
653
+ triggerFace={triggerFace}
654
+ triggerOff={triggerKey === "manual"}
655
+ />
656
+ )}
657
+
658
+ <aside
659
+ className="auto-panel"
660
+ aria-label={panelOpen ? `${panelTitle} settings` : "Run history"}
661
+ >
662
+ {panelOpen ? (
663
+ <>
664
+ <div className="auto-panel-head">
665
+ <h2>{panelTitle}</h2>
666
+ <button
667
+ type="button"
668
+ className="auto-panel-close"
669
+ aria-label="Back to run history"
670
+ title="Back to run history"
671
+ onClick={() => setSelected("")}
672
+ >
673
+ <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
674
+ <path
675
+ d="M4 4l8 8M12 4l-8 8"
676
+ stroke="currentColor"
677
+ strokeWidth="1.5"
678
+ strokeLinecap="round"
679
+ />
680
+ </svg>
681
+ </button>
682
+ </div>
683
+ {!panelOn ? (
684
+ <p className="auto-note is-off">
685
+ It is switched off. Its own card carries the switch that turns it back on.
686
+ </p>
687
+ ) : null}
688
+
689
+ {/*
690
+ The server's own line about this stage, when it sent one. A stage like
691
+ `tracked` or `declined` HAS no settings β€” it is a place, not a step β€” and
692
+ what it needs is a sentence, which the engine already writes.
693
+ */}
694
+ {panelDetail ? <p className="auto-hint">{panelDetail}</p> : null}
695
+ {!panelDetail && panelKey === "review" ? (
696
+ <p className="auto-hint">
697
+ Records wait here until someone moves them on. Moving a card is the
698
+ decision itself β€” nothing advances on its own.
699
+ </p>
700
+ ) : null}
701
+
702
+ {/*
703
+ WHO DECIDED, AND WHEN. A promotion out of a review gate is a person's
704
+ judgement written into a record, so the gate's panel names them β€” the same
705
+ rule that makes every count in this product drill to its rows. Newest first,
706
+ exactly as the server orders them.
707
+ */}
708
+ {panelKey === "review" && (automation.reviews || []).length ? (
709
+ <>
710
+ <h3>Decisions</h3>
711
+ <ol className="autob-reviews">
712
+ {(automation.reviews || []).slice(0, 12).map((r) => (
713
+ <li key={`${r.ts}-${r.rowId}`} className="autob-review">
714
+ <span className="autob-review-ts">{r.ts.replace("T", " ").slice(0, 16)}</span>
715
+ <span className="autob-review-who">{r.user}</span>
716
+ <span className="autob-review-move">
717
+ {r.from} to {r.to}
718
+ </span>
719
+ </li>
720
+ ))}
721
+ </ol>
722
+ </>
723
+ ) : null}
724
+
725
+ {/*
726
+ β›” THE SCHEDULE FACE IS GONE FROM THIS PANEL (R9), and its absence is the
727
+ point. Step 1 now carries the trigger's on/off AND its shape, so a second
728
+ cron control here would be two controls for one fact β€” the thing this file's
729
+ header forbids, and the way a UI starts disagreeing with itself. The trigger
730
+ step is not selectable for the same reason: there is nothing left to show
731
+ here that the card does not already say.
732
+ */}
733
+
734
+ {panelKey === "source" && kind === "scrape_db" ? (
735
+ <>
736
+ <div className="auto-field">
737
+ <label htmlFor="auto-url">Page URL</label>
738
+ <input
739
+ id="auto-url"
740
+ className="auto-input"
741
+ value={url}
742
+ placeholder="https://en.wikipedia.org/wiki/List_of_S%26P_500_companies"
743
+ onChange={(e) => edit(setUrl)(e.target.value)}
744
+ />
745
+ </div>
746
+ <button
747
+ type="button"
748
+ className="auto-btn"
749
+ disabled={!url.trim() || reading}
750
+ onClick={() => void readPage()}
751
+ >
752
+ {reading ? "Reading…" : "Read the page"}
753
+ </button>
754
+ <div className="auto-field">
755
+ <label htmlFor="auto-extract">Read</label>
756
+ <select
757
+ id="auto-extract"
758
+ className="auto-input"
759
+ value={extract}
760
+ onChange={(e) => edit(setExtract)(e.target.value)}
761
+ >
762
+ <option value="table">An HTML table</option>
763
+ <option value="jsonld">Structured data (JSON-LD)</option>
764
+ </select>
765
+ </div>
766
+ {extract === "table" ? (
767
+ <div className="auto-field">
768
+ <label htmlFor="auto-tidx">Which table</label>
769
+ <input
770
+ id="auto-tidx"
771
+ className="auto-input"
772
+ type="number"
773
+ min={0}
774
+ value={tableIndex}
775
+ onChange={(e) => edit(setTableIndex)(Number(e.target.value) || 0)}
776
+ />
777
+ </div>
778
+ ) : null}
779
+ <p className="auto-hint">
780
+ Public web pages only. Private, loopback and link-local addresses are refused
781
+ β€” including a public URL that redirects to one.
782
+ </p>
783
+ </>
784
+ ) : null}
785
+
786
+ {panelKey === "columns" ? (
787
+ plan.length ? (
788
+ <>
789
+ <p className="auto-hint">
790
+ Pick the key β€” the column that identifies a row. On every re-run, a row
791
+ whose key already exists is updated; a new key is inserted; a key that has
792
+ stopped appearing is counted and kept.
793
+ </p>
794
+ <div className="auto-panel-scroll">
795
+ <table className="auto-table">
796
+ <thead>
797
+ <tr>
798
+ <th>Use</th>
799
+ <th>Source column</th>
800
+ <th>Field key</th>
801
+ <th>Key</th>
802
+ </tr>
803
+ </thead>
804
+ <tbody>
805
+ {plan.map((c, i) => (
806
+ <tr key={c.column}>
807
+ <td>
808
+ <input
809
+ type="checkbox"
810
+ checked={c.include}
811
+ aria-label={`Include ${c.column}`}
812
+ onChange={(e) =>
813
+ edit(setPlan)(
814
+ plan.map((x, j) =>
815
+ j === i ? { ...x, include: e.target.checked } : x
816
+ )
817
+ )
818
+ }
819
+ />
820
+ </td>
821
+ <td className="auto-cell-name">{c.column}</td>
822
+ <td>
823
+ <input
824
+ className="auto-input is-small"
825
+ value={c.key}
826
+ aria-label={`Field key for ${c.column}`}
827
+ onChange={(e) =>
828
+ edit(setPlan)(
829
+ plan.map((x, j) =>
830
+ j === i
831
+ ? { ...x, key: fieldKeyFor(e.target.value) }
832
+ : x
833
+ )
834
+ )
835
+ }
836
+ />
837
+ </td>
838
+ <td>
839
+ <input
840
+ type="radio"
841
+ name="auto-keyfield"
842
+ checked={keyField === c.key && c.include}
843
+ disabled={!c.include}
844
+ aria-label={`Use ${c.column} as the key`}
845
+ onChange={() => edit(setKeyField)(c.key)}
846
+ />
847
+ </td>
848
+ </tr>
849
+ ))}
850
+ </tbody>
851
+ </table>
852
+ </div>
853
+ {preview?.sample?.length ? (
854
+ <p className="auto-hint">
855
+ First row read: {Object.values(preview.sample[0]).slice(0, 4).join(" Β· ")}
856
+ </p>
857
+ ) : null}
858
+ </>
859
+ ) : (
860
+ <p className="auto-note">
861
+ Open the Fetch step and read the page to see what columns it offers.
862
+ </p>
863
+ )
864
+ ) : null}
865
+
866
+ {panelKey === "source" && kind === "field_instagram" ? (
867
+ <>
868
+ <div className="auto-field">
869
+ <label htmlFor="auto-table">Database</label>
870
+ <select
871
+ id="auto-table"
872
+ className="auto-input"
873
+ value={targetTable}
874
+ onChange={(e) => {
875
+ edit(setTargetTable)(e.target.value);
876
+ setFieldKey("");
877
+ setUrlField("");
878
+ }}
879
+ >
880
+ <option value="">Choose a database…</option>
881
+ {targetTable && !tables.some((t) => t.key === targetTable) ? (
882
+ <option value={targetTable}>{targetTable} (not visible to you)</option>
883
+ ) : null}
884
+ {tables.map((t) => (
885
+ <option key={t.key} value={t.key}>
886
+ {t.label} ({t.rowCount} {t.rowCount === 1 ? "row" : "rows"})
887
+ </option>
888
+ ))}
889
+ </select>
890
+ </div>
891
+ <div className="auto-field">
892
+ <label htmlFor="auto-urlfield">Profile URL column</label>
893
+ <select
894
+ id="auto-urlfield"
895
+ className="auto-input"
896
+ value={urlField}
897
+ onChange={(e) => edit(setUrlField)(e.target.value)}
898
+ >
899
+ <option value="">The column the field is bound to</option>
900
+ {(table?.fields || []).map((f) => (
901
+ <option key={f.key} value={f.key}>
902
+ {f.label}
903
+ </option>
904
+ ))}
905
+ </select>
906
+ </div>
907
+ <div className="auto-field">
908
+ <label htmlFor="auto-fieldkey">Automation column</label>
909
+ <select
910
+ id="auto-fieldkey"
911
+ className="auto-input"
912
+ value={fieldKey}
913
+ onChange={(e) => edit(setFieldKey)(e.target.value)}
914
+ >
915
+ <option value="">Choose a column…</option>
916
+ {/*
917
+ ⚠ THE STORED VALUE IS ALWAYS AN OPTION, even when the list
918
+ below does not contain it. A <select> whose `value` matches
919
+ no <option> renders the FIRST one β€” so a column the server
920
+ knows about but this list has not caught up with would look
921
+ like a DIFFERENT column, and the next Save would write that
922
+ different column without anybody choosing it. Showing it as
923
+ "(not in this database)" is the honest version.
924
+ */}
925
+ {fieldKey && !(table?.fields || []).some((f) => f.key === fieldKey) ? (
926
+ <option value={fieldKey}>{fieldKey} (not in this database)</option>
927
+ ) : null}
928
+ {(table?.fields || [])
929
+ .filter((f) => f.type === "automation")
930
+ .map((f) => (
931
+ <option key={f.key} value={f.key}>
932
+ {f.label}
933
+ </option>
934
+ ))}
935
+ </select>
936
+ </div>
937
+ {table && !(table.fields || []).some((f) => f.type === "automation") ? (
938
+ <p className="auto-note">
939
+ That database has no automation column yet. Add one from the grid&rsquo;s
940
+ column menu, then choose it here.
941
+ </p>
942
+ ) : null}
943
+ </>
944
+ ) : null}
945
+
946
+ {panelKey === "capture" ? (
947
+ <>
948
+ <div className="auto-field">
949
+ <label htmlFor="auto-maxposts">Posts per pull</label>
950
+ <input
951
+ id="auto-maxposts"
952
+ className="auto-input"
953
+ type="number"
954
+ min={1}
955
+ max={200}
956
+ value={maxPosts}
957
+ onChange={(e) => edit(setMaxPosts)(Number(e.target.value) || 24)}
958
+ />
959
+ </div>
960
+ <h3>Bright Data β€” the paid rung</h3>
961
+ <p className="auto-hint">
962
+ Exact follower counts and the profile&rsquo;s top posts, and it works from a
963
+ datacenter. Its node&rsquo;s switch turns it on.
964
+ {paidReady
965
+ ? " A key is configured on this deployment."
966
+ : " No key is configured on this deployment yet, so it will report itself blocked and the anonymous rung will answer instead."}
967
+ </p>
968
+ <h3>Post engagement β€” the per-post rung</h3>
969
+ <p className="auto-hint">
970
+ Likes and comments for each post. It is a separate step because it is a
971
+ separate bill: the profile read costs one record, and engagement costs{" "}
972
+ <strong>one record per post</strong>. With it off, the posts database still
973
+ grows but the engagement series does not β€” and no empty rows are appended to
974
+ stand in for the numbers nobody bought.
975
+ </p>
976
+ <h3>Anonymous β€” the free rung</h3>
977
+ <p className="auto-hint">
978
+ No login and no credentials. Instagram blocks datacenter addresses and has
979
+ closed most of its anonymous surface, so this rung is honest rather than
980
+ reliable: counts come from the page&rsquo;s own abbreviations (204K, not
981
+ 204,312) and are marked approximate. Turning it off means{" "}
982
+ <strong>exact numbers or nothing</strong> β€” a run reports blocked rather than
983
+ quietly writing a rounded number.
984
+ </p>
985
+ <p className="auto-hint">
986
+ A pull reports what it actually got: <strong>ok</strong> (profile and posts),{" "}
987
+ <strong>partial</strong> (profile only), or <strong>blocked</strong>. It never
988
+ reports success on nothing.
989
+ </p>
990
+ </>
991
+ ) : null}
992
+
993
+ {panelKey === "find" ? (
994
+ <AutomationFind
995
+ discover={discover}
996
+ recordsLimit={recordsLimit}
997
+ onRecordsLimit={(n) => {
998
+ edit(setRecordsLimit)(n);
999
+ setEstimate(null);
1000
+ }}
1001
+ joinOp={joinOp}
1002
+ onJoinOp={edit(setJoinOp)}
1003
+ preds={preds}
1004
+ onPreds={edit(setPreds)}
1005
+ estimate={estimate}
1006
+ onEstimate={() => {
1007
+ void discoverEstimate(recordsLimit)
1008
+ .then(setEstimate)
1009
+ .catch(() => setEstimate(null));
1010
+ }}
1011
+ />
1012
+ ) : null}
1013
+
1014
+ {panelKey === "write" ? (
1015
+ <>
1016
+ {kind === "scrape_db" ? (
1017
+ <div className="auto-field">
1018
+ <label htmlFor="auto-tlabel">Database name</label>
1019
+ <input
1020
+ id="auto-tlabel"
1021
+ className="auto-input"
1022
+ value={targetLabel}
1023
+ placeholder="S&P 500 companies"
1024
+ onChange={(e) => edit(setTargetLabel)(e.target.value)}
1025
+ />
1026
+ </div>
1027
+ ) : kind === "discover_instagram" ? (
1028
+ <p className="auto-hint">
1029
+ Matches are collected into{" "}
1030
+ <code>{discover?.table || "ut_ig_candidates"}</code>, upserted by handle β€” so
1031
+ re-finding an account costs nothing and its <em>Times found</em> count grows.{" "}
1032
+ <strong>Nothing found is ever tracked automatically.</strong> Tick the ones
1033
+ you want; a later search can never un-tick them.
1034
+ </p>
1035
+ ) : (
1036
+ <p className="auto-hint">
1037
+ Each pull appends a timestamped row to <code>ut_ig_snapshots</code> and, when
1038
+ the post-engagement step is on, one per post to{" "}
1039
+ <code>ut_ig_post_snapshots</code> β€” so the history is a time series you can
1040
+ filter by date rather than a single current value.{" "}
1041
+ <code>ut_ig_posts</code> holds one row per post, ever.
1042
+ </p>
1043
+ )}
1044
+ <p className="auto-hint">
1045
+ Turning this step off makes the automation a <strong>dry run</strong>: it
1046
+ reads everything and reports exactly what it would have written, without
1047
+ creating or changing a single row.
1048
+ </p>
1049
+ {kind === "field_instagram" ? (
1050
+ <p className="auto-hint">
1051
+ {/*
1052
+ ⚠ "Writes nothing" and "costs nothing" are DIFFERENT CLAIMS, and only the
1053
+ first one is true. A dry run still READS β€” so with the paid steps on it
1054
+ bills exactly what a real run bills. Saying so here is the only place a
1055
+ user finds out before the invoice.
1056
+ */}
1057
+ A dry run still <strong>reads</strong>. With the Bright Data step on it
1058
+ costs what a real run costs, and with post engagement on that is one
1059
+ charged record per post. Turn those steps off too if you want a free
1060
+ rehearsal.
1061
+ </p>
1062
+ ) : null}
1063
+ <p className="auto-hint">
1064
+ A row that stops appearing at the source is counted and kept, never deleted.
1065
+ </p>
1066
+ </>
1067
+ ) : null}
1068
+ </>
1069
+ ) : (
1070
+ <>
1071
+ <div className="auto-panel-head">
1072
+ <h2>Run history</h2>
1073
+ </div>
1074
+ {!automation.runs?.length ? (
1075
+ <p className="auto-note">
1076
+ It has not run yet. Press Run now, or give it a trigger.
1077
+ </p>
1078
+ ) : (
1079
+ <ol className="auto-runs">
1080
+ {automation.runs.map((r) => (
1081
+ <li key={r.ts} className={"auto-run is-" + (r.ok ? "ok" : "error")}>
1082
+ <button
1083
+ type="button"
1084
+ className="auto-run-head"
1085
+ onClick={() => void openDrill(r)}
1086
+ aria-expanded={drillFor === r.ts}
1087
+ >
1088
+ <span className="auto-run-ts">{r.ts.replace("T", " ")}</span>
1089
+ <span className="auto-run-summary">{r.summary}</span>
1090
+ </button>
1091
+ <div className="auto-counts">
1092
+ {COUNT_LABELS.filter(([k]) => typeof r.counts?.[k] === "number").map(
1093
+ ([k, label]) => (
1094
+ <span
1095
+ key={k}
1096
+ className={
1097
+ "auto-count" + (k === "capped" && r.counts[k] ? " is-warn" : "")
1098
+ }
1099
+ >
1100
+ <b>{r.counts[k]}</b> {label}
1101
+ </span>
1102
+ )
1103
+ )}
1104
+ </div>
1105
+ {drillFor === r.ts && drill ? (
1106
+ <div className="auto-drill">
1107
+ <p className="auto-hint">
1108
+ The rows this run touched in {drill.label}
1109
+ {drill.truncated ? " (first 200)" : ""}.
1110
+ </p>
1111
+ <div className="auto-drill-scroll">
1112
+ <table className="auto-table">
1113
+ <thead>
1114
+ <tr>
1115
+ {drill.fields.map((f) => (
1116
+ <th key={f.key}>{f.label}</th>
1117
+ ))}
1118
+ </tr>
1119
+ </thead>
1120
+ <tbody>
1121
+ {drill.rows.slice(0, 50).map((row) => (
1122
+ <tr key={String(row.id)}>
1123
+ {drill.fields.map((f) => (
1124
+ <td key={f.key}>{String(row[f.key] ?? "")}</td>
1125
+ ))}
1126
+ </tr>
1127
+ ))}
1128
+ </tbody>
1129
+ </table>
1130
+ </div>
1131
+ </div>
1132
+ ) : null}
1133
+ </li>
1134
+ ))}
1135
+ </ol>
1136
+ )}
1137
+ <p className="auto-hint">
1138
+ {board
1139
+ ? "Click a stage to see and change what it does."
1140
+ : "Click any step to see and change what it does."}
1141
+ </p>
1142
+ </>
1143
+ )}
1144
+ </aside>
1145
+ </div>
1146
+ </div>
1147
+ );
1148
+ }
web/src/automation/AutomationFind.tsx ADDED
@@ -0,0 +1,389 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // automation/AutomationFind.tsx β€” the discovery filter, as TOGGLES (owner item 6,
3
+ // contract C4).
4
+ //
5
+ // WHAT CHANGED AND WHY. It was a condition BUILDER: an empty row, a field
6
+ // dropdown listing 21 names, "Add a condition". That shape asks the user to
7
+ // remember what is searchable before they can look, and it hid the only fact
8
+ // that decides whether a search returns anything at all β€” which fields actually
9
+ // carry values. The corpus is 620 million profiles and every run is billed, so
10
+ // "I did not know I could filter on that" and "I filtered on a field that is
11
+ // empty on every row" are both expensive mistakes made in silence.
12
+ //
13
+ // So every searchable field is ON SCREEN, off by default, and turning one on is
14
+ // what creates its condition. The list leads with the fields MEASURED to carry
15
+ // values; the rest are grouped under what is known about them, and neither group
16
+ // is hidden β€” R3 already decided that "every filter" means the 21 we can stand
17
+ // behind, so all 21 are visible.
18
+ //
19
+ // β›” THE VOCABULARY IS THE SERVER'S, ALL OF IT. Field names, operators, which
20
+ // operators take no value, the record ceiling and (once C4 lands it) which
21
+ // fields are populated and which narrow β€” every one of those rides on
22
+ // `GET /automations`. This file holds no list of its own. The reason is the one
23
+ // `automationApi.ts:11-15` gives for cron presets: the thing that ACCEPTS a
24
+ // filter is Python, and a client copy of what it accepts is a copy that can
25
+ // offer a search the server refuses.
26
+ //
27
+ // β›” AND IT DOES NOT RE-IMPLEMENT THE GUARD. `guard` carries the server's
28
+ // numbers, so the rows can say which fields narrow β€” but the refusal is the
29
+ // server's to make and this surface prints it VERBATIM when it comes back
30
+ // (`DiscoverGuard`'s note). A client that predicts the refusal is a second copy
31
+ // of the rule, free to disagree with the first, and when they disagree the user
32
+ // gets a Save button that is disabled for a reason nobody can see.
33
+ // ---------------------------------------------------------------------------
34
+ import type {
35
+ DiscoverEstimate,
36
+ DiscoverFieldMeta,
37
+ DiscoverVocab,
38
+ Predicate,
39
+ } from "./automationApi";
40
+
41
+ interface Props {
42
+ /** The server-declared discovery vocabulary (absent until the list loads). */
43
+ discover?: DiscoverVocab;
44
+ recordsLimit: number;
45
+ onRecordsLimit: (n: number) => void;
46
+ joinOp: string;
47
+ onJoinOp: (v: string) => void;
48
+ preds: Predicate[];
49
+ onPreds: (next: Predicate[]) => void;
50
+ estimate: DiscoverEstimate | null;
51
+ onEstimate: () => void;
52
+ }
53
+
54
+ /** One field's line in the list, with everything known about it. */
55
+ interface FieldRow {
56
+ name: string;
57
+ /** Every stored condition naming this field, with its index in the saved array. */
58
+ at: number[];
59
+ /** MEASURED to carry values. `null` = the server has not said (C4 not shipped yet). */
60
+ populated: boolean | null;
61
+ /** A condition here cuts the corpus down. `null` = not said. */
62
+ narrowing: boolean | null;
63
+ }
64
+
65
+ /**
66
+ * A default operator that is VALID THE MOMENT THE SWITCH GOES ON.
67
+ *
68
+ * ⚠ This is the wave-21 item-8 scar in a new shape. A new condition used to
69
+ * arrive as `{biography includes ""}` β€” a comparison with no value, which
70
+ * `clean_predicates` refuses outright β€” so adding one and pressing Save returned
71
+ * "give a value to compare 'biography' against" for a condition the user had not
72
+ * finished writing. A NULLARY operator needs no value, so a freshly toggled
73
+ * field is a complete, saveable, narrowing-in-the-right-direction condition
74
+ * ("this field has any value") from its first frame.
75
+ *
76
+ * Derived from the server's own lists rather than typed here, so it cannot name
77
+ * an operator the API rejects.
78
+ */
79
+ function firstOperator(v?: DiscoverVocab): string {
80
+ const nullary = v?.nullaryOperators || [];
81
+ const preferred = nullary.find((o) => o === "is_not_null");
82
+ return preferred || nullary[0] || (v?.operators || [])[0] || "";
83
+ }
84
+
85
+ /**
86
+ * The rows, ordered: measured-populated first, then the rest.
87
+ *
88
+ * TWO SOURCES, AND THE FALLBACK IS NARROWER THAN THE REAL THING. With C4's
89
+ * `filterMeta` the answer is per field and complete. Without it, `lead` names
90
+ * the three fields seen carrying values and says NOTHING about the other
91
+ * eighteen β€” so those come back `null`, not `false`, and the UI prints no claim
92
+ * about them rather than an invented one.
93
+ */
94
+ function buildRows(preds: Predicate[], v?: DiscoverVocab): FieldRow[] {
95
+ const meta = new Map<string, DiscoverFieldMeta>(
96
+ (v?.filterMeta || []).map((m) => [m.name, m])
97
+ );
98
+ const lead = new Set(v?.lead || []);
99
+ const byName = new Map<string, number[]>();
100
+ preds.forEach((p, i) => {
101
+ const list = byName.get(p.name);
102
+ if (list) list.push(i);
103
+ else byName.set(p.name, [i]);
104
+ });
105
+
106
+ const rows = (v?.fields || []).map((name) => {
107
+ const m = meta.get(name);
108
+ return {
109
+ name,
110
+ at: byName.get(name) || [],
111
+ populated: m ? !!m.populated : lead.has(name) ? true : null,
112
+ narrowing: m ? !!m.narrowing : null,
113
+ };
114
+ });
115
+ // Stable partition, never a sort: the server's order inside each half is the
116
+ // order the engine lists them in, and re-alphabetising it would be this file
117
+ // having an opinion about a server list.
118
+ return [...rows.filter((r) => r.populated === true), ...rows.filter((r) => r.populated !== true)];
119
+ }
120
+
121
+ export default function AutomationFind({
122
+ discover,
123
+ recordsLimit,
124
+ onRecordsLimit,
125
+ joinOp,
126
+ onJoinOp,
127
+ preds,
128
+ onPreds,
129
+ estimate,
130
+ onEstimate,
131
+ }: Props) {
132
+ const rows = buildRows(preds, discover);
133
+ const known = new Set(discover?.fields || []);
134
+ const nullary = new Set(discover?.nullaryOperators || []);
135
+ const operators = discover?.operators || [];
136
+ const withValues = rows.filter((r) => r.populated === true);
137
+ const rest = rows.filter((r) => r.populated !== true);
138
+ const knownMeta = !!(discover?.filterMeta || []).length;
139
+ // ⚠ THE STORED FILTER CAN NAME A FIELD THE LIST NO LONGER HAS β€” a vocabulary
140
+ // that moved, an automation copied from elsewhere. It must stay VISIBLE and
141
+ // REMOVABLE: a condition the user cannot see is one they cannot delete, and
142
+ // every Save keeps sending it. Same defect as a `<select>` whose value matches
143
+ // no option, one level up.
144
+ const strays = preds
145
+ .map((p, i) => ({ p, i }))
146
+ .filter(({ p }) => !known.has(p.name));
147
+
148
+ const maxRecords = discover?.guard?.maxRecords || discover?.maxRecords || 500;
149
+
150
+ const setAt = (i: number, patch: Partial<Predicate>) =>
151
+ onPreds(preds.map((p, j) => (j === i ? { ...p, ...patch } : p)));
152
+
153
+ const removeAt = (i: number) => onPreds(preds.filter((_p, j) => j !== i));
154
+
155
+ const toggleField = (row: FieldRow) => {
156
+ if (row.at.length) {
157
+ onPreds(preds.filter((p) => p.name !== row.name));
158
+ return;
159
+ }
160
+ onPreds([...preds, { name: row.name, operator: firstOperator(discover) }]);
161
+ };
162
+
163
+ /** One condition line β€” the comparison, its value, and a way out. */
164
+ const condition = (i: number, label: string) => {
165
+ const p = preds[i];
166
+ if (!p) return null;
167
+ return (
168
+ <div className="autob-cond" key={`${p.name}-${i}`}>
169
+ <select
170
+ className="auto-input is-small"
171
+ aria-label={`Comparison for ${label}`}
172
+ value={p.operator}
173
+ onChange={(e) => setAt(i, { operator: e.target.value })}
174
+ >
175
+ {/* The stored value is ALWAYS an option. A select whose value matches no
176
+ option renders the FIRST one, and the next Save writes a comparison
177
+ nobody chose β€” this codebase has paid for that twice. */}
178
+ {p.operator && !operators.includes(p.operator) ? (
179
+ <option value={p.operator}>{p.operator}</option>
180
+ ) : null}
181
+ {operators.map((o) => (
182
+ <option key={o} value={o}>
183
+ {o}
184
+ </option>
185
+ ))}
186
+ </select>
187
+ {nullary.has(p.operator) ? (
188
+ <span className="autob-cond-novalue" title="This comparison takes no value">
189
+ any value
190
+ </span>
191
+ ) : (
192
+ <input
193
+ className="auto-input is-small"
194
+ aria-label={`Value for ${label}`}
195
+ value={p.value === undefined ? "" : String(p.value)}
196
+ onChange={(e) => setAt(i, { value: e.target.value })}
197
+ />
198
+ )}
199
+ <button
200
+ type="button"
201
+ className="autob-cond-x"
202
+ aria-label={`Remove this condition on ${label}`}
203
+ title="Remove this condition"
204
+ onClick={() => removeAt(i)}
205
+ >
206
+ <svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden="true">
207
+ <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
208
+ </svg>
209
+ </button>
210
+ </div>
211
+ );
212
+ };
213
+
214
+ const fieldRow = (row: FieldRow) => {
215
+ const on = row.at.length > 0;
216
+ return (
217
+ <div className={"autob-tgl" + (on ? " is-on" : "")} key={row.name}>
218
+ <div className="autob-tgl-head">
219
+ <button
220
+ type="button"
221
+ className={"auto-step-switch autob-tgl-switch" + (on ? " is-on" : "")}
222
+ aria-pressed={on}
223
+ aria-label={`${on ? "Stop searching" : "Search"} on ${row.name}`}
224
+ title={`${on ? "Stop searching" : "Search"} on ${row.name}`}
225
+ onClick={() => toggleField(row)}
226
+ >
227
+ <span className="auto-step-switch-knob" />
228
+ </button>
229
+ {/* The VENDOR'S OWN NAME, verbatim. Not prettified: every refusal the
230
+ server sends names the field exactly like this ("'x' cannot be used
231
+ to search β€” the searchable fields are: …"), and a label that reads
232
+ differently from the error makes the error unmatchable. */}
233
+ <span className="autob-tgl-name">{row.name}</span>
234
+ {/*
235
+ ⚠ ONE CHIP, AND IT MARKS THE MINORITY. The first version chipped every
236
+ non-narrowing field "broad" AND every unpopulated one "no values seen" β€”
237
+ which put two chips on 18 of the 21 rows, and one of them repeated the group
238
+ heading the row was already sitting under. A mark that is on almost every row
239
+ stops being a mark. Read off the screenshot; no assertion could have said it.
240
+
241
+ So: the group label carries POPULATED (it is what the groups ARE), and the
242
+ chip carries NARROWING, inverted to mark the five that DO narrow. That is the
243
+ actionable half β€” the server refuses a filter with no narrowing condition, so
244
+ "these are the ones that satisfy it" is the sentence a user needs, and
245
+ "this one does not" is not.
246
+ */}
247
+ {row.narrowing === true ? (
248
+ <span
249
+ className="autob-tgl-flag is-narrow"
250
+ title="Cuts the corpus down. A search needs at least one condition that does."
251
+ >
252
+ narrows
253
+ </span>
254
+ ) : null}
255
+ </div>
256
+ {on ? (
257
+ <div className="autob-tgl-body">
258
+ {row.at.map((i) => condition(i, row.name))}
259
+ <button
260
+ type="button"
261
+ className="autob-cond-add"
262
+ onClick={() =>
263
+ onPreds([...preds, { name: row.name, operator: firstOperator(discover) }])
264
+ }
265
+ >
266
+ Another condition on {row.name}
267
+ </button>
268
+ </div>
269
+ ) : null}
270
+ </div>
271
+ );
272
+ };
273
+
274
+ return (
275
+ <>
276
+ <div className="auto-field">
277
+ <label htmlFor="auto-records">How many profiles to fetch</label>
278
+ <input
279
+ id="auto-records"
280
+ className="auto-input"
281
+ type="number"
282
+ min={1}
283
+ max={maxRecords}
284
+ value={recordsLimit}
285
+ onChange={(e) => onRecordsLimit(Number(e.target.value) || 1)}
286
+ />
287
+ </div>
288
+ <p className="auto-hint">
289
+ A search must be bounded β€” at most {maxRecords.toLocaleString()} profiles a run. An
290
+ unbounded one matches a share of a corpus of hundreds of millions, and the vendor
291
+ refuses it outright rather than delivering it.
292
+ </p>
293
+
294
+ <h3>Conditions</h3>
295
+ <div className="auto-field autob-match">
296
+ <label htmlFor="auto-joinop">Match</label>
297
+ <select
298
+ id="auto-joinop"
299
+ className="auto-input"
300
+ value={joinOp}
301
+ onChange={(e) => onJoinOp(e.target.value)}
302
+ >
303
+ <option value="and">All of them</option>
304
+ <option value="or">Any of them</option>
305
+ </select>
306
+ </div>
307
+
308
+ {!rows.length ? (
309
+ <p className="auto-note">
310
+ The searchable fields have not loaded yet.
311
+ </p>
312
+ ) : null}
313
+
314
+ {withValues.length ? (
315
+ <div className="autob-tglgroup">
316
+ <p
317
+ className="autob-tglgroup-label"
318
+ title="Seen carrying values on real corpus rows."
319
+ >
320
+ Has values
321
+ </p>
322
+ {withValues.map(fieldRow)}
323
+ </div>
324
+ ) : null}
325
+
326
+ {rest.length ? (
327
+ <div className="autob-tglgroup">
328
+ <p
329
+ className="autob-tglgroup-label"
330
+ title={
331
+ knownMeta
332
+ ? "Filterable, but empty on every profile we have measured β€” a condition on one of these can return nothing at all."
333
+ : "Whether these carry values has not been measured yet."
334
+ }
335
+ >
336
+ {knownMeta ? "No values seen" : "Not measured"}
337
+ </p>
338
+ {rest.map(fieldRow)}
339
+ </div>
340
+ ) : null}
341
+
342
+ {strays.length ? (
343
+ <div className="autob-tglgroup">
344
+ <p className="autob-tglgroup-label">Not in the searchable list</p>
345
+ {strays.map(({ p, i }) => (
346
+ <div className="autob-tgl is-on is-stray" key={`stray-${i}`}>
347
+ <div className="autob-tgl-head">
348
+ <span className="autob-tgl-name">{p.name}</span>
349
+ <span className="autob-tgl-flag is-stray" title="The server will refuse this condition by name.">
350
+ not searchable
351
+ </span>
352
+ </div>
353
+ <div className="autob-tgl-body">{condition(i, p.name)}</div>
354
+ </div>
355
+ ))}
356
+ </div>
357
+ ) : null}
358
+
359
+ <p className="auto-hint">
360
+ {/* ONE consequence sentence, because it is the one that costs money. Which
361
+ fields carry values is not trivia: a condition on an empty field returns
362
+ nothing and looks exactly like an honest "no such accounts exist". */}
363
+ A condition on a field with no values returns nothing while looking exactly like
364
+ &ldquo;no such accounts exist&rdquo;. Narrow conditions matter more than a small limit
365
+ β€” the search reads the whole corpus either way, so a broad one is slow and expensive
366
+ however few rows you keep.
367
+ </p>
368
+
369
+ <h3>What it costs</h3>
370
+ <div className="auto-head-actions">
371
+ <button type="button" className="auto-btn" onClick={onEstimate}>
372
+ Estimate this search
373
+ </button>
374
+ </div>
375
+ {estimate ? (
376
+ <p className="auto-hint">
377
+ About <strong>${estimate.usd}</strong> for {estimate.records} profiles, at $
378
+ {estimate.unitUsd} each.{" "}
379
+ {/*
380
+ THE CAVEAT IS NOT OPTIONAL. The vendor never quotes a price before a run and this
381
+ deployment cannot read its own balance, so presenting this as a billed figure
382
+ would be inventing a measurement.
383
+ */}
384
+ <strong>This is an estimate</strong> β€” {estimate.note}.
385
+ </p>
386
+ ) : null}
387
+ </>
388
+ );
389
+ }
web/src/automation/AutomationSteps.tsx CHANGED
@@ -1,407 +1,201 @@
1
- // ---------------------------------------------------------------------------
2
- // automation/AutomationSteps.tsx β€” one automation as NUMBERED STEPS (owner ruling R9).
3
- //
4
- // WHAT THIS REPLACES, AND WHY. It replaces the pan/zoom canvas as the work
5
- // surface. The owner asked for "trigger-first Steps": a job you read top to
6
- // bottom, starting with what makes it happen. A canvas answers "what shape is
7
- // this flow"; a numbered list answers "what does it do, in what order, and what
8
- // is step 3" β€” and the engine EXECUTES a list, not a graph. `capture_paid` and
9
- // `capture_anon` render as a fork and are walked linearly (DEBT D-7), so a list
10
- // that shows them as ALTERNATIVES AT ONE NUMBER is closer to what happens than
11
- // two boxes with an arrow between them ever was.
12
- //
13
- // ⚠ EVERY STEP COMES FROM THE SERVER (contract C6). The nodes, their order,
14
- // their titles, their switches and their dots are `engine.graph()`'s β€” this file
15
- // numbers them (`steps.ts`) and paints them. It may not add a step, hide a step,
16
- // or rename one: a client-side second idea of the steps is drift that is
17
- // invisible until an automation stops doing what the picture says.
18
- //
19
- // ONE CONTROL PER FACT, and R9 moved one. The trigger's on/off used to be the
20
- // canvas node's switch while the cron string lived in the panel. Step 1 now owns
21
- // BOTH β€” the picker IS the on/off β€” and the panel's schedule face is gone, so
22
- // there is exactly one place that decides when this runs.
23
- // ---------------------------------------------------------------------------
24
- import { useState } from "react";
25
-
26
- import type { AutomationGraph, GraphNode, TickState } from "./automationApi";
27
- import { WEEKDAYS, numberSteps, readCron, writeCron } from "./steps";
28
-
29
- interface Props {
30
- graph: AutomationGraph;
31
- selected: string;
32
- onSelect: (nodeId: string) => void;
33
- onToggle: (nodeId: string) => void;
34
- busyNode: string;
35
- /** The server's next fire time β€” shown on step 1 when there is one. */
36
- nextRunAt?: string;
37
- cron: string;
38
- enabled: boolean;
39
- /**
40
- * The tick bit, or `null` when the server does not report it. REQUIRED as a key
41
- * (an absent prop would compile) and nullable as a value, because "we were not
42
- * told" is a state this card prints rather than guesses at.
43
- */
44
- tick: TickState | null;
45
- /** Persisting a trigger change is IMMEDIATE β€” a trigger that needs a Save is not a switch. */
46
- onTrigger: (next: { cron: string; enabled: boolean }) => void;
47
- /** Free-text cron edits: local only, committed on blur. See the input's note. */
48
- onCronText: (cron: string) => void;
49
- /** The server's schedule vocabulary β€” never a client copy (`automationApi.ts:11-15`). */
50
- cronPresets: { cron: string; label: string }[];
51
- triggerBusy: boolean;
52
- }
53
-
54
- /** Step 1's icon vocabulary, drawn (owner constant: no emojis). */
55
- function KindMark({ kind }: { kind: GraphNode["kind"] }) {
56
- const common = {
57
- width: 15,
58
- height: 15,
59
- viewBox: "0 0 16 16",
60
- fill: "none",
61
- stroke: "currentColor",
62
- strokeWidth: 1.4,
63
- strokeLinecap: "round" as const,
64
- strokeLinejoin: "round" as const,
65
- "aria-hidden": true,
66
- };
67
- if (kind === "trigger")
68
- return (
69
- <svg {...common}>
70
- <circle cx="8" cy="8" r="5.6" />
71
- <path d="M8 5.2V8l2 1.4" />
72
- </svg>
73
- );
74
- if (kind === "source")
75
- return (
76
- <svg {...common}>
77
- <circle cx="8" cy="8" r="5.6" />
78
- <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" />
79
- </svg>
80
- );
81
- if (kind === "branch")
82
- return (
83
- <svg {...common}>
84
- <path d="M2.6 8h3.2l2.6-3.6h5M8.4 11.6H5.8m2.6 0h5" />
85
- <path d="M11.6 2.6 13.4 4.4 11.6 6.2M11.6 9.8l1.8 1.8-1.8 1.8" />
86
- </svg>
87
- );
88
- if (kind === "write")
89
- return (
90
- <svg {...common}>
91
- <ellipse cx="8" cy="4.2" rx="4.8" ry="1.9" />
92
- <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" />
93
- </svg>
94
- );
95
- return (
96
- <svg {...common}>
97
- <path d="M8 2.6v7.2M5.2 7l2.8 2.8L10.8 7M3 12.4h10" />
98
- </svg>
99
- );
100
- }
101
-
102
- /**
103
- * What the deployment will actually do with a schedule.
104
- *
105
- * β›” THREE ANSWERS, AND ONE OF THEM IS "WE WERE NOT TOLD". A card that said
106
- * "schedules won't fire" because a field was missing would be inventing a
107
- * measurement, and it would be WRONG on this product's own production: the
108
- * external EventBridge tick fires schedules on a deployment whose in-process
109
- * scheduler is off ([[aws-automation-cron]]). So `external` says the door is open,
110
- * not that the caller is alive β€” the server can only prove the first.
111
- */
112
- function tickNote(tick: TickState | null): { text: string; tone: string } {
113
- // ⚠ AN EXPLICIT BOOLEAN OR NOTHING. `!tick` alone was not enough: a payload carrying
114
- // `"tick": {}` β€” a half-shipped field, a serialiser that dropped a false, a version skew β€”
115
- // has no `enabled` at all, and reading `undefined` as "off" printed "schedules won't fire"
116
- // as though it had been measured. Caught by the probe's absent-state check, which is the
117
- // whole reason the third state exists.
118
- if (!tick || typeof tick.enabled !== "boolean") {
119
- return {
120
- text: "Whether this deployment runs schedules is not reported here yet β€” press Run now if you need it now.",
121
- tone: "is-unknown",
122
- };
123
- }
124
- if (!tick.enabled) {
125
- return {
126
- text: "Schedules won't fire on this deployment β€” ask your admin to switch the scheduler on. Run now still works.",
127
- tone: "is-off",
128
- };
129
- }
130
- if (tick.source === "external") {
131
- return {
132
- text: "Schedules fire when the external scheduler calls in. This deployment does not run them itself.",
133
- tone: "is-on",
134
- };
135
- }
136
- return { text: "This deployment runs schedules itself.", tone: "is-on" };
137
- }
138
-
139
- export default function AutomationSteps({
140
- graph,
141
- selected,
142
- onSelect,
143
- onToggle,
144
- busyNode,
145
- nextRunAt,
146
- cron,
147
- enabled,
148
- tick,
149
- onTrigger,
150
- onCronText,
151
- cronPresets,
152
- triggerBusy,
153
- }: Props) {
154
- const steps = numberSteps(graph?.nodes || []);
155
- const shape = readCron(cron);
156
- const note = tickNote(tick);
157
- const trigger = steps.length && steps[0].node.kind === "trigger" ? steps[0] : null;
158
- const rest = trigger ? steps.slice(1) : steps;
159
-
160
- /**
161
- * ⚠ "SHOW ME THE CRON" IS A VIEW CHOICE, NOT A SCHEDULE CHANGE β€” and forgetting that made
162
- * the Custom option DEAD. Everything else on this card is derived from the stored cron, so
163
- * picking "Custom (cron)" wrote… the same cron, which `readCron` then read back as "every
164
- * Wednesday" and the select snapped straight back. The custom face was reachable only by
165
- * already having an inexpressible schedule.
166
- *
167
- * So the choice is remembered here, and ONLY here: no PATCH fires when you ask to see the
168
- * string (nothing about the schedule changed), and an inexpressible stored cron still forces
169
- * the face open on its own. Found by the probe check that types a bad cron β€” which could not
170
- * reach the input at all.
171
- */
172
- const [showCron, setShowCron] = useState(false);
173
- const every = showCron ? "custom" : shape.every;
174
-
175
- const pickEvery = (next: string) => {
176
- setShowCron(next === "custom");
177
- if (next !== "custom") onTrigger({ cron: writeCron(next, shape.time || "06:00", cron), enabled });
178
- };
179
- const setTime = (time: string) => onTrigger({ cron: writeCron(shape.every, time, cron), enabled });
180
-
181
- return (
182
- <div className="auto-steps-wrap">
183
- <ol className="auto-steps">
184
- {trigger ? (
185
- <li className={"auto-step is-trigger" + (enabled ? "" : " is-off")}>
186
- <div className="auto-step-rail">
187
- <span className="auto-step-n">{trigger.n}</span>
188
- </div>
189
- <div className="auto-step-card">
190
- <div className="auto-step-head">
191
- <span className="auto-step-mark">
192
- <KindMark kind={trigger.node.kind} />
193
- </span>
194
- <span className="auto-step-title">{trigger.node.title}</span>
195
- <span className="auto-step-tag">Trigger</span>
196
- </div>
197
-
198
- <div className="auto-field-row">
199
- <div className="auto-field">
200
- <label htmlFor="auto-trigger-kind">When it runs</label>
201
- <select
202
- id="auto-trigger-kind"
203
- className="auto-input"
204
- value={enabled ? "schedule" : "manual"}
205
- disabled={triggerBusy}
206
- onChange={(e) => onTrigger({ cron, enabled: e.target.value === "schedule" })}
207
- >
208
- {/* Short labels: at the width this select gets, "Manual only β€” I press Run
209
- now" truncated to "Manual only β€” I press Run no…". What it MEANS is on
210
- the line below the card, in full, where it has room. */}
211
- <option value="manual">Manual only</option>
212
- <option value="schedule">On a schedule</option>
213
- {/*
214
- R9's designed, DISABLED slot. It is here rather than absent because the
215
- question "can it run when a record changes?" has an answer, and the
216
- honest one is "not yet" β€” an option nobody can pick says that, while a
217
- missing option says nothing and gets asked again. DEBT: the engine has no
218
- event triggers at all (`automation_engine.graph()` emits one trigger node,
219
- always a schedule); the exit condition is in the wave mailbox.
220
- */}
221
- <option value="event" disabled>
222
- When a field changes β€” coming soon
223
- </option>
224
- </select>
225
- </div>
226
- <div className="auto-field">
227
- <label htmlFor="auto-trigger-every">Repeat</label>
228
- <select
229
- id="auto-trigger-every"
230
- className="auto-input"
231
- value={every}
232
- disabled={triggerBusy || !enabled}
233
- onChange={(e) => pickEvery(e.target.value)}
234
- >
235
- <option value="day">Every day</option>
236
- {WEEKDAYS.map((d) => (
237
- <option key={d.value} value={d.value}>
238
- {d.label}
239
- </option>
240
- ))}
241
- {/*
242
- THE ESCAPE HATCH, AND IT IS LOAD-BEARING. Daily and weekly do not cover
243
- the schedules the engine accepts (hourly, every 15 minutes, monthly, a
244
- weekday range), and a picker that cannot express a stored cron would
245
- render its FIRST option instead β€” so the next Save would write "every
246
- day at 06:00" over a schedule nobody changed. `readCron` returns
247
- `custom` for anything it cannot express, and this option is where that
248
- lands, with the string itself editable beside it.
249
- */}
250
- <option value="custom">Custom (cron)</option>
251
- </select>
252
- </div>
253
- {every === "custom" ? (
254
- <>
255
- <div className="auto-field">
256
- <label htmlFor="auto-trigger-preset">Or a preset</label>
257
- {/*
258
- ⚠ THE PRESET LIST IS THE SERVER'S, and it is here because daily/weekly
259
- (R9) are not everything the engine runs β€” hourly, quarter-hourly and
260
- monthly are `CRON_PRESETS` and the old panel offered them. Dropping the
261
- list would have made those schedules reachable only by typing raw cron.
262
- It stays SERVER-SUPPLIED for the reason `automationApi.ts:11-15` gives:
263
- the parser that accepts a cron lives in Python, and a client-invented
264
- preset is a schedule the server can refuse while the UI looks fine.
265
- */}
266
- <select
267
- id="auto-trigger-preset"
268
- className="auto-input"
269
- value={cronPresets.some((p) => p.cron === cron) ? cron : ""}
270
- disabled={triggerBusy || !enabled}
271
- onChange={(e) => e.target.value && onTrigger({ cron: e.target.value, enabled })}
272
- >
273
- <option value="">Typed below</option>
274
- {cronPresets.map((p) => (
275
- <option key={p.cron} value={p.cron}>
276
- {p.label}
277
- </option>
278
- ))}
279
- </select>
280
- </div>
281
- <div className="auto-field">
282
- <label htmlFor="auto-trigger-custom">Cron (minute hour day month weekday)</label>
283
- {/*
284
- ⚠ TYPING DOES NOT PATCH. Every other control here persists on change
285
- because each is one discrete decision; a cron STRING is free text, so
286
- per-keystroke saving would PATCH a half-typed schedule five times and
287
- the server would refuse most of them out loud. It edits locally and
288
- commits on BLUR (and rides the header's Save either way, because every
289
- immediate write persists the pending edit first).
290
- */}
291
- <input
292
- id="auto-trigger-custom"
293
- className="auto-input is-mono"
294
- value={cron}
295
- disabled={triggerBusy || !enabled}
296
- onChange={(e) => onCronText(e.target.value)}
297
- onBlur={() => onTrigger({ cron, enabled })}
298
- />
299
- </div>
300
- </>
301
- ) : (
302
- <div className="auto-field">
303
- <label htmlFor="auto-trigger-time">At</label>
304
- <input
305
- id="auto-trigger-time"
306
- className="auto-input"
307
- type="time"
308
- value={shape.time || "06:00"}
309
- disabled={triggerBusy || !enabled}
310
- onChange={(e) => setTime(e.target.value)}
311
- />
312
- </div>
313
- )}
314
- </div>
315
-
316
- <p className={"auto-tick-note " + note.tone}>{note.text}</p>
317
- <p className="auto-step-detail">
318
- {/*
319
- ⚠ "NEXT RUN 12:30" IS A PROMISE, AND IT IS ONLY TRUE IF SOMETHING TICKS. The
320
- server computes the next fire from the cron alone β€” it does not know whether a
321
- scheduler is running β€” so printing it flat beside a card that has just said
322
- "schedules won't fire" is the surface contradicting itself in two lines. When
323
- the tick is KNOWN off, the same time is stated as the conditional it is.
324
- */}
325
- {enabled
326
- ? nextRunAt
327
- ? tick && tick.enabled === false
328
- ? `It would run next at ${nextRunAt}, once a scheduler is running.`
329
- : `Next run ${nextRunAt}.`
330
- : "Schedules start from the moment they are switched on β€” turning on a daily job after today's time does not fire it today."
331
- : "It runs when you press Run now, and nothing else starts it."}
332
- </p>
333
- </div>
334
- </li>
335
- ) : null}
336
-
337
- {rest.map((s) => (
338
- <li
339
- key={s.node.id}
340
- className={
341
- "auto-step" +
342
- (s.node.id === selected ? " is-selected" : "") +
343
- (s.node.enabled ? "" : " is-off") +
344
- (s.alt ? " is-alt" : "") +
345
- ` is-${s.node.kind}`
346
- }
347
- >
348
- <div className="auto-step-rail">
349
- {/* An alternative shares the number of the step it is an alternative TO β€” the
350
- fork is a choice at one position, not two things that both happen. */}
351
- <span className={"auto-step-n" + (s.alt ? " is-alt" : "")}>{s.n}</span>
352
- {s.alt ? <span className="auto-step-or">or</span> : null}
353
- </div>
354
- <div className="auto-step-card">
355
- <button
356
- type="button"
357
- className="auto-step-hit"
358
- aria-pressed={s.node.id === selected}
359
- title={`${s.node.title} β€” ${s.node.subtitle}`}
360
- onClick={() => onSelect(s.node.id)}
361
- >
362
- <span className="auto-step-head">
363
- <span className="auto-step-mark">
364
- <KindMark kind={s.node.kind} />
365
- </span>
366
- <span className="auto-step-title">{s.node.title}</span>
367
- <span
368
- className={`auto-dot is-${s.node.status}`}
369
- title={`Last run: ${s.node.status}`}
370
- aria-label={`Last run: ${s.node.status}`}
371
- />
372
- </span>
373
- <span className="auto-step-sub">{s.node.subtitle}</span>
374
- {s.node.detail ? (
375
- <span className="auto-step-detail">{s.node.detail}</span>
376
- ) : null}
377
- </button>
378
- {s.node.toggle ? (
379
- <button
380
- type="button"
381
- className={"auto-step-switch" + (s.node.enabled ? " is-on" : "")}
382
- disabled={busyNode === s.node.id}
383
- aria-pressed={s.node.enabled}
384
- aria-label={`${s.node.enabled ? "Turn off" : "Turn on"} ${s.node.title}`}
385
- title={`${s.node.enabled ? "Turn off" : "Turn on"} ${s.node.title}`}
386
- onClick={(e) => {
387
- e.stopPropagation();
388
- onToggle(s.node.id);
389
- }}
390
- >
391
- <span className="auto-step-switch-knob" />
392
- </button>
393
- ) : (
394
- // A step with no honest switch says so rather than carrying a control that
395
- // would do nothing β€” "every step toggleable" ends where a real behaviour
396
- // change ends.
397
- <span className="auto-step-always" title="This step is what the automation is">
398
- Always
399
- </span>
400
- )}
401
- </div>
402
- </li>
403
- ))}
404
- </ol>
405
- </div>
406
- );
407
- }
 
1
+ // ---------------------------------------------------------------------------
2
+ // automation/AutomationSteps.tsx β€” one automation as NUMBERED STEPS (owner ruling R9).
3
+ //
4
+ // WHAT THIS REPLACES, AND WHY. It replaces the pan/zoom canvas as the work
5
+ // surface. The owner asked for "trigger-first Steps": a job you read top to
6
+ // bottom, starting with what makes it happen. A canvas answers "what shape is
7
+ // this flow"; a numbered list answers "what does it do, in what order, and what
8
+ // is step 3" β€” and the engine EXECUTES a list, not a graph. `capture_paid` and
9
+ // `capture_anon` render as a fork and are walked linearly (DEBT D-7), so a list
10
+ // that shows them as ALTERNATIVES AT ONE NUMBER is closer to what happens than
11
+ // two boxes with an arrow between them ever was.
12
+ //
13
+ // ⚠ EVERY STEP COMES FROM THE SERVER (contract C6). The nodes, their order,
14
+ // their titles, their switches and their dots are `engine.graph()`'s β€” this file
15
+ // numbers them (`steps.ts`) and paints them. It may not add a step, hide a step,
16
+ // or rename one: a client-side second idea of the steps is drift that is
17
+ // invisible until an automation stops doing what the picture says.
18
+ //
19
+ // ONE CONTROL PER FACT, and R9 moved one. The trigger's on/off used to be the
20
+ // canvas node's switch while the cron string lived in the panel. Step 1 now owns
21
+ // BOTH β€” the picker IS the on/off β€” and the panel's schedule face is gone, so
22
+ // there is exactly one place that decides when this runs.
23
+ // ---------------------------------------------------------------------------
24
+ import type { ReactNode } from "react";
25
+
26
+ import type { AutomationGraph, GraphNode } from "./automationApi";
27
+ import { numberSteps } from "./steps";
28
+
29
+ interface Props {
30
+ graph: AutomationGraph;
31
+ selected: string;
32
+ onSelect: (nodeId: string) => void;
33
+ onToggle: (nodeId: string) => void;
34
+ busyNode: string;
35
+ /**
36
+ * The trigger face (contract C3), composed by `AutomationDetail`.
37
+ *
38
+ * ⭐ PASSED IN RATHER THAN BUILT HERE, and that is wave 22's change to this file.
39
+ * The board frame needs the same picker, the same cron round-trip and the same
40
+ * tick honesty note; writing them twice would be two copies of three things that
41
+ * go wrong invisibly. `AutomationTrigger` owns all of it and both frames render
42
+ * the same element.
43
+ */
44
+ triggerFace: ReactNode;
45
+ /** Dim Step 1 when nothing automatic starts this automation. */
46
+ triggerOff: boolean;
47
+ }
48
+
49
+ /** Step 1's icon vocabulary, drawn (owner constant: no emojis). */
50
+ function KindMark({ kind }: { kind: GraphNode["kind"] }) {
51
+ const common = {
52
+ width: 15,
53
+ height: 15,
54
+ viewBox: "0 0 16 16",
55
+ fill: "none",
56
+ stroke: "currentColor",
57
+ strokeWidth: 1.4,
58
+ strokeLinecap: "round" as const,
59
+ strokeLinejoin: "round" as const,
60
+ "aria-hidden": true,
61
+ };
62
+ if (kind === "trigger")
63
+ return (
64
+ <svg {...common}>
65
+ <circle cx="8" cy="8" r="5.6" />
66
+ <path d="M8 5.2V8l2 1.4" />
67
+ </svg>
68
+ );
69
+ if (kind === "source")
70
+ return (
71
+ <svg {...common}>
72
+ <circle cx="8" cy="8" r="5.6" />
73
+ <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" />
74
+ </svg>
75
+ );
76
+ if (kind === "branch")
77
+ return (
78
+ <svg {...common}>
79
+ <path d="M2.6 8h3.2l2.6-3.6h5M8.4 11.6H5.8m2.6 0h5" />
80
+ <path d="M11.6 2.6 13.4 4.4 11.6 6.2M11.6 9.8l1.8 1.8-1.8 1.8" />
81
+ </svg>
82
+ );
83
+ if (kind === "write")
84
+ return (
85
+ <svg {...common}>
86
+ <ellipse cx="8" cy="4.2" rx="4.8" ry="1.9" />
87
+ <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" />
88
+ </svg>
89
+ );
90
+ return (
91
+ <svg {...common}>
92
+ <path d="M8 2.6v7.2M5.2 7l2.8 2.8L10.8 7M3 12.4h10" />
93
+ </svg>
94
+ );
95
+ }
96
+
97
+ export default function AutomationSteps({
98
+ graph,
99
+ selected,
100
+ onSelect,
101
+ onToggle,
102
+ busyNode,
103
+ triggerFace,
104
+ triggerOff,
105
+ }: Props) {
106
+ const steps = numberSteps(graph?.nodes || []);
107
+ const trigger = steps.length && steps[0].node.kind === "trigger" ? steps[0] : null;
108
+ const rest = trigger ? steps.slice(1) : steps;
109
+
110
+ return (
111
+ <div className="auto-steps-wrap">
112
+ <ol className="auto-steps">
113
+ {trigger ? (
114
+ <li className={"auto-step is-trigger" + (triggerOff ? " is-off" : "")}>
115
+ <div className="auto-step-rail">
116
+ <span className="auto-step-n">{trigger.n}</span>
117
+ </div>
118
+ <div className="auto-step-card">
119
+ <div className="auto-step-head">
120
+ <span className="auto-step-mark">
121
+ <KindMark kind={trigger.node.kind} />
122
+ </span>
123
+ <span className="auto-step-title">{trigger.node.title}</span>
124
+ <span className="auto-step-tag">Trigger</span>
125
+ </div>
126
+ {triggerFace}
127
+ </div>
128
+ </li>
129
+ ) : null}
130
+
131
+ {rest.map((s) => (
132
+ <li
133
+ key={s.node.id}
134
+ className={
135
+ "auto-step" +
136
+ (s.node.id === selected ? " is-selected" : "") +
137
+ (s.node.enabled ? "" : " is-off") +
138
+ (s.alt ? " is-alt" : "") +
139
+ ` is-${s.node.kind}`
140
+ }
141
+ >
142
+ <div className="auto-step-rail">
143
+ {/* An alternative shares the number of the step it is an alternative TO β€” the
144
+ fork is a choice at one position, not two things that both happen. */}
145
+ <span className={"auto-step-n" + (s.alt ? " is-alt" : "")}>{s.n}</span>
146
+ {s.alt ? <span className="auto-step-or">or</span> : null}
147
+ </div>
148
+ <div className="auto-step-card">
149
+ <button
150
+ type="button"
151
+ className="auto-step-hit"
152
+ aria-pressed={s.node.id === selected}
153
+ title={`${s.node.title} β€” ${s.node.subtitle}`}
154
+ onClick={() => onSelect(s.node.id)}
155
+ >
156
+ <span className="auto-step-head">
157
+ <span className="auto-step-mark">
158
+ <KindMark kind={s.node.kind} />
159
+ </span>
160
+ <span className="auto-step-title">{s.node.title}</span>
161
+ <span
162
+ className={`auto-dot is-${s.node.status}`}
163
+ title={`Last run: ${s.node.status}`}
164
+ aria-label={`Last run: ${s.node.status}`}
165
+ />
166
+ </span>
167
+ <span className="auto-step-sub">{s.node.subtitle}</span>
168
+ {s.node.detail ? (
169
+ <span className="auto-step-detail">{s.node.detail}</span>
170
+ ) : null}
171
+ </button>
172
+ {s.node.toggle ? (
173
+ <button
174
+ type="button"
175
+ className={"auto-step-switch" + (s.node.enabled ? " is-on" : "")}
176
+ disabled={busyNode === s.node.id}
177
+ aria-pressed={s.node.enabled}
178
+ aria-label={`${s.node.enabled ? "Turn off" : "Turn on"} ${s.node.title}`}
179
+ title={`${s.node.enabled ? "Turn off" : "Turn on"} ${s.node.title}`}
180
+ onClick={(e) => {
181
+ e.stopPropagation();
182
+ onToggle(s.node.id);
183
+ }}
184
+ >
185
+ <span className="auto-step-switch-knob" />
186
+ </button>
187
+ ) : (
188
+ // A step with no honest switch says so rather than carrying a control that
189
+ // would do nothing β€” "every step toggleable" ends where a real behaviour
190
+ // change ends.
191
+ <span className="auto-step-always" title="This step is what the automation is">
192
+ Always
193
+ </span>
194
+ )}
195
+ </div>
196
+ </li>
197
+ ))}
198
+ </ol>
199
+ </div>
200
+ );
201
+ }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
web/src/automation/AutomationSurface.tsx CHANGED
@@ -220,11 +220,13 @@ export default function AutomationSurface() {
220
  </div>
221
  );
222
  })}
 
 
 
 
 
223
  {!items.length && !error ? (
224
- <p className="auto-rail-empty">
225
- No automations yet. One reads a public web page into a database on a
226
- schedule; the other fills an automation column from a public profile.
227
- </p>
228
  ) : null}
229
  </div>
230
  </aside>
@@ -259,6 +261,10 @@ export default function AutomationSurface() {
259
  cronPresets={data?.cronPresets || []}
260
  paidReady={!!data?.paidReady}
261
  discover={data?.discover}
 
 
 
 
262
  // `?? null` and never `|| {enabled:false}`: an absent tick bit is "the server did
263
  // not say", which Step 1 prints as its own sentence. Defaulting it here would
264
  // turn a missing field into a claim about production (C6 amendment #1).
@@ -273,36 +279,37 @@ export default function AutomationSurface() {
273
  }}
274
  />
275
  ) : (
276
- <div className="auto-empty">
277
- <h1>Automations</h1>
278
- <p>
279
- An automation is a job this workspace runs for you β€” on demand, or on a
280
- schedule. Each one is a flow: a trigger, the steps it walks, and the database
281
- it writes. Pick one on the left, or create a new one.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
282
  </p>
283
- <ul className="auto-empty-kinds">
284
- <li>
285
- <strong>Web page to database.</strong> Read a public page, map its columns
286
- to fields, and keep a database in step with it. Re-runs update matched rows
287
- by key and insert new ones; a row that stops appearing is counted and kept,
288
- never deleted.
289
- </li>
290
- <li>
291
- <strong>Instagram profile column.</strong> For every record carrying a
292
- public profile URL, read the profile β€” exactly, through Bright Data, or
293
- approximately on the free anonymous rung β€” and append a timestamped row per
294
- pull, so followers become a series you can filter by date rather than a
295
- single current number.
296
- </li>
297
- <li>
298
- <strong>Find Instagram profiles.</strong> Search a corpus of pre-collected
299
- public profiles for accounts you have never heard of β€” a follower band, a
300
- phrase in the bio, an engagement floor β€” and collect the matches into a
301
- candidates database. Searching costs money, so every run is bounded by a
302
- profile count you set and shows an estimate first. Nothing found is ever
303
- tracked automatically; you tick the ones you want.
304
- </li>
305
- </ul>
306
  </div>
307
  )}
308
  </section>
 
220
  </div>
221
  );
222
  })}
223
+ {/* ONE LINE (R13). It used to describe the kinds β€” "one reads a public web page…
224
+ the other fills an automation column…" β€” which was two sentences, wrong by the
225
+ time a third kind shipped, and printed inside a `--lp-rail-w` column. What the
226
+ kinds are belongs to the create form, which is one click away and lists all of
227
+ them from the server. */}
228
  {!items.length && !error ? (
229
+ <p className="auto-rail-empty">No automations yet.</p>
 
 
 
230
  ) : null}
231
  </div>
232
  </aside>
 
261
  cronPresets={data?.cronPresets || []}
262
  paidReady={!!data?.paidReady}
263
  discover={data?.discover}
264
+ // The trigger vocabulary (C3). Forwarded as-is β€” absent stays absent, so the
265
+ // trigger face can tell "the server offered nothing" from "the server offered
266
+ // an empty list" rather than collapsing both into a picker with no options.
267
+ triggers={data?.triggers}
268
  // `?? null` and never `|| {enabled:false}`: an absent tick bit is "the server did
269
  // not say", which Step 1 prints as its own sentence. Defaulting it here would
270
  // turn a missing field into a claim about production (C6 amendment #1).
 
279
  }}
280
  />
281
  ) : (
282
+ /*
283
+ * THE EMPTY STATE IS ONE LINE AND A BUTTON (owner ruling R13 β€” "never
284
+ * over-explain", now a DESIGN.md law).
285
+ *
286
+ * It was a heading, a three-sentence paragraph and a 130-word bulleted list
287
+ * describing all three kinds. Every word of it was true and none of it was READ:
288
+ * an empty state is passed through, not studied, and the person looking at it has
289
+ * already decided to make an automation. The kinds are described where the choice
290
+ * is actually made β€” the create form lists them FROM THE SERVER, so that copy also
291
+ * cannot go stale the way this list had (it described two kinds after a third
292
+ * shipped).
293
+ *
294
+ * The button is here rather than only in the rail because this pane is where the
295
+ * eye is; a create affordance the user has to go find is the same defect as the
296
+ * paragraph, spent differently.
297
+ */
298
+ <div className="autob-empty">
299
+ <h1 className="autob-empty-title">Automations</h1>
300
+ <p className="autob-empty-line">
301
+ A job this workspace runs for you, on demand or on a schedule.
302
  </p>
303
+ <button
304
+ type="button"
305
+ className="auto-btn is-primary"
306
+ onClick={() => {
307
+ setCreating(true);
308
+ setActiveId("");
309
+ }}
310
+ >
311
+ New automation
312
+ </button>
 
 
 
 
 
 
 
 
 
 
 
 
 
313
  </div>
314
  )}
315
  </section>
web/src/automation/AutomationTrigger.tsx ADDED
@@ -0,0 +1,319 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // automation/AutomationTrigger.tsx β€” what STARTS an automation (contract C3).
3
+ //
4
+ // ONE implementation, two frames. The board renders it as the strip above the
5
+ // lanes; the numbered-steps view renders it inside Step 1's card. It used to be
6
+ // written inline in `AutomationSteps`, and the moment the board needed the same
7
+ // controls that was a second copy of the cron round-trip, the tick honesty note
8
+ // and the next-run sentence β€” three things that go subtly wrong and stay wrong
9
+ // invisibly. There is one of each.
10
+ //
11
+ // β›” THE VOCABULARY IS THE SERVER'S (C3, and this is the rule the wave was
12
+ // explicit about). The options come from `triggers: [{key, label, ready, needs}]`
13
+ // on `GET /automations`. There is NO client union over the keys: a union means
14
+ // the two lists can diverge, and they diverge SILENTLY β€” the server offers a
15
+ // trigger the client has no arm for, the client draws nothing, and the product
16
+ // quietly loses a feature it shipped (the wave-9 silent-drop class). The keys are
17
+ // `string` here on purpose, and an unrecognised one still renders.
18
+ //
19
+ // A NOT-READY TRIGGER IS OFFERED, NOT HIDDEN. `ready: false` plus `needs`
20
+ // ("connect_gmail") renders as an option you can pick with a next step attached.
21
+ // R9 set that precedent with the disabled "when a field changes" slot and the
22
+ // reasoning holds: the question "can it run when an email arrives?" has an
23
+ // answer, and an option nobody can use yet SAYS it β€” a missing option says
24
+ // nothing and gets asked again.
25
+ // ---------------------------------------------------------------------------
26
+ import type { OAuthStatus, TickState, TriggerOption } from "./automationApi";
27
+ import { oauthProviderFor, oauthStartUrlFor } from "./automationApi";
28
+ import { WEEKDAYS, readCron, writeCron } from "./steps";
29
+
30
+ interface Props {
31
+ /**
32
+ * The server's trigger list. ABSENT until the engine ships C3 β€” and absent is
33
+ * not "no triggers": the face falls back to the two shapes today's server can
34
+ * actually express, marked below, and stops consulting that fallback the moment
35
+ * the list rides.
36
+ */
37
+ triggers?: TriggerOption[];
38
+ /** The trigger currently stored, as a key. */
39
+ current: string;
40
+ cron: string;
41
+ enabled: boolean;
42
+ /** `null` = the server did not report whether schedules fire here (R9's third state). */
43
+ tick: TickState | null;
44
+ nextRunAt?: string;
45
+ cronPresets: { cron: string; label: string }[];
46
+ busy: boolean;
47
+ /** Picking a trigger PERSISTS β€” a trigger you have to remember to Save is not a switch. */
48
+ onPick: (key: string) => void;
49
+ onSchedule: (next: { cron: string; enabled: boolean }) => void;
50
+ /** Free-text cron edits: local only, committed on blur. See the input's note. */
51
+ onCronText: (cron: string) => void;
52
+ /** Whether this USER has connected each provider (C5). `null` = not asked yet. */
53
+ oauth: OAuthStatus | null;
54
+ /** True when the raw cron face is open β€” a VIEW choice, not a schedule change. */
55
+ showCron: boolean;
56
+ onShowCron: (v: boolean) => void;
57
+ }
58
+
59
+ /**
60
+ * ⚠ THE FALLBACK, AND IT IS TEMPORARY BY CONSTRUCTION. Until `triggers` rides,
61
+ * these are the only two shapes the stored definition can express β€” the engine
62
+ * has exactly one trigger node and `schedule.enabled` decides it β€” so this is a
63
+ * description of what the server can do today, not a second vocabulary. It is
64
+ * NEVER consulted once the list arrives; when C3 lands, deleting this constant
65
+ * changes nothing on screen.
66
+ */
67
+ const FALLBACK_TRIGGERS: TriggerOption[] = [
68
+ { key: "manual", label: "Manual only", ready: true },
69
+ { key: "schedule", label: "On a schedule", ready: true },
70
+ ];
71
+
72
+ /** The one-line next step a not-ready trigger carries. Server words where there are any. */
73
+ function needsLabel(needs: string): string {
74
+ if (needs === "connect_gmail") return "Connect Gmail";
75
+ // An unrecognised `needs` is still SAID, verbatim. A blank next step is how a
76
+ // not-ready trigger becomes a dead control.
77
+ return needs.replace(/_/g, " ");
78
+ }
79
+
80
+ /**
81
+ * What the deployment will actually do with a schedule.
82
+ *
83
+ * β›” THREE ANSWERS, AND ONE OF THEM IS "WE WERE NOT TOLD". A card that said
84
+ * "schedules won't fire" because a field was missing would be inventing a
85
+ * measurement, and it would be WRONG on this product's own production: the
86
+ * external EventBridge tick fires schedules on a deployment whose in-process
87
+ * scheduler is off ([[aws-automation-cron]]). So `external` says the door is open,
88
+ * not that the caller is alive β€” the server can only prove the first.
89
+ */
90
+ function tickNote(tick: TickState | null): { text: string; tone: string } {
91
+ // ⚠ AN EXPLICIT BOOLEAN OR NOTHING. A payload carrying `"tick": {}` β€” a
92
+ // half-shipped field, a serialiser that dropped a false, a version skew β€” has no
93
+ // `enabled` at all, and reading `undefined` as "off" printed "schedules won't
94
+ // fire" as though it had been measured.
95
+ if (!tick || typeof tick.enabled !== "boolean") {
96
+ return {
97
+ text: "Whether this deployment runs schedules is not reported here yet β€” press Run now if you need it now.",
98
+ tone: "is-unknown",
99
+ };
100
+ }
101
+ if (!tick.enabled) {
102
+ return {
103
+ text: "Schedules won't fire on this deployment β€” ask your admin to switch the scheduler on. Run now still works.",
104
+ tone: "is-off",
105
+ };
106
+ }
107
+ if (tick.source === "external") {
108
+ return {
109
+ text: "Schedules fire when the external scheduler calls in. This deployment does not run them itself.",
110
+ tone: "is-on",
111
+ };
112
+ }
113
+ return { text: "This deployment runs schedules itself.", tone: "is-on" };
114
+ }
115
+
116
+ export default function AutomationTrigger({
117
+ triggers,
118
+ current,
119
+ cron,
120
+ enabled,
121
+ tick,
122
+ nextRunAt,
123
+ cronPresets,
124
+ busy,
125
+ onPick,
126
+ onSchedule,
127
+ onCronText,
128
+ oauth,
129
+ showCron,
130
+ onShowCron,
131
+ }: Props) {
132
+ const options = triggers && triggers.length ? triggers : FALLBACK_TRIGGERS;
133
+ const picked = options.find((t) => t.key === current) || null;
134
+ const isSchedule = current === "schedule";
135
+ const shape = readCron(cron);
136
+ const note = tickNote(tick);
137
+ const every = showCron ? "custom" : shape.every;
138
+ // The connector this trigger is waiting on, resolved from the SERVER's `needs`
139
+ // token. Empty provider = we cannot name a route for it, which is a state the
140
+ // block below states in words instead of drawing a button that goes nowhere.
141
+ const waiting = !!picked && picked.ready === false && !!picked.needs;
142
+ const provider = waiting ? oauthProviderFor(picked.needs as string) : "";
143
+ const connected = !!(provider && oauth?.[provider]?.connected);
144
+ const startUrl = waiting ? oauthStartUrlFor(picked.needs as string) : "";
145
+
146
+ const pickEvery = (next: string) => {
147
+ onShowCron(next === "custom");
148
+ if (next !== "custom")
149
+ onSchedule({ cron: writeCron(next, shape.time || "06:00", cron), enabled });
150
+ };
151
+
152
+ return (
153
+ <>
154
+ <div className="auto-field-row">
155
+ <div className="auto-field">
156
+ <label htmlFor="auto-trigger-kind">When it runs</label>
157
+ <select
158
+ id="auto-trigger-kind"
159
+ className="auto-input"
160
+ value={current}
161
+ disabled={busy}
162
+ onChange={(e) => onPick(e.target.value)}
163
+ >
164
+ {/*
165
+ THE STORED VALUE IS ALWAYS AN OPTION. A <select> whose `value` matches
166
+ no <option> renders the FIRST one, so the next write persists a trigger
167
+ nobody chose β€” the defect this codebase has already paid for twice
168
+ ([[cg-condition-builder-items]]).
169
+ */}
170
+ {current && !options.some((t) => t.key === current) ? (
171
+ <option value={current}>{current} (not offered here)</option>
172
+ ) : null}
173
+ {options.map((t) => (
174
+ <option key={t.key} value={t.key}>
175
+ {/* Not-ready is stated ON the option rather than by disabling it: the
176
+ option is pickable, and picking it shows what it is waiting for. */}
177
+ {t.ready === false ? `${t.label} β€” needs setting up` : t.label}
178
+ </option>
179
+ ))}
180
+ </select>
181
+ </div>
182
+
183
+ {isSchedule ? (
184
+ <>
185
+ <div className="auto-field">
186
+ <label htmlFor="auto-trigger-every">Repeat</label>
187
+ <select
188
+ id="auto-trigger-every"
189
+ className="auto-input"
190
+ value={every}
191
+ disabled={busy}
192
+ onChange={(e) => pickEvery(e.target.value)}
193
+ >
194
+ <option value="day">Every day</option>
195
+ {WEEKDAYS.map((d) => (
196
+ <option key={d.value} value={d.value}>
197
+ {d.label}
198
+ </option>
199
+ ))}
200
+ {/*
201
+ THE ESCAPE HATCH, AND IT IS LOAD-BEARING. Daily and weekly do not cover
202
+ the schedules the engine accepts (hourly, every 15 minutes, monthly, a
203
+ weekday range), and a picker that cannot express a stored cron would
204
+ render its FIRST option instead β€” so the next Save would write "every
205
+ day at 06:00" over a schedule nobody changed.
206
+ */}
207
+ <option value="custom">Custom (cron)</option>
208
+ </select>
209
+ </div>
210
+ {every === "custom" ? (
211
+ <>
212
+ <div className="auto-field">
213
+ <label htmlFor="auto-trigger-preset">Or a preset</label>
214
+ {/*
215
+ ⚠ THE PRESET LIST IS THE SERVER'S. Daily and weekly are not everything
216
+ the engine runs β€” hourly, quarter-hourly and monthly are `CRON_PRESETS`
217
+ β€” and the parser that ACCEPTS a cron lives in Python, so a
218
+ client-invented preset is a schedule the server can refuse while the UI
219
+ looks fine.
220
+ */}
221
+ <select
222
+ id="auto-trigger-preset"
223
+ className="auto-input"
224
+ value={cronPresets.some((p) => p.cron === cron) ? cron : ""}
225
+ disabled={busy}
226
+ onChange={(e) => e.target.value && onSchedule({ cron: e.target.value, enabled })}
227
+ >
228
+ <option value="">Typed below</option>
229
+ {cronPresets.map((p) => (
230
+ <option key={p.cron} value={p.cron}>
231
+ {p.label}
232
+ </option>
233
+ ))}
234
+ </select>
235
+ </div>
236
+ <div className="auto-field">
237
+ <label htmlFor="auto-trigger-custom">Cron (minute hour day month weekday)</label>
238
+ {/*
239
+ ⚠ TYPING DOES NOT PATCH. Every other control here persists on change
240
+ because each is one discrete decision; a cron STRING is free text, so
241
+ per-keystroke saving would PATCH a half-typed schedule five times and
242
+ the server would refuse most of them out loud. It edits locally and
243
+ commits on BLUR.
244
+ */}
245
+ <input
246
+ id="auto-trigger-custom"
247
+ className="auto-input is-mono"
248
+ value={cron}
249
+ disabled={busy}
250
+ onChange={(e) => onCronText(e.target.value)}
251
+ onBlur={() => onSchedule({ cron, enabled })}
252
+ />
253
+ </div>
254
+ </>
255
+ ) : (
256
+ <div className="auto-field">
257
+ <label htmlFor="auto-trigger-time">At</label>
258
+ <input
259
+ id="auto-trigger-time"
260
+ className="auto-input"
261
+ type="time"
262
+ value={shape.time || "06:00"}
263
+ disabled={busy}
264
+ onChange={(e) => onSchedule({ cron: writeCron(shape.every, e.target.value, cron), enabled })}
265
+ />
266
+ </div>
267
+ )}
268
+ </>
269
+ ) : null}
270
+ </div>
271
+
272
+ {/* NOT CONFIGURED IS A STATE WITH A NEXT STEP, never a dead control (C3). */}
273
+ {waiting ? (
274
+ <div className="autob-needs">
275
+ <span className="autob-needs-text">
276
+ {connected
277
+ ? "Connected β€” this trigger is still being switched on for this deployment."
278
+ : "This trigger is not set up yet."}
279
+ </span>
280
+ {!connected && startUrl ? (
281
+ <a className="auto-btn is-primary autob-connect" href={startUrl}>
282
+ {needsLabel(picked?.needs || "")}
283
+ </a>
284
+ ) : null}
285
+ </div>
286
+ ) : null}
287
+ {connected && provider && oauth?.[provider]?.email ? (
288
+ <p className="auto-step-detail">Connected as {oauth[provider]?.email}.</p>
289
+ ) : null}
290
+
291
+ {isSchedule ? <p className={"auto-tick-note " + note.tone}>{note.text}</p> : null}
292
+ <p className="auto-step-detail">
293
+ {/*
294
+ ⚠ "NEXT RUN 12:30" IS A PROMISE, AND IT IS ONLY TRUE IF SOMETHING TICKS. The
295
+ server computes the next fire from the cron alone β€” it does not know whether a
296
+ scheduler is running β€” so printing it flat beside a line that has just said
297
+ "schedules won't fire" is the surface contradicting itself twice over.
298
+ */}
299
+ {isSchedule
300
+ ? nextRunAt
301
+ ? tick && tick.enabled === false
302
+ ? `It would run next at ${nextRunAt}, once a scheduler is running.`
303
+ : `Next run ${nextRunAt}.`
304
+ : "Schedules start from the moment they are switched on β€” turning on a daily job after today's time does not fire it today."
305
+ : current === "manual"
306
+ ? "It runs when you press Run now, and nothing else starts it."
307
+ : /*
308
+ β›” NOTHING. This line printed `It runs when ${label.toLowerCase()}` and the
309
+ server's label is "When an email arrives" β€” so the screen read "It runs when
310
+ when an email arrives". Composing a sentence out of somebody else's label is
311
+ how that happens, and the repair is not a better composition: the field above
312
+ is LABELLED "When it runs" and the picker already says the answer, so a
313
+ caption restating it was over-explaining even when it was grammatical (R13).
314
+ */
315
+ ""}
316
+ </p>
317
+ </>
318
+ );
319
+ }
web/src/automation/automationApi.ts CHANGED
@@ -1,378 +1,667 @@
1
- // ---------------------------------------------------------------------------
2
- // automation/automationApi.ts β€” the Automation surface's whole data layer.
3
- //
4
- // Wave-18 item 5 (contracts C4-AUTO + C-AUTONAV). Deliberately its own leaf
5
- // rather than an addition to `customer-grid/apiBridge.ts`: the grid tree is the
6
- // ASSET that also ships inside the Streamlit embed, and an automation surface
7
- // that only the standalone shell mounts must not grow an edge into it. It
8
- // imports `apiContract` (the shared leaf both trees already read) and nothing
9
- // else.
10
- //
11
- // ⚠ EVERY VOCABULARY HERE COMES FROM THE SERVER. The kind list and the cron
12
- // presets ride on `GET /automations` rather than sitting in a client constant,
13
- // because the parser that accepts a cron string lives in Python β€” a client copy
14
- // of the preset list is a list that can offer a schedule the server rejects,
15
- // and the user would see the refusal as "it just doesn't save".
16
- // ---------------------------------------------------------------------------
17
- import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, signal } from "../apiContract";
18
-
19
- export type AutomationKind = "scrape_db" | "field_instagram" | "discover_instagram";
20
- export type RunState = "idle" | "running" | "ok" | "error" | "partial";
21
- /**
22
- * ⚠ `hiker` is NOT in this union any more (wave 20, D-21) β€” the vendor moved.
23
- * Stored configs still SAY `hiker` and the server maps them forward
24
- * (`TIER_ALIASES`), so nothing in this client should ever write that word.
25
- */
26
- export type CaptureTier = "anonymous" | "brightdata";
27
-
28
- /**
29
- * A node's dot. Deliberately WIDER than `RunState` β€” a single step can be
30
- * `blocked` (a rung refused) or `skipped` (a switch is off) in ways a whole run
31
- * cannot, and folding those into `partial` would throw away the only thing the
32
- * dot is there to say.
33
- */
34
- export type NodeState = "idle" | "ok" | "partial" | "error" | "blocked" | "skipped";
35
-
36
- /**
37
- * ⚠ THE GRAPH IS THE SERVER'S, not this client's. `engine.graph()` derives it
38
- * from the definition, in the same module that RUNS the steps β€” so the surface
39
- * cannot show a step the engine stopped executing. This file only types it and
40
- * `steps.ts` only numbers it; nothing here decides what the nodes are.
41
- * (It said `canvasLayout.ts` until wave 21 replaced the canvas with numbered
42
- * Steps β€” R9. Stale prose about a deleted mount is a hazard, not a footnote.)
43
- * (Same rule as `cronPresets` and `kinds`, for the same reason.)
44
- */
45
- export interface GraphNode {
46
- id: string;
47
- kind: "trigger" | "source" | "capture" | "branch" | "write";
48
- title: string;
49
- subtitle: string;
50
- detail: string;
51
- col: number;
52
- row: number;
53
- /** Which config panel this node opens. */
54
- panel: string;
55
- enabled: boolean;
56
- /** Non-empty = this node has a REAL switch. Empty = it is always on, by nature. */
57
- toggle: string;
58
- status: NodeState;
59
- }
60
-
61
- export interface GraphEdge {
62
- from: string;
63
- to: string;
64
- label: string;
65
- }
66
-
67
- export interface AutomationGraph {
68
- nodes: GraphNode[];
69
- edges: GraphEdge[];
70
- }
71
-
72
- export interface RunEntry {
73
- ts: string;
74
- ok: boolean;
75
- summary: string;
76
- counts: Record<string, number>;
77
- /** Per-node outcomes, MEASURED as the run walked. Absent on runs stored before W19-C. */
78
- steps?: Record<string, NodeState>;
79
- affected?: string[];
80
- }
81
-
82
- export interface Automation {
83
- id: string;
84
- name: string;
85
- kind: AutomationKind;
86
- config: Record<string, unknown>;
87
- schedule: { cron: string; enabled: boolean; enabledAt?: string };
88
- status: { state: RunState; lastRunAt?: string; lastSummary?: string; step?: string };
89
- runs: RunEntry[];
90
- created?: string;
91
- createdBy?: string;
92
- nextRunAt?: string;
93
- running?: boolean;
94
- graph: AutomationGraph;
95
- }
96
-
97
- export interface AutomationList {
98
- automations: Automation[];
99
- kinds: { key: AutomationKind; label: string }[];
100
- cronPresets: { cron: string; label: string }[];
101
- /**
102
- * Is `AIOS_BRIGHTDATA_KEY` configured on the server? A BOOLEAN, never the key β€”
103
- * the surface needs to say "the paid rung is not configured" honestly rather
104
- * than offering a tier that will silently refuse.
105
- */
106
- paidReady: boolean;
107
- /**
108
- * THE SOURCE REGISTRY (DEBT D-9's seam). Server-declared, for the reason
109
- * `cronPresets` is: the module that RUNS a source is the only thing entitled
110
- * to say what it can do, and a client copy of "Instagram can discover,
111
- * TikTok cannot" goes stale in silence. `canDiscover: false` is an honest
112
- * statement, not a gap β€” offering the button anyway offers a refusal.
113
- */
114
- sources: SourceStatus[];
115
- /** The discovery vocabulary β€” every name MEASURED-accepted by the vendor. */
116
- discover: DiscoverVocab;
117
- /**
118
- * ⚠ CAN A SCHEDULE ACTUALLY FIRE ON THIS DEPLOYMENT? (R9's honest switch; wave-21 C6
119
- * amendment #1.) OPTIONAL because it is genuinely absent until the server ships it β€” and
120
- * that absence is a THIRD state the card prints out loud ("not reported"), never a silent
121
- * fallback to either answer. An optional field that a UI treats as `false` is how a page
122
- * starts stating a measurement nobody made.
123
- *
124
- * TWO independent paths fire schedules and a single boolean cannot describe them: the
125
- * in-process scheduler (`AIOS_AUTOMATIONS=1`) and an external cron POSTing
126
- * `/automations/tick` with the shared token β€” the AWS EventBridge tick is live
127
- * ([[aws-automation-cron]]), so "the in-process one is off" is not "schedules won't fire".
128
- */
129
- tick?: TickState;
130
- storeAvailable: boolean;
131
- }
132
-
133
- export interface TickState {
134
- enabled: boolean;
135
- /** Which path. `external` means the door is OPEN, never that the caller is alive. */
136
- source?: "in-process" | "external" | "";
137
- }
138
-
139
- export interface SourceStatus {
140
- key: string;
141
- label: string;
142
- vendor: string;
143
- ready: boolean;
144
- canDiscover: boolean;
145
- }
146
-
147
- export interface DiscoverVocab {
148
- fields: string[];
149
- /**
150
- * The subset seen carrying VALUES on real corpus rows. The others are
151
- * filterable and were null on every row measured β€” and a filter on an
152
- * unpopulated field returns nothing while looking exactly like "no such
153
- * influencers exist".
154
- */
155
- lead: string[];
156
- operators: string[];
157
- nullaryOperators: string[];
158
- maxRecords: number;
159
- table: string;
160
- }
161
-
162
- /**
163
- * ⚠ AN ESTIMATE, AND IT CARRIES ITS OWN CAVEAT (`basis: "SPEC"`). Bright Data
164
- * never quotes a price before a run, and this account's token cannot read a
165
- * balance β€” so no surface may present this as a billed figure.
166
- */
167
- export interface DiscoverEstimate {
168
- records: number;
169
- usd: number;
170
- unitUsd: number;
171
- basis: string;
172
- note: string;
173
- }
174
-
175
- export interface UserTable {
176
- key: string;
177
- label: string;
178
- source: string;
179
- rowCount: number;
180
- fields: { key: string; label: string; type: string; automation?: unknown }[];
181
- }
182
-
183
- export interface SourcePreview {
184
- ok: boolean;
185
- status: number;
186
- url: string;
187
- title?: string;
188
- note?: string;
189
- columns: string[];
190
- sample: Record<string, string>[];
191
- rowCount: number;
192
- tableCount?: number;
193
- }
194
-
195
- export interface RunRows {
196
- table: string;
197
- label: string;
198
- fields: { key: string; label: string }[];
199
- rows: Record<string, string>[];
200
- truncated: boolean;
201
- }
202
-
203
- export class AutomationError extends Error {
204
- status: number;
205
-
206
- constructor(message: string, status: number) {
207
- super(message);
208
- this.name = "AutomationError";
209
- this.status = status;
210
- }
211
- }
212
-
213
- async function result<T>(response: Response): Promise<T> {
214
- let body: unknown = null;
215
- try {
216
- body = await response.json();
217
- } catch {
218
- // The status is still an honest answer; the message below says so.
219
- }
220
- if (response.status === 401) signal(UNAUTHORIZED_EVENT);
221
- if (!response.ok) {
222
- const shaped = body as { error?: { message?: string } } | null;
223
- throw new AutomationError(
224
- shaped?.error?.message || `The server answered ${response.status}.`,
225
- response.status
226
- );
227
- }
228
- return body as T;
229
- }
230
-
231
- function send<T>(path: string, init?: RequestInit): Promise<T> {
232
- return fetch(`${API_V1}${path}`, {
233
- credentials: CREDENTIALS,
234
- headers: init?.body ? { "Content-Type": "application/json" } : undefined,
235
- ...init,
236
- }).then((r) => result<T>(r));
237
- }
238
-
239
- export function listAutomations(abort?: AbortSignal): Promise<AutomationList> {
240
- return send<AutomationList>("/automations", { signal: abort });
241
- }
242
-
243
- export function listTables(abort?: AbortSignal): Promise<{ tables: UserTable[] }> {
244
- return send<{ tables: UserTable[] }>("/automations/tables", { signal: abort });
245
- }
246
-
247
- export function createAutomation(body: unknown): Promise<{ automation: Automation }> {
248
- return send("/automations", { method: "POST", body: JSON.stringify(body) });
249
- }
250
-
251
- export function patchAutomation(
252
- id: string,
253
- body: unknown
254
- ): Promise<{ automation: Automation }> {
255
- return send(`/automations/${encodeURIComponent(id)}`, {
256
- method: "PATCH",
257
- body: JSON.stringify(body),
258
- });
259
- }
260
-
261
- export function deleteAutomation(id: string): Promise<{ deleted: string }> {
262
- return send(`/automations/${encodeURIComponent(id)}`, { method: "DELETE" });
263
- }
264
-
265
- export function runAutomation(id: string): Promise<{ started: string }> {
266
- return send(`/automations/${encodeURIComponent(id)}/run`, { method: "POST" });
267
- }
268
-
269
- /**
270
- * Flip one step's switch.
271
- *
272
- * The client says WHICH NODE was clicked and nothing else β€” the server owns what
273
- * each switch means (`engine.NODE_TOGGLES`). A client that knew "the Bright Data
274
- * node writes config.tier" would be a second copy of that knowledge, free to
275
- * drift from the engine that reads it β€” and it would have had to be rewritten
276
- * when the vendor changed. It did not.
277
- */
278
- export function toggleNode(
279
- id: string,
280
- nodeId: string
281
- ): Promise<{ automation: Automation }> {
282
- return send(
283
- `/automations/${encodeURIComponent(id)}/nodes/${encodeURIComponent(nodeId)}/toggle`,
284
- { method: "POST" }
285
- );
286
- }
287
-
288
- export function getAutomation(id: string): Promise<{ automation: Automation }> {
289
- return send(`/automations/${encodeURIComponent(id)}`);
290
- }
291
-
292
- export function runRows(id: string): Promise<RunRows> {
293
- return send(`/automations/${encodeURIComponent(id)}/rows`);
294
- }
295
-
296
- /** What would a search of this size cost? Asked BEFORE the run, never after. */
297
- export function discoverEstimate(recordsLimit: number): Promise<DiscoverEstimate> {
298
- return send("/automations/discover/estimate", {
299
- method: "POST",
300
- body: JSON.stringify({ recordsLimit }),
301
- });
302
- }
303
-
304
- export function previewSource(
305
- url: string,
306
- extract: string,
307
- tableIndex: number
308
- ): Promise<SourcePreview> {
309
- return send("/automations/preview", {
310
- method: "POST",
311
- body: JSON.stringify({ url, extract, tableIndex }),
312
- });
313
- }
314
-
315
- /**
316
- * A source column name β†’ a storable field key. Mirrors the server's own
317
- * normalisation (`clean_config`) so the key the UI shows is the key that gets
318
- * stored β€” a preview that promised `gics_sector` and a store that wrote
319
- * `gics__sector` would look like data loss.
320
- */
321
- export function fieldKeyFor(column: string): string {
322
- return (column || "")
323
- .toLowerCase()
324
- .replace(/[^a-z0-9_]+/g, "_")
325
- .replace(/^_+|_+$/g, "")
326
- .slice(0, 60);
327
- }
328
-
329
- /** The state word a status dot / chip paints from. */
330
- export function stateOf(a: Automation): RunState {
331
- return a.running ? "running" : (a.status?.state as RunState) || "idle";
332
- }
333
-
334
- /**
335
- * A run's counts as ordered label/value pairs. The ORDER is the sentence the
336
- * numbers make β€” new, updated, unchanged, then the ones that need explaining β€”
337
- * and `orphans` is spelled out rather than abbreviated because a bare number
338
- * next to the word "orphans" is the one count a user must not have to guess at.
339
- */
340
- export const COUNT_LABELS: [string, string][] = [
341
- ["inserted", "New"],
342
- ["updated", "Updated"],
343
- ["unchanged", "Unchanged"],
344
- ["orphans", "No longer on the page (kept)"],
345
- ["duplicates", "Duplicate keys"],
346
- ["skipped", "Skipped (no key)"],
347
- // ⚠ ITS OWN CHIP, next to `skipped` but never merged with it. "Skipped" is a
348
- // property of the data and usually benign; "not written β€” the database is
349
- // full" is a property of the system and never is. One chip for both is how a
350
- // time series stops growing without anybody being told.
351
- ["capped", "Not written β€” the database is full"],
352
- ["source_rows", "Rows read"],
353
- ["profiles", "Profiles"],
354
- ["ok", "Read in full"],
355
- // ⚠ ADDED after reading the first live screenshot. The engine counts `partial` separately
356
- // (profile read, media not anonymously readable) but this table did not, so a run whose
357
- // summary said "1/1 profiles read" showed a chip row reading "0 Read" β€” the chips
358
- // contradicting the sentence directly above them. A count the summary names must have a chip.
359
- ["partial", "Profile only"],
360
- ["blocked", "Blocked"],
361
- ["error", "Errors"],
362
- ["paid", "Exact via Bright Data"],
363
- ["posts", "Posts"],
364
- ["new_posts", "New posts"],
365
- // The engagement series only grows while the per-post rung is on, so its
366
- // count is its own chip β€” "12 posts" and "0 engagement snapshots" together
367
- // are the honest picture of a profile-only run.
368
- ["metrics", "Engagement snapshots"],
369
- // Discovery.
370
- ["asked", "Asked for"],
371
- ["found", "Profiles found"],
372
- ["new", "New to us"],
373
- ["seen_again", "Seen before"],
374
- ["dropped", "Returned but unusable (no handle)"],
375
- // ⚠ Its own chip for the same reason `capped` has one: a database that could
376
- // not be CREATED is a system fact, and the run that hit it wrote nothing.
377
- ["missing_tables", "Databases that could not be created"],
378
- ];
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // ---------------------------------------------------------------------------
2
+ // automation/automationApi.ts β€” the Automation surface's whole data layer.
3
+ //
4
+ // Wave-18 item 5 (contracts C4-AUTO + C-AUTONAV). Deliberately its own leaf
5
+ // rather than an addition to `customer-grid/apiBridge.ts`: the grid tree is the
6
+ // ASSET that also ships inside the Streamlit embed, and an automation surface
7
+ // that only the standalone shell mounts must not grow an edge into it. It
8
+ // imports `apiContract` (the shared leaf both trees already read) and nothing
9
+ // else.
10
+ //
11
+ // ⚠ EVERY VOCABULARY HERE COMES FROM THE SERVER. The kind list and the cron
12
+ // presets ride on `GET /automations` rather than sitting in a client constant,
13
+ // because the parser that accepts a cron string lives in Python β€” a client copy
14
+ // of the preset list is a list that can offer a schedule the server rejects,
15
+ // and the user would see the refusal as "it just doesn't save".
16
+ // ---------------------------------------------------------------------------
17
+ import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, signal } from "../apiContract";
18
+
19
+ export type AutomationKind = "scrape_db" | "field_instagram" | "discover_instagram";
20
+ export type RunState = "idle" | "running" | "ok" | "error" | "partial";
21
+ /**
22
+ * ⚠ `hiker` is NOT in this union any more (wave 20, D-21) β€” the vendor moved.
23
+ * Stored configs still SAY `hiker` and the server maps them forward
24
+ * (`TIER_ALIASES`), so nothing in this client should ever write that word.
25
+ */
26
+ export type CaptureTier = "anonymous" | "brightdata";
27
+
28
+ /**
29
+ * A node's dot. Deliberately WIDER than `RunState` β€” a single step can be
30
+ * `blocked` (a rung refused) or `skipped` (a switch is off) in ways a whole run
31
+ * cannot, and folding those into `partial` would throw away the only thing the
32
+ * dot is there to say.
33
+ */
34
+ export type NodeState = "idle" | "ok" | "partial" | "error" | "blocked" | "skipped";
35
+
36
+ /**
37
+ * ⚠ THE GRAPH IS THE SERVER'S, not this client's. `engine.graph()` derives it
38
+ * from the definition, in the same module that RUNS the steps β€” so the surface
39
+ * cannot show a step the engine stopped executing. This file only types it and
40
+ * `steps.ts` only numbers it; nothing here decides what the nodes are.
41
+ * (It said `canvasLayout.ts` until wave 21 replaced the canvas with numbered
42
+ * Steps β€” R9; wave 22 DELETED both canvas files, since the board supersedes the
43
+ * rebuild question they were being kept for. Stale prose about a deleted mount
44
+ * is a hazard, not a footnote.)
45
+ * (Same rule as `cronPresets` and `kinds`, for the same reason.)
46
+ */
47
+ export interface GraphNode {
48
+ id: string;
49
+ kind: "trigger" | "source" | "capture" | "branch" | "write";
50
+ title: string;
51
+ subtitle: string;
52
+ detail: string;
53
+ col: number;
54
+ row: number;
55
+ /** Which config panel this node opens. */
56
+ panel: string;
57
+ enabled: boolean;
58
+ /** Non-empty = this node has a REAL switch. Empty = it is always on, by nature. */
59
+ toggle: string;
60
+ status: NodeState;
61
+ }
62
+
63
+ export interface GraphEdge {
64
+ from: string;
65
+ to: string;
66
+ label: string;
67
+ }
68
+
69
+ export interface AutomationGraph {
70
+ nodes: GraphNode[];
71
+ edges: GraphEdge[];
72
+ }
73
+
74
+ export interface RunEntry {
75
+ ts: string;
76
+ ok: boolean;
77
+ summary: string;
78
+ counts: Record<string, number>;
79
+ /** Per-node outcomes, MEASURED as the run walked. Absent on runs stored before W19-C. */
80
+ steps?: Record<string, NodeState>;
81
+ affected?: string[];
82
+ }
83
+
84
+ export interface Automation {
85
+ id: string;
86
+ name: string;
87
+ kind: AutomationKind;
88
+ config: Record<string, unknown>;
89
+ schedule: { cron: string; enabled: boolean; enabledAt?: string };
90
+ status: { state: RunState; lastRunAt?: string; lastSummary?: string; step?: string };
91
+ runs: RunEntry[];
92
+ created?: string;
93
+ createdBy?: string;
94
+ nextRunAt?: string;
95
+ running?: boolean;
96
+ graph: AutomationGraph;
97
+ /**
98
+ * WAVE 22 / C3 β€” WHAT STARTS THIS ONE, as a key from the server's `triggers`
99
+ * list. OPTIONAL: until the engine stores a trigger the only two shapes a
100
+ * definition can express are `schedule.enabled` true/false, and the picker
101
+ * derives those rather than inventing a third answer.
102
+ */
103
+ trigger?: { key: string; ready?: boolean; needs?: string };
104
+ /**
105
+ * The review gate's decisions, newest first (<=100). A promotion is a person's
106
+ * judgement written into a record, so it says WHO β€” the same reason every count in
107
+ * this product drills to its rows.
108
+ */
109
+ reviews?: ReviewEntry[];
110
+ }
111
+
112
+ export interface AutomationList {
113
+ automations: Automation[];
114
+ kinds: { key: AutomationKind; label: string }[];
115
+ cronPresets: { cron: string; label: string }[];
116
+ /**
117
+ * Is `AIOS_BRIGHTDATA_KEY` configured on the server? A BOOLEAN, never the key β€”
118
+ * the surface needs to say "the paid rung is not configured" honestly rather
119
+ * than offering a tier that will silently refuse.
120
+ */
121
+ paidReady: boolean;
122
+ /**
123
+ * THE SOURCE REGISTRY (DEBT D-9's seam). Server-declared, for the reason
124
+ * `cronPresets` is: the module that RUNS a source is the only thing entitled
125
+ * to say what it can do, and a client copy of "Instagram can discover,
126
+ * TikTok cannot" goes stale in silence. `canDiscover: false` is an honest
127
+ * statement, not a gap β€” offering the button anyway offers a refusal.
128
+ */
129
+ sources: SourceStatus[];
130
+ /** The discovery vocabulary β€” every name MEASURED-accepted by the vendor. */
131
+ discover: DiscoverVocab;
132
+ /**
133
+ * ⚠ CAN A SCHEDULE ACTUALLY FIRE ON THIS DEPLOYMENT? (R9's honest switch; wave-21 C6
134
+ * amendment #1.) OPTIONAL because it is genuinely absent until the server ships it β€” and
135
+ * that absence is a THIRD state the card prints out loud ("not reported"), never a silent
136
+ * fallback to either answer. An optional field that a UI treats as `false` is how a page
137
+ * starts stating a measurement nobody made.
138
+ *
139
+ * TWO independent paths fire schedules and a single boolean cannot describe them: the
140
+ * in-process scheduler (`AIOS_AUTOMATIONS=1`) and an external cron POSTing
141
+ * `/automations/tick` with the shared token β€” the AWS EventBridge tick is live
142
+ * ([[aws-automation-cron]]), so "the in-process one is off" is not "schedules won't fire".
143
+ */
144
+ tick?: TickState;
145
+ /**
146
+ * WAVE 22 / C3 β€” THE TRIGGER VOCABULARY, and it is the server's whole answer to
147
+ * "what can start an automation".
148
+ *
149
+ * β›” NO CLIENT UNION OVER `key`. The contract names six keys today
150
+ * (manual, schedule, event_field, record_created, webhook, email) and the
151
+ * picker must not carry a copy of that list: a client union means the two lists
152
+ * can diverge, and the way they diverge is SILENT β€” the server offers a trigger
153
+ * the client has no arm for and simply does not draw it, which is the wave-9
154
+ * silent-drop class. The picker maps the array.
155
+ *
156
+ * OPTIONAL because it is genuinely absent until the engine ships it, and absent
157
+ * is a third state: with no list, the trigger face falls back to the schedule
158
+ * controls that already exist rather than rendering an empty dropdown.
159
+ */
160
+ triggers?: TriggerOption[];
161
+ storeAvailable: boolean;
162
+ }
163
+
164
+ export interface TriggerOption {
165
+ key: string;
166
+ label: string;
167
+ /**
168
+ * Can this deployment actually run it? `false` is not a reason to hide the
169
+ * option β€” a trigger nobody can pick still ANSWERS the question "can it run
170
+ * when an email arrives", which a missing row does not, and which then gets
171
+ * asked again (the R9 precedent: the disabled "when a field changes" slot).
172
+ */
173
+ ready: boolean;
174
+ /** What it is waiting for, e.g. `"connect_gmail"`. Rendered as a next step, never as an error. */
175
+ needs?: string;
176
+ }
177
+
178
+ export interface OAuthConnection {
179
+ connected: boolean;
180
+ email?: string;
181
+ }
182
+
183
+ /**
184
+ * C5's per-user connector state, keyed by PROVIDER (`google` today).
185
+ *
186
+ * A record and not an interface with a `google` field, for C3's reason one level
187
+ * down: the provider list is the server's β€” R12 says Google first and the rest
188
+ * "one by one, next waves" β€” and a client shape that names one provider has to
189
+ * be edited to see the second. This one does not.
190
+ */
191
+ export type OAuthStatus = Record<string, OAuthConnection | undefined>;
192
+
193
+ /**
194
+ * A trigger's `needs` token β†’ the connector it is waiting on.
195
+ *
196
+ * ⚠ THE ONE PLACE A SERVER TOKEN BECOMES A ROUTE, and it is deliberately tiny and
197
+ * deliberately FAIL-QUIET-BUT-VISIBLE: an unknown token resolves to "", the connect
198
+ * BUTTON is not drawn, and the not-configured state is still stated in words. A
199
+ * button that navigates nowhere is worse than no button β€” it reads as a broken
200
+ * product rather than an unfinished one.
201
+ *
202
+ * DEBT: this table disappears the day a `TriggerOption` carries its own provider or
203
+ * start URL. Booked in the wave-22 mailbox as a question for the engine session.
204
+ */
205
+ const CONNECT_PROVIDERS: Record<string, string> = { connect_gmail: "google" };
206
+
207
+ export function oauthProviderFor(needs: string): string {
208
+ return CONNECT_PROVIDERS[String(needs || "")] || "";
209
+ }
210
+
211
+ export function oauthStartUrlFor(needs: string): string {
212
+ const provider = oauthProviderFor(needs);
213
+ return provider ? `${API_V1}/oauth/${provider}/start` : "";
214
+ }
215
+
216
+ export interface TickState {
217
+ enabled: boolean;
218
+ /** Which path. `external` means the door is OPEN, never that the caller is alive. */
219
+ source?: "in-process" | "external" | "";
220
+ }
221
+
222
+ export interface SourceStatus {
223
+ key: string;
224
+ label: string;
225
+ vendor: string;
226
+ ready: boolean;
227
+ canDiscover: boolean;
228
+ }
229
+
230
+ export interface DiscoverVocab {
231
+ fields: string[];
232
+ /**
233
+ * The subset seen carrying VALUES on real corpus rows. The others are
234
+ * filterable and were null on every row measured β€” and a filter on an
235
+ * unpopulated field returns nothing while looking exactly like "no such
236
+ * influencers exist".
237
+ */
238
+ lead: string[];
239
+ operators: string[];
240
+ nullaryOperators: string[];
241
+ maxRecords: number;
242
+ table: string;
243
+ /**
244
+ * WAVE 22 / C4 β€” per-field facts, one entry per name in `fields`.
245
+ *
246
+ * ⚠ OPTIONAL ON PURPOSE, and it must never be read as "everything is
247
+ * unpopulated". It is genuinely absent until the engine ships it, and absent
248
+ * is a THIRD state: the toggle list falls back to `lead` (which says the same
249
+ * thing about the three fields it names and nothing at all about the other
250
+ * eighteen) and prints no claim about the rest. The `tick` field on
251
+ * `AutomationList` is the precedent and the reason β€” an optional field a UI
252
+ * defaults to `false` is how a surface starts stating a measurement nobody
253
+ * made.
254
+ */
255
+ filterMeta?: DiscoverFieldMeta[];
256
+ /** WAVE 22 / C4 β€” the too-big guard's PARAMETERS. The DECISION stays server-side; see below. */
257
+ guard?: DiscoverGuard;
258
+ }
259
+
260
+ export interface DiscoverFieldMeta {
261
+ name: string;
262
+ /** Seen carrying values on real corpus rows. */
263
+ populated: boolean;
264
+ /** A condition on this field actually cuts the corpus down. */
265
+ narrowing: boolean;
266
+ }
267
+
268
+ /**
269
+ * β›” PARAMETERS, NOT A RULE THE CLIENT RE-IMPLEMENTS (C4).
270
+ *
271
+ * The server refuses a filter with no narrowing predicate, and it refuses it at
272
+ * create, at patch AND at run β€” with a sentence naming why. This client renders
273
+ * those numbers as *facts about the fields* (which ones narrow, which have
274
+ * values) and renders the REFUSAL VERBATIM when it comes back. It does not
275
+ * predict the refusal, because a second copy of the rule is a copy that can
276
+ * disagree: a client that blocks Save on its own arithmetic can block a filter
277
+ * the server would have accepted, and the user cannot tell which of the two is
278
+ * wrong. Same reason `cronPresets` are not a client constant.
279
+ */
280
+ export interface DiscoverGuard {
281
+ minNarrowing: number;
282
+ maxRecords: number;
283
+ }
284
+
285
+ /**
286
+ * ONE condition of a corpus search. Mirrors the server's `clean_predicates`
287
+ * shape exactly β€” `{name, operator}` plus a `value` for every operator that is
288
+ * not nullary.
289
+ */
290
+ export interface Predicate {
291
+ name: string;
292
+ operator: string;
293
+ value?: string | number;
294
+ }
295
+
296
+ /**
297
+ * ⚠ AN ESTIMATE, AND IT CARRIES ITS OWN CAVEAT (`basis: "SPEC"`). Bright Data
298
+ * never quotes a price before a run, and this account's token cannot read a
299
+ * balance β€” so no surface may present this as a billed figure.
300
+ */
301
+ export interface DiscoverEstimate {
302
+ records: number;
303
+ usd: number;
304
+ unitUsd: number;
305
+ basis: string;
306
+ note: string;
307
+ }
308
+
309
+ export interface UserTable {
310
+ key: string;
311
+ label: string;
312
+ source: string;
313
+ rowCount: number;
314
+ fields: { key: string; label: string; type: string; automation?: unknown }[];
315
+ }
316
+
317
+ export interface SourcePreview {
318
+ ok: boolean;
319
+ status: number;
320
+ url: string;
321
+ title?: string;
322
+ note?: string;
323
+ columns: string[];
324
+ sample: Record<string, string>[];
325
+ rowCount: number;
326
+ tableCount?: number;
327
+ }
328
+
329
+ export interface RunRows {
330
+ table: string;
331
+ label: string;
332
+ fields: { key: string; label: string }[];
333
+ rows: Record<string, string>[];
334
+ truncated: boolean;
335
+ }
336
+
337
+ // ── WAVE 22 / contract C1: THE BOARD ──────────────────────────────────────────
338
+ //
339
+ // R1's model, stated once: an automation IS a kanban board. The columns are the
340
+ // flow's stages, the CARDS ARE RECORDS of the target database, and a record's
341
+ // position is stored in a single-select stage field on that database β€” so the
342
+ // same field also drives a plain Kanban view, and the board is not a second,
343
+ // private idea of where a record is.
344
+ //
345
+ // ⚠ EVERY VOCABULARY BELOW IS `string`, DELIBERATELY. `kind` is
346
+ // trigger|action|review|branch today and `posture` is auto|strict, and both are
347
+ // typed loose for the reason contract C3 gives about trigger keys: a client
348
+ // union over a server enumeration is a list that can go stale, and the failure
349
+ // mode is SILENT β€” a `switch` with no arm for a new value renders nothing at all
350
+ // and the surface simply stops showing a stage the engine is running (the wave-9
351
+ // silent-drop class). Rendering falls back to a neutral face for anything
352
+ // unrecognised, which is visible.
353
+
354
+ export interface BoardStage {
355
+ /** For a stage backed by an engine node this IS that node's id (C1 amendment 1). */
356
+ id: string;
357
+ label: string;
358
+ /** `trigger` | `action` | `review` | `branch` β€” see the note above on why it is not a union. */
359
+ kind: string;
360
+ col: number;
361
+ row: number;
362
+ enabled: boolean;
363
+ /** Non-empty = this stage has a REAL switch. Empty = it is always on, by nature. */
364
+ toggle: string;
365
+ /** The `NodeState` words. Painted by class, never matched exhaustively. */
366
+ status: string;
367
+ detail: string;
368
+ /**
369
+ * R7's approval-posture vocabulary, adopted from QM: `strict` = the stage holds
370
+ * for a human, `auto` = the engine advances the record itself.
371
+ */
372
+ posture: string;
373
+ /**
374
+ * ⭐ THE JOIN KEY FOR THE CONFIG PANEL (C1 amendment 1, 2026-08-05). A stage
375
+ * backed by an engine node carries that node's `panel` verbatim; review stages
376
+ * carry `"review"`. The amendment is explicit that B joins on THIS and never on
377
+ * a guessed id equality β€” a panel picked by a key that only usually matches is
378
+ * a surface that shows the wrong settings while looking completely correct.
379
+ */
380
+ panel: string;
381
+ /**
382
+ * ⭐ MAY THIS STAGE HOLD CARDS? (A's CP1, additive to C1 β€” 2026-08-05.) A discovery
383
+ * flow's `find`/`collect`/`write` are things the automation DOES, not places a record
384
+ * sits, and drawing them as lanes would put three permanently empty columns between
385
+ * the trigger and the first real one. They render as the process strip instead.
386
+ *
387
+ * ⚠ OPTIONAL, AND ABSENT MEANS LANE. A server that ships C1's contract text and not
388
+ * this field describes every stage as a place β€” which is what the earlier board did β€”
389
+ * so `undefined` keeps that behaviour and only an explicit `false` moves a stage into
390
+ * the strip. Defaulting an absent field to `false` would empty the board against a
391
+ * server that never said anything of the kind.
392
+ */
393
+ record?: boolean;
394
+ /**
395
+ * May a card be PLACED here β€” i.e. is this stage's label a choice of the stage field?
396
+ * `record && !assignable` is a DERIVED bucket: cards appear from what is true about the
397
+ * row, and nothing may stamp one into it. Such a lane takes no drop.
398
+ */
399
+ assignable?: boolean;
400
+ }
401
+
402
+ export interface BoardRoute {
403
+ from: string;
404
+ to: string;
405
+ /** Server-composed. Falls back to the condition's own words when empty. */
406
+ label: string;
407
+ /** `null` = an unconditional next, which needs no label at all (R5). */
408
+ condition: { field: string; op: string; value?: string | number } | null;
409
+ }
410
+
411
+ export interface BoardCard {
412
+ rowId: string;
413
+ stageId: string;
414
+ /**
415
+ * ⚠ SERVER-COMPOSED STRINGS (C1 amendment 3). The board does NO client-side
416
+ * field formatting β€” it has no field contract for the target database and
417
+ * inventing one would mean a second formatter disagreeing with the grid's.
418
+ */
419
+ title: string;
420
+ sub: string;
421
+ movedAt: string;
422
+ /** The SERVER's answer to "may this move", not a permission the client derives. */
423
+ canAdvance: boolean;
424
+ next: string[];
425
+ }
426
+
427
+ export interface Board {
428
+ stages: BoardStage[];
429
+ routes: BoardRoute[];
430
+ cards: BoardCard[];
431
+ /** `null` = no stage field bound yet. An empty board is a STATE, not an error (C1 amendment 2). */
432
+ stageField: { table: string; key: string } | null;
433
+ /**
434
+ * The TRUE per-stage totals. `cards` may be capped by the server, so a lane
435
+ * whose count exceeds its cards discloses the difference rather than showing a
436
+ * short list as if it were the whole one ([[no-unverifiable-aggregates]]).
437
+ */
438
+ counts: Record<string, number>;
439
+ /**
440
+ * Stages whose `cards` were capped on the wire (200/stage). `counts` always carries the
441
+ * TRUE total, so the lane can state the difference rather than showing a short list as
442
+ * if it were the whole one ([[no-unverifiable-aggregates]]).
443
+ */
444
+ truncated?: string[];
445
+ }
446
+
447
+ /** One human decision at a review gate β€” R7's approval posture, audited (A2(5)). */
448
+ export interface ReviewEntry {
449
+ ts: string;
450
+ user: string;
451
+ rowId: string;
452
+ from: string;
453
+ to: string;
454
+ }
455
+
456
+ export class AutomationError extends Error {
457
+ status: number;
458
+
459
+ constructor(message: string, status: number) {
460
+ super(message);
461
+ this.name = "AutomationError";
462
+ this.status = status;
463
+ }
464
+ }
465
+
466
+ async function result<T>(response: Response): Promise<T> {
467
+ let body: unknown = null;
468
+ try {
469
+ body = await response.json();
470
+ } catch {
471
+ // The status is still an honest answer; the message below says so.
472
+ }
473
+ if (response.status === 401) signal(UNAUTHORIZED_EVENT);
474
+ if (!response.ok) {
475
+ const shaped = body as { error?: { message?: string } } | null;
476
+ throw new AutomationError(
477
+ shaped?.error?.message || `The server answered ${response.status}.`,
478
+ response.status
479
+ );
480
+ }
481
+ return body as T;
482
+ }
483
+
484
+ function send<T>(path: string, init?: RequestInit): Promise<T> {
485
+ return fetch(`${API_V1}${path}`, {
486
+ credentials: CREDENTIALS,
487
+ headers: init?.body ? { "Content-Type": "application/json" } : undefined,
488
+ ...init,
489
+ }).then((r) => result<T>(r));
490
+ }
491
+
492
+ export function listAutomations(abort?: AbortSignal): Promise<AutomationList> {
493
+ return send<AutomationList>("/automations", { signal: abort });
494
+ }
495
+
496
+ export function listTables(abort?: AbortSignal): Promise<{ tables: UserTable[] }> {
497
+ return send<{ tables: UserTable[] }>("/automations/tables", { signal: abort });
498
+ }
499
+
500
+ export function createAutomation(body: unknown): Promise<{ automation: Automation }> {
501
+ return send("/automations", { method: "POST", body: JSON.stringify(body) });
502
+ }
503
+
504
+ export function patchAutomation(
505
+ id: string,
506
+ body: unknown
507
+ ): Promise<{ automation: Automation }> {
508
+ return send(`/automations/${encodeURIComponent(id)}`, {
509
+ method: "PATCH",
510
+ body: JSON.stringify(body),
511
+ });
512
+ }
513
+
514
+ export function deleteAutomation(id: string): Promise<{ deleted: string }> {
515
+ return send(`/automations/${encodeURIComponent(id)}`, { method: "DELETE" });
516
+ }
517
+
518
+ export function runAutomation(id: string): Promise<{ started: string }> {
519
+ return send(`/automations/${encodeURIComponent(id)}/run`, { method: "POST" });
520
+ }
521
+
522
+ /**
523
+ * Flip one step's switch.
524
+ *
525
+ * The client says WHICH NODE was clicked and nothing else β€” the server owns what
526
+ * each switch means (`engine.NODE_TOGGLES`). A client that knew "the Bright Data
527
+ * node writes config.tier" would be a second copy of that knowledge, free to
528
+ * drift from the engine that reads it β€” and it would have had to be rewritten
529
+ * when the vendor changed. It did not.
530
+ */
531
+ export function toggleNode(
532
+ id: string,
533
+ nodeId: string
534
+ ): Promise<{ automation: Automation }> {
535
+ return send(
536
+ `/automations/${encodeURIComponent(id)}/nodes/${encodeURIComponent(nodeId)}/toggle`,
537
+ { method: "POST" }
538
+ );
539
+ }
540
+
541
+ export function getAutomation(id: string): Promise<{ automation: Automation }> {
542
+ return send(`/automations/${encodeURIComponent(id)}`);
543
+ }
544
+
545
+ export function runRows(id: string): Promise<RunRows> {
546
+ return send(`/automations/${encodeURIComponent(id)}/rows`);
547
+ }
548
+
549
+ /**
550
+ * The board for one automation (C1). Answers 200 for every existing automation β€”
551
+ * an automation with no bound stage field comes back with its stages and
552
+ * `stageField: null, cards: []`, which the board prints as a state rather than
553
+ * an error (C1 amendment 2).
554
+ */
555
+ export function getBoard(id: string, abort?: AbortSignal): Promise<{ board: Board }> {
556
+ return send(`/automations/${encodeURIComponent(id)}/board`, { signal: abort });
557
+ }
558
+
559
+ /**
560
+ * Move ONE record along the flow, and answer the fresh board.
561
+ *
562
+ * β›” THE SERVER DECIDES LEGALITY, NOT THIS FILE (C1). A review-stage card
563
+ * advances only to a member of its own `next`; every other move is admin-only.
564
+ * The client sends the drop it was given and renders the refusal verbatim β€” a
565
+ * client that pre-judged the move would be a second copy of a permission rule,
566
+ * and when the two copies disagree the user is left with a control that does
567
+ * nothing for a reason nobody can read.
568
+ */
569
+ export function moveCard(
570
+ id: string,
571
+ rowId: string,
572
+ to: string
573
+ ): Promise<{ board: Board }> {
574
+ return send(
575
+ `/automations/${encodeURIComponent(id)}/cards/${encodeURIComponent(rowId)}/move`,
576
+ { method: "POST", body: JSON.stringify({ to }) }
577
+ );
578
+ }
579
+
580
+ /** Is a connector connected for THIS user? (C5 β€” per-user keychain slots, R7's seam.) */
581
+ export function oauthStatus(abort?: AbortSignal): Promise<OAuthStatus> {
582
+ return send("/oauth/status", { signal: abort });
583
+ }
584
+
585
+ /** What would a search of this size cost? Asked BEFORE the run, never after. */
586
+ export function discoverEstimate(recordsLimit: number): Promise<DiscoverEstimate> {
587
+ return send("/automations/discover/estimate", {
588
+ method: "POST",
589
+ body: JSON.stringify({ recordsLimit }),
590
+ });
591
+ }
592
+
593
+ export function previewSource(
594
+ url: string,
595
+ extract: string,
596
+ tableIndex: number
597
+ ): Promise<SourcePreview> {
598
+ return send("/automations/preview", {
599
+ method: "POST",
600
+ body: JSON.stringify({ url, extract, tableIndex }),
601
+ });
602
+ }
603
+
604
+ /**
605
+ * A source column name β†’ a storable field key. Mirrors the server's own
606
+ * normalisation (`clean_config`) so the key the UI shows is the key that gets
607
+ * stored β€” a preview that promised `gics_sector` and a store that wrote
608
+ * `gics__sector` would look like data loss.
609
+ */
610
+ export function fieldKeyFor(column: string): string {
611
+ return (column || "")
612
+ .toLowerCase()
613
+ .replace(/[^a-z0-9_]+/g, "_")
614
+ .replace(/^_+|_+$/g, "")
615
+ .slice(0, 60);
616
+ }
617
+
618
+ /** The state word a status dot / chip paints from. */
619
+ export function stateOf(a: Automation): RunState {
620
+ return a.running ? "running" : (a.status?.state as RunState) || "idle";
621
+ }
622
+
623
+ /**
624
+ * A run's counts as ordered label/value pairs. The ORDER is the sentence the
625
+ * numbers make β€” new, updated, unchanged, then the ones that need explaining β€”
626
+ * and `orphans` is spelled out rather than abbreviated because a bare number
627
+ * next to the word "orphans" is the one count a user must not have to guess at.
628
+ */
629
+ export const COUNT_LABELS: [string, string][] = [
630
+ ["inserted", "New"],
631
+ ["updated", "Updated"],
632
+ ["unchanged", "Unchanged"],
633
+ ["orphans", "No longer on the page (kept)"],
634
+ ["duplicates", "Duplicate keys"],
635
+ ["skipped", "Skipped (no key)"],
636
+ // ⚠ ITS OWN CHIP, next to `skipped` but never merged with it. "Skipped" is a
637
+ // property of the data and usually benign; "not written β€” the database is
638
+ // full" is a property of the system and never is. One chip for both is how a
639
+ // time series stops growing without anybody being told.
640
+ ["capped", "Not written β€” the database is full"],
641
+ ["source_rows", "Rows read"],
642
+ ["profiles", "Profiles"],
643
+ ["ok", "Read in full"],
644
+ // ⚠ ADDED after reading the first live screenshot. The engine counts `partial` separately
645
+ // (profile read, media not anonymously readable) but this table did not, so a run whose
646
+ // summary said "1/1 profiles read" showed a chip row reading "0 Read" β€” the chips
647
+ // contradicting the sentence directly above them. A count the summary names must have a chip.
648
+ ["partial", "Profile only"],
649
+ ["blocked", "Blocked"],
650
+ ["error", "Errors"],
651
+ ["paid", "Exact via Bright Data"],
652
+ ["posts", "Posts"],
653
+ ["new_posts", "New posts"],
654
+ // The engagement series only grows while the per-post rung is on, so its
655
+ // count is its own chip β€” "12 posts" and "0 engagement snapshots" together
656
+ // are the honest picture of a profile-only run.
657
+ ["metrics", "Engagement snapshots"],
658
+ // Discovery.
659
+ ["asked", "Asked for"],
660
+ ["found", "Profiles found"],
661
+ ["new", "New to us"],
662
+ ["seen_again", "Seen before"],
663
+ ["dropped", "Returned but unusable (no handle)"],
664
+ // ⚠ Its own chip for the same reason `capped` has one: a database that could
665
+ // not be CREATED is a system fact, and the run that hit it wrote nothing.
666
+ ["missing_tables", "Databases that could not be created"],
667
+ ];
web/src/customer-grid/display.ts CHANGED
@@ -267,6 +267,12 @@ export function formatDisplay(field: Field, v: CellValue): string {
267
  // months, and the lesson recorded there is that a type whose rendering is deliberate
268
  // should SAY so where a reader looks for it.
269
  return String(v ?? "");
 
 
 
 
 
 
270
  case "multiselect":
271
  // The comma-joined SET, read back with breathing room ("A, B" not "A,B").
272
  return String(v ?? "")
 
267
  // months, and the lesson recorded there is that a type whose rendering is deliberate
268
  // should SAY so where a reader looks for it.
269
  return String(v ?? "");
270
+ case "metric":
271
+ // Wave-22 C7 β€” a server-computed number over the master snapshot series. BLANK IS A
272
+ // STATE, never zero: the engine sends "" when the window holds no snapshots, and
273
+ // rendering that as 0 would fabricate a measurement (the engine's own blank-never-zero
274
+ // law, kept at the display seam too).
275
+ return v == null || v === "" ? "" : numberText(num(v), field.format);
276
  case "multiselect":
277
  // The comma-joined SET, read back with breathing room ("A, B" not "A,B").
278
  return String(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
  // 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: [
@@ -406,6 +413,9 @@ export const TYPE_LABELS: Record<FieldType, string> = {
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
 
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-22 C7 (added by C as client-vocab registrar, the W18 automation precedent). A rising
109
+ // series on an axis: a measure OVER TIME, which is what a metric field is. Deliberately not
110
+ // the formula fx (that computes over the ROW) and not a bare number (int owns ##).
111
+ metric: [
112
+ { d: "M3.2 3.2v9.6h9.6" },
113
+ { d: "M5 10.4l2.4-2.6 1.9 1.5 3.1-3.9" },
114
+ ],
115
  // Wave-19 R7 β€” a framed picture: the mount, a sun, and the hill line every photo glyph
116
  // resolves to at 16px. Drawn on the same 16-unit grid as its neighbours.
117
  image: [
 
413
  formula: "Formula",
414
  // Wave-18 C5-AUTOFIELD (D's spec, applied by C).
415
  automation: "Automation",
416
+ // Wave-22 C7 β€” spawned by automations (not in CREATABLE_TYPES), so this label mostly shows
417
+ // on headers and the field gear, not the create menu.
418
+ metric: "Metric",
419
  // Wave-19 R7 β€” the picture column.
420
  image: "Image",
421
  status: "Lifecycle status (Odoo)", // never creatable; present so the map stays total
web/src/customer-grid/types.ts CHANGED
@@ -38,6 +38,12 @@ export type FieldType =
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
@@ -88,7 +94,7 @@ export function imageRefKind(value: string): ImageRefKind {
88
  * about the row. Distinct from permissions β€” these are read-only by NATURE, not by policy.
89
  */
90
  export const READONLY_CELL_TYPES: ReadonlySet<FieldType> = new Set<FieldType>([
91
- "formula", "created_time", "automation",
92
  ]);
93
 
94
  /** Types whose value is chosen from a fixed list rather than typed. */
@@ -947,7 +953,8 @@ export function mayEditField(field: Field, viewer: Viewer | undefined): boolean
947
  * by the lock-step gate rather than by an import.
948
  */
949
  export function isNumericFieldType(t: FieldType): boolean {
950
- return t === "currency" || t === "int" || t === "pct" || t === "rating" || t === "formula";
 
951
  }
952
 
953
  export function isDateFamilyType(t: FieldType): boolean {
@@ -1085,6 +1092,21 @@ export interface Field {
1085
  /** kind-specific knobs. Scalars only β€” the host clamps keys and value lengths. */
1086
  settings?: Record<string, string | number | boolean>;
1087
  };
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1088
  /**
1089
  * Wave-5 item 11 (same amendment): a RATING field's star count, TOP-LEVEL. 2..10, default 5
1090
  * β€” read through `ratingMax`, never directly.
 
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-22 C7 β€” `metric` is a NUMBER COMPUTED from the master IG snapshot series (a measure
42
+ // over a time window, e.g. followers over the last 7 days). Machine-computed at wire time,
43
+ // never typed; SPAWNED by automations as pre-set fields rather than created from the column
44
+ // menu (deliberately absent from CREATABLE_TYPES: the menu has no measure/window face yet β€”
45
+ // offering the type without its config would mint permanently blank columns).
46
+ | "metric"
47
  // ⭐ Wave-19 R7 / C5 β€” `image` is a PICTURE on a record. The cell holds a STRING REFERENCE,
48
  // never bytes (see `imageRef`): a SKU code, an `ed:` editorial slug, or a `rec:` upload. That
49
  // is what lets Royal's 1,142 existing SKU masters appear with nothing uploaded, and it keeps
 
94
  * about the row. Distinct from permissions β€” these are read-only by NATURE, not by policy.
95
  */
96
  export const READONLY_CELL_TYPES: ReadonlySet<FieldType> = new Set<FieldType>([
97
+ "formula", "created_time", "automation", "metric",
98
  ]);
99
 
100
  /** Types whose value is chosen from a fixed list rather than typed. */
 
953
  * by the lock-step gate rather than by an import.
954
  */
955
  export function isNumericFieldType(t: FieldType): boolean {
956
+ return t === "currency" || t === "int" || t === "pct" || t === "rating" || t === "formula"
957
+ || t === "metric";
958
  }
959
 
960
  export function isDateFamilyType(t: FieldType): boolean {
 
1092
  /** kind-specific knobs. Scalars only β€” the host clamps keys and value lengths. */
1093
  settings?: Record<string, string | number | boolean>;
1094
  };
1095
+ /**
1096
+ * Wave-22 C7 β€” a METRIC field's config bag, mirrored from `user_tables._clean_metric` (the
1097
+ * C-FIELD parity gate holds this mirror to the server's stored keys). The value the CELL
1098
+ * carries is computed server-side from the master snapshot series; this bag is what the
1099
+ * field gear shows about how. The client renders and never re-computes.
1100
+ */
1101
+ metric?: {
1102
+ /** the series source, e.g. 'ig' */
1103
+ source?: string;
1104
+ /** the measure over that series, e.g. 'followers' | 'avg_engagement' */
1105
+ measure: string;
1106
+ /** the window, e.g. 'latest' | 'last_3_posts' | 'last_7d' | 'last_30d' */
1107
+ window: string;
1108
+ agg?: string;
1109
+ };
1110
  /**
1111
  * Wave-5 item 11 (same amendment): a RATING field's star count, TOP-LEVEL. 2..10, default 5
1112
  * β€” read through `ratingMax`, never directly.
web/src/index.css CHANGED
@@ -7850,6 +7850,533 @@ a.cg-map-ctl-b { text-decoration: none; }
7850
 
7851
  /* ═══════════════════ end W18-D AUTO region ═════════════════════════════════════════════ */
7852
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7853
  /* ═══ W18-A TENANT/SETTINGS region (SESSION A β€” integrator) ═══
7854
  Shell-side surfaces for wave 18: the user-table Add-record bar and the New-database
7855
  dialog. Tokens with fallbacks; text/strokes take the -deep weight rule.
 
7850
 
7851
  /* ═══════════════════ end W18-D AUTO region ═════════════════════════════════════════════ */
7852
 
7853
+ /* === WAVE22 AUTOMATION BOARD β€” B REGION START === */
7854
+ /* Wave 22 (owner ruling R1): the automation AS A BOARD β€” lanes are stages, cards are
7855
+ RECORDS β€” plus the shared trigger strip (C3), the discovery filter toggles (C4) and the
7856
+ one-line empty state (R13). Everything the wave-22 board-UI session added to this shared
7857
+ stylesheet is between these two anchors and nowhere else; the W18-D block above is
7858
+ untouched, including the rules the deletions above left unused (booked, not swept, because
7859
+ they sit outside this fence).
7860
+
7861
+ HOUSE RULES OBSERVED THROUGHOUT: every size is a `--lp-fs-*` token (a literal turns
7862
+ `verify_ui.py` red, by design); every colour is a token consumed as a VARIABLE; text and
7863
+ strokes take the `-deep` weight while pastels stay fills (DESIGN.md 3); no
7864
+ `text-transform: uppercase` anywhere (R6); no emoji β€” every glyph is an SVG path; and
7865
+ where a `font:` shorthand appears it is FIRST in its rule, above the longhands it would
7866
+ otherwise re-expand over (R5b, the Alerts-button scar).
7867
+
7868
+ WHAT IT COPIES. The board wears `KanbanView`'s look β€” 250px lanes, a tinted label pill
7869
+ with a count beside it, quiet white cards β€” because two boards in one product that look
7870
+ like two products is the defect DESIGN.md calls variety. It copies no selectors: those
7871
+ belong to the grid tree, which also ships inside the embed. Three of that block's
7872
+ hard-won rules are copied as RULES rather than as classes, and each is load-bearing:
7873
+ `min-width: 0` on the lane (a flex item's min-content floors its basis, so one long
7874
+ string in one card widened the lane and pushed the board sideways), `overflow-wrap:
7875
+ anywhere` on the card title (only `anywhere` lowers min-content β€” `break-word` wraps the
7876
+ paint and still reports the full width upward), and a count that never shrinks, because a
7877
+ truncated "1,534" is a wrong number rather than a shortened label. */
7878
+
7879
+ /* ── the empty state: one line and a button (R13) ───────────────────────────────────────── */
7880
+ .autob-empty {
7881
+ padding: 40px 32px;
7882
+ max-width: 560px;
7883
+ display: flex;
7884
+ flex-direction: column;
7885
+ align-items: flex-start;
7886
+ gap: 10px;
7887
+ }
7888
+ /* Weight 600, not 700: DESIGN.md 2 caps display weights at 600 and the pane this replaced
7889
+ was one of the sites carrying a heavier one. */
7890
+ .autob-empty-title {
7891
+ margin: 0;
7892
+ font-size: var(--lp-fs-lg);
7893
+ font-weight: 600;
7894
+ color: var(--lp-ink);
7895
+ }
7896
+ .autob-empty-line {
7897
+ margin: 0;
7898
+ font-size: var(--lp-fs-xs);
7899
+ color: var(--lp-muted);
7900
+ line-height: var(--lp-lh);
7901
+ }
7902
+
7903
+ /* ── the flow half: the trigger strip above the board ───────────────────────────────────── */
7904
+ .autob-flow {
7905
+ flex: 1 1 auto;
7906
+ min-width: 0;
7907
+ min-height: 0;
7908
+ display: flex;
7909
+ flex-direction: column;
7910
+ }
7911
+ .autob-triggerbar {
7912
+ flex: 0 0 auto;
7913
+ display: flex;
7914
+ flex-direction: column;
7915
+ gap: 8px;
7916
+ padding: 14px 16px;
7917
+ border-bottom: 1px solid var(--lp-line);
7918
+ background: var(--lp-surface);
7919
+ }
7920
+ /* The picker is one short phrase, not a paragraph: `.auto-field-row`'s `flex: 1 1 220px`
7921
+ stretched it across the full bar, so "Manual only" sat in a 600px control. 320px is
7922
+ MEASURED, not chosen: at 260 the longest option ("When an email arrives - needs setting
7923
+ up") truncated in the collapsed control, which reads as a broken value rather than a long
7924
+ one. The open list is as wide as it needs to be either way. */
7925
+ .autob-triggerbar .auto-field { flex: 0 1 320px; }
7926
+ .autob-triggerbar-tag {
7927
+ font-size: var(--lp-fs-4xs);
7928
+ font-weight: 600;
7929
+ color: var(--lp-muted);
7930
+ }
7931
+ /* A trigger waiting on a connector: attention, not failure β€” so yellow, and the next step
7932
+ sits inside the same box as the sentence that explains it. */
7933
+ .autob-needs {
7934
+ display: flex;
7935
+ align-items: center;
7936
+ gap: 10px;
7937
+ flex-wrap: wrap;
7938
+ padding: 7px 10px;
7939
+ border: 1px solid var(--lp-yellow);
7940
+ border-radius: var(--lp-r-md);
7941
+ background: var(--lp-yellow-tint);
7942
+ }
7943
+ .autob-needs-text {
7944
+ font-size: var(--lp-fs-3xs);
7945
+ color: var(--lp-yellow-deep);
7946
+ line-height: var(--lp-lh);
7947
+ }
7948
+ /* An <a> wearing `.auto-btn`: it navigates (OAuth starts are navigations), so it must be a
7949
+ link. It declares NO font of its own β€” `.auto-btn` already sets the size and weight, and a
7950
+ bare shorthand here would re-expand over them at equal specificity (R5b). */
7951
+ .autob-connect {
7952
+ display: inline-flex;
7953
+ align-items: center;
7954
+ text-decoration: none;
7955
+ }
7956
+
7957
+ /* ── the board ──────────────────────────────────────────────────────────────────────────── */
7958
+ .autob-board {
7959
+ flex: 1 1 auto;
7960
+ min-height: 0;
7961
+ display: flex;
7962
+ flex-direction: column;
7963
+ background: var(--lp-wash);
7964
+ }
7965
+ .autob-board-note {
7966
+ margin: 0;
7967
+ padding: 10px 14px 0;
7968
+ font-size: var(--lp-fs-3xs);
7969
+ color: var(--lp-muted);
7970
+ line-height: var(--lp-lh);
7971
+ }
7972
+ /* ── the process strip: the stages that are STEPS rather than places ─────────────────────
7973
+ `record: false` stages (find / collect / write) can never hold a card, so they are not
7974
+ lanes β€” a lane that can never receive anything is a drop target that lies. They keep
7975
+ everything else a stage has: a click into their settings, their run dot, their switch. */
7976
+ .autob-strip {
7977
+ flex: 0 0 auto;
7978
+ display: flex;
7979
+ align-items: center;
7980
+ gap: 0;
7981
+ flex-wrap: wrap;
7982
+ padding: 10px 14px 0;
7983
+ }
7984
+ .autob-strip-step {
7985
+ display: inline-flex;
7986
+ align-items: center;
7987
+ gap: 8px;
7988
+ padding: 3px 10px;
7989
+ border: 1px solid var(--lp-line);
7990
+ border-radius: var(--lp-r-pill);
7991
+ background: var(--lp-surface);
7992
+ color: var(--lp-ink);
7993
+ }
7994
+ .autob-strip-hit {
7995
+ display: inline-flex;
7996
+ align-items: center;
7997
+ gap: 6px;
7998
+ padding: 0;
7999
+ border: 0;
8000
+ background: transparent;
8001
+ color: inherit;
8002
+ font: inherit;
8003
+ font-size: var(--lp-fs-3xs);
8004
+ font-weight: 600;
8005
+ cursor: pointer;
8006
+ }
8007
+ .autob-strip-hit:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: 3px; }
8008
+ .autob-strip-switch { position: relative; top: auto; right: auto; flex: 0 0 auto; }
8009
+ /* The connector, drawn as a rule rather than a glyph: it is the shape of the flow, not a
8010
+ character somebody has to have a font for. */
8011
+ .autob-strip-step + .autob-strip-step { position: relative; margin-left: 22px; }
8012
+ .autob-strip-step + .autob-strip-step::before {
8013
+ content: "";
8014
+ position: absolute;
8015
+ left: -17px;
8016
+ top: 50%;
8017
+ width: 12px;
8018
+ border-top: 1px solid var(--lp-line);
8019
+ }
8020
+ .autob-strip-step:hover { background: var(--lp-surface-2); }
8021
+ /* The connector must not paint over a chip that has grown a switch. */
8022
+ .autob-strip { row-gap: 8px; }
8023
+ .autob-strip-step.is-selected { border-color: var(--lp-blue-deep); }
8024
+ .autob-strip-step.is-off { opacity: 0.55; }
8025
+
8026
+ /* The review gate's audit: who moved which record, and when. */
8027
+ .autob-reviews {
8028
+ list-style: none;
8029
+ margin: 4px 0 0;
8030
+ padding: 0;
8031
+ display: flex;
8032
+ flex-direction: column;
8033
+ gap: 4px;
8034
+ }
8035
+ .autob-review {
8036
+ display: flex;
8037
+ gap: 8px;
8038
+ align-items: baseline;
8039
+ min-width: 0;
8040
+ font-size: var(--lp-fs-3xs);
8041
+ }
8042
+ .autob-review-ts {
8043
+ flex: 0 0 auto;
8044
+ color: var(--lp-muted);
8045
+ font-variant-numeric: tabular-nums;
8046
+ }
8047
+ .autob-review-who {
8048
+ flex: 0 1 auto;
8049
+ min-width: 0;
8050
+ font-weight: 600;
8051
+ overflow: hidden;
8052
+ text-overflow: ellipsis;
8053
+ white-space: nowrap;
8054
+ }
8055
+ .autob-review-move { flex: 0 0 auto; color: var(--lp-muted); }
8056
+
8057
+ .autob-cols {
8058
+ flex: 1 1 auto;
8059
+ min-height: 0;
8060
+ display: flex;
8061
+ align-items: stretch;
8062
+ gap: 10px;
8063
+ padding: 12px 14px;
8064
+ overflow-x: auto;
8065
+ overflow-y: hidden;
8066
+ }
8067
+ /* ⭐ 250px is the BASIS and `min-width: 0` is what makes it the width. A flex item's
8068
+ `min-width` defaults to `auto`, which resolves to min-content and floors the basis β€” so
8069
+ one unbroken string inside one card would widen the column and push every other stage off
8070
+ the board. The board may scroll because it has many stages; it must never scroll because
8071
+ of one record's text. */
8072
+ .autob-col {
8073
+ flex: 0 0 250px;
8074
+ min-width: 0;
8075
+ display: flex;
8076
+ flex-direction: column;
8077
+ gap: 10px;
8078
+ max-height: 100%;
8079
+ }
8080
+ .autob-lane {
8081
+ min-width: 0;
8082
+ min-height: 92px;
8083
+ display: flex;
8084
+ flex-direction: column;
8085
+ border: 1px solid transparent;
8086
+ border-radius: var(--lp-r-md);
8087
+ background: var(--lp-surface-2);
8088
+ transition: border-color 0.14s ease, background 0.14s ease;
8089
+ }
8090
+ /* Selected (reading its settings) and a legal drop target are both interactive states, so
8091
+ both are blue β€” told apart by solid vs dashed, because they never mean the same thing and
8092
+ almost never happen at once. */
8093
+ .autob-lane.is-selected { border-color: var(--lp-blue-deep); }
8094
+ .autob-lane.is-target {
8095
+ border-style: dashed;
8096
+ border-color: var(--lp-blue-deep);
8097
+ background: var(--lp-blue-tint);
8098
+ }
8099
+ .autob-lane.is-off { opacity: 0.55; }
8100
+ .autob-lane-head {
8101
+ display: flex;
8102
+ align-items: center;
8103
+ gap: 8px;
8104
+ padding: 8px 10px 4px;
8105
+ }
8106
+ .autob-lane-hit {
8107
+ flex: 1 1 auto;
8108
+ min-width: 0;
8109
+ display: flex;
8110
+ align-items: center;
8111
+ gap: 8px;
8112
+ padding: 0;
8113
+ border: 0;
8114
+ background: transparent;
8115
+ color: inherit;
8116
+ font: inherit;
8117
+ font-size: var(--lp-fs-3xs);
8118
+ text-align: left;
8119
+ cursor: pointer;
8120
+ }
8121
+ .autob-lane-hit:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: 2px; }
8122
+ .autob-lane-pill {
8123
+ min-width: 0;
8124
+ padding: 2px 9px;
8125
+ border-radius: var(--lp-r-lg);
8126
+ background: var(--lp-wash);
8127
+ color: var(--lp-ink);
8128
+ font-size: var(--lp-fs-3xs);
8129
+ font-weight: 600;
8130
+ overflow: hidden;
8131
+ text-overflow: ellipsis;
8132
+ white-space: nowrap;
8133
+ }
8134
+ /* The stage kinds, tinted by MEANING (DESIGN.md 3's fixed semantics): a review stage is the
8135
+ one waiting for a person, which is attention; a branch is a routing control, which is the
8136
+ purple family; the ordinary body of the flow is blue. */
8137
+ .autob-lane.is-review .autob-lane-pill {
8138
+ background: var(--lp-yellow-tint);
8139
+ color: var(--lp-yellow-deep);
8140
+ }
8141
+ .autob-lane.is-branch .autob-lane-pill {
8142
+ background: var(--lp-purple-tint);
8143
+ color: var(--lp-purple-deep);
8144
+ }
8145
+ .autob-lane.is-action .autob-lane-pill {
8146
+ background: var(--lp-blue-tint);
8147
+ color: var(--lp-blue-deep);
8148
+ }
8149
+ /* Never shrinks: a truncated count is a wrong number, not a shortened label. It matches the
8150
+ PILL's size rather than the grid kanban's larger one β€” measured side by side, a count a
8151
+ step bigger than the stage it counts reads as the louder of the two, which is backwards
8152
+ (DESIGN.md 2's sibling rule: the spec is the neighbour's computed value). */
8153
+ .autob-lane-count {
8154
+ flex: 0 0 auto;
8155
+ font-size: var(--lp-fs-3xs);
8156
+ color: var(--lp-muted);
8157
+ font-variant-numeric: tabular-nums;
8158
+ }
8159
+ /* `.auto-step-switch` positions itself absolutely in a step card; in a lane head it sits in
8160
+ flow, and it must keep `position: relative` because its knob is positioned against it. */
8161
+ .autob-lane-switch,
8162
+ .autob-tgl-switch {
8163
+ position: relative;
8164
+ top: auto;
8165
+ right: auto;
8166
+ flex: 0 0 auto;
8167
+ }
8168
+ .autob-lane-cards {
8169
+ flex: 1 1 auto;
8170
+ min-height: 20px;
8171
+ overflow-y: auto;
8172
+ display: flex;
8173
+ flex-direction: column;
8174
+ gap: 6px;
8175
+ padding: 4px 8px 8px;
8176
+ }
8177
+ .autob-card {
8178
+ display: flex;
8179
+ flex-direction: column;
8180
+ gap: 2px;
8181
+ min-width: 0;
8182
+ padding: 7px 9px;
8183
+ border: 1px solid var(--lp-line);
8184
+ border-radius: var(--lp-r-md);
8185
+ background: var(--lp-surface);
8186
+ }
8187
+ .autob-card.is-draggable { cursor: grab; }
8188
+ .autob-card.is-moving { opacity: 0.55; }
8189
+ /* `anywhere`, not `break-word`: the two break identically on the painted line, but only
8190
+ `anywhere` also lowers the element's min-content size β€” and min-content is what floors the
8191
+ column above. */
8192
+ .autob-card-title {
8193
+ font-size: var(--lp-fs-xs);
8194
+ font-weight: 600;
8195
+ color: var(--lp-ink);
8196
+ line-height: var(--lp-lh-tight);
8197
+ overflow-wrap: anywhere;
8198
+ }
8199
+ .autob-card-sub {
8200
+ font-size: var(--lp-fs-3xs);
8201
+ color: var(--lp-muted);
8202
+ line-height: var(--lp-lh-tight);
8203
+ overflow-wrap: anywhere;
8204
+ }
8205
+ .autob-card-when {
8206
+ font-size: var(--lp-fs-4xs);
8207
+ color: var(--lp-muted);
8208
+ font-variant-numeric: tabular-nums;
8209
+ }
8210
+ .autob-card-moves {
8211
+ display: flex;
8212
+ flex-wrap: wrap;
8213
+ gap: 6px;
8214
+ margin-top: 4px;
8215
+ }
8216
+ /* THE PROMOTION. On the discovery flow this button is literally the `tracked` tick, so it
8217
+ reads as the one interactive thing on the card β€” blue, bordered, small. */
8218
+ .autob-card-advance {
8219
+ display: inline-flex;
8220
+ align-items: center;
8221
+ gap: 4px;
8222
+ padding: 3px 8px;
8223
+ border: 1px solid var(--lp-blue);
8224
+ border-radius: var(--lp-r-pill);
8225
+ background: var(--lp-blue-tint);
8226
+ color: var(--lp-blue-deep);
8227
+ font: inherit;
8228
+ font-size: var(--lp-fs-4xs);
8229
+ font-weight: 600;
8230
+ cursor: pointer;
8231
+ }
8232
+ .autob-card-advance:hover:not(:disabled) { background: var(--lp-blue); }
8233
+ .autob-card-advance:disabled { opacity: 0.5; cursor: default; }
8234
+ .autob-card-advance:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: 1px; }
8235
+ /* The cap disclosure. A button when there is something left to expand, a flat line when the
8236
+ rest were never sent β€” the same sentence, and only one of them is a control. */
8237
+ .autob-lane-more {
8238
+ display: block;
8239
+ width: 100%;
8240
+ margin: 0;
8241
+ padding: 0 10px 8px;
8242
+ border: 0;
8243
+ background: transparent;
8244
+ color: var(--lp-muted);
8245
+ font: inherit;
8246
+ font-size: var(--lp-fs-4xs);
8247
+ text-align: left;
8248
+ cursor: pointer;
8249
+ }
8250
+ .autob-lane-more:hover { color: var(--lp-blue-solid); text-decoration: underline; }
8251
+ .autob-lane-more.is-flat { cursor: default; }
8252
+ .autob-lane-more.is-flat:hover { color: var(--lp-muted); text-decoration: none; }
8253
+ .autob-lane-routes {
8254
+ display: flex;
8255
+ flex-direction: column;
8256
+ gap: 3px;
8257
+ padding: 0 10px 8px;
8258
+ }
8259
+ .autob-route {
8260
+ padding: 1px 8px;
8261
+ border-radius: var(--lp-r-pill);
8262
+ background: var(--lp-purple-tint);
8263
+ color: var(--lp-purple-deep);
8264
+ font-size: var(--lp-fs-4xs);
8265
+ overflow: hidden;
8266
+ text-overflow: ellipsis;
8267
+ white-space: nowrap;
8268
+ }
8269
+
8270
+ /* ── the discovery filter toggles (C4) ──────────────────────────────────────────────────── */
8271
+ .autob-match { max-width: 220px; }
8272
+ .autob-tglgroup {
8273
+ margin-top: 10px;
8274
+ display: flex;
8275
+ flex-direction: column;
8276
+ gap: 2px;
8277
+ }
8278
+ .autob-tglgroup-label {
8279
+ margin: 0 0 2px;
8280
+ font-size: var(--lp-fs-4xs);
8281
+ font-weight: 600;
8282
+ color: var(--lp-muted);
8283
+ }
8284
+ .autob-tgl { border-radius: var(--lp-r-sm); }
8285
+ .autob-tgl.is-on { background: var(--lp-wash); padding-bottom: 6px; }
8286
+ .autob-tgl-head {
8287
+ display: flex;
8288
+ align-items: center;
8289
+ gap: 8px;
8290
+ min-width: 0;
8291
+ padding: 4px 6px;
8292
+ }
8293
+ .autob-tgl-name {
8294
+ min-width: 0;
8295
+ font-size: var(--lp-fs-3xs);
8296
+ color: var(--lp-ink);
8297
+ overflow: hidden;
8298
+ text-overflow: ellipsis;
8299
+ white-space: nowrap;
8300
+ }
8301
+ .autob-tgl.is-on .autob-tgl-name { font-weight: 600; }
8302
+ .autob-tgl-flag {
8303
+ flex: 0 0 auto;
8304
+ padding: 0 6px;
8305
+ border-radius: var(--lp-r-pill);
8306
+ background: var(--lp-surface-2);
8307
+ color: var(--lp-muted);
8308
+ font-size: var(--lp-fs-4xs);
8309
+ }
8310
+ /* The chip marks the MINORITY (see AutomationFind's note): the fields that narrow, in the
8311
+ interactive blue, because picking one is what satisfies the server's guard. */
8312
+ .autob-tgl-flag.is-narrow {
8313
+ background: var(--lp-blue-tint);
8314
+ color: var(--lp-blue-deep);
8315
+ }
8316
+ .autob-tgl-flag.is-stray {
8317
+ background: var(--lp-yellow-tint);
8318
+ color: var(--lp-yellow-deep);
8319
+ }
8320
+ /* Indented past the switch, so the conditions read as belonging to the field above them. */
8321
+ .autob-tgl-body {
8322
+ display: flex;
8323
+ flex-direction: column;
8324
+ gap: 6px;
8325
+ padding: 0 6px 4px 42px;
8326
+ }
8327
+ .autob-cond {
8328
+ display: flex;
8329
+ align-items: center;
8330
+ gap: 6px;
8331
+ min-width: 0;
8332
+ }
8333
+ .autob-cond .auto-input { flex: 1 1 80px; min-width: 0; }
8334
+ .autob-cond-novalue {
8335
+ flex: 1 1 auto;
8336
+ font-size: var(--lp-fs-3xs);
8337
+ color: var(--lp-muted);
8338
+ }
8339
+ .autob-cond-x {
8340
+ flex: 0 0 auto;
8341
+ display: inline-flex;
8342
+ align-items: center;
8343
+ justify-content: center;
8344
+ width: 22px;
8345
+ height: 22px;
8346
+ padding: 0;
8347
+ border: 0;
8348
+ border-radius: var(--lp-r-sm);
8349
+ background: transparent;
8350
+ color: var(--lp-muted);
8351
+ font: inherit;
8352
+ font-size: var(--lp-fs-3xs);
8353
+ cursor: pointer;
8354
+ }
8355
+ .autob-cond-x:hover { background: var(--lp-red-tint); color: var(--lp-red-deep); }
8356
+ .autob-cond-x:focus-visible { outline: 2px solid var(--lp-blue-deep); outline-offset: 1px; }
8357
+ .autob-cond-add {
8358
+ align-self: flex-start;
8359
+ padding: 0;
8360
+ border: 0;
8361
+ background: transparent;
8362
+ color: var(--lp-blue-solid);
8363
+ font: inherit;
8364
+ font-size: var(--lp-fs-4xs);
8365
+ font-weight: 600;
8366
+ text-align: left;
8367
+ cursor: pointer;
8368
+ }
8369
+ .autob-cond-add:hover { text-decoration: underline; }
8370
+
8371
+ /* Narrow viewports: the same fold the W18-D block applies to the steps half β€” the flow
8372
+ becomes the top sheet and the settings panel the bottom one, so neither is too narrow to
8373
+ read. Stated here rather than added to that block's media query, which is not this
8374
+ session's to edit. */
8375
+ @media (max-width: 1100px) {
8376
+ .autob-flow { flex: 1 1 55%; min-height: 280px; }
8377
+ }
8378
+ /* === WAVE22 AUTOMATION BOARD β€” B REGION END === */
8379
+
8380
  /* ═══ W18-A TENANT/SETTINGS region (SESSION A β€” integrator) ═══
8381
  Shell-side surfaces for wave 18: the user-table Add-record bar and the New-database
8382
  dialog. Tokens with fallbacks; text/strokes take the -deep weight rule.
web/src/settings/permsModel.ts CHANGED
@@ -145,6 +145,8 @@ const FIELD_TYPE_TABLE: Record<FieldType, true> = {
145
  select: true, user: true, multiselect: true, checkbox: true, phone: true,
146
  email: true, url: true, rating: true, created_time: true, formula: true,
147
  automation: true,
 
 
148
  // Wave-19 R7 (added by session A β€” see the dated amendment in the split doc). This ONE key is
149
  // the whole edit: the exhaustiveness alarm above did exactly what it promises, and the fix it
150
  // names is a listing here. Nowhere near `SettingsSection` / the rail, which is B's half of
 
145
  select: true, user: true, multiselect: true, checkbox: true, phone: true,
146
  email: true, url: true, rating: true, created_time: true, formula: true,
147
  automation: true,
148
+ // Wave-22 C7 (added by C, the same one-key edit the alarm demands).
149
+ metric: true,
150
  // Wave-19 R7 (added by session A β€” see the dated amendment in the split doc). This ONE key is
151
  // the whole edit: the exhaustiveness alarm above did exactly what it promises, and the fix it
152
  // names is a listing here. Nowhere near `SettingsSection` / the rail, which is B's half of
web/src/shell/Shell.tsx CHANGED
@@ -525,6 +525,15 @@ export default function Shell() {
525
  return () => clearTimeout(t);
526
  }, [toast]);
527
 
 
 
 
 
 
 
 
 
 
528
  // Boot: ask the server who we are. ⚠ Every boot, no cache β€” the X3 cookie is
529
  // HttpOnly and revocable by epoch bump, so the server is the only thing that
530
  // can answer this and a remembered answer is a stale one.
 
525
  return () => clearTimeout(t);
526
  }, [toast]);
527
 
528
+ // DEBT D-38 (wave 22): the error card is ABOUT a surface, so leaving that surface clears
529
+ // it β€” before this, one failed fetch left the card over every module until sign-out
530
+ // (`setDataError("")` at the nav effect runs only on a WHO change). Clearing on the route
531
+ // commit cannot suppress a real failure: the failing surface raises DATA_ERROR_EVENT from
532
+ // its own fetch, which resolves after this effect has run.
533
+ useEffect(() => {
534
+ setDataError("");
535
+ }, [route]);
536
+
537
  // Boot: ask the server who we are. ⚠ Every boot, no cache β€” the X3 cookie is
538
  // HttpOnly and revocable by epoch bump, so the server is the only thing that
539
  // can answer this and a remembered answer is a stale one.
web/src/viz/seriesData.ts CHANGED
@@ -32,6 +32,8 @@ 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
  // 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
 
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 22 C7 β€” `metric` is numeric (a measure over a snapshot window) and PLOTS.
36
+ "metric",
37
  // Wave 19 R7 β€” `image`. Listed for the reason the comment above gives, not because a chart
38
  // plots pictures: it does not. `isNumericFieldType` leaves it categorical, so it groups like
39
  // any other reference string. What listing it BUYS is honesty β€” without it `asFields` would
web/src/viz/types.ts CHANGED
@@ -35,6 +35,13 @@ export type FieldType =
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
 
35
  | "multiselect"
36
  | "checkbox" | "phone" | "email" | "url" | "rating" | "created_time" | "formula"
37
  | "automation"
38
+ // Wave-22 C7 β€” `metric`: the same alarm (`GridFieldFitsViz`) fired for the same reason. A
39
+ // metric IS numeric (a measure over a window), so unlike `image` it plots β€” the shared
40
+ // formatter renders it via the grid's own blank-never-zero display case. KEEP THIS COMMENT
41
+ // FREE OF THE STATEMENT-TERMINATOR CHARACTER: verify_ui parses this union up to the first
42
+ // one it meets, and a stray one inside prose truncates the declared set (measured twice at
43
+ // the wave-22 close β€” the second time by a comment WARNING about it).
44
+ | "metric"
45
  // Wave-19 R7 β€” `image`. Added here because `GridFieldFitsViz` below went red the moment the
46
  // grid's union grew, which is this file's own stated alarm working. A chart never PLOTS a
47
  // picture (it is a reference string, so `isNumericFieldType` leaves it categorical and the