fsanyoto commited on
Commit
8808ae1
Β·
verified Β·
1 Parent(s): b8caa46

Deploy AIOS web (React glide grid + FastAPI slice)

Browse files
RELEASES.json CHANGED
@@ -1,5 +1,5 @@
1
  {
2
- "current": "2dcd7b3",
3
  "releases": [
4
  {
5
  "version": "v12",
 
1
  {
2
+ "current": "002cf17",
3
  "releases": [
4
  {
5
  "version": "v12",
VERSION CHANGED
@@ -1 +1 @@
1
- 2dcd7b3
 
1
+ 002cf17
api/automation_engine.py CHANGED
@@ -1054,32 +1054,54 @@ def clean_flow(raw, previous=None):
1054
  DISCOVER_SEED_RECORDS = 10
1055
 
1056
 
1057
- def _seed_ig_action(flow_raw, table):
1058
- """C-TRIG LAW 3 β€” the follow-up action `ig_profile_match` seeds, ONCE, on the transition.
1059
-
1060
- β›” ONCE IS THE WHOLE DESIGN. Law 3 ends "deleting it is their call, not a refusal", so this
1061
- fires only on the EDGE into the trigger and only when the flow is empty. Seeding on every
1062
- clean would make the action un-deletable β€” it would reappear on the next Save β€” which is the
1063
- difference between a helpful default and a control that will not take no for an answer.
1064
-
1065
- The seed must be a config `clean_actions` ACCEPTS, or the builder shows a red banner and no
1066
- card: the wave-23 header records four kinds that shipped with illegal seeds and did exactly
1067
- that. `create_record` needs a ut_-prefixed table and at least one value, so it gets both.
 
 
 
 
 
 
 
1068
  """
1069
  flow = dict(flow_raw or {}) if isinstance(flow_raw, dict) else {}
1070
- if flow.get("actions"):
1071
- return flow_raw
1072
- flow["actions"] = [{
1073
- "id": "act_1", "kind": "create_record", "enabled": True, "when": None,
1074
- # `config.label` follows the `review` action's precedent in `_clean_action_config` β€”
1075
- # an action naming itself, inside the untyped config bag, so no shared TS type changes.
1076
- "config": {"table": str(table or DISCOVER_TABLE),
1077
- "label": "Create an Instagram record",
1078
- "values": {"handle": "{{handle}}"}},
1079
- }]
 
 
 
 
 
 
 
 
 
1080
  return flow
1081
 
1082
 
 
 
 
 
 
 
1083
  def clean_definition(raw, previous=None, username=""):
1084
  """Whole-definition validation. Returns `(defn, error)`."""
1085
  raw = raw if isinstance(raw, dict) else {}
@@ -1136,9 +1158,11 @@ def clean_definition(raw, previous=None, username=""):
1136
  return None, str(e)
1137
  # (`clean_trigger` ran at the top β€” law 1 needs the trigger before the kind.)
1138
  flow_raw = raw.get("flow") if "flow" in raw else prev.get("flow")
1139
- if (trigger or {}).get("key") == "ig_profile_match" \
1140
- and (prev.get("trigger") or {}).get("key") != "ig_profile_match":
1141
- flow_raw = _seed_ig_action(flow_raw, config.get("targetTable") or DISCOVER_TABLE)
 
 
1142
  flow, ferr = clean_flow(flow_raw, prev.get("flow"))
1143
  if ferr:
1144
  return None, ferr
@@ -1771,23 +1795,23 @@ def bd_call(path, params=None, body=None):
1771
  headers=hdrs)
1772
  except Refused as e:
1773
  # The BASE was refused by the SSRF rail β€” a configuration fault, not a vendor outage.
1774
- return None, f"the Bright Data base URL was refused by the URL rail: {e}"
1775
  except Exception as e: # noqa: BLE001
1776
  # ⚠ `type(e).__name__` only. A requests exception's str() can carry the full URL, and the
1777
  # Authorization header is one refactor away from being a query param; this line must not
1778
  # be what leaks it.
1779
- return None, f"Bright Data did not answer ({type(e).__name__})"
1780
  if status == 402:
1781
- return None, "Bright Data answered 402 β€” the account is out of credit"
1782
  if status in (401, 403):
1783
- return None, f"Bright Data refused the key ({status})"
1784
  if status == 429:
1785
  # ⚠ MEASURED during the discovery probe: `too_many_parallel_jobs`. The filter API has a
1786
  # concurrency cap and the probe's most important test died on it β€” hence every caller
1787
  # below is SERIAL by construction.
1788
- return None, "Bright Data answered 429 β€” too many parallel jobs; the calls are serialised"
1789
  if not (200 <= status < 300):
1790
- return None, f"Bright Data answered {status}"
1791
  # β›” A BODY THAT REACHED THE READ CEILING IS A TRUNCATION, AND IT MUST SAY SO. `fetch` reads
1792
  # at most `max_kb` and returns what it got β€” silently. A truncated JSON document then fails
1793
  # `json.loads`, falls through to the NDJSON branch, and comes back as "answered with
@@ -1795,12 +1819,12 @@ def bd_call(path, params=None, body=None):
1795
  # looking for a fault that is OUR byte ceiling β€” after a result set that has already been
1796
  # paid for. Naming it here is the same no-silent-caps rule the row and table ceilings follow.
1797
  if len(raw) >= BD_MAX_KB * 1024:
1798
- return None, (f"Bright Data's answer exceeded this client's {BD_MAX_KB // 1024} MB read "
1799
  f"ceiling and was TRUNCATED β€” ask for fewer records; nothing was parsed "
1800
  f"from a partial document")
1801
  text = raw.decode("utf-8", "replace").strip()
1802
  if not text:
1803
- return None, f"Bright Data answered {status} with an empty body"
1804
  try:
1805
  return json.loads(text), ""
1806
  except Exception: # noqa: BLE001
@@ -1815,8 +1839,8 @@ def bd_call(path, params=None, body=None):
1815
  try:
1816
  rows.append(json.loads(line))
1817
  except Exception: # noqa: BLE001
1818
- return None, "Bright Data answered with something that is not JSON"
1819
- return (rows, "") if rows else (None, "Bright Data answered with something that is not JSON")
1820
 
1821
 
1822
  def _first(node, *names, default=None):
@@ -2131,7 +2155,7 @@ def bd_scrape(dataset_id, urls, wait=None):
2131
  waited += BD_SCRAPE_POLL
2132
  # β›” NAME THE SNAPSHOT. It has been paid for and it is still finishing; a note that said only
2133
  # "no rows" would throw away both the data and the way to get it.
2134
- return [], (f"Bright Data deferred this batch to snapshot {sid} and it was not ready within "
2135
  f"{int(budget)}s β€” the records are collected, not lost; ask for a smaller batch "
2136
  f"or collect {sid} from the control panel")
2137
 
@@ -2162,7 +2186,7 @@ def pull_profile_bd(url, max_posts=24, post_metrics=False, log=print):
2162
  # ⚠ `posts_count` is deliberately NOT part of this test: it arrives as a fabricated 0 and
2163
  # is discarded, so a row where it is the only "readable" field is a row we cannot read.
2164
  return {"state": "blocked", "profile": {}, "posts": [], "via": "brightdata",
2165
- "note": "Bright Data answered, but no follower/following counts were readable in "
2166
  "it (the field names may have moved β€” see instagram-capture.md)"}
2167
  posts = []
2168
  for p in (node.get("posts") or [])[:max_posts]:
@@ -2197,7 +2221,7 @@ def pull_profile_bd(url, max_posts=24, post_metrics=False, log=print):
2197
  # over a posts table that did not grow.
2198
  return {"state": "ok" if posts else "partial", "profile": profile, "posts": posts,
2199
  "via": "brightdata",
2200
- "note": note or ("" if posts else "profile read; Bright Data returned no posts")}
2201
 
2202
 
2203
  # ---------------------------------------------------------------------------------------------
@@ -2301,6 +2325,101 @@ BD_POPULATED_FIELDS = frozenset({
2301
  "full_name", "profile_name", "highlights_count", "id", "fbid", "profile_url"})
2302
  BD_MIN_NARROWING = 1
2303
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2304
  #: ⭐ WHAT A **FRESH** CONDITION ON A FIELD STARTS AS β€” and it lives HERE, beside the narrowing
2305
  #: law, because the two drifted apart and the drift cost a user their first automation.
2306
  #:
@@ -2330,16 +2449,22 @@ def default_operator(name):
2330
  saveable rather than two (change the comparison, then type a value) β€” with the second step
2331
  being one the surface never told anyone to take.
2332
  """
2333
- if name in BD_ARRAY_FIELDS:
 
2334
  return "array_includes"
2335
- if name in BD_EXACT_FIELDS or name in BD_BOOLEAN_FIELDS:
 
 
 
 
 
2336
  return "="
2337
- if name in BD_NARROWING_FIELDS:
2338
- return "includes"
2339
- # Numbers. `>=` cannot narrow the scan and is not pretending to β€” it is the comparison a
2340
- # person reaching for `followers` means, and the guard's sentence is the honest answer when
2341
- # it is the ONLY condition present.
2342
- return ">="
2343
 
2344
 
2345
  def predicate_narrows(p):
@@ -2368,16 +2493,15 @@ def narrowing_refusal(preds, operator="and"):
2368
  if str(operator or "").lower() == "or":
2369
  if preds and all(predicate_narrows(p) for p in preds):
2370
  return ""
2371
- return ("with Match set to ANY, EVERY condition has to be a content one (biography "
2372
- "includes …, account =, a hashtag) β€” 'any of them' asks the vendor for the UNION, "
2373
- "so one number or yes/no branch makes the whole search as broad as that branch. "
2374
- "Either narrow every condition or set Match to ALL")
2375
  if any(predicate_narrows(p) for p in preds):
2376
  return ""
2377
- return ("add at least one CONTENT condition (biography includes …, account =, a hashtag) β€” "
2378
- "number and yes/no filters alone make the vendor scan the whole 620-million-row "
2379
- "corpus, and breadth is what costs: the measured `followers > 10000` search was "
2380
- "still building 50 minutes in")
2381
 
2382
 
2383
  def filter_meta():
@@ -2389,9 +2513,25 @@ def filter_meta():
2389
  `default_operator`: the client's own default was `is_not_null` for every field, which the
2390
  narrowing guard refuses on every field.
2391
  """
2392
- return [{"name": n, "populated": n in BD_POPULATED_FIELDS,
 
 
 
 
2393
  "narrowing": n in BD_NARROWING_FIELDS,
2394
- "defaultOperator": default_operator(n)} for n in BD_FILTER_FIELDS]
 
 
 
 
 
 
 
 
 
 
 
 
2395
 
2396
  CANDIDATE_FIELDS = [
2397
  field_def("handle", "Handle"), field_def("profile_url", "Profile", "url"),
@@ -2427,16 +2567,50 @@ def clean_predicates(raw, operator="and"):
2427
  name = _s(p.get("name") or p.get("field"), 60).strip()
2428
  op = _s(p.get("operator") or p.get("op"), 20).strip()
2429
  if name not in BD_FILTER_FIELDS:
2430
- return None, (f"{name or 'that field'!r} cannot be used to search β€” the searchable "
2431
- f"fields are: {', '.join(BD_FILTER_FIELDS)}")
2432
- if op not in BD_FILTER_OPS:
2433
- return None, f"{op or 'that comparison'!r} is not one of: {', '.join(BD_FILTER_OPS)}"
 
 
 
 
 
 
2434
  entry = {"name": name, "operator": op}
2435
  if op not in BD_NULLARY_OPS:
2436
- v = p.get("value")
2437
- if v is None or (isinstance(v, str) and not v.strip()):
2438
- return None, f"give a value to compare {name!r} against"
2439
- entry["value"] = v.strip() if isinstance(v, str) else v
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2440
  out.append(entry)
2441
  if not out:
2442
  # ⭐ WAVE 24 Β· AMENDMENT A2 β€” AN EMPTY FILTER IS INCOMPLETE, NOT WRONG, so it STORES.
@@ -2467,10 +2641,38 @@ def discover_estimate(records_limit):
2467
  n = max(0, int(records_limit or 0))
2468
  return {"records": n, "usd": round(n * BD_RECORD_PRICE_SPEC, 4),
2469
  "unitUsd": BD_RECORD_PRICE_SPEC, "basis": "SPEC",
2470
- "note": "estimated from Bright Data's published dataset rate β€” the API never returns "
2471
  "a price before a run, and this account's token cannot read a balance"}
2472
 
2473
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2474
  def bd_filter_start(predicates, operator="and", records_limit=5, dataset_id=BD_DS_PROFILES):
2475
  """Start ONE corpus query. Returns `(snapshot_id, note)`.
2476
 
@@ -2480,13 +2682,13 @@ def bd_filter_start(predicates, operator="and", records_limit=5, dataset_id=BD_D
2480
  HAS been measured end-to-end. One shape, and it is the tested one.
2481
  """
2482
  body = {"dataset_id": dataset_id, "records_limit": int(records_limit),
2483
- "filter": {"operator": operator, "filters": list(predicates)}}
2484
  payload, note = bd_call(BD_PATH_FILTER, body=body)
2485
  if note:
2486
  return "", note
2487
  sid = str((payload or {}).get("snapshot_id") or "") if isinstance(payload, dict) else ""
2488
  if not sid:
2489
- return "", "Bright Data accepted the search but named no snapshot to collect it from"
2490
  return sid, ""
2491
 
2492
 
@@ -2498,6 +2700,14 @@ def bd_filter_status(snapshot_id):
2498
  d = payload if isinstance(payload, dict) else {}
2499
  status = str(d.get("status") or "")
2500
  err = str(d.get("error") or "")
 
 
 
 
 
 
 
 
2501
  if status == "failed" and err:
2502
  # NOT_ENOUGH_FUNDS is the one everybody will hit; say what it means, not just its name.
2503
  extra = (" β€” the matched set is too large for this account's balance; narrow the "
@@ -2835,7 +3045,7 @@ def run_scrape_db(rt, defn, username="automation", log=print, step=_no_step, row
2835
  summary += f" β€” {note}"
2836
  steps["write"] = "partial"
2837
  if dry:
2838
- summary = f"DRY RUN (the Write step is turned off) β€” would have written: {summary}"
2839
  steps["write"] = "skipped"
2840
  elif not note:
2841
  steps["write"] = "ok"
@@ -3093,7 +3303,7 @@ def run_field_instagram(rt, defn, username="automation", log=print, step=_no_ste
3093
  if lanes:
3094
  summary += f", {counts['routed']}/{len(targets)} routed to lanes"
3095
  if counts["paid"]:
3096
- summary += f", {counts['paid']} exact via Bright Data"
3097
  if counts["metrics"]:
3098
  summary += f", {counts['metrics']} post engagement snapshots"
3099
  elif post_metrics and counts["posts"]:
@@ -3116,7 +3326,7 @@ def run_field_instagram(rt, defn, username="automation", log=print, step=_no_ste
3116
  state = "partial" if state != "error" else state
3117
  steps["write"] = "partial"
3118
  if dry:
3119
- summary = f"DRY RUN (the Write step is turned off) β€” would have written: {summary}"
3120
  steps["write"] = "skipped"
3121
  state = "partial" if state != "error" else state
3122
  if notes:
@@ -3165,8 +3375,8 @@ def run_discover_instagram(rt, defn, username="automation", log=print, step=_no_
3165
  # β›” THE FAIL-CLOSED PATH (C4). Discovery has NO anonymous rung to drop to β€” the corpus is
3166
  # the vendor's β€” so this is where the run stops, saying which env var is missing.
3167
  steps["find"] = "blocked"
3168
- return ("partial", "AIOS_BRIGHTDATA_KEY is not configured β€” profile search is closed "
3169
- "(nothing was searched and nothing was billed)", counts, [], steps)
3170
 
3171
  pending = str((defn.get("state") or {}).get("pendingSnapshot") or "")
3172
  if not pending:
@@ -3180,11 +3390,11 @@ def run_discover_instagram(rt, defn, username="automation", log=print, step=_no_
3180
  est = discover_estimate(limit)
3181
  steps["find"] = steps["write"] = "skipped"
3182
  return ("partial",
3183
- f"DRY RUN (the Write step is turned off) β€” would search for up to {limit} "
3184
  f"profile{'' if limit == 1 else 's'} matching "
3185
- f"{_predicate_sentence(preds, cfg.get('operator'))}. Estimated cost "
3186
- f"${est['usd']} (ESTIMATE β€” {est['note']})", counts, [], steps)
3187
- step("Asking Bright Data to start the search")
3188
  sid, note = bd_filter_start(preds, cfg.get("operator") or "and", limit)
3189
  if note:
3190
  steps["find"] = "blocked"
@@ -3209,7 +3419,7 @@ def run_discover_instagram(rt, defn, username="automation", log=print, step=_no_
3209
  # "Run once now is laggy / looks stuck". A counter here is what makes a legitimate
3210
  # two-minute wait distinguishable from a hung thread; without it the rendered step reads
3211
  # the same word for both, which is a progress indicator that cannot indicate progress.
3212
- step(f"Waiting for Bright Data to build the search β€” {int(waited)}s of "
3213
  f"{int(BD_FILTER_WAIT)}s")
3214
  status, size, note = bd_filter_status(pending)
3215
  if note:
@@ -3228,9 +3438,16 @@ def run_discover_instagram(rt, defn, username="automation", log=print, step=_no_
3228
  # the wrong shape. Say plainly that it is still running and who collects it.
3229
  steps["collect"] = "partial"
3230
  return ("partial",
3231
- f"the search is still running at Bright Data ({pending}) β€” searches take about "
3232
- f"20 minutes, and the NEXT run of this automation collects it. Nothing is lost "
3233
- f"and nothing is re-billed", counts, [], steps)
 
 
 
 
 
 
 
3234
  if status != "ready":
3235
  steps["collect"] = "error"
3236
  set_state(rt, auto_id, {"pendingSnapshot": None, "pendingSince": None})
@@ -3314,18 +3531,17 @@ def run_discover_instagram(rt, defn, username="automation", log=print, step=_no_
3314
  if str(r.get("handle")) in {c["handle"] for c in incoming}][:200]
3315
  est = discover_estimate(counts["found"])
3316
  summary = (f"{counts['found']} profile{'' if counts['found'] == 1 else 's'} found β€” "
3317
- f"{counts['new']} new, {counts['seen_again']} seen before. Est. cost "
3318
- f"${est['usd']} (ESTIMATE, not a billed figure). None is tracked until somebody "
3319
- f"ticks it")
3320
  if counts["dropped"]:
3321
- summary += (f". ⚠ {counts['dropped']} row{'' if counts['dropped'] == 1 else 's'} the "
3322
- f"search returned had no handle and could not be used")
3323
  cnote = cap_note([(table_key, counts["capped"])], missing)
3324
  if cnote:
3325
  summary += f" β€” {cnote}"
3326
  steps["write"] = "partial"
3327
  if dry:
3328
- summary = f"DRY RUN (the Write step is turned off) β€” would have written: {summary}"
3329
  state = "partial" if (dry or counts["capped"] or missing or not counts["found"]) else "ok"
3330
  if not dry and not missing:
3331
  try:
@@ -3337,13 +3553,19 @@ def run_discover_instagram(rt, defn, username="automation", log=print, step=_no_
3337
 
3338
 
3339
  def _predicate_sentence(preds, operator="and"):
3340
- """A predicate list as something a person can read back. Used in summaries and the canvas."""
 
 
 
 
3341
  joiner = " or " if str(operator or "").lower() == "or" else " and "
3342
  parts = []
3343
  for p in preds or []:
3344
  v = p.get("value")
3345
- parts.append(f"{p.get('name')} {p.get('operator')}"
3346
- + ("" if v is None else f" {v}"))
 
 
3347
  return joiner.join(parts) or "no conditions"
3348
 
3349
 
@@ -3571,16 +3793,16 @@ def graph(defn):
3571
  detail=f"URL column: {cfg.get('urlField')}" if cfg.get("urlField")
3572
  else "URL column: the one the field is bound to"),
3573
  node("capture", "branch", "Capture",
3574
- "Bright Data, then anonymous" if paid else "Anonymous only", 2, panel="capture",
3575
  detail=f"Up to {max_posts} posts per profile"),
3576
- node("capture_paid", "capture", "Bright Data",
3577
- "Exact counts, top posts" if paid else "Off β€” the paid rung is not used",
3578
  3, row=-1, panel="capture", on=paid,
3579
- detail="" if bd_ready() else "No AIOS_BRIGHTDATA_KEY is configured"),
3580
- node("capture_anon", "capture", "Anonymous",
3581
- "Approximate counts, $0" if anon_on else "Off β€” exact numbers or nothing",
3582
  3, row=1, panel="capture", on=anon_on,
3583
- detail="Local egress only β€” Instagram blocks datacenters"),
3584
  # ⚠ ITS OWN NODE BECAUSE IT IS ITS OWN BILL. The profile row carries post IDENTITY
3585
  # and no engagement (measured), so likes/comments are a SECOND vendor call per post.
3586
  # A switch that multiplies a run's cost by the post count deserves to be visible on
@@ -3618,17 +3840,17 @@ def graph(defn):
3618
  node("find", "source", "Find profiles",
3619
  _predicate_sentence(cfg.get("predicates"), cfg.get("operator"))[:60], 1,
3620
  panel="find",
3621
- detail=(f"Up to {limit} profiles Β· est. ${est['usd']} (ESTIMATE)"
3622
  if bd_ready()
3623
- else "No AIOS_BRIGHTDATA_KEY is configured β€” search is closed")),
3624
  node("collect", "capture", "Collect results",
3625
- f"Building: {pending}" if pending else "Searches take about 20 minutes", 2,
3626
  panel="find",
3627
- detail="A run that finds it still building hands off to the next run"),
3628
- node("write", "write", "Write candidates",
3629
  cfg.get("targetTable") or DISCOVER_TABLE, 3, panel="write",
3630
  on=not cfg.get("dryRun"),
3631
- detail="Nothing is tracked until somebody ticks it"),
3632
  ]
3633
  edges = [{"from": "trigger", "to": "find", "label": ""},
3634
  {"from": "find", "to": "collect", "label": ""},
 
1054
  DISCOVER_SEED_RECORDS = 10
1055
 
1056
 
1057
+ def _ensure_ig_action(flow_raw, table):
1058
+ """Create record is PERMANENT step 1 on `ig_profile_match` β€” it cannot be deleted or moved.
1059
+
1060
+ ⭐ OWNER RULING 2026-08-06, AND IT REVERSES WAVE 24's LAW 3. That law seeded this action once,
1061
+ on the edge into the trigger, and ended "deleting it is their call, not a refusal" β€” with a
1062
+ comment warning that re-seeding on every clean would be "a control that will not take no for
1063
+ an answer". The owner's answer: *"should ALWAYS have a 'Create record' Step 1, that can't be
1064
+ deleted, because the nature of that automation is that it needs to first create a record in a
1065
+ database somewhere from the list of profiles to fetch."*
1066
+
1067
+ Which is right, and the earlier reasoning had the category wrong: a flow whose TRIGGER
1068
+ produces rows has nowhere to put them until something writes them, so an Instagram search
1069
+ with no Create record is not a customised automation β€” it is a search whose results are
1070
+ discarded. That is not a preference to respect.
1071
+
1072
+ ⚠ IT KEEPS THE USER'S EDITS. Presence and POSITION are guaranteed; the table it writes to and
1073
+ the values it maps are theirs. An existing `create_record` further down is MOVED to the front
1074
+ rather than duplicated β€” re-seeding a second one would quietly double every run's writes.
1075
  """
1076
  flow = dict(flow_raw or {}) if isinstance(flow_raw, dict) else {}
1077
+ actions = [a for a in (flow.get("actions") or []) if isinstance(a, dict)]
1078
+ if actions and actions[0].get("kind") == "create_record":
1079
+ return flow_raw if isinstance(flow_raw, dict) else flow
1080
+ at = next((i for i, a in enumerate(actions) if a.get("kind") == "create_record"), -1)
1081
+ if at > 0:
1082
+ actions.insert(0, actions.pop(at))
1083
+ else:
1084
+ # The seed must be a config `clean_actions` ACCEPTS, or the builder shows a red banner
1085
+ # and no card: the wave-23 header records four kinds that shipped with illegal seeds and
1086
+ # did exactly that. `create_record` needs a ut_-prefixed table and at least one value.
1087
+ actions.insert(0, {
1088
+ "id": "act_1", "kind": "create_record", "enabled": True, "when": None,
1089
+ # `config.label` follows the `review` action's precedent in `_clean_action_config` β€”
1090
+ # an action naming itself, inside the untyped config bag, so no shared TS type changes.
1091
+ "config": {"table": str(table or DISCOVER_TABLE),
1092
+ "label": "Save the profile",
1093
+ "values": {"handle": "{{handle}}"}},
1094
+ })
1095
+ flow["actions"] = actions
1096
  return flow
1097
 
1098
 
1099
+ def ig_action_pinned(defn, index):
1100
+ """Is this action the one that cannot be removed? Derived, never stored β€” a stored `pinned`
1101
+ flag is a second copy of the rule, and the copy is what a hand-written PATCH omits."""
1102
+ return (defn or {}).get("kind") == "discover_instagram" and index == 0
1103
+
1104
+
1105
  def clean_definition(raw, previous=None, username=""):
1106
  """Whole-definition validation. Returns `(defn, error)`."""
1107
  raw = raw if isinstance(raw, dict) else {}
 
1158
  return None, str(e)
1159
  # (`clean_trigger` ran at the top β€” law 1 needs the trigger before the kind.)
1160
  flow_raw = raw.get("flow") if "flow" in raw else prev.get("flow")
1161
+ # ⭐ EVERY CLEAN, NOT ONLY THE EDGE (owner ruling 6 β€” see `_ensure_ig_action`). The edge-only
1162
+ # call was what made the action deletable; running it on every save is what makes step 1
1163
+ # permanent, and it is deliberate rather than a widened condition nobody noticed.
1164
+ if (trigger or {}).get("key") == "ig_profile_match":
1165
+ flow_raw = _ensure_ig_action(flow_raw, config.get("targetTable") or DISCOVER_TABLE)
1166
  flow, ferr = clean_flow(flow_raw, prev.get("flow"))
1167
  if ferr:
1168
  return None, ferr
 
1795
  headers=hdrs)
1796
  except Refused as e:
1797
  # The BASE was refused by the SSRF rail β€” a configuration fault, not a vendor outage.
1798
+ return None, f"the profile source's address was refused by the URL rail: {e}"
1799
  except Exception as e: # noqa: BLE001
1800
  # ⚠ `type(e).__name__` only. A requests exception's str() can carry the full URL, and the
1801
  # Authorization header is one refactor away from being a query param; this line must not
1802
  # be what leaks it.
1803
+ return None, f"the profile source did not answer ({type(e).__name__})"
1804
  if status == 402:
1805
+ return None, "the profile search is out of credit"
1806
  if status in (401, 403):
1807
+ return None, f"the profile source refused our key ({status})"
1808
  if status == 429:
1809
  # ⚠ MEASURED during the discovery probe: `too_many_parallel_jobs`. The filter API has a
1810
  # concurrency cap and the probe's most important test died on it β€” hence every caller
1811
  # below is SERIAL by construction.
1812
+ return None, "the profile source is busy with another search; they run one at a time"
1813
  if not (200 <= status < 300):
1814
+ return None, f"the profile source answered {status}"
1815
  # β›” A BODY THAT REACHED THE READ CEILING IS A TRUNCATION, AND IT MUST SAY SO. `fetch` reads
1816
  # at most `max_kb` and returns what it got β€” silently. A truncated JSON document then fails
1817
  # `json.loads`, falls through to the NDJSON branch, and comes back as "answered with
 
1819
  # looking for a fault that is OUR byte ceiling β€” after a result set that has already been
1820
  # paid for. Naming it here is the same no-silent-caps rule the row and table ceilings follow.
1821
  if len(raw) >= BD_MAX_KB * 1024:
1822
+ return None, (f"the profile source's answer exceeded this client's {BD_MAX_KB // 1024} MB read "
1823
  f"ceiling and was TRUNCATED β€” ask for fewer records; nothing was parsed "
1824
  f"from a partial document")
1825
  text = raw.decode("utf-8", "replace").strip()
1826
  if not text:
1827
+ return None, f"the profile source answered {status} with an empty body"
1828
  try:
1829
  return json.loads(text), ""
1830
  except Exception: # noqa: BLE001
 
1839
  try:
1840
  rows.append(json.loads(line))
1841
  except Exception: # noqa: BLE001
1842
+ return None, "the profile source answered with something we could not read"
1843
+ return (rows, "") if rows else (None, "the profile source answered with something we could not read")
1844
 
1845
 
1846
  def _first(node, *names, default=None):
 
2155
  waited += BD_SCRAPE_POLL
2156
  # β›” NAME THE SNAPSHOT. It has been paid for and it is still finishing; a note that said only
2157
  # "no rows" would throw away both the data and the way to get it.
2158
+ return [], (f"the profile source deferred this batch to {sid} and it was not ready within "
2159
  f"{int(budget)}s β€” the records are collected, not lost; ask for a smaller batch "
2160
  f"or collect {sid} from the control panel")
2161
 
 
2186
  # ⚠ `posts_count` is deliberately NOT part of this test: it arrives as a fabricated 0 and
2187
  # is discarded, so a row where it is the only "readable" field is a row we cannot read.
2188
  return {"state": "blocked", "profile": {}, "posts": [], "via": "brightdata",
2189
+ "note": "the profile source answered, but no follower/following counts were readable in "
2190
  "it (the field names may have moved β€” see instagram-capture.md)"}
2191
  posts = []
2192
  for p in (node.get("posts") or [])[:max_posts]:
 
2221
  # over a posts table that did not grow.
2222
  return {"state": "ok" if posts else "partial", "profile": profile, "posts": posts,
2223
  "via": "brightdata",
2224
+ "note": note or ("" if posts else "profile read; no posts were returned")}
2225
 
2226
 
2227
  # ---------------------------------------------------------------------------------------------
 
2325
  "full_name", "profile_name", "highlights_count", "id", "fbid", "profile_url"})
2326
  BD_MIN_NARROWING = 1
2327
 
2328
+ # ── THE FIELD SCHEMA β€” what a person sees, and what they are allowed to ask. ──────────────────
2329
+ # β›” THE SURFACE USED TO SHOW THE VENDOR'S OWN COLUMN NAMES AND ALL FOURTEEN OPERATORS ON EVERY
2330
+ # ROW. So `is_business_account` offered `>=`, `fbid` sat in the list with no explanation of what
2331
+ # it is, and `not_array_includes` was a thing a customer was expected to reason about. Owner:
2332
+ # *"look at each damn schema and only provide toggles operator that make sense"*.
2333
+ #
2334
+ # ⚠ THE LABEL IS NOW LOAD-BEARING IN BOTH DIRECTIONS. The old comment in `AutomationFind.tsx`
2335
+ # defended raw names on the grounds that a refusal names the field exactly as the row does β€” and
2336
+ # it was right, which is why `field_label()` is used by the REFUSALS too. Prettifying only the UI
2337
+ # is how you get an error message about `bio_hashtags` on a row labelled "Hashtags in bio".
2338
+ BD_FIELD_LABELS = {
2339
+ "followers": "Followers", "following": "Following", "posts_count": "Posts",
2340
+ "avg_engagement": "Engagement rate", "biography": "Bio", "category_name": "Category",
2341
+ "business_category_name": "Business category", "is_business_account": "Business account",
2342
+ "is_professional_account": "Professional account", "is_verified": "Verified",
2343
+ "account": "Handle", "full_name": "Name", "profile_name": "Profile name",
2344
+ "external_url": "Link in bio", "profile_url": "Profile link",
2345
+ "bio_hashtags": "Hashtags in bio", "post_hashtags": "Hashtags in posts",
2346
+ "related_accounts": "Related accounts", "id": "Instagram ID", "fbid": "Facebook ID",
2347
+ "highlights_count": "Story highlights",
2348
+ }
2349
+ #: A one-line "what IS this" for the rows nobody can be expected to guess. Absent = self-evident;
2350
+ #: a hint on all 21 rows is a hint on none of them (the wave-24 chip lesson).
2351
+ BD_FIELD_HINTS = {
2352
+ "account": "The @username",
2353
+ "avg_engagement": "Likes and comments as a share of followers",
2354
+ "id": "Instagram's internal number for the account β€” for matching a list you already have",
2355
+ "fbid": "The linked Facebook id β€” for matching a list you already have",
2356
+ "profile_name": "The name shown above the bio, when it differs from the account name",
2357
+ "related_accounts": "Accounts Instagram suggests alongside this one",
2358
+ }
2359
+ #: The KIND decides the comparisons offered and the control drawn for the value.
2360
+ BD_FIELD_KINDS = {
2361
+ **{n: "number" for n in ("followers", "following", "posts_count", "avg_engagement",
2362
+ "highlights_count")},
2363
+ **{n: "boolean" for n in ("is_business_account", "is_professional_account", "is_verified")},
2364
+ **{n: "tags" for n in ("bio_hashtags", "post_hashtags", "related_accounts")},
2365
+ **{n: "choice" for n in ("category_name", "business_category_name")},
2366
+ **{n: "text" for n in ("biography", "account", "full_name", "profile_name", "external_url",
2367
+ "profile_url", "id", "fbid")},
2368
+ }
2369
+ #: β›” ONLY WHAT MAKES SENSE, and the ORDER is the order they are offered in β€” the first entry of
2370
+ #: each list is what `default_operator` must agree with.
2371
+ BD_OPS_BY_KIND = {
2372
+ # ⚠ `in`/`not_in` are DELIBERATELY ABSENT. "is any of" is what `=` becomes the moment a second
2373
+ # value is typed (see `BD_MULTI_VALUE_OPS`), so offering both would be two controls for one
2374
+ # idea β€” and the second one is the one written in vendor grammar.
2375
+ "text": ("includes", "not_includes", "=", "is_not_null", "is_null"),
2376
+ "choice": ("=", "!=", "is_not_null", "is_null"),
2377
+ "number": (">=", "<=", "=", ">", "<"),
2378
+ # A yes/no field has exactly one sensible comparison and a two-option value. `!=` on a boolean
2379
+ # is `=` with the other value, written the confusing way.
2380
+ "boolean": ("=",),
2381
+ "tags": ("array_includes", "not_array_includes", "is_not_null", "is_null"),
2382
+ }
2383
+ #: Plain English for every comparison the surface can offer. The vendor's token stays on the wire
2384
+ #: (it is what the API accepts); nobody has to read it.
2385
+ BD_OP_LABELS = {
2386
+ "includes": "contains", "not_includes": "does not contain",
2387
+ "=": "is", "!=": "is not", "in": "is any of", "not_in": "is none of",
2388
+ ">=": "at least", "<=": "at most", ">": "more than", "<": "less than",
2389
+ "array_includes": "has any of", "not_array_includes": "does not have",
2390
+ "is_null": "is empty", "is_not_null": "is not empty",
2391
+ }
2392
+ #: Yes/No, so a boolean is a two-item dropdown instead of a box you type `true` into.
2393
+ BD_BOOLEAN_OPTIONS = [{"value": "true", "label": "Yes"}, {"value": "false", "label": "No"}]
2394
+
2395
+ #: ⭐ THE OPERATORS THAT MAY CARRY SEVERAL VALUES β€” owner item 3, "if i want to include many
2396
+ #: keywords like floral, flower, beauty". One condition row holds the list; `bd_filter_start`
2397
+ #: expands it into a NESTED OR group, so it composes with the other conditions instead of forcing
2398
+ #: the whole search to "match any" (which would also drag Followers into the union β€” the hole the
2399
+ #: OR guard closed the same day).
2400
+ #:
2401
+ #: β›” POSITIVE OPERATORS ONLY, and this is a correctness line rather than a scope line. "does not
2402
+ #: contain floral OR does not contain flower" matches nearly every account alive β€” a negative over
2403
+ #: a list is an AND (De Morgan), and quietly OR-ing it would build a filter that reads like a
2404
+ #: narrowing and behaves like the whole corpus. Negatives stay single-valued until someone needs
2405
+ #: them enough to write the AND branch.
2406
+ BD_MULTI_VALUE_OPS = frozenset({"includes", "=", "array_includes"})
2407
+ MAX_PREDICATE_VALUES = 12
2408
+
2409
+
2410
+ def field_label(name):
2411
+ """The human name for a searchable field β€” used by the SURFACE and by every REFUSAL."""
2412
+ return BD_FIELD_LABELS.get(name) or str(name or "that field")
2413
+
2414
+
2415
+ def field_kind(name):
2416
+ return BD_FIELD_KINDS.get(name, "text")
2417
+
2418
+
2419
+ def ops_for(name):
2420
+ """The comparisons this field may be asked. A tuple, in offer order."""
2421
+ return BD_OPS_BY_KIND.get(field_kind(name), BD_OPS_BY_KIND["text"])
2422
+
2423
  #: ⭐ WHAT A **FRESH** CONDITION ON A FIELD STARTS AS β€” and it lives HERE, beside the narrowing
2424
  #: law, because the two drifted apart and the drift cost a user their first automation.
2425
  #:
 
2449
  saveable rather than two (change the comparison, then type a value) β€” with the second step
2450
  being one the surface never told anyone to take.
2451
  """
2452
+ kind = field_kind(name)
2453
+ if kind == "tags":
2454
  return "array_includes"
2455
+ if kind in ("boolean", "choice"):
2456
+ # ⚠ `choice` LANDS HERE AND NOT ON `includes`, which is the arm it used to fall through
2457
+ # to (Category is a narrowing field). `includes` is not in `BD_OPS_BY_KIND["choice"]`, so
2458
+ # the default would have been an operator the same module refuses to offer β€” the exact
2459
+ # default-versus-guard split this function was written to close, reintroduced one commit
2460
+ # later by adding a kind. Asserted per field in `verify_automation.py`.
2461
  return "="
2462
+ if kind == "number":
2463
+ # `>=` cannot narrow the scan and is not pretending to β€” it is the comparison a person
2464
+ # reaching for Followers means, and the guard's sentence is the honest answer when it is
2465
+ # the ONLY condition present.
2466
+ return ">="
2467
+ return "=" if name in BD_EXACT_FIELDS else "includes"
2468
 
2469
 
2470
  def predicate_narrows(p):
 
2493
  if str(operator or "").lower() == "or":
2494
  if preds and all(predicate_narrows(p) for p in preds):
2495
  return ""
2496
+ return ("with Match set to any, every condition has to describe the account itself "
2497
+ "(Bio, Handle, Name, a hashtag). Matching any means the results are added "
2498
+ "together, so one follower or yes/no condition widens the whole search. Narrow "
2499
+ "every condition, or set Match to all")
2500
  if any(predicate_narrows(p) for p in preds):
2501
  return ""
2502
+ return ("add a condition that describes the account itself β€” Bio contains, Handle is, a "
2503
+ "hashtag. Follower counts and yes/no conditions alone match too much of Instagram "
2504
+ "to search")
 
2505
 
2506
 
2507
  def filter_meta():
 
2513
  `default_operator`: the client's own default was `is_not_null` for every field, which the
2514
  narrowing guard refuses on every field.
2515
  """
2516
+ return [{"name": n,
2517
+ "label": field_label(n),
2518
+ "hint": BD_FIELD_HINTS.get(n, ""),
2519
+ "kind": field_kind(n),
2520
+ "populated": n in BD_POPULATED_FIELDS,
2521
  "narrowing": n in BD_NARROWING_FIELDS,
2522
+ "defaultOperator": default_operator(n),
2523
+ # The comparisons THIS field may be asked, already in plain English and already in
2524
+ # offer order. A client that filtered a global list by field kind would be a second
2525
+ # copy of `BD_OPS_BY_KIND`, and the copy is what goes stale.
2526
+ "operators": [{"value": o, "label": BD_OP_LABELS.get(o, o),
2527
+ "nullary": o in BD_NULLARY_OPS,
2528
+ # `in`/`is any of` and the tag operators take a LIST β€” the control
2529
+ # has to know that, and deriving it from the token in the client is
2530
+ # the same second-copy mistake one level down.
2531
+ "multi": o in BD_MULTI_VALUE_OPS}
2532
+ for o in ops_for(n)],
2533
+ "options": BD_BOOLEAN_OPTIONS if field_kind(n) == "boolean" else []}
2534
+ for n in BD_FILTER_FIELDS]
2535
 
2536
  CANDIDATE_FIELDS = [
2537
  field_def("handle", "Handle"), field_def("profile_url", "Profile", "url"),
 
2567
  name = _s(p.get("name") or p.get("field"), 60).strip()
2568
  op = _s(p.get("operator") or p.get("op"), 20).strip()
2569
  if name not in BD_FILTER_FIELDS:
2570
+ return None, ("that field cannot be searched β€” the searchable ones are: "
2571
+ + ", ".join(field_label(f) for f in BD_FILTER_FIELDS))
2572
+ # ⭐ PER-FIELD, not the global list. `is_business_account >= 3` used to validate cleanly
2573
+ # because every operator was legal on every field; a yes/no column offering "at least"
2574
+ # is a question with no meaning that the vendor is nevertheless asked.
2575
+ allowed = ops_for(name)
2576
+ if op not in allowed:
2577
+ return None, (f"{field_label(name)} cannot be asked {BD_OP_LABELS.get(op, op)!r} β€” "
2578
+ "it takes: "
2579
+ + ", ".join(BD_OP_LABELS.get(o, o) for o in allowed))
2580
  entry = {"name": name, "operator": op}
2581
  if op not in BD_NULLARY_OPS:
2582
+ raw_v = p.get("value")
2583
+ # ONE value or SEVERAL β€” several is the "contains any of" shape (owner item 3), and
2584
+ # it is stored as a list rather than as N sibling predicates so the row a person sees
2585
+ # and the row that is stored are the same thing.
2586
+ vals = raw_v if isinstance(raw_v, list) else [raw_v]
2587
+ vals = [v.strip() if isinstance(v, str) else v for v in vals]
2588
+ vals = [v for v in vals if not (v is None or (isinstance(v, str) and not v))]
2589
+ if not vals:
2590
+ return None, f"give {field_label(name)} something to compare against"
2591
+ if len(vals) > 1 and op not in BD_MULTI_VALUE_OPS:
2592
+ return None, (f"{BD_OP_LABELS.get(op, op)!r} takes one value β€” "
2593
+ f"{field_label(name)} can only be given a list with "
2594
+ + ", ".join(BD_OP_LABELS[o] for o in ops_for(name)
2595
+ if o in BD_MULTI_VALUE_OPS))
2596
+ if len(vals) > MAX_PREDICATE_VALUES:
2597
+ return None, (f"{field_label(name)} takes at most {MAX_PREDICATE_VALUES} values "
2598
+ "in one condition")
2599
+ if field_kind(name) == "boolean":
2600
+ ok = {o["value"] for o in BD_BOOLEAN_OPTIONS}
2601
+ bad = [v for v in vals if str(v).lower() not in ok]
2602
+ if bad:
2603
+ return None, f"{field_label(name)} is answered Yes or No"
2604
+ vals = [str(v).lower() for v in vals]
2605
+ if field_kind(name) == "number":
2606
+ try:
2607
+ vals = [float(v) if "." in str(v) else int(v) for v in vals]
2608
+ except (TypeError, ValueError):
2609
+ return None, f"{field_label(name)} takes a number"
2610
+ # A single value stays a SCALAR on the wire. The vendor has only ever been sent
2611
+ # scalars for these operators; the list form is expanded at send time and the
2612
+ # one-value case must not quietly start exercising an untested shape.
2613
+ entry["value"] = vals[0] if len(vals) == 1 else vals
2614
  out.append(entry)
2615
  if not out:
2616
  # ⭐ WAVE 24 Β· AMENDMENT A2 β€” AN EMPTY FILTER IS INCOMPLETE, NOT WRONG, so it STORES.
 
2641
  n = max(0, int(records_limit or 0))
2642
  return {"records": n, "usd": round(n * BD_RECORD_PRICE_SPEC, 4),
2643
  "unitUsd": BD_RECORD_PRICE_SPEC, "basis": "SPEC",
2644
+ "note": "estimated from the published rate β€” an exact price is only known after a run"
2645
  "a price before a run, and this account's token cannot read a balance"}
2646
 
2647
 
2648
+ def expand_predicates(predicates):
2649
+ """Stored predicates β†’ the vendor's `filters` list, expanding a value LIST into a nested OR.
2650
+
2651
+ ⭐ MEASURED 2026-08-06: the filter API ACCEPTS a nested `{operator, filters:[…]}` inside
2652
+ `filters` (`snap_msh14ix81n8hlpo3nr`), which is what makes "Bio contains any of floral,
2653
+ flower, beauty" expressible WITHOUT setting the whole search to "match any". The alternative
2654
+ β€” the global Match dropdown β€” would drag every other condition into the same union, so
2655
+ "…and at least 10,000 followers" would silently become "…or at least 10,000 followers".
2656
+
2657
+ β›” A ONE-VALUE CONDITION IS STILL SENT FLAT. Wrapping it in a one-element group would be a
2658
+ shape nothing has ever been billed against, adopted for tidiness, on the path that spends
2659
+ money. Only the several-values case takes the new shape.
2660
+ """
2661
+ out = []
2662
+ for p in predicates or []:
2663
+ v = (p or {}).get("value")
2664
+ if isinstance(v, list) and len(v) > 1:
2665
+ out.append({"operator": "or",
2666
+ "filters": [{"name": p["name"], "operator": p["operator"], "value": one}
2667
+ for one in v]})
2668
+ elif isinstance(v, list):
2669
+ out.append({**p, "value": v[0]} if v else
2670
+ {k: val for k, val in p.items() if k != "value"})
2671
+ else:
2672
+ out.append(dict(p))
2673
+ return out
2674
+
2675
+
2676
  def bd_filter_start(predicates, operator="and", records_limit=5, dataset_id=BD_DS_PROFILES):
2677
  """Start ONE corpus query. Returns `(snapshot_id, note)`.
2678
 
 
2682
  HAS been measured end-to-end. One shape, and it is the tested one.
2683
  """
2684
  body = {"dataset_id": dataset_id, "records_limit": int(records_limit),
2685
+ "filter": {"operator": operator, "filters": expand_predicates(predicates)}}
2686
  payload, note = bd_call(BD_PATH_FILTER, body=body)
2687
  if note:
2688
  return "", note
2689
  sid = str((payload or {}).get("snapshot_id") or "") if isinstance(payload, dict) else ""
2690
  if not sid:
2691
+ return "", "the search was accepted but came back with nothing to collect it from"
2692
  return sid, ""
2693
 
2694
 
 
2700
  d = payload if isinstance(payload, dict) else {}
2701
  status = str(d.get("status") or "")
2702
  err = str(d.get("error") or "")
2703
+ if status == "failed" and "did not match any records" in err.lower():
2704
+ # ⭐ MEASURED 2026-08-06 (`snap_msh14ix81n8hlpo3nr`): a filter that matches NOTHING comes
2705
+ # back `failed` β€” "Provided filter did not match any records" β€” not `ready` with zero
2706
+ # rows. Passed through, that reached the customer as "the search failed", which is the
2707
+ # single most likely outcome of typing a keyword that is too specific and the one most
2708
+ # certain to be read as "the product is broken". It is an ANSWER, so it gets its own
2709
+ # status and no error note.
2710
+ return "empty", 0, ""
2711
  if status == "failed" and err:
2712
  # NOT_ENOUGH_FUNDS is the one everybody will hit; say what it means, not just its name.
2713
  extra = (" β€” the matched set is too large for this account's balance; narrow the "
 
3045
  summary += f" β€” {note}"
3046
  steps["write"] = "partial"
3047
  if dry:
3048
+ summary = f"Test run β€” nothing saved. Would have written: {summary}"
3049
  steps["write"] = "skipped"
3050
  elif not note:
3051
  steps["write"] = "ok"
 
3303
  if lanes:
3304
  summary += f", {counts['routed']}/{len(targets)} routed to lanes"
3305
  if counts["paid"]:
3306
+ summary += f", {counts['paid']} with exact counts"
3307
  if counts["metrics"]:
3308
  summary += f", {counts['metrics']} post engagement snapshots"
3309
  elif post_metrics and counts["posts"]:
 
3326
  state = "partial" if state != "error" else state
3327
  steps["write"] = "partial"
3328
  if dry:
3329
+ summary = f"Test run β€” nothing saved. Would have written: {summary}"
3330
  steps["write"] = "skipped"
3331
  state = "partial" if state != "error" else state
3332
  if notes:
 
3375
  # β›” THE FAIL-CLOSED PATH (C4). Discovery has NO anonymous rung to drop to β€” the corpus is
3376
  # the vendor's β€” so this is where the run stops, saying which env var is missing.
3377
  steps["find"] = "blocked"
3378
+ return ("partial", "Profile search is not set up yet β€” nothing was searched and nothing "
3379
+ "was charged", counts, [], steps)
3380
 
3381
  pending = str((defn.get("state") or {}).get("pendingSnapshot") or "")
3382
  if not pending:
 
3390
  est = discover_estimate(limit)
3391
  steps["find"] = steps["write"] = "skipped"
3392
  return ("partial",
3393
+ f"Test run β€” nothing saved. Would look for up to {limit} "
3394
  f"profile{'' if limit == 1 else 's'} matching "
3395
+ f"{_predicate_sentence(preds, cfg.get('operator'))}, for about "
3396
+ f"${est['usd']}", counts, [], steps)
3397
+ step("Starting the search")
3398
  sid, note = bd_filter_start(preds, cfg.get("operator") or "and", limit)
3399
  if note:
3400
  steps["find"] = "blocked"
 
3419
  # "Run once now is laggy / looks stuck". A counter here is what makes a legitimate
3420
  # two-minute wait distinguishable from a hung thread; without it the rendered step reads
3421
  # the same word for both, which is a progress indicator that cannot indicate progress.
3422
+ step(f"Searching β€” {int(waited)}s of "
3423
  f"{int(BD_FILTER_WAIT)}s")
3424
  status, size, note = bd_filter_status(pending)
3425
  if note:
 
3438
  # the wrong shape. Say plainly that it is still running and who collects it.
3439
  steps["collect"] = "partial"
3440
  return ("partial",
3441
+ "Still searching β€” this takes about 20 minutes. The next run picks up the results; nothing is lost and you are not charged twice", counts, [], steps)
3442
+ if status == "empty":
3443
+ # A search that matched nothing RAN CORRECTLY. It is the ordinary result of a keyword
3444
+ # that is too specific, so it says what to do about it instead of reporting a fault.
3445
+ steps["collect"] = "ok"
3446
+ steps["write"] = "skipped"
3447
+ set_state(rt, auto_id, {"pendingSnapshot": None, "pendingSince": None})
3448
+ return ("partial", "No profiles matched. Try a shorter or more common keyword β€” "
3449
+ "'floral' finds more accounts than 'floral design studio'",
3450
+ counts, [], steps)
3451
  if status != "ready":
3452
  steps["collect"] = "error"
3453
  set_state(rt, auto_id, {"pendingSnapshot": None, "pendingSince": None})
 
3531
  if str(r.get("handle")) in {c["handle"] for c in incoming}][:200]
3532
  est = discover_estimate(counts["found"])
3533
  summary = (f"{counts['found']} profile{'' if counts['found'] == 1 else 's'} found β€” "
3534
+ f"{counts['new']} new, {counts['seen_again']} seen before. About "
3535
+ f"${est['usd']}")
 
3536
  if counts["dropped"]:
3537
+ summary += (f". {counts['dropped']} result{'' if counts['dropped'] == 1 else 's'} had no "
3538
+ f"username and could not be saved")
3539
  cnote = cap_note([(table_key, counts["capped"])], missing)
3540
  if cnote:
3541
  summary += f" β€” {cnote}"
3542
  steps["write"] = "partial"
3543
  if dry:
3544
+ summary = f"Test run β€” nothing saved. Would have written: {summary}"
3545
  state = "partial" if (dry or counts["capped"] or missing or not counts["found"]) else "ok"
3546
  if not dry and not missing:
3547
  try:
 
3553
 
3554
 
3555
  def _predicate_sentence(preds, operator="and"):
3556
+ """A predicate list as something a person can read back. Used in summaries and the canvas.
3557
+
3558
+ Human words on BOTH halves β€” it used to render `biography includes floral`, the vendor's
3559
+ column name beside the vendor's operator token, in a sentence shown to a customer.
3560
+ """
3561
  joiner = " or " if str(operator or "").lower() == "or" else " and "
3562
  parts = []
3563
  for p in preds or []:
3564
  v = p.get("value")
3565
+ shown = " or ".join(str(x) for x in v) if isinstance(v, list) else v
3566
+ parts.append(f"{field_label(p.get('name'))} "
3567
+ f"{BD_OP_LABELS.get(p.get('operator'), p.get('operator'))}"
3568
+ + ("" if shown is None else f" {shown}"))
3569
  return joiner.join(parts) or "no conditions"
3570
 
3571
 
 
3793
  detail=f"URL column: {cfg.get('urlField')}" if cfg.get("urlField")
3794
  else "URL column: the one the field is bound to"),
3795
  node("capture", "branch", "Capture",
3796
+ "Exact counts, then estimates" if paid else "Estimated counts only", 2, panel="capture",
3797
  detail=f"Up to {max_posts} posts per profile"),
3798
+ node("capture_paid", "capture", "Exact counts",
3799
+ "Exact followers and top posts" if paid else "Off",
3800
  3, row=-1, panel="capture", on=paid,
3801
+ detail="" if bd_ready() else "Not set up yet"),
3802
+ node("capture_anon", "capture", "Estimated counts",
3803
+ "Free, rounded numbers" if anon_on else "Off",
3804
  3, row=1, panel="capture", on=anon_on,
3805
+ detail="Rounded to the nearest thousand"),
3806
  # ⚠ ITS OWN NODE BECAUSE IT IS ITS OWN BILL. The profile row carries post IDENTITY
3807
  # and no engagement (measured), so likes/comments are a SECOND vendor call per post.
3808
  # A switch that multiplies a run's cost by the post count deserves to be visible on
 
3840
  node("find", "source", "Find profiles",
3841
  _predicate_sentence(cfg.get("predicates"), cfg.get("operator"))[:60], 1,
3842
  panel="find",
3843
+ detail=(f"Up to {limit} profiles Β· about ${est['usd']}"
3844
  if bd_ready()
3845
+ else "Profile search is not set up yet")),
3846
  node("collect", "capture", "Collect results",
3847
+ "Searching…" if pending else "Takes about 20 minutes", 2,
3848
  panel="find",
3849
+ detail=""),
3850
+ node("write", "write", "Save results",
3851
  cfg.get("targetTable") or DISCOVER_TABLE, 3, panel="write",
3852
  on=not cfg.get("dryRun"),
3853
+ detail=""),
3854
  ]
3855
  edges = [{"from": "trigger", "to": "find", "label": ""},
3856
  {"from": "find", "to": "collect", "label": ""},
web/src/automation/AutomationBuilder.tsx CHANGED
@@ -743,8 +743,18 @@ export default function AutomationBuilder({
743
  const row = catalog.find((c) => c.kind === a.kind);
744
  const isGroup = a.kind === "group";
745
  const branches = isGroup ? groupBranches(a) : [];
 
 
 
 
 
 
 
 
 
 
746
  /** Only TOP-LEVEL cards reorder (see `moveAction`) β€” depth 0, and never while a write is up. */
747
- const canDrag = depth === 0 && !busy;
748
  return (
749
  <div className="autox-actionwrap" key={a.id}>
750
  <div
@@ -850,19 +860,25 @@ export default function AutomationBuilder({
850
  )}
851
  </span>
852
  </button>
853
- <button
854
- type="button"
855
- className="autox-card-drop"
856
- disabled={busy}
857
- aria-label={`Remove ${row?.label || a.kind}`}
858
- title={`Remove ${row?.label || a.kind}`}
859
- onClick={() => dropAction(a.id)}
860
- >
861
- <svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden="true">
862
- <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.5"
863
- strokeLinecap="round" />
864
- </svg>
865
- </button>
 
 
 
 
 
 
866
  </div>
867
 
868
  {/*
 
743
  const row = catalog.find((c) => c.kind === a.kind);
744
  const isGroup = a.kind === "group";
745
  const branches = isGroup ? groupBranches(a) : [];
746
+ /**
747
+ * ⭐ THE PERMANENT FIRST STEP (owner ruling 2026-08-06). An Instagram search produces rows
748
+ * and has nowhere to put them until something writes them, so Create record is step 1 and
749
+ * stays. DERIVED from the same rule the server enforces (`ig_action_pinned`) rather than
750
+ * from a stored flag β€” and the control is HIDDEN rather than disabled, because the server
751
+ * re-inserts the action on the next save, so a delete button here would appear to work and
752
+ * then silently undo itself.
753
+ */
754
+ const pinned =
755
+ automation.kind === "discover_instagram" && depth === 0 && a.id === actions[0]?.id;
756
  /** Only TOP-LEVEL cards reorder (see `moveAction`) β€” depth 0, and never while a write is up. */
757
+ const canDrag = depth === 0 && !busy && !pinned;
758
  return (
759
  <div className="autox-actionwrap" key={a.id}>
760
  <div
 
860
  )}
861
  </span>
862
  </button>
863
+ {pinned ? (
864
+ <span className="autox-card-pin" title="Every search saves what it finds">
865
+ Always first
866
+ </span>
867
+ ) : (
868
+ <button
869
+ type="button"
870
+ className="autox-card-drop"
871
+ disabled={busy}
872
+ aria-label={`Remove ${row?.label || a.kind}`}
873
+ title={`Remove ${row?.label || a.kind}`}
874
+ onClick={() => dropAction(a.id)}
875
+ >
876
+ <svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden="true">
877
+ <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.5"
878
+ strokeLinecap="round" />
879
+ </svg>
880
+ </button>
881
+ )}
882
  </div>
883
 
884
  {/*
web/src/automation/AutomationDetail.tsx CHANGED
@@ -877,20 +877,20 @@ export default function AutomationDetail({
877
  />
878
  </div>
879
  ) : null}
880
- <p className="auto-hint">
881
- Public web pages only. Private, loopback and link-local addresses are refused
882
- β€” including a public URL that redirects to one.
883
- </p>
884
  </>
885
  ) : null}
886
 
887
  {panelKey === "columns" ? (
888
  plan.length ? (
889
  <>
 
 
890
  <p className="auto-hint">
891
- Pick the key β€” the column that identifies a row. On every re-run, a row
892
- whose key already exists is updated; a new key is inserted; a key that has
893
- stopped appearing is counted and kept.
894
  </p>
895
  <div className="auto-panel-scroll">
896
  <table className="auto-table">
@@ -1058,35 +1058,23 @@ export default function AutomationDetail({
1058
  onChange={(e) => edit(setMaxPosts)(Number(e.target.value) || 24)}
1059
  />
1060
  </div>
1061
- <h3>Bright Data β€” the paid rung</h3>
1062
- <p className="auto-hint">
1063
- Exact follower counts and the profile&rsquo;s top posts, and it works from a
1064
- datacenter. Its node&rsquo;s switch turns it on.
1065
- {paidReady
1066
- ? " A key is configured on this deployment."
1067
- : " No key is configured on this deployment yet, so it will report itself blocked and the anonymous rung will answer instead."}
1068
- </p>
1069
- <h3>Post engagement β€” the per-post rung</h3>
1070
  <p className="auto-hint">
1071
- Likes and comments for each post. It is a separate step because it is a
1072
- separate bill: the profile read costs one record, and engagement costs{" "}
1073
- <strong>one record per post</strong>. With it off, the posts database still
1074
- grows but the engagement series does not β€” and no empty rows are appended to
1075
- stand in for the numbers nobody bought.
1076
  </p>
1077
- <h3>Anonymous β€” the free rung</h3>
1078
  <p className="auto-hint">
1079
- No login and no credentials. Instagram blocks datacenter addresses and has
1080
- closed most of its anonymous surface, so this rung is honest rather than
1081
- reliable: counts come from the page&rsquo;s own abbreviations (204K, not
1082
- 204,312) and are marked approximate. Turning it off means{" "}
1083
- <strong>exact numbers or nothing</strong> β€” a run reports blocked rather than
1084
- quietly writing a rounded number.
1085
  </p>
 
1086
  <p className="auto-hint">
1087
- A pull reports what it actually got: <strong>ok</strong> (profile and posts),{" "}
1088
- <strong>partial</strong> (profile only), or <strong>blocked</strong>. It never
1089
- reports success on nothing.
1090
  </p>
1091
  </>
1092
  ) : null}
@@ -1126,43 +1114,36 @@ export default function AutomationDetail({
1126
  />
1127
  </div>
1128
  ) : kind === "discover_instagram" ? (
 
 
 
 
 
 
 
 
 
 
1129
  <p className="auto-hint">
1130
- Matches are collected into{" "}
1131
- <code>{discover?.table || "ut_ig_candidates"}</code>, upserted by handle β€” so
1132
- re-finding an account costs nothing and its <em>Times found</em> count grows.{" "}
1133
- <strong>Nothing found is ever tracked automatically.</strong> Tick the ones
1134
- you want; a later search can never un-tick them.
1135
  </p>
1136
  ) : (
1137
  <p className="auto-hint">
1138
- Each pull appends a timestamped row to <code>ut_ig_snapshots</code> and, when
1139
- the post-engagement step is on, one per post to{" "}
1140
- <code>ut_ig_post_snapshots</code> β€” so the history is a time series you can
1141
- filter by date rather than a single current value.{" "}
1142
- <code>ut_ig_posts</code> holds one row per post, ever.
1143
  </p>
1144
  )}
1145
  <p className="auto-hint">
1146
- Turning this step off makes the automation a <strong>dry run</strong>: it
1147
- reads everything and reports exactly what it would have written, without
1148
- creating or changing a single row.
1149
- </p>
1150
- {kind === "field_instagram" ? (
1151
- <p className="auto-hint">
1152
- {/*
1153
- ⚠ "Writes nothing" and "costs nothing" are DIFFERENT CLAIMS, and only the
1154
- first one is true. A dry run still READS β€” so with the paid steps on it
1155
- bills exactly what a real run bills. Saying so here is the only place a
1156
- user finds out before the invoice.
1157
- */}
1158
- A dry run still <strong>reads</strong>. With the Bright Data step on it
1159
- costs what a real run costs, and with post engagement on that is one
1160
- charged record per post. Turn those steps off too if you want a free
1161
- rehearsal.
1162
- </p>
1163
- ) : null}
1164
- <p className="auto-hint">
1165
- A row that stops appearing at the source is counted and kept, never deleted.
1166
  </p>
1167
  </>
1168
  ) : null}
 
877
  />
878
  </div>
879
  ) : null}
880
+ {/* "loopback and link-local addresses" is the SSRF rail describing itself.
881
+ The rail still refuses them, loudly, at the moment it happens. */}
882
+ <p className="auto-hint">Public web pages only.</p>
 
883
  </>
884
  ) : null}
885
 
886
  {panelKey === "columns" ? (
887
  plan.length ? (
888
  <>
889
+ {/* The upsert rules, in full, to somebody choosing a column. What they
890
+ need is which column, and that rows are updated rather than duplicated. */}
891
  <p className="auto-hint">
892
+ Pick the column that identifies a row, so re-runs update it instead of
893
+ adding it again.
 
894
  </p>
895
  <div className="auto-panel-scroll">
896
  <table className="auto-table">
 
1058
  onChange={(e) => edit(setMaxPosts)(Number(e.target.value) || 24)}
1059
  />
1060
  </div>
1061
+ {/* β›” THREE <h3> ESSAYS ON THE CAPTURE RUNGS lived here β€” the vendor by name,
1062
+ datacenter egress, "204K not 204,312", which rung answers when. The
1063
+ CHOICE a person makes is exact-or-estimated and what it costs; the rest
1064
+ was the architecture explaining itself. DESIGN.md Β§4. */}
1065
+ <h3>Exact counts</h3>
 
 
 
 
1066
  <p className="auto-hint">
1067
+ Real follower numbers and the account&rsquo;s top posts, charged per profile.
1068
+ {paidReady ? "" : " Not set up on this workspace yet."}
 
 
 
1069
  </p>
1070
+ <h3>Post engagement</h3>
1071
  <p className="auto-hint">
1072
+ Likes and comments per post. Charged per post, so it is its own switch.
 
 
 
 
 
1073
  </p>
1074
+ <h3>Estimated counts</h3>
1075
  <p className="auto-hint">
1076
+ Free, but rounded (204K rather than 204,312) and marked as estimates. Switch
1077
+ it off to get exact numbers or nothing.
 
1078
  </p>
1079
  </>
1080
  ) : null}
 
1114
  />
1115
  </div>
1116
  ) : kind === "discover_instagram" ? (
1117
+ /*
1118
+ β›” FOUR PARAGRAPHS LIVED HERE and the owner quoted every one of them back:
1119
+ the upsert key, the Times-found counter, the never-un-ticked guarantee,
1120
+ the dry-run definition, and "a row that stops appearing at the source is
1121
+ counted and kept, never deleted". All TRUE, all engine internals, none of
1122
+ them a thing a customer came here to learn. DESIGN.md Β§4.
1123
+ What survives is the only sentence with a decision in it: results wait for
1124
+ you. (Duplicates elsewhere are gone rather than reworded β€” the Find panel
1125
+ already says nothing is picked automatically.)
1126
+ */
1127
  <p className="auto-hint">
1128
+ Profiles you find are saved here for you to review. Nothing is picked
1129
+ automatically.
 
 
 
1130
  </p>
1131
  ) : (
1132
  <p className="auto-hint">
1133
+ Each run adds a dated row, so you keep the history rather than just
1134
+ today&rsquo;s number.
 
 
 
1135
  </p>
1136
  )}
1137
  <p className="auto-hint">
1138
+ Switch this off to test the automation without saving anything.
1139
+ {kind === "field_instagram" ? (
1140
+ <>
1141
+ {" "}
1142
+ {/* "Writes nothing" and "costs nothing" are different claims and only
1143
+ the first is true β€” the one place anybody finds out before the bill. */}
1144
+ It still reads, so it still costs the same.
1145
+ </>
1146
+ ) : null}
 
 
 
 
 
 
 
 
 
 
 
1147
  </p>
1148
  </>
1149
  ) : null}
web/src/automation/AutomationFind.tsx CHANGED
@@ -34,6 +34,7 @@
34
  import type {
35
  DiscoverEstimate,
36
  DiscoverFieldMeta,
 
37
  DiscoverVocab,
38
  Predicate,
39
  } from "./automationApi";
@@ -199,6 +200,12 @@ function FilterMark({ name }: { name: string }) {
199
  /** One field's line in the list, with everything known about it. */
200
  interface FieldRow {
201
  name: string;
 
 
 
 
 
 
202
  /** Every stored condition naming this field, with its index in the saved array. */
203
  at: number[];
204
  /** MEASURED to carry values. `null` = the server has not said (C4 not shipped yet). */
@@ -207,6 +214,29 @@ interface FieldRow {
207
  narrowing: boolean | null;
208
  }
209
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
210
  /**
211
  * The comparison a freshly toggled field starts with β€” ASKED FOR, never chosen here.
212
  *
@@ -253,6 +283,14 @@ function buildRows(preds: Predicate[], v?: DiscoverVocab): FieldRow[] {
253
  const m = meta.get(name);
254
  return {
255
  name,
 
 
 
 
 
 
 
 
256
  at: byName.get(name) || [],
257
  populated: m ? !!m.populated : lead.has(name) ? true : null,
258
  narrowing: m ? !!m.narrowing : null,
@@ -277,8 +315,10 @@ export default function AutomationFind({
277
  }: Props) {
278
  const rows = buildRows(preds, discover);
279
  const known = new Set(discover?.fields || []);
 
 
 
280
  const nullary = new Set(discover?.nullaryOperators || []);
281
- const operators = discover?.operators || [];
282
  const withValues = rows.filter((r) => r.populated === true);
283
  const rest = rows.filter((r) => r.populated !== true);
284
  const knownMeta = !!(discover?.filterMeta || []).length;
@@ -307,9 +347,16 @@ export default function AutomationFind({
307
  };
308
 
309
  /** One condition line β€” the comparison, its value, and a way out. */
310
- const condition = (i: number, label: string) => {
311
  const p = preds[i];
312
  if (!p) return null;
 
 
 
 
 
 
 
313
  return (
314
  <div className="autob-cond" key={`${p.name}-${i}`}>
315
  <select
@@ -321,27 +368,49 @@ export default function AutomationFind({
321
  {/* The stored value is ALWAYS an option. A select whose value matches no
322
  option renders the FIRST one, and the next Save writes a comparison
323
  nobody chose β€” this codebase has paid for that twice. */}
324
- {p.operator && !operators.includes(p.operator) ? (
325
  <option value={p.operator}>{p.operator}</option>
326
  ) : null}
327
- {operators.map((o) => (
328
- <option key={o} value={o}>
329
- {o}
330
  </option>
331
  ))}
332
  </select>
333
- {nullary.has(p.operator) ? (
334
- <span className="autob-cond-novalue" title="This comparison takes no value">
335
- any value
336
- </span>
 
 
 
 
 
 
 
 
 
 
 
 
337
  ) : (
338
  <input
339
  className="auto-input is-small"
 
340
  aria-label={`Value for ${label}`}
341
- value={p.value === undefined ? "" : String(p.value)}
342
- onChange={(e) => setAt(i, { value: e.target.value })}
 
 
 
 
343
  />
344
  )}
 
 
 
 
 
345
  <button
346
  type="button"
347
  className="autob-cond-x"
@@ -366,8 +435,8 @@ export default function AutomationFind({
366
  type="button"
367
  className={"auto-step-switch autob-tgl-switch" + (on ? " is-on" : "")}
368
  aria-pressed={on}
369
- aria-label={`${on ? "Stop searching" : "Search"} on ${row.name}`}
370
- title={`${on ? "Stop searching" : "Search"} on ${row.name}`}
371
  onClick={() => toggleField(row)}
372
  >
373
  <span className="auto-step-switch-knob" />
@@ -375,11 +444,15 @@ export default function AutomationFind({
375
  <span className="autob-tgl-mark">
376
  <FilterMark name={row.name} />
377
  </span>
378
- {/* The VENDOR'S OWN NAME, verbatim. Not prettified: every refusal the
379
- server sends names the field exactly like this ("'x' cannot be used
380
- to search β€” the searchable fields are: …"), and a label that reads
381
- differently from the error makes the error unmatchable. */}
382
- <span className="autob-tgl-name">{row.name}</span>
 
 
 
 
383
  {/*
384
  ⚠ ONE CHIP, AND IT MARKS THE MINORITY. The first version chipped every
385
  non-narrowing field "broad" AND every unpopulated one "no values seen" β€”
@@ -396,7 +469,7 @@ export default function AutomationFind({
396
  {row.narrowing === true ? (
397
  <span
398
  className="autob-tgl-flag is-narrow"
399
- title="Cuts the corpus down. A search needs at least one condition that does."
400
  >
401
  narrows
402
  </span>
@@ -404,7 +477,8 @@ export default function AutomationFind({
404
  </div>
405
  {on ? (
406
  <div className="autob-tgl-body">
407
- {row.at.map((i) => condition(i, row.name))}
 
408
  <button
409
  type="button"
410
  className="autob-cond-add"
@@ -412,7 +486,7 @@ export default function AutomationFind({
412
  onPreds([...preds, { name: row.name, operator: firstOperator(discover, row.name) }])
413
  }
414
  >
415
- Another condition on {row.name}
416
  </button>
417
  </div>
418
  ) : null}
@@ -434,11 +508,10 @@ export default function AutomationFind({
434
  onChange={(e) => onRecordsLimit(Number(e.target.value) || 1)}
435
  />
436
  </div>
437
- <p className="auto-hint">
438
- A search must be bounded β€” at most {maxRecords.toLocaleString()} profiles a run. An
439
- unbounded one matches a share of a corpus of hundreds of millions, and the vendor
440
- refuses it outright rather than delivering it.
441
- </p>
442
 
443
  <h3>Conditions</h3>
444
  <div className="auto-field autob-match">
@@ -464,9 +537,9 @@ export default function AutomationFind({
464
  <div className="autob-tglgroup">
465
  <p
466
  className="autob-tglgroup-label"
467
- title="Seen carrying values on real corpus rows."
468
  >
469
- Has values
470
  </p>
471
  {withValues.map(fieldRow)}
472
  </div>
@@ -478,11 +551,11 @@ export default function AutomationFind({
478
  className="autob-tglgroup-label"
479
  title={
480
  knownMeta
481
- ? "Filterable, but empty on every profile we have measured β€” a condition on one of these can return nothing at all."
482
- : "Whether these carry values has not been measured yet."
483
  }
484
  >
485
- {knownMeta ? "No values seen" : "Not measured"}
486
  </p>
487
  {rest.map(fieldRow)}
488
  </div>
@@ -513,14 +586,11 @@ export default function AutomationFind({
513
  </div>
514
  ) : null}
515
 
 
 
 
516
  <p className="auto-hint">
517
- {/* ONE consequence sentence, because it is the one that costs money. Which
518
- fields carry values is not trivia: a condition on an empty field returns
519
- nothing and looks exactly like an honest "no such accounts exist". */}
520
- A condition on a field with no values returns nothing while looking exactly like
521
- &ldquo;no such accounts exist&rdquo;. Narrow conditions matter more than a small limit
522
- β€” the search reads the whole corpus either way, so a broad one is slow and expensive
523
- however few rows you keep.
524
  </p>
525
 
526
  <h3>What it costs</h3>
 
34
  import type {
35
  DiscoverEstimate,
36
  DiscoverFieldMeta,
37
+ DiscoverOperator,
38
  DiscoverVocab,
39
  Predicate,
40
  } from "./automationApi";
 
200
  /** One field's line in the list, with everything known about it. */
201
  interface FieldRow {
202
  name: string;
203
+ /** What the row is CALLED. Falls back to the raw name only if the server sent none. */
204
+ label: string;
205
+ hint: string;
206
+ kind: string;
207
+ operators: DiscoverOperator[];
208
+ options: { value: string; label: string }[];
209
  /** Every stored condition naming this field, with its index in the saved array. */
210
  at: number[];
211
  /** MEASURED to carry values. `null` = the server has not said (C4 not shipped yet). */
 
214
  narrowing: boolean | null;
215
  }
216
 
217
+ /** A stored value β†’ what the text box shows. A list is the "any of" shape. */
218
+ function valueText(v: Predicate["value"]): string {
219
+ if (Array.isArray(v)) return v.join(", ");
220
+ return v === undefined || v === null ? "" : String(v);
221
+ }
222
+
223
+ /**
224
+ * What the user typed β†’ what is stored. Comma-separated becomes a LIST for the operators that
225
+ * accept one, and stays a plain string for the ones that do not.
226
+ *
227
+ * ⚠ A single value stays a SCALAR rather than a one-element list β€” the server sends scalars
228
+ * flat and lists as a nested OR group, and a one-element group is a shape nothing has been
229
+ * billed against.
230
+ */
231
+ function parseValue(text: string, multi: boolean): Predicate["value"] {
232
+ if (!multi) return text;
233
+ const parts = text.split(",").map((s) => s.trim()).filter(Boolean);
234
+ if (parts.length > 1) return parts;
235
+ // Keep the RAW text while it is still being typed β€” trimming here would fight the cursor on
236
+ // every keystroke, and the server trims anyway.
237
+ return text;
238
+ }
239
+
240
  /**
241
  * The comparison a freshly toggled field starts with β€” ASKED FOR, never chosen here.
242
  *
 
283
  const m = meta.get(name);
284
  return {
285
  name,
286
+ label: m?.label || name,
287
+ hint: m?.hint || "",
288
+ kind: m?.kind || "text",
289
+ // β›” NO FALLBACK TO THE GLOBAL OPERATOR LIST. An older server that sends no per-field list
290
+ // gets a row with no comparisons rather than all fourteen on every field β€” visibly
291
+ // unfinished beats quietly offering `at least` on a yes/no column.
292
+ operators: m?.operators || [],
293
+ options: m?.options || [],
294
  at: byName.get(name) || [],
295
  populated: m ? !!m.populated : lead.has(name) ? true : null,
296
  narrowing: m ? !!m.narrowing : null,
 
315
  }: Props) {
316
  const rows = buildRows(preds, discover);
317
  const known = new Set(discover?.fields || []);
318
+ // The GLOBAL operator list is gone from this component: comparisons are per field now
319
+ // (`row.operators`). `nullary` survives for STRAYS only β€” a stored condition on a field the
320
+ // vendor dropped has no per-field row to read from, and it still has to render to be removable.
321
  const nullary = new Set(discover?.nullaryOperators || []);
 
322
  const withValues = rows.filter((r) => r.populated === true);
323
  const rest = rows.filter((r) => r.populated !== true);
324
  const knownMeta = !!(discover?.filterMeta || []).length;
 
347
  };
348
 
349
  /** One condition line β€” the comparison, its value, and a way out. */
350
+ const condition = (i: number, label: string, row?: FieldRow) => {
351
  const p = preds[i];
352
  if (!p) return null;
353
+ // The field's OWN comparisons. `row` is absent only for a stray (a stored condition on a
354
+ // field the vendor no longer offers), which keeps the raw token so it stays removable.
355
+ const ops = row?.operators || [];
356
+ const cur = ops.find((o) => o.value === p.operator);
357
+ const isNullary = cur ? cur.nullary : nullary.has(p.operator);
358
+ const isMulti = !!cur?.multi;
359
+ const options = row?.options || [];
360
  return (
361
  <div className="autob-cond" key={`${p.name}-${i}`}>
362
  <select
 
368
  {/* The stored value is ALWAYS an option. A select whose value matches no
369
  option renders the FIRST one, and the next Save writes a comparison
370
  nobody chose β€” this codebase has paid for that twice. */}
371
+ {p.operator && !ops.some((o) => o.value === p.operator) ? (
372
  <option value={p.operator}>{p.operator}</option>
373
  ) : null}
374
+ {ops.map((o) => (
375
+ <option key={o.value} value={o.value}>
376
+ {o.label}
377
  </option>
378
  ))}
379
  </select>
380
+ {isNullary ? null : options.length ? (
381
+ // A fixed vocabulary gets a dropdown. Owner item 2: a yes/no column was a box you
382
+ // typed `true` into, beside a comparison list that offered "at least".
383
+ <select
384
+ className="auto-input is-small"
385
+ aria-label={`Value for ${label}`}
386
+ value={valueText(p.value)}
387
+ onChange={(e) => setAt(i, { value: e.target.value })}
388
+ >
389
+ <option value="">Choose…</option>
390
+ {options.map((o) => (
391
+ <option key={o.value} value={o.value}>
392
+ {o.label}
393
+ </option>
394
+ ))}
395
+ </select>
396
  ) : (
397
  <input
398
  className="auto-input is-small"
399
+ type={row?.kind === "number" ? "number" : "text"}
400
  aria-label={`Value for ${label}`}
401
+ // ⭐ OWNER ITEM 3. Several comma-separated values become an "any of" condition, which
402
+ // the server sends as its own OR group β€” so it does NOT drag Followers into a union
403
+ // the way the Match dropdown would.
404
+ placeholder={isMulti ? "floral, flower, beauty" : ""}
405
+ value={valueText(p.value)}
406
+ onChange={(e) => setAt(i, { value: parseValue(e.target.value, isMulti) })}
407
  />
408
  )}
409
+ {isMulti && Array.isArray(p.value) && p.value.length > 1 ? (
410
+ <span className="autob-cond-any" title="Any one of these is a match">
411
+ any of {p.value.length}
412
+ </span>
413
+ ) : null}
414
  <button
415
  type="button"
416
  className="autob-cond-x"
 
435
  type="button"
436
  className={"auto-step-switch autob-tgl-switch" + (on ? " is-on" : "")}
437
  aria-pressed={on}
438
+ aria-label={`${on ? "Stop searching" : "Search"} on ${row.label}`}
439
+ title={`${on ? "Stop searching" : "Search"} on ${row.label}`}
440
  onClick={() => toggleField(row)}
441
  >
442
  <span className="auto-step-switch-knob" />
 
444
  <span className="autob-tgl-mark">
445
  <FilterMark name={row.name} />
446
  </span>
447
+ {/* ⭐ THE HUMAN LABEL (owner item 1: "wtf is id/fbid").
448
+ This used to render the vendor's own column name verbatim, and the comment
449
+ defending it was RIGHT about the reason β€” a refusal names the field, and a label
450
+ that reads differently makes the error unmatchable. So the label did not move
451
+ alone: `field_label()` is what the SERVER's refusals use too, which is the only
452
+ version of this change that does not trade one confusion for another. */}
453
+ <span className="autob-tgl-name" title={row.hint || undefined}>
454
+ {row.label}
455
+ </span>
456
  {/*
457
  ⚠ ONE CHIP, AND IT MARKS THE MINORITY. The first version chipped every
458
  non-narrowing field "broad" AND every unpopulated one "no values seen" β€”
 
469
  {row.narrowing === true ? (
470
  <span
471
  className="autob-tgl-flag is-narrow"
472
+ title="A search needs at least one condition like this."
473
  >
474
  narrows
475
  </span>
 
477
  </div>
478
  {on ? (
479
  <div className="autob-tgl-body">
480
+ {row.at.map((i) => condition(i, row.label, row))}
481
+ {row.hint ? <p className="autob-tgl-hint">{row.hint}</p> : null}
482
  <button
483
  type="button"
484
  className="autob-cond-add"
 
486
  onPreds([...preds, { name: row.name, operator: firstOperator(discover, row.name) }])
487
  }
488
  >
489
+ Another condition on {row.label}
490
  </button>
491
  </div>
492
  ) : null}
 
508
  onChange={(e) => onRecordsLimit(Number(e.target.value) || 1)}
509
  />
510
  </div>
511
+ {/* Owner item 5: "Stop at the 'A search must be at most 500 profiles a run'". The two
512
+ sentences that followed explained the vendor's billing model to somebody who wants a
513
+ list of florists. */}
514
+ <p className="auto-hint">At most {maxRecords.toLocaleString()} profiles a run.</p>
 
515
 
516
  <h3>Conditions</h3>
517
  <div className="auto-field autob-match">
 
537
  <div className="autob-tglgroup">
538
  <p
539
  className="autob-tglgroup-label"
540
+ title="Most accounts have this filled in."
541
  >
542
+ Usually filled in
543
  </p>
544
  {withValues.map(fieldRow)}
545
  </div>
 
551
  className="autob-tglgroup-label"
552
  title={
553
  knownMeta
554
+ ? "Most accounts leave these blank, so a condition here can return nothing."
555
+ : "We have not measured how often these are filled in."
556
  }
557
  >
558
+ {knownMeta ? "Often blank" : "Not measured"}
559
  </p>
560
  {rest.map(fieldRow)}
561
  </div>
 
586
  </div>
587
  ) : null}
588
 
589
+ {/* The consequence kept, the mechanism dropped: a condition on an often-blank field
590
+ returning nothing is a thing that will happen to somebody and confuse them. Why the
591
+ search is slow when broad is our problem, not theirs. */}
592
  <p className="auto-hint">
593
+ Conditions on often-blank fields can come back with nothing.
 
 
 
 
 
 
594
  </p>
595
 
596
  <h3>What it costs</h3>
web/src/automation/automationApi.ts CHANGED
@@ -1,931 +1,962 @@
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
- /**
20
- * ⭐ WAVE 24 / R6 β€” `plain` IS A REAL KIND, and it is the default for every new automation.
21
- * No machine graph nodes: the flow's ACTIONS are the whole automation. It exists because
22
- * `clean_definition` refuses a definition with no kind, so "an automation that is just a
23
- * trigger and some steps" needed a name at the door rather than a special case behind it.
24
- * `scrape_db` and `field_instagram` survive on the two automations that already use them and
25
- * no new one can be created (R6); `discover_instagram` is now reached by PICKING the
26
- * `ig_profile_match` trigger rather than by a wizard.
27
- */
28
- export type AutomationKind =
29
- | "scrape_db"
30
- | "field_instagram"
31
- | "discover_instagram"
32
- | "plain";
33
- export type RunState = "idle" | "running" | "ok" | "error" | "partial";
34
- /**
35
- * ⚠ `hiker` is NOT in this union any more (wave 20, D-21) β€” the vendor moved.
36
- * Stored configs still SAY `hiker` and the server maps them forward
37
- * (`TIER_ALIASES`), so nothing in this client should ever write that word.
38
- */
39
- export type CaptureTier = "anonymous" | "brightdata";
40
-
41
- /**
42
- * A node's dot. Deliberately WIDER than `RunState` β€” a single step can be
43
- * `blocked` (a rung refused) or `skipped` (a switch is off) in ways a whole run
44
- * cannot, and folding those into `partial` would throw away the only thing the
45
- * dot is there to say.
46
- */
47
- export type NodeState = "idle" | "ok" | "partial" | "error" | "blocked" | "skipped";
48
-
49
- /**
50
- * ⚠ THE GRAPH IS THE SERVER'S, not this client's. `engine.graph()` derives it
51
- * from the definition, in the same module that RUNS the steps β€” so the surface
52
- * cannot show a step the engine stopped executing. This file only types it and
53
- * `steps.ts` only numbers it; nothing here decides what the nodes are.
54
- * (It said `canvasLayout.ts` until wave 21 replaced the canvas with numbered
55
- * Steps β€” R9; wave 22 DELETED both canvas files, since the board supersedes the
56
- * rebuild question they were being kept for. Stale prose about a deleted mount
57
- * is a hazard, not a footnote.)
58
- * (Same rule as `cronPresets` and `kinds`, for the same reason.)
59
- */
60
- export interface GraphNode {
61
- id: string;
62
- kind: "trigger" | "source" | "capture" | "branch" | "write";
63
- title: string;
64
- subtitle: string;
65
- detail: string;
66
- col: number;
67
- row: number;
68
- /** Which config panel this node opens. */
69
- panel: string;
70
- enabled: boolean;
71
- /** Non-empty = this node has a REAL switch. Empty = it is always on, by nature. */
72
- toggle: string;
73
- status: NodeState;
74
- }
75
-
76
- export interface GraphEdge {
77
- from: string;
78
- to: string;
79
- label: string;
80
- }
81
-
82
- export interface AutomationGraph {
83
- nodes: GraphNode[];
84
- edges: GraphEdge[];
85
- }
86
-
87
- export interface RunEntry {
88
- ts: string;
89
- ok: boolean;
90
- summary: string;
91
- counts: Record<string, number>;
92
- /** Per-node outcomes, MEASURED as the run walked. Absent on runs stored before W19-C. */
93
- steps?: Record<string, NodeState>;
94
- affected?: string[];
95
- }
96
-
97
- export interface Automation {
98
- id: string;
99
- name: string;
100
- kind: AutomationKind;
101
- config: Record<string, unknown>;
102
- schedule: { cron: string; enabled: boolean; enabledAt?: string };
103
- status: { state: RunState; lastRunAt?: string; lastSummary?: string; step?: string };
104
- runs: RunEntry[];
105
- created?: string;
106
- createdBy?: string;
107
- nextRunAt?: string;
108
- running?: boolean;
109
- graph: AutomationGraph;
110
- /**
111
- * WAVE 22 / C3 β€” WHAT STARTS THIS ONE, as a key from the server's `triggers`
112
- * list. OPTIONAL: until the engine stores a trigger the only two shapes a
113
- * definition can express are `schedule.enabled` true/false, and the picker
114
- * derives those rather than inventing a third answer.
115
- */
116
- trigger?: {
117
- key: string;
118
- ready?: boolean;
119
- needs?: string;
120
- /** ⚠ STORED INERT, NOT REFUSED (A3): the picker writes `{key}` first and the table/field
121
- * after, so an unfinished trigger is a STATE the builder finishes β€” never a snap-back to
122
- * Manual. It cannot fire while incomplete, which is the fail-closed direction. */
123
- configured?: boolean;
124
- paused?: boolean;
125
- enabled?: boolean;
126
- table?: string;
127
- field?: string;
128
- fields?: string[];
129
- viewId?: string;
130
- query?: string;
131
- token?: string;
132
- formToken?: string;
133
- when?: Cond | null;
134
- };
135
- /**
136
- * WAVE 23 / C4 β€” the ACTIONS this automation runs, and how it ends (C5). Defaulted
137
- * server-side to `{actions: [], ending: {mode: "terminal"}}`, so an automation written before
138
- * this wave reads as "no actions, stops at the end" rather than as a missing key.
139
- */
140
- flow?: Flow;
141
- /**
142
- * The review gate's decisions, newest first (<=100). A promotion is a person's
143
- * judgement written into a record, so it says WHO β€” the same reason every count in
144
- * this product drills to its rows.
145
- */
146
- reviews?: ReviewEntry[];
147
- }
148
-
149
- export interface AutomationList {
150
- automations: Automation[];
151
- kinds: { key: AutomationKind; label: string }[];
152
- cronPresets: { cron: string; label: string }[];
153
- /**
154
- * Is `AIOS_BRIGHTDATA_KEY` configured on the server? A BOOLEAN, never the key β€”
155
- * the surface needs to say "the paid rung is not configured" honestly rather
156
- * than offering a tier that will silently refuse.
157
- */
158
- paidReady: boolean;
159
- /**
160
- * THE SOURCE REGISTRY (DEBT D-9's seam). Server-declared, for the reason
161
- * `cronPresets` is: the module that RUNS a source is the only thing entitled
162
- * to say what it can do, and a client copy of "Instagram can discover,
163
- * TikTok cannot" goes stale in silence. `canDiscover: false` is an honest
164
- * statement, not a gap β€” offering the button anyway offers a refusal.
165
- */
166
- sources: SourceStatus[];
167
- /** The discovery vocabulary β€” every name MEASURED-accepted by the vendor. */
168
- discover: DiscoverVocab;
169
- /**
170
- * ⚠ CAN A SCHEDULE ACTUALLY FIRE ON THIS DEPLOYMENT? (R9's honest switch; wave-21 C6
171
- * amendment #1.) OPTIONAL because it is genuinely absent until the server ships it β€” and
172
- * that absence is a THIRD state the card prints out loud ("not reported"), never a silent
173
- * fallback to either answer. An optional field that a UI treats as `false` is how a page
174
- * starts stating a measurement nobody made.
175
- *
176
- * TWO independent paths fire schedules and a single boolean cannot describe them: the
177
- * in-process scheduler (`AIOS_AUTOMATIONS=1`) and an external cron POSTing
178
- * `/automations/tick` with the shared token β€” the AWS EventBridge tick is live
179
- * ([[aws-automation-cron]]), so "the in-process one is off" is not "schedules won't fire".
180
- */
181
- tick?: TickState;
182
- /**
183
- * WAVE 22 / C3 β€” THE TRIGGER VOCABULARY, and it is the server's whole answer to
184
- * "what can start an automation".
185
- *
186
- * β›” NO CLIENT UNION OVER `key`. The contract names six keys today
187
- * (manual, schedule, event_field, record_created, webhook, email) and the
188
- * picker must not carry a copy of that list: a client union means the two lists
189
- * can diverge, and the way they diverge is SILENT β€” the server offers a trigger
190
- * the client has no arm for and simply does not draw it, which is the wave-9
191
- * silent-drop class. The picker maps the array.
192
- *
193
- * OPTIONAL because it is genuinely absent until the engine ships it, and absent
194
- * is a third state: with no list, the trigger face falls back to the schedule
195
- * controls that already exist rather than rendering an empty dropdown.
196
- */
197
- triggers?: TriggerOption[];
198
- /**
199
- * WAVE 23 / C4 β€” the action menu and the builder's ceilings. OPTIONAL for the reason every
200
- * other server vocabulary here is: absent is a third state (a server older than this client),
201
- * and the builder prints what it has rather than inventing a menu.
202
- */
203
- actionsCatalog?: ActionCatalogRow[];
204
- flow?: FlowVocab;
205
- storeAvailable: boolean;
206
- }
207
-
208
- export interface TriggerOption {
209
- key: string;
210
- label: string;
211
- /**
212
- * Can this deployment actually run it? `false` is not a reason to hide the
213
- * option β€” a trigger nobody can pick still ANSWERS the question "can it run
214
- * when an email arrives", which a missing row does not, and which then gets
215
- * asked again (the R9 precedent: the disabled "when a field changes" slot).
216
- */
217
- ready: boolean;
218
- /** What it is waiting for, e.g. `"connect_gmail"`. Rendered as a next step, never as an error. */
219
- needs?: string;
220
- /**
221
- * WAVE 23 / R2 β€” DECLARED BUT NOT BUILT (`button_clicked`, `comment_added`). Distinct from
222
- * `ready:false`, and the difference is what the user can DO about it: a not-ready trigger is
223
- * waiting on a connection THEY can make, a planned one is waiting on us. Both render; only
224
- * the first offers an action. The server refuses a planned key at the door
225
- * (`clean_trigger`), so the faded state is enforced rather than merely displayed.
226
- */
227
- planned?: boolean;
228
- /**
229
- * ⭐ THE CONNECT AFFORDANCE, SERVER-COMPOSED (A3(3), wave 23). This replaced a client table
230
- * that mapped a `needs` token to a provider and hand-built the start URL β€” two facts the
231
- * OAuth registry already owns, kept in a second place that could disagree with it. `null`
232
- * (or absent) means there is no route to offer, which the trigger face states in words
233
- * instead of drawing a button that goes nowhere.
234
- */
235
- connect?: { provider: string; startUrl: string } | null;
236
- /**
237
- * WAVE 24 / C-TYPES β€” THE SERVER'S OWN ONE-LINE DESCRIPTION, rendered under the picker.
238
- *
239
- * β›” A CLIENT PARAPHRASE OF A SERVER VOCABULARY IS FORBIDDEN, which is the whole reason this
240
- * key exists rather than a `TRIGGER_BLURBS` table next to `TriggerMark`. The engine decides
241
- * what a trigger DOES; a second sentence written here would be free to describe a behaviour
242
- * the engine stopped having, and nothing would go red. Same rule as `cronPresets`, one field
243
- * further in. Absent = the picker prints no description, never an invented one.
244
- */
245
- detail?: string;
246
- /**
247
- * WAVE 24 / C-TYPES β€” which SECTION of the picker this trigger sits in ("Standard" |
248
- * "Sources"). Typed `string` and not a union for the reason the header gives about `key`: a
249
- * client union over a server enumeration diverges silently. **Absent = "Standard"** β€” that
250
- * default is stated here so the picker does not have to invent a third bucket for a server
251
- * older than this client.
252
- */
253
- group?: string;
254
- }
255
-
256
- // ── WAVE 23 / contracts C4 + C5: CONDITION TREES, ACTIONS, ENDINGS ───────────────────────────
257
- //
258
- // β›” EVERY VOCABULARY BELOW IS `string`, for the reason C1 and C3 already give: a client union
259
- // over a server enumeration is a list that can go stale, and it goes stale SILENTLY. The engine
260
- // ships `flow.condOps`, `flow.endingModes`, `flow.reviewDeciders` and `actionsCatalog` on
261
- // `GET /automations`; the builder renders whatever rides and never a list of its own.
262
-
263
- /**
264
- * ONE condition, as a TREE (C4). A leaf is wave 22's lane condition unchanged β€” which is why
265
- * nothing migrated: a stored leaf IS a valid tree, and the engine dispatches on shape.
266
- * Depth and breadth are the SERVER's numbers (`flow.maxCondDepth` / `maxCondChildren`), read
267
- * from the payload rather than repeated here.
268
- */
269
- export type Cond =
270
- | { field: string; op: string; value?: string | number }
271
- | { all: Cond[] }
272
- | { any: Cond[] };
273
-
274
- export function isCondGroup(c: Cond | null | undefined): c is { all: Cond[] } | { any: Cond[] } {
275
- return !!c && (Array.isArray((c as { all?: Cond[] }).all)
276
- || Array.isArray((c as { any?: Cond[] }).any));
277
- }
278
-
279
- /** A group's join word and its children, without the caller re-testing both keys every time. */
280
- export function groupParts(c: Cond): { join: "all" | "any"; children: Cond[] } {
281
- const all = (c as { all?: Cond[] }).all;
282
- return Array.isArray(all) ? { join: "all", children: all }
283
- : { join: "any", children: (c as { any: Cond[] }).any || [] };
284
- }
285
-
286
- /**
287
- * One step of a flow (C4). `config` is per-kind and deliberately loose here β€” the engine
288
- * validates it and REFUSES rather than coercing, so a client-side shape would be a second
289
- * validator free to disagree with the one that decides.
290
- */
291
- /**
292
- * ⭐ WAVE 24 / C-FORK (owner ruling R8, item 12a) β€” ONE LEG OF AN IF FORK.
293
- *
294
- * A group action's `config` is `{ branches: Branch[] }`. The LAST branch may carry
295
- * `cond: null` β€” that is the **Otherwise** leg, and there is at most one of them; every other
296
- * branch names a condition. `label` is the branch's LETTER ("A", "B", …), because R8 rules a
297
- * fork occupies ONE step number and its legs are lettered: a branch is an alternative, not a
298
- * later step.
299
- *
300
- * ⚠ THE ENGINE MIGRATES THE OLD SHAPE, it does not refuse it: a stored `{cond, actions}`
301
- * becomes `{branches:[{id:"b1", label:"A", cond, actions}]}` on the next clean. The live
302
- * automations use the old shape, so a refusal here would break them.
303
- */
304
- export interface Branch {
305
- id: string;
306
- label: string;
307
- cond: Cond | null;
308
- actions: Action[];
309
- }
310
-
311
- export interface Action {
312
- id: string;
313
- kind: string;
314
- enabled: boolean;
315
- /**
316
- * Run this action only when the walking record matches. `null` = always.
317
- *
318
- * ⚠ REQUIRED, and that is a MEASURED claim rather than a tidy one: `clean_actions` emits
319
- * `"when"` on every action it returns (`automation_engine.py:3713`), null included, so an
320
- * action on the wire always carries the key. Typing it optional would let a caller build one
321
- * without it and let a reader treat "absent" as a third state the server cannot produce.
322
- */
323
- when: Cond | null;
324
- /** Per-kind. For `kind === "group"` this is `{ branches: Branch[] }` (C-FORK). */
325
- config: Record<string, unknown>;
326
- }
327
-
328
- /** `flow.ending` (C5) β€” what happens to a record that reaches the end. */
329
- export interface FlowEnding {
330
- mode: string;
331
- hours?: number;
332
- }
333
-
334
- export interface Flow {
335
- actions: Action[];
336
- ending: FlowEnding;
337
- }
338
-
339
- /**
340
- * A row of the ACTION MENU (image 7/8's grouped list). `group` is the section heading and
341
- * `ready:false` paints the card faded WITH the server's own reason β€” the owner asked for the
342
- * full menu, and a shorter one would imply the missing actions do not exist. `clean_actions`
343
- * refuses an unready kind, so faded is a wall rather than a styling choice.
344
- */
345
- export interface ActionCatalogRow {
346
- kind: string;
347
- label: string;
348
- group: string;
349
- ready: boolean;
350
- detail: string;
351
- /**
352
- * ⭐ WAVE 24 / C-ACT β€” THE SERVER DECIDES THE MENU'S GROUP ORDER, and the client sorts by
353
- * this number and **never by a literal list of group names**. A hard-coded
354
- * `["Web action", "Database", …]` in the client is a second copy of the catalog's own
355
- * structure: the day the server adds or renames a group, the client either drops it off the
356
- * end or drops it entirely, silently. Absent sorts last β€” a server older than this client
357
- * still renders every group it sends.
358
- */
359
- groupOrder?: number;
360
- }
361
-
362
- /** The builder's own ceilings, server-declared so the client never hard-codes the same numbers. */
363
- export interface FlowVocab {
364
- condOps: string[];
365
- nullaryCondOps: string[];
366
- maxCondDepth: number;
367
- maxCondChildren: number;
368
- maxGroupDepth: number;
369
- maxActions: number;
370
- endingModes: string[];
371
- maxResetHours: number;
372
- reviewDeciders: string[];
373
- /**
374
- * ⚠ PER-DEPLOYMENT, AND HONEST RATHER THAN DECORATIVE. With no LLM key configured the engine
375
- * holds every card for a human β€” so an enabled-looking "decided by AI" control would promise
376
- * a decision nothing will make. False renders it as not-configured (C6's fail-closed path,
377
- * made visible).
378
- */
379
- aiReady: boolean;
380
- }
381
-
382
- export interface OAuthConnection {
383
- connected: boolean;
384
- email?: string;
385
- }
386
-
387
- /**
388
- * C5's per-user connector state, keyed by PROVIDER (`google` today).
389
- *
390
- * A record and not an interface with a `google` field, for C3's reason one level
391
- * down: the provider list is the server's β€” R12 says Google first and the rest
392
- * "one by one, next waves" β€” and a client shape that names one provider has to
393
- * be edited to see the second. This one does not.
394
- */
395
- export type OAuthStatus = Record<string, OAuthConnection | undefined>;
396
-
397
- /*
398
- * β›” `CONNECT_PROVIDERS` / `oauthProviderFor` / `oauthStartUrlFor` ARE GONE (D-43, wave 23).
399
- *
400
- * They were a client table mapping a server `needs` token ("connect_gmail") to a provider
401
- * ("google") and composing `/oauth/google/start` by hand β€” a second copy of the OAuth
402
- * registry, booked as debt on the day it shipped with the resolution written into it: "this
403
- * table disappears the day a `TriggerOption` carries its own provider or start URL." It does
404
- * now (`TriggerOption.connect`, composed by `routes_automation._triggers_vocab`), so the copy
405
- * is deleted rather than left to drift the first time a second provider lands.
406
- *
407
- * The FAIL-QUIET-BUT-VISIBLE behaviour it was built for is unchanged and now belongs to the
408
- * server: no `connect` means no button, and the not-configured state is still said in words.
409
- */
410
-
411
- export interface TickState {
412
- enabled: boolean;
413
- /** Which path. `external` means the door is OPEN, never that the caller is alive. */
414
- source?: "in-process" | "external" | "";
415
- }
416
-
417
- export interface SourceStatus {
418
- key: string;
419
- label: string;
420
- vendor: string;
421
- ready: boolean;
422
- canDiscover: boolean;
423
- }
424
-
425
- export interface DiscoverVocab {
426
- fields: string[];
427
- /**
428
- * The subset seen carrying VALUES on real corpus rows. The others are
429
- * filterable and were null on every row measured β€” and a filter on an
430
- * unpopulated field returns nothing while looking exactly like "no such
431
- * influencers exist".
432
- */
433
- lead: string[];
434
- operators: string[];
435
- nullaryOperators: string[];
436
- maxRecords: number;
437
- table: string;
438
- /**
439
- * WAVE 22 / C4 β€” per-field facts, one entry per name in `fields`.
440
- *
441
- * ⚠ OPTIONAL ON PURPOSE, and it must never be read as "everything is
442
- * unpopulated". It is genuinely absent until the engine ships it, and absent
443
- * is a THIRD state: the toggle list falls back to `lead` (which says the same
444
- * thing about the three fields it names and nothing at all about the other
445
- * eighteen) and prints no claim about the rest. The `tick` field on
446
- * `AutomationList` is the precedent and the reason β€” an optional field a UI
447
- * defaults to `false` is how a surface starts stating a measurement nobody
448
- * made.
449
- */
450
- filterMeta?: DiscoverFieldMeta[];
451
- /** WAVE 22 / C4 β€” the too-big guard's PARAMETERS. The DECISION stays server-side; see below. */
452
- guard?: DiscoverGuard;
453
- }
454
-
455
- export interface DiscoverFieldMeta {
456
- name: string;
457
- /** Seen carrying values on real corpus rows. */
458
- populated: boolean;
459
- /** A condition on this field actually cuts the corpus down. */
460
- narrowing: boolean;
461
- /**
462
- * The comparison a NEW condition on this field starts with β€” SERVER-OWNED, and optional only
463
- * because an older server does not send it.
464
- *
465
- * β›” Do not replace an absent one with a client default. That is the whole defect this field
466
- * exists to fix: the client used to pick `is_not_null` for every field, which the server's
467
- * narrowing guard refuses on every field, so a filter stayed unsaveable no matter what the
468
- * user toggled on.
469
- */
470
- defaultOperator?: string;
471
- }
472
-
473
- /**
474
- * β›” PARAMETERS, NOT A RULE THE CLIENT RE-IMPLEMENTS (C4).
475
- *
476
- * The server refuses a filter with no narrowing predicate, and it refuses it at
477
- * create, at patch AND at run β€” with a sentence naming why. This client renders
478
- * those numbers as *facts about the fields* (which ones narrow, which have
479
- * values) and renders the REFUSAL VERBATIM when it comes back. It does not
480
- * predict the refusal, because a second copy of the rule is a copy that can
481
- * disagree: a client that blocks Save on its own arithmetic can block a filter
482
- * the server would have accepted, and the user cannot tell which of the two is
483
- * wrong. Same reason `cronPresets` are not a client constant.
484
- */
485
- export interface DiscoverGuard {
486
- minNarrowing: number;
487
- maxRecords: number;
488
- }
489
-
490
- /**
491
- * ONE condition of a corpus search. Mirrors the server's `clean_predicates`
492
- * shape exactly β€” `{name, operator}` plus a `value` for every operator that is
493
- * not nullary.
494
- */
495
- export interface Predicate {
496
- name: string;
497
- operator: string;
498
- value?: string | number;
499
- }
500
-
501
- /**
502
- * ⚠ AN ESTIMATE, AND IT CARRIES ITS OWN CAVEAT (`basis: "SPEC"`). Bright Data
503
- * never quotes a price before a run, and this account's token cannot read a
504
- * balance β€” so no surface may present this as a billed figure.
505
- */
506
- export interface DiscoverEstimate {
507
- records: number;
508
- usd: number;
509
- unitUsd: number;
510
- basis: string;
511
- note: string;
512
- }
513
-
514
- export interface UserTable {
515
- key: string;
516
- label: string;
517
- source: string;
518
- rowCount: number;
519
- /**
520
- * `automation` is the machine-owner TAG (W23/R9's grey columns) β€” the id of the automation
521
- * that owns the column, or `null`. Narrowed from `unknown` in wave 24 against the route that
522
- * composes it: `routes_automation.py:291` sends `f.get("automation") or None`, so `string`
523
- * and `null` are the only two values that ride.
524
- */
525
- fields: { key: string; label: string; type: string; automation?: string | null }[];
526
- /**
527
- * The table's saved views β€” what `enters_view` names (C3). ABSENT until the server sends it,
528
- * and absent is a third state, not an empty list: the trigger's view control says the list was
529
- * not offered rather than rendering an empty picker that looks like "this table has no views".
530
- * (Asked of session A in the wave mailbox; the control reads this key the day it rides.)
531
- */
532
- views?: { id: string; label: string }[];
533
- }
534
-
535
- export interface SourcePreview {
536
- ok: boolean;
537
- status: number;
538
- url: string;
539
- title?: string;
540
- note?: string;
541
- columns: string[];
542
- sample: Record<string, string>[];
543
- rowCount: number;
544
- tableCount?: number;
545
- }
546
-
547
- export interface RunRows {
548
- table: string;
549
- label: string;
550
- fields: { key: string; label: string }[];
551
- rows: Record<string, string>[];
552
- truncated: boolean;
553
- }
554
-
555
- // ── WAVE 22 / contract C1: THE BOARD ──────────────────────────────────────────
556
- //
557
- // R1's model, stated once: an automation IS a kanban board. The columns are the
558
- // flow's stages, the CARDS ARE RECORDS of the target database, and a record's
559
- // position is stored in a single-select stage field on that database β€” so the
560
- // same field also drives a plain Kanban view, and the board is not a second,
561
- // private idea of where a record is.
562
- //
563
- // ⚠ EVERY VOCABULARY BELOW IS `string`, DELIBERATELY. `kind` is
564
- // trigger|action|review|branch today and `posture` is auto|strict, and both are
565
- // typed loose for the reason contract C3 gives about trigger keys: a client
566
- // union over a server enumeration is a list that can go stale, and the failure
567
- // mode is SILENT β€” a `switch` with no arm for a new value renders nothing at all
568
- // and the surface simply stops showing a stage the engine is running (the wave-9
569
- // silent-drop class). Rendering falls back to a neutral face for anything
570
- // unrecognised, which is visible.
571
-
572
- export interface BoardStage {
573
- /** For a stage backed by an engine node this IS that node's id (C1 amendment 1). */
574
- id: string;
575
- label: string;
576
- /** `trigger` | `action` | `review` | `branch` β€” see the note above on why it is not a union. */
577
- kind: string;
578
- col: number;
579
- row: number;
580
- enabled: boolean;
581
- /** Non-empty = this stage has a REAL switch. Empty = it is always on, by nature. */
582
- toggle: string;
583
- /** The `NodeState` words. Painted by class, never matched exhaustively. */
584
- status: string;
585
- detail: string;
586
- /**
587
- * R7's approval-posture vocabulary, adopted from QM: `strict` = the stage holds
588
- * for a human, `auto` = the engine advances the record itself.
589
- */
590
- posture: string;
591
- /**
592
- * ⭐ THE JOIN KEY FOR THE CONFIG PANEL (C1 amendment 1, 2026-08-05). A stage
593
- * backed by an engine node carries that node's `panel` verbatim; review stages
594
- * carry `"review"`. The amendment is explicit that B joins on THIS and never on
595
- * a guessed id equality β€” a panel picked by a key that only usually matches is
596
- * a surface that shows the wrong settings while looking completely correct.
597
- */
598
- panel: string;
599
- /**
600
- * ⭐ MAY THIS STAGE HOLD CARDS? (A's CP1, additive to C1 β€” 2026-08-05.) A discovery
601
- * flow's `find`/`collect`/`write` are things the automation DOES, not places a record
602
- * sits, and drawing them as lanes would put three permanently empty columns between
603
- * the trigger and the first real one. They render as the process strip instead.
604
- *
605
- * ⚠ OPTIONAL, AND ABSENT MEANS LANE. A server that ships C1's contract text and not
606
- * this field describes every stage as a place β€” which is what the earlier board did β€”
607
- * so `undefined` keeps that behaviour and only an explicit `false` moves a stage into
608
- * the strip. Defaulting an absent field to `false` would empty the board against a
609
- * server that never said anything of the kind.
610
- */
611
- record?: boolean;
612
- /**
613
- * May a card be PLACED here β€” i.e. is this stage's label a choice of the stage field?
614
- * `record && !assignable` is a DERIVED bucket: cards appear from what is true about the
615
- * row, and nothing may stamp one into it. Such a lane takes no drop.
616
- */
617
- assignable?: boolean;
618
- }
619
-
620
- export interface BoardRoute {
621
- from: string;
622
- to: string;
623
- /** Server-composed. Falls back to the condition's own words when empty. */
624
- label: string;
625
- /** `null` = an unconditional next, which needs no label at all (R5). */
626
- condition: { field: string; op: string; value?: string | number } | null;
627
- }
628
-
629
- export interface BoardCard {
630
- rowId: string;
631
- stageId: string;
632
- /**
633
- * ⚠ SERVER-COMPOSED STRINGS (C1 amendment 3). The board does NO client-side
634
- * field formatting β€” it has no field contract for the target database and
635
- * inventing one would mean a second formatter disagreeing with the grid's.
636
- */
637
- title: string;
638
- sub: string;
639
- movedAt: string;
640
- /** The SERVER's answer to "may this move", not a permission the client derives. */
641
- canAdvance: boolean;
642
- next: string[];
643
- /**
644
- * WAVE 23 / C5 β€” how many times this record has been round the flow. The count lives in the
645
- * machine cell `stage_<autoId>_cycles` and the engine increments it on every reset.
646
- *
647
- * ⚠ NOT ON THE CARD WIRE YET (asked of session A in the wave mailbox). Absent means "not
648
- * reported", NOT "once": the badge only draws from 2 upwards, so a missing key renders
649
- * nothing at all rather than a claim that every record is on its first pass β€” which is
650
- * exactly the measurement nobody made. It lights up the day the key rides.
651
- */
652
- cycles?: number;
653
- }
654
-
655
- export interface Board {
656
- stages: BoardStage[];
657
- routes: BoardRoute[];
658
- cards: BoardCard[];
659
- /** `null` = no stage field bound yet. An empty board is a STATE, not an error (C1 amendment 2). */
660
- stageField: { table: string; key: string } | null;
661
- /**
662
- * The TRUE per-stage totals. `cards` may be capped by the server, so a lane
663
- * whose count exceeds its cards discloses the difference rather than showing a
664
- * short list as if it were the whole one ([[no-unverifiable-aggregates]]).
665
- */
666
- counts: Record<string, number>;
667
- /**
668
- * Stages whose `cards` were capped on the wire (200/stage). `counts` always carries the
669
- * TRUE total, so the lane can state the difference rather than showing a short list as
670
- * if it were the whole one ([[no-unverifiable-aggregates]]).
671
- */
672
- truncated?: string[];
673
- }
674
-
675
- /**
676
- * One decision at a review gate β€” R7's approval posture, audited (A2(5)).
677
- *
678
- * ⭐ WAVE 23 / C6 (R4/R14): a decision may now be made by a MODEL, and the audit says so. One
679
- * log, not two β€” a reader asking "who decided this" gets one answer whether it was a person or
680
- * a provider, which is the only version that can be trusted at all.
681
- */
682
- export interface ReviewEntry {
683
- ts: string;
684
- user: string;
685
- rowId: string;
686
- from: string;
687
- to: string;
688
- /** `"user"` | `"ai"`. Absent on entries written before this wave β€” render as a person. */
689
- by?: string;
690
- /** The one-line reason. On an AI decision it is the model's own; never invented here. */
691
- note?: string;
692
- /** Which model decided. Present only on AI entries, and shown so the reason has provenance. */
693
- model?: string;
694
- }
695
-
696
- export class AutomationError extends Error {
697
- status: number;
698
-
699
- constructor(message: string, status: number) {
700
- super(message);
701
- this.name = "AutomationError";
702
- this.status = status;
703
- }
704
- }
705
-
706
- async function result<T>(response: Response): Promise<T> {
707
- let body: unknown = null;
708
- try {
709
- body = await response.json();
710
- } catch {
711
- // The status is still an honest answer; the message below says so.
712
- }
713
- if (response.status === 401) signal(UNAUTHORIZED_EVENT);
714
- if (!response.ok) {
715
- const shaped = body as { error?: { message?: string } } | null;
716
- throw new AutomationError(
717
- shaped?.error?.message || `The server answered ${response.status}.`,
718
- response.status
719
- );
720
- }
721
- return body as T;
722
- }
723
-
724
- function send<T>(path: string, init?: RequestInit): Promise<T> {
725
- return fetch(`${API_V1}${path}`, {
726
- credentials: CREDENTIALS,
727
- headers: init?.body ? { "Content-Type": "application/json" } : undefined,
728
- ...init,
729
- }).then((r) => result<T>(r));
730
- }
731
-
732
- export function listAutomations(abort?: AbortSignal): Promise<AutomationList> {
733
- return send<AutomationList>("/automations", { signal: abort });
734
- }
735
-
736
- export function listTables(abort?: AbortSignal): Promise<{ tables: UserTable[] }> {
737
- return send<{ tables: UserTable[] }>("/automations/tables", { signal: abort });
738
- }
739
-
740
- export function createAutomation(body: unknown): Promise<{ automation: Automation }> {
741
- return send("/automations", { method: "POST", body: JSON.stringify(body) });
742
- }
743
-
744
- export function patchAutomation(
745
- id: string,
746
- body: unknown
747
- ): Promise<{ automation: Automation }> {
748
- return send(`/automations/${encodeURIComponent(id)}`, {
749
- method: "PATCH",
750
- body: JSON.stringify(body),
751
- });
752
- }
753
-
754
- export function deleteAutomation(id: string): Promise<{ deleted: string }> {
755
- return send(`/automations/${encodeURIComponent(id)}`, { method: "DELETE" });
756
- }
757
-
758
- export function runAutomation(id: string): Promise<{ started: string }> {
759
- return send(`/automations/${encodeURIComponent(id)}/run`, { method: "POST" });
760
- }
761
-
762
- /**
763
- * Flip one step's switch.
764
- *
765
- * The client says WHICH NODE was clicked and nothing else β€” the server owns what
766
- * each switch means (`engine.NODE_TOGGLES`). A client that knew "the Bright Data
767
- * node writes config.tier" would be a second copy of that knowledge, free to
768
- * drift from the engine that reads it β€” and it would have had to be rewritten
769
- * when the vendor changed. It did not.
770
- */
771
- export function toggleNode(
772
- id: string,
773
- nodeId: string
774
- ): Promise<{ automation: Automation }> {
775
- return send(
776
- `/automations/${encodeURIComponent(id)}/nodes/${encodeURIComponent(nodeId)}/toggle`,
777
- { method: "POST" }
778
- );
779
- }
780
-
781
- export function getAutomation(id: string): Promise<{ automation: Automation }> {
782
- return send(`/automations/${encodeURIComponent(id)}`);
783
- }
784
-
785
- export function runRows(id: string): Promise<RunRows> {
786
- return send(`/automations/${encodeURIComponent(id)}/rows`);
787
- }
788
-
789
- /**
790
- * The board for one automation (C1). Answers 200 for every existing automation β€”
791
- * an automation with no bound stage field comes back with its stages and
792
- * `stageField: null, cards: []`, which the board prints as a state rather than
793
- * an error (C1 amendment 2).
794
- */
795
- export function getBoard(id: string, abort?: AbortSignal): Promise<{ board: Board }> {
796
- return send(`/automations/${encodeURIComponent(id)}/board`, { signal: abort });
797
- }
798
-
799
- /**
800
- * Move ONE record along the flow, and answer the fresh board.
801
- *
802
- * β›” THE SERVER DECIDES LEGALITY, NOT THIS FILE (C1). A review-stage card
803
- * advances only to a member of its own `next`; every other move is admin-only.
804
- * The client sends the drop it was given and renders the refusal verbatim β€” a
805
- * client that pre-judged the move would be a second copy of a permission rule,
806
- * and when the two copies disagree the user is left with a control that does
807
- * nothing for a reason nobody can read.
808
- */
809
- export function moveCard(
810
- id: string,
811
- rowId: string,
812
- to: string
813
- ): Promise<{ board: Board }> {
814
- return send(
815
- `/automations/${encodeURIComponent(id)}/cards/${encodeURIComponent(rowId)}/move`,
816
- { method: "POST", body: JSON.stringify({ to }) }
817
- );
818
- }
819
-
820
- /** Is a connector connected for THIS user? (C5 β€” per-user keychain slots, R7's seam.) */
821
- export function oauthStatus(abort?: AbortSignal): Promise<OAuthStatus> {
822
- return send("/oauth/status", { signal: abort });
823
- }
824
-
825
- /** What would a search of this size cost? Asked BEFORE the run, never after. */
826
- export function discoverEstimate(recordsLimit: number): Promise<DiscoverEstimate> {
827
- return send("/automations/discover/estimate", {
828
- method: "POST",
829
- body: JSON.stringify({ recordsLimit }),
830
- });
831
- }
832
-
833
- export function previewSource(
834
- url: string,
835
- extract: string,
836
- tableIndex: number
837
- ): Promise<SourcePreview> {
838
- return send("/automations/preview", {
839
- method: "POST",
840
- body: JSON.stringify({ url, extract, tableIndex }),
841
- });
842
- }
843
-
844
- /**
845
- * A source column name β†’ a storable field key. Mirrors the server's own
846
- * normalisation (`clean_config`) so the key the UI shows is the key that gets
847
- * stored β€” a preview that promised `gics_sector` and a store that wrote
848
- * `gics__sector` would look like data loss.
849
- */
850
- export function fieldKeyFor(column: string): string {
851
- return (column || "")
852
- .toLowerCase()
853
- .replace(/[^a-z0-9_]+/g, "_")
854
- .replace(/^_+|_+$/g, "")
855
- .slice(0, 60);
856
- }
857
-
858
- /** The state word a status dot / chip paints from. */
859
- export function stateOf(a: Automation): RunState {
860
- return a.running ? "running" : (a.status?.state as RunState) || "idle";
861
- }
862
-
863
- /**
864
- * ⭐ WAVE 24 / C-TYPES + C-PERF (item 6) β€” WHAT THIS RUN IS DOING RIGHT NOW, or `""`.
865
- *
866
- * This is the honest half of "Run once now looks stuck": the engine has been publishing a live
867
- * step text the whole time and **nothing has ever rendered it**, so a 120-second Bright Data
868
- * wait and a hung thread look identical from the outside. They are not the same thing, and the
869
- * server already knows which one it is.
870
- *
871
- * β›” WHY A FUNCTION AND NOT A FIELD β€” C-TYPES AMENDMENT A2 (2026-08-06, session D).
872
- * The contract block writes `liveStep?: string` on `interface Automation`. Measured against the
873
- * route that composes the payload: `_wire()` (`routes_automation.py:52-81`) emits `status` with
874
- * `step` inside it (`:50-51`) and emits **no top-level `liveStep` at all**. Declaring the field
875
- * would put a key on the `Automation` interface that no server sends β€” so `automation.liveStep`
876
- * would compile, type-check, and be `undefined` forever. That is this codebase's own
877
- * silent-drop class pointing the other way: the whole file is built on "absent must stay
878
- * absent", and inventing a present-looking field is the same defect with the sign flipped.
879
- * `step` is ALREADY typed on `status` (see `Automation.status`), so nothing is lost β€” this
880
- * function is the greppable name the contract wanted, reading the key that actually rides.
881
- * The W24-W1 hand-off is unaffected: it is a PROP called `liveStep`, and this is what fills it.
882
- */
883
- export function liveStepOf(a: Automation): string {
884
- return stateOf(a) === "running" ? String(a.status?.step || "") : "";
885
- }
886
-
887
- /**
888
- * A run's counts as ordered label/value pairs. The ORDER is the sentence the
889
- * numbers make β€” new, updated, unchanged, then the ones that need explaining β€”
890
- * and `orphans` is spelled out rather than abbreviated because a bare number
891
- * next to the word "orphans" is the one count a user must not have to guess at.
892
- */
893
- export const COUNT_LABELS: [string, string][] = [
894
- ["inserted", "New"],
895
- ["updated", "Updated"],
896
- ["unchanged", "Unchanged"],
897
- ["orphans", "No longer on the page (kept)"],
898
- ["duplicates", "Duplicate keys"],
899
- ["skipped", "Skipped (no key)"],
900
- // ⚠ ITS OWN CHIP, next to `skipped` but never merged with it. "Skipped" is a
901
- // property of the data and usually benign; "not written β€” the database is
902
- // full" is a property of the system and never is. One chip for both is how a
903
- // time series stops growing without anybody being told.
904
- ["capped", "Not written β€” the database is full"],
905
- ["source_rows", "Rows read"],
906
- ["profiles", "Profiles"],
907
- ["ok", "Read in full"],
908
- // ⚠ ADDED after reading the first live screenshot. The engine counts `partial` separately
909
- // (profile read, media not anonymously readable) but this table did not, so a run whose
910
- // summary said "1/1 profiles read" showed a chip row reading "0 Read" β€” the chips
911
- // contradicting the sentence directly above them. A count the summary names must have a chip.
912
- ["partial", "Profile only"],
913
- ["blocked", "Blocked"],
914
- ["error", "Errors"],
915
- ["paid", "Exact via Bright Data"],
916
- ["posts", "Posts"],
917
- ["new_posts", "New posts"],
918
- // The engagement series only grows while the per-post rung is on, so its
919
- // count is its own chip β€” "12 posts" and "0 engagement snapshots" together
920
- // are the honest picture of a profile-only run.
921
- ["metrics", "Engagement snapshots"],
922
- // Discovery.
923
- ["asked", "Asked for"],
924
- ["found", "Profiles found"],
925
- ["new", "New to us"],
926
- ["seen_again", "Seen before"],
927
- ["dropped", "Returned but unusable (no handle)"],
928
- // ⚠ Its own chip for the same reason `capped` has one: a database that could
929
- // not be CREATED is a system fact, and the run that hit it wrote nothing.
930
- ["missing_tables", "Databases that could not be created"],
931
- ];
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
+ /**
20
+ * ⭐ WAVE 24 / R6 β€” `plain` IS A REAL KIND, and it is the default for every new automation.
21
+ * No machine graph nodes: the flow's ACTIONS are the whole automation. It exists because
22
+ * `clean_definition` refuses a definition with no kind, so "an automation that is just a
23
+ * trigger and some steps" needed a name at the door rather than a special case behind it.
24
+ * `scrape_db` and `field_instagram` survive on the two automations that already use them and
25
+ * no new one can be created (R6); `discover_instagram` is now reached by PICKING the
26
+ * `ig_profile_match` trigger rather than by a wizard.
27
+ */
28
+ export type AutomationKind =
29
+ | "scrape_db"
30
+ | "field_instagram"
31
+ | "discover_instagram"
32
+ | "plain";
33
+ export type RunState = "idle" | "running" | "ok" | "error" | "partial";
34
+ /**
35
+ * ⚠ `hiker` is NOT in this union any more (wave 20, D-21) β€” the vendor moved.
36
+ * Stored configs still SAY `hiker` and the server maps them forward
37
+ * (`TIER_ALIASES`), so nothing in this client should ever write that word.
38
+ */
39
+ export type CaptureTier = "anonymous" | "brightdata";
40
+
41
+ /**
42
+ * A node's dot. Deliberately WIDER than `RunState` β€” a single step can be
43
+ * `blocked` (a rung refused) or `skipped` (a switch is off) in ways a whole run
44
+ * cannot, and folding those into `partial` would throw away the only thing the
45
+ * dot is there to say.
46
+ */
47
+ export type NodeState = "idle" | "ok" | "partial" | "error" | "blocked" | "skipped";
48
+
49
+ /**
50
+ * ⚠ THE GRAPH IS THE SERVER'S, not this client's. `engine.graph()` derives it
51
+ * from the definition, in the same module that RUNS the steps β€” so the surface
52
+ * cannot show a step the engine stopped executing. This file only types it and
53
+ * `steps.ts` only numbers it; nothing here decides what the nodes are.
54
+ * (It said `canvasLayout.ts` until wave 21 replaced the canvas with numbered
55
+ * Steps β€” R9; wave 22 DELETED both canvas files, since the board supersedes the
56
+ * rebuild question they were being kept for. Stale prose about a deleted mount
57
+ * is a hazard, not a footnote.)
58
+ * (Same rule as `cronPresets` and `kinds`, for the same reason.)
59
+ */
60
+ export interface GraphNode {
61
+ id: string;
62
+ kind: "trigger" | "source" | "capture" | "branch" | "write";
63
+ title: string;
64
+ subtitle: string;
65
+ detail: string;
66
+ col: number;
67
+ row: number;
68
+ /** Which config panel this node opens. */
69
+ panel: string;
70
+ enabled: boolean;
71
+ /** Non-empty = this node has a REAL switch. Empty = it is always on, by nature. */
72
+ toggle: string;
73
+ status: NodeState;
74
+ }
75
+
76
+ export interface GraphEdge {
77
+ from: string;
78
+ to: string;
79
+ label: string;
80
+ }
81
+
82
+ export interface AutomationGraph {
83
+ nodes: GraphNode[];
84
+ edges: GraphEdge[];
85
+ }
86
+
87
+ export interface RunEntry {
88
+ ts: string;
89
+ ok: boolean;
90
+ summary: string;
91
+ counts: Record<string, number>;
92
+ /** Per-node outcomes, MEASURED as the run walked. Absent on runs stored before W19-C. */
93
+ steps?: Record<string, NodeState>;
94
+ affected?: string[];
95
+ }
96
+
97
+ export interface Automation {
98
+ id: string;
99
+ name: string;
100
+ kind: AutomationKind;
101
+ config: Record<string, unknown>;
102
+ schedule: { cron: string; enabled: boolean; enabledAt?: string };
103
+ status: { state: RunState; lastRunAt?: string; lastSummary?: string; step?: string };
104
+ runs: RunEntry[];
105
+ created?: string;
106
+ createdBy?: string;
107
+ nextRunAt?: string;
108
+ running?: boolean;
109
+ graph: AutomationGraph;
110
+ /**
111
+ * WAVE 22 / C3 β€” WHAT STARTS THIS ONE, as a key from the server's `triggers`
112
+ * list. OPTIONAL: until the engine stores a trigger the only two shapes a
113
+ * definition can express are `schedule.enabled` true/false, and the picker
114
+ * derives those rather than inventing a third answer.
115
+ */
116
+ trigger?: {
117
+ key: string;
118
+ ready?: boolean;
119
+ needs?: string;
120
+ /** ⚠ STORED INERT, NOT REFUSED (A3): the picker writes `{key}` first and the table/field
121
+ * after, so an unfinished trigger is a STATE the builder finishes β€” never a snap-back to
122
+ * Manual. It cannot fire while incomplete, which is the fail-closed direction. */
123
+ configured?: boolean;
124
+ paused?: boolean;
125
+ enabled?: boolean;
126
+ table?: string;
127
+ field?: string;
128
+ fields?: string[];
129
+ viewId?: string;
130
+ query?: string;
131
+ token?: string;
132
+ formToken?: string;
133
+ when?: Cond | null;
134
+ };
135
+ /**
136
+ * WAVE 23 / C4 β€” the ACTIONS this automation runs, and how it ends (C5). Defaulted
137
+ * server-side to `{actions: [], ending: {mode: "terminal"}}`, so an automation written before
138
+ * this wave reads as "no actions, stops at the end" rather than as a missing key.
139
+ */
140
+ flow?: Flow;
141
+ /**
142
+ * The review gate's decisions, newest first (<=100). A promotion is a person's
143
+ * judgement written into a record, so it says WHO β€” the same reason every count in
144
+ * this product drills to its rows.
145
+ */
146
+ reviews?: ReviewEntry[];
147
+ }
148
+
149
+ export interface AutomationList {
150
+ automations: Automation[];
151
+ kinds: { key: AutomationKind; label: string }[];
152
+ cronPresets: { cron: string; label: string }[];
153
+ /**
154
+ * Is `AIOS_BRIGHTDATA_KEY` configured on the server? A BOOLEAN, never the key β€”
155
+ * the surface needs to say "the paid rung is not configured" honestly rather
156
+ * than offering a tier that will silently refuse.
157
+ */
158
+ paidReady: boolean;
159
+ /**
160
+ * THE SOURCE REGISTRY (DEBT D-9's seam). Server-declared, for the reason
161
+ * `cronPresets` is: the module that RUNS a source is the only thing entitled
162
+ * to say what it can do, and a client copy of "Instagram can discover,
163
+ * TikTok cannot" goes stale in silence. `canDiscover: false` is an honest
164
+ * statement, not a gap β€” offering the button anyway offers a refusal.
165
+ */
166
+ sources: SourceStatus[];
167
+ /** The discovery vocabulary β€” every name MEASURED-accepted by the vendor. */
168
+ discover: DiscoverVocab;
169
+ /**
170
+ * ⚠ CAN A SCHEDULE ACTUALLY FIRE ON THIS DEPLOYMENT? (R9's honest switch; wave-21 C6
171
+ * amendment #1.) OPTIONAL because it is genuinely absent until the server ships it β€” and
172
+ * that absence is a THIRD state the card prints out loud ("not reported"), never a silent
173
+ * fallback to either answer. An optional field that a UI treats as `false` is how a page
174
+ * starts stating a measurement nobody made.
175
+ *
176
+ * TWO independent paths fire schedules and a single boolean cannot describe them: the
177
+ * in-process scheduler (`AIOS_AUTOMATIONS=1`) and an external cron POSTing
178
+ * `/automations/tick` with the shared token β€” the AWS EventBridge tick is live
179
+ * ([[aws-automation-cron]]), so "the in-process one is off" is not "schedules won't fire".
180
+ */
181
+ tick?: TickState;
182
+ /**
183
+ * WAVE 22 / C3 β€” THE TRIGGER VOCABULARY, and it is the server's whole answer to
184
+ * "what can start an automation".
185
+ *
186
+ * β›” NO CLIENT UNION OVER `key`. The contract names six keys today
187
+ * (manual, schedule, event_field, record_created, webhook, email) and the
188
+ * picker must not carry a copy of that list: a client union means the two lists
189
+ * can diverge, and the way they diverge is SILENT β€” the server offers a trigger
190
+ * the client has no arm for and simply does not draw it, which is the wave-9
191
+ * silent-drop class. The picker maps the array.
192
+ *
193
+ * OPTIONAL because it is genuinely absent until the engine ships it, and absent
194
+ * is a third state: with no list, the trigger face falls back to the schedule
195
+ * controls that already exist rather than rendering an empty dropdown.
196
+ */
197
+ triggers?: TriggerOption[];
198
+ /**
199
+ * WAVE 23 / C4 β€” the action menu and the builder's ceilings. OPTIONAL for the reason every
200
+ * other server vocabulary here is: absent is a third state (a server older than this client),
201
+ * and the builder prints what it has rather than inventing a menu.
202
+ */
203
+ actionsCatalog?: ActionCatalogRow[];
204
+ flow?: FlowVocab;
205
+ storeAvailable: boolean;
206
+ }
207
+
208
+ export interface TriggerOption {
209
+ key: string;
210
+ label: string;
211
+ /**
212
+ * Can this deployment actually run it? `false` is not a reason to hide the
213
+ * option β€” a trigger nobody can pick still ANSWERS the question "can it run
214
+ * when an email arrives", which a missing row does not, and which then gets
215
+ * asked again (the R9 precedent: the disabled "when a field changes" slot).
216
+ */
217
+ ready: boolean;
218
+ /** What it is waiting for, e.g. `"connect_gmail"`. Rendered as a next step, never as an error. */
219
+ needs?: string;
220
+ /**
221
+ * WAVE 23 / R2 β€” DECLARED BUT NOT BUILT (`button_clicked`, `comment_added`). Distinct from
222
+ * `ready:false`, and the difference is what the user can DO about it: a not-ready trigger is
223
+ * waiting on a connection THEY can make, a planned one is waiting on us. Both render; only
224
+ * the first offers an action. The server refuses a planned key at the door
225
+ * (`clean_trigger`), so the faded state is enforced rather than merely displayed.
226
+ */
227
+ planned?: boolean;
228
+ /**
229
+ * ⭐ THE CONNECT AFFORDANCE, SERVER-COMPOSED (A3(3), wave 23). This replaced a client table
230
+ * that mapped a `needs` token to a provider and hand-built the start URL β€” two facts the
231
+ * OAuth registry already owns, kept in a second place that could disagree with it. `null`
232
+ * (or absent) means there is no route to offer, which the trigger face states in words
233
+ * instead of drawing a button that goes nowhere.
234
+ */
235
+ connect?: { provider: string; startUrl: string } | null;
236
+ /**
237
+ * WAVE 24 / C-TYPES β€” THE SERVER'S OWN ONE-LINE DESCRIPTION, rendered under the picker.
238
+ *
239
+ * β›” A CLIENT PARAPHRASE OF A SERVER VOCABULARY IS FORBIDDEN, which is the whole reason this
240
+ * key exists rather than a `TRIGGER_BLURBS` table next to `TriggerMark`. The engine decides
241
+ * what a trigger DOES; a second sentence written here would be free to describe a behaviour
242
+ * the engine stopped having, and nothing would go red. Same rule as `cronPresets`, one field
243
+ * further in. Absent = the picker prints no description, never an invented one.
244
+ */
245
+ detail?: string;
246
+ /**
247
+ * WAVE 24 / C-TYPES β€” which SECTION of the picker this trigger sits in ("Standard" |
248
+ * "Sources"). Typed `string` and not a union for the reason the header gives about `key`: a
249
+ * client union over a server enumeration diverges silently. **Absent = "Standard"** β€” that
250
+ * default is stated here so the picker does not have to invent a third bucket for a server
251
+ * older than this client.
252
+ */
253
+ group?: string;
254
+ }
255
+
256
+ // ── WAVE 23 / contracts C4 + C5: CONDITION TREES, ACTIONS, ENDINGS ───────────────────────────
257
+ //
258
+ // β›” EVERY VOCABULARY BELOW IS `string`, for the reason C1 and C3 already give: a client union
259
+ // over a server enumeration is a list that can go stale, and it goes stale SILENTLY. The engine
260
+ // ships `flow.condOps`, `flow.endingModes`, `flow.reviewDeciders` and `actionsCatalog` on
261
+ // `GET /automations`; the builder renders whatever rides and never a list of its own.
262
+
263
+ /**
264
+ * ONE condition, as a TREE (C4). A leaf is wave 22's lane condition unchanged β€” which is why
265
+ * nothing migrated: a stored leaf IS a valid tree, and the engine dispatches on shape.
266
+ * Depth and breadth are the SERVER's numbers (`flow.maxCondDepth` / `maxCondChildren`), read
267
+ * from the payload rather than repeated here.
268
+ */
269
+ export type Cond =
270
+ | { field: string; op: string; value?: string | number }
271
+ | { all: Cond[] }
272
+ | { any: Cond[] };
273
+
274
+ export function isCondGroup(c: Cond | null | undefined): c is { all: Cond[] } | { any: Cond[] } {
275
+ return !!c && (Array.isArray((c as { all?: Cond[] }).all)
276
+ || Array.isArray((c as { any?: Cond[] }).any));
277
+ }
278
+
279
+ /** A group's join word and its children, without the caller re-testing both keys every time. */
280
+ export function groupParts(c: Cond): { join: "all" | "any"; children: Cond[] } {
281
+ const all = (c as { all?: Cond[] }).all;
282
+ return Array.isArray(all) ? { join: "all", children: all }
283
+ : { join: "any", children: (c as { any: Cond[] }).any || [] };
284
+ }
285
+
286
+ /**
287
+ * One step of a flow (C4). `config` is per-kind and deliberately loose here β€” the engine
288
+ * validates it and REFUSES rather than coercing, so a client-side shape would be a second
289
+ * validator free to disagree with the one that decides.
290
+ */
291
+ /**
292
+ * ⭐ WAVE 24 / C-FORK (owner ruling R8, item 12a) β€” ONE LEG OF AN IF FORK.
293
+ *
294
+ * A group action's `config` is `{ branches: Branch[] }`. The LAST branch may carry
295
+ * `cond: null` β€” that is the **Otherwise** leg, and there is at most one of them; every other
296
+ * branch names a condition. `label` is the branch's LETTER ("A", "B", …), because R8 rules a
297
+ * fork occupies ONE step number and its legs are lettered: a branch is an alternative, not a
298
+ * later step.
299
+ *
300
+ * ⚠ THE ENGINE MIGRATES THE OLD SHAPE, it does not refuse it: a stored `{cond, actions}`
301
+ * becomes `{branches:[{id:"b1", label:"A", cond, actions}]}` on the next clean. The live
302
+ * automations use the old shape, so a refusal here would break them.
303
+ */
304
+ export interface Branch {
305
+ id: string;
306
+ label: string;
307
+ cond: Cond | null;
308
+ actions: Action[];
309
+ }
310
+
311
+ export interface Action {
312
+ id: string;
313
+ kind: string;
314
+ enabled: boolean;
315
+ /**
316
+ * Run this action only when the walking record matches. `null` = always.
317
+ *
318
+ * ⚠ REQUIRED, and that is a MEASURED claim rather than a tidy one: `clean_actions` emits
319
+ * `"when"` on every action it returns (`automation_engine.py:3713`), null included, so an
320
+ * action on the wire always carries the key. Typing it optional would let a caller build one
321
+ * without it and let a reader treat "absent" as a third state the server cannot produce.
322
+ */
323
+ when: Cond | null;
324
+ /** Per-kind. For `kind === "group"` this is `{ branches: Branch[] }` (C-FORK). */
325
+ config: Record<string, unknown>;
326
+ }
327
+
328
+ /** `flow.ending` (C5) β€” what happens to a record that reaches the end. */
329
+ export interface FlowEnding {
330
+ mode: string;
331
+ hours?: number;
332
+ }
333
+
334
+ export interface Flow {
335
+ actions: Action[];
336
+ ending: FlowEnding;
337
+ }
338
+
339
+ /**
340
+ * A row of the ACTION MENU (image 7/8's grouped list). `group` is the section heading and
341
+ * `ready:false` paints the card faded WITH the server's own reason β€” the owner asked for the
342
+ * full menu, and a shorter one would imply the missing actions do not exist. `clean_actions`
343
+ * refuses an unready kind, so faded is a wall rather than a styling choice.
344
+ */
345
+ export interface ActionCatalogRow {
346
+ kind: string;
347
+ label: string;
348
+ group: string;
349
+ ready: boolean;
350
+ detail: string;
351
+ /**
352
+ * ⭐ WAVE 24 / C-ACT β€” THE SERVER DECIDES THE MENU'S GROUP ORDER, and the client sorts by
353
+ * this number and **never by a literal list of group names**. A hard-coded
354
+ * `["Web action", "Database", …]` in the client is a second copy of the catalog's own
355
+ * structure: the day the server adds or renames a group, the client either drops it off the
356
+ * end or drops it entirely, silently. Absent sorts last β€” a server older than this client
357
+ * still renders every group it sends.
358
+ */
359
+ groupOrder?: number;
360
+ }
361
+
362
+ /** The builder's own ceilings, server-declared so the client never hard-codes the same numbers. */
363
+ export interface FlowVocab {
364
+ condOps: string[];
365
+ nullaryCondOps: string[];
366
+ maxCondDepth: number;
367
+ maxCondChildren: number;
368
+ maxGroupDepth: number;
369
+ maxActions: number;
370
+ endingModes: string[];
371
+ maxResetHours: number;
372
+ reviewDeciders: string[];
373
+ /**
374
+ * ⚠ PER-DEPLOYMENT, AND HONEST RATHER THAN DECORATIVE. With no LLM key configured the engine
375
+ * holds every card for a human β€” so an enabled-looking "decided by AI" control would promise
376
+ * a decision nothing will make. False renders it as not-configured (C6's fail-closed path,
377
+ * made visible).
378
+ */
379
+ aiReady: boolean;
380
+ }
381
+
382
+ export interface OAuthConnection {
383
+ connected: boolean;
384
+ email?: string;
385
+ }
386
+
387
+ /**
388
+ * C5's per-user connector state, keyed by PROVIDER (`google` today).
389
+ *
390
+ * A record and not an interface with a `google` field, for C3's reason one level
391
+ * down: the provider list is the server's β€” R12 says Google first and the rest
392
+ * "one by one, next waves" β€” and a client shape that names one provider has to
393
+ * be edited to see the second. This one does not.
394
+ */
395
+ export type OAuthStatus = Record<string, OAuthConnection | undefined>;
396
+
397
+ /*
398
+ * β›” `CONNECT_PROVIDERS` / `oauthProviderFor` / `oauthStartUrlFor` ARE GONE (D-43, wave 23).
399
+ *
400
+ * They were a client table mapping a server `needs` token ("connect_gmail") to a provider
401
+ * ("google") and composing `/oauth/google/start` by hand β€” a second copy of the OAuth
402
+ * registry, booked as debt on the day it shipped with the resolution written into it: "this
403
+ * table disappears the day a `TriggerOption` carries its own provider or start URL." It does
404
+ * now (`TriggerOption.connect`, composed by `routes_automation._triggers_vocab`), so the copy
405
+ * is deleted rather than left to drift the first time a second provider lands.
406
+ *
407
+ * The FAIL-QUIET-BUT-VISIBLE behaviour it was built for is unchanged and now belongs to the
408
+ * server: no `connect` means no button, and the not-configured state is still said in words.
409
+ */
410
+
411
+ export interface TickState {
412
+ enabled: boolean;
413
+ /** Which path. `external` means the door is OPEN, never that the caller is alive. */
414
+ source?: "in-process" | "external" | "";
415
+ }
416
+
417
+ export interface SourceStatus {
418
+ key: string;
419
+ label: string;
420
+ vendor: string;
421
+ ready: boolean;
422
+ canDiscover: boolean;
423
+ }
424
+
425
+ export interface DiscoverVocab {
426
+ fields: string[];
427
+ /**
428
+ * The subset seen carrying VALUES on real corpus rows. The others are
429
+ * filterable and were null on every row measured β€” and a filter on an
430
+ * unpopulated field returns nothing while looking exactly like "no such
431
+ * influencers exist".
432
+ */
433
+ lead: string[];
434
+ operators: string[];
435
+ nullaryOperators: string[];
436
+ maxRecords: number;
437
+ table: string;
438
+ /**
439
+ * WAVE 22 / C4 β€” per-field facts, one entry per name in `fields`.
440
+ *
441
+ * ⚠ OPTIONAL ON PURPOSE, and it must never be read as "everything is
442
+ * unpopulated". It is genuinely absent until the engine ships it, and absent
443
+ * is a THIRD state: the toggle list falls back to `lead` (which says the same
444
+ * thing about the three fields it names and nothing at all about the other
445
+ * eighteen) and prints no claim about the rest. The `tick` field on
446
+ * `AutomationList` is the precedent and the reason β€” an optional field a UI
447
+ * defaults to `false` is how a surface starts stating a measurement nobody
448
+ * made.
449
+ */
450
+ filterMeta?: DiscoverFieldMeta[];
451
+ /** WAVE 22 / C4 β€” the too-big guard's PARAMETERS. The DECISION stays server-side; see below. */
452
+ guard?: DiscoverGuard;
453
+ }
454
+
455
+ export interface DiscoverOperator {
456
+ /** The token the vendor accepts. Never rendered. */
457
+ value: string;
458
+ /** Plain English β€” "contains", "at least", "has any of". */
459
+ label: string;
460
+ /** Takes no value at all ("is empty"). */
461
+ nullary: boolean;
462
+ /** May carry several values, which the server expands into an OR. */
463
+ multi: boolean;
464
+ }
465
+
466
+ export interface DiscoverFieldMeta {
467
+ name: string;
468
+ /** What a person reads β€” "Bio", not `biography`. Server-owned; refusals use the same word. */
469
+ label?: string;
470
+ /** One line for the rows nobody can guess (`fbid`). Absent on the self-evident ones. */
471
+ hint?: string;
472
+ /** text | choice | number | boolean | tags β€” decides the value control. */
473
+ kind?: string;
474
+ /**
475
+ * The comparisons THIS field may be asked, in offer order.
476
+ *
477
+ * β›” Optional only because an older server does not send it β€” and when it is missing the row
478
+ * offers nothing rather than falling back to the global list. Every operator on every field is
479
+ * what produced `is_business_account >= 3`.
480
+ */
481
+ operators?: DiscoverOperator[];
482
+ /** Fixed choices for the value (Yes/No on a boolean). Empty = free text. */
483
+ options?: { value: string; label: string }[];
484
+ /** Seen carrying values on real corpus rows. */
485
+ populated: boolean;
486
+ /** A condition on this field actually cuts the corpus down. */
487
+ narrowing: boolean;
488
+ /**
489
+ * The comparison a NEW condition on this field starts with β€” SERVER-OWNED, and optional only
490
+ * because an older server does not send it.
491
+ *
492
+ * β›” Do not replace an absent one with a client default. That is the whole defect this field
493
+ * exists to fix: the client used to pick `is_not_null` for every field, which the server's
494
+ * narrowing guard refuses on every field, so a filter stayed unsaveable no matter what the
495
+ * user toggled on.
496
+ */
497
+ defaultOperator?: string;
498
+ }
499
+
500
+ /**
501
+ * β›” PARAMETERS, NOT A RULE THE CLIENT RE-IMPLEMENTS (C4).
502
+ *
503
+ * The server refuses a filter with no narrowing predicate, and it refuses it at
504
+ * create, at patch AND at run β€” with a sentence naming why. This client renders
505
+ * those numbers as *facts about the fields* (which ones narrow, which have
506
+ * values) and renders the REFUSAL VERBATIM when it comes back. It does not
507
+ * predict the refusal, because a second copy of the rule is a copy that can
508
+ * disagree: a client that blocks Save on its own arithmetic can block a filter
509
+ * the server would have accepted, and the user cannot tell which of the two is
510
+ * wrong. Same reason `cronPresets` are not a client constant.
511
+ */
512
+ export interface DiscoverGuard {
513
+ minNarrowing: number;
514
+ maxRecords: number;
515
+ }
516
+
517
+ /**
518
+ * ONE condition of a corpus search. Mirrors the server's `clean_predicates`
519
+ * shape exactly β€” `{name, operator}` plus a `value` for every operator that is
520
+ * not nullary.
521
+ */
522
+ export interface Predicate {
523
+ name: string;
524
+ operator: string;
525
+ /**
526
+ * One value, or SEVERAL β€” several is "Bio contains any of floral, flower, beauty", which the
527
+ * server expands into a nested OR so it still composes with the other conditions.
528
+ */
529
+ value?: string | number | (string | number)[];
530
+ }
531
+
532
+ /**
533
+ * ⚠ AN ESTIMATE, AND IT CARRIES ITS OWN CAVEAT (`basis: "SPEC"`). Bright Data
534
+ * never quotes a price before a run, and this account's token cannot read a
535
+ * balance β€” so no surface may present this as a billed figure.
536
+ */
537
+ export interface DiscoverEstimate {
538
+ records: number;
539
+ usd: number;
540
+ unitUsd: number;
541
+ basis: string;
542
+ note: string;
543
+ }
544
+
545
+ export interface UserTable {
546
+ key: string;
547
+ label: string;
548
+ source: string;
549
+ rowCount: number;
550
+ /**
551
+ * `automation` is the machine-owner TAG (W23/R9's grey columns) β€” the id of the automation
552
+ * that owns the column, or `null`. Narrowed from `unknown` in wave 24 against the route that
553
+ * composes it: `routes_automation.py:291` sends `f.get("automation") or None`, so `string`
554
+ * and `null` are the only two values that ride.
555
+ */
556
+ fields: { key: string; label: string; type: string; automation?: string | null }[];
557
+ /**
558
+ * The table's saved views β€” what `enters_view` names (C3). ABSENT until the server sends it,
559
+ * and absent is a third state, not an empty list: the trigger's view control says the list was
560
+ * not offered rather than rendering an empty picker that looks like "this table has no views".
561
+ * (Asked of session A in the wave mailbox; the control reads this key the day it rides.)
562
+ */
563
+ views?: { id: string; label: string }[];
564
+ }
565
+
566
+ export interface SourcePreview {
567
+ ok: boolean;
568
+ status: number;
569
+ url: string;
570
+ title?: string;
571
+ note?: string;
572
+ columns: string[];
573
+ sample: Record<string, string>[];
574
+ rowCount: number;
575
+ tableCount?: number;
576
+ }
577
+
578
+ export interface RunRows {
579
+ table: string;
580
+ label: string;
581
+ fields: { key: string; label: string }[];
582
+ rows: Record<string, string>[];
583
+ truncated: boolean;
584
+ }
585
+
586
+ // ── WAVE 22 / contract C1: THE BOARD ──────────────────────────────────────────
587
+ //
588
+ // R1's model, stated once: an automation IS a kanban board. The columns are the
589
+ // flow's stages, the CARDS ARE RECORDS of the target database, and a record's
590
+ // position is stored in a single-select stage field on that database β€” so the
591
+ // same field also drives a plain Kanban view, and the board is not a second,
592
+ // private idea of where a record is.
593
+ //
594
+ // ⚠ EVERY VOCABULARY BELOW IS `string`, DELIBERATELY. `kind` is
595
+ // trigger|action|review|branch today and `posture` is auto|strict, and both are
596
+ // typed loose for the reason contract C3 gives about trigger keys: a client
597
+ // union over a server enumeration is a list that can go stale, and the failure
598
+ // mode is SILENT β€” a `switch` with no arm for a new value renders nothing at all
599
+ // and the surface simply stops showing a stage the engine is running (the wave-9
600
+ // silent-drop class). Rendering falls back to a neutral face for anything
601
+ // unrecognised, which is visible.
602
+
603
+ export interface BoardStage {
604
+ /** For a stage backed by an engine node this IS that node's id (C1 amendment 1). */
605
+ id: string;
606
+ label: string;
607
+ /** `trigger` | `action` | `review` | `branch` β€” see the note above on why it is not a union. */
608
+ kind: string;
609
+ col: number;
610
+ row: number;
611
+ enabled: boolean;
612
+ /** Non-empty = this stage has a REAL switch. Empty = it is always on, by nature. */
613
+ toggle: string;
614
+ /** The `NodeState` words. Painted by class, never matched exhaustively. */
615
+ status: string;
616
+ detail: string;
617
+ /**
618
+ * R7's approval-posture vocabulary, adopted from QM: `strict` = the stage holds
619
+ * for a human, `auto` = the engine advances the record itself.
620
+ */
621
+ posture: string;
622
+ /**
623
+ * ⭐ THE JOIN KEY FOR THE CONFIG PANEL (C1 amendment 1, 2026-08-05). A stage
624
+ * backed by an engine node carries that node's `panel` verbatim; review stages
625
+ * carry `"review"`. The amendment is explicit that B joins on THIS and never on
626
+ * a guessed id equality β€” a panel picked by a key that only usually matches is
627
+ * a surface that shows the wrong settings while looking completely correct.
628
+ */
629
+ panel: string;
630
+ /**
631
+ * ⭐ MAY THIS STAGE HOLD CARDS? (A's CP1, additive to C1 β€” 2026-08-05.) A discovery
632
+ * flow's `find`/`collect`/`write` are things the automation DOES, not places a record
633
+ * sits, and drawing them as lanes would put three permanently empty columns between
634
+ * the trigger and the first real one. They render as the process strip instead.
635
+ *
636
+ * ⚠ OPTIONAL, AND ABSENT MEANS LANE. A server that ships C1's contract text and not
637
+ * this field describes every stage as a place β€” which is what the earlier board did β€”
638
+ * so `undefined` keeps that behaviour and only an explicit `false` moves a stage into
639
+ * the strip. Defaulting an absent field to `false` would empty the board against a
640
+ * server that never said anything of the kind.
641
+ */
642
+ record?: boolean;
643
+ /**
644
+ * May a card be PLACED here β€” i.e. is this stage's label a choice of the stage field?
645
+ * `record && !assignable` is a DERIVED bucket: cards appear from what is true about the
646
+ * row, and nothing may stamp one into it. Such a lane takes no drop.
647
+ */
648
+ assignable?: boolean;
649
+ }
650
+
651
+ export interface BoardRoute {
652
+ from: string;
653
+ to: string;
654
+ /** Server-composed. Falls back to the condition's own words when empty. */
655
+ label: string;
656
+ /** `null` = an unconditional next, which needs no label at all (R5). */
657
+ condition: { field: string; op: string; value?: string | number } | null;
658
+ }
659
+
660
+ export interface BoardCard {
661
+ rowId: string;
662
+ stageId: string;
663
+ /**
664
+ * ⚠ SERVER-COMPOSED STRINGS (C1 amendment 3). The board does NO client-side
665
+ * field formatting β€” it has no field contract for the target database and
666
+ * inventing one would mean a second formatter disagreeing with the grid's.
667
+ */
668
+ title: string;
669
+ sub: string;
670
+ movedAt: string;
671
+ /** The SERVER's answer to "may this move", not a permission the client derives. */
672
+ canAdvance: boolean;
673
+ next: string[];
674
+ /**
675
+ * WAVE 23 / C5 β€” how many times this record has been round the flow. The count lives in the
676
+ * machine cell `stage_<autoId>_cycles` and the engine increments it on every reset.
677
+ *
678
+ * ⚠ NOT ON THE CARD WIRE YET (asked of session A in the wave mailbox). Absent means "not
679
+ * reported", NOT "once": the badge only draws from 2 upwards, so a missing key renders
680
+ * nothing at all rather than a claim that every record is on its first pass β€” which is
681
+ * exactly the measurement nobody made. It lights up the day the key rides.
682
+ */
683
+ cycles?: number;
684
+ }
685
+
686
+ export interface Board {
687
+ stages: BoardStage[];
688
+ routes: BoardRoute[];
689
+ cards: BoardCard[];
690
+ /** `null` = no stage field bound yet. An empty board is a STATE, not an error (C1 amendment 2). */
691
+ stageField: { table: string; key: string } | null;
692
+ /**
693
+ * The TRUE per-stage totals. `cards` may be capped by the server, so a lane
694
+ * whose count exceeds its cards discloses the difference rather than showing a
695
+ * short list as if it were the whole one ([[no-unverifiable-aggregates]]).
696
+ */
697
+ counts: Record<string, number>;
698
+ /**
699
+ * Stages whose `cards` were capped on the wire (200/stage). `counts` always carries the
700
+ * TRUE total, so the lane can state the difference rather than showing a short list as
701
+ * if it were the whole one ([[no-unverifiable-aggregates]]).
702
+ */
703
+ truncated?: string[];
704
+ }
705
+
706
+ /**
707
+ * One decision at a review gate β€” R7's approval posture, audited (A2(5)).
708
+ *
709
+ * ⭐ WAVE 23 / C6 (R4/R14): a decision may now be made by a MODEL, and the audit says so. One
710
+ * log, not two β€” a reader asking "who decided this" gets one answer whether it was a person or
711
+ * a provider, which is the only version that can be trusted at all.
712
+ */
713
+ export interface ReviewEntry {
714
+ ts: string;
715
+ user: string;
716
+ rowId: string;
717
+ from: string;
718
+ to: string;
719
+ /** `"user"` | `"ai"`. Absent on entries written before this wave β€” render as a person. */
720
+ by?: string;
721
+ /** The one-line reason. On an AI decision it is the model's own; never invented here. */
722
+ note?: string;
723
+ /** Which model decided. Present only on AI entries, and shown so the reason has provenance. */
724
+ model?: string;
725
+ }
726
+
727
+ export class AutomationError extends Error {
728
+ status: number;
729
+
730
+ constructor(message: string, status: number) {
731
+ super(message);
732
+ this.name = "AutomationError";
733
+ this.status = status;
734
+ }
735
+ }
736
+
737
+ async function result<T>(response: Response): Promise<T> {
738
+ let body: unknown = null;
739
+ try {
740
+ body = await response.json();
741
+ } catch {
742
+ // The status is still an honest answer; the message below says so.
743
+ }
744
+ if (response.status === 401) signal(UNAUTHORIZED_EVENT);
745
+ if (!response.ok) {
746
+ const shaped = body as { error?: { message?: string } } | null;
747
+ throw new AutomationError(
748
+ shaped?.error?.message || `The server answered ${response.status}.`,
749
+ response.status
750
+ );
751
+ }
752
+ return body as T;
753
+ }
754
+
755
+ function send<T>(path: string, init?: RequestInit): Promise<T> {
756
+ return fetch(`${API_V1}${path}`, {
757
+ credentials: CREDENTIALS,
758
+ headers: init?.body ? { "Content-Type": "application/json" } : undefined,
759
+ ...init,
760
+ }).then((r) => result<T>(r));
761
+ }
762
+
763
+ export function listAutomations(abort?: AbortSignal): Promise<AutomationList> {
764
+ return send<AutomationList>("/automations", { signal: abort });
765
+ }
766
+
767
+ export function listTables(abort?: AbortSignal): Promise<{ tables: UserTable[] }> {
768
+ return send<{ tables: UserTable[] }>("/automations/tables", { signal: abort });
769
+ }
770
+
771
+ export function createAutomation(body: unknown): Promise<{ automation: Automation }> {
772
+ return send("/automations", { method: "POST", body: JSON.stringify(body) });
773
+ }
774
+
775
+ export function patchAutomation(
776
+ id: string,
777
+ body: unknown
778
+ ): Promise<{ automation: Automation }> {
779
+ return send(`/automations/${encodeURIComponent(id)}`, {
780
+ method: "PATCH",
781
+ body: JSON.stringify(body),
782
+ });
783
+ }
784
+
785
+ export function deleteAutomation(id: string): Promise<{ deleted: string }> {
786
+ return send(`/automations/${encodeURIComponent(id)}`, { method: "DELETE" });
787
+ }
788
+
789
+ export function runAutomation(id: string): Promise<{ started: string }> {
790
+ return send(`/automations/${encodeURIComponent(id)}/run`, { method: "POST" });
791
+ }
792
+
793
+ /**
794
+ * Flip one step's switch.
795
+ *
796
+ * The client says WHICH NODE was clicked and nothing else β€” the server owns what
797
+ * each switch means (`engine.NODE_TOGGLES`). A client that knew "the Bright Data
798
+ * node writes config.tier" would be a second copy of that knowledge, free to
799
+ * drift from the engine that reads it β€” and it would have had to be rewritten
800
+ * when the vendor changed. It did not.
801
+ */
802
+ export function toggleNode(
803
+ id: string,
804
+ nodeId: string
805
+ ): Promise<{ automation: Automation }> {
806
+ return send(
807
+ `/automations/${encodeURIComponent(id)}/nodes/${encodeURIComponent(nodeId)}/toggle`,
808
+ { method: "POST" }
809
+ );
810
+ }
811
+
812
+ export function getAutomation(id: string): Promise<{ automation: Automation }> {
813
+ return send(`/automations/${encodeURIComponent(id)}`);
814
+ }
815
+
816
+ export function runRows(id: string): Promise<RunRows> {
817
+ return send(`/automations/${encodeURIComponent(id)}/rows`);
818
+ }
819
+
820
+ /**
821
+ * The board for one automation (C1). Answers 200 for every existing automation β€”
822
+ * an automation with no bound stage field comes back with its stages and
823
+ * `stageField: null, cards: []`, which the board prints as a state rather than
824
+ * an error (C1 amendment 2).
825
+ */
826
+ export function getBoard(id: string, abort?: AbortSignal): Promise<{ board: Board }> {
827
+ return send(`/automations/${encodeURIComponent(id)}/board`, { signal: abort });
828
+ }
829
+
830
+ /**
831
+ * Move ONE record along the flow, and answer the fresh board.
832
+ *
833
+ * β›” THE SERVER DECIDES LEGALITY, NOT THIS FILE (C1). A review-stage card
834
+ * advances only to a member of its own `next`; every other move is admin-only.
835
+ * The client sends the drop it was given and renders the refusal verbatim β€” a
836
+ * client that pre-judged the move would be a second copy of a permission rule,
837
+ * and when the two copies disagree the user is left with a control that does
838
+ * nothing for a reason nobody can read.
839
+ */
840
+ export function moveCard(
841
+ id: string,
842
+ rowId: string,
843
+ to: string
844
+ ): Promise<{ board: Board }> {
845
+ return send(
846
+ `/automations/${encodeURIComponent(id)}/cards/${encodeURIComponent(rowId)}/move`,
847
+ { method: "POST", body: JSON.stringify({ to }) }
848
+ );
849
+ }
850
+
851
+ /** Is a connector connected for THIS user? (C5 β€” per-user keychain slots, R7's seam.) */
852
+ export function oauthStatus(abort?: AbortSignal): Promise<OAuthStatus> {
853
+ return send("/oauth/status", { signal: abort });
854
+ }
855
+
856
+ /** What would a search of this size cost? Asked BEFORE the run, never after. */
857
+ export function discoverEstimate(recordsLimit: number): Promise<DiscoverEstimate> {
858
+ return send("/automations/discover/estimate", {
859
+ method: "POST",
860
+ body: JSON.stringify({ recordsLimit }),
861
+ });
862
+ }
863
+
864
+ export function previewSource(
865
+ url: string,
866
+ extract: string,
867
+ tableIndex: number
868
+ ): Promise<SourcePreview> {
869
+ return send("/automations/preview", {
870
+ method: "POST",
871
+ body: JSON.stringify({ url, extract, tableIndex }),
872
+ });
873
+ }
874
+
875
+ /**
876
+ * A source column name β†’ a storable field key. Mirrors the server's own
877
+ * normalisation (`clean_config`) so the key the UI shows is the key that gets
878
+ * stored β€” a preview that promised `gics_sector` and a store that wrote
879
+ * `gics__sector` would look like data loss.
880
+ */
881
+ export function fieldKeyFor(column: string): string {
882
+ return (column || "")
883
+ .toLowerCase()
884
+ .replace(/[^a-z0-9_]+/g, "_")
885
+ .replace(/^_+|_+$/g, "")
886
+ .slice(0, 60);
887
+ }
888
+
889
+ /** The state word a status dot / chip paints from. */
890
+ export function stateOf(a: Automation): RunState {
891
+ return a.running ? "running" : (a.status?.state as RunState) || "idle";
892
+ }
893
+
894
+ /**
895
+ * ⭐ WAVE 24 / C-TYPES + C-PERF (item 6) β€” WHAT THIS RUN IS DOING RIGHT NOW, or `""`.
896
+ *
897
+ * This is the honest half of "Run once now looks stuck": the engine has been publishing a live
898
+ * step text the whole time and **nothing has ever rendered it**, so a 120-second Bright Data
899
+ * wait and a hung thread look identical from the outside. They are not the same thing, and the
900
+ * server already knows which one it is.
901
+ *
902
+ * β›” WHY A FUNCTION AND NOT A FIELD β€” C-TYPES AMENDMENT A2 (2026-08-06, session D).
903
+ * The contract block writes `liveStep?: string` on `interface Automation`. Measured against the
904
+ * route that composes the payload: `_wire()` (`routes_automation.py:52-81`) emits `status` with
905
+ * `step` inside it (`:50-51`) and emits **no top-level `liveStep` at all**. Declaring the field
906
+ * would put a key on the `Automation` interface that no server sends β€” so `automation.liveStep`
907
+ * would compile, type-check, and be `undefined` forever. That is this codebase's own
908
+ * silent-drop class pointing the other way: the whole file is built on "absent must stay
909
+ * absent", and inventing a present-looking field is the same defect with the sign flipped.
910
+ * `step` is ALREADY typed on `status` (see `Automation.status`), so nothing is lost β€” this
911
+ * function is the greppable name the contract wanted, reading the key that actually rides.
912
+ * The W24-W1 hand-off is unaffected: it is a PROP called `liveStep`, and this is what fills it.
913
+ */
914
+ export function liveStepOf(a: Automation): string {
915
+ return stateOf(a) === "running" ? String(a.status?.step || "") : "";
916
+ }
917
+
918
+ /**
919
+ * A run's counts as ordered label/value pairs. The ORDER is the sentence the
920
+ * numbers make β€” new, updated, unchanged, then the ones that need explaining β€”
921
+ * and `orphans` is spelled out rather than abbreviated because a bare number
922
+ * next to the word "orphans" is the one count a user must not have to guess at.
923
+ */
924
+ export const COUNT_LABELS: [string, string][] = [
925
+ ["inserted", "New"],
926
+ ["updated", "Updated"],
927
+ ["unchanged", "Unchanged"],
928
+ ["orphans", "No longer on the page (kept)"],
929
+ ["duplicates", "Duplicate keys"],
930
+ ["skipped", "Skipped (no key)"],
931
+ // ⚠ ITS OWN CHIP, next to `skipped` but never merged with it. "Skipped" is a
932
+ // property of the data and usually benign; "not written β€” the database is
933
+ // full" is a property of the system and never is. One chip for both is how a
934
+ // time series stops growing without anybody being told.
935
+ ["capped", "Not written β€” the database is full"],
936
+ ["source_rows", "Rows read"],
937
+ ["profiles", "Profiles"],
938
+ ["ok", "Read in full"],
939
+ // ⚠ ADDED after reading the first live screenshot. The engine counts `partial` separately
940
+ // (profile read, media not anonymously readable) but this table did not, so a run whose
941
+ // summary said "1/1 profiles read" showed a chip row reading "0 Read" β€” the chips
942
+ // contradicting the sentence directly above them. A count the summary names must have a chip.
943
+ ["partial", "Profile only"],
944
+ ["blocked", "Blocked"],
945
+ ["error", "Errors"],
946
+ ["paid", "Exact counts"],
947
+ ["posts", "Posts"],
948
+ ["new_posts", "New posts"],
949
+ // The engagement series only grows while the per-post rung is on, so its
950
+ // count is its own chip β€” "12 posts" and "0 engagement snapshots" together
951
+ // are the honest picture of a profile-only run.
952
+ ["metrics", "Engagement snapshots"],
953
+ // Discovery.
954
+ ["asked", "Asked for"],
955
+ ["found", "Profiles found"],
956
+ ["new", "New to us"],
957
+ ["seen_again", "Seen before"],
958
+ ["dropped", "Returned but unusable (no handle)"],
959
+ // ⚠ Its own chip for the same reason `capped` has one: a database that could
960
+ // not be CREATED is a system fact, and the run that hit it wrote nothing.
961
+ ["missing_tables", "Databases that could not be created"],
962
+ ];
web/src/index.css CHANGED
@@ -8296,6 +8296,24 @@ a.cg-map-ctl-b { text-decoration: none; }
8296
  background: var(--lp-yellow-tint);
8297
  color: var(--lp-yellow-deep);
8298
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8299
  /* Indented past the switch, so the conditions read as belonging to the field above them. */
8300
  .autob-tgl-body {
8301
  display: flex;
@@ -8541,6 +8559,17 @@ a.cg-map-ctl-b { text-decoration: none; }
8541
  font-size: var(--lp-fs-3xs);
8542
  color: var(--lp-muted);
8543
  }
 
 
 
 
 
 
 
 
 
 
 
8544
  .autox-card-drop {
8545
  flex: 0 0 auto;
8546
  display: inline-flex;
 
8296
  background: var(--lp-yellow-tint);
8297
  color: var(--lp-yellow-deep);
8298
  }
8299
+ /* The "what IS this field" line, for the handful nobody can guess (Instagram ID, Facebook ID).
8300
+ Shown only when a field is switched ON β€” a hint under all 21 rows is a hint under none. */
8301
+ .autob-tgl-hint {
8302
+ margin: 0 0 6px;
8303
+ color: var(--lp-muted);
8304
+ font-size: var(--lp-fs-4xs);
8305
+ }
8306
+ /* "any of 3" β€” the confirmation that a comma-separated value was read as several. Without it,
8307
+ the difference between one keyword and three is a comma the eye skips. */
8308
+ .autob-cond-any {
8309
+ flex: 0 0 auto;
8310
+ padding: 0 6px;
8311
+ border-radius: var(--lp-r-pill);
8312
+ background: var(--lp-blue-tint);
8313
+ color: var(--lp-blue-deep);
8314
+ font-size: var(--lp-fs-4xs);
8315
+ white-space: nowrap;
8316
+ }
8317
  /* Indented past the switch, so the conditions read as belonging to the field above them. */
8318
  .autob-tgl-body {
8319
  display: flex;
 
8559
  font-size: var(--lp-fs-3xs);
8560
  color: var(--lp-muted);
8561
  }
8562
+ /* Where the remove βœ• would be on the one card that has no remove. It says WHY rather than
8563
+ showing a disabled control: a greyed βœ• invites the click that cannot work. */
8564
+ .autox-card-pin {
8565
+ flex: 0 0 auto;
8566
+ padding: 0 6px;
8567
+ border-radius: var(--lp-r-pill);
8568
+ background: var(--lp-surface-2);
8569
+ color: var(--lp-muted);
8570
+ font-size: var(--lp-fs-4xs);
8571
+ white-space: nowrap;
8572
+ }
8573
  .autox-card-drop {
8574
  flex: 0 0 auto;
8575
  display: inline-flex;