diff --git "a/api/automation_engine.py" "b/api/automation_engine.py" --- "a/api/automation_engine.py" +++ "b/api/automation_engine.py" @@ -67,9 +67,30 @@ UT_PREFIX = "ut_" MAX_AUTOMATIONS = 40 MAX_RUNS = 20 # trimmed history per automation MAX_NAME = 80 -MAX_UT_ROWS = 5000 # mirrors core.user_tables.MAX_ROWS +#: ⛔ IT DOES **NOT** MIRROR `core.user_tables.MAX_ROWS`, AND THE COMMENT THAT SAID SO WAS A 12x +#: STALE CLAIM — `MAX_ROWS` is 60,000. That sentence is most of what made D-143 hard to see: it +#: read as "the substrate's bound, kept in step", so nobody asked whether a flow was silently +#: walking 5,000 of 32,826 connected rows. It was. +#: **This is the FALLBACK ONLY.** The live answer is per TABLE and comes from +#: `core.user_tables.row_limit` via `_flow_record_cap` — `None` for a connected source (R6: no +#: cap), `MAX_ROWS` for the editable substrate, `0` for a read-through grid. This constant is +#: reached only when that import fails, and it is deliberately the CONSERVATIVE direction. +#: ⚠ Do not "fix" it by raising it to 60,000: a fallback that runs when the evaluator is missing +#: should not also be the widest one. And do not delete it — D-143's own row says the editable +#: substrate still needs a bound. +MAX_UT_ROWS = 5000 MAX_UT_TABLES = 40 +#: ⛔⛔ D-112's SENTENCE, AS A CONSTANT, BECAUSE TWO PLACES DEPEND ON IT AGREEING. +#: `enrich_selection` produces it when a step's `fromView` names a view that no longer resolves; +#: `run_flow` tests for it to turn that run `partial` instead of `ok`. Measured live on a real +#: tenant: an enrich action pointed at a deleted view walked ZERO records and reported **`ok`** — +#: indistinguishable on every surface from a run that worked, and a strong candidate for why the +#: owner's enrichment kept appearing to do nothing. +#: ⚠ THE WORDING IS FREE TO CHANGE; the AGREEMENT is not. Both sites read this name, so a better +#: sentence stays a one-line edit instead of a silent regression [[constant-two-features-share]]. +ENRICH_VIEW_UNREADABLE = "the enrich step names a view it cannot read" + #: ⚠ THE APPEND TABLES NEED A DIFFERENT CAP, and the reason is arithmetic rather than taste. #: `MAX_UT_ROWS` was sized for a scraped LIST — a page of ~500 companies that is re-read, so the #: row count is bounded by the page. The `ut_ig_*` tables are the opposite shape: every pull @@ -223,10 +244,40 @@ RETIRED_KIND_REPLACEMENT = { #: door open on purpose, and there is a gate check that says so in those words. A kind may only be #: walled off at a door once something else answers the same need. #: (`REPLACED_KINDS` was here and is deleted with the refusal it gated — see `clean_definition`.) -KIND_LABELS = {"plain": "Automation", "scrape_db": "Web page to database", +#: ⭐ WAVE 34 · R12 — `plain` READS "Agent". The owner renamed the module to Agents, so the KIND +#: that means "an ordinary one of these" is an Agent, singular (the module is the plural). +#: ⛔ THE KEY `"plain"` IS UNTOUCHED and so is every other key here: D-65's rule, restated three +#: times in this file, is that a kind is permanent — the LABELS are display and may move freely, +#: the keys are stored on every automation ever created and may not. +KIND_LABELS = {"plain": "Agent", "scrape_db": "Web page to database", "field_instagram": "Instagram profile column", "discover_instagram": "Find Instagram profiles", "discover_tiktok": "Find TikTok profiles"} +#: ⭐⭐ WAVE 34 · CONTRACTS C3 + C4 — WHY A SYSTEM AGENT CANNOT BE DELETED, one sentence per slug. +#: +#: ⛔ ONE PLACE, because two doors ask this question (the DELETE route refuses with it, and the +#: Canvas explains why its controls are read-only) and a refusal that says something different +#: from the surface it refuses on is worse than either sentence alone. D-65's own remedy in a new +#: family: a refusal that does not name the alternative sends somebody looking for a bug in a +#: decision made on purpose. +SYSTEM_AGENT_REASON = { + "field_agent": "this agent is an AI enrichment column. Delete the column on its database and " + "the agent goes with it", + "odoo_sync": "this is the Odoo connection's own sync schedule. Disconnect Odoo in Connectors " + "to stop it, or change how often it runs on this page", +} + + +def system_agent_refusal(slug): + """The sentence for a `system:` slug, or a general one for a slug nobody has written yet. + + ⚠ IT NEVER RETURNS EMPTY. A refusal with no sentence is a 409 a person cannot act on, and the + fallback is the one branch that will be reached by a slug added later and forgotten here. + """ + return SYSTEM_AGENT_REASON.get(str(slug or ""), "this agent is part of the workspace setup " + "and cannot be deleted here") + + EXTRACTS = ("table", "jsonld") STATES = ("idle", "running", "ok", "error", "partial") #: Which capture rung a `field_instagram` automation is allowed to reach for (R1's hybrid). @@ -453,7 +504,7 @@ def fetch(url, timeout=20.0, max_kb=2048, allowed=(), max_hops=5, headers=None): status, final = r.status_code, str(r.url) r.close() return status, final, body - raise Refused(f"more than {max_hops} redirects — refusing to follow further") + raise Refused(f"more than {max_hops} redirects. Refusing to follow further") def fetch_json(url, body, timeout=60.0, max_kb=8192, headers=None): @@ -473,7 +524,7 @@ def fetch_json(url, body, timeout=60.0, max_kb=8192, headers=None): data=json.dumps(body if body is not None else {}), stream=True) try: if r.status_code in (301, 302, 303, 307, 308): - raise Refused(f"the POST answered {r.status_code} — a redirected POST is refused, " + raise Refused(f"the POST answered {r.status_code}. A redirected POST is refused, " f"never re-sent to a location the server picked") return r.status_code, (r.raw.read(max_kb * 1024, decode_content=True) or b"") finally: @@ -487,7 +538,7 @@ def fetch_json(url, body, timeout=60.0, max_kb=8192, headers=None): def _soup(body): if BeautifulSoup is None: raise RuntimeError( - "beautifulsoup4 is not installed in this environment — the automation engine's " + "beautifulsoup4 is not installed in this environment. The automation engine's " "extraction half needs it (see the wave-18 mailbox: add beautifulsoup4 + lxml to " "aios-web/requirements.txt).") try: @@ -544,7 +595,7 @@ def preview(url, extract="table", table_index=0, allowed=()): status, final, body = fetch(url, allowed=allowed) if not (200 <= status < 300): return {"ok": False, "status": status, "url": final, - "note": f"the page answered {status} — it may be bot-gated or gone", + "note": f"the page answered {status}. It may be bot-gated or gone", "columns": [], "sample": [], "rowCount": 0} soup = _soup(body) rows = [] @@ -732,9 +783,38 @@ def next_fire(expr, now=None, lookahead_days=400): # THE UPSERT — pure, so the arithmetic is testable without a store or a network # --------------------------------------------------------------------------------------------- -def upsert_rows(existing, incoming, key_field, cap=None): +#: ⛔⛔ D-116 — THE SIX CELLS A CORPUS RE-FIND MUST NOT OVERWRITE ONCE AN ENRICHMENT MEASURED THEM. +#: A discovery re-find emits these on EVERY match, not only on insert, so the moment a scheduled +#: search re-matched an account somebody had PAID to enrich, six exact measurements were replaced by +#: pre-collected corpus values of unknown vintage — no error, no visible change other than the +#: number. Measured 2026-08-10 on a live tenant: 0 of 105 profiles had been re-found yet, so this +#: was a defect waiting for its first scheduled re-run rather than one anybody had seen. +#: ⚠ SCALARS ONLY, and that is the ruling. The OBSERVATION is appended either way — the corpus +#: genuinely saw that account at that follower count, and the snapshot series is where a corpus read +#: belongs. Suppressing the observation would be the same defect arriving from the other side. +CORPUS_SOFT_KEYS = ("followers", "following", "avg_engagement", "verified", "category", "bio") + + +def corpus_protect(before, _src): + """Which keys this incoming CORPUS row may not overwrite on `before`. D-116's precedence rule. + + ⛔ THE TEST IS `enriched_at`, i.e. "did an exact read ever write this row", NOT "is the cell + non-empty". The exit condition rules the second one out by name, and rightly: *"NOT by making + `upsert_rows` skip non-empty cells — that would break every re-scrape in the product."* A + re-scrape SHOULD move a number the corpus owns; what it may not do is move one an exact read + owns. + """ + return CORPUS_SOFT_KEYS if str((before or {}).get("enriched_at") or "").strip() else () + + +def upsert_rows(existing, incoming, key_field, cap=None, protect=None): """Merge scraped rows into a user table's rows BY KEY. Returns `(rows, counts)`. + `protect` is an optional `f(before, src) -> keys` naming, PER ROW, the keys this incoming row + may not overwrite. Default `None` = the old behaviour exactly, so the other nine call sites are + untouched — the precedence rule belongs to the CALLER that knows its data's provenance, not to + the merge, and a rule baked in here would apply to nine paths that never asked for one. + THE RULE THAT MATTERS: **an orphan is COUNTED, NEVER DELETED.** A row that has stopped appearing on the source page has not necessarily stopped existing — the page changed its filter, the fetch was partial, the site paginated. Deleting on absence turns any upstream @@ -792,9 +872,18 @@ def upsert_rows(existing, incoming, key_field, cap=None): counts["inserted"] += 1 continue before = rows[rid] - changed = {k: v for k, v in src.items() if str(before.get(k, "")) != str(v)} + # ⛔ D-116's PRECEDENCE RULE, applied per ROW because provenance is a property of the row. + # `held` counts the cells a lower-provenance source was refused, so the run can SAY it + # rather than quietly doing the right thing — a protection nobody is told about is + # indistinguishable from a source that happened to agree. + keep = set(protect(before, src) or ()) if protect else set() + use = {k: v for k, v in src.items() if k not in keep} if keep else src + if keep: + counts["held"] = counts.get("held", 0) + sum( + 1 for k in keep if k in src and str(before.get(k, "")) != str(src.get(k))) + changed = {k: v for k, v in use.items() if str(before.get(k, "")) != str(v)} if changed: - before.update(src) + before.update(use) counts["updated"] += 1 else: counts["unchanged"] += 1 @@ -987,7 +1076,7 @@ def bind_unbound_fields(rt): else: f["automation"]["disabled"] = True f["automation"]["statusNote"] = ( - "not bound to any flow — create an automation for this column " + "not bound to any flow. Create an automation for this column " "or delete it") return cur @@ -1438,10 +1527,10 @@ def clean_post_groups(raw, max_posts): return None, "each post group has to be a {type, limit} entry" t = str(item.get("type") or "").strip().lower() if t not in POST_TYPES: - return None, (f"'{t or 'blank'}' is not a post type — use one of " + return None, (f"'{t or 'blank'}' is not a post type. Use one of " f"{', '.join(POST_TYPES)}") if t in seen: - return None, f"the post groups name '{t}' twice — one limit per type" + return None, f"the post groups name '{t}' twice. One limit per type" seen.add(t) try: lim = int(item.get("limit")) @@ -1454,7 +1543,7 @@ def clean_post_groups(raw, max_posts): # refused HERE, where the number they typed is still on the screen in front of them. if lim > max_posts: return None, (f"this enrichment captures {max_posts} posts per profile, so a {t} " - f"group cannot keep {lim} — raise the post count first") + f"group cannot keep {lim}. Raise the post count first") out.append({"type": t, "limit": lim}) return out, None @@ -1486,7 +1575,7 @@ def clean_max_posts(raw, default=DEFAULT_POSTS_PER_PULL, submitted=True): if n < 1: return None, "keep at least one post per profile, or turn the post capture off" if n > MAX_POSTS_PER_PULL: - return None, (f"a profile pull returns at most {MAX_POSTS_PER_PULL} posts — that is the " + return None, (f"a profile pull returns at most {MAX_POSTS_PER_PULL} posts. That is the " f"vendor's cap, not ours, so {n} would store the same " f"{MAX_POSTS_PER_PULL} and read as more") return n, None @@ -1600,7 +1689,7 @@ def clean_config(kind, raw, previous=None): _, _disc_table, _disc_label, _ = discovery_facts(kind) limit = int(raw.get("recordsLimit") or 0) if limit < 1: - return None, ("say how many profiles to fetch — an UNBOUNDED discovery query is the " + return None, ("say how many profiles to fetch. An UNBOUNDED discovery query is the " "one shape the vendor refuses outright (NOT_ENOUGH_FUNDS)") if limit > BD_MAX_RECORDS: return None, f"a single discovery run may ask for at most {BD_MAX_RECORDS} profiles" @@ -1653,7 +1742,7 @@ def clean_seed(raw): return None, f"{source or 'that seed'!r} is not one of: " + ", ".join(SEED_SOURCES) table = _s(raw.get("table"), 60).strip() if table and not table.startswith(UT_PREFIX): - return None, f"a seed reads a blank database (ut_*) — {table!r} is not one" + return None, f"a seed reads a blank database (ut_*). {table!r} is not one" basis = raw.get("basis") if isinstance(raw.get("basis"), dict) else {} derived, _err = clean_predicates(raw.get("derived") or [], "and") return {"source": source, "table": table, "id": _s(raw.get("id"), 80).strip(), @@ -1693,11 +1782,15 @@ def clean_schedule(raw, previous=None): # ⛔ `terminal` IS THE DEFAULT and every existing automation gets it, because a stored definition # that predates this field must not start moving records on its own the day the code ships. A # loop is a thing somebody turns on. -def clean_flow(raw, previous=None): - """Validate the builder's ordered action list. `(flow, error)`.""" +def clean_flow(raw, previous=None, notes=None, rt=None): + """Validate the builder's ordered action list. `(flow, error)`. + + ⚠ `rt` is the tenant wall for gated action kinds (W35-T35 / C8) and is simply forwarded. + """ raw = raw if isinstance(raw, dict) else {} prev = previous if isinstance(previous, dict) else {} - actions, err = clean_actions(raw.get("actions") if "actions" in raw else prev.get("actions")) + actions, err = clean_actions( + raw.get("actions") if "actions" in raw else prev.get("actions"), notes=notes, rt=rt) if err: return None, err return {"actions": actions}, None @@ -1972,7 +2065,7 @@ def ig_action_pinned(defn, index): return (defn or {}).get("kind") in DISCOVERY_KINDS and index == 0 -def clean_definition(raw, previous=None, username=""): +def clean_definition(raw, previous=None, username="", notes=None, rt=None): """Whole-definition validation. Returns `(defn, error)`.""" raw = raw if isinstance(raw, dict) else {} prev = previous or {} @@ -2149,7 +2242,7 @@ def clean_definition(raw, previous=None, username=""): _prev_table, _prev_enrich = discovery_seed_spec(prev.get("kind")) flow_raw = _drop_ig_seeds( flow_raw, (prev.get("config") or {}).get("targetTable") or _prev_table, _prev_enrich) - flow, ferr = clean_flow(flow_raw, prev.get("flow")) + flow, ferr = clean_flow(flow_raw, prev.get("flow"), notes=notes, rt=rt) if ferr: return None, ferr # ⭐ WAVE 30 — widened with the seeder above: TikTok now HAS a pinned step 1, so the rule that @@ -2225,6 +2318,22 @@ def clean_definition(raw, previous=None, username=""): "state": dict(prev.get("state") or {}), "created": prev.get("created") or _iso(), "createdBy": prev.get("createdBy") or username, + # ⭐⭐ WAVE 35 · T37 — `system` IS STICKY ACROSS A PATCH, AND IT IS **NEVER READ FROM `raw`**. + # + # ⛔ THE BUG THIS CLOSES WAS ALREADY WRITTEN AND WOULD HAVE SHIPPED. `routes_automation. + # delete_automation` refuses any stored row carrying `system`, which is what makes a seeded + # system agent undeletable — and this function is a WHITELIST that did not carry the key, so + # the FIRST EDIT of such an agent silently stripped its marker and made it deletable. The + # seed would then mint it again on the next list call: a delete that appears to work and + # undoes itself. Found by asserting the round trip rather than by reading the code. + # + # ⛔ FROM `prev` ONLY. Reading it from `raw` would let ANY caller POST + # `{"system": "anything"}` and mint themselves an automation nobody can delete — a + # privilege escalation through a field nobody validates. The flag is granted by the seeder + # and inherited from the stored row, never asserted by a payload. + # ⚠ Same shape and same reason as the pre-set FIELD flag, which DESIGN.md §4 already + # describes as "sticky across a PATCH". One idea, one behaviour, two objects. + **({"system": _s(prev.get("system"), 40)} if prev.get("system") else {}), }, None @@ -2475,7 +2584,7 @@ def resolve_target(rt, raw, username=""): import core.user_tables as _ut_new key = _ut_new.create(label, username or "automation", st=rt) if not key: - return None, ("the database could not be created — this workspace may be at its table " + return None, ("the database could not be created. This workspace may be at its table " "limit") return {"targetTable": key, "targetLabel": label}, None @@ -2497,7 +2606,7 @@ def _unmint(rt, key): pass -def create(rt, raw, username=""): +def create(rt, raw, username="", notes=None): existing = all_definitions(rt) if len(existing) >= MAX_AUTOMATIONS: return None, f"this workspace is at the {MAX_AUTOMATIONS}-automation limit" @@ -2526,7 +2635,9 @@ def create(rt, raw, username=""): # has, instead of letting the pure validator mint a second empty one. See # `discover_default_table`; a target the caller named is never rewritten. raw = _apply_discover_default(rt, raw) - defn, err = clean_definition(raw, None, username) + # W35-T35 (C8): `rt=` is the tenant wall for gated action kinds. Both doors pass it; a door + # that forgot would REFUSE the kind, not admit it (`TENANT_GATED_ACTIONS` is fail-closed). + defn, err = clean_definition(raw, None, username, notes=notes, rt=rt) if err: _unmint(rt, minted) return None, err @@ -2541,7 +2652,7 @@ def create(rt, raw, username=""): if defn["kind"] in RETIRED_KINDS: _unmint(rt, minted) return None, (f"{KIND_LABELS.get(defn['kind'], defn['kind'])!r} automations are no " - f"longer created — the ones already using it keep working. " + f"longer created. The ones already using it keep working. " f"{RETIRED_KIND_REPLACEMENT.get(defn['kind'], '')}") defn["id"] = _new_id(existing) @@ -2562,7 +2673,7 @@ def create(rt, raw, username=""): return defn, None -def patch(rt, auto_id, raw, username=""): +def patch(rt, auto_id, raw, username="", notes=None): existing = all_definitions(rt) prev = existing.get(str(auto_id)) if prev is None: @@ -2581,7 +2692,7 @@ def patch(rt, auto_id, raw, username=""): # config that has never carried a target through the pure validator, which mints the empty # `ut_ig_candidates`. `create` alone would have left the commonest path untouched. merged = _apply_discover_default(rt, merged) - defn, err = clean_definition(merged, prev, username) + defn, err = clean_definition(merged, prev, username, notes=notes, rt=rt) if err: return None, err defn["id"] = str(auto_id) @@ -2880,14 +2991,45 @@ def remove(rt, auto_id): # `(table, field)` pairs it found and the mutation applies exactly those — the shape # `bind_unbound_fields` in this module already uses, so a delete costs one walk instead of two # and the write touches only the fields it named. - # ⛔ HONEST RESIDUAL, STATED RATHER THAN SMOOTHED (R6's second sentence): this still costs ONE - # full read of the tenant's `user_tables` document, and `rt.update` below takes its own strict - # read. **That second read cannot be removed here** — it belongs to the write, and answering - # "which fields did this flow tag?" without a scan needs a tagged-field INDEX, which is a - # feature and not a wave-tail edit. It is booked as D-179; what changed is the second WALK, - # not the read count. + # ⭐⭐ WAVE 33 (D-179) — THE SCAN NO LONGER READS THE ROWS, and that is where the cost was. + # + # This walk asks ONE question — "which fields did this flow tag?" — and it has never looked at + # a row to answer it. It was nevertheless taking `ut_all`, a whole deep copy of the tenant's + # `user_tables` document, of which **99.9% of the bytes are `rows` nothing here reads** + # (measured on tenant #0: 28.6 MB, 81,330 rows, 703 ms warm). A's C5 projection makes that + # ~0.1% of the bytes. + # ⛔ HANDED TO A READ AND NOTHING ELSE. `lend_defs` serves `_Projected` values, so reaching + # `defn['rows']` raises a `KeyError` NAMING the projection — by design — and `plan` carries + # only `(table_key, field_key)` STRINGS out of this scope. The mutation below takes its own + # strict document from `rt.update` and never sees a projected value, which is C5's second + # clause: a projected snapshot is never handed to a post-write read-back. + # ⚠ HONEST RESIDUAL, STATED RATHER THAN SMOOTHED (R6's second sentence): D-179's exit condition + # asks for ZERO full-document reads and this is ONE — `rt.update` below takes a strict read + # that belongs to the WRITE and cannot be removed from here. What is gone is the expensive one. + # ⚠ AND THE FALLBACK IS DELIBERATE: `all_defs` degrades to the whole read on any failure, so a + # store that cannot project still deletes correctly, only slower. + # + # ⭐⭐ WAVE 35 · T34 — THE RESIDUAL IS NOW MEASURED RATHER THAN ASSERTED, and the count is + # better than the paragraph above claims. Whole `user_tables` reads per delete, against a + # runtime that has production's `get_projection`: + # TAGGED (a discovery flow that spawned columns) → 1 whole + 1 projected + # UNTAGGED (a `plain` flow) → 0 whole + 1 projected + # The untagged case pays NONE because `if not plan: return` fires before the write. The + # tagged case's ONE is `rt.update`'s own strict read, and it is a FLOOR, not a choice: + # `core/store.py::get_projection` states that a write must always read whole, because a + # read-modify-write handed a rows-less document would upload the tenant with its rows deleted. + # ⛔ Reaching ZERO needs D-179's `{flowId: [(table_key, field_key)]}` index, written where the + # presets are spawned — a feature, not an edit to this function. Nothing here can do better. + # ⚠ THOSE NUMBERS WERE UNOBSERVABLE UNTIL W35-T34: `verify_automation`'s delete-speed double + # had no `get_projection`, so `all_defs` fell back and the gate measured 2 and 1 — the + # PRE-WAVE-33 path — for two waves. The double is producer-faithful now and asserts the counts. + try: + import core.user_tables as _ut_defs # noqa: PLC0415 + _scan = dict(_ut_defs.all_defs(rt) or {}) + except Exception: # noqa: BLE001 + _scan = ut_all(rt) plan = [(tk, str(f.get("key") or "")) - for tk, t in ut_all(rt).items() + for tk, t in _scan.items() for f in ((t or {}).get("fields") or []) if str((f.get("automation") or {}).get("flowId") or "") == aid] if not plan: @@ -2999,7 +3141,7 @@ def _commit_run(rt, auto_id, state, summary, counts, ok, affected=None, steps=No if isinstance(trg, dict): trg["paused"] = True d["statusNote"] = (f"auto-paused after {CONSECUTIVE_FAILURE_PAUSE} consecutive " - f"failures — fix the cause, then re-enable: " + f"failures. Fix the cause, then re-enable: " f"{entry['summary'][:120]}") return cur @@ -3038,7 +3180,9 @@ def _notify_outcome(rt, auto_id, state, entry): from core import alerts as _alerts _alerts.notify( owner=owner, - label=_s(defn.get("name") or "Automation", 80), + # ⭐ WAVE 34 · R12 — the fallback name a notification wears when the automation has + # none. "Agent", singular: this names ONE of them, not the module. + label=_s(defn.get("name") or "Agent", 80), topic="automation", key=str(auto_id), detail=f"{state}: {entry.get('summary') or ''}"[:300], @@ -3866,8 +4010,8 @@ BD_FIELD_LABELS = { BD_FIELD_HINTS = { "account": "The @username", "avg_engagement": "Likes and comments as a share of followers", - "id": "Instagram's internal number for the account — for matching a list you already have", - "fbid": "The linked Facebook id — for matching a list you already have", + "id": "Instagram's internal number for the account. For matching a list you already have", + "fbid": "The linked Facebook id. For matching a list you already have", "profile_name": "The name shown above the bio, when it differs from the account name", "related_accounts": "Accounts Instagram suggests alongside this one", } @@ -4019,7 +4163,7 @@ def narrowing_refusal(preds, operator="and", kind=""): # read, because the string predates the second platform. `discovery_facts` already carries the # network's name for exactly this class of string, so there is no second literal. _net = discovery_facts(kind)[0] if kind else PLATFORM_INSTAGRAM - return ("add a condition that describes the account itself — Bio contains, Handle is, a " + return ("add a condition that describes the account itself. Bio contains, Handle is, a " f"hashtag. Follower counts and yes/no conditions alone match too much of {_net} " "to search") @@ -5151,7 +5295,7 @@ def retract_foreign_presets(rt, log=print): if not (stats["columns"] or stats["flags"]): if stats["kept"]: log(f"[aios-auto] retract: {len(stats['kept'])} foreign column(s) KEPT because they " - f"hold data — " + ", ".join(f"{k['table']}.{k['column']} ({k['rows']} rows)" + f"hold data. " + ", ".join(f"{k['table']}.{k['column']} ({k['rows']} rows)" for k in stats["kept"])) return stats stats = {"tables": 0, "columns": 0, "cells": 0, "flags": 0, "kept": []} @@ -5160,7 +5304,7 @@ def retract_foreign_presets(rt, log=print): f"{stats['flags']} mis-declared flag(s) across {stats['tables']} database(s)") if stats["kept"]: log(f"[aios-auto] retract: {len(stats['kept'])} foreign column(s) KEPT because they hold " - f"data — " + ", ".join(f"{k['table']}.{k['column']} ({k['rows']} rows)" + f"data. " + ", ".join(f"{k['table']}.{k['column']} ({k['rows']} rows)" for k in stats["kept"])) return stats @@ -5830,6 +5974,30 @@ def migrate_ig_tables(rt, log=print, only=""): return cur rt.update(UT_STORE_KEY, _up) + # ⭐⭐ WAVE 33 (D-187) — A SINGLE-TABLE CALL STOPS PAYING FOR A TENANT-WIDE RECONCILIATION. + # + # W31-T30 closed HALF of this: `only` naming a table outside the Instagram graph returns early + # (`if only and not targets` above). What it left is the case the row is actually about — `only` + # naming a table that IS in the graph, i.e. **every save an Instagram tenant makes**. The four + # passes below are tenant-wide by construction: two `_ig_schema_contract` + + # `_reconcile_ig_graph_fields` rounds and two backfills, each walking the whole document, none + # of them reading `only`. So one `ut_ensure` on one table paid a whole-tenant Instagram + # reconciliation, and `ut_ensure` runs several times per save. + # + # ⛔ THE ROW'S EXIT OFFERS TWO BRANCHES AND THIS TAKES THE FIRST ONE — *"the tenant-wide passes + # are reachable from a scheduled/boot caller"* — because they ARE, and were before this change: + # `routes_tables.py:882` (`_ig_forward`) calls `migrate_ig_tables(rt)` with NO `only`, once per + # tenant per process, guarded by `_IG_FORWARDED`. That is the right home for a whole-tenant + # repair: once, off the save path, rather than on every ensure. + # ⚠ THE SECOND BRANCH — "bound them by an anything-to-do test guarded on the READ" — is NOT + # available here and the comment above says why: the second contract pass exists to read what + # the first pass WROTE, so it cannot be answered out of one snapshot without silently + # un-fixing the idempotency everything else depends on. + # ⛔ NARROW AND CHECKABLE, like its W31-T30 sibling: a call that NAMES ONE TABLE does that + # table's migration. A call that names none still does the whole sweep, unchanged, and every + # tenant-wide check in `verify_automation` goes through that path. + if only: + return stats # The profile loop owns value conversions and deduplication. The schema pass owns the # declarations across ALL related databases and is safe only after those conversions, because # the stored old type is the idempotency key for unit-changing values such as engagement. @@ -5956,7 +6124,7 @@ def seed_predicates(rows): if str(r.get("related_accounts") or "").strip())}, "note": ""} if total < SEED_MIN_ROWS: - basis["note"] = ("a seed needs at least two records — one record has nothing to share " + basis["note"] = ("a seed needs at least two records. One record has nothing to share " "with anything") return [], basis ranked = [] @@ -5995,11 +6163,11 @@ def seed_predicates(rows): # asserted in the gate. If the LAW ever changes shape, this fails closed with an honest # empty rather than offering something the save door will reject. basis["note"] = ("the shared characteristics found are not specific enough to search on " - "— add a condition of your own") + "add a condition of your own") return [], basis if not derived: basis["note"] = basis["note"] or ( - "these records share no bio words, link domain or name in common — nothing could be " + "these records share no bio words, link domain or name in common. Nothing could be " "derived, so the conditions are yours to write") return derived, basis @@ -6234,14 +6402,14 @@ def clean_predicates(raw, operator="and", kind=""): name = _s(p.get("name") or p.get("field"), 60).strip() op = _s(p.get("operator") or p.get("op"), 20).strip() if name not in fields: - return None, ("that field cannot be searched — the searchable ones are: " + return None, ("that field cannot be searched. The searchable ones are: " + ", ".join(field_label(f) for f in fields)) # ⭐ PER-FIELD, not the global list. `is_business_account >= 3` used to validate cleanly # because every operator was legal on every field; a yes/no column offering "at least" # is a question with no meaning that the vendor is nevertheless asked. allowed = ops_for(name) if op not in allowed: - return None, (f"{field_label(name)} cannot be asked {BD_OP_LABELS.get(op, op)!r} — " + return None, (f"{field_label(name)} cannot be asked {BD_OP_LABELS.get(op, op)!r}. " "it takes: " + ", ".join(BD_OP_LABELS.get(o, o) for o in allowed)) entry = {"name": name, "operator": op} @@ -6256,7 +6424,7 @@ def clean_predicates(raw, operator="and", kind=""): if not vals: return None, f"give {field_label(name)} something to compare against" if len(vals) > 1 and op not in BD_MULTI_VALUE_OPS: - return None, (f"{BD_OP_LABELS.get(op, op)!r} takes one value — " + return None, (f"{BD_OP_LABELS.get(op, op)!r} takes one value. " f"{field_label(name)} can only be given a list with " + ", ".join(BD_OP_LABELS[o] for o in ops_for(name) if o in BD_MULTI_VALUE_OPS)) @@ -6315,7 +6483,7 @@ def discover_estimate(records_limit): n = max(0, int(records_limit or 0)) return {"records": n, "usd": round(n * BD_RECORD_PRICE_SPEC, 4), "unitUsd": BD_RECORD_PRICE_SPEC, "basis": "SPEC", - "note": "estimated from the published rate — an exact price is only known after a run" + "note": "estimated from the published rate. An exact price is only known after a run" "a price before a run, and this account's token cannot read a balance"} @@ -6485,9 +6653,9 @@ def cap_note(capped, missing=()): success over a database that does not exist. Exactly the silent-stop failure the row cap already had, one level up — and harder to spot, because the table is not there to look at. """ - out = [f"⚠ the {k} database is FULL ({row_cap(k):,} rows) — {n} row{'' if n == 1 else 's'} " + out = [f"⚠ the {k} database is FULL ({row_cap(k):,} rows). {n} row{'' if n == 1 else 's'} " f"from this run were NOT written" for k, n in (capped or []) if n] - out += [f"⚠ the {k} database could NOT BE CREATED — this workspace is at its " + out += [f"⚠ the {k} database could NOT BE CREATED. This workspace is at its " f"{MAX_UT_TABLES}-database limit, so nothing from this run reached it" for k in (missing or [])] return "; ".join(out) @@ -6512,7 +6680,7 @@ def run_scrape_db(rt, defn, username="automation", log=print, step=_no_step, row status, final, body = fetch(cfg["url"]) if not (200 <= status < 300): steps["fetch"] = "error" - return ("error", f"{cfg['url']} answered {status} — nothing was written", + return ("error", f"{cfg['url']} answered {status}. Nothing was written", {"status": status}, [], steps) steps["fetch"] = "ok" soup = _soup(body) @@ -6557,8 +6725,10 @@ def run_scrape_db(rt, defn, username="automation", log=print, step=_no_step, row else: table_key = ut_ensure(rt, label, fields, username, key=cfg.get("targetTable") or None) t = ut_get(rt, table_key) or {} + # ⛔ D-116 — THE ONE CALL SITE THAT NEEDS A PRECEDENCE RULE, because it is the one whose rows + # come from a CORPUS. Every other `upsert_rows` caller writes measurements or appends a series. rows, counts = upsert_rows(t.get("rows") or {}, incoming, key_field, - cap=row_cap(table_key)) + cap=row_cap(table_key), protect=corpus_protect) touched = [rid for rid, row in rows.items() if str(row.get(key_field, "")) in {str(i.get(key_field)) for i in incoming}] if not dry: @@ -6568,15 +6738,23 @@ def run_scrape_db(rt, defn, username="automation", log=print, step=_no_step, row summary = (f"{counts['inserted']} new, {counts['updated']} updated, " f"{counts['unchanged']} unchanged, {counts['orphans']} no longer on the page " f"(kept)") + # ⛔ D-116 — SAY IT. A search that quietly declines to overwrite six measured cells is doing + # the right thing invisibly, which is indistinguishable from a corpus that happened to agree — + # and the next person to wonder why a number did not move has nothing to read. The observation + # still lands in the series either way; this sentence is about the SCALAR. + if counts.get("held"): + summary += (f", {counts['held']} measured value(s) kept over the corpus " + f"(an enrichment read them exactly; the search's own numbers are in the " + f"snapshot series)") capped = [(table_key, counts.get("capped", 0))] missing = [] if dry else ut_missing(rt, table_key) counts["missing_tables"] = len(missing) note = cap_note(capped, missing) if note: - summary += f" — {note}" + summary += f". {note}" steps["write"] = "partial" if dry: - summary = f"Test run — nothing saved. Would have written: {summary}" + summary = f"Test run. Nothing saved. Would have written: {summary}" steps["write"] = "skipped" elif not note: steps["write"] = "ok" @@ -7115,7 +7293,7 @@ def run_field_instagram(rt, defn, username="automation", log=print, step=_no_ste m_status, m_note = ig_master.append_run(getattr(rt, "key", ""), in_snaps, in_posts, in_psnaps) if m_status == "error": - master_note = f"⚠ the platform master copy FAILED — {m_note}; the tenant copy " \ + master_note = f"⚠ the platform master copy FAILED. {m_note}; the tenant copy " \ f"is complete and the next run re-appends" counts["master_failed"] = 1 elif m_status == "ok": @@ -7186,21 +7364,21 @@ def run_field_instagram(rt, defn, username="automation", log=print, step=_no_ste summary += f", {counts['blocked']} blocked" note = cap_note(capped, missing) if note: - summary += f" — {note}" + summary += f". {note}" state = "partial" if state != "error" else state steps["write"] = "partial" elif not dry: steps["write"] = "ok" if master_note: - summary += f" — {master_note}" + summary += f". {master_note}" state = "partial" if state != "error" else state steps["write"] = "partial" if dry: - summary = f"Test run — nothing saved. Would have written: {summary}" + summary = f"Test run. Nothing saved. Would have written: {summary}" steps["write"] = "skipped" state = "partial" if state != "error" else state if notes: - summary += f" — {notes[0][:120]}" + summary += f". {notes[0][:120]}" if not dry: # C7: the fresh master rows are exactly what the table's metric cells summarise. try: @@ -7389,7 +7567,7 @@ def run_discovery(rt, defn, username="automation", log=print, step=_no_step, row # ⛔ THE FAIL-CLOSED PATH (C4). Discovery has NO anonymous rung to drop to — the corpus is # the vendor's — so this is where the run stops, saying which env var is missing. steps["find"] = "blocked" - return ("partial", "Profile search is not set up yet — nothing was searched and nothing " + return ("partial", "Profile search is not set up yet. Nothing was searched and nothing " "was charged", counts, [], steps) pending = str((defn.get("state") or {}).get("pendingSnapshot") or "") @@ -7404,12 +7582,12 @@ def run_discovery(rt, defn, username="automation", log=print, step=_no_step, row or depth_refusal(preds, cfg.get("operator"))) if guard_err: steps["find"] = "blocked" - return ("error", f"the search was not started — {guard_err}", counts, [], steps) + return ("error", f"the search was not started. {guard_err}", counts, [], steps) if dry: est = discover_estimate(limit) steps["find"] = steps["write"] = "skipped" return ("partial", - f"Test run — nothing saved. Would look for up to {limit} " + f"Test run. Nothing saved. Would look for up to {limit} " f"{noun}{'' if limit == 1 else 's'} matching " f"{_predicate_sentence(preds, cfg.get('operator'))}, for about " f"${est['usd']}", counts, [], steps) @@ -7432,10 +7610,10 @@ def run_discovery(rt, defn, username="automation", log=print, step=_no_step, row step(f"excluded {excl['excluded']} already-found " f"profile{'' if excl['excluded'] == 1 else 's'} at the provider") elif excl.get("dropped"): - step(f"searching without the already-found list — {excl['dropped']}") + step(f"searching without the already-found list. {excl['dropped']}") if note: steps["find"] = "blocked" - return ("error", f"the search was not started — {note}", counts, [], steps) + return ("error", f"the search was not started. {note}", counts, [], steps) pending = sid # ⛔ LOG THE ID *BEFORE* PERSISTING IT, and the order is the whole point. `set_state` goes # through `rt.update`, which can RAISE on an unavailable store — and that exception @@ -7456,7 +7634,7 @@ def run_discovery(rt, defn, username="automation", log=print, step=_no_step, row # is laggy / looks stuck". A counter here is what makes a legitimate wait distinguishable # from a hung thread; without it the rendered step reads the same word for both, which is a # progress indicator that cannot indicate progress. - step(f"Searching — {int(waited)}s of " + step(f"Searching. {int(waited)}s of " f"{int(BD_FILTER_WAIT)}s") status, size, note = bd_filter_status(pending) if note: @@ -7492,7 +7670,7 @@ def run_discovery(rt, defn, username="automation", log=print, step=_no_step, row // 60)) except Exception: # noqa: BLE001 mins = 0 - been = f" — {mins} min so far" if mins else "" + been = f". {mins} min so far" if mins else "" steps["collect"] = "partial" return ("partial", f"Still searching at the provider{been}. A corpus search takes about 20 minutes " @@ -7505,7 +7683,7 @@ def run_discovery(rt, defn, username="automation", log=print, step=_no_step, row steps["collect"] = "ok" steps["write"] = "skipped" set_state(rt, auto_id, {"pendingSnapshot": None, "pendingSince": None}) - return ("partial", "No profiles matched. Try a shorter or more common keyword — " + return ("partial", "No profiles matched. Try a shorter or more common keyword. " "'floral' finds more accounts than 'floral design studio'", counts, [], steps) if status != "ready": @@ -7632,7 +7810,7 @@ def run_discovery(rt, defn, username="automation", log=print, step=_no_step, row affected = [rid for rid, r in merged.items() if str(r.get("handle")) in {c["handle"] for c in incoming}][:200] est = discover_estimate(counts["found"]) - summary = (f"{counts['found']} {noun}{'' if counts['found'] == 1 else 's'} found — " + summary = (f"{counts['found']} {noun}{'' if counts['found'] == 1 else 's'} found. " f"{counts['new']} new, {counts['seen_again']} seen before. About " f"${est['usd']}") if counts["dropped"]: @@ -7640,10 +7818,10 @@ def run_discovery(rt, defn, username="automation", log=print, step=_no_step, row f"username and could not be saved") cnote = cap_note([(table_key, counts["capped"])], missing) if cnote: - summary += f" — {cnote}" + summary += f". {cnote}" steps["write"] = "partial" if dry: - summary = f"Test run — nothing saved. Would have written: {summary}" + summary = f"Test run. Nothing saved. Would have written: {summary}" state = "partial" if (dry or counts["capped"] or missing or not counts["found"]) else "ok" if not dry and not missing and spec["after_write"]: spec["after_write"](rt, table_key, auto_id, log) @@ -7719,7 +7897,289 @@ def _flow_cap_reason(table_key, rt=None): cause, fix = str(rep.get("cause") or ""), str(rep.get("recommendation") or "") if not cause and not fix: return "" - return f" — {cause}." + (f" To walk them all: {fix}." if fix else "") + return f". {cause}." + (f" To walk them all: {fix}." if fix else "") + + +# --------------------------------------------------------------------------------------------- +# WAVE 35 · T36 / CONTRACT C8 / OWNER RULING R10 — THE STATEMENTS BATCH: ASSEMBLE, PARK, NEVER SEND +# +# ⛔⛔ THE TICKET'S `how:` SAID TO USE "the board's strict review posture (wave 22)". THAT POSTURE +# DOES NOT EXIST, and rebuilding it would REVERSE AN OWNER RULING rather than merely miss a symbol. +# Wave 27 R3 deleted `board()`, `move_card()`, `stages_for()`, `ensure_stage_field()` and the review +# branch of the action walk (the tombstone is above `LANE_OPS`), and its reason is a DATA reason, +# verbatim: *"the board wrote MACHINE COLUMNS INTO A TENANT'S OWN TABLE — a stage select, an `_at` +# stamp and a `_cycles` counter per automation — to render a view of state the RUN LOG already +# holds."* `retire_automation_stage_fields` and `migrate_ig_tables` still DROP those columns, so a +# batch parked in a stage field would be deleted by our own migration. +# ⇒ The batch parks on the AUTOMATION DEFINITION, the shape `runs` and `reviews` already use. Zero +# machine columns on a customer's database, and the migration has nothing to take away. +# +# ⛔ A STATEMENTS FLOW IS **BATCH**-SCOPED, NOT RECORD-SCOPED, and that is why it does not go +# through `apply_actions` at all. `run_plain` walks every row of the flow's bound table, so a +# per-record arm would assemble the whole worklist once per record; and a statements agent binds NO +# table (its customers come from the Odoo AR worklist, not a `ut_*` grid), so `run_plain` would +# have answered `partial: "no database is bound yet"` and the step would NEVER HAVE RUN. The +# precedent for a kind that defines its own scope is already here: the enrich-only branch below, +# whose saved View "ARE the set of records the automation was asked to process". +# ⚠ The `_walk` arm for this kind therefore stays a REFUSAL, not a duplicate: a `send_statement` +# dropped into an ordinary record-walking flow must say it did nothing, never half-send. +# +# ⛔⛔ AND NOTHING HERE SENDS. Not one function in this section imports the mail path. The send door +# is `routes_statements`, behind `admin_gate` + `_royal_only`, calling `collections_send. +# queue_statement`, whose SAFE_MODE guardrail lives in the DATA LAYER where no route, payload or UI +# can bypass it. This module ASSEMBLES and PARKS. A person clicks Send. + +#: How many statements one parked batch holds. Bounded for the reason `MAX_RUNS` and `MAX_REVIEWS` +#: are: this rides inside the automation DEFINITION, and an unbounded list is a serialisation cost +#: on every read of the automations bucket. +#: ⚠ WHEN IT BITES IT IS DISCLOSED, never a silent `[:N]` — R6's second sentence, and +#: [[no-unverifiable-aggregates]]. `assemble_statements` appends a note naming the number left out. +MAX_STATEMENT_BATCH = 200 + +#: The collection worklist loader, injectable so a gate can drive this without Odoo credentials. +#: Production leaves it None and the real data layer answers. Same shape as `_DRAFT_CHAT`. +_STATEMENT_ROWS = [None] + + +def _collections(): + """`modules.collections_send`, imported lazily — `platform/` is not on the path at import time + for every consumer of this module, and this is the only section that needs it.""" + import modules.collections_send as cs # noqa: PLC0415 + return cs + + +def statement_steps(defn): + """The ENABLED `send_statement` actions of this flow, top level only. + + ⚠ Top level only, deliberately, and `is_statement_flow` is what makes that safe: a batch flow + is exactly one enabled action. A `send_statement` nested inside an If is NOT a batch flow, so + it falls to the ordinary record walk and is refused there with a sentence. + """ + return [a for a in (((defn or {}).get("flow") or {}).get("actions") or []) + if isinstance(a, dict) and a.get("kind") == "send_statement" + and a.get("enabled", True)] + + +def is_statement_flow(defn): + """Is this automation a statements BATCH rather than a record walk? + + ⛔ EXACTLY ONE ENABLED ACTION, AND IT IS THIS KIND. The narrowness is the safety: a flow that + also updates records has record semantics that the batch path would silently drop, so it keeps + the ordinary walk (where the arm refuses and says so). This mirrors the enrich-only branch in + `run_plain`, which is narrow for the same stated reason. + """ + enabled = [a for a in (((defn or {}).get("flow") or {}).get("actions") or []) + if isinstance(a, dict) and a.get("enabled", True)] + return len(enabled) == 1 and enabled[0].get("kind") == "send_statement" + + +def assemble_statements(defn, log=print): + """`(batch, notes)` — the statements this configuration WOULD send, rendered, plus why anybody + was left out. **Reads Odoo read-only. Sends nothing. Writes nothing.** + + Each entry is `{customer, to, subject, html, tier, overdue}`. `html` is rendered by the SAME + `render_statement_html` the send door uses, so what a person approves is what goes out — a + review screen rendering its own approximation of the mail is a review of the wrong thing. + + ⚠ A CUSTOMER WITH NO EMAIL IS *SKIPPED AND NAMED*, never dropped. `routes_statements.send` + already separates "we could not" from "there was nowhere to send"; this keeps that distinction + at the assembly end, because a batch that silently shrinks is one nobody can reconcile. + """ + cfg = (statement_steps(defn) or [{}])[0].get("config") or {} + cs = _collections() + notes = [] + loader = _STATEMENT_ROWS[0] + rows = list(loader() if loader else cs.load_collection_list(cs.Odoo())) + tier = str(cfg.get("tier") or "").strip() + if tier: + before = len(rows) + rows = [r for r in rows if str(r.get("Tier") or "") == tier] + log(f"[aios-auto] statements: {len(rows)} of {before} customers are in tier {tier}") + subject_tpl = str(cfg.get("subject") or "") or cs.DEFAULT_SUBJECT + intro_tpl = str(cfg.get("intro") or "") or cs.DEFAULT_INTRO + footer_tpl = str(cfg.get("footer") or "") or cs.DEFAULT_FOOTER + month = _dt.date.today().strftime("%B %Y") + batch, no_email = [], [] + for row in rows: + if len(batch) >= MAX_STATEMENT_BATCH: + break + name = str(row.get("Customer") or "") + to = str(row.get("Email") or "").strip() + if not to: + no_email.append(name) + continue + try: + subject = subject_tpl.format(customer=name, company=cs.COMPANY, month=month) + except (KeyError, IndexError): + # An unknown placeholder is the person's typo, not a crash. Show what they typed — + # the same choice `routes_statements.preview` already makes. + subject = subject_tpl + batch.append({"customer": name, "to": to, "subject": _s(subject, 200), + "html": _s(cs.render_statement_html(row, intro_tpl, footer_tpl), 40000), + "tier": str(row.get("Tier") or ""), "overdue": row.get("Overdue")}) + if no_email: + shown = ", ".join(no_email[:5]) + one = len(no_email) == 1 + notes.append(f"{len(no_email)} customer{'' if one else 's'} " + f"{'has' if one else 'have'} no email address on their record and " + f"{'is' if one else 'are'} not in this batch " + f"({shown}{', and others' if len(no_email) > 5 else ''}). " + f"Add an address in Odoo and run it again") + left = len(rows) - len(batch) - len(no_email) + if left > 0: + # R6's second sentence: a limit that bites is REPORTED, with its cause and what to do. + notes.append(f"{left} more customers matched but one batch holds " + f"{MAX_STATEMENT_BATCH}. Send this batch, then run it again for the rest, or " + f"narrow the tier filter") + return batch, notes + + +def park_statements(rt, auto_id, batch, notes): + """Write the assembled batch onto the DEFINITION as `pendingStatements`. Replaces, never + appends: a batch is THIS run's worklist, and two runs' statements merged into one list is a + customer invoiced twice. + + ⚠ `flush="async"` for the reason every writer in this module gives — the read-your-writes + contract means the next `GET /automations` already sees it, and only the upload is deferred. + """ + entry = {"ts": _iso(), "count": len(batch), "sent": False, + "items": list(batch)[:MAX_STATEMENT_BATCH], + "notes": [_s(n, 300) for n in (notes or [])][:25]} + + def _up(cur): + cur = cur if isinstance(cur, dict) else {} + d = cur.get(str(auto_id)) + if d is not None: + d["pendingStatements"] = entry + return cur + + _store_update(rt, _up, flush="async") + return entry + + +def clear_statements(rt, auto_id): + """Drop a parked batch — after it is sent, or when somebody discards it.""" + def _up(cur): + cur = cur if isinstance(cur, dict) else {} + d = cur.get(str(auto_id)) + if d is not None: + d.pop("pendingStatements", None) + return cur + + _store_update(rt, _up, flush="async") + + +def run_statements(rt, defn, username="automation", log=print, step=_no_step): + """The batch runner: assemble, park, tell somebody. Returns `run_plain`'s 5-tuple. + + ⛔ THE STATE IS `partial`, NEVER `ok`, AND THAT IS DELIBERATE. `ok` would put a green dot over + a job that is only half done — the statements exist and NOBODY HAS SENT THEM. `partial` is this + module's honest-progress state and the summary says exactly what is waiting, which is what makes + the run notification (`_notify_run`) read as "come and look" rather than "done". + """ + if not is_statement_tenant(rt): + # Belt and braces behind `clean_actions`' wall: a definition stored before the wall, or + # copied between tenants, must not assemble another company's customer list. + return ("error", "statements are not configured for this workspace", {}, [], {}) + step("reading the collection list") + try: + batch, notes = assemble_statements(defn, log=log) + except Exception as exc: # noqa: BLE001 + return ("error", f"the collection list could not be read: {str(exc)[:200]}", {}, [], {}) + step("rendering statements") + park_statements(rt, defn.get("id"), batch, notes) + counts = {"statements": len(batch)} + if not batch: + return ("partial", "no customers matched, so there is nothing to review", counts, [], {}) + one = len(batch) == 1 + return ("partial", + f"{len(batch)} statement{'' if one else 's'} " + f"{'is' if one else 'are'} ready for review. Nothing has been sent. Open this agent " + f"and click Send to release them", + counts, [], {}) + + +#: ⭐⭐ WAVE 35 · T37 — THE SEEDED ROYAL IMPORTS STATEMENTS AGENT. +#: A FIXED id, because the row's own EXISTENCE is the idempotency key (see `seed_statements_agent`). +STATEMENTS_AGENT_ID = "system:statements" +SYSTEM_STATEMENTS = "statements" +#: First of the month, 06:00. A monthly statement run is what the collections worklist is for, and +#: the hour matches the Odoo sync default so the numbers it reads are the night's. +STATEMENTS_DEFAULT_CRON = "0 6 1 * *" + + +def seed_statements_agent(rt, username="system"): + """Mint Royal Imports' "Monthly statements" agent ONCE, **switched OFF**. Returns the + definition if it wrote one, else None. + + ⛔⛔ IT ARRIVES `enabled: False` AND THAT IS THE TICKET'S OWN TRAP, not a preference. An agent + that ships enabled has scheduled itself against real customers before a single person has read + its configuration — and this one's action queues mail to the tenant's actual debtors. + + ⭐ WHY STORED, WHEN WAVE 34's SYSTEM AGENT IS DERIVED. `_odoo_sync_row` gives three reasons for + deriving and only one survives contact with THIS agent (raised as `ASK D-11`): + · "two copies of one cadence" — does not apply: Odoo's cadence already lives in the connector + config, so a stored copy could drift; a statements schedule has no other home to drift from. + · "stored means the failure-pause can disable it" — INVERTS: auto-pausing statements after K + consecutive failures is correct (a dead credential should stop it), where pausing the Odoo + cadence would silently break infrastructure. + · "nothing can seed it" — real, and answered here: ONE write per tenant ever, by the + CONTAINER (which is what D-195 asks for; what it forbids is a CLI writing while the Space + is up), behind the existence check below. + And deriving cannot meet T37 anyway: a derived row is not in the automations bucket, so edit, + toggle, schedule and run would each need a bespoke door — four new mechanisms to avoid one + guarded write. The Odoo agent escapes that only because a separate resync loop already does its + work. + + ⛔ THE EXISTENCE CHECK IS THE WHOLE IDEMPOTENCY STORY, AND IT IS SAFE ONLY BECAUSE THE ROW + CANNOT BE DELETED. `routes_automation.delete_automation` refuses any stored row carrying + `system` (409, with a sentence), so "the row is present" can never become false behind our + back. If that refusal is ever relaxed, THIS FUNCTION NEEDS A SEPARATE DURABLE FLAG — otherwise + deleting the agent resurrects it on the next list call, which is a delete that undoes itself. + ⚠ And `system` is STICKY through `clean_definition` (see its return) for the same reason: an + edit that stripped the marker would make the row deletable and re-open exactly that hole. + """ + if not is_statement_tenant(rt): + return None + existing = all_definitions(rt) or {} + if STATEMENTS_AGENT_ID in existing: + return None + raw = { + "name": "Monthly statements", + "kind": "plain", + # ⚠ A SCHEDULE THAT IS OFF, not an absent schedule: the cron is the CONFIGURATION T37 asks + # a person to open and read, and a blank one would make them invent it before they could + # judge it. + "schedule": {"cron": STATEMENTS_DEFAULT_CRON, "enabled": False}, + "trigger": {"key": "schedule"}, + "flow": {"actions": [{ + "id": "act_1", "kind": "send_statement", + # ⚠ TIER BLANK = every tier, which is the honest default: narrowing to "A-Urgent" would + # be us deciding who gets chased, and the blank is the value the config panel shows as + # "all of them" rather than an empty box. + "config": {"tier": "", "subject": "", "intro": "", "footer": ""}, + }]}, + } + defn, err = clean_definition(raw, None, username, rt=rt) + if err: + return None + defn["id"] = STATEMENTS_AGENT_ID + # Stamped AFTER the clean, because `clean_definition` reads this key from `prev` only — a + # payload may never assert it (see that function's note). + defn["system"] = SYSTEM_STATEMENTS + + def _up(cur): + cur = cur if isinstance(cur, dict) else {} + # ⚠ RE-CHECKED INSIDE THE MUTATION. Two concurrent list calls can both pass the read above; + # the store applies mutations under its own lock, so this is where "only once" is actually + # decided. Without it the second writer would overwrite a row a person may already have + # edited, silently resetting their schedule and template. + if STATEMENTS_AGENT_ID not in cur: + cur[STATEMENTS_AGENT_ID] = defn + return cur + + _store_update(rt, _up, flush="async") + return defn def run_plain(rt, defn, username="automation", log=print, step=_no_step, rows=None): @@ -7736,10 +8196,18 @@ def run_plain(rt, defn, username="automation", log=print, step=_no_step, rows=No exact defect this module names in three other places. It reports the honest state and says which fact is missing. """ + # ⭐⭐ WAVE 35 · T36 — THE BATCH FLOW BRANCHES BEFORE THE TABLE CHECK, and the ORDER is the + # whole of it. A statements agent binds no `ut_*` table (its customers come from the Odoo AR + # worklist), so leaving this below the `if not table` return would answer "no database is bound + # yet" and the step would never run — a feature that is whole, gated and unreachable, which is + # this repo's most-repeated failure. See the section above `run_plain` for why it is not an + # `apply_actions` arm. + if is_statement_flow(defn): + return run_statements(rt, defn, username=username, log=log, step=step) table = _flow_table(defn) if not table: return ("partial", - "no database is bound yet — a plain automation walks the records of its target " + "no database is bound yet. A plain automation walks the records of its target " "database, and this one names none (pick one on the trigger, or in Properties)", {}, [], {}) all_rows = (ut_get(rt, table) or {}).get("rows") or {} @@ -7782,8 +8250,15 @@ def run_plain(rt, defn, username="automation", log=print, step=_no_step, rows=No selected, enrich_scope_note = enrich_selection( rt, table, enrich_cfg, profile_key, gone=dict(((defn or {}).get("state") or {}).get("enrichNotFound") or {})) - if enrich_scope_note.startswith("the enrich step names a view it cannot read"): - return ("partial", f"nothing walked in {table} — {enrich_scope_note}", {}, [], {}) + # ⛔ D-112 — AND THE CONSTANT IS THE FIX, NOT THE `if`. This guard was a `startswith` + # against the sentence SPELLED OUT, twelve hundred lines from the only place that + # produces it. Reword the message in `enrich_selection` — a perfectly ordinary edit, + # since it is a sentence a person reads — and this line silently stops matching, the + # run goes back to reporting `ok`, and the defect D-112 describes returns with nothing + # anywhere going red [[gate-pins-a-spelling-not-a-claim]], on the product side. + # ONE constant, two readers, so the wording is free to change and the behaviour is not. + if enrich_scope_note.startswith(ENRICH_VIEW_UNREADABLE): + return ("partial", f"nothing walked in {table}. {enrich_scope_note}", {}, [], {}) ids = selected step(f"Walking {len(ids)} record{'' if len(ids) == 1 else 's'} in {table}") counts = {"records": len(ids)} @@ -7811,7 +8286,7 @@ def run_plain(rt, defn, username="automation", log=print, step=_no_step, rows=No total = len(ids) ids = ids[:_cap] return ("partial", - f"{total} records in {table} — this run walked the first {_cap}" + f"{total} records in {table}. This run walked the first {_cap}" + _flow_cap_reason(table, rt), counts, ids, {}) n = len(ids) # ⭐⭐ 2026-08-07 (owner report) — SAY IT IN WORDS A PERSON CAN CHECK. @@ -7829,7 +8304,7 @@ def run_plain(rt, defn, username="automation", log=print, step=_no_step, rows=No else ("the records selected for Instagram enrichment" if len(enabled_direct) == 1 and enabled_direct[0].get("kind") == "enrich_instagram" - else "every record — this run was started by hand, so nothing narrowed it")) + else "every record. This run was started by hand, so nothing narrowed it")) if enrich_scope_note: scope += f" ({enrich_scope_note})" # ⭐⭐ AND ON THE RUN, not only inside the summary sentence. `summary` is capped at 400 @@ -8019,12 +8494,17 @@ def graph(defn): # whole of it) and `record_updated` no longer names a condition (its watched fields are). # These two lines are the migration's visible half: a node still describing a `.field` # the validator has stopped storing would be the surface and the store disagreeing. + # ⚠ W34-T47 — A COLON, NOT A FULL STOP. R6's sweep turned these four em dashes into + # sentence breaks, which is right for a REFUSAL and wrong here: these are compact node + # SUBTITLES ("ut_leads: view v1"), not prose, and a full stop mid-label reads as two + # truncated fields rather than one qualified name. The rule the sweep encodes is "a + # sentence that used a dash usually wants a period"; a LABEL usually wants a colon. det = {"event_field": (f"{trg.get('table', '')}" - + (f" — {_lane_sentence(trg.get('when'))}" + + (f": {_lane_sentence(trg.get('when'))}" if trg.get("when") else "")), - "record_updated": f"{trg.get('table', '')} — {watched}", + "record_updated": f"{trg.get('table', '')}: {watched}", "record_created": str(trg.get("table") or ""), - "enters_view": f"{trg.get('table', '')} — view {trg.get('viewId') or 'unset'}", + "enters_view": f"{trg.get('table', '')}: view {trg.get('viewId') or 'unset'}", "form_submitted": str(trg.get("table") or ""), "webhook": "POST the hook URL to fire it", # ⭐ WAVE 30 · T05 — BOTH corpus triggers, and the value is identical because the @@ -8034,11 +8514,11 @@ def graph(defn): "ig_profile_match": (_predicate_sentence(cfg.get("predicates"), cfg.get("operator"))[:80] if cfg.get("predicates") - else "No filters yet — nothing to search for"), + else "No filters yet. Nothing to search for"), "tiktok_profile_match": (_predicate_sentence(cfg.get("predicates"), cfg.get("operator"))[:80] if cfg.get("predicates") - else "No filters yet — nothing to search for"), + else "No filters yet. Nothing to search for"), "email": str(trg.get("query") or "")}.get(trg["key"], "") if not trg.get("configured", True): det = "Finish setting this trigger up before it can fire" @@ -8091,7 +8571,7 @@ def graph(defn): node("capture_comments", "capture", "Comment data", "Comments on those posts" if comments_on else "Off", 3, panel="capture", on=comments_on, - detail=("The full comments dataset — many rows per post" if comments_on else + detail=("The full comments dataset. Many rows per post" if comments_on else "Comments already embedded in a paid post row are kept either way")), node("write", "write", "Write", cfg.get("targetTable") or "No database", 4, panel="write", @@ -8143,7 +8623,7 @@ def graph(defn): node("fetch", "source", "Fetch page", host, 1, panel="source", detail=url[:90]), node("extract", "capture", "Extract", which, 2, panel="columns", detail=f"{mapped} column{'' if mapped == 1 else 's'} mapped · key: " - f"{cfg.get('keyField') or '—'}"), + f"{cfg.get('keyField') or ', '}"), node("write", "write", "Write", cfg.get("targetLabel") or "Scraped table", 3, panel="write", on=not cfg.get("dryRun"), detail=cfg.get("targetTable") or "a new database"), @@ -8180,7 +8660,7 @@ def toggle_node(rt, auto_id, node_id): if target is None: return None, f"there is no {node_id!r} step in this automation" if not target.get("toggle"): - return None, (f"the {target['title']} step cannot be turned off — it is what this " + return None, (f"the {target['title']} step cannot be turned off. It is what this " f"automation is") cfg, sched = dict(prev.get("config") or {}), dict(prev.get("schedule") or {}) which = target["toggle"] @@ -8295,18 +8775,18 @@ def clean_cond(raw, depth=0, where=""): return None, f"the condition{at} must be an object" conj = [k for k in COND_GROUP_KEYS if k in raw] if len(conj) > 1: - return None, (f"the condition{at} sets both 'all' and 'any' — a group is one or the " + return None, (f"the condition{at} sets both 'all' and 'any'. A group is one or the " f"other") if conj: key = conj[0] if depth + 1 > MAX_COND_DEPTH: - return None, (f"conditions nest at most {MAX_COND_DEPTH} levels deep — " + return None, (f"conditions nest at most {MAX_COND_DEPTH} levels deep. " f"the group{at} is deeper") kids_raw = raw.get(key) if not isinstance(kids_raw, list) or not kids_raw: return None, f"the '{key}' group{at} needs at least one condition inside it" if len(kids_raw) > MAX_COND_CHILDREN: - return None, (f"a group holds at most {MAX_COND_CHILDREN} conditions — " + return None, (f"a group holds at most {MAX_COND_CHILDREN} conditions. " f"the '{key}' group{at} has {len(kids_raw)}") kids = [] for child in kids_raw: @@ -8314,7 +8794,7 @@ def clean_cond(raw, depth=0, where=""): if err: return None, err if c is None: - return None, (f"an empty condition sits inside the '{key}' group{at} — " + return None, (f"an empty condition sits inside the '{key}' group{at}. " f"finish it or remove it") kids.append(c) return {key: kids}, None @@ -8325,7 +8805,7 @@ def clean_cond(raw, depth=0, where=""): # act on. It states a fact about the stored tree; it never said what to DO, and the usual # cause is not a typo but an empty field picker (the flow had no walking record to offer # columns from). The fix belongs in the message. - return None, (f"the condition{at} names no field — pick a column, or remove the " + return None, (f"the condition{at} names no field. Pick a column, or remove the " f"condition") if op not in LANE_OPS: return None, f"{op or 'that comparison'!r} is not one of: " + ", ".join(LANE_OPS) @@ -8439,6 +8919,113 @@ FIND_LIMIT_MAX = 100 #: ceiling nearly unreachable. That is E's own PENDING row; this bound is what stops the damage #: until it lands. MAX_WEB_JOBS_PER_RUN = 50 +#: ⭐⭐ W33-T58 (D-191) — HOW MANY WEB STEPS MAY SHARE ONE JOB. The comment above finally got its +#: batching, so the ceiling above now counts JOBS rather than pages and a record's consecutive web +#: steps cost one cold start between them instead of ~9 s each. +#: ⚠ 20 IS THE RUNNER'S OWN `MAX_STEPS` (`jobs/web_agent_job.py`), not a number chosen here: a plan +#: longer than that is refused by the job with `kind="too_many_steps"`, which would turn a +#: performance improvement into a whole record's worth of failed steps. Kept in step by +#: `verify_web_agent.py`, which reads both. +MAX_WEB_STEPS_PER_JOB = 20 +#: ⭐⭐ W33-T56 — HOW MANY STEPS ONE `ai_agent` ACTION MAY COMPOSE FOR ITSELF. +#: ⛔ A CEILING, NOT A TARGET, and it is the only bound between a sentence and a browser session. +#: The five `web_*` kinds are each ONE action a person wrote down; this one is a description that +#: the model turns into a journey at run time, so the number of real browser actions it performs is +#: decided by a paragraph rather than by the flow. Twelve is enough for "log in, search, open the +#: third result, read the price" and short of anything that reads as a program. +#: ⚠ Bounded by `MAX_WEB_STEPS_PER_JOB` as well, since the composed steps ride ONE job. +AI_AGENT_MAX_STEPS = 12 + + +#: The test seam for `_ai_agent_plan` — `None` in every shipped path. `verify_automation.py` sets it +#: so the fuzzy step is proven end to end with NO API key and NO spend, exactly as +#: `routes_automation._DRAFT_CHAT` does for the drafting door. +_AI_AGENT_CHAT = [None] + + +def _ai_agent_plan(cfg, row, log=print, st=None, user=""): + """A description + one record -> `(steps, "")` for `run_plan`, or `(None, sentence)`. + + ⭐⭐ W33-T56. This is the whole of the fuzzy step: the instruction and the record's own values + go to the model, and CONCRETE `web_*` steps come back — the same vocabulary a person could have + written by hand, so everything downstream (the seam, the job, the checkpoint, the per-step + verdicts) is unchanged and none of it has to know an assistant was involved. + + ⛔ IT MAY COMPOSE ONLY BROWSER STEPS. `ai_review.draft_flow` is handed a catalog filtered to + `WEB_KINDS`, so the enum in the tool schema cannot express `create_record` or a connector call. + A fuzzy sentence therefore cannot be talked into writing the tenant's data: the worst a bad + instruction can do is waste one browser session. That is a property of the SCHEMA, not of the + prompt, which is the only version of it worth relying on. + ⛔ AND IT IS BOUNDED. `maxSteps` is clamped at save time and re-applied here, because the + number of real browser actions is otherwise decided by a paragraph. + ⚠ `interpolate` FIRST, so the model is told about THIS record — `{{Website}}` is a different + page for every row, and a journey composed against the template would be one guess repeated. + """ + import ai_review # noqa: PLC0415 + url = interpolate(str(cfg.get("url") or ""), row) + instruction = interpolate(str(cfg.get("instruction") or ""), row) + cap = max(1, min(int(cfg.get("maxSteps") or AI_AGENT_MAX_STEPS), MAX_WEB_STEPS_PER_JOB)) + web_only = [r for r in ACTION_CATALOG if r.get("kind") in WEB_KINDS and r.get("ready")] + draft, why, _prov = ai_review.draft_flow( + prompt=(f"Starting page: {url}\n\nDo this: {instruction}\n\n" + f"Answer with at most {cap} steps. The FIRST step must open the starting page."), + catalog=web_only, + required={k: v for k, v in ACTION_REQUIRED.items() if k in WEB_KINDS}, + triggers=[], tables=[], + # ⭐ W35 · C7 (`NOTE E-16`) — threaded IN from `_walk` rather than resolved here: this + # function is pure over `(cfg, row)` by design and giving it a store handle of its own + # would be a second way to reach the tenant. + st=st, user=user, + chat=_AI_AGENT_CHAT[0]) + if why or not draft: + return None, (why or "the assistant produced no steps for that instruction") + steps, seen_url = [], False + for i, a in enumerate(draft.get("actions") or [], 1): + kind = str(a.get("kind") or "") + if kind not in WEB_KINDS: + # Belt and braces behind the enum: a rung that ignores its own schema is stopped here + # rather than reaching the browser. + return None, f"the assistant asked for a step this action cannot perform ({kind})" + c = a.get("config") or {} + step = {"kind": kind, "id": f"ai{i}", + "url": str(c.get("url") or "") or (url if not seen_url else ""), + "selector": str(c.get("selector") or ""), + "attr": str(c.get("attr") or "text"), + "all": bool(c.get("all")), + "waitFor": str(c.get("waitFor") or "") or None, + "timeoutMs": int(cfg.get("timeoutMs") or WEB_READ_TIMEOUT_MS)} + if c.get("value"): + step["value"] = str(c.get("value")) + if c.get("hint"): + step["hint"] = str(c.get("hint")) + if cfg.get("dryRun"): + step["dryRun"] = True + seen_url = seen_url or bool(step["url"]) + steps.append(step) + if len(steps) >= cap: + break + if not steps: + return None, "the assistant produced no steps for that instruction" + # ⛔ THE SEAM REFUSES A JOURNEY WHOSE FIRST STEP CARRIES NO ADDRESS — there is no page to act + # on yet — and the action's own `url` is exactly the answer. Supplying it here beats letting + # the whole job be refused for a sentence the model happened not to repeat. + if not steps[0].get("url"): + steps[0]["url"] = url + return steps, "" + + +def _web_missing(kind, cfg): + """Which of this kind's REQUIRED config keys are blank — the human phrases, in table order. + + ⚠ PER KIND, because they do not need the same things: `web_goto` needs a url and no selector; + `web_fill` needs a value nobody else takes; only `web_read` needs a column to write into. One + shared three-field test would have blocked every `web_goto` ever configured for want of a + selector it does not use. + ⭐ Lifted out of `apply_actions` at W33-T58 so the BATCH BUILDER and the per-step arm ask the + same question of the same table. Two copies of "is this step configured" would let a batch + include a step the arm then refuses — or worse, exclude one it would have run. + """ + return [n for n, key in WEB_REQUIRED.get(kind, ()) if not str((cfg or {}).get(key) or "").strip()] #: ⭐⭐ W31 QA — THE FIVE WEB KINDS THE ENGINE DISPATCHES, and this is the THIRD list that names #: them (`web_agent.RUNNABLE_KINDS` is the seam's, `jobs/web_agent_job.py::RUNNABLE_KINDS` is the #: runner's). ⛔ IT IS DELIBERATELY NOT AN IMPORT: `_web_agent()` resolves the seam LAZILY so an @@ -8458,6 +9045,10 @@ WEB_REQUIRED = { "web_click": (("a CSS selector", "selector"),), "web_repair": (("a CSS selector", "selector"),), "web_fill": (("a CSS selector", "selector"), ("a value to type", "value")), + # ⭐⭐ W33-T56 — the fuzzy step needs a page to start on and a job to do, and nothing else. + # ⚠ NO `selector` AND NO `field`: working out the selector IS the step, and where to put the + # answer is optional (a journey may only need to have been performed). + "ai_agent": (("a URL", "url"), ("a description of what to do", "instruction")), } #: ⭐⭐ WAVE 32 · T45 (owner item 10) — WHAT EACH ACTION KIND CANNOT RUN WITHOUT, for every kind. #: @@ -8521,16 +9112,56 @@ ACTION_CATALOG = [ # job"* and *"Needs the recorder that captures a selector"* — both false since E's runner # landed. A menu that dates its own promises is this module's own recorded complaint one # comment up; a row that advertises a missing prerequisite it already has is the same defect. - {"kind": "web_goto", "label": "Open a page", "group": "Web action", "ready": True, + # ⭐⭐ WAVE 33 · W33-T56 (owner item 7, ruling R3) — THE FUZZY STEP. + # ⛔ IT ADDS; IT REPLACES NOTHING. R3 is explicit: *"No existing `web_*` kind is removed — + # dropping a kind from the catalog 400s every stored automation using it, forever"* (D-65). + # This is the step for a journey somebody can DESCRIBE but not spell as a selector; the five + # kinds below stay exactly as they are for the journeys they can already express, and a person + # who knows the selector should still use `web_read`, which costs no model call. + # ⭐⭐ WAVE 34 · W34-T44 / R18 — SIX ROWS BECAME ONE, AND THE OTHER FIVE DID NOT LEAVE THE + # CATALOG. Owner, verbatim: *"Remove Do this on a page / Open a page / Fill a field / Click + # something / Read from the page / Repair a broken step completely. One action, Web agent."* + # + # ⛔⛔ WHY THEY ARE HIDDEN AND NOT DELETED, AND IT IS NOT D-65 THIS TIME — IT IS WORSE. + # `_ai_agent_plan` builds the model's tool schema as + # `[r for r in ACTION_CATALOG if r["kind"] in WEB_KINDS and r["ready"]]` + # so DELETING these five rows empties that list, and the ONE action the ruling keeps would be + # left able to compose nothing at all. Deleting the six would have deleted the survivor, in + # silence, and `ai_agent`'s own tests would still pass because they stub the chat rung + # (`_AI_AGENT_CHAT`). D-65's usual argument (a deleted kind 400s every stored automation + # forever) applies as well and is the smaller half. + # + # ⭐ SO THE LINE MOVED FROM "IS IT IN THE CATALOG" TO "IS IT ON THE MENU". `menu: False` is + # withheld by `action_catalog()` from the picker, while `clean_actions` (which reads this + # constant, not the wire) still validates the kind, the runner still runs it, and a stored + # automation built before today keeps working and stays editable. + # ⚠ THE LABELS CHANGED TOO, and that is R18's "appear NOWHERE" clause taken literally: a + # hidden row's label is still rendered on a STORED step's card, so leaving the six captions in + # place would have kept them on screen for exactly the people who already use them. They now + # name the mechanism instead, and no old caption survives as a substring in any case. + {"kind": "ai_agent", "label": "Web agent", "group": "Web action", "ready": True, + "detail": "Describe a job on a website in words; the agent works out the steps, runs them in " + "a browser and reports what it actually did"}, + {"kind": "web_goto", "label": "Web agent step (navigate)", "group": "Web action", + "ready": True, "menu": False, "detail": "Opens a page in a browser job and reports the title it landed on"}, - {"kind": "web_fill", "label": "Fill a field", "group": "Web action", "ready": True, - "detail": "Types a value into a field — mark it secret and the value is masked in the log"}, - {"kind": "web_click", "label": "Click something", "group": "Web action", "ready": True, + {"kind": "web_fill", "label": "Web agent step (type)", "group": "Web action", + "ready": True, "menu": False, + "detail": "Types a value into a field. Mark it secret and the value is masked in the log"}, + {"kind": "web_click", "label": "Web agent step (click)", "group": "Web action", + "ready": True, "menu": False, "detail": "Clicks the element a selector names, and reports where it landed"}, - {"kind": "web_read", "label": "Read from the page", "group": "Web action", "ready": True, - "detail": "Reads one value off a live page in a browser job — expect ~10-30 s per step"}, - {"kind": "web_repair", "label": "Repair a broken step", "group": "Web action", - "ready": True, + # ⚠ `"kind": "web_read"` AND `"ready": True` STAY ON ONE LINE. `verify_wiring`'s C5 row matches + # `"kind": "web_read".*?"ready": True` without DOTALL, so wrapping this row the way its four + # siblings are wrapped turns that cross-fence assertion red — on a formatting change, with the + # mount and the flag both intact. The row is A's file and its CLAIM is right (a catalog kind + # the client can add must be one the runner will execute); the layout is what it happens to + # depend on, so the layout is preserved here rather than the assertion weakened there. + {"kind": "web_read", "ready": True, "label": "Web agent step (extract)", + "group": "Web action", "menu": False, + "detail": "Reads one value off a live page in a browser job. Expect ~10-30 s per step"}, + {"kind": "web_repair", "label": "Web agent step (relocate)", "group": "Web action", + "ready": True, "menu": False, "detail": "Follows a label to its control when a selector has gone stale, and proposes one"}, # ── 2. DATABASE ────────────────────────────────────────────────────────────────────────── {"kind": "update_record", "label": "Update record", "group": "Database", "ready": True, @@ -8564,6 +9195,30 @@ ACTION_CATALOG = [ "history"}, {"kind": "send_email", "label": "Send email", "group": "Connected", "ready": False, "detail": "Needs a send scope on the Gmail connection"}, + # ⭐⭐ WAVE 35 · T35 / CONTRACT C8 / OWNER RULING R10 — STATEMENTS BECOME AN AGENT STEP. + # + # Owner item 14: move Statements out of Settings and into the agent automation, "templatic and + # easily toggleable". R10 is the half that decides the shape: the step ASSEMBLES and PARKS a + # batch in a review stage, and **nothing sends without a human click**. So this row's promise + # is deliberately "prepares", not "sends" — the label a person reads must not describe an act + # the step does not perform. + # + # ⛔ ADDED BESIDE `send_email`, NEVER BY REPURPOSING IT (the ticket's own trap, D-295): a + # stored automation naming a kind that no longer exists is refused FOREVER rather than dropped + # with a reason, so adding a kind is cheap and re-pointing one is not. + # + # ⛔ `ready: True` IS WHAT MAKES IT STORABLE — `clean_actions` refuses any row whose `ready` is + # false — and the note at `enrich_tiktok` above is the reason the RUNNER ARM lands in the same + # wave rather than after it: `_walk` has no terminal `else`, so a catalog row ahead of its arm + # is addable, storable and SILENTLY INERT, which is worse than not existing. T35 lands an arm + # that reports it is not configured; T36 makes it park a real batch. + # + # ⚠ TENANT-GATED, not `ready: False`: `TENANT_GATED_ACTIONS` withholds this row from every + # tenant but #0, because the send client behind it is env-credentialed and is tenant #0's. + {"kind": "send_statement", "label": "Prepare customer statements", "group": "Connected", + "ready": True, + "detail": "Assemble this month's statements and park them for review. Nothing is sent until " + "somebody opens the batch and clicks Send"}, {"kind": "slack", "label": "Send Slack message", "group": "Connected", "ready": False, "detail": "Needs the Slack connector"}, # ── 4. ADVANCED LOGIC ──────────────────────────────────────────────────────────────────── @@ -8575,7 +9230,7 @@ ACTION_CATALOG = [ {"kind": "repeating_group", "label": "Repeating group", "group": "Advanced logic", "ready": False, "detail": "Run the same actions on every item in a list"}, {"kind": "run_script", "label": "Run script", "group": "Advanced logic", "ready": False, - "detail": "Not built — a sandbox is its own decision"}, + "detail": "Not built. A sandbox is its own decision"}, {"kind": "generate_ai", "label": "Generate with AI", "group": "Advanced logic", "ready": False, "detail": "Needs an AI action implementation"}, ] @@ -8604,10 +9259,63 @@ def _connector_meta(key): return next((dict(v) for v in TRIGGER_CONNECTOR.values() if v.get("key") == key), None) -def action_catalog(): +#: ⭐⭐ WAVE 35 · T35 / CONTRACT C8 — THE TENANT PREDICATE `routes_statements._royal_only` USES, +#: LIFTED SO THERE IS EXACTLY ONE COPY OF IT. C8's words are "the predicate is imported, never +#: re-expressed", and this is the direction that import can run: `automation_engine` imports no +#: route module and no FastAPI (checked), and breaking that to reach `_royal_only` would drag +#: `deps` + `routes_admin` into the engine. So the ENGINE holds the test and the ROUTE calls it. +#: +#: ⛔⛔ THIS IS NOT `odoo_relational.is_royal`, AND THE DIFFERENCE IS A SEND. That one asks "is this +#: tenant ENTITLED to Odoo databases" over `RI_SLUGS = ("", "royal-imports")` — it answers TRUE for +#: the EMPTY slug and lower-cases its input. This one is `_royal_only`'s exact test: the runtime's +#: own `key`, matched exactly. A tenant whose key never got set would pass `is_royal("")` and then +#: queue statements THROUGH TENANT #0'S ENV-CREDENTIALED SEND CLIENT, i.e. email another company's +#: customers over Royal Imports' name. Entitlement to READ is not authority to SEND, and the two +#: questions keep their two predicates on purpose. Do not "unify" them. +ROYAL_TENANT_KEY = "royal-imports" + + +def is_statement_tenant(rt): + """Exactly `routes_statements._royal_only`'s test, as a boolean over the RUNTIME. + + Keyed on the runtime, never on a request field: a tenant is a property of the SESSION, so a + payload cannot argue its way into another company's sender. + """ + return getattr(rt, "key", None) == ROYAL_TENANT_KEY + + +#: Kinds only SOME tenants may see or store, as `{kind: predicate(rt) -> bool}`. +#: +#: ⛔ FAIL-CLOSED ON `rt=None`, AND THAT IS THE WHOLE SAFETY ARGUMENT. Every reader below treats an +#: absent runtime as "not allowed", so a call site that forgets to pass one makes the action VANISH +#: rather than become universal. The opposite default would mean any future caller of +#: `action_catalog()` or `clean_actions()` silently offers tenant #0's send door to every tenant — +#: an omission that is invisible in review and loud only in production [[default-must-pass-its-own-guard]]. +TENANT_GATED_ACTIONS = {"send_statement": is_statement_tenant} + +#: The dunning buckets a statements step may filter on. ⚠ ONE LITERAL, TWO READERS: this and +#: `routes_statements.statements()`'s `"tiers"` field are the same four strings, and a step +#: configured against a tier the sender's worklist does not produce would filter to nothing and +#: report success. `routes_statements` imports this rather than repeating it. +STATEMENT_TIERS = ("A-Urgent", "B-Active", "C-Light", "Monitor") + + +def _tenant_may_use(kind, rt): + """May this runtime see/store this action kind? Ungated kinds are always yes.""" + gate = TENANT_GATED_ACTIONS.get(str(kind or "")) + return True if gate is None else bool(rt is not None and gate(rt)) + + +def action_catalog(rt=None): """The catalog as the wire carries it — a copy, because a caller that mutated the module constant would change every later reader's answer. + ⭐⭐ WAVE 35 · T35 (C8): `rt` filters TENANT-GATED rows out entirely — not `ready: False`, not + `menu: False`, but ABSENT. A tenant that may not send statements should not learn that the + capability exists, and `ready: False` renders as "coming soon", which is a promise we are not + making to them. ⚠ Called with no `rt` the gated rows are withheld (fail-closed): see + `TENANT_GATED_ACTIONS`. + ⭐ WAVE 24 (C-ACT): each row is stamped with its `groupOrder`, DERIVED from `ACTION_GROUP_ORDER` rather than hand-written per row, so a group cannot be given two different orders by two rows that claim to be in it. A group nobody has ordered sorts LAST @@ -8618,11 +9326,24 @@ def action_catalog(): nests on — RESOLVED here rather than written out per row, for the reason `groupOrder` is: two rows in one nest cannot disagree about what that nest is called. A row naming an unknown connector loses the stamp instead of inventing a nest with a raw slug for a title. + + ⭐⭐ WAVE 34 · W34-T44 / R18: `menu` is stamped on EVERY row, never left absent. A row the + picker must not offer carries `menu: False` and STILL RIDES THE WIRE, because the client + resolves a STORED step's label out of this same list (`AutomationBuilder`: + `catalog.find(c => c.kind === a.kind)` then `row?.label || a.kind`) — withholding the row + entirely would make an existing web step render its raw kind token at somebody, which this + module forbids in those words elsewhere. + ⚠ STAMPED RATHER THAN LEFT TO DEFAULT: absent-means-true is a rule two codebases have to + remember the same way, and a client filter is one `!== false` away from meaning the opposite. + An explicit boolean on every row cannot be read two ways. """ last = max(ACTION_GROUP_ORDER.values()) + 1 out = [] for a in ACTION_CATALOG: - row = {**a, "groupOrder": ACTION_GROUP_ORDER.get(a.get("group"), last)} + if not _tenant_may_use(a.get("kind"), rt): + continue + row = {**a, "groupOrder": ACTION_GROUP_ORDER.get(a.get("group"), last), + "menu": bool(a.get("menu", True))} conn = _connector_meta(a.get("connector")) if conn: row["connector"] = dict(conn) @@ -8712,12 +9433,35 @@ def _action_label(act): return str(act.get("kind") or "Action") -def clean_actions(raw, depth=0, _seen=None, _count=None): +def clean_actions(raw, depth=0, _seen=None, _count=None, notes=None, rt=None): """Validate `flow.actions`. Returns `(actions, error)` — refuses, never coerces. + ⭐⭐ WAVE 35 · T35 (C8) — `rt` IS THE TENANT WALL ON THE STORE SIDE, and it is a separate wall + from `action_catalog(rt)`'s. Withholding a row from the MENU stops it being offered; it does + not stop a hand-written body naming the kind, and the picker is not a security boundary + [[opening-a-route-widens-every-field]]. ⚠ Keyword-only in effect and defaulting to None, so + every existing caller is untouched by construction — the same shape `notes` used, for the + reason this docstring already gives about a signature change failing at RUN, not at import. + ⛔ `rt=None` REFUSES a gated kind rather than allowing it (`TENANT_GATED_ACTIONS`). + Ids are STABLE: a caller's well-formed `id` is kept, so selecting an action in the builder survives a Save. A missing or colliding one is minted `act_`; minting on every clean would move the selection under the person editing it. + + ⭐⭐ D-75 — `notes` IS THE DISCLOSURE CHANNEL, AND IT IS OPT-IN. Pass a list and this function + appends one plain sentence per thing it SILENTLY CHANGED: a `create_record` condition dropped + (see the note at that branch), and any config key an arm's allowlist did not keep. + + ⛔ WHY IT IS AN OUT-PARAMETER RATHER THAN A THIRD RETURN VALUE. D-75's own exit says *"this is + a signature change across its callers"* and that is exactly what makes the obvious fix + dangerous mid-wave: `clean_actions` is called from `clean_flow`, from `_is_untouched_ig_seed` + and recursively from its own group arm, and a caller that unpacked two values from a + three-tuple fails at RUN, not at import. An optional list defaults to `None`, every existing + caller is untouched by construction, and the one door that wants to tell somebody opts in. + ⚠ IT REPORTS, IT NEVER REFUSES. Every drop here is deliberate and D-65 is the reason — refusing + a stored automation's condition would 400 it forever, with no way to edit it out, because the + editor cannot save the automation it needs to fix. A drop is recoverable; a locked door is not. + What was missing was never the refusal, it was somebody being told. """ if raw in (None, ""): return [], None @@ -8735,8 +9479,17 @@ def clean_actions(raw, depth=0, _seen=None, _count=None): return None, (f"{kind or 'that action'!r} is not one of: " + ", ".join(a["kind"] for a in ACTION_CATALOG)) if not row["ready"]: - return None, (f"{row['label']!r} is on the menu but not built yet — " + return None, (f"{row['label']!r} is on the menu but not built yet. " f"{row['detail'][0].lower()}{row['detail'][1:]}") + # ⭐⭐ W35-T35 (C8) — THE TENANT WALL. Refused, not dropped, and this is the one place in + # this function where a refusal is right: D-65's "drop, never refuse" protects a stored + # automation from becoming permanently unsavable, and NO tenant this can refuse has ever + # been able to store one — the kind is withheld from their catalog, so there is no legacy + # body to strand. Dropping it silently would instead let a flow save, look saved, and never + # do the step the person configured. + if not _tenant_may_use(kind, rt): + return None, (f"{row['label']!r} is not available in this workspace. It sends as " + f"Royal Imports, using Royal Imports' own mail credentials") count[0] += 1 if count[0] > MAX_ACTIONS: return None, f"an automation runs at most {MAX_ACTIONS} actions" @@ -8767,30 +9520,52 @@ def clean_actions(raw, depth=0, _seen=None, _count=None): # whose value could appear to be ignored. If a `create_record` condition editor ever comes # back, this needs a disclosure channel — `clean_actions` has none today. if kind == "create_record": + # D-75: the drop is unchanged; what is new is that a caller can be TOLD about it. + if notes is not None and entry.get("when"): + notes.append(f"{aid}: the condition on a Create-record step was dropped. A " + f"Create record has no record to test yet. Put the condition on the " + f"trigger, or on an If wrapping this step.") when = None else: when, cerr = clean_cond(entry.get("when"), where=f"action {aid}") if cerr: return None, cerr cfg_raw = entry.get("config") if isinstance(entry.get("config"), dict) else {} - cfg, cerr = _clean_action_config(kind, cfg_raw, depth, seen, count) + cfg, cerr = _clean_action_config(kind, cfg_raw, depth, seen, count, notes=notes, rt=rt) if cerr: return None, cerr + # ⛔ D-75 — THE ALLOWLIST'S OWN DROPS, DIFFED HERE RATHER THAN REPORTED BY EACH ARM. Every + # arm builds a fresh `out = {...}`, so none of them knows what it did not keep; the caller + # of the arm does, because it holds both dicts. One diff, and a new arm is covered the day + # it is written rather than the day somebody remembers to instrument it. + if notes is not None and isinstance(cfg, dict): + gone = [k for k in cfg_raw if k not in cfg] + if gone: + notes.append(f"{aid}: {', '.join(sorted(gone))} " + f"{'is' if len(gone) == 1 else 'are'} not a setting a " + f"{KIND_LABELS.get(kind, kind)!r} step uses, so " + f"{'it was' if len(gone) == 1 else 'they were'} not saved.") out.append({"id": aid, "kind": kind, "enabled": bool(entry.get("enabled", True)), "when": when, "config": cfg}) return out, None -def _clean_action_config(kind, cfg, depth, seen, count): - """One action's `config`, per kind. Returns `(config, error)`.""" +def _clean_action_config(kind, cfg, depth, seen, count, notes=None, rt=None): + """One action's `config`, per kind. Returns `(config, error)`. + + ⚠ `rt` is threaded ONLY so the `group` arm can hand it back to `clean_actions` for the branch + recursion (W35-T35 / C8). Without it a tenant-gated kind is refused at the top level and + ACCEPTED inside an If, which is the half of a flow `_walk_actions`' own docstring says people + cannot see. + """ if kind == "group": # ⭐ WAVE 24 · C-FORK (owner ruling R8) — a group is a FORK now: `{branches: [...]}`, # each `{id, label, cond, actions}`. It was one condition with one action list, i.e. an # if with no else, so expressing "otherwise" meant a second group carrying the negation # by hand — two conditions a later edit could put out of step with each other. if depth + 1 > MAX_GROUP_DEPTH: - return None, (f"conditional groups nest at most {MAX_GROUP_DEPTH} deep — " + return None, (f"conditional groups nest at most {MAX_GROUP_DEPTH} deep. " f"past that a flow is a flowchart and belongs on the board") raw_branches = cfg.get("branches") if not isinstance(raw_branches, list) or not raw_branches: @@ -8800,7 +9575,7 @@ def _clean_action_config(kind, cfg, depth, seen, count): raw_branches = [{"id": "b1", "label": "A", "cond": cfg.get("cond"), "actions": cfg.get("actions")}] if len(raw_branches) > MAX_BRANCHES: - return None, (f"an If / then has at most {MAX_BRANCHES} branches — past that the " + return None, (f"an If / then has at most {MAX_BRANCHES} branches. Past that the " f"record is being routed, which is what the board's lanes are for") out_branches, bseen = [], set() for i, br in enumerate(raw_branches): @@ -8815,10 +9590,13 @@ def _clean_action_config(kind, cfg, depth, seen, count): # would make every branch below it dead code — silently, and only for the # records that reached it. Refused with the reason rather than reordered: this # module does not quietly rewrite what somebody built. - return None, ("only the LAST branch of an If / then can be the Otherwise leg — " + return None, ("only the LAST branch of an If / then can be the Otherwise leg. " "a catch-all above another branch makes the ones below it " "unreachable") - kids, kerr = clean_actions(br.get("actions"), depth + 1, seen, count) + # D-75: threaded into the branch too — an unconfigured step inside an If is + # exactly the one a person cannot see, which is `_walk_actions`' own argument. + kids, kerr = clean_actions(br.get("actions"), depth + 1, seen, count, + notes=notes, rt=rt) if kerr: return None, kerr if not kids: @@ -8843,7 +9621,7 @@ def _clean_action_config(kind, cfg, depth, seen, count): if not key: return None, "a value is written to a field with no name" if v is not None and not isinstance(v, (str, int, float, bool)): - return None, (f"the value for {key!r} must be text or a number — " + return None, (f"the value for {key!r} must be text or a number. " f"an automation writes cells, not objects") clean_vals[key] = _s(v, 500) if isinstance(v, str) else v out = {"values": clean_vals} @@ -8860,7 +9638,7 @@ def _clean_action_config(kind, cfg, depth, seen, count): if not table: return None, "the create record action names no database" if not table.startswith(UT_PREFIX): - return None, (f"actions write to blank databases (ut_*) this wave — " + return None, (f"actions write to blank databases (ut_*) this wave. " f"{table!r} is not one") out["table"] = table # ⭐ WAVE 25 · C5 (owner ruling R1a) — UNIQUE ON. Without it this action APPENDS @@ -8880,9 +9658,37 @@ def _clean_action_config(kind, cfg, depth, seen, count): unique = _s(cfg.get("uniqueOn"), 80).strip() if unique and unique not in clean_vals: return None, (f"this action does not write {unique!r}, so it cannot keep records " - f"unique on it — it writes: " + ", ".join(sorted(clean_vals))) + f"unique on it. It writes: " + ", ".join(sorted(clean_vals))) out["uniqueOn"] = unique return out, None + if kind == "send_statement": + # ⭐⭐ WAVE 35 · T35 / R10 — WHAT A STATEMENTS STEP IS CONFIGURED WITH: a customer filter + # and a template. Both are the SENDER's own vocabulary (`routes_statements.send` passes + # `templates: {subject, intro, footer}` straight to `collections_send.queue_statement`), + # so this arm names no field the send door does not already take. + # + # ⚠ EVERY TEMPLATE FIELD IS OPTIONAL AND EMPTY MEANS "THE DEFAULT", which is exactly how + # the send door already reads them (`t.get("subject") or cs.DEFAULT_SUBJECT`). Storing our + # own copy of the default instead would freeze today's wording into every stored agent and + # silently stop tracking `collections_send`'s. + out = {} + tier = _s(cfg.get("tier"), 40).strip() + # ⛔ REFUSED, NOT COERCED, AND THE ANSWER LISTS THE REAL ONES — the same shape the connector + # cadence uses. A tier nobody sends to would filter the batch to zero customers and report + # a successful run: a silent no-op is the worst outcome available here, because the person + # believes their customers were invoiced. + # ⚠ `""` IS LEGAL and means EVERY tier. It is the stored default, so an agent saved before + # anybody picks a filter does not change meaning the day this key arrives (D-65's rule). + if tier and tier not in STATEMENT_TIERS: + return None, (f"{tier!r} is not a collection tier. Pick one of: " + + ", ".join(STATEMENT_TIERS) + ", or leave it blank for all of them") + out["tier"] = tier + for key, cap in (("subject", 200), ("intro", 4000), ("footer", 4000)): + out[key] = _s(cfg.get(key), cap) + lbl = " ".join(_s(cfg.get("label"), 60).split()) + if lbl: + out["label"] = lbl + return out, None if kind in ENRICH_KINDS: # ⭐ WAVE 30 · T08 — BOTH networks share this branch. See `ENRICH_KINDS`: the selection, the # cooldown, the limit clamps and their reasons are network-agnostic, and a second copy for @@ -8977,6 +9783,40 @@ def _clean_action_config(kind, cfg, depth, seen, count): if limit < 1 or limit > FIND_LIMIT_MAX: return None, f"the find records limit is between 1 and {FIND_LIMIT_MAX}" return {"table": table, "cond": cond, "limit": limit}, None + if kind == "ai_agent": + # ⭐⭐ W33-T56 — THE FUZZY STEP'S CONFIG. Same posture as the web arm below in every + # respect that matters: an ALLOWLIST, a shape test on the url, a clamped timeout, and an + # EMPTY config stored rather than refused so the step can be added before it is configured + # (the wave-23 illegal-default-seed defect, and D-79's scar). + # ⚠ IT DELIBERATELY DOES NOT TAKE A `selector`. Working the selector out is the step; a + # selector box here would be a control that contradicts the action's own reason to exist. + _u = _s(cfg.get("url"), 500).strip() + if _u and not (_u.startswith("http://") or _u.startswith("https://") + or _u.startswith("{{")): + return None, "a web address must start with http:// or https://" + try: + _t = int(cfg.get("timeoutMs") or WEB_READ_TIMEOUT_MS) + except (TypeError, ValueError): + return None, "the web step timeout must be a whole number of milliseconds" + try: + _max = int(cfg.get("maxSteps") or AI_AGENT_MAX_STEPS) + except (TypeError, ValueError): + return None, "the step ceiling must be a whole number" + out = {"url": _u, + # ⚠ LONGER THAN A SELECTOR AND SHORTER THAN A PROMPT. This is a sentence or two + # describing a job, and the model is given the page's own vocabulary at run time — + # a 4,000-character instruction is a sign somebody is writing a program in prose. + "instruction": _s(cfg.get("instruction"), 600), + "field": _s(cfg.get("field"), 80).strip(), + "timeoutMs": max(1000, min(_t, WEB_READ_TIMEOUT_MAX_MS)), + # ⛔ THE CEILING IS THE POINT OF THE CLAMP, not the default. Every step this action + # composes is a real browser action inside one job, and a fuzzy instruction is + # exactly the input that produces twenty of them. Bounded here so a run cannot be + # talked into an unbounded journey by a sentence. + "maxSteps": max(1, min(_max, AI_AGENT_MAX_STEPS))} + if cfg.get("dryRun"): + out["dryRun"] = True + return out, None if kind in WEB_KINDS: # ⭐⭐ WAVE 31 · T38 (C5 / R10) — AND THIS ARM IS THE HALF THAT WOULD HAVE SHIPPED MISSING. # @@ -9441,7 +10281,7 @@ def enrich_selection(rt, table_key, cfg, profile_key, today=None, gone=None, pla if problem: # ⛔ REFUSE, do not widen. See the docstring — this is the branch where a quiet # fallback costs real money. - return [], f"the enrich step names a view it cannot read — {problem}" + return [], f"{ENRICH_VIEW_UNREADABLE}. {problem}" # ⭐⭐ 2026-08-07 (owner report) — `filter_eval.matches`, NOT `lane_match`. THIS LINE WAS # A THIRD IMPLEMENTATION OF "does this row match", AND IT SPOKE THE WRONG LANGUAGE. # @@ -9565,12 +10405,12 @@ def enrich_selection(rt, table_key, cfg, profile_key, today=None, gone=None, pla # do, because nothing else will ever retry them — under R9 this note is the only path # back from a tombstone, so a vaguer version would strand the row permanently. notes.append(f"{len(skipped_gone)} skipped because Instagram has no such account " - f"({shown}{', …' if len(skipped_gone) > 5 else ''}) — delete the row or " + f"({shown}{', …' if len(skipped_gone) > 5 else ''}). Delete the row or " f"correct the handle; they are not retried automatically") if blank_handle: notes.append(f"{blank_handle} skipped with no handle") if len(picked) < quota and (cooled or blank_handle or skipped_gone or ordered): - notes.append(f"{len(picked)} of the {quota} asked for — the list ran out") + notes.append(f"{len(picked)} of the {quota} asked for. The list ran out") return picked, "; ".join(notes) @@ -9803,6 +10643,131 @@ def apply_actions(rt, defn, table_key, row_ids, username="automation", log=print # The RUN LOG is the operational record of what happened now, and it is the only one. patches, creates = {}, {} + #: ⭐⭐ W33-T58 · D-191 — this record's web results, keyed by ACTION ID, and the run's job + #: count. `web_done` is cleared per record (a batch is built from one row's interpolated + #: values and means nothing for the next one); `web_jobs` counts JOBS across the whole run, + #: which is what `MAX_WEB_JOBS_PER_RUN` has always been trying to bound. + #: ⚠ A key present with `None` means "this step was in a batch that refused" — distinct from + #: absent, which means "no batch has covered it yet". Collapsing the two would re-run the + #: whole batch once per step of it, which is the defect this fixes, inverted. + web_done: dict = {} + web_jobs = [0] + + def _web_step_dict(act, row): + """One action + one record → the step dict the seam takes. Interpolated HERE, as before. + + ⚠ `interpolate` on the CALLER's side, exactly as the update/create arms do it, so + `{{Field}}` works in a url, a selector or a typed value. The seam takes a plain dict and + does not know about rows. + """ + cfg = act.get("config") or {} + wait = cfg.get("waitFor") + step = {"kind": act.get("kind"), "id": str(act.get("id") or ""), + "url": interpolate(str(cfg.get("url") or ""), row), + "selector": interpolate(str(cfg.get("selector") or ""), row), + "attr": str(cfg.get("attr") or "text"), + "all": bool(cfg.get("all")), + "waitFor": interpolate(str(wait), row) if wait else None, + "timeoutMs": int(cfg.get("timeoutMs") or 20000)} + # ⚠ ADDED ONLY WHEN PRESENT: the seam distinguishes a key that is absent from one that is + # empty, and an empty `value` on a `web_read` would be a typed blank. + if cfg.get("value"): + step["value"] = interpolate(str(cfg.get("value")), row) + if cfg.get("hint"): + step["hint"] = interpolate(str(cfg.get("hint")), row) + if cfg.get("secret"): + step["secret"] = True + if cfg.get("dryRun"): + step["dryRun"] = True + return step + + def _run_web_batch(acts, start, row, rid): + """Run the longest safe run of consecutive web steps from `acts[start]` in ONE job. + + ⛔ **CONSECUTIVE, AND ONLY WHILE NOTHING IN THE BATCH DEPENDS ON THE BATCH.** `run_plan` + sends every step to one browser at once, so a step whose url/selector/value interpolates a + column an EARLIER step in the same batch writes would be interpolated against the value + that column had BEFORE the batch ran. That is a wrong answer rather than a slow one, so the + batch is cut immediately before any such step and the remainder becomes the next batch. + The single-step case is then exactly the old behaviour, which is what makes this safe to + land on a live flow. + ⚠ A step that is disabled, filtered out by its `when`, or unconfigured ENDS the batch + rather than being skipped inside it: each of those is a reason this record does not run + that step, and the loop's own arms already report them one at a time with their own + sentences. Ending here keeps exactly one place that decides what a blocked step says. + """ + batch, produced = [], set() + for act in acts[start:]: + kind = act.get("kind") + if kind not in WEB_KINDS or not act.get("enabled", True): + break + if not lane_match(act.get("when"), row): + break + cfg = act.get("config") or {} + if _web_missing(kind, cfg): + break + # The dependency cut. `interpolate` reads `{{Name}}`; a step naming a column an + # earlier step in THIS batch writes has to wait for the next job. + refs = " ".join(str(cfg.get(k) or "") for k in ("url", "selector", "value", "hint")) + if any(("{{" + f) in refs or ("{{ " + f) in refs for f in produced): + break + batch.append(act) + if str(cfg.get("field") or ""): + produced.add(str(cfg.get("field"))) + if len(batch) >= MAX_WEB_STEPS_PER_JOB: + break + if not batch: + return + steps = [_web_step_dict(a, row) for a in batch] + # ⛔ THE SEAM REFUSES A JOURNEY WHOSE FIRST STEP CARRIES NO ADDRESS — there is no page to + # act on yet — and a refusal is for the WHOLE plan. Batching a url-less first step would + # therefore take its followers down with it, where one-job-per-step only lost that step. + # A batch that cannot start is cut to one, which is exactly the old behaviour. + if not str(steps[0].get("url") or "").strip(): + batch, steps = batch[:1], steps[:1] + web_jobs[0] += 1 + + def _block(a, why_one): + web_done[str(a.get("id") or "")] = None + counts["webBlocked"] += 1 + if why_one: + log(f"[aios-auto] {a.get('kind')}: {why_one}") + + # ⛔ THE SEAM'S OWN BOUNDARY IS ON `run_step`, NOT ON `run_plan` — `run_step` wraps its + # call in `try/except` and calls that "the LAST boundary". Calling `run_plan` directly + # steps around it, and this code runs inside a record walk where an escaping exception + # ends the whole run. So the boundary moves here with the call. + try: + rows_out, why = _web_agent().run_plan( + steps, {"tenant": str(defn.get("tenant") or ""), + "automationId": str(defn.get("id") or ""), + "runId": str(defn.get("id") or ""), "log": log}) + except Exception as exc: # noqa: BLE001 — the LAST boundary + why, rows_out = (f"The web steps failed unexpectedly ({type(exc).__name__}: " + f"{str(exc).splitlines()[0][:200]}). Nothing was read."), None + if why: + log(f"[aios-auto] web: {why}") + for a in batch: + _block(a, "") + return + # ⚠ MATCHED BY ID, NEVER BY POSITION. The job returns a row for a step that FAILED and for + # every step after it that was never attempted, so the list can be shorter than, or + # misaligned with, the plan — and a positional read would hand step 3's caller step 2's + # answer, writing a wrong value into a real column, which is worse than the missing one it + # replaced. `_clean_step` mints an id for every step and the runner echoes it back, so the + # id is carried the whole way and is the only thing worth matching on. + by_id = {str(r.get("id") or ""): r for r in (rows_out or []) if isinstance(r, dict)} + for a in batch: + hit = by_id.get(str(a.get("id") or "")) + # ⛔ `ok` IS CHECKED HERE BECAUSE `run_step` USED TO CHECK IT. It turned a row with + # `ok:false` into a sentence and returned no result; reading `hit` without that test + # would take a failed step's empty `value` and write it over a real cell. + if not hit or not hit.get("ok"): + _block(a, str((hit or {}).get("error") or "") + or "The browser job returned nothing for this step.") + continue + web_done[str(a.get("id") or "")] = hit + def _walk(acts, row, rid, depth=0): """Walk the actions in order for ONE record. @@ -9811,7 +10776,7 @@ def apply_actions(rt, defn, table_key, row_ids, username="automation", log=print early. With review retired nothing suspends anything, so every record walks its whole flow; the signature stays so a future gate-style action has an obvious place to say so. """ - for act in acts: + for idx, act in enumerate(acts): if not act.get("enabled", True): continue if not lane_match(act.get("when"), row): @@ -9843,6 +10808,103 @@ def apply_actions(rt, defn, table_key, row_ids, username="automation", log=print # the table would silently apply one action's uniqueness rule to the other's rows. creates.setdefault((target, str(cfg.get("uniqueOn") or "")), []).append(vals) counts["created"] += 1 + elif kind == "send_statement": + # ⭐⭐ WAVE 35 · T35 / R10 — THE ARM LANDS WITH THE CATALOG ROW, ON PURPOSE. + # + # `_walk` has no terminal `else` (see the note on `enrich_tiktok` in the catalog): + # an unknown kind is walked, COUNTED, reports the run `ok` and writes nothing. So a + # catalog row whose arm arrives in a later ticket is addable, storable and silently + # inert — a step a person configured, that reports success and does nothing. This + # arm exists so that window never opens. + # + # ⛔ T35 DOES NOT SEND AND DOES NOT PARK. R10's review stage is W35-T36; until it + # lands this says so out loud and counts the record as blocked, which is the same + # shape `ai_agent` uses for a step it cannot perform. It must never fall through to + # "ok". + # ⛔ AND IT NEVER SENDS FROM HERE, in this wave or any later one. The send door is + # `routes_statements`, behind SAFE_MODE + `admin_gate` + the tenant gate, reached by + # a human click on the review batch. This arm's whole job is to PREPARE. + if "send_statement_pending" not in web_notes: + web_notes.append("send_statement_pending") + log("[aios-auto] send_statement: statements are assembled for review, not " + "sent. The review batch is not configured yet, so nothing was prepared " + "and nothing was sent.") + counts["webBlocked"] += 1 + continue + elif kind == "ai_agent": + # ⭐⭐ W33-T56 (owner item 7, ruling R3) — THE FUZZY STEP, AT RUN TIME. + # + # A description becomes concrete web steps HERE, against this record's own values, + # and then rides the ordinary seam. Composing at run time rather than at save time + # is the whole point: `{{Website}}` is a different page for every row, so a journey + # fixed at save time would be the same guess repeated. + # ⛔ IT COMPOSES ONLY `web_*` KINDS. The composer is handed the same catalog the + # AI-agent module uses, filtered to what a browser job can perform — so a fuzzy + # instruction cannot talk this action into writing a record or calling a connector. + # The blast radius of a bad sentence is one browser session, not the tenant. + # ⚠ AND IT REPORTS THE STEPS IT ACTUALLY TOOK, which is the ticket's own + # `done-when`. A step that composes a journey and reports only its final value is + # unauditable: nobody can tell a right answer from a lucky one. + _missing = _web_missing(kind, cfg) + if _missing: + _note = f"{kind}_unconfigured" + if _note not in web_notes: + web_notes.append(_note) + log(f"[aios-auto] {kind}: this step still needs " + + ", ".join(_missing) + ". Nothing was done") + counts["webBlocked"] += 1 + continue + if web_jobs[0] >= MAX_WEB_JOBS_PER_RUN: + if "web_cap" not in web_notes: + web_notes.append("web_cap") + log(f"[aios-auto] web: this run stopped after {MAX_WEB_JOBS_PER_RUN} " + f"browser jobs of about 10-30 seconds each.") + counts["webBlocked"] += 1 + continue + # W35 · C7: `st` + `user` so the model spend is attributed (`NOTE E-16`). + _plan, _why = _ai_agent_plan(cfg, row, log, st=rt, + user=str(defn.get("createdBy") or "")) + if _why: + # ⛔ NAMED, NEVER OPAQUE — the second half of the `done-when`. "The assistant + # could not work out how to do that" with the reason attached is actionable; + # a blank cell is not. + log(f"[aios-auto] ai_agent: {_why}") + counts["webBlocked"] += 1 + continue + web_jobs[0] += 1 + try: + _rows_out, _why2 = _web_agent().run_plan( + _plan, {"tenant": str(defn.get("tenant") or ""), + "automationId": str(defn.get("id") or ""), + "runId": str(defn.get("id") or ""), "log": log}) + except Exception as _exc: # noqa: BLE001 — the LAST boundary + _rows_out, _why2 = None, ( + f"the browser job failed unexpectedly ({type(_exc).__name__}: " + f"{str(_exc).splitlines()[0][:200]}). Nothing was done.") + if _why2: + log(f"[aios-auto] ai_agent: {_why2}") + counts["webBlocked"] += 1 + continue + # THE ACCOUNT OF WHAT IT DID — one line per step, in order, with each step's own + # verdict. This is what makes a fuzzy step auditable at all. + _done = [r for r in (_rows_out or []) if isinstance(r, dict)] + for _i, _r in enumerate(_done, 1): + log(f"[aios-auto] ai_agent step {_i}/{len(_plan)}: {_r.get('kind')} " + f"{'ok' if _r.get('ok') else 'FAILED'}" + + (f". {str(_r.get('error'))[:160]}" if not _r.get("ok") else "")) + _last = _done[-1] if _done else {} + if not _done or not _last.get("ok"): + log("[aios-auto] ai_agent: the journey did not finish. " + + str((_last or {}).get("error") + or "the browser job returned nothing for the last step")) + counts["webBlocked"] += 1 + continue # ⛔ NOTHING IS WRITTEN on an unfinished journey. + _target = str(cfg.get("field") or "") + if _target: + vals = {_target: _last.get("value")} + row.update(vals) + _act_row_patch(patches, table, rid, vals) + counts["webRead"] += len(_done) elif kind in WEB_KINDS: # ⭐⭐ WAVE 31 · T38 (C5) — THE WEB-BROWSING AGENT'S LIVE ARM, ALL FIVE KINDS. # @@ -9875,8 +10937,7 @@ def apply_actions(rt, defn, table_key, row_ids, username="automation", log=print # no selector; `web_fill` needs a value nobody else takes; only `web_read` needs a # column to write into. One shared three-field test would have blocked every # `web_goto` ever configured for want of a selector it does not use. - _missing = [n for n, key in WEB_REQUIRED.get(kind, ()) - if not str(cfg.get(key) or "").strip()] + _missing = _web_missing(kind, cfg) if _missing: # ⚠ THE NOTE KEY CARRIES THE KIND. It used to be the literal # `"web_read_unconfigured"`, so a flow with an unconfigured `web_goto` AND an @@ -9886,57 +10947,37 @@ def apply_actions(rt, defn, table_key, row_ids, username="automation", log=print if _note not in web_notes: web_notes.append(_note) log(f"[aios-auto] {kind}: this step still needs " - + ", ".join(_missing) + " — nothing was done") + + ", ".join(_missing) + ". Nothing was done") counts["webBlocked"] += 1 continue - # ⛔⛔ THE PER-RUN JOB CEILING (E-4). One browser job per RECORD, ~9-32 s each, - # against HF's 6-concurrent cap — a flow over a few thousand rows would submit a few - # thousand jobs and run for days. Reported ONCE with its cause AND the fix, which is - # R6's second sentence: a limit that cannot be removed today must say why and what - # would remove it. `MAX_WEB_JOBS_PER_RUN` carries the reasoning. - if counts["webRead"] >= MAX_WEB_JOBS_PER_RUN: + # ⛔⛔ THE PER-RUN JOB CEILING (E-4). A browser job is ~9-32 s against HF's + # 6-concurrent cap — a flow over a few thousand rows would submit a few thousand + # jobs and run for days. Reported ONCE with its cause AND the fix, which is R6's + # second sentence: a limit that cannot be removed today must say why and what would + # remove it. `MAX_WEB_JOBS_PER_RUN` carries the reasoning. + # ⭐⭐ W33-T58 (D-191) — THE CEILING NOW COUNTS **JOBS**, NOT PAGES, because the + # two stopped being the same thing on the line below. A record whose three web + # steps batch into one job spends ONE of these, not three. + if web_jobs[0] >= MAX_WEB_JOBS_PER_RUN: if "web_cap" not in web_notes: web_notes.append("web_cap") log(f"[aios-auto] web_read: this run stopped after " - f"{MAX_WEB_JOBS_PER_RUN} pages — each one is a separate browser job " - f"of about 10-30 seconds, and they do not run in parallel. To read " - f"more, narrow the flow's records, or batch the flow's web steps into " - f"one job (web_agent.run_plan).") + f"{MAX_WEB_JOBS_PER_RUN} browser jobs of about 10-30 seconds each, " + f"which do not run in parallel. A record's consecutive web steps " + f"already share ONE job; to read more, narrow the flow's records.") counts["webBlocked"] += 1 continue - _url = interpolate(str(cfg.get("url") or ""), row) - _sel = interpolate(str(cfg.get("selector") or ""), row) - _wait = cfg.get("waitFor") - _step = {"kind": kind, "id": str(act.get("id") or ""), - "url": _url, "selector": _sel, - "attr": str(cfg.get("attr") or "text"), - "all": bool(cfg.get("all")), - "waitFor": interpolate(str(_wait), row) if _wait else None, - "timeoutMs": int(cfg.get("timeoutMs") or 20000)} - # ⚠ `value` IS INTERPOLATED LIKE THE URL AND THE SELECTOR — a `web_fill` typing - # `{{Email}}` is the whole point of running it over a record walk. ⛔ AND IT IS - # ADDED ONLY WHEN PRESENT: the seam distinguishes a key that is absent from one - # that is empty, and an empty `value` on a `web_read` would be a typed blank. - if cfg.get("value"): - _step["value"] = interpolate(str(cfg.get("value")), row) - if cfg.get("hint"): - _step["hint"] = interpolate(str(cfg.get("hint")), row) - if cfg.get("secret"): - _step["secret"] = True - if cfg.get("dryRun"): - _step["dryRun"] = True - result, why = _web_agent().run_step( - _step, - {"tenant": str(defn.get("tenant") or ""), - "automationId": str(defn.get("id") or ""), - "runId": str(defn.get("id") or ""), "log": log}) - # ⛔ EXACTLY ONE OF THE TWO IS TRUTHY — E's contract, and `if why:` is the COMPLETE - # client-side branch. There is no exception path to catch: `run_step` turns - # everything into a sentence, which is R6's second sentence built into the seam. - if why: - log(f"[aios-auto] web_read: {why}") - counts["webBlocked"] += 1 - continue # ⛔ NOTHING IS WRITTEN on a refusal. + # ⭐⭐ W33-T58 · D-191 — ONE JOB FOR A RECORD'S CONSECUTIVE WEB STEPS. + # `run_plan(steps, ctx)` has always taken a list and nothing ever called it with + # more than one: the arm called `run_step`, which wraps `[step]`, so a flow with + # three web reads paid THREE ~9 s cold starts to do what one job does. The batch is + # built at WALK time rather than from the stored flow, because whether a step runs + # at all depends on this record (`enabled`, `when`, and whether it is configured). + if str(act.get("id") or "") not in web_done: + _run_web_batch(acts, idx, row, rid) + result = web_done.get(str(act.get("id") or "")) + if result is None: + continue # its batch refused; the reason was logged once, there _target = str(cfg.get("field") or "") if _target: vals = {_target: (result or {}).get("value")} @@ -9954,7 +10995,7 @@ def apply_actions(rt, defn, table_key, row_ids, username="automation", log=print if "unbound" not in enrich["notes"]: enrich["notes"].append("unbound") log("[aios-auto] enrich_instagram: no profile column on " - f"{table} — name one on the action, or mark a text column as an " + f"{table}. Name one on the action, or mark a text column as an " "Instagram profile") continue # ⭐ 2026-08-07 (owner ruling) — IS THIS RECORD IN THIS RUN'S BUDGET? @@ -10099,7 +11140,7 @@ def apply_actions(rt, defn, table_key, row_ids, username="automation", log=print if "unbound" not in tt["notes"]: tt["notes"].append("unbound") log("[aios-auto] enrich_tiktok: no profile column on " - f"{table} — name one on the action, or mark a text column as a " + f"{table}. Name one on the action, or mark a text column as a " "TikTok profile") continue aid = str(act.get("id") or "") @@ -10240,6 +11281,10 @@ def apply_actions(rt, defn, table_key, row_ids, username="automation", log=print row = dict(rows.get(str(rid)) or {}) if not row: continue + # ⭐ D-191 — the web batch is built from THIS row's interpolated values, so it means + # nothing for the next one. Cleared here rather than inside `_walk`, which recurses + # into branches and would wipe a batch its own caller is still consuming. + web_done.clear() _walk(actions, row, str(rid)) # ⭐⭐ WAVE 30 · T08 — TWO FLUSHES, ONE `counts`, AND THE NOTES ARE CONCATENATED RATHER THAN # OVERWRITTEN. `RUN_NOTES_KEY` is the one key both flushes legitimately produce, so a plain @@ -10425,7 +11470,7 @@ def _enrich_flush(rt, defn, username, acc, log): acc["posts"], acc["psnaps"]) if m_status == "error": out["enrichMasterFailed"] = 1 - log(f"[aios-auto] enrich_instagram: the platform master copy FAILED — {m_note}; " + log(f"[aios-auto] enrich_instagram: the platform master copy FAILED. {m_note}; " f"the tenant copy is complete and the next run re-appends") elif m_status == "ok": out["enrichMaster"] = len(acc["snaps"]) + len(acc["psnaps"]) @@ -10469,7 +11514,7 @@ def _unbound_hint(rt, table_key): return "" shown = ", ".join(names[:UNBOUND_HINT_MAX]) more = len(names) - UNBOUND_HINT_MAX - return (f" — this database's text columns are {shown}" + return (f". This database's text columns are {shown}" + (f" (+{more} more)" if more > 0 else "")) @@ -10931,7 +11976,7 @@ def collect_pending_profile_snapshots(rt, defn, username="automation", log=print if stale_h is not None and stale_h >= PENDING_PROFILE_MAX_HOURS: closed += 1 note = (f"@{task['influencer']}: the source never finished the profile read " - f"queued {int(stale_h)}h ago ({task['snapshotId']}) — it was dropped; " + f"queued {int(stale_h)}h ago ({task['snapshotId']}). It was dropped; " f"the next run will ask again") notes.append(note) acc["notes"].append(note) @@ -10949,7 +11994,7 @@ def collect_pending_profile_snapshots(rt, defn, username="automation", log=print acc["profiles"] += 1 acc["blocked"] += 1 note = (f"@{task['influencer']}: the source delivered {len(rows)} profile" - f"{'' if len(rows) == 1 else 's'} for that batch, none of them this handle — " + f"{'' if len(rows) == 1 else 's'} for that batch, none of them this handle. " f"it was dropped from the batch and the next run will ask again") notes.append(note) acc["notes"].append(note) @@ -11210,9 +12255,16 @@ def ai_decide(rt, defn, act, row, row_id="", log=print): (ut_get(rt, ((defn.get("config") or {}).get("targetTable") or (defn.get("trigger") or {}).get("table") or "")) or {} ).get("fields") or []] + # ⭐ W35 · CONTRACT C7 (`NOTE E-16`) — ATTRIBUTE THE SPEND. `st=` is what lets the ledger write + # to the right tenant's store and `user=` is who it is billed to; without them the call is + # counted as UNATTRIBUTED, which is a meter that reports a total nobody can act on. + # ⚠ `createdBy` is the honest actor here: an AI review decision is made ON BEHALF of the + # automation, by a scheduler, with no person at the keyboard. Naming whoever last edited it + # would attribute a nightly run to an editor who was asleep. choice, meta = ai_review.decide(prompt=cfg.get("prompt") or "", options=options, row=row, fields=[f for f in fields if f], - label=cfg.get("label") or "Review") + label=cfg.get("label") or "Review", + st=rt, user=str(defn.get("createdBy") or "")) if not choice: if meta.get("problem"): log(f"[aios-auto] ai review declined to answer: {meta['problem']}") @@ -11280,7 +12332,7 @@ def _commit_action_writes(rt, table, patches, creates, username, log): t = ut_get(rt, tkey) if t is None: n = sum(len(r) for _u, r in groups) - log(f"[aios-auto] create_record: {tkey} no longer exists — {n} skipped") + log(f"[aios-auto] create_record: {tkey} no longer exists. {n} skipped") out["createSkipped"] += n continue # The PATCHED rows when this table was also stamped this run, so the creates land on top @@ -11300,7 +12352,7 @@ def _commit_action_writes(rt, table, patches, creates, username, log): # because the symptom is otherwise a run that says it created less than it walked. out["createSkipped"] += c["skipped"] if c["capped"]: - log(f"[aios-auto] create_record: {tkey} at its {cap}-row cap — " + log(f"[aios-auto] create_record: {tkey} at its {cap}-row cap. " f"{c['capped']} row(s) not written") continue nxt = max([int(r) for r in cur if str(r).isdigit()] or [0]) + 1 @@ -11310,7 +12362,7 @@ def _commit_action_writes(rt, table, patches, creates, username, log): # named, here and in the run's counts. This used to `break` with a log line # that said the cap was hit and never said how much was lost. out["createCapped"] += len(new_rows) - i - log(f"[aios-auto] create_record: {tkey} at its {cap}-row cap — " + log(f"[aios-auto] create_record: {tkey} at its {cap}-row cap. " f"{len(new_rows) - i} row(s) not written") break cur[str(nxt)] = dict(vals) @@ -12270,9 +13322,19 @@ TRIGGER_LABELS = { # * THE GATE fails HARD — `verify_automation` asserts that NO shipped trigger lands in `other`, # so the fallback is provably dead code in production and the classification is still # mandatory. The fallback catches the accident; the gate stops it shipping. +# ⭐ WAVE 34 · R19 — CONNECTOR SITS ABOVE DATABASE, DIRECTLY UNDER TIME. Owner, verbatim: +# *"In the Trigger picker, the Connector section sits directly above the Database section, just +# under the Time trigger types."* So the two orders below are SWAPPED against wave 24's, and +# nothing else moved: same keys, same labels, same fallback. +# ⛔ THIS IS THE WHOLE OF R19 AND IT IS DELIBERATELY NOT A CLIENT CHANGE. `steps.ts::groupTriggers` +# sorts by each option's `groupOrder` and by nothing else, so re-ordering an array on the client +# would look right in a fixture and be wrong in production the moment the server re-sorted. +# ⚠ `verify_steps.py` CANNOT WITNESS THIS EDIT: its C2 leg supplies its OWN `groupOrder` in a +# fixture and asserts the client honours it, which stays true whatever these numbers say. The +# check that binds R19 to this table lives in `verify_automation` beside the vocab section. TRIGGER_GROUPS = {"time": {"label": "Time", "order": 1}, - "database": {"label": "Database", "order": 2}, - "connector": {"label": "Connector", "order": 3}, + "connector": {"label": "Connector", "order": 2}, + "database": {"label": "Database", "order": 3}, "other": {"label": "Other", "order": 99}} #: Where an unclassified trigger goes. ⚠ Reaching this in production is a BUG the gate exists to #: prevent — it is the soft landing, not a category anybody should be adding triggers to. @@ -12398,7 +13460,7 @@ def clean_trigger(raw, previous=None): if key in TRIGGER_PLANNED: # Declared on the wire, refused at the door — see the TRIGGER_PLANNED note. The sentence # says WHY rather than "unknown trigger", because the picker legitimately showed it. - return None, (f"{TRIGGER_LABELS[key]!r} is on the list but not built yet — " + return None, (f"{TRIGGER_LABELS[key]!r} is on the list but not built yet. " f"it renders so you can see it is coming, and it cannot be saved") if key not in TRIGGER_KEYS: return None, (f"{key or 'that trigger'!r} is not one of: " + ", ".join(TRIGGER_KEYS)) @@ -12439,7 +13501,7 @@ def clean_trigger(raw, previous=None): if key in TRIGGER_TABLE_KEYS: table = _s(raw.get("table") if "table" in raw else prev.get("table"), 60).strip() if table and not table.startswith(UT_PREFIX): - return None, ("event triggers watch blank databases (ut_*) this wave — " + return None, ("event triggers watch blank databases (ut_*) this wave. " f"{table!r} is not one") out["table"] = table if key == "event_field": @@ -12466,7 +13528,7 @@ def clean_trigger(raw, previous=None): watch = [_s(f, 80).strip() for f in watch_raw if _s(f, 80).strip()] if len(watch) > MAX_WATCH_FIELDS: return None, (f"a record-updated trigger watches at most {MAX_WATCH_FIELDS} " - f"fields — leave the list empty to watch every field") + f"fields. Leave the list empty to watch every field") out["fields"] = watch # ⭐ WAVE 24 · C-TRIG LAW 5 (owner item 7) — THE CONDITION IS GONE, and this REMOVES A # SHIPPED CAPABILITY. Watched `fields` is now the whole of this trigger's configuration: @@ -12496,7 +13558,7 @@ def clean_trigger(raw, previous=None): # every existing webhook trigger would go unconfigured and stop firing. table = _s(raw.get("table") if "table" in raw else prev.get("table"), 60).strip() if table and not table.startswith(UT_PREFIX): - return None, ("a webhook writes into a blank database (ut_*) — " + return None, ("a webhook writes into a blank database (ut_*). " f"{table!r} is not one") out["table"] = table fmap, ferr = clean_body_map(raw.get("fieldMap") if "fieldMap" in raw @@ -12537,7 +13599,7 @@ def clean_body_map(raw): if not p: return None, "a webhook mapping has an empty body path" if len(p.split(".")) > MAX_BODY_DEPTH: - return None, (f"{p!r} reaches more than {MAX_BODY_DEPTH} levels into the payload — " + return None, (f"{p!r} reaches more than {MAX_BODY_DEPTH} levels into the payload. " f"map a shallower value") fk = re.sub(r"[^a-z0-9_]+", "_", _s(field, 60).strip().lower()).strip("_") if not fk: @@ -12587,7 +13649,7 @@ def webhook_row(rt, defn, body): if v is not None: values[fkey] = _s(v, 500) if isinstance(v, str) else v if not values: - return "", 0, ("none of the mapped paths resolved to a value in this payload — " + return "", 0, ("none of the mapped paths resolved to a value in this payload. " "check the paths against what you are sending") rows = dict((t.get("rows") or {})) if len(rows) >= row_cap(table): @@ -12672,7 +13734,7 @@ def trigger_fire(rt, tenant, auto_id, log=print, rows=None): start (breaker, or already running — both are answers, not errors).""" if _breaker_trips(tenant, auto_id): note = (f"auto-paused: more than {FIRE_LIMIT} trigger fires in " - f"{FIRE_WINDOW_SECONDS // 60} minutes — something is writing this trigger's " + f"{FIRE_WINDOW_SECONDS // 60} minutes. Something is writing this trigger's " f"subject in a loop") _pause_trigger(rt, auto_id, note) log(f"[aios-auto] breaker: {auto_id} {note}") @@ -12816,7 +13878,7 @@ def _settle_eval(rt, tenant, auto_id, log=print): fired = list(touched) # "the field changed" — the burst is the edge if len(fired) > FLOOD_LIMIT: _commit_run(rt, auto_id, "partial", - f"the trigger matched {len(fired)} records in one evaluation — more than " + f"the trigger matched {len(fired)} records in one evaluation. More than " f"the {FLOOD_LIMIT}-record flood hold, so nothing ran. Press Run now to " f"process them deliberately", {"held": len(fired)}, True) return @@ -13009,7 +14071,7 @@ def email_poll(rt, tenant, auto_id, defn, log=print, _list=None, _read=None): reader = _read or (lambda mid: oauth_connect.gmail_message(token, mid)) ids, lerr = lister(trg.get("query") or "", EMAIL_MAX_PER_POLL + FLOOD_LIMIT) if lerr: - return _commit_run(rt, auto_id, "partial", f"the Gmail poll did not answer — {lerr}", + return _commit_run(rt, auto_id, "partial", f"the Gmail poll did not answer. {lerr}", {}, True) seen = set((defn.get("state") or {}).get("emailSeen") or []) fresh = [m for m in ids if m not in seen] @@ -13017,7 +14079,7 @@ def email_poll(rt, tenant, auto_id, defn, log=print, _list=None, _read=None): return None # nothing new is not a run — no history spam if len(fresh) > FLOOD_LIMIT: return _commit_run(rt, auto_id, "partial", - f"{len(fresh)} new emails matched in one poll — more than the " + f"{len(fresh)} new emails matched in one poll. More than the " f"{FLOOD_LIMIT}-record flood hold, so nothing was written. Narrow " f"the query, or press Run now after adjusting it", {"held": len(fresh)}, True) @@ -13032,7 +14094,7 @@ def email_poll(rt, tenant, auto_id, defn, log=print, _list=None, _read=None): table_key = (defn.get("config") or {}).get("targetTable") or "" if not table_key: return _commit_run(rt, auto_id, "error", - "the email trigger has nowhere to write — the automation names no " + "the email trigger has nowhere to write. The automation names no " "target database", {}, False) ut_ensure(rt, (defn.get("config") or {}).get("targetLabel") or defn.get("name") or "Inbox", EMAIL_FIELDS, username=str(defn.get("createdBy") or "automation"), key=table_key) @@ -13041,10 +14103,10 @@ def email_poll(rt, tenant, auto_id, defn, log=print, _list=None, _read=None): ut_write_rows(rt, table_key, merged) new_seen = (list(seen) + fresh)[-EMAIL_SEEN_CAP:] set_state(rt, auto_id, {"emailSeen": new_seen}) - summary = (f"{len(fresh)} new email{'' if len(fresh) == 1 else 's'} matched — " + summary = (f"{len(fresh)} new email{'' if len(fresh) == 1 else 's'} matched. " f"{counts['inserted']} row{'' if counts['inserted'] == 1 else 's'} written") if notes: - summary += f" — {notes[0][:100]}" + summary += f". {notes[0][:100]}" entry = _commit_run(rt, auto_id, "ok" if not notes else "partial", summary, counts, True, affected=list(merged)[:200]) trigger_fire(rt, tenant, auto_id, log=log) @@ -13106,7 +14168,7 @@ def compose_sentence(defn): n = sum(1 for _ in walk_actions((defn.get("flow") or {}).get("actions"))) tbl = cfg.get("targetTable") or trg.get("table") or "" body = ((f"run {n} action{'' if n == 1 else 's'}" + (f" on {tbl}" if tbl else "")) - if n else "do nothing yet — this automation has no actions") + if n else "do nothing yet. This automation has no actions") lanes = cfg.get("lanes") or [] tail = f", then route each record across {len(lanes)} lanes" if lanes else "" return f"{head}, {body}{tail}." @@ -13216,7 +14278,7 @@ def run_now(rt, tenant, auto_id, username="automation", log=print, rows=None): if a_counts.get("enrichMetricBatchesPending"): batches = int(a_counts["enrichMetricBatchesPending"]) state = "partial" if state != "error" else state - summary += (f" — {batches} post-engagement batch" + summary += (f". {batches} post-engagement batch" f"{'' if batches == 1 else 'es'} still building; Views and other " "metrics will be collected automatically without another paid read") if a_counts.get("enrichUnbound"): @@ -13225,7 +14287,7 @@ def run_now(rt, tenant, auto_id, username="automation", log=print, rows=None): # the sentence names the ONE thing that has to change, in the two places a person # can change it. The old behaviour was `ok` with an empty table. state = "partial" if state != "error" else state - summary += (" — the Instagram step did not run: this database has no profile " + summary += (". The Instagram step did not run: this database has no profile " "column. Name one on the step, or mark a text column as the " "Instagram profile" + _unbound_hint(rt, _flow_table(defn))) @@ -13236,21 +14298,21 @@ def run_now(rt, tenant, auto_id, username="automation", log=print, rows=None): # so a single sentence covering "the enrich step" would send them to the wrong # place half the time. Both may appear on one run, which is correct. state = "partial" if state != "error" else state - summary += (" — the TikTok step did not run: this database has no TikTok profile " + summary += (". The TikTok step did not run: this database has no TikTok profile " "column. Name one on the step, or mark a text column as a TikTok " "profile" + _unbound_hint(rt, _flow_table(defn))) if a_counts.get("ttEnrichBlocked"): state = "partial" if state != "error" else state tt_note = next((n for n in run_notes if "(TikTok): " in n), "") - summary += (f" — {int(a_counts['ttEnrichBlocked'])} TikTok profile read(s) were " + summary += (f". {int(a_counts['ttEnrichBlocked'])} TikTok profile read(s) were " "blocked" + (f". {_s(tt_note, 220)}" if tt_note else "")) if a_counts.get("enrichProfileBatchesPending"): # ⭐ The paid profile the vendor is still building. Said out loud so a run that # looks like a failure is read as the handoff it is — the tick finishes it. n = int(a_counts["enrichProfileBatchesPending"]) state = "partial" if state != "error" else state - summary += (f" — {n} profile read{'' if n == 1 else 's'} took longer than the " + summary += (f". {n} profile read{'' if n == 1 else 's'} took longer than the " "wait allows and will be collected automatically, at no extra cost") if a_counts.get("enrichBlocked"): state = "partial" if state != "error" else state @@ -13262,7 +14324,7 @@ def run_now(rt, tenant, auto_id, username="automation", log=print, rows=None): # reason. Two sentences quoting each other's vendor reason is worse than one. blocked_note = next((n for n in run_notes if ": " in n and "(TikTok): " not in n), "") - summary += (f" — {int(a_counts['enrichBlocked'])} profile read(s) were blocked" + summary += (f". {int(a_counts['enrichBlocked'])} profile read(s) were blocked" + (f". {_s(blocked_note, 220)}" if blocked_note else "")) # ⭐ WAVE 25 · C5 — A FULL TARGET IS A `partial` RUN THAT SAYS SO. D-11 made this the # law for the runners' OWN writes (`cap_note`), and `create_record` never joined: it @@ -13270,12 +14332,12 @@ def run_now(rt, tenant, auto_id, username="automation", log=print, rows=None): # looked exactly like one that had nothing to write. Same rule, same sentence shape. if a_counts.get("createCapped"): state = "partial" if state != "error" else state - summary = (f"{summary} — {a_counts['createCapped']} row(s) NOT created: a target " + summary = (f"{summary}. {a_counts['createCapped']} row(s) NOT created: a target " f"database is at its row cap") except Exception as e: # noqa: BLE001 log(f"[aios-auto] actions on {auto_id} failed: {type(e).__name__}: {e}") state = "partial" if state != "error" else state - summary = f"{summary} — the actions did not finish ({type(e).__name__})" + summary = f"{summary}. The actions did not finish ({type(e).__name__})" return _commit_run(rt, auto_id, state, summary, counts, state != "error", affected, steps, notes=run_notes) finally: