Deploy AIOS web (React glide grid + FastAPI slice)

RELEASES.json

@@ -1,6 +1,12 @@
 {
- "current": "v20 (442e4a1)",
+ "current": "v21 (5fdffce)",
  "releases": [
+  {
+   "version": "v21",
+   "sha": "5fdffce",
+   "date": "2026-08-09",
+   "subject": "release v21"
+  },
   {
    "version": "v20",
    "sha": "442e4a1",

VERSION

@@ -1 +1 @@
-v20 (442e4a1)
+v21 (5fdffce)

api/automation_engine.py

@@ -2252,18 +2252,32 @@ def _release(tenant, auto_id):
         _RUNNING.pop((tenant, str(auto_id)), None)
 
 
-def _commit_run(rt, auto_id, state, summary, counts, ok, affected=None, steps=None):
+def _commit_run(rt, auto_id, state, summary, counts, ok, affected=None, steps=None, notes=None):
     """THE ONE store write a run performs on the `automations` bucket.
 
     `steps` is the per-NODE outcome map the canvas paints its dots from. It is recorded here
     because it is a MEASUREMENT the runner took as it walked — see `graph`, which refuses to
     invent a node status when this map is absent (every run stored before W19-C has no `steps`,
     and painting those nodes green from the run's overall state would be a fabrication).
+
+    ⭐⭐ `notes` CLOSES DEBT D-103 (2026-08-09). A run's `counts` are integers and the
+    comprehension below drops everything else — so the per-record sentence a vendor gave us had
+    literally nowhere to live, and *"1 profile read(s) were blocked"* was the whole of what the
+    product could say. MEASURED on nurilab: the same record blocked on three separate runs and
+    the reason was unrecoverable from the store afterwards, so the diagnosis had to be rebuilt by
+    calling the vendors by hand. The note is the most valuable thing a run produces — a dead
+    handle, a vendor hiccup and an exhausted key are three different actions — and it was the one
+    thing thrown away.
+    ⚠ ON THE RUN, NOT ON THE RECORD. D-103's own prescription: no tenant table gains a column it
+    did not ask for, and W25/R4 already retired writing status STRINGS into people's grids.
     """
     entry = {"ts": _iso(), "ok": bool(ok), "summary": _s(summary, 400),
              "counts": {k: int(v) for k, v in (counts or {}).items()
                         if isinstance(v, (int, float))},
              "steps": {str(k): str(v) for k, v in (steps or {}).items()},
+             # Bounded on both axes: a 100-profile run must not put 100 sentences into a store
+             # entry that is kept 20 deep per automation.
+             "notes": [_s(n, 300) for n in (notes or []) if str(n or "").strip()][:25],
              "affected": list(affected or [])[:200]}
 
     def _up(cur):
@@ -2572,11 +2586,13 @@ POST_SNAPSHOT_FIELDS = [
 # and below `PACE_SECONDS`, so even if somebody later makes one of those reach-backs a
 # module-level import, the names it wants already exist and the cycle still resolves.
 from connectors_ig import (                                        # noqa: E402
-    BD_DS_COMMENTS, BD_DS_POSTS, BD_DS_REELS, BD_EXCLUDE_MAX, BD_PATH_SNAPSHOT,
+    BD_DS_COMMENTS, BD_DS_POSTS, BD_DS_PROFILES, BD_DS_REELS, BD_EXCLUDE_MAX, BD_PATH_SNAPSHOT,
     BD_RECORD_PRICE_SPEC,
-    _bd_comment, _bd_deferral, _bd_first_url, _bd_post_metrics, _bd_rows, _bd_tagged_location,
+    _bd_comment, _bd_deferral, _bd_first_url, _bd_post_metrics, _bd_profile, _bd_rows,
+    _bd_tagged_location,
     _first, _ig_int,
-    bd_call, bd_filter_rows, bd_filter_start, bd_filter_status, bd_ready, depth_refusal,
+    bd_call, bd_filter_rows, bd_filter_start, bd_filter_status, bd_ready,
+    bd_snapshot_progress, depth_refusal,
     ig_handle, pull_profile,
 )
 
@@ -6249,6 +6265,26 @@ DEFAULT_ENRICH_COOLDOWN_DAYS = 30
 #: discovery just found rather than re-walking the oldest leads in the book.
 DEFAULT_ENRICH_SORT = "first_found"
 
+#: ⭐⭐ 2026-08-09 (DEBT D-103) — WHERE A RUN'S PER-RECORD REASONS TRAVEL.
+#: A run's `counts` are integers and `_commit_run` drops everything non-numeric, so the sentence
+#: a vendor gave us had nowhere to ride and was thrown away at three separate layers. This key is
+#: a deliberate passenger IN the counts dict, popped by `run_now` before the counts are stored.
+#: ⛔ A RESERVED KEY, NOT A COUNT: it must never be rendered as one, which is why it starts with
+#: an underscore — `COUNT_LABELS` on the client is an allow-list and cannot pick it up by
+#: accident, and `_commit_run`'s numeric filter is the second net under it.
+RUN_NOTES_KEY = "_notes"
+#: How long a handle a VENDOR SAID DOES NOT EXIST is left alone before it is tried again.
+#: ⚠ NOT permanent, and not the success cooldown either. Permanent would be wrong — a handle can
+#: be renamed back or a suspension lifted — but re-buying a dead account every morning is what
+#: the owner reported ("blocked AGAIN"), so the floor is one paid attempt per handle per month
+#: instead of one per day. Editing the handle changes the key and retries immediately, which is
+#: the behaviour someone correcting a typo expects.
+NOT_FOUND_RETRY_DAYS = 30
+#: A queued profile snapshot the vendor never finishes is dropped after this, with a note. An
+#: unbounded pending list is the forever-loop this whole change exists to remove, wearing the
+#: opposite mask ([[gate-answers-the-wrong-question]]).
+PENDING_PROFILE_MAX_HOURS = 24
+
 
 def _order_key(value):
     """Order one CELL. Numbers numerically, everything else as text.
@@ -6286,7 +6322,41 @@ def _days_since(day, today=None):
     return ((today or _dt.date.today()) - d).days
 
 
-def enrich_selection(rt, table_key, cfg, profile_key, today=None):
+def _hours_since(stamp):
+    """Whole hours since a full ISO stamp, or None when it cannot be read.
+
+    ⚠ ISO, NOT `YYYY-MM-DD` — `_days_since` above answers a question in DAYS about a `date`
+    column and truncates to 10 characters. A pending snapshot's age is measured in hours and its
+    stamp carries a time, so reusing that function would read every entry as "queued at
+    midnight". Same reason its None means UNKNOWN: an unreadable stamp must not age a paid,
+    outstanding snapshot out of the queue.
+    """
+    import datetime as _dt
+    s = str(stamp or "").strip()
+    if not s:
+        return None
+    try:
+        t = _dt.datetime.fromisoformat(s.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    now = _dt.datetime.now(_dt.timezone.utc)
+    if t.tzinfo is None:
+        t = t.replace(tzinfo=_dt.timezone.utc)
+    return max(0, int((now - t).total_seconds() // 3600))
+
+
+def _gone_key(row, handle):
+    """The identity a "this account does not exist" verdict is remembered under.
+
+    `(platform, handle)` — wave 26 R4's dedup key, not the handle alone, because `@x` on
+    Instagram and `@x` on TikTok are two accounts. Blank platform means Instagram, which is what
+    every row on a preset profile table is and what `preset_cells` stamps.
+    """
+    plat = str((row or {}).get("platform") or PLATFORM_INSTAGRAM).strip().lower()
+    return f"{plat}:{str(handle or '').strip().lstrip('@').lower()}"
+
+
+def enrich_selection(rt, table_key, cfg, profile_key, today=None, gone=None):
     """⭐ 2026-08-07 (owner ruling) — WHICH records this enrich step spends on, in order.
 
     Returns `(ordered_row_ids, note)`. The note is the honest account of what the selection did
@@ -6403,12 +6473,32 @@ def enrich_selection(rt, table_key, cfg, profile_key, today=None):
     days = max(1, days)
 
     picked, cooled, blank_handle = [], 0, 0
+    # ⭐⭐ 2026-08-09 — HANDLES A VENDOR HAS ALREADY SAID DO NOT EXIST.
+    #
+    # ⛔ THE DEFECT THIS CLOSES IS STRUCTURAL, AND IT IS THE WORD "AGAIN" IN THE OWNER'S REPORT.
+    # A blocked read writes NO cells, so `enriched_at` stays unset, so `_days_since(None)` is
+    # None, so the cooldown above can never exclude the row — while `Followers is empty` keeps it
+    # in the Pending cohort by construction. MEASURED on nurilab: one dead handle, re-bought at
+    # 06:00 on three consecutive days, reported each time as an opaque "1 blocked". No vendor fix
+    # removes that loop; only a memory of the verdict does.
+    #
+    # ⚠ THEY ARE **NAMED**, NOT SILENTLY DROPPED. The whole point is that the owner can act — the
+    # note goes into the run every single time, not only on the run that discovered it, because a
+    # run that quietly reports "0 records walked" tomorrow puts them straight back at "wtf".
+    skipped_gone = []
     for rid, r in ordered:
         if len(picked) >= quota:
             break
-        if not str(r.get(profile_key) or "").strip():
+        raw_handle = str(r.get(profile_key) or "").strip()
+        if not raw_handle:
             blank_handle += 1
             continue
+        verdict = (gone or {}).get(_gone_key(r, raw_handle))
+        if isinstance(verdict, dict):
+            since_gone = _days_since(verdict.get("at"), today=today)
+            if since_gone is None or since_gone < NOT_FOUND_RETRY_DAYS:
+                skipped_gone.append(raw_handle)
+                continue
         if cooling:
             since = _days_since(r.get("enriched_at"), today=today)
             if since is not None and since < days:
@@ -6421,9 +6511,14 @@ def enrich_selection(rt, table_key, cfg, profile_key, today=None):
     # `run_plain` follow. Silence here would make a shrinking selection invisible.
     if cooled:
         notes.append(f"{cooled} skipped as enriched in the last {days} days")
+    if skipped_gone:
+        shown = ", ".join(f"@{h}" for h in skipped_gone[:5])
+        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"correct the handle; it is retried after {NOT_FOUND_RETRY_DAYS} days")
     if blank_handle:
         notes.append(f"{blank_handle} skipped with no handle")
-    if len(picked) < quota and (cooled or blank_handle or ordered):
+    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")
     return picked, "; ".join(notes)
 
@@ -6494,7 +6589,14 @@ def apply_actions(rt, defn, table_key, row_ids, username="automation", log=print
     # entry, so calling it per record is O(existing) per record — survivable at 5,000 rows and an
     # automation that never finishes at `MAX_UT_IG_ROWS`. One flush, three upserts.
     enrich = {"snaps": [], "posts": [], "psnaps": [], "comments": [], "pending": [],
+              # ⭐ 2026-08-09 — deferred PROFILE snapshots (paid, still building at the vendor)
+              # and handles a vendor has said do not exist. Both are collected across the whole
+              # walk and written once, for the same reason every other list here is.
+              "pendingProfiles": [], "gone": {},
               "profiles": 0, "ok": 0, "blocked": 0, "notes": [], "dry": False}
+    # The verdicts this automation already holds, read ONCE — `enrich_selection` consults them
+    # per record and re-reading the definition per row would be a store read per record.
+    known_gone = dict(((defn or {}).get("state") or {}).get("enrichNotFound") or {})
     # ⭐ 2026-08-07 — THE SELECTION, RESOLVED ONCE PER ACTION AND NOT ONCE PER RECORD.
     # `enrich_selection` sorts and scans the whole table; doing that inside the per-record walk
     # would be O(rows²) and, worse, would re-answer "which 25 records" every time a record walked
@@ -6630,7 +6732,7 @@ def apply_actions(rt, defn, table_key, row_ids, username="automation", log=print
                 # not this run's work, and the selection's own note already accounts for it.
                 aid = str(act.get("id") or "")
                 if aid not in enrich_plan:
-                    chosen, sel_note = enrich_selection(rt, table, cfg, pkey)
+                    chosen, sel_note = enrich_selection(rt, table, cfg, pkey, gone=known_gone)
                     enrich_plan[aid] = set(chosen)
                     if sel_note:
                         enrich["notes"].append(sel_note)
@@ -6642,6 +6744,10 @@ def apply_actions(rt, defn, table_key, row_ids, username="automation", log=print
                 if enrich["profiles"]:
                     time.sleep(PACE_SECONDS)       # >=2 s between profiles (R7), as the runner does
                 enrich["profiles"] += 1
+                # ⭐ THE DEFERRED-PROFILE SINK IS PER RECORD so the snapshot can be stamped with
+                # the row it belongs to: the collector writes preset cells back onto THAT record,
+                # and a run-wide list would have no way to say which handle each snapshot was for.
+                pend_prof = []
                 res = pull_profile(handle_raw,
                                    max_posts=cfg.get("maxPosts") or DEFAULT_POSTS_PER_PULL,
                                    log=log,
@@ -6650,7 +6756,12 @@ def apply_actions(rt, defn, table_key, row_ids, username="automation", log=print
                                    post_metrics=bool(cfg.get("postMetrics")),
                                    comment_metrics=bool(cfg.get("commentMetrics")),
                                    pending_metrics=(enrich["pending"]
+                                                    if not cfg.get("dryRun") else None),
+                                   pending_profile=(pend_prof
                                                     if not cfg.get("dryRun") else None))
+                for _p in pend_prof:
+                    _p["table"], _p["rowId"], _p["requestedAt"] = table, str(rid), _iso()
+                enrich["pendingProfiles"].extend(pend_prof)
                 pulled = _iso()
                 if res["state"] in ("ok", "partial"):
                     enrich["ok"] += 1
@@ -6671,7 +6782,19 @@ def apply_actions(rt, defn, table_key, row_ids, username="automation", log=print
                         _act_row_patch(patches, table, rid, cells)
                 else:
                     enrich["blocked"] += 1
-                    enrich["notes"].append(_s(res.get("note"), 90) or res["state"])
+                    # ⭐⭐ D-103 — THE NOTE IS NAMED AND KEPT AT FULL LENGTH.
+                    # It used to be `_s(note, 90)` with no handle attached: three runs blocked
+                    # the same record and the store could not say which record, let alone why.
+                    # 90 characters also truncated the one measured sentence mid-clause. This is
+                    # the most valuable thing the run produces and it now reaches the run entry.
+                    enrich["notes"].append(
+                        f"@{handle_raw}: {_s(res.get('note'), 300) or res['state']}")
+                    # A vendor STATING that the account does not exist is remembered, so the next
+                    # run stops paying to be told the same thing.
+                    if res.get("gone"):
+                        enrich["gone"][_gone_key(row, handle_raw)] = {
+                            "at": _iso(), "handle": handle_raw,
+                            "note": _s(res.get("note"), 300)}
             elif kind == "find_records":
                 found = find_records(rt, cfg.get("table"), cfg.get("cond"),
                                      int(cfg.get("limit") or 25))
@@ -6782,10 +6905,32 @@ def _enrich_flush(rt, defn, username, acc, log):
         # ⚠ IT IS A COUNT, not a flag, so `run_now`'s existing non-zero merge carries it without a
         # special case — and so the run entry itself records that this happened.
         return {"enrichUnbound": 1}
+    # ⭐⭐ 2026-08-09 — THE NOTES SURVIVE A RUN THAT READ NOTHING, and that is not a detail.
+    # `if not acc["profiles"]: return {}` is exactly the branch a run takes when EVERY candidate
+    # was skipped as a known-dead handle — so the sentence explaining why the automation appears
+    # to do nothing would have been dropped on precisely the runs that most need it, and the
+    # owner would be back at "0 records walked, wtf". The selection note is produced before any
+    # profile is read and must outlive that early return.
     if not acc.get("profiles"):
-        return {}
+        notes = list(acc.get("notes") or [])
+        return {RUN_NOTES_KEY: notes} if notes else {}
     out = {"enriched": acc["ok"], "enrichBlocked": acc["blocked"]}
+    if acc.get("notes"):
+        out[RUN_NOTES_KEY] = list(acc["notes"])
+    # ⭐ D-103's own prescription: "the block note survives on the RUN … not a status column, so
+    # no table gains a column it did not ask for". `RUN_NOTES_KEY` is that channel.
     if not acc.get("dry"):
+        # The vendor's not-found verdicts, merged into engine state (never a tenant column and
+        # never a status string — W25/R4 retired those). Merged rather than replaced: a run that
+        # walked one record must not forget what earlier runs learned about the others.
+        if acc.get("gone"):
+            merged = dict(((defn or {}).get("state") or {}).get("enrichNotFound") or {})
+            merged.update(acc["gone"])
+            set_state(rt, str(defn.get("id") or ""), {"enrichNotFound": merged})
+        pending_profiles = queue_pending_profile_snapshots(
+            rt, str(defn.get("id") or ""), acc.get("pendingProfiles") or [])
+        if pending_profiles:
+            out["enrichProfileBatchesPending"] = pending_profiles
         queued = queue_pending_metric_snapshots(rt, str(defn.get("id") or ""),
                                                 acc.get("pending") or [])
         if queued:
@@ -6924,6 +7069,189 @@ def queue_pending_metric_snapshots(rt, auto_id, pending):
     return added[0]
 
 
+def _pending_profile_tasks(defn):
+    """Validated, deduplicated deferred PROFILE snapshots from automation state.
+
+    ⭐⭐ ITS OWN LIST, NOT `pendingMetricSnapshots`, and the separation is load-bearing rather
+    than tidy. `_pending_metric_tasks` filters on `datasetId in {posts, reels, comments}` and
+    `kind in {posts, comments}` — so a profile entry appended to that list is silently dropped to
+    zero by its own validator, and even if it survived, the collector would hand it to
+    `_write_collected_metric_rows`, a posts/comments writer that has nothing to do with a profile
+    row. Reusing the name would have shipped a green no-op of exactly the class this change
+    exists to remove.
+
+    ⚠ A PROFILE TASK CARRIES ITS DESTINATION (`table` + `rowId`). A collected profile is written
+    back as PRESET CELLS onto the record that asked for it, so unlike a metric batch it cannot be
+    resolved from the handle alone: two databases may both hold `@x`.
+    """
+    raw = ((defn or {}).get("state") or {}).get("pendingProfileSnapshots") or []
+    out, seen = [], set()
+    for item in raw if isinstance(raw, list) else []:
+        if not isinstance(item, dict):
+            continue
+        sid = str(item.get("snapshotId") or "").strip()
+        dataset = str(item.get("datasetId") or "").strip()
+        handle = str(item.get("influencer") or "").strip().lstrip("@").lower()
+        table = str(item.get("table") or "").strip()
+        row_id = str(item.get("rowId") or "").strip()
+        # ⛔ `sd_` ONLY. A `snap_…` corpus id sent to `/datasets/v3/…` is a flat 404 about a
+        # snapshot that is alive (§2c), and a malformed id must never be handed back to a vendor
+        # endpoint at all.
+        if (not sid.startswith("sd_") or dataset != BD_DS_PROFILES or not handle
+                or not table or not row_id):
+            continue
+        if sid in seen:
+            continue
+        seen.add(sid)
+        out.append({"snapshotId": sid, "datasetId": dataset, "kind": "profile",
+                    "influencer": handle, "table": table, "rowId": row_id,
+                    "requestedAt": str(item.get("requestedAt") or ""),
+                    "lastChecked": str(item.get("lastChecked") or ""),
+                    "lastNote": _s(item.get("lastNote"), 200)})
+    return out
+
+
+def queue_pending_profile_snapshots(rt, auto_id, pending):
+    """Durably retain deferred profile snapshots. Starts no new paid request. Returns how many
+    were newly added."""
+    aid = str(auto_id or "").strip()
+    if not aid:
+        return 0
+    incoming = _pending_profile_tasks({"state": {"pendingProfileSnapshots": pending}})
+    if not incoming:
+        return 0
+    added = [0]
+
+    def _up(cur):
+        cur = cur if isinstance(cur, dict) else {}
+        definition = cur.get(aid)
+        if not isinstance(definition, dict):
+            return cur
+        state = definition.setdefault("state", {})
+        existing = _pending_profile_tasks(definition)
+        known = {x["snapshotId"] for x in existing}
+        for task in incoming:
+            if task["snapshotId"] not in known:
+                existing.append(task)
+                known.add(task["snapshotId"])
+                added[0] += 1
+        state["pendingProfileSnapshots"] = existing
+        return cur
+
+    rt.update(STORE_KEY, _up, flush="sync")
+    return added[0]
+
+
+def collect_pending_profile_snapshots(rt, defn, username="automation", log=print, step=_no_step):
+    """Finish deferred PROFILE reads the tenant has already paid for. Starts no new scrape.
+
+    ⭐⭐ 2026-08-09 — THE HALF THAT DID NOT EXIST. `bd_scrape` has always accepted a `deferred`
+    list, and every post/reel/comment call passed one; the PROFILE call did not, so a profile the
+    vendor took longer than `BD_SCRAPE_WAIT` to collect was billed and its snapshot id thrown
+    away — on every run, forever. MEASURED on nurilab: `collection_duration` 320 s against a
+    180 s budget, two abandoned `sd_…` snapshots in two runs.
+
+    ⛔ IT CLOSES A TASK THAT FINISHED EMPTY. A pending entry that can never resolve is the same
+    forever-loop wearing a different mask, so `bd_snapshot_progress` deciding `done` with zero
+    records ends the task with the vendor's reason attached — and, when the vendor blames the
+    target rather than itself, records the not-found verdict so the handle stops being re-bought.
+    """
+    tasks = _pending_profile_tasks(defn)
+    if not tasks:
+        return ("ok", "No pending profile reads.", {}, [], {"capture_paid": "idle"})
+    step(f"Collecting {len(tasks)} deferred profile read{'' if len(tasks) == 1 else 's'}")
+    remaining, patches, affected, notes = [], {}, [], []
+    acc = {"snaps": [], "posts": [], "psnaps": [], "comments": [], "pending": [],
+           "pendingProfiles": [], "gone": {}, "profiles": 0, "ok": 0, "blocked": 0,
+           "notes": [], "dry": False}
+    ready = waiting = closed = 0
+    for task in tasks:
+        stale_h = _hours_since(task.get("requestedAt"))
+        state, records, empty_note = bd_snapshot_progress(task["snapshotId"])
+        if state in ("done", "failed") and not records:
+            closed += 1
+            acc["profiles"] += 1
+            acc["blocked"] += 1
+            note = f"@{task['influencer']}: {_s(empty_note, 240)}"
+            notes.append(note)
+            acc["notes"].append(note)
+            # ⭐ `failed` = the vendor finished, collected nothing, and blamed the TARGET. On a
+            # profile request that means the account could not be reached at all, so the verdict
+            # is remembered and the selection stops re-buying it (`NOT_FOUND_RETRY_DAYS`).
+            # ⚠ `done`-with-zero is NOT remembered: "we found no matches" is a statement about
+            # the query, and turning it into "this account does not exist" would silently retire
+            # live handles.
+            if state == "failed":
+                acc["gone"][_gone_key({}, task["influencer"])] = {
+                    "at": _iso(), "handle": task["influencer"], "note": _s(empty_note, 300)}
+            continue
+        rows = []
+        if state != "running":
+            payload, err = bd_call(f"{BD_PATH_SNAPSHOT}/{task['snapshotId']}", {"format": "json"})
+            rows = _bd_rows(payload) if not err else []
+            if rows and (_bd_deferral(payload) or
+                         (len(rows) == 1 and str(rows[0].get("status") or "") in
+                          ("running", "building", "collecting"))):
+                rows = []
+        if not rows:
+            # ⚠ BOUNDED. A snapshot the vendor never finishes must not be polled until the end of
+            # time; after `PENDING_PROFILE_MAX_HOURS` it is dropped WITH a sentence, never
+            # silently. An unbounded queue is the forever-loop this change removes, inverted.
+            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"the next run will ask again")
+                notes.append(note)
+                acc["notes"].append(note)
+                continue
+            waiting += 1
+            remaining.append({**task, "lastChecked": _iso(),
+                              "lastNote": _s("still building", 200)})
+            continue
+        ready += 1
+        acc["profiles"] += 1
+        profile = _bd_profile(rows[0], task["influencer"])
+        if profile.get("followers") is None and profile.get("following") is None:
+            acc["blocked"] += 1
+            note = (f"@{task['influencer']}: the source delivered the profile but no "
+                    f"follower/following counts were readable in it")
+            notes.append(note)
+            acc["notes"].append(note)
+            continue
+        acc["ok"] += 1
+        res = {"state": "ok", "profile": profile, "posts": [], "comments": [],
+               "via": "brightdata:deferred", "note": ""}
+        pulled = _iso()
+        snap_row, idents, metric_rows, comment_rows = capture_rows(res, pulled)
+        acc["snaps"].append(snap_row)
+        acc["posts"].extend(idents)
+        acc["psnaps"].extend(metric_rows)
+        acc["comments"].extend(comment_rows)
+        _act_row_patch(patches, task["table"], task["rowId"], preset_cells(res, pulled))
+        affected.append(task["rowId"])
+        notes.append(f"@{task['influencer']}: collected the profile the source had already been "
+                     f"paid for ({profile.get('followers')} followers)")
+
+    set_state(rt, str(defn.get("id") or ""),
+              {"pendingProfileSnapshots": remaining or None})
+    counts = _enrich_flush(rt, defn, username, acc, log)
+    counts.pop(RUN_NOTES_KEY, None)                 # this function owns the note list below
+    counts.update(_commit_action_writes(rt, str(_flow_table(defn) or ""), patches, {},
+                                        username, log))
+    counts.update({"profileBatchesCollected": ready, "profileBatchesPending": waiting,
+                   "profileBatchesEmpty": closed})
+    if notes:
+        counts[RUN_NOTES_KEY] = notes
+    head = (f"{ready} deferred profile read{'' if ready == 1 else 's'} collected"
+            if ready else "no deferred profile read was ready")
+    tail = "".join([f"; {closed} finished with nothing to collect" if closed else "",
+                    f"; {waiting} still building" if waiting else ""])
+    state = "ok" if ready and not closed else "partial"
+    return (state, head + tail, counts, affected,
+            {"capture_paid": "ok" if ready else "partial", "write": "ok" if ready else "idle"})
+
+
 def _write_collected_metric_rows(rt, defn, username, idents, snapshots, comments, log):
     """Write a completed metric snapshot through the canonical Post/Comment graph once."""
     if not (idents or snapshots or comments):
@@ -6974,11 +7302,23 @@ def collect_pending_metric_snapshots(rt, defn, username="automation", log=print,
         return ("ok", "No pending post-engagement snapshots.", {}, [], {"capture_metrics": "idle"})
     step(f"Collecting {len(tasks)} post-engagement batch{'' if len(tasks) == 1 else 'es'}")
     remaining, idents, snapshots, comments = [], [], [], []
-    ready, waiting = 0, 0
+    ready, waiting, closed, closed_notes = 0, 0, 0, []
     for task in tasks:
+        # ⭐⭐ 2026-08-09 — ASK THE STATUS DOCUMENT, NOT THE ROWS. `building` used to be
+        # `not rows or …`, so a snapshot the vendor had FINISHED with zero records was re-queued
+        # as "still building" on every tick — forever, because nothing about it would ever
+        # change. That is the same forever-loop the profile path was measured in, one dataset
+        # over, and it was latent here the whole time.
+        state, records, empty_note = bd_snapshot_progress(task["snapshotId"])
+        if state in ("done", "failed") and not records:
+            # ⛔ CLOSED, NOT RE-QUEUED. The vendor is finished and there is nothing to collect;
+            # keeping the entry would be a pending task that can never resolve.
+            closed += 1
+            closed_notes.append(f"{task['influencer']}: {_s(empty_note, 160)}")
+            continue
         payload, note = bd_call(f"{BD_PATH_SNAPSHOT}/{task['snapshotId']}", {"format": "json"})
         rows = _bd_rows(payload) if not note else []
-        building = (not rows or _bd_deferral(payload) or
+        building = (state == "running" or not rows or _bd_deferral(payload) or
                     (len(rows) == 1 and str(rows[0].get("status") or "") in
                      ("running", "building", "collecting")))
         if building:
@@ -7014,14 +7354,25 @@ def collect_pending_metric_snapshots(rt, defn, username="automation", log=print,
               {"pendingMetricSnapshots": remaining or None})
     written = _write_collected_metric_rows(rt, defn, username, idents, snapshots, comments, log)
     counts = {"metricBatchesCollected": ready, "metricBatchesPending": waiting,
+              "metricBatchesEmpty": closed,
               "postEngagementSnapshots": written["snapshots"],
               "commentsCollected": written["comments"]}
+    # ⚠ THE RUNNER CONTRACT STAYS A 5-TUPLE and the notes ride in `counts` under the reserved
+    # `RUN_NOTES_KEY`, which `run_now` pops. Widening the tuple for one runner would make four
+    # other call sites disagree about the shape of a run — and `_commit_run` already drops
+    # non-numeric count values, so a pop that is ever missed degrades to today's behaviour rather
+    # than to a crash.
+    if closed_notes:
+        counts[RUN_NOTES_KEY] = closed_notes
+    # ⚠ THE EMPTY ONES ARE NAMED, not silently dropped. A batch that finished with no records is
+    # a real outcome the tenant paid for and it must read as an answer, not as a disappearance.
+    tail = (f"; {closed} finished with nothing to collect" if closed else "")
     if waiting:
         return ("partial",
                 f"{ready} post-engagement batch{'' if ready == 1 else 'es'} collected; "
-                f"{waiting} still building and will be collected automatically",
+                f"{waiting} still building and will be collected automatically{tail}",
                 counts, [], {"capture_metrics": "partial", "write": "ok"})
-    return ("ok", f"{ready} post-engagement batch{'' if ready == 1 else 'es'} collected",
+    return ("ok", f"{ready} post-engagement batch{'' if ready == 1 else 'es'} collected{tail}",
             counts, [], {"capture_metrics": "ok", "write": "ok"})
 
 
@@ -8740,12 +9091,27 @@ def run_now(rt, tenant, auto_id, username="automation", log=print, rows=None):
         # first and do not start another profile scrape while it is outstanding: re-running the
         # action would buy duplicate engagement reads and reintroduce the timeout this handoff
         # exists to remove.  The normal scheduler calls this path too via `pending_collect_ids`.
+        # ⭐ 2026-08-09 — THE PROFILE HANDOFF IS COLLECTED FIRST, for the same reason and one
+        # rung earlier: a profile snapshot the vendor is still building is paid work, and
+        # starting a fresh scrape for the same handle would buy the identical row a second time.
+        # Ahead of the metric collector because the profile IS the thing the run was asked for;
+        # the engagement batches hang off it.
+        if _pending_profile_tasks(defn):
+            state, summary, counts, affected, steps = collect_pending_profile_snapshots(
+                rt, defn, username=username, log=log,
+                step=lambda text: _step(tenant, auto_id, text))
+            return _commit_run(rt, auto_id, state, summary,
+                               {k: v for k, v in counts.items() if k != RUN_NOTES_KEY},
+                               state != "error", affected, steps,
+                               notes=counts.get(RUN_NOTES_KEY))
         if _pending_metric_tasks(defn):
             state, summary, counts, affected, steps = collect_pending_metric_snapshots(
                 rt, defn, username=username, log=log,
                 step=lambda text: _step(tenant, auto_id, text))
-            return _commit_run(rt, auto_id, state, summary, counts, state != "error", affected,
-                               steps)
+            return _commit_run(rt, auto_id, state, summary,
+                               {k: v for k, v in counts.items() if k != RUN_NOTES_KEY},
+                               state != "error", affected, steps,
+                               notes=counts.get(RUN_NOTES_KEY))
         runner = RUNNERS.get(defn.get("kind"))
         if runner is None:
             return _commit_run(rt, auto_id, "error",
@@ -8779,9 +9145,17 @@ def run_now(rt, tenant, auto_id, username="automation", log=print, rows=None):
         # A failing action must not fail the RUN: the machine steps already wrote their rows and
         # reporting that as an error would misdescribe what happened. It degrades to `partial`
         # with the reason in the summary — the cap_note discipline.
+        # ⚠ BOUND BEFORE THE `try`. The `except` below falls through to the same `_commit_run`,
+        # which now reads this name — an assignment only on the success path would turn any
+        # action failure into a NameError inside the handler that exists to prevent exactly that.
+        run_notes = []
         try:
             a_counts = apply_actions(rt, defn, _flow_table(defn), affected or [],
                                      username=username, log=log)
+            # ⭐⭐ D-103 — POPPED BEFORE THE MERGE. The per-record reasons ride inside `counts` so
+            # the runner contract keeps its shape, and they must leave before the merge or they
+            # would be a "count" everywhere downstream.
+            run_notes = list(a_counts.pop(RUN_NOTES_KEY, None) or [])
             counts = {**(counts or {}), **{k: v for k, v in a_counts.items() if v}}
             if a_counts.get("enrichMetricBatchesPending"):
                 batches = int(a_counts["enrichMetricBatchesPending"])
@@ -8798,9 +9172,22 @@ def run_now(rt, tenant, auto_id, username="automation", log=print, rows=None):
                 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")
+            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 "
+                            "wait allows and will be collected automatically, at no extra cost")
             if a_counts.get("enrichBlocked"):
                 state = "partial" if state != "error" else state
-                summary += f" — {int(a_counts['enrichBlocked'])} profile read(s) were blocked"
+                # ⭐⭐ D-103 — THE REASON IS IN THE SENTENCE, not only behind a click. "1 profile
+                # read(s) were blocked" is the exact string the owner read three mornings running
+                # before asking "wtf is going on"; it names a quantity and withholds the one
+                # thing that would let anybody act. The first note is the vendor's own words.
+                blocked_note = next((n for n in run_notes if ": " in n), "")
+                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
             # logged the cap and rolled up `ok`, so a flow that had silently stopped writing
@@ -8814,7 +9201,7 @@ def run_now(rt, tenant, auto_id, username="automation", log=print, rows=None):
             state = "partial" if state != "error" else state
             summary = f"{summary} — the actions did not finish ({type(e).__name__})"
         return _commit_run(rt, auto_id, state, summary, counts, state != "error", affected,
-                           steps)
+                           steps, notes=run_notes)
     finally:
         _release(tenant, auto_id)
 
@@ -8857,7 +9244,12 @@ def pending_collect_ids(rt):
             continue
         pending_discovery = (d.get("kind") == "discover_instagram"
                              and str((d.get("state") or {}).get("pendingSnapshot") or "").strip())
-        if pending_discovery or _pending_metric_tasks(d):
+        # ⭐ 2026-08-09 — PROFILE handoffs join the other two. Without this line the profile
+        # deferral would be stored and never collected, which is the same defect it fixes wearing
+        # a queue: `due_ids` only returns SCHEDULED automations, and the automation this was
+        # measured on is `trigger: manual`. A capability written down but never walked is what
+        # this whole change is about, so it must not be reintroduced one function later.
+        if pending_discovery or _pending_metric_tasks(d) or _pending_profile_tasks(d):
             out.append(aid)
     return sorted(out)
 

api/connectors_ig.py

@@ -237,6 +237,16 @@ BD_DS_COMMENTS = "gd_ltppn085pokosxh13"        # Instagram Comments: opt-in full
 BD_PATH_SCRAPE = "/datasets/v3/scrape"        # SYNC: rows come back inline. param: dataset_id
 BD_PATH_TRIGGER = "/datasets/v3/trigger"      # ASYNC: -> {"snapshot_id": "sd_…"}
 BD_PATH_SNAPSHOT = "/datasets/v3/snapshot"    # /<sd_id>?format=json -> the rows
+#: ⭐⭐ 2026-08-09 — THE SNAPSHOT'S OWN STATUS DOCUMENT, and asking it is the difference between
+#: "the vendor is still working" and "the vendor finished and collected nothing". MEASURED on
+#: `sd_msl80v7l1ti14rhcd6` (nurilab's `roxyfoxypinky`): `{"status": "ready", "records": 0,
+#: "errors": 1, "error_codes": {"crawl_error": 1}, "collection_duration": 320513}`. The rows
+#: endpoint answers `[]` for that snapshot forever, which `bd_scrape`'s old `if rows:` poll could
+#: not distinguish from a snapshot mid-build — so it burned its whole budget and then reported
+#: *"the records are collected, not lost"* about a batch that had collected nothing at all.
+#: ⛔ SCRAPER NAMESPACE ONLY (`sd_…`). The corpus has no twin here; its status is
+#: `BD_PATH_FILTER_SNAPSHOT/<snap_id>`, and crossing the two 404s (§2c).
+BD_PATH_PROGRESS = "/datasets/v3/progress"    # /<sd_id> -> {status, records, errors, error_codes}
 BD_PATH_FILTER = "/datasets/filter"           # ⚠ NO /v3/ — the CORPUS query (discovery)
 BD_PATH_FILTER_SNAPSHOT = "/datasets/snapshot"        # /<snap_id> -> status
 #: A sync scrape MEASURED at 15–23 s for one URL and ~40 s for two, so the timeout is generous;
@@ -860,6 +870,64 @@ def _bd_deferral(payload):
     return ""
 
 
+def bd_snapshot_progress(sid):
+    """One scraper snapshot's status. `(state, records, note)`.
+
+    state ∈ `running` | `done` | `failed` | `unknown`:
+      · `running` — the vendor is still collecting; poll again.
+      · `done`    — finished. `records` says whether it produced anything.
+      · `failed`  — finished, produced NOTHING, and the vendor blamed the TARGET (an
+                    `error_codes` entry such as `crawl_error`). On a profile request that is the
+                    vendor saying it could not reach that account at all, which is a different
+                    action from "we found no matches" — so it is a distinct state rather than a
+                    phrase inside the note. A caller that has to grep an English sentence to
+                    decide what happened is a caller whose behaviour changes when someone
+                    improves the wording.
+      · `unknown` — the status call itself did not answer; fall back to probing the rows.
+
+    ⭐⭐ 2026-08-09 — THE QUESTION `bd_scrape` COULD NOT ASK. Its poll loop advanced only on
+    `if rows:`, so a snapshot the vendor had FINISHED with zero records looked byte-for-byte like
+    one still building: the rows endpoint answers `[]` in both cases. MEASURED on nurilab's one
+    pending handle — `status: ready, records: 0, errors: 1, crawl_error: 1` after 320 s — while
+    the enrich run reported *"deferred … the records are collected, not lost"*, which was false
+    about that batch and had been re-reported on three separate runs.
+
+    ⛔ `unknown` IS NOT `done`, and the distinction is the whole reason this returns three states
+    rather than a boolean. When the status call itself fails we must fall back to the old
+    row-probing behaviour, not conclude the snapshot is empty — an unreachable status endpoint
+    would otherwise turn every deferral into a confident "the vendor found nothing".
+
+    ⚠ THE NOTE IS DELIBERATELY VENDOR-NEUTRAL about WHAT was being read. This serves profile,
+    post, reel and comment snapshots alike; a sentence naming "the account" would be wrong on
+    three of the four, and the caller knows which it asked for.
+    """
+    payload, err = bd_call(f"{BD_PATH_PROGRESS}/{sid}", None, None)
+    if err or not isinstance(payload, dict):
+        return "unknown", 0, ""
+    status = str(payload.get("status") or "").strip().lower()
+
+    def _n(key):
+        try:
+            return int(payload.get(key) or 0)
+        except (TypeError, ValueError):
+            return 0
+
+    records, errors = _n("records"), _n("errors")
+    if status not in ("ready", "done", "failed", "error"):
+        return "running", records, ""
+    if records > 0:
+        return "done", records, ""
+    codes = payload.get("error_codes")
+    named = (", ".join(f"{str(k).replace('_', ' ')} x{v}"
+                       for k, v in sorted(codes.items()))
+             if isinstance(codes, dict) and codes else "")
+    if errors or named or status in ("failed", "error"):
+        return "failed", 0, ("the source finished this request and collected nothing"
+                             + (f" — it reported {named}" if named else "")
+                             + "; the target is unreachable, private, or no longer exists")
+    return "done", 0, "the source finished this request and found no records for it"
+
+
 def bd_scrape(dataset_id, urls, wait=None, deferred=None):
     """Scrape a batch. `(rows, note)`; a note means it did not answer.
 
@@ -881,15 +949,22 @@ def bd_scrape(dataset_id, urls, wait=None, deferred=None):
     budget = BD_SCRAPE_WAIT if wait is None else float(wait)
     waited = 0.0
     while True:
-        got, gnote = bd_call(f"{BD_PATH_SNAPSHOT}/{sid}", {"format": "json"})
-        if not gnote:
-            rows = _bd_rows(got)
-            # The status document is itself JSON, so "did it deliver?" is decided by whether
-            # what came back looks like ROWS — never by the HTTP code.
-            if rows and not _bd_deferral(got) and not (
-                    len(rows) == 1 and str(rows[0].get("status") or "") in
-                    ("running", "building", "collecting")):
-                return rows, ""
+        # ⭐ THE STATUS DOCUMENT IS ASKED FIRST, because it is the only surface that can say
+        # "finished, and there was nothing". Fetching rows while the vendor is still collecting
+        # is also a wasted call on every single poll.
+        state, records, empty_note = bd_snapshot_progress(sid)
+        if state in ("done", "failed") and not records:
+            return [], empty_note          # a definitive EMPTY, never our timeout sentence
+        if state != "running":
+            got, gnote = bd_call(f"{BD_PATH_SNAPSHOT}/{sid}", {"format": "json"})
+            if not gnote:
+                rows = _bd_rows(got)
+                # The status document is itself JSON, so "did it deliver?" is decided by whether
+                # what came back looks like ROWS — never by the HTTP code.
+                if rows and not _bd_deferral(got) and not (
+                        len(rows) == 1 and str(rows[0].get("status") or "") in
+                        ("running", "building", "collecting")):
+                    return rows, ""
         if waited >= budget:
             break
         time.sleep(BD_SCRAPE_POLL)
@@ -927,6 +1002,17 @@ APIFY_ACTOR_POSTS = os.environ.get("AIOS_APIFY_ACTOR") or "apify~instagram-scrap
 APIFY_WAIT = float(os.environ.get("AIOS_APIFY_WAIT") or 240)
 
 
+#: ⭐⭐ THE ONE SENTENCE FOR "THIS HANDLE HAS NO ACCOUNT BEHIND IT", named rather than inlined so
+#: that the engine can recognise it and act on it. A vendor saying *not found* is categorically
+#: different from a vendor being slow, rate-limited or out of credit: the first will never
+#: succeed however many times it is retried, and every retry is billed. `pull_profile` promotes
+#: a rung that returns this into `res["gone"]`, which is what lets a run stop re-buying a dead
+#: handle every morning ([[flag-shipped-without-its-writer]] — the flag needs a writer AND a
+#: reader, so both are in this file's call graph).
+ACCOUNT_GONE_NOTE = ("Instagram has no account with that handle — the source reports it does "
+                     "not exist (it may have been deleted, renamed, or suspended)")
+
+
 def apify_key():
     """The key, or ''. Read fresh every call, exactly as `bd_key` is."""
     return (os.environ.get("AIOS_APIFY_KEY") or "").strip()
@@ -1022,6 +1108,25 @@ def apify_profile(handle):
         return None, "Apify's answer was not readable JSON"
     if not isinstance(items, list) or not items:
         return None, "Apify answered with no profile for that handle"
+    # ⭐⭐ 2026-08-09 — THE VENDOR'S ERROR ENVELOPE IS AN ANSWER, AND IT WAS BEING THROWN AWAY.
+    # MEASURED on nurilab's one pending handle: Apify returned
+    # `{"url": …, "username": "roxyfoxypinky", "error": "not_found",
+    #   "errorDescription": "Post does not exist"}` — a 200, a well-formed item, and the single
+    # most useful sentence any provider produced about that account. `normalize_profile_apify`
+    # mapped it into a "profile" carrying username + url, this function returned `(prof, "")`
+    # meaning SUCCESS, and the caller — finding no follower count on it — recorded the useless
+    # `apify: answered without follower counts`. Three runs asked, three runs were told, and the
+    # owner still could not find out why the row was blank.
+    # ⚠ `error` RIDES EVERY ITEM AS `null` on the success path (measured on `sriyynntt`), so the
+    # test must be truthiness, never key presence.
+    # ⚠ AND THE VENDOR'S OWN WORDING IS NOT REPEATED VERBATIM: it says "Post does not exist" for
+    # a PROFILE url, which describes the wrong kind of object to anyone reading a profile row.
+    err = str((items[0] or {}).get("error") or "").strip()
+    if err:
+        desc = str((items[0] or {}).get("errorDescription") or "").strip()
+        if err in ("not_found", "not-found", "notfound"):
+            return None, ACCOUNT_GONE_NOTE
+        return None, f"the source could not read that account ({desc or err})"
     prof = providers.normalize_profile_apify(items[0])
     if not prof:
         return None, "Apify's profile row was not readable"
@@ -1109,7 +1214,8 @@ def _tag_metric_deferrals(items, start, kind, influencer_key):
 
 
 def pull_profile_bd(url, max_posts=None, post_metrics=False,
-                    comment_metrics=False, log=print, pending_metrics=None):
+                    comment_metrics=False, log=print, pending_metrics=None,
+                    pending_profile=None):
     """The paid rung: one profile, EXACT counts, plus the top posts the anonymous surface hides.
 
     Same return contract as `pull_profile` (`{state, profile, posts, via, note}`) so the runner
@@ -1134,7 +1240,17 @@ def pull_profile_bd(url, max_posts=None, post_metrics=False,
     if not handle:
         return {"state": "error", "note": f"{url!r} is not an Instagram profile URL",
                 "profile": {}, "posts": [], "comments": [], "via": ""}
-    rows, note = bd_scrape(BD_DS_PROFILES, [f"https://www.instagram.com/{handle}/"])
+    # ⭐⭐ 2026-08-09 — THE PROFILE SCRAPE NOW HANDS ITS DEFERRAL OVER, and until today it was the
+    # ONLY `bd_scrape` caller that did not. Every post, reel and comment call below passes
+    # `deferred=pending_metrics`; this one passed nothing, so a profile the vendor took longer
+    # than `BD_SCRAPE_WAIT` to collect was BILLED and its snapshot id discarded — on every run,
+    # forever. MEASURED on nurilab: two runs, two fresh `sd_…` snapshots, both abandoned, the
+    # second at a vendor-reported `collection_duration` of 320 s against our 180 s budget.
+    # That is [[artifact-with-no-importer]] in a function signature: the parameter existed, the
+    # machinery to collect it existed, and nothing handed the list in.
+    _deferred = []
+    rows, note = bd_scrape(BD_DS_PROFILES, [f"https://www.instagram.com/{handle}/"],
+                           deferred=_deferred)
     node = rows[0] if rows else {}
     profile = _bd_profile(node, handle) if node else {}
     unreadable = profile.get("followers") is None and profile.get("following") is None
@@ -1168,7 +1284,16 @@ def pull_profile_bd(url, max_posts=None, post_metrics=False,
                     f"the vendor's pre-collected profile corpus — the values are its last "
                     f"capture, not a read taken just now")
         else:
+            # ⭐ THE DEFERRAL IS REGISTERED ONLY WHEN THE PAID RUNG GIVES UP. If the corpus
+            # answered we already have the profile, and queueing a second write of the same
+            # identity would add churn for a row we did not need. Here we have nothing — and the
+            # snapshot is both paid for and the freshest answer that will ever exist for this
+            # handle, so it is the one thing worth carrying forward.
+            if isinstance(pending_profile, list):
+                for d in _deferred:
+                    pending_profile.append({**d, "kind": "profile", "influencer": handle})
             return {"state": "blocked", "profile": {}, "posts": [], "comments": [], "via": "brightdata",
+                    "deferredProfile": [d.get("snapshotId") for d in _deferred],
                     "note": f"{scrape_note}; the profile corpus did not answer either ({cnote})"}
     if profile.get("followers") is None and profile.get("following") is None:
         # It answered 200 with something we could not read. Say THAT — not "0 followers".
@@ -1621,7 +1746,8 @@ def bd_filter_rows(snapshot_id):
 
 def pull_profile(url, max_posts=None, log=print, tier="anonymous",
                  fallback=True,
-                 post_metrics=False, comment_metrics=False, pending_metrics=None):
+                 post_metrics=False, comment_metrics=False, pending_metrics=None,
+                 pending_profile=None):
     """Everything readable about one public profile, cheapest-honest rung last.
 
     Returns `{state, profile, posts, via, note}` with state ∈ ok | partial | blocked | error.
@@ -1650,14 +1776,23 @@ def pull_profile(url, max_posts=None, log=print, tier="anonymous",
         return {"state": "error", "note": f"{url!r} is not an Instagram profile URL",
                 "profile": {}, "posts": [], "comments": [], "via": ""}
     attempts = []
+    # ⭐ 2026-08-09 — SET BY A RUNG THAT SAW A VENDOR SAY *this account does not exist*. It rides
+    # out on the result so the engine can stop re-buying a dead handle every morning; it is never
+    # inferred from a mere failure, only from a vendor stating it.
+    gone = ""
 
     if clean_tier(tier) == "brightdata":
         paid = pull_profile_bd(url, max_posts=max_posts, post_metrics=post_metrics,
                                comment_metrics=comment_metrics, log=log,
-                               pending_metrics=pending_metrics)
+                               pending_metrics=pending_metrics,
+                               pending_profile=pending_profile)
         if paid["state"] in ("ok", "partial"):
             return paid
-        attempts.append(f"brightdata:{_s(paid.get('note'), 90)}")
+        # ⚠ 200, NOT 90. This string is the ONLY account of what the vendor said, and at 90 the
+        # measured sentence truncated to *"…was not ready within"* — mid-clause, with the budget
+        # and the snapshot id cut off. A reason nobody can read is the reason being discarded
+        # with extra steps (D-103).
+        attempts.append(f"brightdata:{_s(paid.get('note'), 200)}")
         # ⭐ THE APIFY RUNG (owner report 2026-08-09: "both Bright Data and Apify working in
         # tandem"). `providers.py` has declared `ig_profile -> ("brightdata", "apify")` since
         # 2026-08-08 and nothing ever walked it: Bright Data failing went straight to the
@@ -1678,13 +1813,20 @@ def pull_profile(url, max_posts=None, log=print, tier="anonymous",
                         "via": "apify",
                         "note": ("Bright Data could not read this profile "
                                  f"({_s(paid.get('note'), 90)}), so it came from Apify")}
-            attempts.append(f"apify:{_s(a_note or 'answered without follower counts', 90)}")
+            # ⭐ A VENDOR SAYING *not found* IS THE ANSWER, NOT A FAILED ATTEMPT. Recorded here
+            # and carried to whichever return this walk reaches, so the run can say the one thing
+            # that ends the loop instead of the fourth variation on "we could not read it".
+            if a_note == ACCOUNT_GONE_NOTE:
+                gone = a_note
+            attempts.append(f"apify:{_s(a_note or 'answered without follower counts', 200)}")
             time.sleep(PACE_SECONDS)
         if not fallback:
             return {"state": "blocked", "profile": {}, "posts": [], "comments": [],
-                    "via": "brightdata",
-                    "note": "the paid rungs did not answer and the anonymous fallback is turned "
-                            f"off for this automation ({'; '.join(attempts) or 'blocked'})"}
+                    "via": "brightdata", "gone": bool(gone),
+                    "note": (gone + " (the anonymous fallback is turned off for this automation)"
+                             if gone else
+                             "the paid rungs did not answer and the anonymous fallback is turned "
+                             f"off for this automation ({'; '.join(attempts) or 'blocked'})")}
         time.sleep(PACE_SECONDS)
 
     # RUNG 1 — the web client's own profile endpoint. Public, no cookie; the one that used to
@@ -1758,6 +1900,15 @@ def pull_profile(url, max_posts=None, log=print, tier="anonymous",
             return {"state": "partial", "profile": profile, "posts": [], "via": "og:description",
                     "note": "counts are the page's own abbreviations; media is not anonymously "
                             "readable (" + ", ".join(attempts) + ")"}
+    # ⭐⭐ THE DEFINITIVE ANSWER WINS OVER THE LAST RUNG'S SHRUG. If a vendor said the account does
+    # not exist and the free rungs then also found nothing, the honest report is *"this account
+    # does not exist"* — not *"nothing anonymously readable"*, which is a statement about US.
+    # ⚠ It is checked HERE, after the free rungs have run, and not as an early return: an
+    # anonymous read that DOES succeed above proves the vendor wrong and returns `ok`/`partial`
+    # on its own. A vendor's not-found is strong evidence, never a reason to stop looking.
+    if gone:
+        return {"state": "blocked", "profile": {}, "posts": [], "via": "", "gone": True,
+                "note": f"{gone}. Nothing else could read it either ({', '.join(attempts)})"}
     if status in (401, 403, 429) or status == 0:
         return {"state": "blocked", "profile": {}, "posts": [], "via": "",
                 "note": f"Instagram refused the anonymous read ({', '.join(attempts)})"}

api/odoo_relational.py

@@ -139,6 +139,25 @@ def customer_fields():
          "default": True,
          "rollup": {"link": "invoices", "field": "due_date", "fn": "latest",
                     "sortBy": "due_date", "sortDir": "asc"}},
+        # ⭐ THE READ-THROUGH ROLLUP — the column C8 said this substrate "cannot host", now hosted
+        # WITHOUT hosting the rows (owner 2026-08-09). It names a governed TOPIC and a METRIC KEY;
+        # `rollup_sql` answers every customer in ONE grouped query against DuckDB.
+        # MEASURED: 1,748 customers over 256,810 order lines in 232 ms, and PARITY-PROVEN at
+        # 1,716/1,716 customers TO THE CENT against the topic's own scope.
+        #
+        # ⛔ IT DOES NOT AND CANNOT COME FROM `ut_odoo_invoices`. That table is OPEN AR only
+        # (`_AR_WHERE` filters `payment_state IN ('not_paid','partial')`), so a rollup over the
+        # `invoices` link would sum UNPAID invoices and call it sales — a wrong number that looks
+        # right. Different question, different source; stated so nobody "simplifies" it later.
+        #
+        # ⚠ `revenue_invoiced` is ORDER-LINE revenue narrowed by the order's fully-invoiced flag —
+        # NOT posted-invoice billing (that is `customer_invoices`, a different topic which says so
+        # itself). The metric KEY carries that distinction; this field only names the key, which is
+        # the whole reason it may not carry SQL of its own.
+        {"key": "sales_ytd", "label": "Sales YTD - invoiced", "type": "rollup",
+         "source": "overlay", "default": True, "agg": "sum",
+         "rollup": {"source": {"topic": "sales_lines", "measure": "revenue_invoiced",
+                               "groupBy": "order_partner", "on": JOIN_KEY, "window": "ytd"}}},
         {"key": "refreshed", "label": "Refreshed", "type": "date", "source": "overlay",
          "default": False},
     )]

api/providers.py

@@ -348,6 +348,18 @@ def normalize_profile_apify(row):
     """
     if not isinstance(row, dict):
         return None
+    # ⛔ AN ERROR ENVELOPE IS NOT A PROFILE (measured 2026-08-09). Apify answers a dead handle
+    # with a 200 and a well-formed item — `{"username": …, "error": "not_found",
+    # "errorDescription": "Post does not exist"}` — and this function used to build a "profile"
+    # out of it: a username, a url and a source_payload, with every measured field absent. It
+    # then read to the caller as a vendor that answered, so the reason was replaced by a shrug.
+    # Refused HERE as well as in `connectors_ig.apify_profile` on purpose: the boundary rule this
+    # module exists for is that nothing downstream ever sees a vendor-shaped key, and a vendor's
+    # ERROR shape is the one that must never become a row.
+    # ⚠ TRUTHINESS, NOT KEY PRESENCE — a successful item carries `error: null` (measured on
+    # `sriyynntt`), so `"error" in row` would refuse every good profile.
+    if row.get("error"):
+        return None
     handle = str(row.get("username") or "").strip()
     if not handle:
         return None

api/rollup_sql.py

@@ -0,0 +1,164 @@
+"""rollup_sql.py — the READ-THROUGH rollup: one grouped SQL query answers every parent row.
+
+⛔ WHY THIS EXISTS. A linked rollup folds rows that live in the store, and `MAX_ROWS = 5000`
+bounds them for a measured reason: every `ut_*` table lives inside ONE `user_tables.json` that is
+parsed and deep-copied on essentially every request (MEASURED 2026-08-09 on nurilab — 5.1 MB /
+1,567 rows = 67 ms per copy, and rendering a 91-row table still pays for all of it). Royal's
+254k+ order lines cannot live there and never will: at that density the blob is ~829 MB and one
+deep copy is ~9.8 s.
+
+⭐ SO THIS KIND NEVER COPIES THE ROWS AT ALL. It names a governed semantic TOPIC and a METRIC KEY,
+and `store_query(..., group_by=[dim])` answers EVERY parent in one pass against DuckDB.
+MEASURED: 1,748 customers over 256,810 order lines in **232 ms**. The row count stops being the
+product's problem and becomes the database's, which is the whole of D-87's "read-through binding".
+
+⚠ A METRIC KEY, NEVER A FILTER FRAGMENT — the decision this module is built around.
+`model/metrics/*.yml` already carries each metric's scope, its `store_filter_sql` AND the matching
+`live_domain`, whose own comment reads *"BOTH or store_parity compares two different questions"*.
+Binding a rollup to the KEY inherits the scope and the live-parity oracle for free. Letting a
+rollup carry SQL would mint a second definition of a number the semantic layer exists to define
+once, and the two would drift in silence.
+
+⛔ TRUNCATION IS A WRONG NUMBER HERE, NOT A SHORT LIST. A row window is honest because counts and
+totals are computed over the full scope beside it; a GROUP window has no such companion — the
+groups ARE the answer. `store_query` now reports `truncated`, and this module REFUSES to write a
+single cell when it is set. Half a rollup is worse than none: it looks finished.
+"""
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+_PLATFORM = _HERE.parents[1] / "platform"
+for _p in (str(_HERE), str(_PLATFORM)):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+
+class RollupSourceError(Exception):
+    """The rollup could not be computed HONESTLY — no cells are written when this is raised."""
+
+
+def _ut():
+    import core.user_tables as user_tables
+    return user_tables
+
+
+def source_fields(table_def):
+    """Every source-backed rollup field on a table definition, in declaration order."""
+    out = []
+    for f in ((table_def or {}).get("fields") or []):
+        if not isinstance(f, dict) or f.get("type") != "rollup":
+            continue
+        bag = (f.get("rollup") or {}).get("source")
+        if isinstance(bag, dict) and bag.get("topic") and bag.get("measure"):
+            out.append(f)
+    return out
+
+
+def group_values(bag, today=None):
+    """`{group_id: value}` for one source bag — ONE grouped query over the whole scope.
+
+    ⚠ Keyed by the dim's `_id` column, never its label. Two customers can share a display name;
+    `partner_id` is what the parent row actually joins on.
+    """
+    from harness import semantic as sem
+    from harness import windows as W
+
+    topic = str(bag.get("topic") or "")
+    measure = str(bag.get("measure") or "")
+    dim = str(bag.get("groupBy") or "")
+    window = str(bag.get("window") or "").strip().lower()
+
+    date_from = date_to = None
+    if window and window != "all_time":
+        # ⚠ RESOLVED HERE, AGAINST `today`, not stored as a date pair. `harness.windows` owns what
+        # "ytd" means so there is one implementation; a literal year-start baked into the field
+        # would be right until 1 January and wrong afterwards with nothing to notice.
+        rng = W.resolve({"kind": window}, today or _today())
+        if rng is None:
+            raise RollupSourceError(
+                f"window {window!r} could not be resolved — refusing rather than widening this "
+                f"rollup to all time")
+        date_from, date_to = rng
+
+    try:
+        res = sem.store_query(topic, [measure], group_by=[dim],
+                              date_from=date_from, date_to=date_to,
+                              limit=sem.MAX_GROUPS, today=today)
+    except Exception as e:                                            # noqa: BLE001
+        raise RollupSourceError(f"{type(e).__name__}: {e}") from e
+
+    if res.get("truncated"):
+        # ⛔ THE REFUSAL THAT MATTERS. See the module header: a truncated GROUP set is a wrong
+        # answer per parent, not a shortened one, and it would look completely normal on screen.
+        raise RollupSourceError(
+            f"{topic}/{measure} grouped by {dim} exceeded {sem.MAX_GROUPS} groups — refusing to "
+            f"write cells from a truncated result")
+
+    id_col = f"{dim}_id"
+    out = {}
+    for row in res.get("rows") or []:
+        gid = row.get(id_col)
+        if gid is None:
+            continue
+        out[str(gid)] = row.get(measure)
+    return out
+
+
+def _today():
+    import datetime as _dt
+    return _dt.date.today().strftime("%Y-%m-%d")
+
+
+def compute(rt, table_key, today=None, tables=None):
+    """Write every source-backed rollup cell on `table_key`. Returns `{field_key: cells_written}`.
+
+    `tables` (a live `user_tables` dict) is the gate's injection point — the same shape
+    `automation_engine.compute_relation_cells` takes, so this can be proven against a fixture
+    without a store.
+    """
+    ut = _ut()
+    owned = tables is not None
+    blob = tables if owned else (rt.get(ut.STORE_KEY) or {})
+    tdef = (blob or {}).get(str(table_key)) or {}
+    fields = source_fields(tdef)
+    if not fields:
+        return {}
+
+    stamp = today or _today()
+    plans = []
+    for f in fields:
+        bag = f["rollup"]["source"]
+        # ⚠ Resolved BEFORE anything is written. A rollup that refuses must leave every cell as it
+        # was — a partially applied pass would mix two vintages of the same column.
+        plans.append((f["key"], str(bag.get("on") or ""), group_values(bag, today=stamp)))
+
+    written = {}
+
+    def _apply(cur):
+        t = cur.get(str(table_key))
+        if t is None:
+            return cur
+        rows = t.setdefault("rows", {})
+        for fkey, on, values in plans:
+            n = 0
+            for row in rows.values():
+                if not isinstance(row, dict):
+                    continue
+                join = str(row.get(on) or "").strip()
+                if not join:
+                    continue
+                # ⚠ int-ish join keys arrive as "5280" or 5280 depending on who wrote them.
+                hit = values.get(join)
+                if hit is None and join.endswith(".0"):
+                    hit = values.get(join[:-2])
+                row[fkey] = "" if hit is None else str(hit)
+                n += 1
+            written[fkey] = n
+        return cur
+
+    if owned:
+        _apply(blob)
+    else:
+        rt.update(ut.STORE_KEY, _apply, flush="async")
+    return written

api/routes_alerts.py

@@ -1,254 +1,254 @@
-"""routes_alerts.py — the Alerts module (wave 20, owner item 25, contract C-ALERT).
-
-    GET    /api/v1/alerts                  -> {alerts:[...]}
-    POST   /api/v1/alerts                  <- {viewId, topic, label?}
-    DELETE /api/v1/alerts/{alert_id}
-    POST   /api/v1/alerts/{alert_id}/run   -> evaluate now (the pane's manual refresh)
-    GET    /api/v1/notifications           -> {unread, items:[...]}
-    POST   /api/v1/notifications/read      <- {ids:[...]|null, read?:bool}
-
-The semantics — an alert is a view plus a remembered matched set, a notification is a NEW
-ENTRANT, and the first evaluation seeds silently — live in `core.alerts` with the reasoning.
-This file owns the two things a route must: WHO may do it, and HOW the view gets evaluated.
-
-⭐ **THE EVALUATION RUNS AS THE ALERT'S OWNER, NOT AS THE CALLER.** `_run_alert` builds the pool
-for `rec['owner']`, never for whoever tripped the write hook. Any other choice leaks: a
-full-access admin editing a cell would otherwise evaluate a BU-scoped user's alert over the whole
-book, and the notification would name customers that user may not see — a permission leak wearing
-a notification's clothes. The owner's own scope is the only correct basis for their alert.
-
-⚠ **AN ALERT IS NOT A SECOND READ PATH.** It resolves rows through the same
-`routes_customers.grid_assembly` / `routes_tables.ut_assembly` the grid uses, so a row that an
-alert can see is by construction a row its owner could open. Re-implementing the filter here
-would be a second definition of "matches", and those two would drift.
-"""
-from fastapi import APIRouter, Body, Depends
-
-import core.alerts as alerts
-from deps import Session, err, require_session
-
-router = APIRouter(prefix="/api/v1")
-
-#: The alert-bearing surfaces. `ut_` tables are admitted by prefix, like everywhere else.
-_TOPICS = ("customer", "product")
-
-
-def _topic_or_400(raw):
-    topic = str(raw or "").strip().lower()
-    if topic.startswith("ut_") or topic in _TOPICS:
-        return topic
-    raise err(400, "bad_topic", f"topic must be one of {', '.join(_TOPICS)} or a ut_ table")
-
-
-def _owner_session(session: Session, owner: str):
-    """A `Session` for the alert's OWNER (see the module note on why the owner, not the caller).
-
-    ⚠ `Session` exposes `uname`/`admin` as PROPERTIES derived from `user`, not as fields — so an
-    owner session is built by swapping the `user` RECORD and letting both derive themselves. An
-    earlier version passed `uname=`/`admin=` to the constructor, which would have raised on the
-    first write hook of the wave; the properties are the single definition of who a session is,
-    and going around them is how a session with an admin flag and a non-admin record exists.
-
-    Returns None when the owner is gone or deactivated — their alerts then stop evaluating rather
-    than evaluating as somebody else, which is the fail-closed direction.
-    """
-    import core.users as users
-
-    if str(owner) == str(session.uname):
-        return session
-    rec = (users.registry() or {}).get(str(owner))
-    if not isinstance(rec, dict) or not rec.get("active", True):
-        return None
-    # `_public` is THE definition of what a session may know about its own account (never a hash
-    # or a salt) — the same one `routes_auth` uses. Building the dict by hand here would be a
-    # second definition, and the one that leaks is always the copy.
-    return Session(tenant=session.tenant, user=users._public(str(owner), rec),
-                   claims=session.claims, runtime=session.runtime)
-
-
-def _evaluate(session: Session, rec: dict):
-    """Resolve `rec`'s view over its topic AS THE ALERT'S OWNER, then fold the result in."""
-    import aios_grid
-    from harness import filter_eval
-
-    owner_sess = _owner_session(session, rec.get("owner"))
-    if owner_sess is None:
-        return {"skipped": "owner_unavailable"}
-    topic = str(rec.get("topic") or "")
-    try:
-        if topic.startswith("ut_"):
-            from routes_tables import ut_assembly
-            g = ut_assembly(owner_sess, topic,
-                            storage_key=f"{owner_sess.tenant}:{topic}:{owner_sess.uname}")
-        else:
-            from routes_customers import grid_assembly
-            g = grid_assembly(owner_sess, scope=topic, consume_corrections=False)
-    except Exception as e:                                  # noqa: BLE001
-        return {"skipped": "unavailable", "detail": type(e).__name__}
-
-    view = (g.get("views") or {}).get(str(rec.get("viewId")))
-    if not isinstance(view, dict):
-        # Deleted, or un-shared out from under the alert. Say so on the RECORD rather than
-        # deleting the alert: an alert that silently vanishes is indistinguishable from one that
-        # never fires, and the user cannot debug what is not there.
-        return {"skipped": "view_missing"}
-
-    # The SAME row build the grid and `/customers` use — `rows_from_pool` is what puts derived
-    # and overlay values on a row. Evaluating a filter against raw pool dicts would silently
-    # never match any condition on a user-created or measure column.
-    rows = aios_grid.rows_from_pool(g["rows_src"], g["fields"], g["ws"].get("overlays"),
-                                    derived=g.get("derived"))
-    config = view.get("config") or view
-    ctx = filter_eval.EvalCtx(
-        cohort_sets={str(k): {str(p) for p in (v.get("memberPids") or ())}
-                     for k, v in (g.get("lists") or {}).items() if isinstance(v, dict)},
-        measure_sets=g.get("measure_sets") or {},
-        today=g.get("today"))
-    pids = filter_eval.visible_pids(config.get("filters") or [], rows, g["fields"], ctx,
-                                    member_pids=config.get("memberPids"))
-    labels = {str(r.get("pid")): str(r.get("name") or r.get("pid")) for r in rows}
-    return alerts.evaluate(rec.get("id"), [str(p) for p in pids],
-                           labels=labels, partial=False, st=session.runtime)
-
-
-@router.get("/alerts")
-def list_alerts(session: Session = Depends(require_session)):
-    return {"alerts": alerts.list_alerts(user=session.uname, is_admin=session.admin,
-                                         st=session.runtime)}
-
-
-@router.post("/alerts")
-def create_alert(body: dict = Body(default=None), session: Session = Depends(require_session)):
-    body = body or {}
-    view_id = str(body.get("viewId") or "").strip()
-    if not view_id:
-        raise err(400, "bad_view", "an alert needs the id of the view it watches")
-    topic = _topic_or_400(body.get("topic"))
-    _require_filtered_view(session, topic, view_id)
-    import uuid
-    aid = f"al_{uuid.uuid4().hex[:12]}"
-    rec = alerts.create(aid, view_id=view_id, topic=topic, owner=session.uname,
-                        label=body.get("label") or "", st=session.runtime)
-    # SEED IMMEDIATELY, so the alert starts from "everything currently matching is old news".
-    # Deferring this to the first write hook would mean the next edit announces the whole view.
-    outcome = _evaluate(session, rec)
-    return {"alert": {**rec, "seeded": True}, "first": outcome}
-
-
-def _require_filtered_view(session: Session, topic: str, view_id: str):
-    """400 unless `view_id` exists on `topic` AND actually narrows something.
-
-    ⛔ AN ALERT ON AN UNFILTERED VIEW IS SILENTLY INCAPABLE OF ALERTING, which is worse than one
-    that is refused. `filter_eval` treats an inactive tree as "no narrowing, every row shows"
-    (`visible_pids`'s own rule), so such an alert seeds with the entire table and can never see an
-    entrant again — there is nothing left to enter. The owner's words are *"when a Record gets
-    into that Filter's criteria"*: no criteria, no alert, and said at creation rather than
-    discovered by never being notified.
-
-    `is_rule_active` is the SAME activeness predicate the engine and the column tints use — a
-    half-typed rule is not a filter, and this must agree with what actually narrows or it would
-    accept a view whose one rule the engine then ignores.
-    """
-    from harness import filter_eval
-
-    try:
-        if topic.startswith("ut_"):
-            from routes_tables import ut_assembly
-            g = ut_assembly(session, topic,
-                            storage_key=f"{session.tenant}:{topic}:{session.uname}")
-        else:
-            from routes_customers import grid_assembly
-            g = grid_assembly(session, scope=topic, consume_corrections=False)
-    except Exception:                                       # noqa: BLE001
-        raise err(503, "unavailable", "the table is unavailable — try again in a moment")
-    view = (g.get("views") or {}).get(str(view_id))
-    if not isinstance(view, dict):
-        raise err(404, "no_view", "that view does not exist on this table")
-    nodes, _conj = filter_eval.tree_parts((view.get("config") or view).get("filters") or [])
-
-    def _any_active(ns):
-        for n in ns or ():
-            if isinstance(n, dict) and isinstance(n.get("children"), list):
-                if _any_active(n["children"]):
-                    return True
-            elif filter_eval.is_rule_active(n):
-                return True
-        return False
-
-    if not _any_active(nodes):
-        raise err(400, "no_filter",
-                  "this view has no active filter, so no record can ever ENTER it — add a "
-                  "condition to the view first, then create the alert")
-
-
-@router.delete("/alerts/{alert_id}")
-def delete_alert(alert_id: str, session: Session = Depends(require_session)):
-    rec = next((r for r in alerts.list_alerts(st=session.runtime)
-                if str(r.get("id")) == str(alert_id)), None)
-    if rec is None:
-        raise err(404, "no_alert", "that alert does not exist")
-    if str(rec.get("owner")) != str(session.uname) and not session.admin:
-        raise err(403, "not_yours", "only the alert's owner (or an administrator) can delete it")
-    alerts.delete(alert_id, st=session.runtime)
-    return {"ok": True}
-
-
-@router.post("/alerts/{alert_id}/run")
-def run_alert(alert_id: str, session: Session = Depends(require_session)):
-    rec = next((r for r in alerts.list_alerts(user=session.uname, is_admin=session.admin,
-                                              st=session.runtime)
-                if str(r.get("id")) == str(alert_id)), None)
-    if rec is None:
-        raise err(404, "no_alert", "that alert does not exist")
-    return _evaluate(session, rec)
-
-
-@router.get("/notifications")
-def notifications(session: Session = Depends(require_session)):
-    """The inbox — RE-EVALUATED on read, which is a deliberate design choice.
-
-    ⭐ A-S1-2 RESOLVED THE OTHER WAY, and the reason is structural rather than a shortcut. The
-    plan was a push hook: the automation engine calls `after_write` when it lands rows. But
-    `run_async` runs on a BACKGROUND THREAD with no `Session` in scope, and an alert must be
-    evaluated as its OWNER (see `_evaluate`) — so a push hook would have to mint a session inside
-    a worker thread from a tenant runtime, which is exactly the kind of ad-hoc identity
-    construction that leaks scope.
-
-    Pulling on read has none of that: the caller IS a session, the assemblies are already
-    scope-cached, and the user cannot observe the difference — an inbox is only ever read by
-    someone opening it. The cost is that a notification is minted when you LOOK rather than when
-    the row landed, so the `at` stamp is detection time, not arrival time.
-
-    `after_write` stays exported for the day the engine can hand over a real identity.
-    """
-    for rec in alerts.list_alerts(user=session.uname, is_admin=False, st=session.runtime):
-        try:
-            _evaluate(session, rec)
-        except Exception:                                   # noqa: BLE001
-            continue                                        # one bad alert must not empty the pane
-    return alerts.inbox(session.uname, st=session.runtime)
-
-
-@router.post("/notifications/read")
-def read_notifications(body: dict = Body(default=None),
-                       session: Session = Depends(require_session)):
-    body = body or {}
-    ids = body.get("ids")
-    if ids is not None and not isinstance(ids, list):
-        raise err(400, "bad_ids", "ids must be a list, or null to mark every notification")
-    return alerts.mark_read(session.uname, ids, read=bool(body.get("read", True)),
-                            st=session.runtime)
-
-
-def after_write(session: Session, topic_key: str):
-    """THE WRITE HOOK — call after a write that could change what a view matches.
-
-    Exported as a plain function (not a route) so `core.grid_events`' callers and S2's automation
-    upserts reach it the same way. It never raises: an alert evaluation failing must not fail the
-    edit that triggered it.
-    """
-    try:
-        return alerts.after_write(topic_key, st=session.runtime,
-                                  runner=lambda rec: _evaluate(session, rec))
-    except Exception:                                       # noqa: BLE001
-        return {"evaluated": 0}
+"""routes_alerts.py — the Alerts module (wave 20, owner item 25, contract C-ALERT).
+
+    GET    /api/v1/alerts                  -> {alerts:[...]}
+    POST   /api/v1/alerts                  <- {viewId, topic, label?}
+    DELETE /api/v1/alerts/{alert_id}
+    POST   /api/v1/alerts/{alert_id}/run   -> evaluate now (the pane's manual refresh)
+    GET    /api/v1/notifications           -> {unread, items:[...]}
+    POST   /api/v1/notifications/read      <- {ids:[...]|null, read?:bool}
+
+The semantics — an alert is a view plus a remembered matched set, a notification is a NEW
+ENTRANT, and the first evaluation seeds silently — live in `core.alerts` with the reasoning.
+This file owns the two things a route must: WHO may do it, and HOW the view gets evaluated.
+
+⭐ **THE EVALUATION RUNS AS THE ALERT'S OWNER, NOT AS THE CALLER.** `_run_alert` builds the pool
+for `rec['owner']`, never for whoever tripped the write hook. Any other choice leaks: a
+full-access admin editing a cell would otherwise evaluate a BU-scoped user's alert over the whole
+book, and the notification would name customers that user may not see — a permission leak wearing
+a notification's clothes. The owner's own scope is the only correct basis for their alert.
+
+⚠ **AN ALERT IS NOT A SECOND READ PATH.** It resolves rows through the same
+`routes_customers.grid_assembly` / `routes_tables.ut_assembly` the grid uses, so a row that an
+alert can see is by construction a row its owner could open. Re-implementing the filter here
+would be a second definition of "matches", and those two would drift.
+"""
+from fastapi import APIRouter, Body, Depends
+
+import core.alerts as alerts
+from deps import Session, err, require_session
+
+router = APIRouter(prefix="/api/v1")
+
+#: The alert-bearing surfaces. `ut_` tables are admitted by prefix, like everywhere else.
+_TOPICS = ("customer", "product")
+
+
+def _topic_or_400(raw):
+    topic = str(raw or "").strip().lower()
+    if topic.startswith("ut_") or topic in _TOPICS:
+        return topic
+    raise err(400, "bad_topic", f"topic must be one of {', '.join(_TOPICS)} or a ut_ table")
+
+
+def _owner_session(session: Session, owner: str):
+    """A `Session` for the alert's OWNER (see the module note on why the owner, not the caller).
+
+    ⚠ `Session` exposes `uname`/`admin` as PROPERTIES derived from `user`, not as fields — so an
+    owner session is built by swapping the `user` RECORD and letting both derive themselves. An
+    earlier version passed `uname=`/`admin=` to the constructor, which would have raised on the
+    first write hook of the wave; the properties are the single definition of who a session is,
+    and going around them is how a session with an admin flag and a non-admin record exists.
+
+    Returns None when the owner is gone or deactivated — their alerts then stop evaluating rather
+    than evaluating as somebody else, which is the fail-closed direction.
+    """
+    import core.users as users
+
+    if str(owner) == str(session.uname):
+        return session
+    rec = (users.registry() or {}).get(str(owner))
+    if not isinstance(rec, dict) or not rec.get("active", True):
+        return None
+    # `_public` is THE definition of what a session may know about its own account (never a hash
+    # or a salt) — the same one `routes_auth` uses. Building the dict by hand here would be a
+    # second definition, and the one that leaks is always the copy.
+    return Session(tenant=session.tenant, user=users._public(str(owner), rec),
+                   claims=session.claims, runtime=session.runtime)
+
+
+def _evaluate(session: Session, rec: dict):
+    """Resolve `rec`'s view over its topic AS THE ALERT'S OWNER, then fold the result in."""
+    import aios_grid
+    from harness import filter_eval
+
+    owner_sess = _owner_session(session, rec.get("owner"))
+    if owner_sess is None:
+        return {"skipped": "owner_unavailable"}
+    topic = str(rec.get("topic") or "")
+    try:
+        if topic.startswith("ut_"):
+            from routes_tables import ut_assembly
+            g = ut_assembly(owner_sess, topic,
+                            storage_key=f"{owner_sess.tenant}:{topic}:{owner_sess.uname}")
+        else:
+            from routes_customers import grid_assembly
+            g = grid_assembly(owner_sess, scope=topic, consume_corrections=False)
+    except Exception as e:                                  # noqa: BLE001
+        return {"skipped": "unavailable", "detail": type(e).__name__}
+
+    view = (g.get("views") or {}).get(str(rec.get("viewId")))
+    if not isinstance(view, dict):
+        # Deleted, or un-shared out from under the alert. Say so on the RECORD rather than
+        # deleting the alert: an alert that silently vanishes is indistinguishable from one that
+        # never fires, and the user cannot debug what is not there.
+        return {"skipped": "view_missing"}
+
+    # The SAME row build the grid and `/customers` use — `rows_from_pool` is what puts derived
+    # and overlay values on a row. Evaluating a filter against raw pool dicts would silently
+    # never match any condition on a user-created or measure column.
+    rows = aios_grid.rows_from_pool(g["rows_src"], g["fields"], g["ws"].get("overlays"),
+                                    derived=g.get("derived"))
+    config = view.get("config") or view
+    ctx = filter_eval.EvalCtx(
+        cohort_sets={str(k): {str(p) for p in (v.get("memberPids") or ())}
+                     for k, v in (g.get("lists") or {}).items() if isinstance(v, dict)},
+        measure_sets=g.get("measure_sets") or {},
+        today=g.get("today"))
+    pids = filter_eval.visible_pids(config.get("filters") or [], rows, g["fields"], ctx,
+                                    member_pids=config.get("memberPids"))
+    labels = {str(r.get("pid")): str(r.get("name") or r.get("pid")) for r in rows}
+    return alerts.evaluate(rec.get("id"), [str(p) for p in pids],
+                           labels=labels, partial=False, st=session.runtime)
+
+
+@router.get("/alerts")
+def list_alerts(session: Session = Depends(require_session)):
+    return {"alerts": alerts.list_alerts(user=session.uname, is_admin=session.admin,
+                                         st=session.runtime)}
+
+
+@router.post("/alerts")
+def create_alert(body: dict = Body(default=None), session: Session = Depends(require_session)):
+    body = body or {}
+    view_id = str(body.get("viewId") or "").strip()
+    if not view_id:
+        raise err(400, "bad_view", "an alert needs the id of the view it watches")
+    topic = _topic_or_400(body.get("topic"))
+    _require_filtered_view(session, topic, view_id)
+    import uuid
+    aid = f"al_{uuid.uuid4().hex[:12]}"
+    rec = alerts.create(aid, view_id=view_id, topic=topic, owner=session.uname,
+                        label=body.get("label") or "", st=session.runtime)
+    # SEED IMMEDIATELY, so the alert starts from "everything currently matching is old news".
+    # Deferring this to the first write hook would mean the next edit announces the whole view.
+    outcome = _evaluate(session, rec)
+    return {"alert": {**rec, "seeded": True}, "first": outcome}
+
+
+def _require_filtered_view(session: Session, topic: str, view_id: str):
+    """400 unless `view_id` exists on `topic` AND actually narrows something.
+
+    ⛔ AN ALERT ON AN UNFILTERED VIEW IS SILENTLY INCAPABLE OF ALERTING, which is worse than one
+    that is refused. `filter_eval` treats an inactive tree as "no narrowing, every row shows"
+    (`visible_pids`'s own rule), so such an alert seeds with the entire table and can never see an
+    entrant again — there is nothing left to enter. The owner's words are *"when a Record gets
+    into that Filter's criteria"*: no criteria, no alert, and said at creation rather than
+    discovered by never being notified.
+
+    `is_rule_active` is the SAME activeness predicate the engine and the column tints use — a
+    half-typed rule is not a filter, and this must agree with what actually narrows or it would
+    accept a view whose one rule the engine then ignores.
+    """
+    from harness import filter_eval
+
+    try:
+        if topic.startswith("ut_"):
+            from routes_tables import ut_assembly
+            g = ut_assembly(session, topic,
+                            storage_key=f"{session.tenant}:{topic}:{session.uname}")
+        else:
+            from routes_customers import grid_assembly
+            g = grid_assembly(session, scope=topic, consume_corrections=False)
+    except Exception:                                       # noqa: BLE001
+        raise err(503, "unavailable", "the table is unavailable — try again in a moment")
+    view = (g.get("views") or {}).get(str(view_id))
+    if not isinstance(view, dict):
+        raise err(404, "no_view", "that view does not exist on this table")
+    nodes, _conj = filter_eval.tree_parts((view.get("config") or view).get("filters") or [])
+
+    def _any_active(ns):
+        for n in ns or ():
+            if isinstance(n, dict) and isinstance(n.get("children"), list):
+                if _any_active(n["children"]):
+                    return True
+            elif filter_eval.is_rule_active(n):
+                return True
+        return False
+
+    if not _any_active(nodes):
+        raise err(400, "no_filter",
+                  "this view has no active filter, so no record can ever ENTER it — add a "
+                  "condition to the view first, then create the alert")
+
+
+@router.delete("/alerts/{alert_id}")
+def delete_alert(alert_id: str, session: Session = Depends(require_session)):
+    rec = next((r for r in alerts.list_alerts(st=session.runtime)
+                if str(r.get("id")) == str(alert_id)), None)
+    if rec is None:
+        raise err(404, "no_alert", "that alert does not exist")
+    if str(rec.get("owner")) != str(session.uname) and not session.admin:
+        raise err(403, "not_yours", "only the alert's owner (or an administrator) can delete it")
+    alerts.delete(alert_id, st=session.runtime)
+    return {"ok": True}
+
+
+@router.post("/alerts/{alert_id}/run")
+def run_alert(alert_id: str, session: Session = Depends(require_session)):
+    rec = next((r for r in alerts.list_alerts(user=session.uname, is_admin=session.admin,
+                                              st=session.runtime)
+                if str(r.get("id")) == str(alert_id)), None)
+    if rec is None:
+        raise err(404, "no_alert", "that alert does not exist")
+    return _evaluate(session, rec)
+
+
+@router.get("/notifications")
+def notifications(session: Session = Depends(require_session)):
+    """The inbox — RE-EVALUATED on read, which is a deliberate design choice.
+
+    ⭐ A-S1-2 RESOLVED THE OTHER WAY, and the reason is structural rather than a shortcut. The
+    plan was a push hook: the automation engine calls `after_write` when it lands rows. But
+    `run_async` runs on a BACKGROUND THREAD with no `Session` in scope, and an alert must be
+    evaluated as its OWNER (see `_evaluate`) — so a push hook would have to mint a session inside
+    a worker thread from a tenant runtime, which is exactly the kind of ad-hoc identity
+    construction that leaks scope.
+
+    Pulling on read has none of that: the caller IS a session, the assemblies are already
+    scope-cached, and the user cannot observe the difference — an inbox is only ever read by
+    someone opening it. The cost is that a notification is minted when you LOOK rather than when
+    the row landed, so the `at` stamp is detection time, not arrival time.
+
+    `after_write` stays exported for the day the engine can hand over a real identity.
+    """
+    for rec in alerts.list_alerts(user=session.uname, is_admin=False, st=session.runtime):
+        try:
+            _evaluate(session, rec)
+        except Exception:                                   # noqa: BLE001
+            continue                                        # one bad alert must not empty the pane
+    return alerts.inbox(session.uname, st=session.runtime)
+
+
+@router.post("/notifications/read")
+def read_notifications(body: dict = Body(default=None),
+                       session: Session = Depends(require_session)):
+    body = body or {}
+    ids = body.get("ids")
+    if ids is not None and not isinstance(ids, list):
+        raise err(400, "bad_ids", "ids must be a list, or null to mark every notification")
+    return alerts.mark_read(session.uname, ids, read=bool(body.get("read", True)),
+                            st=session.runtime)
+
+
+def after_write(session: Session, topic_key: str):
+    """THE WRITE HOOK — call after a write that could change what a view matches.
+
+    Exported as a plain function (not a route) so `core.grid_events`' callers and S2's automation
+    upserts reach it the same way. It never raises: an alert evaluation failing must not fail the
+    edit that triggered it.
+    """
+    try:
+        return alerts.after_write(topic_key, st=session.runtime,
+                                  runner=lambda rec: _evaluate(session, rec))
+    except Exception:                                       # noqa: BLE001
+        return {"evaluated": 0}

api/routes_auth.py

@@ -1,217 +1,217 @@
-"""routes_auth.py — X2's auth leg: login / logout / me (EXIT-3a).
-
-Password auth against the SAME `core/users` accounts the Streamlit `gate()` uses, so both
-front-ends share one identity today. The amended D-3 (our own OIDC client against Authentik, with
-a branded login page) lands when D-1/D-2 unblock (owner blocker B-4); this is the interim leg it
-replaces, and it is deliberately the same account store so the migration is a swap of the
-CREDENTIAL check, not of the user model.
-"""
-import base64 as _b64
-import hmac
-import os
-import re as _re
-import time
-from collections import OrderedDict
-
-from fastapi import APIRouter, Body, Depends, Request, Response
-
-import aios_session
-from deps import Session, err, require_session, users, perms
-
-router = APIRouter(prefix="/api/v1/auth")
-
-#: THE SERVER OWNS BACKOFF (X5): the login page shows an inline error and never paces itself, so
-#: the pacing has to be here or it does not exist. Bounded so it cannot grow into a memory leak.
-#: ⚠ HONEST LIMIT: per-PROCESS. Behind several workers an attacker gets this budget per worker,
-#: and it resets on deploy. It raises the cost of online guessing against PBKDF2-200k; it is not
-#: a substitute for the real thing, which arrives with Authentik (D-1) owning rate limits centrally.
-#: ⚠ KEYED BY (TENANT, USERNAME), not by username. Two tenants can each have an 'admin' or a
-#: 'boss', and a shared bucket would mean failed logins against tenant B lock the same name out of
-#: tenant A — a cross-tenant coupling in the one wave whose point is that tenants cannot reach
-#: each other. It is also a (weak) existence oracle: a 429 for a name you never tried here would
-#: tell you somebody else did.
-_FAILS = OrderedDict()
-_MAX_TRACKED = 2048
-_LOCKOUT_AFTER = 8
-_LOCKOUT_SECONDS = 60
-
-
-def _throttled(key, now=None):
-    now = now or time.time()
-    hit = _FAILS.get(key)
-    if not hit:
-        return 0
-    count, last = hit
-    if count < _LOCKOUT_AFTER:
-        return 0
-    remaining = int(_LOCKOUT_SECONDS - (now - last))
-    return remaining if remaining > 0 else 0
-
-
-def _note_failure(key, now=None):
-    now = now or time.time()
-    count, last = _FAILS.get(key, (0, 0.0))
-    # A window that has fully elapsed starts the count again — a user who mistypes twice today
-    # and twice next week is not an attacker.
-    if now - last > _LOCKOUT_SECONDS:
-        count = 0
-    _FAILS[key] = (count + 1, now)
-    _FAILS.move_to_end(key)
-    while len(_FAILS) > _MAX_TRACKED:
-        _FAILS.popitem(last=False)
-
-
-def _clear_failures(key):
-    _FAILS.pop(key, None)
-
-
-def _public_user(user):
-    """What the client is allowed to know about itself. Never a hash, a salt, or the epoch —
-    the epoch is a server-side revocation handle and a client has no use for it."""
-    return {"username": user.get("username", ""), "name": user.get("name", ""),
-            "role": user.get("role", "user"),
-            # Wave 18 (C1-TENANT, R1): the company this session is bound to — the client shows
-            # it and tests assert the binding; the SERVER-side truth stays in the signed cookie.
-            "tenant": str(user.get("tenant") or "royal-imports").strip().lower(),
-            "bus": perms.allowed_bu_labels(user),
-            "team_id": perms.scope_team_id(user),
-            "agent": perms.scope_agent(user),
-            "modules": sorted(perms.allowed_modules(user) or []) or "all",
-            "landing": perms.landing_page(user),
-            # Wave 14 C-AVATAR — the user's OWN photo (Settings preview + the shell chip).
-            # Everyone else's rides workspace.userAvatars, keyed by display name.
-            "avatar": user.get("avatar") or None}
-
-
-#: Wave 14 C-AVATAR — the write-side wall. PNG/JPEG data URLs only; the client downscales to
-#: <=128px before posting, and the server re-validates because a stored data URL is served to
-#: every grid session verbatim.
-_AVATAR_RE = _re.compile(r"^data:image/(png|jpeg);base64,([A-Za-z0-9+/=]+)$")
-_AVATAR_MAX_BYTES = 64 * 1024
-
-
-@router.post("/me/avatar")
-def set_avatar(body: dict = Body(default=None),
-               session: Session = Depends(require_session)):
-    import core.store as _store
-    raw = str((body or {}).get("dataUrl") or "")
-    m = _AVATAR_RE.match(raw)
-    if not m:
-        raise err(400, "bad_avatar",
-                  "expected a data:image/png;base64,... or image/jpeg data URL")
-    try:
-        blob = _b64.b64decode(m.group(2), validate=True)
-    except Exception:
-        raise err(400, "bad_avatar", "that data URL is not valid base64")
-    if len(blob) > _AVATAR_MAX_BYTES:
-        raise err(400, "bad_avatar",
-                  f"avatar too large - {_AVATAR_MAX_BYTES // 1024}KB decoded max "
-                  f"(downscale to 128px before posting)")
-    if not _store.available():
-        raise err(503, "store_unavailable", "the tenant store is unavailable")
-    # session.uname is the canonical account handle; the session's user RECORD does not
-    # carry a "username" key (it is the registry's dict key), so keying the write off the
-    # record would silently no-op — caught by X7's fresh /me read.
-    users.set_avatar(session.uname, raw)
-    u2 = dict(session.user)
-    u2["avatar"] = raw
-    return {"user": _public_user(u2)}
-
-
-@router.delete("/me/avatar")
-def clear_avatar(session: Session = Depends(require_session)):
-    import core.store as _store
-    if not _store.available():
-        raise err(503, "store_unavailable", "the tenant store is unavailable")
-    users.set_avatar(session.uname, None)
-    u2 = dict(session.user)
-    u2.pop("avatar", None)
-    return {"user": _public_user(u2)}
-
-
-@router.post("/login")
-def login(request: Request, response: Response, body: dict = Body(default=None)):
-    """Wave 18 (C1-TENANT, R1): ONE login box — the ACCOUNT decides the tenant.
-
-    The pre-wave flow validated a caller-posted tenant slug and minted the session for it, so
-    the same credential could sign in to any registered tenant. Now the credential resolves
-    FIRST (username or email — `users.verify` takes both) and the session binds to the tenant
-    ON THE RECORD; the posted `tenant` field is accepted for wire-compat and ignored. An
-    account whose tenant no longer resolves (deleted / suspended record) gets the same 401 as
-    a bad password — "which tenants exist" is not the login form's question to answer.
-    """
-    body = body or {}
-    uname = str(body.get("username") or "").strip().lower()
-    pw = str(body.get("password") or "")
-
-    # Throttle on the IDENTIFIER alone: the tenant is not known until the credential resolves,
-    # and a per-(tenant, uname) key would let an attacker reset their budget by rotating slugs.
-    throttle_key = ("*", uname)
-    wait = _throttled(throttle_key)
-    if wait:
-        raise err(429, "too_many_attempts",
-                  f"too many failed attempts — try again in {wait} seconds")
-
-    user = users.verify(uname, pw) if (uname and pw) else None
-    if not user:
-        # CONSTANT-TIME-ISH 401. `users.verify` returns immediately for an unknown username (no
-        # record, no PBKDF2) and burns ~200k iterations for a known one, so the response time
-        # answers "does this account exist?" to anyone with a stopwatch. Burning one equivalent
-        # hash on the failure path removes that oracle. It costs nothing on the happy path.
-        try:
-            users._hash(pw or "x", "00" * 16)
-        except Exception:
-            pass
-        _note_failure(throttle_key)
-        raise err(401, "invalid_credentials", "that username and password do not match")
-
-    tenant = str(user.get("tenant") or "royal-imports").strip().lower()
-    from harness import runtime
-    try:
-        runtime.get_runtime(tenant)
-    except KeyError:
-        _note_failure(throttle_key)
-        raise err(401, "invalid_credentials", "that username and password do not match")
-
-    _clear_failures(throttle_key)
-    value, _claims = aios_session.mint(tenant, user["username"], int(user.get("epoch") or 0))
-    aios_session.set_cookie(response, request, value)
-    # Wave 19 (R4): the login stamp. THE RESOLVED username, never the posted identifier — the
-    # person may have typed an email address and `users.verify` resolved it to the registry key;
-    # stamping what was typed would write onto a key that does not exist. Fail-silent inside
-    # `touch_login` and a no-op for the emergency-master identity (which has no record to stamp),
-    # so the one thing this cannot do is turn a good credential into a failed sign-in.
-    users.touch_login(user["username"])
-    # `touch_login` also sets `last_active`, so tell the session resolver it has been seen —
-    # otherwise the very next request stamps it again and the hourly throttle is off by one write
-    # per sign-in.
-    import deps as _deps
-    _deps.note_active(user["username"])
-    return {"user": _public_user(user)}
-
-
-@router.post("/logout", status_code=204)
-def logout(request: Request):
-    """204 and the cookie is cleared. Deliberately NOT session-gated: logging out must work from
-    an already-invalid session, or a user holding a broken cookie has no way to get rid of it.
-
-    ⚠ THE COOKIE IS CLEARED ON THE RETURNED RESPONSE, not on an injected `response` param. When a
-    handler RETURNS a Response object, FastAPI ships that object — anything written to the
-    injected `response` is silently dropped. The first version of this route took `response:
-    Response`, called `clear_cookie` on it, then returned a fresh `Response(204)`: the 204 was
-    correct, no `Set-Cookie` was ever sent, and the session stayed alive after a "successful"
-    logout. Caught by asserting `/auth/me` is 401 AFTER the logout rather than trusting the 204.
-
-    ⚠ This clears the BROWSER's copy only — the signed value stays cryptographically valid until
-    it expires, which is the honest cost of a stateless session. "Sign me out everywhere" is
-    `core.users.bump_epoch` (a password change already does it); D2's Postgres session mirror
-    makes per-device revocation possible and arrives with C-2.
-    """
-    out = Response(status_code=204)
-    aios_session.clear_cookie(out, request)
-    return out
-
-
-@router.get("/me")
-def me(session: Session = Depends(require_session)):
-    return {"user": _public_user(session.user), "tenant": session.tenant}
+"""routes_auth.py — X2's auth leg: login / logout / me (EXIT-3a).
+
+Password auth against the SAME `core/users` accounts the Streamlit `gate()` uses, so both
+front-ends share one identity today. The amended D-3 (our own OIDC client against Authentik, with
+a branded login page) lands when D-1/D-2 unblock (owner blocker B-4); this is the interim leg it
+replaces, and it is deliberately the same account store so the migration is a swap of the
+CREDENTIAL check, not of the user model.
+"""
+import base64 as _b64
+import hmac
+import os
+import re as _re
+import time
+from collections import OrderedDict
+
+from fastapi import APIRouter, Body, Depends, Request, Response
+
+import aios_session
+from deps import Session, err, require_session, users, perms
+
+router = APIRouter(prefix="/api/v1/auth")
+
+#: THE SERVER OWNS BACKOFF (X5): the login page shows an inline error and never paces itself, so
+#: the pacing has to be here or it does not exist. Bounded so it cannot grow into a memory leak.
+#: ⚠ HONEST LIMIT: per-PROCESS. Behind several workers an attacker gets this budget per worker,
+#: and it resets on deploy. It raises the cost of online guessing against PBKDF2-200k; it is not
+#: a substitute for the real thing, which arrives with Authentik (D-1) owning rate limits centrally.
+#: ⚠ KEYED BY (TENANT, USERNAME), not by username. Two tenants can each have an 'admin' or a
+#: 'boss', and a shared bucket would mean failed logins against tenant B lock the same name out of
+#: tenant A — a cross-tenant coupling in the one wave whose point is that tenants cannot reach
+#: each other. It is also a (weak) existence oracle: a 429 for a name you never tried here would
+#: tell you somebody else did.
+_FAILS = OrderedDict()
+_MAX_TRACKED = 2048
+_LOCKOUT_AFTER = 8
+_LOCKOUT_SECONDS = 60
+
+
+def _throttled(key, now=None):
+    now = now or time.time()
+    hit = _FAILS.get(key)
+    if not hit:
+        return 0
+    count, last = hit
+    if count < _LOCKOUT_AFTER:
+        return 0
+    remaining = int(_LOCKOUT_SECONDS - (now - last))
+    return remaining if remaining > 0 else 0
+
+
+def _note_failure(key, now=None):
+    now = now or time.time()
+    count, last = _FAILS.get(key, (0, 0.0))
+    # A window that has fully elapsed starts the count again — a user who mistypes twice today
+    # and twice next week is not an attacker.
+    if now - last > _LOCKOUT_SECONDS:
+        count = 0
+    _FAILS[key] = (count + 1, now)
+    _FAILS.move_to_end(key)
+    while len(_FAILS) > _MAX_TRACKED:
+        _FAILS.popitem(last=False)
+
+
+def _clear_failures(key):
+    _FAILS.pop(key, None)
+
+
+def _public_user(user):
+    """What the client is allowed to know about itself. Never a hash, a salt, or the epoch —
+    the epoch is a server-side revocation handle and a client has no use for it."""
+    return {"username": user.get("username", ""), "name": user.get("name", ""),
+            "role": user.get("role", "user"),
+            # Wave 18 (C1-TENANT, R1): the company this session is bound to — the client shows
+            # it and tests assert the binding; the SERVER-side truth stays in the signed cookie.
+            "tenant": str(user.get("tenant") or "royal-imports").strip().lower(),
+            "bus": perms.allowed_bu_labels(user),
+            "team_id": perms.scope_team_id(user),
+            "agent": perms.scope_agent(user),
+            "modules": sorted(perms.allowed_modules(user) or []) or "all",
+            "landing": perms.landing_page(user),
+            # Wave 14 C-AVATAR — the user's OWN photo (Settings preview + the shell chip).
+            # Everyone else's rides workspace.userAvatars, keyed by display name.
+            "avatar": user.get("avatar") or None}
+
+
+#: Wave 14 C-AVATAR — the write-side wall. PNG/JPEG data URLs only; the client downscales to
+#: <=128px before posting, and the server re-validates because a stored data URL is served to
+#: every grid session verbatim.
+_AVATAR_RE = _re.compile(r"^data:image/(png|jpeg);base64,([A-Za-z0-9+/=]+)$")
+_AVATAR_MAX_BYTES = 64 * 1024
+
+
+@router.post("/me/avatar")
+def set_avatar(body: dict = Body(default=None),
+               session: Session = Depends(require_session)):
+    import core.store as _store
+    raw = str((body or {}).get("dataUrl") or "")
+    m = _AVATAR_RE.match(raw)
+    if not m:
+        raise err(400, "bad_avatar",
+                  "expected a data:image/png;base64,... or image/jpeg data URL")
+    try:
+        blob = _b64.b64decode(m.group(2), validate=True)
+    except Exception:
+        raise err(400, "bad_avatar", "that data URL is not valid base64")
+    if len(blob) > _AVATAR_MAX_BYTES:
+        raise err(400, "bad_avatar",
+                  f"avatar too large - {_AVATAR_MAX_BYTES // 1024}KB decoded max "
+                  f"(downscale to 128px before posting)")
+    if not _store.available():
+        raise err(503, "store_unavailable", "the tenant store is unavailable")
+    # session.uname is the canonical account handle; the session's user RECORD does not
+    # carry a "username" key (it is the registry's dict key), so keying the write off the
+    # record would silently no-op — caught by X7's fresh /me read.
+    users.set_avatar(session.uname, raw)
+    u2 = dict(session.user)
+    u2["avatar"] = raw
+    return {"user": _public_user(u2)}
+
+
+@router.delete("/me/avatar")
+def clear_avatar(session: Session = Depends(require_session)):
+    import core.store as _store
+    if not _store.available():
+        raise err(503, "store_unavailable", "the tenant store is unavailable")
+    users.set_avatar(session.uname, None)
+    u2 = dict(session.user)
+    u2.pop("avatar", None)
+    return {"user": _public_user(u2)}
+
+
+@router.post("/login")
+def login(request: Request, response: Response, body: dict = Body(default=None)):
+    """Wave 18 (C1-TENANT, R1): ONE login box — the ACCOUNT decides the tenant.
+
+    The pre-wave flow validated a caller-posted tenant slug and minted the session for it, so
+    the same credential could sign in to any registered tenant. Now the credential resolves
+    FIRST (username or email — `users.verify` takes both) and the session binds to the tenant
+    ON THE RECORD; the posted `tenant` field is accepted for wire-compat and ignored. An
+    account whose tenant no longer resolves (deleted / suspended record) gets the same 401 as
+    a bad password — "which tenants exist" is not the login form's question to answer.
+    """
+    body = body or {}
+    uname = str(body.get("username") or "").strip().lower()
+    pw = str(body.get("password") or "")
+
+    # Throttle on the IDENTIFIER alone: the tenant is not known until the credential resolves,
+    # and a per-(tenant, uname) key would let an attacker reset their budget by rotating slugs.
+    throttle_key = ("*", uname)
+    wait = _throttled(throttle_key)
+    if wait:
+        raise err(429, "too_many_attempts",
+                  f"too many failed attempts — try again in {wait} seconds")
+
+    user = users.verify(uname, pw) if (uname and pw) else None
+    if not user:
+        # CONSTANT-TIME-ISH 401. `users.verify` returns immediately for an unknown username (no
+        # record, no PBKDF2) and burns ~200k iterations for a known one, so the response time
+        # answers "does this account exist?" to anyone with a stopwatch. Burning one equivalent
+        # hash on the failure path removes that oracle. It costs nothing on the happy path.
+        try:
+            users._hash(pw or "x", "00" * 16)
+        except Exception:
+            pass
+        _note_failure(throttle_key)
+        raise err(401, "invalid_credentials", "that username and password do not match")
+
+    tenant = str(user.get("tenant") or "royal-imports").strip().lower()
+    from harness import runtime
+    try:
+        runtime.get_runtime(tenant)
+    except KeyError:
+        _note_failure(throttle_key)
+        raise err(401, "invalid_credentials", "that username and password do not match")
+
+    _clear_failures(throttle_key)
+    value, _claims = aios_session.mint(tenant, user["username"], int(user.get("epoch") or 0))
+    aios_session.set_cookie(response, request, value)
+    # Wave 19 (R4): the login stamp. THE RESOLVED username, never the posted identifier — the
+    # person may have typed an email address and `users.verify` resolved it to the registry key;
+    # stamping what was typed would write onto a key that does not exist. Fail-silent inside
+    # `touch_login` and a no-op for the emergency-master identity (which has no record to stamp),
+    # so the one thing this cannot do is turn a good credential into a failed sign-in.
+    users.touch_login(user["username"])
+    # `touch_login` also sets `last_active`, so tell the session resolver it has been seen —
+    # otherwise the very next request stamps it again and the hourly throttle is off by one write
+    # per sign-in.
+    import deps as _deps
+    _deps.note_active(user["username"])
+    return {"user": _public_user(user)}
+
+
+@router.post("/logout", status_code=204)
+def logout(request: Request):
+    """204 and the cookie is cleared. Deliberately NOT session-gated: logging out must work from
+    an already-invalid session, or a user holding a broken cookie has no way to get rid of it.
+
+    ⚠ THE COOKIE IS CLEARED ON THE RETURNED RESPONSE, not on an injected `response` param. When a
+    handler RETURNS a Response object, FastAPI ships that object — anything written to the
+    injected `response` is silently dropped. The first version of this route took `response:
+    Response`, called `clear_cookie` on it, then returned a fresh `Response(204)`: the 204 was
+    correct, no `Set-Cookie` was ever sent, and the session stayed alive after a "successful"
+    logout. Caught by asserting `/auth/me` is 401 AFTER the logout rather than trusting the 204.
+
+    ⚠ This clears the BROWSER's copy only — the signed value stays cryptographically valid until
+    it expires, which is the honest cost of a stateless session. "Sign me out everywhere" is
+    `core.users.bump_epoch` (a password change already does it); D2's Postgres session mirror
+    makes per-device revocation possible and arrives with C-2.
+    """
+    out = Response(status_code=204)
+    aios_session.clear_cookie(out, request)
+    return out
+
+
+@router.get("/me")
+def me(session: Session = Depends(require_session)):
+    return {"user": _public_user(session.user), "tenant": session.tenant}

api/routes_customers.py

@@ -1,346 +1,346 @@
-"""routes_customers.py — X2's read + write of the customer table, BU-SCOPED (EXIT-3b / EXIT-2a).
-
-Two things happen here that did not happen in the pre-wave `main.py`:
-
-  1. **ROWS ARE SCOPED TO THE SESSION.** The old `/api/customers` served `cl.pool()` — the whole
-     book, to anyone holding the shared APP_PASSWORD. Now the pool is built with
-     `(team_id, agent_name)` derived from the USER RECORD, so a Royal-only user never receives a
-     Fisch row and an agent-linked login never receives another rep's book. The scope is applied
-     at the QUERY, not as a post-filter, so there is no moment at which the other BU's rows exist
-     in this response.
-
-  2. **THE OVERLAY FORK IS GONE.** `aios-web/api/data/overlay.json` was a SECOND writable home
-     for the same user-owned fields the Streamlit app keeps in the tenant store — two truths, and
-     whichever process you asked last was right. Reads and writes now both go through
-     `modules.customer_data`'s table-workspace functions: ONE store (C1c, ARCHITECTURE §1a rule 3).
-
-⚠ ONE STORE IS NOT YET ONE CACHE (strangler-period, booked honestly). `core.store.get()` is
-cache-first per PROCESS, so a write from the Streamlit container is invisible to a running API
-container until its cache is refreshed, and vice versa. Deleting the fork removes the second
-SOURCE OF TRUTH; it does not make the two runtimes coherent. The fix is X4/Postgres (task C-4,
-owner-blocked on B-3), and no test here may claim read-your-writes ACROSS runtimes — a TestClient
-proof is single-process and would report green on exactly the thing that is still broken.
-"""
-import time
-
-from fastapi import APIRouter, Body, Depends
-
-import scope_cache
-from deps import Session, err, module_gate, perms
-
-router = APIRouter(prefix="/api/v1")
-
-#: The surface these routes serve. Both legs are gated on it, so a user without the grant gets a
-#: 403 rather than an empty table that looks like "you have no customers".
-MODULE = "customer_data"
-
-_CACHE_TTL = 900       # the pool build is slow (Odoo + reconciliation); 15 min, as before
-
-
-def _pool_rows(session: Session):
-    """The reconciled Odoo pool for this session's SCOPE — the slow part, and the only part that
-    may be shared between users.
-
-    ⛔ WHAT MAY BE CACHED HERE, AND WHY THE LINE IS EXACTLY HERE. The cache key is
-    `(team_id, agent)` and the cached value is the raw pool: Odoo-source columns only. That is
-    genuinely scope-shaped — two users with the same BU and the same book are asking the same
-    question, and `cl.pool()` is expensive (an Odoo pull plus reconciliation).
-
-    The FULL PAYLOAD is NOT cacheable on this key, and caching it here was a real defect I shipped
-    and then removed. `fields` comes from `fields_from_workspace(ws)` — that user's own `custom_`
-    and `measure_` columns — and every overlay cell comes from `ws['overlays']`; the table
-    workspace is read as `data[username]` and written as `patch_table_overlay(uname, …)`, i.e.
-    PER USER. So two Royal-only users with no agent link share `(6, None)` and the second one
-    would have been served the FIRST one's private notes and private columns. The scope key was
-    right for the pool and wrong for everything wrapped around it.
-
-    It survived a green 129-check battery because every fixture user had a DISTINCT
-    `(team_id, agent)` pair, so no two of them ever collided on the key — the test set could not
-    express the bug. `verify_api.py` now carries a same-scope second user for exactly this.
-    """
-    rt = session.runtime
-    team_id, agent = _team_agent(session)
-    return _pool_for(rt, team_id, agent)
-
-
-def _pool_for(rt, team_id, agent):
-    """The cached pool for an explicit scope — session-free so the prewarm thread and the
-    stale-refresh path can call it. STALE-WHILE-REFRESH (scope_cache): once a copy exists no
-    request blocks on the 10–30s Odoo rebuild again; only a scope's FIRST-ever build does.
-
-    DEBT-2 (2026-08-04): while the tenant's RESOLVED Odoo source is PAUSED this path never
-    goes live — it serves the in-process copy at any age, else the persisted pause-time
-    snapshot (restart-safe), else answers 503. Never a WIDER scope's snapshot: handing a
-    scoped user the consolidated rows would widen their book, which is worse than an error."""
-    import modules.customer_data as cl
-    import routes_keychain
-
-    key = ("pool", team_id, agent)
-
-    if routes_keychain.odoo_paused(rt):
-        hit = rt.pool_cache.get(key)
-        if hit:
-            return hit[1]
-        snap = routes_keychain.load_pool_snapshot(rt, team_id, agent)
-        if snap is not None:
-            rt.pool_cache[key] = snap          # seed, so the memo stamps stay coherent
-            return snap[1]
-        raise err(503, "connector_paused",
-                  "this data source is paused and no snapshot exists for your scope — "
-                  "an admin can resume it under Settings → Connectors")
-
-    def _build():
-        # ⚠ THE SCOPE GOES INTO THE BUILDER. `pool(agent_name, team_id)` is the same reconciled
-        # builder the Streamlit page uses — passing the scope here is what makes the isolation a
-        # property of the QUERY instead of a filter someone can forget to apply downstream.
-        return cl.pool(agent, team_id)
-
-    def _evict():
-        # Bounded: a scope cache that only ever grows is a memory leak in a shared process.
-        if len(rt.pool_cache) > 16:
-            for stale in sorted(rt.pool_cache, key=lambda k: rt.pool_cache[k][0])[:8]:
-                rt.pool_cache.pop(stale, None)
-
-    return scope_cache.get(rt.pool_cache, key, _CACHE_TTL, _build, _evict)
-
-
-def warm_default(rt):
-    """Boot prewarm: the consolidated pool `(None, None)` — the scope every admin and every
-    all-BU account lands on. Called from main.py's prewarm thread only."""
-    _pool_for(rt, None, None)
-
-
-def _team_agent(session: Session):
-    """The `(team_id, agent)` this session's POOL is built with — ONE derivation point, used by
-    `_pool_rows` and `grid_assembly` alike, so the cache key and the query can never disagree.
-
-    ⛔ WAVE 15 R1: THIS NOW COMES FROM THE PERMANENT FILTER (C-PERM amendment 3). `team_id` is
-    not a row filter — `customer_data._pool_build` passes it into `cust._cust_rev` three times
-    and into `_cadence_bulk`, so it decides what `rev`/`ly`/`ltm`/`aov`/`status` MEAN. Enforcing
-    a BU purely as a post-filter would keep the row list right and silently consolidate every
-    number. So the pushdown survives as a DERIVATION OF the declared filter rather than a second
-    wall beside it, and `perm_scope.derive_pool_scope` falls back to the legacy `bus`/`agent`
-    derivation for any record the migration has not reached yet.
-    """
-    import core.perm_scope as perm_scope
-    return perm_scope.derive_pool_scope(session.user, MODULE)
-
-
-def _pool_stamp(rt, team_id, agent):
-    """The cached pool's build timestamp — the DATA STAMP in every measure-memo key, so a pool
-    refresh invalidates the memoised answers exactly when the underlying rows changed."""
-    entry = rt.pool_cache.get(("pool", team_id, agent))
-    return entry[0] if isinstance(entry, tuple) and entry else 0
-
-
-def _measure_err(tag, e):
-    try:
-        import harness.telemetry as _tel
-        _tel.error(f"api:{tag}", e)
-    except Exception:
-        pass
-
-
-def grid_assembly(session: Session, scope: str = "customer", storage_key: str = "",
-                  consume_corrections: bool = True):
-    """ONE assembly of this session's grid state, shared by `/customers`, `/workspace` and the
-    events route (2026-07-31 — the standalone measure gap, owner item 1).
-
-    What it adds over the pre-wave hand-rolled `_payload` loop, and why it replaced it:
-
-      * rows go through `aios_grid.rows_from_pool` — the SAME builder the embedded host uses,
-        so `lat`/`lon` (the Map view's data), `_created` and every derived column ride each row
-        by construction instead of by a second loop that drifts. The hand loop was written to
-        mirror the pre-Map contract and silently dropped the coordinates: the shell's Map view
-        had nothing to plot ("the Map no longer works").
-      * `derived` carries the cohort column's cells AND the measure columns' values, resolved
-        through `core.measure_resolve` (EXIT-5's extraction of the `_cl_measure_*` family).
-        Without them every measure column the owner built rendered BLANK in the shell.
-      * `measures` (the offer) and `measure_sets` (condition answers) are computed here so the
-        events route can finally validate measure fields/conditions instead of refusing them
-        (an empty `measure_offer` made `clean_measure_field` reject every create over HTTP).
-
-    Memos live on the TENANT RUNTIME (`rt.measure_memo` / `rt.mset_memo`) — bounded by the
-    module's own clear-past-cap rule, keyed on (stamp, scope, pool identity, question), nothing
-    user-shaped in them.
-    """
-    import aios_grid
-    from core import grid_events, measure_resolve
-
-    import core.perm_scope as perm_scope
-
-    rt = session.runtime
-    team_id, agent = _team_agent(session)
-    rows_src = _pool_for(rt, team_id, agent)
-    # ⛔ THE ROW WALL, APPLIED BEFORE `pids` IS TAKEN. Everything downstream is bounded by that
-    # frozenset — `allowed_pids` for the workspace, cohort membership, measure resolution — so
-    # scoping here means a row this account may not see never enters ANY of them, rather than
-    # being filtered out of one payload and surviving in another.
-    #
-    # Evaluated against the CANONICAL field list, not the per-user assembled one, for two
-    # reasons: the assembled list is not built yet (it needs `pids`), and a permanent filter may
-    # only ever name a canonical field anyway — `routes_admin._clean_perms` validates it against
-    # exactly this schema and 400s otherwise. `permits()` denies on anything it cannot answer.
-    rows_src = perm_scope.apply_row_scope(rows_src, session.user, MODULE, aios_grid.FIELDS)
-    pids = frozenset(r["pid"] for r in rows_src if r.get("pid") is not None)
-    ws = grid_events.table_workspace(
-        _ctx_for(session, pids), allowed_pids=pids,
-        consume_corrections=consume_corrections)
-    workspace, fields, views, lists = aios_grid.workspace_wire(
-        ws, session.uname, set(pids), defs={}, scope_key=scope, storage_key=storage_key)
-    # THE FIELD WALL — a TRANSITIVE closure (C-PERM amendment 5), so hiding a field also hides
-    # every formula computed FROM it. Formulas evaluate in the browser from `{ref}`s, so
-    # shipping a dependent formula while withholding its input either leaks the input through
-    # the formula's value or silently computes a wrong one; only removing both is coherent.
-    # Applied AFTER workspace_wire because custom + measure columns are what it must cover.
-    hidden = perm_scope.hidden_keys(session.user, MODULE, fields)
-    if hidden:
-        fields = [f for f in fields if f.get("key") not in hidden]
-        # The field LIST and the ROW payload are two different wires. Narrowing only the first
-        # would leave the value sitting in the second, where anything can read it.
-        rows_src = [perm_scope.strip_row(r, hidden) for r in rows_src]
-
-    today = time.strftime("%Y-%m-%d")
-    stamp = _pool_stamp(rt, team_id, agent)
-    measures = measure_resolve.offer(team_id, on_error=_measure_err)
-    measure_sets = measure_resolve.condition_sets(
-        [v.get("config") or {} for v in (views or [])], None, team_id, pids, today, stamp,
-        rt.mset_memo, on_error=_measure_err)
-    # The derived channel: cohort membership cells + measure column values, ONE dict — the
-    # same read-only channel the embed host hands to rows_from_pool.
-    derived = aios_grid.cohort_cells(lists)
-    for pid, cells in measure_resolve.column_values(
-            fields, team_id, pids, today, stamp, rt.measure_memo,
-            on_error=_measure_err).items():
-        derived.setdefault(pid, {}).update(cells)
-
-    return {"rows_src": rows_src, "pids": pids, "ws": ws, "workspace": workspace,
-            "fields": fields, "views": views, "lists": lists, "derived": derived,
-            "measures": measures, "measure_sets": measure_sets, "today": today,
-            "team_id": team_id}
-
-
-def _payload(session: Session):
-    """`{fields, rows, today, pulled_at}` — X2's shape, which `verify_fields_contract.py`
-    referees. Rows are now built by `aios_grid.rows_from_pool` (embed == standalone by
-    construction); see `grid_assembly` for what that fixed.
-
-    ⚠ `rows_src` is the SHARED cached list — `rows_from_pool` reads it and builds NEW dicts,
-    never mutating a cached row (the same-scope-second-user leak rule).
-    """
-    import aios_grid
-
-    g = grid_assembly(session)
-    rows = aios_grid.rows_from_pool(
-        g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"])
-    return {"fields": g["fields"], "rows": rows,
-            # `today` rides the payload because every relative date condition must resolve against
-            # the TENANT's day, never the browser's — a client that falls back to its own clock
-            # disagrees with the server for everyone west of it.
-            "today": g["today"],
-            "pulled_at": time.strftime("%Y-%m-%d %H:%M")}
-
-
-def _ctx_for(session: Session, pids):
-    """An EventCtx for the READ path — no fallback workspace, so a store outage is a 503 rather
-    than a phantom in-memory workspace an API request cannot persist."""
-    from core import grid_events
-    return grid_events.EventCtx(
-        uname=session.uname, allowed_pids=frozenset(pids or ()), fields=[],
-        # C-PERM: the write wall's field half. Computed from the CANONICAL contract because
-        # `fields=[]` here — the closure only needs the schema, not this user's column list.
-        hidden_keys=_hidden_for(session),
-        admin=session.admin, fallback_ws=None, seen_ids={})
-
-
-
-def _hidden_for(session: Session):
-    """The fields this session's permissions hide — the write wall's half of C-PERM.
-
-    Read paths strip these from both wires so they cannot be SEEN; this is what stops them
-    being WRITTEN by a caller who knows the key. Evaluated against the canonical contract, the
-    same schema `routes_admin._clean_perms` validates a hiddenFields entry against.
-    """
-    import aios_grid
-    import core.perm_scope as perm_scope
-
-    return perm_scope.hidden_keys(session.user, MODULE, aios_grid.FIELDS)
-
-def allowed_pids(session: Session):
-    """The pids this session may touch — the POOL's own ids, so the write wall and the read scope
-    can never disagree.
-
-    Reads `_pool_rows` rather than `_payload`: the wall only needs identities, and going through
-    the full payload would pay for a workspace read and a row assembly on every write.
-
-    ⛔ THE PERMANENT FILTER APPLIES HERE TOO, AND FORGETTING IT IS A WRITE-WITHOUT-READ HOLE.
-    `_pool_rows` is built with the DERIVED pushdown, which expresses only what a `(team_id,
-    agent)` pair can express. Any part of the wall the pushdown cannot carry — `revenue > 1000`,
-    a nested group, a condition on any other column — leaves the pool WIDER than the filter. Read
-    paths close that gap with `apply_row_scope`; without the same call here the write wall would
-    be the wider set, and a restricted user could PATCH a row this API will not show them.
-    Same function, same order as `grid_assembly`, so the two walls cannot drift.
-    """
-    import core.perm_scope as perm_scope
-    import aios_grid
-
-    rows = perm_scope.apply_row_scope(_pool_rows(session), session.user, MODULE,
-                                      aios_grid.FIELDS)
-    return frozenset(r["pid"] for r in rows if r.get("pid") is not None)
-
-
-@router.get("/customers")
-def customers(session: Session = Depends(module_gate(MODULE))):
-    return _payload(session)
-
-
-@router.patch("/customers/{pid}")
-def patch_customer(pid: int, body: dict = Body(default=None),
-                   session: Session = Depends(module_gate(MODULE))):
-    """Write the EDITABLE overlay stratum only — Odoo stays read-only, forever.
-
-    Routed through `core.grid_events.handle_one` as an `overlay_patch` event rather than writing
-    the store directly: that handler is where the per-key `permissions.edit` wall, the pid wall
-    and the truncation rules live, and a second implementation of those would be a second set of
-    them to keep in step. The response reports what was ACCEPTED, which is not always what was
-    asked for.
-    """
-    from core import grid_events
-
-    updates = dict(body or {})
-    if not updates:
-        raise err(400, "empty_patch", "no fields to update")
-    pool = allowed_pids(session)
-    if pid not in pool:
-        # 403, not 404: the pid may well exist — it is simply not in this session's book, and
-        # saying "no such customer" would confirm the opposite to anyone who guessed right.
-        raise err(403, "out_of_scope", "that customer is not in your book")
-    payload = _payload(session)
-    ctx = grid_events.EventCtx(
-        uname=session.uname, allowed_pids=pool, fields=payload["fields"],
-        admin=session.admin, fallback_ws=None, seen_ids={},
-        hidden_keys=_hidden_for(session))
-    try:
-        grid_events.handle_one(
-            {"id": f"patch:{pid}:{time.time_ns()}", "type": "overlay_patch",
-             "pid": pid, "updates": updates}, ctx)
-    except grid_events.StoreUnavailable:
-        raise err(503, "store_unavailable",
-                  "the tenant store is unavailable — your change was not saved")
-
-    # What actually landed, read back from the store rather than echoed from the request: a
-    # refused key or a truncated value must not be reported as accepted.
-    stored = (grid_events.table_workspace(_ctx_for(session, pool), allowed_pids=None)
-              .get("overlays") or {}).get(str(pid)) or {}
-    accepted = {k: stored.get(k) for k in updates if k in stored}
-    refused = sorted(k for k in updates if k not in accepted or stored.get(k) != str(updates[k]))
-    # No cache to patch: the overlay stratum is re-read from the store on every `_payload`, so
-    # read-your-writes within this runtime is a property of the design rather than of a
-    # write-through step somebody has to remember. (It was a write-through step while the whole
-    # payload was cached on a scope key — the arrangement that leaked one user's notes to
-    # another. See `_pool_rows`.) Cross-RUNTIME coherence is still not claimed: the module
-    # docstring says why, and Postgres is the fix.
-    out = {"ok": True, "pid": pid, "updates": accepted}
-    if refused:
-        out["refused"] = refused
-    return out
+"""routes_customers.py — X2's read + write of the customer table, BU-SCOPED (EXIT-3b / EXIT-2a).
+
+Two things happen here that did not happen in the pre-wave `main.py`:
+
+  1. **ROWS ARE SCOPED TO THE SESSION.** The old `/api/customers` served `cl.pool()` — the whole
+     book, to anyone holding the shared APP_PASSWORD. Now the pool is built with
+     `(team_id, agent_name)` derived from the USER RECORD, so a Royal-only user never receives a
+     Fisch row and an agent-linked login never receives another rep's book. The scope is applied
+     at the QUERY, not as a post-filter, so there is no moment at which the other BU's rows exist
+     in this response.
+
+  2. **THE OVERLAY FORK IS GONE.** `aios-web/api/data/overlay.json` was a SECOND writable home
+     for the same user-owned fields the Streamlit app keeps in the tenant store — two truths, and
+     whichever process you asked last was right. Reads and writes now both go through
+     `modules.customer_data`'s table-workspace functions: ONE store (C1c, ARCHITECTURE §1a rule 3).
+
+⚠ ONE STORE IS NOT YET ONE CACHE (strangler-period, booked honestly). `core.store.get()` is
+cache-first per PROCESS, so a write from the Streamlit container is invisible to a running API
+container until its cache is refreshed, and vice versa. Deleting the fork removes the second
+SOURCE OF TRUTH; it does not make the two runtimes coherent. The fix is X4/Postgres (task C-4,
+owner-blocked on B-3), and no test here may claim read-your-writes ACROSS runtimes — a TestClient
+proof is single-process and would report green on exactly the thing that is still broken.
+"""
+import time
+
+from fastapi import APIRouter, Body, Depends
+
+import scope_cache
+from deps import Session, err, module_gate, perms
+
+router = APIRouter(prefix="/api/v1")
+
+#: The surface these routes serve. Both legs are gated on it, so a user without the grant gets a
+#: 403 rather than an empty table that looks like "you have no customers".
+MODULE = "customer_data"
+
+_CACHE_TTL = 900       # the pool build is slow (Odoo + reconciliation); 15 min, as before
+
+
+def _pool_rows(session: Session):
+    """The reconciled Odoo pool for this session's SCOPE — the slow part, and the only part that
+    may be shared between users.
+
+    ⛔ WHAT MAY BE CACHED HERE, AND WHY THE LINE IS EXACTLY HERE. The cache key is
+    `(team_id, agent)` and the cached value is the raw pool: Odoo-source columns only. That is
+    genuinely scope-shaped — two users with the same BU and the same book are asking the same
+    question, and `cl.pool()` is expensive (an Odoo pull plus reconciliation).
+
+    The FULL PAYLOAD is NOT cacheable on this key, and caching it here was a real defect I shipped
+    and then removed. `fields` comes from `fields_from_workspace(ws)` — that user's own `custom_`
+    and `measure_` columns — and every overlay cell comes from `ws['overlays']`; the table
+    workspace is read as `data[username]` and written as `patch_table_overlay(uname, …)`, i.e.
+    PER USER. So two Royal-only users with no agent link share `(6, None)` and the second one
+    would have been served the FIRST one's private notes and private columns. The scope key was
+    right for the pool and wrong for everything wrapped around it.
+
+    It survived a green 129-check battery because every fixture user had a DISTINCT
+    `(team_id, agent)` pair, so no two of them ever collided on the key — the test set could not
+    express the bug. `verify_api.py` now carries a same-scope second user for exactly this.
+    """
+    rt = session.runtime
+    team_id, agent = _team_agent(session)
+    return _pool_for(rt, team_id, agent)
+
+
+def _pool_for(rt, team_id, agent):
+    """The cached pool for an explicit scope — session-free so the prewarm thread and the
+    stale-refresh path can call it. STALE-WHILE-REFRESH (scope_cache): once a copy exists no
+    request blocks on the 10–30s Odoo rebuild again; only a scope's FIRST-ever build does.
+
+    DEBT-2 (2026-08-04): while the tenant's RESOLVED Odoo source is PAUSED this path never
+    goes live — it serves the in-process copy at any age, else the persisted pause-time
+    snapshot (restart-safe), else answers 503. Never a WIDER scope's snapshot: handing a
+    scoped user the consolidated rows would widen their book, which is worse than an error."""
+    import modules.customer_data as cl
+    import routes_keychain
+
+    key = ("pool", team_id, agent)
+
+    if routes_keychain.odoo_paused(rt):
+        hit = rt.pool_cache.get(key)
+        if hit:
+            return hit[1]
+        snap = routes_keychain.load_pool_snapshot(rt, team_id, agent)
+        if snap is not None:
+            rt.pool_cache[key] = snap          # seed, so the memo stamps stay coherent
+            return snap[1]
+        raise err(503, "connector_paused",
+                  "this data source is paused and no snapshot exists for your scope — "
+                  "an admin can resume it under Settings → Connectors")
+
+    def _build():
+        # ⚠ THE SCOPE GOES INTO THE BUILDER. `pool(agent_name, team_id)` is the same reconciled
+        # builder the Streamlit page uses — passing the scope here is what makes the isolation a
+        # property of the QUERY instead of a filter someone can forget to apply downstream.
+        return cl.pool(agent, team_id)
+
+    def _evict():
+        # Bounded: a scope cache that only ever grows is a memory leak in a shared process.
+        if len(rt.pool_cache) > 16:
+            for stale in sorted(rt.pool_cache, key=lambda k: rt.pool_cache[k][0])[:8]:
+                rt.pool_cache.pop(stale, None)
+
+    return scope_cache.get(rt.pool_cache, key, _CACHE_TTL, _build, _evict)
+
+
+def warm_default(rt):
+    """Boot prewarm: the consolidated pool `(None, None)` — the scope every admin and every
+    all-BU account lands on. Called from main.py's prewarm thread only."""
+    _pool_for(rt, None, None)
+
+
+def _team_agent(session: Session):
+    """The `(team_id, agent)` this session's POOL is built with — ONE derivation point, used by
+    `_pool_rows` and `grid_assembly` alike, so the cache key and the query can never disagree.
+
+    ⛔ WAVE 15 R1: THIS NOW COMES FROM THE PERMANENT FILTER (C-PERM amendment 3). `team_id` is
+    not a row filter — `customer_data._pool_build` passes it into `cust._cust_rev` three times
+    and into `_cadence_bulk`, so it decides what `rev`/`ly`/`ltm`/`aov`/`status` MEAN. Enforcing
+    a BU purely as a post-filter would keep the row list right and silently consolidate every
+    number. So the pushdown survives as a DERIVATION OF the declared filter rather than a second
+    wall beside it, and `perm_scope.derive_pool_scope` falls back to the legacy `bus`/`agent`
+    derivation for any record the migration has not reached yet.
+    """
+    import core.perm_scope as perm_scope
+    return perm_scope.derive_pool_scope(session.user, MODULE)
+
+
+def _pool_stamp(rt, team_id, agent):
+    """The cached pool's build timestamp — the DATA STAMP in every measure-memo key, so a pool
+    refresh invalidates the memoised answers exactly when the underlying rows changed."""
+    entry = rt.pool_cache.get(("pool", team_id, agent))
+    return entry[0] if isinstance(entry, tuple) and entry else 0
+
+
+def _measure_err(tag, e):
+    try:
+        import harness.telemetry as _tel
+        _tel.error(f"api:{tag}", e)
+    except Exception:
+        pass
+
+
+def grid_assembly(session: Session, scope: str = "customer", storage_key: str = "",
+                  consume_corrections: bool = True):
+    """ONE assembly of this session's grid state, shared by `/customers`, `/workspace` and the
+    events route (2026-07-31 — the standalone measure gap, owner item 1).
+
+    What it adds over the pre-wave hand-rolled `_payload` loop, and why it replaced it:
+
+      * rows go through `aios_grid.rows_from_pool` — the SAME builder the embedded host uses,
+        so `lat`/`lon` (the Map view's data), `_created` and every derived column ride each row
+        by construction instead of by a second loop that drifts. The hand loop was written to
+        mirror the pre-Map contract and silently dropped the coordinates: the shell's Map view
+        had nothing to plot ("the Map no longer works").
+      * `derived` carries the cohort column's cells AND the measure columns' values, resolved
+        through `core.measure_resolve` (EXIT-5's extraction of the `_cl_measure_*` family).
+        Without them every measure column the owner built rendered BLANK in the shell.
+      * `measures` (the offer) and `measure_sets` (condition answers) are computed here so the
+        events route can finally validate measure fields/conditions instead of refusing them
+        (an empty `measure_offer` made `clean_measure_field` reject every create over HTTP).
+
+    Memos live on the TENANT RUNTIME (`rt.measure_memo` / `rt.mset_memo`) — bounded by the
+    module's own clear-past-cap rule, keyed on (stamp, scope, pool identity, question), nothing
+    user-shaped in them.
+    """
+    import aios_grid
+    from core import grid_events, measure_resolve
+
+    import core.perm_scope as perm_scope
+
+    rt = session.runtime
+    team_id, agent = _team_agent(session)
+    rows_src = _pool_for(rt, team_id, agent)
+    # ⛔ THE ROW WALL, APPLIED BEFORE `pids` IS TAKEN. Everything downstream is bounded by that
+    # frozenset — `allowed_pids` for the workspace, cohort membership, measure resolution — so
+    # scoping here means a row this account may not see never enters ANY of them, rather than
+    # being filtered out of one payload and surviving in another.
+    #
+    # Evaluated against the CANONICAL field list, not the per-user assembled one, for two
+    # reasons: the assembled list is not built yet (it needs `pids`), and a permanent filter may
+    # only ever name a canonical field anyway — `routes_admin._clean_perms` validates it against
+    # exactly this schema and 400s otherwise. `permits()` denies on anything it cannot answer.
+    rows_src = perm_scope.apply_row_scope(rows_src, session.user, MODULE, aios_grid.FIELDS)
+    pids = frozenset(r["pid"] for r in rows_src if r.get("pid") is not None)
+    ws = grid_events.table_workspace(
+        _ctx_for(session, pids), allowed_pids=pids,
+        consume_corrections=consume_corrections)
+    workspace, fields, views, lists = aios_grid.workspace_wire(
+        ws, session.uname, set(pids), defs={}, scope_key=scope, storage_key=storage_key)
+    # THE FIELD WALL — a TRANSITIVE closure (C-PERM amendment 5), so hiding a field also hides
+    # every formula computed FROM it. Formulas evaluate in the browser from `{ref}`s, so
+    # shipping a dependent formula while withholding its input either leaks the input through
+    # the formula's value or silently computes a wrong one; only removing both is coherent.
+    # Applied AFTER workspace_wire because custom + measure columns are what it must cover.
+    hidden = perm_scope.hidden_keys(session.user, MODULE, fields)
+    if hidden:
+        fields = [f for f in fields if f.get("key") not in hidden]
+        # The field LIST and the ROW payload are two different wires. Narrowing only the first
+        # would leave the value sitting in the second, where anything can read it.
+        rows_src = [perm_scope.strip_row(r, hidden) for r in rows_src]
+
+    today = time.strftime("%Y-%m-%d")
+    stamp = _pool_stamp(rt, team_id, agent)
+    measures = measure_resolve.offer(team_id, on_error=_measure_err)
+    measure_sets = measure_resolve.condition_sets(
+        [v.get("config") or {} for v in (views or [])], None, team_id, pids, today, stamp,
+        rt.mset_memo, on_error=_measure_err)
+    # The derived channel: cohort membership cells + measure column values, ONE dict — the
+    # same read-only channel the embed host hands to rows_from_pool.
+    derived = aios_grid.cohort_cells(lists)
+    for pid, cells in measure_resolve.column_values(
+            fields, team_id, pids, today, stamp, rt.measure_memo,
+            on_error=_measure_err).items():
+        derived.setdefault(pid, {}).update(cells)
+
+    return {"rows_src": rows_src, "pids": pids, "ws": ws, "workspace": workspace,
+            "fields": fields, "views": views, "lists": lists, "derived": derived,
+            "measures": measures, "measure_sets": measure_sets, "today": today,
+            "team_id": team_id}
+
+
+def _payload(session: Session):
+    """`{fields, rows, today, pulled_at}` — X2's shape, which `verify_fields_contract.py`
+    referees. Rows are now built by `aios_grid.rows_from_pool` (embed == standalone by
+    construction); see `grid_assembly` for what that fixed.
+
+    ⚠ `rows_src` is the SHARED cached list — `rows_from_pool` reads it and builds NEW dicts,
+    never mutating a cached row (the same-scope-second-user leak rule).
+    """
+    import aios_grid
+
+    g = grid_assembly(session)
+    rows = aios_grid.rows_from_pool(
+        g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"])
+    return {"fields": g["fields"], "rows": rows,
+            # `today` rides the payload because every relative date condition must resolve against
+            # the TENANT's day, never the browser's — a client that falls back to its own clock
+            # disagrees with the server for everyone west of it.
+            "today": g["today"],
+            "pulled_at": time.strftime("%Y-%m-%d %H:%M")}
+
+
+def _ctx_for(session: Session, pids):
+    """An EventCtx for the READ path — no fallback workspace, so a store outage is a 503 rather
+    than a phantom in-memory workspace an API request cannot persist."""
+    from core import grid_events
+    return grid_events.EventCtx(
+        uname=session.uname, allowed_pids=frozenset(pids or ()), fields=[],
+        # C-PERM: the write wall's field half. Computed from the CANONICAL contract because
+        # `fields=[]` here — the closure only needs the schema, not this user's column list.
+        hidden_keys=_hidden_for(session),
+        admin=session.admin, fallback_ws=None, seen_ids={})
+
+
+
+def _hidden_for(session: Session):
+    """The fields this session's permissions hide — the write wall's half of C-PERM.
+
+    Read paths strip these from both wires so they cannot be SEEN; this is what stops them
+    being WRITTEN by a caller who knows the key. Evaluated against the canonical contract, the
+    same schema `routes_admin._clean_perms` validates a hiddenFields entry against.
+    """
+    import aios_grid
+    import core.perm_scope as perm_scope
+
+    return perm_scope.hidden_keys(session.user, MODULE, aios_grid.FIELDS)
+
+def allowed_pids(session: Session):
+    """The pids this session may touch — the POOL's own ids, so the write wall and the read scope
+    can never disagree.
+
+    Reads `_pool_rows` rather than `_payload`: the wall only needs identities, and going through
+    the full payload would pay for a workspace read and a row assembly on every write.
+
+    ⛔ THE PERMANENT FILTER APPLIES HERE TOO, AND FORGETTING IT IS A WRITE-WITHOUT-READ HOLE.
+    `_pool_rows` is built with the DERIVED pushdown, which expresses only what a `(team_id,
+    agent)` pair can express. Any part of the wall the pushdown cannot carry — `revenue > 1000`,
+    a nested group, a condition on any other column — leaves the pool WIDER than the filter. Read
+    paths close that gap with `apply_row_scope`; without the same call here the write wall would
+    be the wider set, and a restricted user could PATCH a row this API will not show them.
+    Same function, same order as `grid_assembly`, so the two walls cannot drift.
+    """
+    import core.perm_scope as perm_scope
+    import aios_grid
+
+    rows = perm_scope.apply_row_scope(_pool_rows(session), session.user, MODULE,
+                                      aios_grid.FIELDS)
+    return frozenset(r["pid"] for r in rows if r.get("pid") is not None)
+
+
+@router.get("/customers")
+def customers(session: Session = Depends(module_gate(MODULE))):
+    return _payload(session)
+
+
+@router.patch("/customers/{pid}")
+def patch_customer(pid: int, body: dict = Body(default=None),
+                   session: Session = Depends(module_gate(MODULE))):
+    """Write the EDITABLE overlay stratum only — Odoo stays read-only, forever.
+
+    Routed through `core.grid_events.handle_one` as an `overlay_patch` event rather than writing
+    the store directly: that handler is where the per-key `permissions.edit` wall, the pid wall
+    and the truncation rules live, and a second implementation of those would be a second set of
+    them to keep in step. The response reports what was ACCEPTED, which is not always what was
+    asked for.
+    """
+    from core import grid_events
+
+    updates = dict(body or {})
+    if not updates:
+        raise err(400, "empty_patch", "no fields to update")
+    pool = allowed_pids(session)
+    if pid not in pool:
+        # 403, not 404: the pid may well exist — it is simply not in this session's book, and
+        # saying "no such customer" would confirm the opposite to anyone who guessed right.
+        raise err(403, "out_of_scope", "that customer is not in your book")
+    payload = _payload(session)
+    ctx = grid_events.EventCtx(
+        uname=session.uname, allowed_pids=pool, fields=payload["fields"],
+        admin=session.admin, fallback_ws=None, seen_ids={},
+        hidden_keys=_hidden_for(session))
+    try:
+        grid_events.handle_one(
+            {"id": f"patch:{pid}:{time.time_ns()}", "type": "overlay_patch",
+             "pid": pid, "updates": updates}, ctx)
+    except grid_events.StoreUnavailable:
+        raise err(503, "store_unavailable",
+                  "the tenant store is unavailable — your change was not saved")
+
+    # What actually landed, read back from the store rather than echoed from the request: a
+    # refused key or a truncated value must not be reported as accepted.
+    stored = (grid_events.table_workspace(_ctx_for(session, pool), allowed_pids=None)
+              .get("overlays") or {}).get(str(pid)) or {}
+    accepted = {k: stored.get(k) for k in updates if k in stored}
+    refused = sorted(k for k in updates if k not in accepted or stored.get(k) != str(updates[k]))
+    # No cache to patch: the overlay stratum is re-read from the store on every `_payload`, so
+    # read-your-writes within this runtime is a property of the design rather than of a
+    # write-through step somebody has to remember. (It was a write-through step while the whole
+    # payload was cached on a scope key — the arrangement that leaked one user's notes to
+    # another. See `_pool_rows`.) Cross-RUNTIME coherence is still not claimed: the module
+    # docstring says why, and Postgres is the fix.
+    out = {"ok": True, "pid": pid, "updates": accepted}
+    if refused:
+        out["refused"] = refused
+    return out

api/routes_grid.py

@@ -1,832 +1,832 @@
-"""routes_grid.py — X2's write seam over HTTP: the SECOND adapter on `core.grid_events` (EXIT-1c).
-
-`POST /api/v1/grid/events` takes the component's event objects VERBATIM — the same objects the
-Streamlit host receives through the component value slot, unchanged — and runs them through the
-same `core.grid_events.handle_events` the Streamlit adapter runs. That is the whole point of
-EXIT-1a: one implementation of every permission wall, two transports. A route that re-validated
-anything here would be a second wall to keep in step, and the two would drift on the first change.
-
-DEDUP IS PER REQUEST, and that is a deliberate limit, not an oversight. The Streamlit adapter's
-`seen_ids` lives in `st.session_state` — genuinely per user session — because the client resends
-its recent 24-event window on every emit inside one page session. A stateless API has no such
-dict, and inventing a per-user server-side one would be exactly the resident per-tenant state
-EXIT-4a exists to remove. So: ids are deduped WITHIN a request body (the resend window's whole
-purpose — a batch that repeats an id processes it once), and a genuinely replayed request is
-handled by the operations being idempotent. The one event where a replay is observable is
-`add_to_list` (it would add the same pids to the same cohort twice — a set union, so the
-membership is unchanged, but the toast count repeats). Noted rather than papered over; a
-server-side idempotency key belongs with D2's session mirror (C-2).
-
-STORE DOWN = 503. `fallback_ws` is None on this adapter, so `core.grid_events` raises
-`StoreUnavailable` rather than writing to an in-memory workspace no API request could ever read
-back. A 200 over a write that evaporated is the failure this rule exists to prevent.
-"""
-import datetime as dt
-import time
-
-from fastapi import APIRouter, Body, Depends
-
-from deps import Session, err, module_gate, perms, require_session
-
-router = APIRouter(prefix="/api/v1")
-
-MODULE = "customer_data"
-
-#: The client's own resend window (`app.py`'s `[-24:]`). A body larger than this is not a
-#: legitimate client — refuse it rather than doing 500 store writes on one request.
-_MAX_EVENTS = 24
-
-
-def _ctx(session: Session, fields, pids, **kw):
-    from core import grid_events
-    import aios_grid
-    import core.perm_scope as perm_scope
-
-    # Wave 16 C-TOPIC: the ctx is TOPIC-SHAPED. The product scope swaps all three of the
-    # things a write is validated against — the module the permission wall reads, the canonical
-    # contract the hidden-field closure runs over, and the TABLE OPS the write lands in.
-    # Getting any one of them from the other topic is the "validated against the wrong field
-    # contract" near-miss the wave-15 routes_products header warned about.
-    scope_key = str(kw.get("scope_key") or "")
-    if scope_key == "product":
-        import modules.product_data as pd
-        from routes_products import MODULE as _PMOD, pd_fields
-
-        module, canonical = _PMOD, pd_fields(consolidated=True)
-        kw.setdefault("table", pd.TABLE_OPS)
-        hidden = perm_scope.hidden_keys(session.user, module, canonical)
-    elif scope_key.startswith("ut_"):
-        # Wave 18 C3-UT: a user table has no module in the permission wall (its wall is
-        # `user_tables.may_open`, already applied by the assembly this route ran first), so
-        # the hidden-field closure is EMPTY rather than borrowed from another topic's contract.
-        import core.table_store as table_store
-
-        kw.setdefault("table",
-                      table_store.make(f"{scope_key}_table_workspace", st=session.runtime))
-        hidden = frozenset()
-    else:
-        module, canonical = MODULE, aios_grid.FIELDS
-        hidden = perm_scope.hidden_keys(session.user, module, canonical)
-    return grid_events.EventCtx(
-        uname=session.uname, allowed_pids=pids, fields=fields, admin=session.admin,
-        # C-PERM: the write wall's field half, on the EVENTS transport too. This route takes the
-        # component's event objects verbatim, so a hidden key would otherwise arrive here with
-        # nothing between it and the store.
-        hidden_keys=hidden,
-        # ⭐ WAVE 25 (R6b, closes D-16) — THE TENANT HANDLE, on EVERY scope. This is the line
-        # D-16's exit condition names, and without it the rest of the fix is inert: the handler
-        # falls back to the module-global `core.store`, which is tenant #0's repo, so a Nurilab
-        # user's documents, cohorts and — through `_tops` — their whole customer/product table
-        # workspace were written into Royal Imports' dataset. Note it is set for the CUSTOMER
-        # and PRODUCT branches too, not only `ut_`: those two never passed a scoped `table`, so
-        # they were the ones actually resolving to tenant #0 on every request.
-        st=session.runtime,
-        fallback_ws=None, seen_ids={}, **kw)
-
-
-#: The surfaces the ONE grid serves. `cohort` is the same table over hand-curated SETS rather
-#: than over the whole scoped pool — `app.py:page_cohort` calls the same `_table_grid` with
-#: `cohort_mode=True, scope_key='cohort'`. `product` (wave 16 C-TOPIC) is the SKU table:
-#: same engine, its own pool, field contract and workspace BUCKET (routes_products).
-_SCOPES = ("customer", "cohort", "product")
-
-
-def _scope_or_400(raw):
-    """⛔ REFUSE AN UNKNOWN SCOPE, never default it. A typo silently served as `customer` would
-    hand a user the whole book on a page they opened to see one cohort — the widening direction,
-    which is the one that must fail closed.
-
-    Wave 18 (C3-UT): a `ut_`-prefixed scope names a USER TABLE and passes through here —
-    existence and the per-table wall are enforced by `routes_tables.ut_assembly` (404/403),
-    which every consumer of such a scope goes through. Passing an unknown ut key therefore
-    still fails closed, just one layer down where the store can actually be consulted."""
-    scope = (raw or "customer").strip().lower()
-    if scope.startswith("ut_"):
-        return scope
-    if scope not in _SCOPES:
-        raise err(400, "bad_scope",
-                  f"scope must be one of {', '.join(_SCOPES)} — refusing to guess")
-    return scope
-
-
-@router.get("/workspace")
-def workspace(scope: str = "customer",
-              session: Session = Depends(require_session)):
-    """The durable table workspace for this session: views, fields, overlays, folders.
-
-    ⛔ WAVE 21 (C4): the wall is TOPIC-SHAPED, so the DEPENDENCY is session-only and each scope
-    asserts its own gate below. The old `module_gate("customer_data")` dependency 403'd a
-    `ut_*` workspace for any tenant whose catalogue omits the customer module (loopable/
-    nurilab/gtmlab ship modules w/o it) — and the client then fell back to the shared
-    localStorage bucket + demo data, which is exactly the "new database shows RI's customer
-    fields" defect. A user table's real wall is `user_tables.may_open`, enforced inside
-    `ut_assembly` (404/403, one layer down where the store can be consulted).
-
-    ⚠ WHY THIS EXISTS (S1↔S2, 2026-07-30 — an X2 AMENDMENT, see the split doc). X2 fixes
-    `/customers` at the exact shape `verify_fields_contract.py` referees, so the workspace cannot
-    ride along in it without forking the thing that gate keeps single-sourced. Without a
-    workspace route the standalone shell's write path would be WRITE-ONLY: events persist
-    server-side and nothing reads them back on reload, so a saved view looks lost to the user
-    even though the store has it. This route closes that read-back gap at its own URL.
-
-    `allowed_pids` is passed so a SHARED view's `memberPids` are re-scoped to THIS reader — the
-    wave-9 leak rule. Omitting it would hand a Fisch-scoped user a member list built by a
-    full-access user.
-    """
-    from core import grid_events
-    from routes_customers import grid_assembly
-
-    scope = _scope_or_400(scope)
-    # Wave 21 C4 — the per-scope gate the dependency no longer asserts: customer/cohort need
-    # the customer module; product asserts PRODUCT_MODULE in its branch; ut_* needs only a
-    # session (its wall is the table's own, inside the assembly).
-    if not (scope == "product" or scope.startswith("ut_")):
-        session.require(MODULE)
-    # ── Wave 18 C3-UT: a USER TABLE'S workspace — the third topic through the one wire. The
-    # storage key has no (bu, agent) because a user table has no Odoo scope; per-user by the
-    # table's own wall (creator or admin, `user_tables.may_open`).
-    if scope.startswith("ut_"):
-        from routes_tables import ut_assembly
-
-        storage_key = f"{session.tenant}:{scope}:{session.uname}"
-        try:
-            g = ut_assembly(session, scope, storage_key=storage_key)
-        except grid_events.StoreUnavailable:
-            raise err(503, "store_unavailable", "the tenant store is unavailable")
-        workspace = g["workspace"]
-        workspace["overlays"] = g["ws"].get("overlays") or {}
-        # The field contract rides the cheap re-read on EVERY topic — see the customer branch
-        # below for why (a user table's first cohort changes its contract too: `_cohorts(ctx)`
-        # is scope-parameterized, so `ut_` surfaces have their own sets).
-        workspace["fields"] = g["fields"]
-        workspace["measures"] = g["measures"]
-        workspace["measureSets"] = g["measure_sets"]
-        # ⚠ `g["derived"]`, NOT `{}` (2026-08-04). R9 gave every topic its own cohort sets, and
-        # `ut_assembly` has been building this topic's cohort CELLS since — but this route threw
-        # them away, so the Locked-views column arrived on the cheap re-read with permanently
-        # empty values. A column that exists and can never have one is worse than an absent
-        # column: it reads as "this record is in no locked view", which is a claim.
-        workspace["derived"] = {str(pid): cells for pid, cells in (g["derived"] or {}).items()}
-        workspace["viewer"] = {"name": session.uname, "isAdmin": bool(session.admin)}
-        try:
-            from core import users as _users
-            workspace["userOptions"] = _users.assignable_people(tenant=session.tenant)
-            workspace["userAvatars"] = {k: v for k, v in
-                                        _users.avatar_map(tenant=session.tenant).items()
-                                        if str(v).startswith("data:image/")}
-        except Exception:
-            workspace["userOptions"] = []
-            workspace["userAvatars"] = {}
-        workspace["scopeKey"] = scope
-        return {"workspace": workspace}
-
-    # ── Wave 16 C-TOPIC: the PRODUCT surface has its own assembly (own pool, own field
-    # contract, own workspace BUCKET) and the contract's own storage key. It branches before
-    # the customer derivation because the customer storage key embeds (bu, agent) while the
-    # product one is deliberately `all:all` — one product workspace per user (the wave doc's
-    # C-TOPIC line), since BU narrows the product VALUES, not which workspace you own.
-    if scope == "product":
-        from routes_products import MODULE as PRODUCT_MODULE, product_assembly
-
-        # ⛔ THE GATE CHANGES WITH THE SCOPE (wave 21 C4: the dependency is session-only now,
-        # so this line IS the product wall — not a second one on top of customer_data).
-        session.require(PRODUCT_MODULE)
-        storage_key = f"{session.tenant}:product-list:{session.uname}:all:all"
-        try:
-            g = product_assembly(session, scope=scope, storage_key=storage_key)
-        except grid_events.StoreUnavailable:
-            raise err(503, "store_unavailable", "the tenant store is unavailable")
-        workspace = g["workspace"]
-        workspace["overlays"] = g["ws"].get("overlays") or {}
-        # R9 made cohorts per-topic, so the PRODUCT surface has its own sets and its own
-        # first-cohort contract change. Same reason as the customer branch below.
-        workspace["fields"] = g["fields"]
-        # The measure channel is EMPTY on this topic (customer-grain descope) — stated
-        # explicitly so the client's pickers grey rather than guess.
-        workspace["measures"] = g["measures"]
-        workspace["measureSets"] = g["measure_sets"]
-        # `g["derived"]` — the same correction as the user-table branch above, for the same
-        # reason: `product_assembly` builds this topic's cohort cells and this route discarded
-        # them. The measure half stays empty on this topic by descope, which is a different
-        # statement and one the offer already makes.
-        workspace["derived"] = {str(pid): cells for pid, cells in (g["derived"] or {}).items()}
-        workspace["viewer"] = {"name": session.uname, "isAdmin": bool(session.admin)}
-        try:
-            from core import users as _users
-            workspace["userOptions"] = _users.assignable_people(tenant=session.tenant)
-            workspace["userAvatars"] = {k: v for k, v in
-                                        _users.avatar_map(tenant=session.tenant).items()
-                                        if str(v).startswith("data:image/")}
-        except Exception:
-            workspace["userOptions"] = []
-            workspace["userAvatars"] = {}
-        workspace["scopeKey"] = scope
-        return {"workspace": workspace}
-
-    # The storage key mirrors the host's own convention byte-for-byte (app.py's `_table_grid`
-    # call sites) with the session's TENANT in the host's hardcoded slot, so localStorage state
-    # carries across embed ⇄ standalone on the same browser.
-    # Wave 15 R1 — the SAME derivation the pool uses (`routes_customers._team_agent`), so the
-    # storage key cannot drift from the scope it names. Value-identical for every migrated
-    # record (verify_perm_scope section D proves the derivation reproduces the legacy scope
-    # exactly), so nobody's saved localStorage state moves when the migration runs.
-    import core.perm_scope as perm_scope
-    team_id, agent = perm_scope.derive_pool_scope(session.user, MODULE)
-    bu = team_id if team_id is not None else "all"
-    if scope == "cohort":
-        storage_key = f"{session.tenant}:cohort:{session.uname}:{bu}"
-    else:
-        storage_key = f"{session.tenant}:customer-list:{session.uname}:{bu}:{agent or 'all'}"
-
-    # ⛔ THE WIRE SHAPE IS THE SHARED PROJECTION (`aios_grid.workspace_wire`), not the store
-    # shape. The first version returned the store dict with no `storageKey` — and the client
-    # validator requires one, so the standalone shell DISCARDED the whole workspace: saved views
-    # never rendered, `cohortMode` never arrived, and the Cohort route silently drew the Customer
-    # surface. One projection for both servers is the fix that cannot drift.
-    try:
-        g = grid_assembly(session, scope=scope, storage_key=storage_key)
-    except grid_events.StoreUnavailable:
-        raise err(503, "store_unavailable", "the tenant store is unavailable")
-    workspace = g["workspace"]
-    # ADDITIVE to the wire: the caller's own overlay cells. The grid reads overlays from the
-    # /customers rows, but this route is the cheap read-back a write can be verified against
-    # (verify_api's overlay probe) without paying the pool call. Per-user by construction —
-    # `table_workspace` is this session's workspace.
-    workspace["overlays"] = g["ws"].get("overlays") or {}
-    # ⭐ THE FIELD CONTRACT, 2026-08-04 — and it is NOT decoration.
-    #
-    # `fields_from_workspace(ws, cohorts=bool(cohort_lists))` appends the derived "Locked
-    # views" column ONLY when the caller owns at least one cohort. So a user's FIRST cohort
-    # CHANGES THE FIELD CONTRACT — and the rows call that used to be the only carrier of
-    # `fields` is deliberately never re-fetched on a write (it is a 15-minute-cached Odoo
-    # pull; this route is the cheap re-read). The client therefore had no way to learn about
-    # that column short of a remount, which is the second half of the owner's "it only shows
-    # up when I switch modules and come back".
-    #
-    # ⚠ `g["fields"]` is the SAME list `_payload` serves on `/customers` — same assembly,
-    # same permission wall (`hidden_keys` already applied) — so the two wires cannot disagree
-    # about what a column is. Taking it from anywhere else would fork the contract that
-    # verify_fields_contract.py exists to keep single-sourced.
-    workspace["fields"] = g["fields"]
-    # ── the STANDALONE measure channel (owner item 1, 2026-07-31) ────────────────────────────
-    # The embed receives these as top-level render args; standalone lifts them off THIS route
-    # (useCustomerData merges them into the payload slots the grid already reads). They ride
-    # the workspace rather than /customers because a durable write re-reads exactly this route
-    # (WORKSPACE_STALE), so a new measure column populates without refetching the heavy pool.
-    workspace["measures"] = g["measures"]
-    workspace["measureSets"] = g["measure_sets"]
-    # Derived cells (cohort column + measure columns), keyed by pid. JSON object keys are
-    # strings; the client indexes with String(pid).
-    workspace["derived"] = {str(pid): cells for pid, cells in g["derived"].items()}
-    # Who is looking (permissions verdicts) + the assignee choices for `user`-typed columns —
-    # the two other host-only render args the shell was missing (fail-closed without them:
-    # restricted fields uneditable, assignee picker empty).
-    workspace["viewer"] = {"name": session.uname, "isAdmin": bool(session.admin)}
-    try:
-        from core import users as _users
-        workspace["userOptions"] = _users.assignable_people(tenant=session.tenant)
-        # Wave 14 C-AVATAR — the options vocabulary's companion: display name -> data URL.
-        # Absent entries fall back to the client's initials disc; a non-data: value is
-        # dropped (defence in depth beside the write-side wall in routes_auth).
-        workspace["userAvatars"] = {k: v for k, v in
-                                    _users.avatar_map(tenant=session.tenant).items()
-                                    if str(v).startswith("data:image/")}
-    except Exception:
-        workspace["userOptions"] = []
-        workspace["userAvatars"] = {}
-
-    # THE SURFACE STAMP — a MIRROR of the host's own (`_table_grid`'s hide/cohort stamps).
-    # ⚠ Deliberately NOT `hideViews`: `cohortMode` is what swaps the Views panel for the cohort
-    # list, and two switches for one behaviour would drift.
-    workspace["scopeKey"] = scope
-    if scope == "cohort":
-        workspace["cohortMode"] = True
-        # The create pane offers "this cohort table only" (default) vs "all customer tables".
-        workspace["scopeChoice"] = True
-    return {"workspace": workspace}
-
-
-# ─────────────────────────────────────────────── the TIME-SERIES channel (C-TS, 2026-08-02)
-_TS_BUCKETS = ("week", "month", "quarter", "year")
-_TS_MAX_BUCKETS = 120
-_TS_MAX_FIELDS = 12
-_TS_MAX_PIDS = 5000
-_TS_MAX_LAST_N = 120
-#: C-TSWIN (wave 14): sliding windows cost ONE aggregate query per (metric, bucket) — the
-#: price of "bucket N == the grid cell at bucket N's end". The product cap keeps a legal
-#: 120-bucket × 12-metric ask from becoming 1,440 queries in one request; typical panels
-#: (12 × 3) sit two orders of magnitude under it. Dated amendment in the split doc.
-_TS_MAX_CELLS = 720
-
-
-def _ts_start_of(bucket, d):
-    """The calendar START of the bucket holding `d` (week = Monday, the vocabulary rule)."""
-    if bucket == "week":
-        return d - dt.timedelta(days=d.weekday())
-    if bucket == "month":
-        return d.replace(day=1)
-    if bucket == "quarter":
-        return d.replace(month=((d.month - 1) // 3) * 3 + 1, day=1)
-    return d.replace(month=1, day=1)
-
-
-def _ts_next(bucket, d):
-    if bucket == "week":
-        return d + dt.timedelta(days=7)
-    if bucket == "year":
-        return d.replace(year=d.year + 1)
-    step = 1 if bucket == "month" else 3
-    m = d.month + step
-    return dt.date(d.year + (m - 1) // 12, (m - 1) % 12 + 1, 1)
-
-
-def _ts_prev(bucket, d):
-    if bucket == "week":
-        return d - dt.timedelta(days=7)
-    if bucket == "year":
-        return d.replace(year=d.year - 1)
-    step = 1 if bucket == "month" else 3
-    y, m = d.year, d.month - step
-    while m < 1:
-        m += 12
-        y -= 1
-    return dt.date(y, m, 1)
-
-
-def _ts_label(bucket, start):
-    if bucket == "week":
-        return f"Wk of {start.strftime('%b %d')}"
-    if bucket == "month":
-        return start.strftime("%b %Y")
-    if bucket == "quarter":
-        return f"Q{(start.month - 1) // 3 + 1} {start.year}"
-    return str(start.year)
-
-
-@router.post("/grid/timeseries")
-def grid_timeseries(body: dict = Body(default=None), scope: str = "customer",
-                    session: Session = Depends(module_gate(MODULE))):
-    """Pooled measure values per calendar bucket — the time-series view's data channel.
-
-    C-TSWIN (wave 14, ruling R1): AS-OF semantics. Each metric's OWN stored window is
-    re-resolved per bucket with `today := min(bucket end, real today)` — `ytd` is cumulative
-    from Jan 1, `last_90_days` trailing, `all_time` cumulative ever; bucket N equals what the
-    grid's measure column would show if today were bucket N's end. Fixed-range (`custom`)
-    windows cannot slide and are dropped per field as `window_fixed`. Rows carry
-    `window: {kind, label}` so a cumulative row cannot be misread as periodic, and there is
-    NO `total` column — sliding windows overlap, so a sum of columns would double-count.
-
-    The client sends the pids its view currently matches (the filter IS the scope); the server
-    intersects them with the session's book, so the request can only ever NARROW. Values are
-    POOLED aggregates computed by the semantic layer's own expression (the additivity law: an
-    average is computed at pool grain, never averaged over per-customer answers). A bucket
-    with no rows is 0 for a sum/count and null for anything else; a bucket that has not
-    STARTED yet is null for every kind — an unstarted period's YTD is unanswered, not 0.
-    """
-    from core import measure_resolve
-    from harness import windows as _wn
-    from routes_customers import _pool_stamp, _team_agent, allowed_pids
-
-    # Wave 16 C-TOPIC: the channel is CUSTOMER-GRAIN (measure_resolve's own grain), so the
-    # product surface is refused in words rather than answered with an id-space accident —
-    # product pids are CRC32 hashes and would mostly fall outside the customer book anyway,
-    # but "mostly" is not a wall. The client hides the mode for this topic; this is the
-    # server's half of the same refusal.
-    _sc = _scope_or_400(scope)
-    if _sc == "product" or _sc.startswith("ut_"):
-        raise err(400, "bad_timeseries",
-                  "this surface has no time-series channel — measures are customer-grain")
-
-    body = body or {}
-    bucket = body.get("bucket")
-    if bucket not in _TS_BUCKETS:
-        raise err(400, "bad_timeseries", "bucket must be one of week, month, quarter, year")
-    raw_fields = body.get("fields")
-    if not isinstance(raw_fields, list) or not raw_fields:
-        raise err(400, "bad_timeseries", "fields must be a non-empty list of field keys")
-    if len(raw_fields) > _TS_MAX_FIELDS:
-        raise err(400, "bad_timeseries", f"at most {_TS_MAX_FIELDS} fields per request")
-    raw_pids = body.get("pids")
-    if not isinstance(raw_pids, list) or not raw_pids:
-        raise err(400, "bad_timeseries", "pids must be a non-empty list")
-    if len(raw_pids) > _TS_MAX_PIDS:
-        raise err(400, "bad_timeseries", f"at most {_TS_MAX_PIDS} pids per request")
-    try:
-        wanted = {int(p) for p in raw_pids}
-    except (TypeError, ValueError):
-        raise err(400, "bad_timeseries", "pids must be integers")
-    pool = wanted & {int(p) for p in allowed_pids(session)}
-    if not pool:
-        # 403, not an empty 200: the caller asked about customers outside their book, and an
-        # all-zero series over nobody would read as "no activity", not "not yours".
-        raise err(403, "out_of_scope", "none of those customers are in your book")
-
-    span = body.get("span")
-    if not isinstance(span, dict):
-        raise err(400, "bad_timeseries", "span must be {'lastN': n} or {'from': .., 'to': ..}")
-    today = time.strftime("%Y-%m-%d")
-    t = dt.date.fromisoformat(today)
-    n = span.get("lastN")
-    starts = []
-    if n is not None:
-        if not isinstance(n, int) or isinstance(n, bool) or not (1 <= n <= _TS_MAX_LAST_N):
-            raise err(400, "bad_timeseries", f"lastN must be 1..{_TS_MAX_LAST_N}")
-        cur = _ts_start_of(bucket, t)
-        starts = [cur]
-        for _ in range(n - 1):
-            cur = _ts_prev(bucket, cur)
-            starts.append(cur)
-        starts.reverse()
-    else:
-        try:
-            d_from = dt.date.fromisoformat(str(span.get("from")))
-            d_to = dt.date.fromisoformat(str(span.get("to")))
-        except (TypeError, ValueError):
-            raise err(400, "bad_timeseries", "span.from/to must be ISO dates (YYYY-MM-DD)")
-        if d_from > d_to:
-            d_from, d_to = d_to, d_from
-        cur = _ts_start_of(bucket, d_from)
-        while cur <= d_to:
-            starts.append(cur)
-            if len(starts) > _TS_MAX_BUCKETS:
-                raise err(400, "bad_timeseries",
-                          f"that span is more than {_TS_MAX_BUCKETS} {bucket} buckets - "
-                          f"narrow it")
-            cur = _ts_next(bucket, cur)
-        if not starts:
-            raise err(400, "bad_timeseries", "the span holds no buckets")
-    ends = [_ts_next(bucket, s) - dt.timedelta(days=1) for s in starts]
-
-    rt = session.runtime
-    if not rt.available():
-        raise err(503, "store_unavailable", "the tenant store is unavailable")
-    import modules.customer_data as cl_mod
-    # Read-only route: it must not consume a one-shot label-correction ack the browser has
-    # not seen yet (the same rule event validation follows).
-    ws = cl_mod.table_workspace(session.uname, consume_corrections=False)
-    fdefs = ws.get("fields") or {}
-    keys, dropped, seen = [], [], set()
-    for k in raw_fields:
-        k = str(k or "")
-        if not k or k in seen:
-            continue
-        seen.add(k)
-        fd = fdefs.get(k)
-        if not isinstance(fd, dict) or not isinstance(fd.get("measure"), dict):
-            # Named, never silent: v1 eligibility is measure-backed fields only (C-TS).
-            dropped.append({"field": k, "reason": "not_a_measure_field"})
-            continue
-        keys.append(k)
-    # ⚡ WAVE 17 R9 (amendment 2026-08-03, GRID's cross-fence ask) — A SHEET WITH NO MEASURE
-    # FIELDS IS NO LONGER A 400. It answers with the BUCKET GRID and no rows.
-    #
-    # Why this is the honest direction and not a loosening: the bucket starts and their labels
-    # are SERVER math (`_ts_start_of` / `_ts_next` / `_ts_label`), and R9 has the client
-    # synthesizing snapshot rows for preset columns that have no window to slide. Those rows
-    # must be painted under the SAME headings as everything else, so the client needs the
-    # columns even when the server has no series to put in them. Refusing the whole request
-    # meant the panel could offer nothing at all on this tenant — the shipped contract has zero
-    # measure-backed presets (`aios_grid.py`: "this branch is currently MEMBERLESS"), which is
-    # what item 5 is actually about.
-    #
-    # Nothing is invented by this: `rows` is empty and `meta.dropped` NAMES every field and why.
-    # A 400 is still returned for a request that is malformed (bad bucket, bad span, no fields
-    # at all) — this only stops treating "I asked about columns you cannot serve" as an error.
-    mfields, slid_keys = [], []
-    for k in keys:
-        m = dict(fdefs[k]["measure"])
-        if (m.get("window") or {}).get("kind") == "custom":
-            # C-TSWIN: a fixed date range cannot slide across buckets — named, never silent,
-            # the same posture as not_a_measure_field.
-            dropped.append({"field": k, "reason": "window_fixed"})
-            continue
-        mfields.append({"key": k, "measure": m})
-        slid_keys.append(k)
-    # Same amendment as above: every metric being fixed-range is a sheet with no SERIES, not a
-    # broken request. The columns still stand, and `window_fixed` still names each refusal.
-    if len(starts) * len(mfields) > _TS_MAX_CELLS:
-        raise err(400, "bad_timeseries",
-                  "that ask is too wide - narrow the span or pick fewer metrics")
-
-    team_id, agent = _team_agent(session)
-    stamp = _pool_stamp(rt, team_id, agent)
-    problems = []
-    bucket_bounds = [(s.isoformat(), e.isoformat()) for s, e in zip(starts, ends)]
-    # No slidable metrics = nothing to resolve. Skipping the call rather than asking the
-    # resolver about an empty list keeps the memo free of a meaningless key.
-    answers = measure_resolve.series_values(
-        mfields, bucket, bucket_bounds,
-        team_id, frozenset(pool), today, stamp, rt.series_memo,
-        on_error=lambda tag, e: problems.append(str(e)[:200])) if mfields else {}
-
-    columns = []
-    for s, e in zip(starts, ends):
-        col = {"key": s.isoformat(), "label": _ts_label(bucket, s),
-               "from": s.isoformat(), "to": e.isoformat()}
-        if e > t:
-            col["partial"] = True
-        columns.append(col)
-    rows = []
-    for k in slid_keys:
-        ans = answers.get(k)
-        if ans is None:
-            dropped.append({"field": k, "reason": "unresolvable"})
-            continue
-        vals_by = ans.get("values") or {}
-        agg_kind = str(ans.get("agg") or "sum")
-        zero_fill = agg_kind in ("sum", "count")
-        vals = []
-        for s in starts:
-            if s > t:
-                # C-TSWIN: an unstarted period is unanswered for EVERY agg kind — a future
-                # month's YTD zero-filled to 0 would read as "the year reset".
-                vals.append(None)
-            else:
-                vals.append(vals_by.get(s.isoformat(), 0 if zero_fill else None))
-        wspec = (fdefs[k].get("measure") or {}).get("window")
-        wnorm = _wn.normalize(wspec) or {}
-        rows.append({"field": k, "label": str(fdefs[k].get("label") or k)[:120],
-                     "agg": agg_kind, "values": vals,
-                     "window": {"kind": str(wnorm.get("kind") or ""),
-                                "label": _wn.label(wspec)}})
-    meta = {"pool": len(pool), "today": today, "bucket": bucket}
-    if dropped:
-        meta["dropped"] = dropped
-    if problems:
-        meta["problems"] = problems[:5]
-    return {"columns": columns, "rows": rows, "meta": meta}
-
-
-#: C-CAL caps (wave 17, owner item 9 / ruling R4). A month of days, a handful of metrics.
-#: Every one of these is a 400 WITH ITS REASON, never a silent trim: a calendar that quietly
-#: answered 20 of the 31 days asked about would paint eleven blank cells that look like days
-#: with no activity.
-_CAL_MAX_GROUPS = 31
-_CAL_MAX_FIELDS = 6
-_CAL_MAX_CELLS = 186
-
-
-@router.post("/grid/calendar_metrics")
-def grid_calendar_metrics(body: dict = Body(default=None), scope: str = "customer",
-                          session: Session = Depends(module_gate(MODULE))):
-    """Per-DAY measure values with each metric's own window slid to that day (C-CAL / R4).
-
-    ⛔ WHY THIS EXISTS AT ALL. The calendar's summary cells used to aggregate the row VALUES the
-    grid already held — which for a measure column means "every member's YTD **as of today**",
-    summed and printed under a date in March. The number was arithmetically fine and semantically
-    a lie: it answered a question about today while sitting in a cell labelled with another day.
-    R4: a metric in a day cell is computed AS OF THAT DAY.
-
-    The shape differs from the time-series channel in exactly one way, and it is the reason this
-    is a separate route rather than a parameter: **every group carries its OWN pid set**. A
-    calendar day holds the records the date field placed there, so day-to-day the subject
-    changes. One `allowed_pids` for the whole request — the TS channel's shape — would compute
-    each day over everybody, which is a different question again.
-
-    Static (non-measure) fields are NOT served here. They have no window to slide, so the
-    client's own per-day aggregation over row values stays correct for them; sending them would
-    invite a second implementation of arithmetic that already works.
-    """
-    from core import measure_resolve
-    from harness import windows as _wn
-    from routes_customers import _pool_stamp, _team_agent, allowed_pids
-
-    # The same refusal the TS channel makes, for the same reason: measures are customer-grain
-    # and product pids are CRC32 hashes of SKU codes. "Mostly outside the book" is not a wall.
-    _sc_cal = _scope_or_400(scope)
-    if _sc_cal == "product" or _sc_cal.startswith("ut_"):
-        raise err(400, "bad_calendar_metrics",
-                  "the product surface has no measure channel yet — measures are customer-grain")
-
-    body = body or {}
-    raw_groups = body.get("groups")
-    if not isinstance(raw_groups, list) or not raw_groups:
-        raise err(400, "bad_calendar_metrics",
-                  "groups must be a non-empty list of {key: 'YYYY-MM-DD', pids: [...]}")
-    if len(raw_groups) > _CAL_MAX_GROUPS:
-        raise err(400, "bad_calendar_metrics",
-                  f"at most {_CAL_MAX_GROUPS} days per request (one month)")
-    raw_fields = body.get("fields")
-    if not isinstance(raw_fields, list) or not raw_fields:
-        raise err(400, "bad_calendar_metrics", "fields must be a non-empty list of field keys")
-    if len(raw_fields) > _CAL_MAX_FIELDS:
-        raise err(400, "bad_calendar_metrics", f"at most {_CAL_MAX_FIELDS} metrics per request")
-    if len(raw_groups) * len(raw_fields) > _CAL_MAX_CELLS:
-        raise err(400, "bad_calendar_metrics",
-                  "that ask is too wide - fewer days or fewer metrics")
-
-    book = {int(p) for p in allowed_pids(session)}
-    groups, seen_days = [], set()
-    for g in raw_groups:
-        if not isinstance(g, dict):
-            raise err(400, "bad_calendar_metrics", "every group must be an object")
-        day = str(g.get("key") or "")
-        try:
-            d = dt.date.fromisoformat(day)
-        except (TypeError, ValueError):
-            raise err(400, "bad_calendar_metrics",
-                      "every group key must be an ISO date (YYYY-MM-DD)")
-        if day in seen_days:
-            raise err(400, "bad_calendar_metrics", f"day {day} appears twice")
-        seen_days.add(day)
-        raw_pids = g.get("pids")
-        if not isinstance(raw_pids, list):
-            raise err(400, "bad_calendar_metrics", "every group needs a pids list")
-        try:
-            wanted = {int(p) for p in raw_pids}
-        except (TypeError, ValueError):
-            raise err(400, "bad_calendar_metrics", "pids must be integers")
-        # NARROW-ONLY, per group. The client sends what its calendar placed; the server can
-        # only ever remove from that, never add.
-        groups.append((day, d, frozenset(wanted & book)))
-    if sum(len(p) for _, _, p in groups) > _TS_MAX_PIDS:
-        raise err(400, "bad_calendar_metrics",
-                  f"at most {_TS_MAX_PIDS} customer references per request")
-
-    rt = session.runtime
-    if not rt.available():
-        raise err(503, "store_unavailable", "the tenant store is unavailable")
-    import modules.customer_data as cl_mod
-    ws = cl_mod.table_workspace(session.uname, consume_corrections=False)
-    fdefs = ws.get("fields") or {}
-    keys, dropped, seen = [], [], set()
-    for k in raw_fields:
-        k = str(k or "")
-        if not k or k in seen:
-            continue
-        seen.add(k)
-        fd = fdefs.get(k)
-        if not isinstance(fd, dict) or not isinstance(fd.get("measure"), dict):
-            # The TS channel's vocabulary, deliberately reused rather than re-coined: the client
-            # already knows how to say these three words to a reader.
-            dropped.append({"field": k, "reason": "not_a_measure_field"})
-            continue
-        if ((fd["measure"].get("window") or {}).get("kind") == "custom"):
-            dropped.append({"field": k, "reason": "window_fixed"})
-            continue
-        keys.append(k)
-    if not keys:
-        raise err(400, "bad_calendar_metrics",
-                  "none of the requested fields are measure fields with a window that can "
-                  "slide to a day")
-
-    today = time.strftime("%Y-%m-%d")
-    t = dt.date.fromisoformat(today)
-    team_id, agent = _team_agent(session)
-    stamp = _pool_stamp(rt, team_id, agent)
-    problems = []
-    values = {k: {} for k in keys}
-    for day, d, pids in groups:
-        # A day that has not happened is unanswered for EVERY aggregate kind — the unstarted
-        # bucket law at day grain. Answering 0 would say "we sold nothing", which is a claim
-        # about a day nobody has lived through yet.
-        if d > t or not pids:
-            for k in keys:
-                values[k][day] = None
-            continue
-        answers = measure_resolve.series_values(
-            [{"key": k, "measure": dict(fdefs[k]["measure"])} for k in keys],
-            "day", [(day, day)], team_id, pids, today, stamp, rt.series_memo,
-            on_error=lambda tag, e: problems.append(str(e)[:200]))
-        for k in keys:
-            ans = answers.get(k)
-            if ans is None:
-                values[k][day] = None
-                continue
-            vals_by = ans.get("values") or {}
-            zero_fill = str(ans.get("agg") or "sum") in ("sum", "count")
-            values[k][day] = vals_by.get(day, 0 if zero_fill else None)
-
-    for k in keys:
-        if all(v is None for v in values[k].values()):
-            # Every day unanswerable is a FIELD-level failure, and saying so is the difference
-            # between "no activity that month" and "this metric could not be computed".
-            dropped.append({"field": k, "reason": "unresolvable"})
-    out = {"values": values, "today": today,
-           "windows": {k: {"kind": str((_wn.normalize(
-               (fdefs[k].get("measure") or {}).get("window")) or {}).get("kind") or ""),
-               "label": _wn.label((fdefs[k].get("measure") or {}).get("window"))}
-               for k in keys}}
-    if dropped:
-        out["dropped"] = dropped
-    if problems:
-        out["problems"] = problems[:5]
-    return out
-
-
-@router.post("/grid/events")
-def grid_events_route(body: dict = Body(default=None),
-                      session: Session = Depends(require_session)):
-    """`{events: [<component event objects, verbatim>]}` → `{results, doc?, toast?}`.
-
-    Wave 21 C4: session-only dependency, per-scope gate below — the write door must admit the
-    same sessions the read door (`/workspace`) admits, or a tenant without the customer module
-    can SEE its own user tables and not write to them."""
-    from core import grid_events
-    from routes_customers import grid_assembly
-
-    events = (body or {}).get("events")
-    if events is None and isinstance(body, dict) and body.get("type"):
-        events = [body]                    # a single event object, the legacy shape
-    if not isinstance(events, list):
-        raise err(400, "bad_events", "expected {events: [...]}")
-    if len(events) > _MAX_EVENTS:
-        raise err(400, "too_many_events",
-                  f"at most {_MAX_EVENTS} events per request (the client's resend window)")
-
-    # Validated with the SAME predicate as the read route. An unrecognised scopeKey used to be
-    # passed through verbatim, and `core.grid_events` only ever compares it to 'cohort' — so a
-    # typo degraded silently to customer-scope behaviour on a WRITE. Read and write must agree on
-    # what a scope is, or the surface you read is not the surface you wrote.
-    scope = _scope_or_400((body or {}).get("scopeKey"))
-    # Wave 21 C4 — same per-scope gate as /workspace (read and write doors must agree).
-    if not (scope == "product" or scope.startswith("ut_")):
-        session.require(MODULE)
-    # This assembly validates the write; it is not a payload the browser will render. Leave
-    # one-shot field-name correction acks queued for the subsequent /workspace refresh.
-    # Wave 16 C-TOPIC: the PRODUCT topic gets the product assembly — product field contract,
-    # product pids, and (below) the product TABLE OPS, so a product event is validated against
-    # and lands in the product bucket. The measure/cohort context is honestly EMPTY there:
-    # `clean_measure_field` refuses measure creates on this surface by construction (the
-    # customer-grain descope), which is the fail-closed shape, not an accident.
-    if scope == "product":
-        from routes_products import MODULE as PRODUCT_MODULE, product_assembly
-
-        session.require(PRODUCT_MODULE)   # the product wall (dependency is session-only, C4)
-        g = product_assembly(session, consume_corrections=False)
-    elif scope.startswith("ut_"):
-        # Wave 18 C3-UT — the user-table wall (creator/admin) is inside the assembly; the
-        # measure/cohort context is honestly EMPTY (customer-grain machinery, no meaning here).
-        from routes_tables import ut_assembly
-
-        g = ut_assembly(session, scope, consume_corrections=False)
-    else:
-        g = grid_assembly(session, scope=scope, consume_corrections=False)
-    # ⚠ THE MEASURE CONTEXT IS NOT OPTIONAL (2026-07-31). Without `measure_offer`,
-    # `clean_measure_field` had an empty admission list and every measure-column create over
-    # HTTP was silently refused; without `measure_keys`, `clean_filter_tree` stripped every
-    # measure CONDITION out of a saved view. The embed always passed these; the API adapter
-    # simply had not been given them — the standalone shell could read measures it could
-    # never write.
-    ctx = _ctx(session, g["fields"], g["pids"], scope_key=scope,
-               measure_keys=frozenset(m["key"] for m in g["measures"]),
-               resolved_ids=frozenset(g["measure_sets"]),
-               cohort_ids=frozenset(c["id"] for c in g["lists"]),
-               measure_offer=tuple(g["measures"]),
-               visible_views=tuple(g["views"]))
-
-    # Per-event results so the client can tell which of a batch landed — the component's own
-    # bridge has no response channel at all, so this is strictly more than the embed gets.
-    results = []
-    try:
-        for one in events:
-            eid = str(one.get("id") or "") if isinstance(one, dict) else ""
-            rerender = grid_events.handle_one(one, ctx)
-            results.append({"id": eid, "rerender": bool(rerender)})
-    except grid_events.StoreUnavailable:
-        raise err(503, "store_unavailable",
-                  "the tenant store is unavailable — none of your changes were saved")
-
-    out = {"results": results, "rerender": any(r["rerender"] for r in results)}
-    if ctx.out.doc is not None:
-        out["doc"] = ctx.out.doc
-    if ctx.out.toast is not None:
-        out["toast"] = ctx.out.toast
-
-    # ── ⭐ owner item 2 (2026-08-03): THE NEW MEASURE COLUMN'S VALUES, ONE ROUND TRIP SOONER ──
-    #
-    # Creating a measure column cost the browser TWO sequential trips before a single number
-    # appeared: this one to persist the field, then a whole `/workspace` to compute it. The
-    # second cannot start until the first lands (the resolver reads the PERSISTED field), so the
-    # wait was structural, not slow code — the owner's "it takes some time for the data to
-    # populate". The values are computed here instead, immediately after the write, and ride
-    # this response.
-    #
-    # ⚠ IT COSTS NOTHING EXTRA TO COMPUTE. The expensive part is one DuckDB aggregate over the
-    # book, and `rt.measure_memo` is keyed on (pool stamp, scope, pool, measure, window) — so
-    # the `/workspace` re-read that still follows HITS the memo instead of doing this work. The
-    # query happens once either way; only its position moved.
-    #
-    # ⚠ NARROW ON PURPOSE. Gated to an actual measure-column write, so an overlay edit or a
-    # cohort add — the overwhelming majority of events — never pays for a second assembly.
-    #
-    # ⚠ AND IT IS A SHORTCUT, NOT A PATH. Any failure is swallowed: `WORKSPACE_STALE` still
-    # fires from `rerender`, and the re-read still delivers these values exactly as it does
-    # today. Nothing depends on this having worked.
-    if out["rerender"] and scope in ("customer", "cohort") and any(
-            isinstance(e, dict) and e.get("type") == "field_upsert"
-            and str(((e.get("field") or {}) if isinstance(e.get("field"), dict) else {})
-                    .get("key") or "").startswith("measure_")
-            for e in events):
-        try:
-            fresh = grid_assembly(session, scope=scope, consume_corrections=False)
-            out["derived"] = {str(pid): cells for pid, cells in fresh["derived"].items()}
-        except Exception:
-            pass
-    # ⚠ NOTHING IS INVALIDATED HERE, on purpose. The runtime cache holds ONLY the scope-shaped
-    # Odoo pool (see `routes_customers._pool_rows`), and no event on this route can change an
-    # Odoo column — Odoo is read-only. Everything an event DOES change (overlays, fields, views,
-    # folders, cohorts) is re-read from the store on the next request. An earlier version cleared
-    # `pool_cache` after an `overlay_patch`, which threw away an expensive Odoo pull to refresh
-    # data that was never in it.
-    return out
+"""routes_grid.py — X2's write seam over HTTP: the SECOND adapter on `core.grid_events` (EXIT-1c).
+
+`POST /api/v1/grid/events` takes the component's event objects VERBATIM — the same objects the
+Streamlit host receives through the component value slot, unchanged — and runs them through the
+same `core.grid_events.handle_events` the Streamlit adapter runs. That is the whole point of
+EXIT-1a: one implementation of every permission wall, two transports. A route that re-validated
+anything here would be a second wall to keep in step, and the two would drift on the first change.
+
+DEDUP IS PER REQUEST, and that is a deliberate limit, not an oversight. The Streamlit adapter's
+`seen_ids` lives in `st.session_state` — genuinely per user session — because the client resends
+its recent 24-event window on every emit inside one page session. A stateless API has no such
+dict, and inventing a per-user server-side one would be exactly the resident per-tenant state
+EXIT-4a exists to remove. So: ids are deduped WITHIN a request body (the resend window's whole
+purpose — a batch that repeats an id processes it once), and a genuinely replayed request is
+handled by the operations being idempotent. The one event where a replay is observable is
+`add_to_list` (it would add the same pids to the same cohort twice — a set union, so the
+membership is unchanged, but the toast count repeats). Noted rather than papered over; a
+server-side idempotency key belongs with D2's session mirror (C-2).
+
+STORE DOWN = 503. `fallback_ws` is None on this adapter, so `core.grid_events` raises
+`StoreUnavailable` rather than writing to an in-memory workspace no API request could ever read
+back. A 200 over a write that evaporated is the failure this rule exists to prevent.
+"""
+import datetime as dt
+import time
+
+from fastapi import APIRouter, Body, Depends
+
+from deps import Session, err, module_gate, perms, require_session
+
+router = APIRouter(prefix="/api/v1")
+
+MODULE = "customer_data"
+
+#: The client's own resend window (`app.py`'s `[-24:]`). A body larger than this is not a
+#: legitimate client — refuse it rather than doing 500 store writes on one request.
+_MAX_EVENTS = 24
+
+
+def _ctx(session: Session, fields, pids, **kw):
+    from core import grid_events
+    import aios_grid
+    import core.perm_scope as perm_scope
+
+    # Wave 16 C-TOPIC: the ctx is TOPIC-SHAPED. The product scope swaps all three of the
+    # things a write is validated against — the module the permission wall reads, the canonical
+    # contract the hidden-field closure runs over, and the TABLE OPS the write lands in.
+    # Getting any one of them from the other topic is the "validated against the wrong field
+    # contract" near-miss the wave-15 routes_products header warned about.
+    scope_key = str(kw.get("scope_key") or "")
+    if scope_key == "product":
+        import modules.product_data as pd
+        from routes_products import MODULE as _PMOD, pd_fields
+
+        module, canonical = _PMOD, pd_fields(consolidated=True)
+        kw.setdefault("table", pd.TABLE_OPS)
+        hidden = perm_scope.hidden_keys(session.user, module, canonical)
+    elif scope_key.startswith("ut_"):
+        # Wave 18 C3-UT: a user table has no module in the permission wall (its wall is
+        # `user_tables.may_open`, already applied by the assembly this route ran first), so
+        # the hidden-field closure is EMPTY rather than borrowed from another topic's contract.
+        import core.table_store as table_store
+
+        kw.setdefault("table",
+                      table_store.make(f"{scope_key}_table_workspace", st=session.runtime))
+        hidden = frozenset()
+    else:
+        module, canonical = MODULE, aios_grid.FIELDS
+        hidden = perm_scope.hidden_keys(session.user, module, canonical)
+    return grid_events.EventCtx(
+        uname=session.uname, allowed_pids=pids, fields=fields, admin=session.admin,
+        # C-PERM: the write wall's field half, on the EVENTS transport too. This route takes the
+        # component's event objects verbatim, so a hidden key would otherwise arrive here with
+        # nothing between it and the store.
+        hidden_keys=hidden,
+        # ⭐ WAVE 25 (R6b, closes D-16) — THE TENANT HANDLE, on EVERY scope. This is the line
+        # D-16's exit condition names, and without it the rest of the fix is inert: the handler
+        # falls back to the module-global `core.store`, which is tenant #0's repo, so a Nurilab
+        # user's documents, cohorts and — through `_tops` — their whole customer/product table
+        # workspace were written into Royal Imports' dataset. Note it is set for the CUSTOMER
+        # and PRODUCT branches too, not only `ut_`: those two never passed a scoped `table`, so
+        # they were the ones actually resolving to tenant #0 on every request.
+        st=session.runtime,
+        fallback_ws=None, seen_ids={}, **kw)
+
+
+#: The surfaces the ONE grid serves. `cohort` is the same table over hand-curated SETS rather
+#: than over the whole scoped pool — `app.py:page_cohort` calls the same `_table_grid` with
+#: `cohort_mode=True, scope_key='cohort'`. `product` (wave 16 C-TOPIC) is the SKU table:
+#: same engine, its own pool, field contract and workspace BUCKET (routes_products).
+_SCOPES = ("customer", "cohort", "product")
+
+
+def _scope_or_400(raw):
+    """⛔ REFUSE AN UNKNOWN SCOPE, never default it. A typo silently served as `customer` would
+    hand a user the whole book on a page they opened to see one cohort — the widening direction,
+    which is the one that must fail closed.
+
+    Wave 18 (C3-UT): a `ut_`-prefixed scope names a USER TABLE and passes through here —
+    existence and the per-table wall are enforced by `routes_tables.ut_assembly` (404/403),
+    which every consumer of such a scope goes through. Passing an unknown ut key therefore
+    still fails closed, just one layer down where the store can actually be consulted."""
+    scope = (raw or "customer").strip().lower()
+    if scope.startswith("ut_"):
+        return scope
+    if scope not in _SCOPES:
+        raise err(400, "bad_scope",
+                  f"scope must be one of {', '.join(_SCOPES)} — refusing to guess")
+    return scope
+
+
+@router.get("/workspace")
+def workspace(scope: str = "customer",
+              session: Session = Depends(require_session)):
+    """The durable table workspace for this session: views, fields, overlays, folders.
+
+    ⛔ WAVE 21 (C4): the wall is TOPIC-SHAPED, so the DEPENDENCY is session-only and each scope
+    asserts its own gate below. The old `module_gate("customer_data")` dependency 403'd a
+    `ut_*` workspace for any tenant whose catalogue omits the customer module (loopable/
+    nurilab/gtmlab ship modules w/o it) — and the client then fell back to the shared
+    localStorage bucket + demo data, which is exactly the "new database shows RI's customer
+    fields" defect. A user table's real wall is `user_tables.may_open`, enforced inside
+    `ut_assembly` (404/403, one layer down where the store can be consulted).
+
+    ⚠ WHY THIS EXISTS (S1↔S2, 2026-07-30 — an X2 AMENDMENT, see the split doc). X2 fixes
+    `/customers` at the exact shape `verify_fields_contract.py` referees, so the workspace cannot
+    ride along in it without forking the thing that gate keeps single-sourced. Without a
+    workspace route the standalone shell's write path would be WRITE-ONLY: events persist
+    server-side and nothing reads them back on reload, so a saved view looks lost to the user
+    even though the store has it. This route closes that read-back gap at its own URL.
+
+    `allowed_pids` is passed so a SHARED view's `memberPids` are re-scoped to THIS reader — the
+    wave-9 leak rule. Omitting it would hand a Fisch-scoped user a member list built by a
+    full-access user.
+    """
+    from core import grid_events
+    from routes_customers import grid_assembly
+
+    scope = _scope_or_400(scope)
+    # Wave 21 C4 — the per-scope gate the dependency no longer asserts: customer/cohort need
+    # the customer module; product asserts PRODUCT_MODULE in its branch; ut_* needs only a
+    # session (its wall is the table's own, inside the assembly).
+    if not (scope == "product" or scope.startswith("ut_")):
+        session.require(MODULE)
+    # ── Wave 18 C3-UT: a USER TABLE'S workspace — the third topic through the one wire. The
+    # storage key has no (bu, agent) because a user table has no Odoo scope; per-user by the
+    # table's own wall (creator or admin, `user_tables.may_open`).
+    if scope.startswith("ut_"):
+        from routes_tables import ut_assembly
+
+        storage_key = f"{session.tenant}:{scope}:{session.uname}"
+        try:
+            g = ut_assembly(session, scope, storage_key=storage_key)
+        except grid_events.StoreUnavailable:
+            raise err(503, "store_unavailable", "the tenant store is unavailable")
+        workspace = g["workspace"]
+        workspace["overlays"] = g["ws"].get("overlays") or {}
+        # The field contract rides the cheap re-read on EVERY topic — see the customer branch
+        # below for why (a user table's first cohort changes its contract too: `_cohorts(ctx)`
+        # is scope-parameterized, so `ut_` surfaces have their own sets).
+        workspace["fields"] = g["fields"]
+        workspace["measures"] = g["measures"]
+        workspace["measureSets"] = g["measure_sets"]
+        # ⚠ `g["derived"]`, NOT `{}` (2026-08-04). R9 gave every topic its own cohort sets, and
+        # `ut_assembly` has been building this topic's cohort CELLS since — but this route threw
+        # them away, so the Locked-views column arrived on the cheap re-read with permanently
+        # empty values. A column that exists and can never have one is worse than an absent
+        # column: it reads as "this record is in no locked view", which is a claim.
+        workspace["derived"] = {str(pid): cells for pid, cells in (g["derived"] or {}).items()}
+        workspace["viewer"] = {"name": session.uname, "isAdmin": bool(session.admin)}
+        try:
+            from core import users as _users
+            workspace["userOptions"] = _users.assignable_people(tenant=session.tenant)
+            workspace["userAvatars"] = {k: v for k, v in
+                                        _users.avatar_map(tenant=session.tenant).items()
+                                        if str(v).startswith("data:image/")}
+        except Exception:
+            workspace["userOptions"] = []
+            workspace["userAvatars"] = {}
+        workspace["scopeKey"] = scope
+        return {"workspace": workspace}
+
+    # ── Wave 16 C-TOPIC: the PRODUCT surface has its own assembly (own pool, own field
+    # contract, own workspace BUCKET) and the contract's own storage key. It branches before
+    # the customer derivation because the customer storage key embeds (bu, agent) while the
+    # product one is deliberately `all:all` — one product workspace per user (the wave doc's
+    # C-TOPIC line), since BU narrows the product VALUES, not which workspace you own.
+    if scope == "product":
+        from routes_products import MODULE as PRODUCT_MODULE, product_assembly
+
+        # ⛔ THE GATE CHANGES WITH THE SCOPE (wave 21 C4: the dependency is session-only now,
+        # so this line IS the product wall — not a second one on top of customer_data).
+        session.require(PRODUCT_MODULE)
+        storage_key = f"{session.tenant}:product-list:{session.uname}:all:all"
+        try:
+            g = product_assembly(session, scope=scope, storage_key=storage_key)
+        except grid_events.StoreUnavailable:
+            raise err(503, "store_unavailable", "the tenant store is unavailable")
+        workspace = g["workspace"]
+        workspace["overlays"] = g["ws"].get("overlays") or {}
+        # R9 made cohorts per-topic, so the PRODUCT surface has its own sets and its own
+        # first-cohort contract change. Same reason as the customer branch below.
+        workspace["fields"] = g["fields"]
+        # The measure channel is EMPTY on this topic (customer-grain descope) — stated
+        # explicitly so the client's pickers grey rather than guess.
+        workspace["measures"] = g["measures"]
+        workspace["measureSets"] = g["measure_sets"]
+        # `g["derived"]` — the same correction as the user-table branch above, for the same
+        # reason: `product_assembly` builds this topic's cohort cells and this route discarded
+        # them. The measure half stays empty on this topic by descope, which is a different
+        # statement and one the offer already makes.
+        workspace["derived"] = {str(pid): cells for pid, cells in (g["derived"] or {}).items()}
+        workspace["viewer"] = {"name": session.uname, "isAdmin": bool(session.admin)}
+        try:
+            from core import users as _users
+            workspace["userOptions"] = _users.assignable_people(tenant=session.tenant)
+            workspace["userAvatars"] = {k: v for k, v in
+                                        _users.avatar_map(tenant=session.tenant).items()
+                                        if str(v).startswith("data:image/")}
+        except Exception:
+            workspace["userOptions"] = []
+            workspace["userAvatars"] = {}
+        workspace["scopeKey"] = scope
+        return {"workspace": workspace}
+
+    # The storage key mirrors the host's own convention byte-for-byte (app.py's `_table_grid`
+    # call sites) with the session's TENANT in the host's hardcoded slot, so localStorage state
+    # carries across embed ⇄ standalone on the same browser.
+    # Wave 15 R1 — the SAME derivation the pool uses (`routes_customers._team_agent`), so the
+    # storage key cannot drift from the scope it names. Value-identical for every migrated
+    # record (verify_perm_scope section D proves the derivation reproduces the legacy scope
+    # exactly), so nobody's saved localStorage state moves when the migration runs.
+    import core.perm_scope as perm_scope
+    team_id, agent = perm_scope.derive_pool_scope(session.user, MODULE)
+    bu = team_id if team_id is not None else "all"
+    if scope == "cohort":
+        storage_key = f"{session.tenant}:cohort:{session.uname}:{bu}"
+    else:
+        storage_key = f"{session.tenant}:customer-list:{session.uname}:{bu}:{agent or 'all'}"
+
+    # ⛔ THE WIRE SHAPE IS THE SHARED PROJECTION (`aios_grid.workspace_wire`), not the store
+    # shape. The first version returned the store dict with no `storageKey` — and the client
+    # validator requires one, so the standalone shell DISCARDED the whole workspace: saved views
+    # never rendered, `cohortMode` never arrived, and the Cohort route silently drew the Customer
+    # surface. One projection for both servers is the fix that cannot drift.
+    try:
+        g = grid_assembly(session, scope=scope, storage_key=storage_key)
+    except grid_events.StoreUnavailable:
+        raise err(503, "store_unavailable", "the tenant store is unavailable")
+    workspace = g["workspace"]
+    # ADDITIVE to the wire: the caller's own overlay cells. The grid reads overlays from the
+    # /customers rows, but this route is the cheap read-back a write can be verified against
+    # (verify_api's overlay probe) without paying the pool call. Per-user by construction —
+    # `table_workspace` is this session's workspace.
+    workspace["overlays"] = g["ws"].get("overlays") or {}
+    # ⭐ THE FIELD CONTRACT, 2026-08-04 — and it is NOT decoration.
+    #
+    # `fields_from_workspace(ws, cohorts=bool(cohort_lists))` appends the derived "Locked
+    # views" column ONLY when the caller owns at least one cohort. So a user's FIRST cohort
+    # CHANGES THE FIELD CONTRACT — and the rows call that used to be the only carrier of
+    # `fields` is deliberately never re-fetched on a write (it is a 15-minute-cached Odoo
+    # pull; this route is the cheap re-read). The client therefore had no way to learn about
+    # that column short of a remount, which is the second half of the owner's "it only shows
+    # up when I switch modules and come back".
+    #
+    # ⚠ `g["fields"]` is the SAME list `_payload` serves on `/customers` — same assembly,
+    # same permission wall (`hidden_keys` already applied) — so the two wires cannot disagree
+    # about what a column is. Taking it from anywhere else would fork the contract that
+    # verify_fields_contract.py exists to keep single-sourced.
+    workspace["fields"] = g["fields"]
+    # ── the STANDALONE measure channel (owner item 1, 2026-07-31) ────────────────────────────
+    # The embed receives these as top-level render args; standalone lifts them off THIS route
+    # (useCustomerData merges them into the payload slots the grid already reads). They ride
+    # the workspace rather than /customers because a durable write re-reads exactly this route
+    # (WORKSPACE_STALE), so a new measure column populates without refetching the heavy pool.
+    workspace["measures"] = g["measures"]
+    workspace["measureSets"] = g["measure_sets"]
+    # Derived cells (cohort column + measure columns), keyed by pid. JSON object keys are
+    # strings; the client indexes with String(pid).
+    workspace["derived"] = {str(pid): cells for pid, cells in g["derived"].items()}
+    # Who is looking (permissions verdicts) + the assignee choices for `user`-typed columns —
+    # the two other host-only render args the shell was missing (fail-closed without them:
+    # restricted fields uneditable, assignee picker empty).
+    workspace["viewer"] = {"name": session.uname, "isAdmin": bool(session.admin)}
+    try:
+        from core import users as _users
+        workspace["userOptions"] = _users.assignable_people(tenant=session.tenant)
+        # Wave 14 C-AVATAR — the options vocabulary's companion: display name -> data URL.
+        # Absent entries fall back to the client's initials disc; a non-data: value is
+        # dropped (defence in depth beside the write-side wall in routes_auth).
+        workspace["userAvatars"] = {k: v for k, v in
+                                    _users.avatar_map(tenant=session.tenant).items()
+                                    if str(v).startswith("data:image/")}
+    except Exception:
+        workspace["userOptions"] = []
+        workspace["userAvatars"] = {}
+
+    # THE SURFACE STAMP — a MIRROR of the host's own (`_table_grid`'s hide/cohort stamps).
+    # ⚠ Deliberately NOT `hideViews`: `cohortMode` is what swaps the Views panel for the cohort
+    # list, and two switches for one behaviour would drift.
+    workspace["scopeKey"] = scope
+    if scope == "cohort":
+        workspace["cohortMode"] = True
+        # The create pane offers "this cohort table only" (default) vs "all customer tables".
+        workspace["scopeChoice"] = True
+    return {"workspace": workspace}
+
+
+# ─────────────────────────────────────────────── the TIME-SERIES channel (C-TS, 2026-08-02)
+_TS_BUCKETS = ("week", "month", "quarter", "year")
+_TS_MAX_BUCKETS = 120
+_TS_MAX_FIELDS = 12
+_TS_MAX_PIDS = 5000
+_TS_MAX_LAST_N = 120
+#: C-TSWIN (wave 14): sliding windows cost ONE aggregate query per (metric, bucket) — the
+#: price of "bucket N == the grid cell at bucket N's end". The product cap keeps a legal
+#: 120-bucket × 12-metric ask from becoming 1,440 queries in one request; typical panels
+#: (12 × 3) sit two orders of magnitude under it. Dated amendment in the split doc.
+_TS_MAX_CELLS = 720
+
+
+def _ts_start_of(bucket, d):
+    """The calendar START of the bucket holding `d` (week = Monday, the vocabulary rule)."""
+    if bucket == "week":
+        return d - dt.timedelta(days=d.weekday())
+    if bucket == "month":
+        return d.replace(day=1)
+    if bucket == "quarter":
+        return d.replace(month=((d.month - 1) // 3) * 3 + 1, day=1)
+    return d.replace(month=1, day=1)
+
+
+def _ts_next(bucket, d):
+    if bucket == "week":
+        return d + dt.timedelta(days=7)
+    if bucket == "year":
+        return d.replace(year=d.year + 1)
+    step = 1 if bucket == "month" else 3
+    m = d.month + step
+    return dt.date(d.year + (m - 1) // 12, (m - 1) % 12 + 1, 1)
+
+
+def _ts_prev(bucket, d):
+    if bucket == "week":
+        return d - dt.timedelta(days=7)
+    if bucket == "year":
+        return d.replace(year=d.year - 1)
+    step = 1 if bucket == "month" else 3
+    y, m = d.year, d.month - step
+    while m < 1:
+        m += 12
+        y -= 1
+    return dt.date(y, m, 1)
+
+
+def _ts_label(bucket, start):
+    if bucket == "week":
+        return f"Wk of {start.strftime('%b %d')}"
+    if bucket == "month":
+        return start.strftime("%b %Y")
+    if bucket == "quarter":
+        return f"Q{(start.month - 1) // 3 + 1} {start.year}"
+    return str(start.year)
+
+
+@router.post("/grid/timeseries")
+def grid_timeseries(body: dict = Body(default=None), scope: str = "customer",
+                    session: Session = Depends(module_gate(MODULE))):
+    """Pooled measure values per calendar bucket — the time-series view's data channel.
+
+    C-TSWIN (wave 14, ruling R1): AS-OF semantics. Each metric's OWN stored window is
+    re-resolved per bucket with `today := min(bucket end, real today)` — `ytd` is cumulative
+    from Jan 1, `last_90_days` trailing, `all_time` cumulative ever; bucket N equals what the
+    grid's measure column would show if today were bucket N's end. Fixed-range (`custom`)
+    windows cannot slide and are dropped per field as `window_fixed`. Rows carry
+    `window: {kind, label}` so a cumulative row cannot be misread as periodic, and there is
+    NO `total` column — sliding windows overlap, so a sum of columns would double-count.
+
+    The client sends the pids its view currently matches (the filter IS the scope); the server
+    intersects them with the session's book, so the request can only ever NARROW. Values are
+    POOLED aggregates computed by the semantic layer's own expression (the additivity law: an
+    average is computed at pool grain, never averaged over per-customer answers). A bucket
+    with no rows is 0 for a sum/count and null for anything else; a bucket that has not
+    STARTED yet is null for every kind — an unstarted period's YTD is unanswered, not 0.
+    """
+    from core import measure_resolve
+    from harness import windows as _wn
+    from routes_customers import _pool_stamp, _team_agent, allowed_pids
+
+    # Wave 16 C-TOPIC: the channel is CUSTOMER-GRAIN (measure_resolve's own grain), so the
+    # product surface is refused in words rather than answered with an id-space accident —
+    # product pids are CRC32 hashes and would mostly fall outside the customer book anyway,
+    # but "mostly" is not a wall. The client hides the mode for this topic; this is the
+    # server's half of the same refusal.
+    _sc = _scope_or_400(scope)
+    if _sc == "product" or _sc.startswith("ut_"):
+        raise err(400, "bad_timeseries",
+                  "this surface has no time-series channel — measures are customer-grain")
+
+    body = body or {}
+    bucket = body.get("bucket")
+    if bucket not in _TS_BUCKETS:
+        raise err(400, "bad_timeseries", "bucket must be one of week, month, quarter, year")
+    raw_fields = body.get("fields")
+    if not isinstance(raw_fields, list) or not raw_fields:
+        raise err(400, "bad_timeseries", "fields must be a non-empty list of field keys")
+    if len(raw_fields) > _TS_MAX_FIELDS:
+        raise err(400, "bad_timeseries", f"at most {_TS_MAX_FIELDS} fields per request")
+    raw_pids = body.get("pids")
+    if not isinstance(raw_pids, list) or not raw_pids:
+        raise err(400, "bad_timeseries", "pids must be a non-empty list")
+    if len(raw_pids) > _TS_MAX_PIDS:
+        raise err(400, "bad_timeseries", f"at most {_TS_MAX_PIDS} pids per request")
+    try:
+        wanted = {int(p) for p in raw_pids}
+    except (TypeError, ValueError):
+        raise err(400, "bad_timeseries", "pids must be integers")
+    pool = wanted & {int(p) for p in allowed_pids(session)}
+    if not pool:
+        # 403, not an empty 200: the caller asked about customers outside their book, and an
+        # all-zero series over nobody would read as "no activity", not "not yours".
+        raise err(403, "out_of_scope", "none of those customers are in your book")
+
+    span = body.get("span")
+    if not isinstance(span, dict):
+        raise err(400, "bad_timeseries", "span must be {'lastN': n} or {'from': .., 'to': ..}")
+    today = time.strftime("%Y-%m-%d")
+    t = dt.date.fromisoformat(today)
+    n = span.get("lastN")
+    starts = []
+    if n is not None:
+        if not isinstance(n, int) or isinstance(n, bool) or not (1 <= n <= _TS_MAX_LAST_N):
+            raise err(400, "bad_timeseries", f"lastN must be 1..{_TS_MAX_LAST_N}")
+        cur = _ts_start_of(bucket, t)
+        starts = [cur]
+        for _ in range(n - 1):
+            cur = _ts_prev(bucket, cur)
+            starts.append(cur)
+        starts.reverse()
+    else:
+        try:
+            d_from = dt.date.fromisoformat(str(span.get("from")))
+            d_to = dt.date.fromisoformat(str(span.get("to")))
+        except (TypeError, ValueError):
+            raise err(400, "bad_timeseries", "span.from/to must be ISO dates (YYYY-MM-DD)")
+        if d_from > d_to:
+            d_from, d_to = d_to, d_from
+        cur = _ts_start_of(bucket, d_from)
+        while cur <= d_to:
+            starts.append(cur)
+            if len(starts) > _TS_MAX_BUCKETS:
+                raise err(400, "bad_timeseries",
+                          f"that span is more than {_TS_MAX_BUCKETS} {bucket} buckets - "
+                          f"narrow it")
+            cur = _ts_next(bucket, cur)
+        if not starts:
+            raise err(400, "bad_timeseries", "the span holds no buckets")
+    ends = [_ts_next(bucket, s) - dt.timedelta(days=1) for s in starts]
+
+    rt = session.runtime
+    if not rt.available():
+        raise err(503, "store_unavailable", "the tenant store is unavailable")
+    import modules.customer_data as cl_mod
+    # Read-only route: it must not consume a one-shot label-correction ack the browser has
+    # not seen yet (the same rule event validation follows).
+    ws = cl_mod.table_workspace(session.uname, consume_corrections=False)
+    fdefs = ws.get("fields") or {}
+    keys, dropped, seen = [], [], set()
+    for k in raw_fields:
+        k = str(k or "")
+        if not k or k in seen:
+            continue
+        seen.add(k)
+        fd = fdefs.get(k)
+        if not isinstance(fd, dict) or not isinstance(fd.get("measure"), dict):
+            # Named, never silent: v1 eligibility is measure-backed fields only (C-TS).
+            dropped.append({"field": k, "reason": "not_a_measure_field"})
+            continue
+        keys.append(k)
+    # ⚡ WAVE 17 R9 (amendment 2026-08-03, GRID's cross-fence ask) — A SHEET WITH NO MEASURE
+    # FIELDS IS NO LONGER A 400. It answers with the BUCKET GRID and no rows.
+    #
+    # Why this is the honest direction and not a loosening: the bucket starts and their labels
+    # are SERVER math (`_ts_start_of` / `_ts_next` / `_ts_label`), and R9 has the client
+    # synthesizing snapshot rows for preset columns that have no window to slide. Those rows
+    # must be painted under the SAME headings as everything else, so the client needs the
+    # columns even when the server has no series to put in them. Refusing the whole request
+    # meant the panel could offer nothing at all on this tenant — the shipped contract has zero
+    # measure-backed presets (`aios_grid.py`: "this branch is currently MEMBERLESS"), which is
+    # what item 5 is actually about.
+    #
+    # Nothing is invented by this: `rows` is empty and `meta.dropped` NAMES every field and why.
+    # A 400 is still returned for a request that is malformed (bad bucket, bad span, no fields
+    # at all) — this only stops treating "I asked about columns you cannot serve" as an error.
+    mfields, slid_keys = [], []
+    for k in keys:
+        m = dict(fdefs[k]["measure"])
+        if (m.get("window") or {}).get("kind") == "custom":
+            # C-TSWIN: a fixed date range cannot slide across buckets — named, never silent,
+            # the same posture as not_a_measure_field.
+            dropped.append({"field": k, "reason": "window_fixed"})
+            continue
+        mfields.append({"key": k, "measure": m})
+        slid_keys.append(k)
+    # Same amendment as above: every metric being fixed-range is a sheet with no SERIES, not a
+    # broken request. The columns still stand, and `window_fixed` still names each refusal.
+    if len(starts) * len(mfields) > _TS_MAX_CELLS:
+        raise err(400, "bad_timeseries",
+                  "that ask is too wide - narrow the span or pick fewer metrics")
+
+    team_id, agent = _team_agent(session)
+    stamp = _pool_stamp(rt, team_id, agent)
+    problems = []
+    bucket_bounds = [(s.isoformat(), e.isoformat()) for s, e in zip(starts, ends)]
+    # No slidable metrics = nothing to resolve. Skipping the call rather than asking the
+    # resolver about an empty list keeps the memo free of a meaningless key.
+    answers = measure_resolve.series_values(
+        mfields, bucket, bucket_bounds,
+        team_id, frozenset(pool), today, stamp, rt.series_memo,
+        on_error=lambda tag, e: problems.append(str(e)[:200])) if mfields else {}
+
+    columns = []
+    for s, e in zip(starts, ends):
+        col = {"key": s.isoformat(), "label": _ts_label(bucket, s),
+               "from": s.isoformat(), "to": e.isoformat()}
+        if e > t:
+            col["partial"] = True
+        columns.append(col)
+    rows = []
+    for k in slid_keys:
+        ans = answers.get(k)
+        if ans is None:
+            dropped.append({"field": k, "reason": "unresolvable"})
+            continue
+        vals_by = ans.get("values") or {}
+        agg_kind = str(ans.get("agg") or "sum")
+        zero_fill = agg_kind in ("sum", "count")
+        vals = []
+        for s in starts:
+            if s > t:
+                # C-TSWIN: an unstarted period is unanswered for EVERY agg kind — a future
+                # month's YTD zero-filled to 0 would read as "the year reset".
+                vals.append(None)
+            else:
+                vals.append(vals_by.get(s.isoformat(), 0 if zero_fill else None))
+        wspec = (fdefs[k].get("measure") or {}).get("window")
+        wnorm = _wn.normalize(wspec) or {}
+        rows.append({"field": k, "label": str(fdefs[k].get("label") or k)[:120],
+                     "agg": agg_kind, "values": vals,
+                     "window": {"kind": str(wnorm.get("kind") or ""),
+                                "label": _wn.label(wspec)}})
+    meta = {"pool": len(pool), "today": today, "bucket": bucket}
+    if dropped:
+        meta["dropped"] = dropped
+    if problems:
+        meta["problems"] = problems[:5]
+    return {"columns": columns, "rows": rows, "meta": meta}
+
+
+#: C-CAL caps (wave 17, owner item 9 / ruling R4). A month of days, a handful of metrics.
+#: Every one of these is a 400 WITH ITS REASON, never a silent trim: a calendar that quietly
+#: answered 20 of the 31 days asked about would paint eleven blank cells that look like days
+#: with no activity.
+_CAL_MAX_GROUPS = 31
+_CAL_MAX_FIELDS = 6
+_CAL_MAX_CELLS = 186
+
+
+@router.post("/grid/calendar_metrics")
+def grid_calendar_metrics(body: dict = Body(default=None), scope: str = "customer",
+                          session: Session = Depends(module_gate(MODULE))):
+    """Per-DAY measure values with each metric's own window slid to that day (C-CAL / R4).
+
+    ⛔ WHY THIS EXISTS AT ALL. The calendar's summary cells used to aggregate the row VALUES the
+    grid already held — which for a measure column means "every member's YTD **as of today**",
+    summed and printed under a date in March. The number was arithmetically fine and semantically
+    a lie: it answered a question about today while sitting in a cell labelled with another day.
+    R4: a metric in a day cell is computed AS OF THAT DAY.
+
+    The shape differs from the time-series channel in exactly one way, and it is the reason this
+    is a separate route rather than a parameter: **every group carries its OWN pid set**. A
+    calendar day holds the records the date field placed there, so day-to-day the subject
+    changes. One `allowed_pids` for the whole request — the TS channel's shape — would compute
+    each day over everybody, which is a different question again.
+
+    Static (non-measure) fields are NOT served here. They have no window to slide, so the
+    client's own per-day aggregation over row values stays correct for them; sending them would
+    invite a second implementation of arithmetic that already works.
+    """
+    from core import measure_resolve
+    from harness import windows as _wn
+    from routes_customers import _pool_stamp, _team_agent, allowed_pids
+
+    # The same refusal the TS channel makes, for the same reason: measures are customer-grain
+    # and product pids are CRC32 hashes of SKU codes. "Mostly outside the book" is not a wall.
+    _sc_cal = _scope_or_400(scope)
+    if _sc_cal == "product" or _sc_cal.startswith("ut_"):
+        raise err(400, "bad_calendar_metrics",
+                  "the product surface has no measure channel yet — measures are customer-grain")
+
+    body = body or {}
+    raw_groups = body.get("groups")
+    if not isinstance(raw_groups, list) or not raw_groups:
+        raise err(400, "bad_calendar_metrics",
+                  "groups must be a non-empty list of {key: 'YYYY-MM-DD', pids: [...]}")
+    if len(raw_groups) > _CAL_MAX_GROUPS:
+        raise err(400, "bad_calendar_metrics",
+                  f"at most {_CAL_MAX_GROUPS} days per request (one month)")
+    raw_fields = body.get("fields")
+    if not isinstance(raw_fields, list) or not raw_fields:
+        raise err(400, "bad_calendar_metrics", "fields must be a non-empty list of field keys")
+    if len(raw_fields) > _CAL_MAX_FIELDS:
+        raise err(400, "bad_calendar_metrics", f"at most {_CAL_MAX_FIELDS} metrics per request")
+    if len(raw_groups) * len(raw_fields) > _CAL_MAX_CELLS:
+        raise err(400, "bad_calendar_metrics",
+                  "that ask is too wide - fewer days or fewer metrics")
+
+    book = {int(p) for p in allowed_pids(session)}
+    groups, seen_days = [], set()
+    for g in raw_groups:
+        if not isinstance(g, dict):
+            raise err(400, "bad_calendar_metrics", "every group must be an object")
+        day = str(g.get("key") or "")
+        try:
+            d = dt.date.fromisoformat(day)
+        except (TypeError, ValueError):
+            raise err(400, "bad_calendar_metrics",
+                      "every group key must be an ISO date (YYYY-MM-DD)")
+        if day in seen_days:
+            raise err(400, "bad_calendar_metrics", f"day {day} appears twice")
+        seen_days.add(day)
+        raw_pids = g.get("pids")
+        if not isinstance(raw_pids, list):
+            raise err(400, "bad_calendar_metrics", "every group needs a pids list")
+        try:
+            wanted = {int(p) for p in raw_pids}
+        except (TypeError, ValueError):
+            raise err(400, "bad_calendar_metrics", "pids must be integers")
+        # NARROW-ONLY, per group. The client sends what its calendar placed; the server can
+        # only ever remove from that, never add.
+        groups.append((day, d, frozenset(wanted & book)))
+    if sum(len(p) for _, _, p in groups) > _TS_MAX_PIDS:
+        raise err(400, "bad_calendar_metrics",
+                  f"at most {_TS_MAX_PIDS} customer references per request")
+
+    rt = session.runtime
+    if not rt.available():
+        raise err(503, "store_unavailable", "the tenant store is unavailable")
+    import modules.customer_data as cl_mod
+    ws = cl_mod.table_workspace(session.uname, consume_corrections=False)
+    fdefs = ws.get("fields") or {}
+    keys, dropped, seen = [], [], set()
+    for k in raw_fields:
+        k = str(k or "")
+        if not k or k in seen:
+            continue
+        seen.add(k)
+        fd = fdefs.get(k)
+        if not isinstance(fd, dict) or not isinstance(fd.get("measure"), dict):
+            # The TS channel's vocabulary, deliberately reused rather than re-coined: the client
+            # already knows how to say these three words to a reader.
+            dropped.append({"field": k, "reason": "not_a_measure_field"})
+            continue
+        if ((fd["measure"].get("window") or {}).get("kind") == "custom"):
+            dropped.append({"field": k, "reason": "window_fixed"})
+            continue
+        keys.append(k)
+    if not keys:
+        raise err(400, "bad_calendar_metrics",
+                  "none of the requested fields are measure fields with a window that can "
+                  "slide to a day")
+
+    today = time.strftime("%Y-%m-%d")
+    t = dt.date.fromisoformat(today)
+    team_id, agent = _team_agent(session)
+    stamp = _pool_stamp(rt, team_id, agent)
+    problems = []
+    values = {k: {} for k in keys}
+    for day, d, pids in groups:
+        # A day that has not happened is unanswered for EVERY aggregate kind — the unstarted
+        # bucket law at day grain. Answering 0 would say "we sold nothing", which is a claim
+        # about a day nobody has lived through yet.
+        if d > t or not pids:
+            for k in keys:
+                values[k][day] = None
+            continue
+        answers = measure_resolve.series_values(
+            [{"key": k, "measure": dict(fdefs[k]["measure"])} for k in keys],
+            "day", [(day, day)], team_id, pids, today, stamp, rt.series_memo,
+            on_error=lambda tag, e: problems.append(str(e)[:200]))
+        for k in keys:
+            ans = answers.get(k)
+            if ans is None:
+                values[k][day] = None
+                continue
+            vals_by = ans.get("values") or {}
+            zero_fill = str(ans.get("agg") or "sum") in ("sum", "count")
+            values[k][day] = vals_by.get(day, 0 if zero_fill else None)
+
+    for k in keys:
+        if all(v is None for v in values[k].values()):
+            # Every day unanswerable is a FIELD-level failure, and saying so is the difference
+            # between "no activity that month" and "this metric could not be computed".
+            dropped.append({"field": k, "reason": "unresolvable"})
+    out = {"values": values, "today": today,
+           "windows": {k: {"kind": str((_wn.normalize(
+               (fdefs[k].get("measure") or {}).get("window")) or {}).get("kind") or ""),
+               "label": _wn.label((fdefs[k].get("measure") or {}).get("window"))}
+               for k in keys}}
+    if dropped:
+        out["dropped"] = dropped
+    if problems:
+        out["problems"] = problems[:5]
+    return out
+
+
+@router.post("/grid/events")
+def grid_events_route(body: dict = Body(default=None),
+                      session: Session = Depends(require_session)):
+    """`{events: [<component event objects, verbatim>]}` → `{results, doc?, toast?}`.
+
+    Wave 21 C4: session-only dependency, per-scope gate below — the write door must admit the
+    same sessions the read door (`/workspace`) admits, or a tenant without the customer module
+    can SEE its own user tables and not write to them."""
+    from core import grid_events
+    from routes_customers import grid_assembly
+
+    events = (body or {}).get("events")
+    if events is None and isinstance(body, dict) and body.get("type"):
+        events = [body]                    # a single event object, the legacy shape
+    if not isinstance(events, list):
+        raise err(400, "bad_events", "expected {events: [...]}")
+    if len(events) > _MAX_EVENTS:
+        raise err(400, "too_many_events",
+                  f"at most {_MAX_EVENTS} events per request (the client's resend window)")
+
+    # Validated with the SAME predicate as the read route. An unrecognised scopeKey used to be
+    # passed through verbatim, and `core.grid_events` only ever compares it to 'cohort' — so a
+    # typo degraded silently to customer-scope behaviour on a WRITE. Read and write must agree on
+    # what a scope is, or the surface you read is not the surface you wrote.
+    scope = _scope_or_400((body or {}).get("scopeKey"))
+    # Wave 21 C4 — same per-scope gate as /workspace (read and write doors must agree).
+    if not (scope == "product" or scope.startswith("ut_")):
+        session.require(MODULE)
+    # This assembly validates the write; it is not a payload the browser will render. Leave
+    # one-shot field-name correction acks queued for the subsequent /workspace refresh.
+    # Wave 16 C-TOPIC: the PRODUCT topic gets the product assembly — product field contract,
+    # product pids, and (below) the product TABLE OPS, so a product event is validated against
+    # and lands in the product bucket. The measure/cohort context is honestly EMPTY there:
+    # `clean_measure_field` refuses measure creates on this surface by construction (the
+    # customer-grain descope), which is the fail-closed shape, not an accident.
+    if scope == "product":
+        from routes_products import MODULE as PRODUCT_MODULE, product_assembly
+
+        session.require(PRODUCT_MODULE)   # the product wall (dependency is session-only, C4)
+        g = product_assembly(session, consume_corrections=False)
+    elif scope.startswith("ut_"):
+        # Wave 18 C3-UT — the user-table wall (creator/admin) is inside the assembly; the
+        # measure/cohort context is honestly EMPTY (customer-grain machinery, no meaning here).
+        from routes_tables import ut_assembly
+
+        g = ut_assembly(session, scope, consume_corrections=False)
+    else:
+        g = grid_assembly(session, scope=scope, consume_corrections=False)
+    # ⚠ THE MEASURE CONTEXT IS NOT OPTIONAL (2026-07-31). Without `measure_offer`,
+    # `clean_measure_field` had an empty admission list and every measure-column create over
+    # HTTP was silently refused; without `measure_keys`, `clean_filter_tree` stripped every
+    # measure CONDITION out of a saved view. The embed always passed these; the API adapter
+    # simply had not been given them — the standalone shell could read measures it could
+    # never write.
+    ctx = _ctx(session, g["fields"], g["pids"], scope_key=scope,
+               measure_keys=frozenset(m["key"] for m in g["measures"]),
+               resolved_ids=frozenset(g["measure_sets"]),
+               cohort_ids=frozenset(c["id"] for c in g["lists"]),
+               measure_offer=tuple(g["measures"]),
+               visible_views=tuple(g["views"]))
+
+    # Per-event results so the client can tell which of a batch landed — the component's own
+    # bridge has no response channel at all, so this is strictly more than the embed gets.
+    results = []
+    try:
+        for one in events:
+            eid = str(one.get("id") or "") if isinstance(one, dict) else ""
+            rerender = grid_events.handle_one(one, ctx)
+            results.append({"id": eid, "rerender": bool(rerender)})
+    except grid_events.StoreUnavailable:
+        raise err(503, "store_unavailable",
+                  "the tenant store is unavailable — none of your changes were saved")
+
+    out = {"results": results, "rerender": any(r["rerender"] for r in results)}
+    if ctx.out.doc is not None:
+        out["doc"] = ctx.out.doc
+    if ctx.out.toast is not None:
+        out["toast"] = ctx.out.toast
+
+    # ── ⭐ owner item 2 (2026-08-03): THE NEW MEASURE COLUMN'S VALUES, ONE ROUND TRIP SOONER ──
+    #
+    # Creating a measure column cost the browser TWO sequential trips before a single number
+    # appeared: this one to persist the field, then a whole `/workspace` to compute it. The
+    # second cannot start until the first lands (the resolver reads the PERSISTED field), so the
+    # wait was structural, not slow code — the owner's "it takes some time for the data to
+    # populate". The values are computed here instead, immediately after the write, and ride
+    # this response.
+    #
+    # ⚠ IT COSTS NOTHING EXTRA TO COMPUTE. The expensive part is one DuckDB aggregate over the
+    # book, and `rt.measure_memo` is keyed on (pool stamp, scope, pool, measure, window) — so
+    # the `/workspace` re-read that still follows HITS the memo instead of doing this work. The
+    # query happens once either way; only its position moved.
+    #
+    # ⚠ NARROW ON PURPOSE. Gated to an actual measure-column write, so an overlay edit or a
+    # cohort add — the overwhelming majority of events — never pays for a second assembly.
+    #
+    # ⚠ AND IT IS A SHORTCUT, NOT A PATH. Any failure is swallowed: `WORKSPACE_STALE` still
+    # fires from `rerender`, and the re-read still delivers these values exactly as it does
+    # today. Nothing depends on this having worked.
+    if out["rerender"] and scope in ("customer", "cohort") and any(
+            isinstance(e, dict) and e.get("type") == "field_upsert"
+            and str(((e.get("field") or {}) if isinstance(e.get("field"), dict) else {})
+                    .get("key") or "").startswith("measure_")
+            for e in events):
+        try:
+            fresh = grid_assembly(session, scope=scope, consume_corrections=False)
+            out["derived"] = {str(pid): cells for pid, cells in fresh["derived"].items()}
+        except Exception:
+            pass
+    # ⚠ NOTHING IS INVALIDATED HERE, on purpose. The runtime cache holds ONLY the scope-shaped
+    # Odoo pool (see `routes_customers._pool_rows`), and no event on this route can change an
+    # Odoo column — Odoo is read-only. Everything an event DOES change (overlays, fields, views,
+    # folders, cohorts) is re-read from the store on the next request. An earlier version cleared
+    # `pool_cache` after an `overlay_patch`, which threw away an expensive Odoo pull to refresh
+    # data that was never in it.
+    return out

api/routes_keychain.py

@@ -1,278 +1,278 @@
-"""routes_keychain.py — Keychains + Connectors admin surfaces (wave 18, C7 / R3).
-
-Keychain: encrypted per-tenant credential entries (`core/keychain.py`). The routes NEVER
-return a decrypted field — list rows carry a masked preview, and the decrypt function is a
-connector-layer internal. Connectors: the tenant's data sources as STATUS rows — Royal's
-env-configured Odoo, keychain-held sources — plus R3's guardrail: the **Unsynced records**
-count (rows holding overlay data whose pids the current pool no longer serves; counted and
-drillable, never silently dropped) and a pause toggle whose v1 semantics are stated honestly
-in the payload (`pausedNote`): pausing marks intent and warns; the source cutover ships with
-the keychain cutover wave R3 staged.
-"""
-import os
-
-from fastapi import Body, Depends
-from fastapi import APIRouter
-
-from deps import Session, err
-from routes_admin import admin_gate
-
-router = APIRouter(prefix="/api/v1")
-
-#: ⭐ D-10 (wave 24): ONE literal, owned by the harness. It was spelled here AND implied by
-#: `harness/runtime.py`'s reader; a pause flag written under one spelling and read under another
-#: freezes nothing while reporting success, which is the shape of the bug D-10 books.
-from harness.runtime import (CONNECTOR_FLAGS_KEY as _CONNECTOR_FLAGS_KEY,  # noqa: E402
-                             ENV_ODOO_FLAG_KEY as _ENV_ODOO_FLAG_KEY)
-#: DEBT-2 (2026-08-04): the last-successful-sync snapshot bucket. Written when the RESOLVED
-#: odoo connector is paused; read by the pool path while paused; survives a Space restart.
-SNAPSHOT_KEY = "connector_snapshots"
-
-
-def _kc():
-    import core.keychain as keychain
-    return keychain
-
-
-def _resolved_odoo_key(rt):
-    """`(source, flag_key)` — which source would serve this tenant's Odoo queries, in both the
-    shapes this module needs: the display string (`env` / `keychain:<id>`) and the key the pause
-    flag is stored under.
-
-    ⭐ D-10 (wave 24): THE RESOLUTION ITSELF NOW LIVES IN ONE PLACE, `TenantRuntime.odoo_flag_key`,
-    beside the `odoo_source()` it must agree with. This function had its own copy of the same
-    three rules — first unlocked keychain odoo entry, else env for tenant #0, else nothing — and
-    a second copy is exactly how a pause flag comes to be written against one resolution and read
-    against another, freezing nothing while the UI reports success. The two SHAPES stay here
-    because they are this module's presentation concern; the DECISION does not.
-    """
-    flag_key = rt.odoo_flag_key()
-    if not flag_key:
-        return None, None
-    return ("env" if flag_key == _ENV_ODOO_FLAG_KEY else f"keychain:{flag_key}"), flag_key
-
-
-def odoo_paused(rt):
-    """True when the tenant's RESOLVED Odoo source carries the pause flag. Pausing an entry
-    that is not the resolved source freezes nothing — it serves nothing.
-
-    ⭐ D-10: a thin delegate now. The implementation moved to `TenantRuntime.odoo_paused` so the
-    measure mirror (`harness/datastore.py`, which cannot import this layer) asks the SAME question
-    the customer pool does. This name stays because `routes_customers`, `routes_products` and
-    `verify_api` all call it — moving the logic without moving the door keeps one answer and
-    costs no caller a change.
-    """
-    return bool(rt.odoo_paused())
-
-
-def _snap_scope_key(team_id, agent):
-    return f"t={team_id}|a={agent}"
-
-
-def load_pool_snapshot(rt, team_id, agent):
-    """(ts, rows) from the persisted snapshot for this exact scope, or None. NEVER a wider
-    scope's rows — serving the consolidated snapshot to a scoped user would widen their book."""
-    try:
-        snap = (rt.get(SNAPSHOT_KEY) or {}).get("odoo_pool") or {}
-        e = snap.get(_snap_scope_key(team_id, agent))
-        if isinstance(e, dict) and isinstance(e.get("rows"), list):
-            return float(e.get("ts") or 0), e["rows"]
-    except Exception:
-        pass
-    return None
-
-
-def save_pool_snapshots(rt, taken_by=""):
-    """Persist every currently-cached pool scope as the pause-time snapshot ('the last
-    successful sync', made concrete). Ensures the consolidated default scope exists first so
-    a pause on a cold process still captures something to serve."""
-    import time as _time
-    import routes_customers as _rc
-    try:
-        _rc._pool_for(rt, None, None)          # the scope every admin/all-BU account lands on
-    except Exception:
-        pass                                   # cold + Odoo down: persist whatever IS cached
-    pools = {}
-    for key, entry in list(rt.pool_cache.items()):
-        if (isinstance(key, tuple) and len(key) == 3 and key[0] == "pool"
-                and isinstance(entry, tuple) and len(entry) == 2
-                and isinstance(entry[1], list)):
-            pools[_snap_scope_key(key[1], key[2])] = {"ts": entry[0], "rows": entry[1]}
-    if not pools:
-        return 0
-
-    def _up(cur):
-        cur["odoo_pool"] = pools
-        cur["taken"] = _time.strftime("%Y-%m-%dT%H:%M:%S")
-        cur["takenBy"] = str(taken_by or "")
-        return cur
-
-    rt.update(SNAPSHOT_KEY, _up, flush="sync")
-    return len(pools)
-
-
-@router.get("/admin/keychain")
-def list_keychain(session: Session = Depends(admin_gate)):
-    kc = _kc()
-    return {"entries": kc.list_entries(session.runtime), "locked": not kc.unlocked()}
-
-
-@router.post("/admin/keychain", status_code=201)
-def add_key(body: dict = Body(default=None), session: Session = Depends(admin_gate)):
-    kc = _kc()
-    body = body or {}
-    if not session.runtime.available():
-        raise err(503, "store_unavailable", "the tenant store is unavailable")
-    try:
-        row = kc.add_entry(session.runtime, body.get("label"), body.get("type"),
-                           body.get("fields"), session.uname)
-    except kc.KeychainLocked as e:
-        raise err(503, "keychain_locked",
-                  f"the keychain is locked — {e}. A secret is never stored unencrypted.")
-    except ValueError as e:
-        raise err(400, "bad_entry", str(e))
-    except Exception:
-        raise err(503, "store_unavailable", "the entry was not saved — try again")
-    return {"entry": row}
-
-
-@router.delete("/admin/keychain/{entry_id}")
-def delete_key(entry_id: str, session: Session = Depends(admin_gate)):
-    try:
-        _kc().delete_entry(session.runtime, entry_id)
-    except Exception:
-        raise err(503, "store_unavailable", "the delete did not land — try again")
-    return {"ok": True}
-
-
-@router.post("/admin/keychain/{entry_id}/test")
-def test_key(entry_id: str, session: Session = Depends(admin_gate)):
-    return _kc().test_entry(session.runtime, entry_id)
-
-
-def _unsynced_customer_records(session):
-    """R3's guardrail, tenant #0's customer topic: overlay-holding pids the CURRENT pool no
-    longer serves. Overlays are unioned across EVERY user of the table (the guardrail is a
-    tenant fact, not a per-user one). Honest degradation: when the pool cannot be built the
-    answer is `known: False`, never a fabricated zero."""
-    try:
-        import core.table_store as table_store
-        bucket = session.runtime.get("customer_table_workspace") or {}
-        overlay_pids = {}
-        for uname, ws in bucket.items():
-            if uname == table_store.SHARED_KEY or not isinstance(ws, dict):
-                continue
-            for pid, cells in (ws.get("overlays") or {}).items():
-                if isinstance(cells, dict) and cells:
-                    overlay_pids.setdefault(str(pid), cells)
-        if not overlay_pids:
-            return {"known": True, "count": 0, "rows": []}
-        from routes_customers import allowed_pids
-        pool = {str(p) for p in allowed_pids(session)}
-        orphans = sorted((p for p in overlay_pids if p not in pool), key=lambda x: int(x)
-                         if str(x).isdigit() else 0)
-        rows = []
-        for p in orphans[:50]:
-            cells = overlay_pids[p]
-            hint = next((str(v) for v in cells.values() if str(v).strip()), "")
-            rows.append({"pid": int(p) if str(p).isdigit() else p,
-                         "fields": len(cells), "hint": hint[:80]})
-        return {"known": True, "count": len(orphans), "rows": rows,
-                "shown": min(len(orphans), 50)}
-    except Exception as e:
-        return {"known": False, "count": None, "rows": [],
-                "note": f"pool unavailable — {type(e).__name__}"}
-
-
-@router.get("/admin/connectors")
-def connectors(session: Session = Depends(admin_gate)):
-    kc = _kc()
-    flags = session.runtime.get(_CONNECTOR_FLAGS_KEY) or {}
-    entries = kc.list_entries(session.runtime)
-    # R3 cutover (2026-08-04): which source would actually serve this tenant's Odoo queries —
-    # mirrors TenantRuntime.odoo_source() exactly: first unlocked keychain odoo entry, else env
-    # for tenant #0 only, else nothing (fail closed — never another tenant's environment).
-    first_odoo = next((e["id"] for e in entries if e["type"] == "odoo"), None)
-    if first_odoo and kc.unlocked():
-        resolved = f"keychain:{first_odoo}"
-    elif session.tenant == "royal-imports" and os.environ.get("ODOO_URL"):
-        resolved = "env"
-    else:
-        resolved = None
-    rows = []
-    if session.tenant == "royal-imports" and os.environ.get("ODOO_URL"):
-        rows.append({"key": _ENV_ODOO_FLAG_KEY, "label": "Odoo (environment)", "type": "odoo",
-                     "source": "env", "active": resolved == "env",
-                     "paused": bool((flags.get(_ENV_ODOO_FLAG_KEY) or {}).get("paused"))})
-    for e in entries:
-        rows.append({"key": e["id"], "label": e["label"], "type": e["type"],
-                     "source": "keychain", "preview": e["preview"],
-                     "active": (e["type"] == "odoo" and resolved == f"keychain:{e['id']}"),
-                     "paused": bool((flags.get(e["id"]) or {}).get("paused"))})
-    out = {"connectors": rows, "locked": not kc.unlocked(), "resolved": resolved,
-           # ⭐ D-10 (wave 24) — THIS SENTENCE IS NOW TRUE OF EVERY PATH, which it was not before.
-           # DEBT-2 (2026-08-04) froze the CUSTOMER pool and this note honestly disclosed the
-           # hole it left: "measures not already computed may still reach the source". D-10
-           # closed that hole — `harness/datastore.py` (the mirror every measure column is
-           # answered from) refuses to sync while paused, and `routes_products._pool_for` got the
-           # guard its customer sibling has had since DEBT-2. So the caveat is deleted rather
-           # than left standing, because a warning that outlives its defect teaches the reader to
-           # ignore warnings.
-           # ⚠ THE THREE BEHAVIOURS ARE NAMED SEPARATELY on purpose: they are genuinely
-           # different answers (a persisted snapshot, an in-process cache, a frozen mirror), and
-           # collapsing them into "everything freezes" would be the kind of tidy summary that
-           # stops being true the first time one of them changes.
-           # ⭐ D-62 CLOSED (wave 27) — AND THE REGISTER'S DIAGNOSIS OF IT WAS WRONG, so the
-           # correction is recorded here rather than silently applied. D-62 said this note
-           # "promises a behaviour on a dashboard measure path that has been dead since W16".
-           # MEASURED 2026-08-08, and it is not: measure COLUMNS are grid columns answered from
-           # the DuckDB mirror, and `harness/datastore.py` genuinely refuses to sync while
-           # paused (`source_paused()` at four sites), so that clause was TRUE. The dead path is
-           # `/api/v1/pages/{key}` (D-52), which this note never mentioned.
-           #
-           # ⛔ THE REAL DEFECT WAS THE OPPOSITE ONE, and it was the last sentence: "so figures
-           # stop moving rather than going blank". BOTH pool paths answer **503** when they have
-           # no copy to serve — the customer path for a scope with no snapshot
-           # (`routes_customers.py:88`) and the product path ALWAYS after a restart, because
-           # there is no product snapshot bucket at all (`routes_products.py:60-73`, which says
-           # so in as many words). So a paused connector plus a restarted server is exactly the
-           # blank screen this sentence promised could not happen. A warning that over-promises
-           # is worse than none: it is the sentence somebody quotes when the screen disagrees.
-           "pausedNote": ("Pausing a connector never deletes data — notes, custom fields and "
-                          "views stay, and nothing reaches the source while it is paused. "
-                          "Anything this server has already read keeps showing: the customer "
-                          "workspace serves its pause-time snapshot, the product list serves "
-                          "the last copy read since startup, and measure columns keep answering "
-                          "from the mirror as it stood when you paused. What has NOT been read "
-                          "cannot be shown — a scope with no snapshot, or the product list after "
-                          "a restart, reports that the source is paused instead of showing "
-                          "figures. Resume to start reading live again.")}
-    if session.tenant == "royal-imports":
-        out["unsynced"] = _unsynced_customer_records(session)
-    return out
-
-
-@router.post("/admin/connectors/{key}/pause")
-def pause_connector(key: str, body: dict = Body(default=None),
-                    session: Session = Depends(admin_gate)):
-    paused = bool((body or {}).get("paused"))
-    if not session.runtime.available():
-        raise err(503, "store_unavailable", "the tenant store is unavailable")
-
-    # DEBT-2: pausing the RESOLVED Odoo source captures the snapshot FIRST, so there is a
-    # "last successful sync" to serve before the freeze takes effect. Capturing before the
-    # flag flips means a failed capture leaves the connector live (never paused-with-nothing).
-    snapshots = 0
-    _, flag_key = _resolved_odoo_key(session.runtime)
-    if paused and flag_key and str(key) == flag_key:
-        snapshots = save_pool_snapshots(session.runtime, taken_by=session.uname)
-
-    def _up(cur):
-        cur[str(key)] = {"paused": paused}
-        return cur
-
-    try:
-        session.runtime.update(_CONNECTOR_FLAGS_KEY, _up)
-    except Exception:
-        raise err(503, "store_unavailable", "the change was not saved — try again")
-    return {"key": key, "paused": paused, "snapshots": snapshots}
+"""routes_keychain.py — Keychains + Connectors admin surfaces (wave 18, C7 / R3).
+
+Keychain: encrypted per-tenant credential entries (`core/keychain.py`). The routes NEVER
+return a decrypted field — list rows carry a masked preview, and the decrypt function is a
+connector-layer internal. Connectors: the tenant's data sources as STATUS rows — Royal's
+env-configured Odoo, keychain-held sources — plus R3's guardrail: the **Unsynced records**
+count (rows holding overlay data whose pids the current pool no longer serves; counted and
+drillable, never silently dropped) and a pause toggle whose v1 semantics are stated honestly
+in the payload (`pausedNote`): pausing marks intent and warns; the source cutover ships with
+the keychain cutover wave R3 staged.
+"""
+import os
+
+from fastapi import Body, Depends
+from fastapi import APIRouter
+
+from deps import Session, err
+from routes_admin import admin_gate
+
+router = APIRouter(prefix="/api/v1")
+
+#: ⭐ D-10 (wave 24): ONE literal, owned by the harness. It was spelled here AND implied by
+#: `harness/runtime.py`'s reader; a pause flag written under one spelling and read under another
+#: freezes nothing while reporting success, which is the shape of the bug D-10 books.
+from harness.runtime import (CONNECTOR_FLAGS_KEY as _CONNECTOR_FLAGS_KEY,  # noqa: E402
+                             ENV_ODOO_FLAG_KEY as _ENV_ODOO_FLAG_KEY)
+#: DEBT-2 (2026-08-04): the last-successful-sync snapshot bucket. Written when the RESOLVED
+#: odoo connector is paused; read by the pool path while paused; survives a Space restart.
+SNAPSHOT_KEY = "connector_snapshots"
+
+
+def _kc():
+    import core.keychain as keychain
+    return keychain
+
+
+def _resolved_odoo_key(rt):
+    """`(source, flag_key)` — which source would serve this tenant's Odoo queries, in both the
+    shapes this module needs: the display string (`env` / `keychain:<id>`) and the key the pause
+    flag is stored under.
+
+    ⭐ D-10 (wave 24): THE RESOLUTION ITSELF NOW LIVES IN ONE PLACE, `TenantRuntime.odoo_flag_key`,
+    beside the `odoo_source()` it must agree with. This function had its own copy of the same
+    three rules — first unlocked keychain odoo entry, else env for tenant #0, else nothing — and
+    a second copy is exactly how a pause flag comes to be written against one resolution and read
+    against another, freezing nothing while the UI reports success. The two SHAPES stay here
+    because they are this module's presentation concern; the DECISION does not.
+    """
+    flag_key = rt.odoo_flag_key()
+    if not flag_key:
+        return None, None
+    return ("env" if flag_key == _ENV_ODOO_FLAG_KEY else f"keychain:{flag_key}"), flag_key
+
+
+def odoo_paused(rt):
+    """True when the tenant's RESOLVED Odoo source carries the pause flag. Pausing an entry
+    that is not the resolved source freezes nothing — it serves nothing.
+
+    ⭐ D-10: a thin delegate now. The implementation moved to `TenantRuntime.odoo_paused` so the
+    measure mirror (`harness/datastore.py`, which cannot import this layer) asks the SAME question
+    the customer pool does. This name stays because `routes_customers`, `routes_products` and
+    `verify_api` all call it — moving the logic without moving the door keeps one answer and
+    costs no caller a change.
+    """
+    return bool(rt.odoo_paused())
+
+
+def _snap_scope_key(team_id, agent):
+    return f"t={team_id}|a={agent}"
+
+
+def load_pool_snapshot(rt, team_id, agent):
+    """(ts, rows) from the persisted snapshot for this exact scope, or None. NEVER a wider
+    scope's rows — serving the consolidated snapshot to a scoped user would widen their book."""
+    try:
+        snap = (rt.get(SNAPSHOT_KEY) or {}).get("odoo_pool") or {}
+        e = snap.get(_snap_scope_key(team_id, agent))
+        if isinstance(e, dict) and isinstance(e.get("rows"), list):
+            return float(e.get("ts") or 0), e["rows"]
+    except Exception:
+        pass
+    return None
+
+
+def save_pool_snapshots(rt, taken_by=""):
+    """Persist every currently-cached pool scope as the pause-time snapshot ('the last
+    successful sync', made concrete). Ensures the consolidated default scope exists first so
+    a pause on a cold process still captures something to serve."""
+    import time as _time
+    import routes_customers as _rc
+    try:
+        _rc._pool_for(rt, None, None)          # the scope every admin/all-BU account lands on
+    except Exception:
+        pass                                   # cold + Odoo down: persist whatever IS cached
+    pools = {}
+    for key, entry in list(rt.pool_cache.items()):
+        if (isinstance(key, tuple) and len(key) == 3 and key[0] == "pool"
+                and isinstance(entry, tuple) and len(entry) == 2
+                and isinstance(entry[1], list)):
+            pools[_snap_scope_key(key[1], key[2])] = {"ts": entry[0], "rows": entry[1]}
+    if not pools:
+        return 0
+
+    def _up(cur):
+        cur["odoo_pool"] = pools
+        cur["taken"] = _time.strftime("%Y-%m-%dT%H:%M:%S")
+        cur["takenBy"] = str(taken_by or "")
+        return cur
+
+    rt.update(SNAPSHOT_KEY, _up, flush="sync")
+    return len(pools)
+
+
+@router.get("/admin/keychain")
+def list_keychain(session: Session = Depends(admin_gate)):
+    kc = _kc()
+    return {"entries": kc.list_entries(session.runtime), "locked": not kc.unlocked()}
+
+
+@router.post("/admin/keychain", status_code=201)
+def add_key(body: dict = Body(default=None), session: Session = Depends(admin_gate)):
+    kc = _kc()
+    body = body or {}
+    if not session.runtime.available():
+        raise err(503, "store_unavailable", "the tenant store is unavailable")
+    try:
+        row = kc.add_entry(session.runtime, body.get("label"), body.get("type"),
+                           body.get("fields"), session.uname)
+    except kc.KeychainLocked as e:
+        raise err(503, "keychain_locked",
+                  f"the keychain is locked — {e}. A secret is never stored unencrypted.")
+    except ValueError as e:
+        raise err(400, "bad_entry", str(e))
+    except Exception:
+        raise err(503, "store_unavailable", "the entry was not saved — try again")
+    return {"entry": row}
+
+
+@router.delete("/admin/keychain/{entry_id}")
+def delete_key(entry_id: str, session: Session = Depends(admin_gate)):
+    try:
+        _kc().delete_entry(session.runtime, entry_id)
+    except Exception:
+        raise err(503, "store_unavailable", "the delete did not land — try again")
+    return {"ok": True}
+
+
+@router.post("/admin/keychain/{entry_id}/test")
+def test_key(entry_id: str, session: Session = Depends(admin_gate)):
+    return _kc().test_entry(session.runtime, entry_id)
+
+
+def _unsynced_customer_records(session):
+    """R3's guardrail, tenant #0's customer topic: overlay-holding pids the CURRENT pool no
+    longer serves. Overlays are unioned across EVERY user of the table (the guardrail is a
+    tenant fact, not a per-user one). Honest degradation: when the pool cannot be built the
+    answer is `known: False`, never a fabricated zero."""
+    try:
+        import core.table_store as table_store
+        bucket = session.runtime.get("customer_table_workspace") or {}
+        overlay_pids = {}
+        for uname, ws in bucket.items():
+            if uname == table_store.SHARED_KEY or not isinstance(ws, dict):
+                continue
+            for pid, cells in (ws.get("overlays") or {}).items():
+                if isinstance(cells, dict) and cells:
+                    overlay_pids.setdefault(str(pid), cells)
+        if not overlay_pids:
+            return {"known": True, "count": 0, "rows": []}
+        from routes_customers import allowed_pids
+        pool = {str(p) for p in allowed_pids(session)}
+        orphans = sorted((p for p in overlay_pids if p not in pool), key=lambda x: int(x)
+                         if str(x).isdigit() else 0)
+        rows = []
+        for p in orphans[:50]:
+            cells = overlay_pids[p]
+            hint = next((str(v) for v in cells.values() if str(v).strip()), "")
+            rows.append({"pid": int(p) if str(p).isdigit() else p,
+                         "fields": len(cells), "hint": hint[:80]})
+        return {"known": True, "count": len(orphans), "rows": rows,
+                "shown": min(len(orphans), 50)}
+    except Exception as e:
+        return {"known": False, "count": None, "rows": [],
+                "note": f"pool unavailable — {type(e).__name__}"}
+
+
+@router.get("/admin/connectors")
+def connectors(session: Session = Depends(admin_gate)):
+    kc = _kc()
+    flags = session.runtime.get(_CONNECTOR_FLAGS_KEY) or {}
+    entries = kc.list_entries(session.runtime)
+    # R3 cutover (2026-08-04): which source would actually serve this tenant's Odoo queries —
+    # mirrors TenantRuntime.odoo_source() exactly: first unlocked keychain odoo entry, else env
+    # for tenant #0 only, else nothing (fail closed — never another tenant's environment).
+    first_odoo = next((e["id"] for e in entries if e["type"] == "odoo"), None)
+    if first_odoo and kc.unlocked():
+        resolved = f"keychain:{first_odoo}"
+    elif session.tenant == "royal-imports" and os.environ.get("ODOO_URL"):
+        resolved = "env"
+    else:
+        resolved = None
+    rows = []
+    if session.tenant == "royal-imports" and os.environ.get("ODOO_URL"):
+        rows.append({"key": _ENV_ODOO_FLAG_KEY, "label": "Odoo (environment)", "type": "odoo",
+                     "source": "env", "active": resolved == "env",
+                     "paused": bool((flags.get(_ENV_ODOO_FLAG_KEY) or {}).get("paused"))})
+    for e in entries:
+        rows.append({"key": e["id"], "label": e["label"], "type": e["type"],
+                     "source": "keychain", "preview": e["preview"],
+                     "active": (e["type"] == "odoo" and resolved == f"keychain:{e['id']}"),
+                     "paused": bool((flags.get(e["id"]) or {}).get("paused"))})
+    out = {"connectors": rows, "locked": not kc.unlocked(), "resolved": resolved,
+           # ⭐ D-10 (wave 24) — THIS SENTENCE IS NOW TRUE OF EVERY PATH, which it was not before.
+           # DEBT-2 (2026-08-04) froze the CUSTOMER pool and this note honestly disclosed the
+           # hole it left: "measures not already computed may still reach the source". D-10
+           # closed that hole — `harness/datastore.py` (the mirror every measure column is
+           # answered from) refuses to sync while paused, and `routes_products._pool_for` got the
+           # guard its customer sibling has had since DEBT-2. So the caveat is deleted rather
+           # than left standing, because a warning that outlives its defect teaches the reader to
+           # ignore warnings.
+           # ⚠ THE THREE BEHAVIOURS ARE NAMED SEPARATELY on purpose: they are genuinely
+           # different answers (a persisted snapshot, an in-process cache, a frozen mirror), and
+           # collapsing them into "everything freezes" would be the kind of tidy summary that
+           # stops being true the first time one of them changes.
+           # ⭐ D-62 CLOSED (wave 27) — AND THE REGISTER'S DIAGNOSIS OF IT WAS WRONG, so the
+           # correction is recorded here rather than silently applied. D-62 said this note
+           # "promises a behaviour on a dashboard measure path that has been dead since W16".
+           # MEASURED 2026-08-08, and it is not: measure COLUMNS are grid columns answered from
+           # the DuckDB mirror, and `harness/datastore.py` genuinely refuses to sync while
+           # paused (`source_paused()` at four sites), so that clause was TRUE. The dead path is
+           # `/api/v1/pages/{key}` (D-52), which this note never mentioned.
+           #
+           # ⛔ THE REAL DEFECT WAS THE OPPOSITE ONE, and it was the last sentence: "so figures
+           # stop moving rather than going blank". BOTH pool paths answer **503** when they have
+           # no copy to serve — the customer path for a scope with no snapshot
+           # (`routes_customers.py:88`) and the product path ALWAYS after a restart, because
+           # there is no product snapshot bucket at all (`routes_products.py:60-73`, which says
+           # so in as many words). So a paused connector plus a restarted server is exactly the
+           # blank screen this sentence promised could not happen. A warning that over-promises
+           # is worse than none: it is the sentence somebody quotes when the screen disagrees.
+           "pausedNote": ("Pausing a connector never deletes data — notes, custom fields and "
+                          "views stay, and nothing reaches the source while it is paused. "
+                          "Anything this server has already read keeps showing: the customer "
+                          "workspace serves its pause-time snapshot, the product list serves "
+                          "the last copy read since startup, and measure columns keep answering "
+                          "from the mirror as it stood when you paused. What has NOT been read "
+                          "cannot be shown — a scope with no snapshot, or the product list after "
+                          "a restart, reports that the source is paused instead of showing "
+                          "figures. Resume to start reading live again.")}
+    if session.tenant == "royal-imports":
+        out["unsynced"] = _unsynced_customer_records(session)
+    return out
+
+
+@router.post("/admin/connectors/{key}/pause")
+def pause_connector(key: str, body: dict = Body(default=None),
+                    session: Session = Depends(admin_gate)):
+    paused = bool((body or {}).get("paused"))
+    if not session.runtime.available():
+        raise err(503, "store_unavailable", "the tenant store is unavailable")
+
+    # DEBT-2: pausing the RESOLVED Odoo source captures the snapshot FIRST, so there is a
+    # "last successful sync" to serve before the freeze takes effect. Capturing before the
+    # flag flips means a failed capture leaves the connector live (never paused-with-nothing).
+    snapshots = 0
+    _, flag_key = _resolved_odoo_key(session.runtime)
+    if paused and flag_key and str(key) == flag_key:
+        snapshots = save_pool_snapshots(session.runtime, taken_by=session.uname)
+
+    def _up(cur):
+        cur[str(key)] = {"paused": paused}
+        return cur
+
+    try:
+        session.runtime.update(_CONNECTOR_FLAGS_KEY, _up)
+    except Exception:
+        raise err(503, "store_unavailable", "the change was not saved — try again")
+    return {"key": key, "paused": paused, "snapshots": snapshots}

api/routes_platform_admin.py

@@ -1,618 +1,618 @@
-"""routes_platform_admin.py — THE LOOPABLE ADMIN PLANE (wave 19, owner item 13 / R3+R4).
-
-Every other admin surface in this product answers questions about ONE tenant. This one answers
-questions about the PLATFORM: who our customers are, what they are running, whether their data
-sources are alive, and what the automation fleet costs. It is the first cross-tenant reader that
-has ever existed here, which is why it is also the most carefully walled.
-
-⛔ THE WALL. `padmin_gate` is `core.platform_admin.is_platform_admin` — a DOUBLE lock (the record
-flag AND the `loopable` tenant), fail-closed, applied to every single route in this file through
-one dependency. A tenant admin is NOT admitted: `role: 'admin'` is Royal's or Nurilab's authority
-over their own workspace and it must never widen into a view of each other. `verify_api.py`'s
-W19-ADMIN section proves that by ENUMERATING this router and having a tenant admin try every path
-it declares, so a route added later cannot quietly ship without the wall.
-
-⛔ CROSS-TENANT READS GO THROUGH EACH TENANT'S OWN RUNTIME. `runtime.get_runtime(slug)` per tenant,
-then `rt.get(...)` — never `core.store.get("<raw key>")`. The runtime is what applies the store
-NAMESPACE (`t/<slug>/…`) or binds the tenant's OWN dataset repo (R2), so reading raw keys would
-silently return tenant #0's data labelled as somebody else's — a wrong answer that looks right,
-which is the worst failure this plane could have.
-
-HONEST DEGRADATION IS THE WHOLE DESIGN, NOT AN ERROR PATH. This plane reads six subsystems across
-N tenants; on any given day one of them can be unreachable (a suspended tenant record, a locked
-keychain, an HF repo hiccup, no AWS credentials in this container). A 500 would take the entire
-dashboard down because one cell could not be filled. So every collector catches, and every row can
-carry an `error` string that the pane RENDERS — "unknown" is a real answer and it is never
-rendered as a zero. ([[gate-can-report-green-on-nothing]]: a fabricated 0 and a true 0 must not
-look alike.)
-
-EVERY COUNT DRILLS TO ROWS. `/overview`'s per-tenant counts are computed by the SAME collector
-functions the `/users`, `/databases`, `/connectors` and `/automations` routes serve rows from, so
-a number and its drill-down cannot disagree — they are one computation, projected twice
-([[no-unverifiable-aggregates]]).
-"""
-import json
-import os
-import subprocess
-import sys
-import time
-from pathlib import Path
-
-from fastapi import APIRouter, Depends
-
-import core.platform_admin as platform_admin
-import core.store as store
-from deps import Session, err, require_session, users
-
-router = APIRouter(prefix="/api/v1/platform-admin")
-
-
-def _now_iso():
-    """UTC, offset-bearing — the one stamp format anything client-side may subtract from."""
-    import datetime as _dt
-    return _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds")
-
-
-def padmin_gate(session: Session = Depends(require_session)) -> Session:
-    """401 without a session, 403 unless this account is a Loopable platform operator.
-
-    ONE dependency for the whole router. A per-route check is a per-route chance to forget, and
-    the thing being forgotten here would be every customer's data at once.
-
-    The message deliberately does not confirm that a platform plane exists for somebody else —
-    a tenant admin who pokes at this URL learns only that their account cannot open it.
-    """
-    if not platform_admin.is_platform_admin(session.user):
-        raise err(403, "forbidden", "your account does not have access to this surface")
-    return session
-
-
-# ══════════════════════════════════════════════════════════════════════════ tenants
-
-
-def _tenant_bucket():
-    """The control-plane `tenants` records, or {} — a platform fact, in the DEFAULT store."""
-    from harness import runtime
-    try:
-        recs = store.get(runtime.TENANTS_KEY) or {}
-        return {str(k).strip().lower(): v for k, v in recs.items() if isinstance(v, dict)}
-    except Exception:
-        return {}
-
-
-def _slugs():
-    """Every tenant this deployment knows: compiled builders + control-plane records.
-
-    `runtime.known_tenants()` is the union and it is the same list login resolves against, so
-    this plane cannot show a customer the door does not recognise (or miss one it does).
-    """
-    from harness import runtime
-    try:
-        return list(runtime.known_tenants())
-    except Exception:
-        return sorted(_tenant_bucket())
-
-
-def _runtime_for(slug):
-    """(runtime, error). A tenant whose runtime will not build is a ROW WITH A NOTE, never a 500.
-
-    Two real cases produce one: a SUSPENDED record (`get_runtime` raises KeyError by design —
-    "which tenants exist" is not a question the login path answers), and tenant #0's builder,
-    which makes a LIVE Odoo call (`harness.tenants.royal_imports` → `excluded_customer_ids`) and
-    therefore fails on a box that cannot reach the ERP. Neither may take the dashboard down.
-    """
-    from harness import runtime
-    try:
-        return runtime.get_runtime(slug), ""
-    except KeyError:
-        return None, "not resolvable (suspended, or no builder and no active record)"
-    except Exception as e:                                        # noqa: BLE001
-        return None, f"runtime unavailable ({type(e).__name__})"
-
-
-def _scan(want=""):
-    """[(row, runtime)] — every tenant (or one), with its runtime RESOLVED EXACTLY ONCE.
-
-    The one-resolution rule is not tidiness. `get_runtime` is LRU-cached on success, but a tenant
-    that FAILS to build is not cached, and tenant #0's builder makes a live Odoo call — so a route
-    that asked twice would pay the timeout twice, and `/overview` (which asks about six
-    subsystems) would pay it six times. Resolve once, pass the handle down.
-    """
-    bucket = _tenant_bucket()
-    want = str(want or "").strip().lower()
-    out = []
-    for slug in _slugs():
-        if want and slug != want:
-            continue
-        rec = bucket.get(slug) or {}
-        rt, error = _runtime_for(slug)
-        out.append(({
-            "slug": slug,
-            # The record's name, else the built runtime's, else the slug. Tenant #0 is compiled
-            # and has no record, so without the runtime fallback it would render as "royal-imports".
-            "name": str(rec.get("name") or (getattr(rt, "name", "") if rt else "") or slug),
-            "source": "record" if rec else "compiled",
-            "status": str(rec.get("status") or ("active" if rt else "unknown")),
-            "domains": list(rec.get("domains") or []),
-            "modules": rec.get("modules", "all" if not rec else []),
-            # R2: the isolation shape. "own repo" and "shared repo + prefix" are genuinely
-            # different blast radii and an operator should be able to see which is which.
-            "storeRepo": rec.get("store_repo") or ("shared (tenant #0 repo)" if not rec else ""),
-            "storePrefix": getattr(rt, "store_namespace", "") if rt else "",
-            "error": error,
-        }, rt))
-    return out
-
-
-# ══════════════════════════════════════════════════════════════════════════ users
-
-
-def _user_rows(tenant=None):
-    """Accounts across every tenant, from the GLOBAL registry (`users.json` is control-plane).
-
-    ⛔ NEVER `salt` OR `hash`. This projection is the only one these routes use, mirroring
-    `routes_admin._view`'s discipline: one function that can leak, and it does not.
-
-    R4's two new fields ride here — `lastLogin` / `lastActive`, absent on every pre-wave record,
-    rendered as "never" rather than as a fabricated date.
-    """
-    try:
-        reg = users.registry() or {}
-    except Exception:
-        return []
-    want = str(tenant or "").strip().lower()
-    rows = []
-    for uname, rec in sorted(reg.items()):
-        if not isinstance(rec, dict):
-            continue
-        slug = str(rec.get("tenant") or "royal-imports").strip().lower()
-        if want and slug != want:
-            continue
-        rows.append({
-            "username": uname,
-            "name": rec.get("name") or uname,
-            "email": rec.get("email") or "",
-            "tenant": slug,
-            "role": rec.get("role", "user"),
-            "active": bool(rec.get("active", True)),
-            "lastLogin": rec.get("last_login") or "",
-            "lastActive": rec.get("last_active") or "",
-            "platformAdmin": rec.get("platform_admin") is True,
-        })
-    return rows
-
-
-# ══════════════════════════════════════════════════════════════════════════ databases
-
-
-def _database_rows(slug, rt):
-    """A tenant's user-created databases (`ut_*`) with their row counts.
-
-    Via `core.user_tables.all_tables(st=rt)` — the TenantRuntime, never the module-global, which
-    the engine's own header (`automation_engine.py:49-52`) flags as a cross-tenant defect for
-    every R2 tenant. That booked defect is exactly the mistake a cross-tenant reader would make
-    most easily, so it is stated at the call site too.
-    """
-    try:
-        import core.user_tables as ut
-        tables = ut.all_tables(st=rt) or {}
-    except Exception as e:                                        # noqa: BLE001
-        return [], f"databases unreadable ({type(e).__name__})"
-    rows = []
-    for key, t in sorted(tables.items(), key=lambda kv: (kv[1].get("label") or "").lower()):
-        if not isinstance(t, dict):
-            continue
-        rows.append({
-            "tenant": slug,
-            "key": key,
-            "label": t.get("label") or key,
-            "source": t.get("source") or "Blank",
-            "createdBy": t.get("createdBy") or "",
-            "created": t.get("created") or "",
-            "fields": len(t.get("fields") or []),
-            "rowCount": len(t.get("rows") or {}),
-        })
-    return rows, ""
-
-
-# ══════════════════════════════════════════════════════════════════════════ connectors
-
-
-def _connector_rows(slug, rt):
-    """A tenant's data sources and which one is actually RESOLVED (i.e. would serve a query).
-
-    `_resolved_odoo_key` is imported from `routes_keychain` rather than re-derived. It is the
-    route-level mirror of `TenantRuntime.odoo_source()`, it takes a runtime (not a session), and
-    a second copy of that resolution here would be a copy that drifts — at which point this plane
-    would confidently name the wrong live connector. Reused, not restated.
-    """
-    try:
-        import core.keychain as keychain
-        from routes_keychain import _CONNECTOR_FLAGS_KEY, _resolved_odoo_key
-        entries = keychain.list_entries(rt)
-        locked = not keychain.unlocked()
-        resolved, _flag = _resolved_odoo_key(rt)
-        flags = rt.get(_CONNECTOR_FLAGS_KEY) or {}
-    except Exception as e:                                        # noqa: BLE001
-        return [], f"connectors unreadable ({type(e).__name__})", False
-
-    rows = []
-    if slug == "royal-imports" and os.environ.get("ODOO_URL"):
-        rows.append({"tenant": slug, "key": "odoo-env", "label": "Odoo (environment)",
-                     "type": "odoo", "source": "env", "active": resolved == "env",
-                     "paused": bool((flags.get("odoo-env") or {}).get("paused"))})
-    for e in entries:
-        rows.append({"tenant": slug, "key": e["id"], "label": e["label"], "type": e["type"],
-                     "source": "keychain",
-                     "active": e["type"] == "odoo" and resolved == f"keychain:{e['id']}",
-                     "paused": bool((flags.get(e["id"]) or {}).get("paused"))})
-    return rows, "", locked
-
-
-# ══════════════════════════════════════════════════════════════════════════ automations + cost
-
-#: THE UNIT MODEL, from `ops/provision_automation_cron.py` (its cost note at :25-28 and the
-#: function it actually provisions at :211 / :269). Restated as constants rather than as prose so
-#: the arithmetic below is re-checkable against the thing that was really deployed:
-#: EventBridge Scheduler `rate(15 minutes)` → a 128 MB, 30 s-timeout Lambda that POSTs the tick.
-TICK_CADENCE = "rate(15 minutes)"
-TICK_PER_DAY = 96                       # 1440 / 15
-LAMBDA_MB = 128
-FREE_LAMBDA_REQUESTS = 1_000_000        # AWS always-free, per month
-FREE_SCHEDULER_INVOCATIONS = 14_000_000
-DAYS_PER_MONTH = 30.4
-
-
-def _runs_per_day(cron):
-    """Scheduled runs/day for the five-field crons this product offers, or None.
-
-    ⚠ DELIBERATELY NARROW. It answers exactly the shapes `automation_engine.CRON_PRESETS` can
-    produce (every-N-minutes, hourly, daily, weekly, monthly) and returns None for anything else
-    — an unparsed cadence is reported as "custom", never as a guessed number that would then be
-    multiplied into a cost. A wrong denominator is worse than an absent one.
-
-    ⚠ AND IT IS NOT MEASURED FROM HISTORY, on purpose: `automation_engine.MAX_RUNS` trims run
-    history to 20 entries, so a 15-minute automation retains ~5 hours of it. Deriving runs/day
-    from that window would understate by ~5x. History is reported as what it is — the last N runs.
-    """
-    parts = str(cron or "").split()
-    if len(parts) != 5:
-        return None
-    minute, hour, dom, _mon, dow = parts
-    if minute.startswith("*/") and hour == "*":
-        try:
-            step = int(minute[2:])
-        except ValueError:
-            return None
-        return (1440.0 / step) if step > 0 else None
-    if minute.isdigit() and hour == "*":
-        return 24.0
-    if minute.isdigit() and hour.isdigit():
-        if dom.isdigit():
-            return 1.0 / DAYS_PER_MONTH          # monthly
-        if dow.isdigit():
-            return 1.0 / 7.0                     # weekly
-        return 1.0                               # daily
-    return None
-
-
-def _automation_rows(slug, rt):
-    """A tenant's automations, their schedules, and their retained run history."""
-    try:
-        import automation_engine as engine
-        defs = engine.all_definitions(rt) or {}
-        max_runs = int(getattr(engine, "MAX_RUNS", 20))
-    except Exception as e:                                        # noqa: BLE001
-        return [], f"automations unreadable ({type(e).__name__})", 20
-    rows = []
-    for auto_id, d in sorted(defs.items(), key=lambda kv: (kv[1].get("name") or "").lower()):
-        if not isinstance(d, dict):
-            continue
-        sched = d.get("schedule") or {}
-        status = d.get("status") or {}
-        runs = list(d.get("runs") or [])
-        cron = sched.get("cron") or ""
-        per_day = _runs_per_day(cron) if sched.get("enabled") else 0.0
-        rows.append({
-            "tenant": slug,
-            "id": auto_id,
-            "name": d.get("name") or auto_id,
-            "kind": d.get("kind") or "",
-            "enabled": bool(sched.get("enabled")),
-            "cron": cron,
-            "runsPerDay": round(per_day, 2) if per_day is not None else None,
-            "state": status.get("state") or "idle",
-            "lastRunAt": status.get("lastRunAt") or "",
-            "lastSummary": status.get("lastSummary") or "",
-            # The retained window, named as such — see `_runs_per_day`'s second warning.
-            "runsRetained": len(runs),
-            "failedRetained": sum(1 for r in runs if isinstance(r, dict) and not r.get("ok")),
-            "createdBy": d.get("createdBy") or "",
-            "created": d.get("created") or "",
-        })
-    return rows, "", max_runs
-
-
-def _automation_cost(auto_rows):
-    """The estimated monthly cost of running the automation fleet — and the honest shape of it.
-
-    THE POINT THIS BLOCK EXISTS TO MAKE, which is not intuitive: **the external cron does not
-    scale with automations or tenants.** One EventBridge schedule fires one Lambda, which POSTs
-    one tick, and that tick runs every DUE automation for every tenant (`provision_automation_cron`
-    states this as the reason it stays $0 "at ten tenants"). So the AWS bill is a function of the
-    CADENCE alone — the fleet below adds work inside the API container, which is already paid for.
-
-    WHAT IS NOT COMPUTED HERE, deliberately: Lambda GB-seconds. That needs the real average
-    duration of the function, which only CloudWatch knows; assuming one would be inventing the
-    larger half of the free-tier calculation. `/aws` reports the measured figure when credentials
-    are available, and this block says so rather than filling the gap with a plausible number.
-    """
-    invocations = TICK_PER_DAY * DAYS_PER_MONTH
-    fleet_runs = sum(r["runsPerDay"] or 0 for r in auto_rows if r.get("enabled"))
-    unknown_cadence = sum(1 for r in auto_rows if r.get("enabled") and r.get("runsPerDay") is None)
-    return {
-        "cadence": TICK_CADENCE,
-        "invocationsPerMonth": int(round(invocations)),
-        "freeRequestsPct": round(100.0 * invocations / FREE_LAMBDA_REQUESTS, 3),
-        "freeSchedulerPct": round(100.0 * invocations / FREE_SCHEDULER_INVOCATIONS, 4),
-        "lambdaMb": LAMBDA_MB,
-        "usd": 0.0,
-        "fleetRunsPerDay": round(fleet_runs, 2),
-        "unknownCadence": unknown_cadence,
-        "basis": (
-            f"One EventBridge schedule ({TICK_CADENCE}) fires one {LAMBDA_MB} MB Lambda that "
-            f"POSTs the tick; that ONE tick runs every due automation for every tenant, so the "
-            f"AWS cost is set by the cadence and does not grow with the fleet. "
-            f"{int(round(invocations)):,} invocations/month is "
-            f"{round(100.0 * invocations / FREE_LAMBDA_REQUESTS, 3)}% of the 1,000,000-request "
-            f"always-free tier, so the marginal cost of the automations below is $0.00. "
-            f"Compute (GB-seconds) depends on measured durations and is NOT estimated here — "
-            f"the AWS report reads the real figure when credentials are available."
-        ),
-    }
-
-
-# ══════════════════════════════════════════════════════════════════════════ the AWS report
-
-#: `ops/aws_usage_report.py`, relative to this file: aios-web/api/ -> repo root -> ops/.
-_AWS_REPORT = Path(__file__).resolve().parents[2] / "ops" / "aws_usage_report.py"
-_AWS_TIMEOUT = 60
-
-
-def _aws_report(days=7):
-    """The AWS usage report as text, or an honest block saying why there is none.
-
-    ⛔ SUBPROCESS, NEVER `import`. Two concrete reasons, both found by reading that file rather
-    than by running it:
-      * it reassigns `sys.stdout` to a UTF-8 wrapper AT MODULE IMPORT (a cp1252 fix for this
-        box) — importing it would mutate the API process's stdout as a side effect;
-      * its `main()` calls `argparse.parse_args()` with no argv, so inside a server it would
-        parse UVICORN's arguments and can `sys.exit(2)` — and `SystemExit` is a `BaseException`,
-        which `except Exception` does not catch. A route that "cannot crash" would crash.
-
-    ⚠ ON THE SPACE THIS IS THE NORMAL PATH, NOT THE ERROR PATH. `deploy_web.py` ships `api/*.py`
-    and `web/`; `ops/` is not in the image, and AWS credentials live in a local `.env` that is
-    never deployed. So the honest block below is what the deployed plane shows, and it is written
-    to be read by an operator as information ("run it here") rather than as a fault.
-    """
-    if not _AWS_REPORT.is_file():
-        return {"available": False, "text": "",
-                "note": ("The AWS usage report is not part of this deployment — `ops/` ships "
-                         "with the repository, not with the container image. Run "
-                         "`python ops/aws_usage_report.py` locally for the live figures.")}
-    try:
-        proc = subprocess.run(
-            [sys.executable, str(_AWS_REPORT), "--days", str(int(days))],
-            capture_output=True, text=True, timeout=_AWS_TIMEOUT,
-            cwd=str(_AWS_REPORT.parent.parent))
-    except subprocess.TimeoutExpired:
-        return {"available": False, "text": "",
-                "note": (f"The AWS report did not answer within {_AWS_TIMEOUT}s — CloudWatch may "
-                         f"be unreachable from here. Nothing was assumed about usage.")}
-    except Exception as e:                                        # noqa: BLE001
-        return {"available": False, "text": "",
-                "note": f"The AWS report could not be run here ({type(e).__name__})."}
-    out = (proc.stdout or "").strip()
-    if proc.returncode != 0 or not out:
-        detail = (proc.stderr or "").strip().splitlines()
-        return {"available": False, "text": out,
-                "note": ("AWS credentials are not available here, or boto3 is not installed — "
-                         "no usage could be read, and none is guessed. "
-                         + (detail[-1][:200] if detail else ""))}
-    return {"available": True, "text": out, "note": ""}
-
-
-# ══════════════════════════════════════════════════════════════════════════ routes
-
-
-@router.get("/overview")
-def overview(session: Session = Depends(padmin_gate)):
-    """THE PLANE'S ONE TABLE: every tenant, with the counts that drill to the rows below.
-
-    Each count is produced by the same collector its `/…` route serves, so the number and its
-    drill-down are one computation projected twice. A subsystem that cannot be read contributes
-    an `errors` entry on that tenant's row and a NULL count — never a zero, which would read as
-    "this customer has no databases" when the truth is "we could not look".
-    """
-    t0 = time.time()
-    all_users = _user_rows()
-    users_by_tenant = {}
-    for u in all_users:
-        users_by_tenant.setdefault(u["tenant"], []).append(u)
-
-    rows = []
-    for t, rt in _scan():
-        slug = t["slug"]
-        row = dict(t)
-        row["users"] = len(users_by_tenant.get(slug, []))
-        row["admins"] = sum(1 for u in users_by_tenant.get(slug, []) if u["role"] == "admin")
-        errors = [t["error"]] if t["error"] else []
-        if rt is None:
-            # An unresolvable tenant still shows its ACCOUNTS (they live in the global registry,
-            # which is readable regardless) — everything tenant-store-shaped is honestly unknown.
-            row.update({"databases": None, "rows": None, "connectors": None,
-                        "automations": None, "keychainLocked": None, "errors": errors})
-            rows.append(row)
-            continue
-        dbs, db_err = _database_rows(slug, rt)
-        conns, conn_err, locked = _connector_rows(slug, rt)
-        autos, auto_err, _mr = _automation_rows(slug, rt)
-        errors += [e for e in (db_err, conn_err, auto_err) if e]
-        row.update({
-            "databases": None if db_err else len(dbs),
-            "rows": None if db_err else sum(d["rowCount"] for d in dbs),
-            "connectors": None if conn_err else len(conns),
-            "connectorsPaused": None if conn_err else sum(1 for c in conns if c["paused"]),
-            "automations": None if auto_err else len(autos),
-            "automationsEnabled": None if auto_err else sum(1 for a in autos if a["enabled"]),
-            "keychainLocked": None if conn_err else locked,
-            "errors": errors,
-        })
-        rows.append(row)
-
-    return {
-        "tenants": rows,
-        "totals": {
-            "tenants": len(rows),
-            # EVERY account, not the sum of the rows: an account whose `tenant` names a slug this
-            # deployment no longer knows belongs in the platform total and would vanish from a
-            # per-row sum. `orphanUsers` names that gap instead of hiding it.
-            "users": len(all_users),
-            "orphanUsers": len(all_users) - sum(r["users"] for r in rows),
-            # Sums SKIP unknowns rather than treating them as 0, and say how many were skipped —
-            # a total that silently absorbs an unreadable tenant is a fabricated total.
-            "databases": sum(r["databases"] or 0 for r in rows),
-            "rows": sum(r["rows"] or 0 for r in rows),
-            "automations": sum(r["automations"] or 0 for r in rows),
-            "unknownTenants": sum(1 for r in rows if r["databases"] is None),
-        },
-        "storeAvailable": bool(_store_ok()),
-        # ⚠ OFFSET-BEARING, and that is not pedantry. The client renders this as "read 2 minutes
-        # ago" via `Date.parse`, which reads a NAIVE stamp as browser-local — so a UTC container
-        # and a US viewer would turn "just now" into "5 hours ago", or into a future date that
-        # renders as "just now" forever. The stamps written by `core.users` carry an offset for
-        # the same reason; anything a browser subtracts from `Date.now()` must say what zone it
-        # is in. `verify_api` asserts the offset so this cannot regress to `strftime`.
-        "generatedAt": _now_iso(),
-        "tookMs": int((time.time() - t0) * 1000),
-    }
-
-
-def _store_ok():
-    try:
-        return store.available()
-    except Exception:
-        return False
-
-
-@router.get("/users")
-def platform_users(tenant: str = "", session: Session = Depends(padmin_gate)):
-    """Every account on the platform, or one tenant's — the drill behind the Users count.
-
-    R4's stamps are the columns that did not exist before this wave: `lastLogin` is written by
-    `routes_auth.login`, `lastActive` by `deps.require_session` (throttled to once an hour per
-    account per process). Absent means never seen, and the pane renders it as "never".
-    """
-    rows = _user_rows(tenant)
-    return {"users": rows, "count": len(rows),
-            "stampsNote": ("Login and activity stamps started with this release — accounts that "
-                           "have not signed in since show no date rather than an invented one. "
-                           "Activity is recorded at most once an hour per account.")}
-
-
-@router.get("/databases")
-def platform_databases(tenant: str = "", session: Session = Depends(padmin_gate)):
-    """Every tenant's user-created databases and row counts — the drill behind Databases/Rows."""
-    out, errors = [], {}
-    for t, rt in _scan(tenant):
-        slug = t["slug"]
-        if rt is None:
-            errors[slug] = t["error"]
-            continue
-        rows, err = _database_rows(slug, rt)
-        if err:
-            errors[slug] = err
-            continue
-        out += rows
-    return {"databases": out, "count": len(out),
-            "rows": sum(d["rowCount"] for d in out), "errors": errors}
-
-
-@router.get("/connectors")
-def platform_connectors(tenant: str = "", session: Session = Depends(padmin_gate)):
-    """Every tenant's data sources, which one is live, and which are paused.
-
-    METADATA ONLY — `keychain.list_entries` never decrypts, so no credential, and no masked
-    preview either: a platform operator needs to know a source EXISTS and whether it serves, not
-    what the secret looks like. The tenant's own admin surface is where previews belong.
-    """
-    out, errors, locked_any = [], {}, {}
-    for t, rt in _scan(tenant):
-        slug = t["slug"]
-        if rt is None:
-            errors[slug] = t["error"]
-            continue
-        rows, err, locked = _connector_rows(slug, rt)
-        if err:
-            errors[slug] = err
-            continue
-        locked_any[slug] = locked
-        out += rows
-    return {"connectors": out, "count": len(out), "keychainLocked": locked_any,
-            "errors": errors,
-            "note": ("A locked keychain means this container has no `AIOS_KEYCHAIN_KEY` — stored "
-                     "credentials cannot be read, so a tenant's sources fail closed rather than "
-                     "falling back to anyone else's.")}
-
-
-@router.get("/automations")
-def platform_automations(tenant: str = "", session: Session = Depends(padmin_gate)):
-    """Every tenant's automations, their schedules and run history, plus the fleet cost model."""
-    out, errors, retained = [], {}, 20
-    for t, rt in _scan(tenant):
-        slug = t["slug"]
-        if rt is None:
-            errors[slug] = t["error"]
-            continue
-        rows, err, max_runs = _automation_rows(slug, rt)
-        if err:
-            errors[slug] = err
-            continue
-        retained = max_runs
-        out += rows
-    return {"automations": out, "count": len(out),
-            "enabled": sum(1 for a in out if a["enabled"]),
-            "historyRetained": retained,
-            "cost": _automation_cost(out), "errors": errors,
-            "tickEnabled": os.environ.get("AIOS_AUTOMATIONS") == "1"}
-
-
-@router.get("/aws")
-def platform_aws(days: int = 7, session: Session = Depends(padmin_gate)):
-    """The AWS cron's usage report, verbatim, or an honest note explaining its absence."""
-    days = max(1, min(int(days or 7), 90))
-    return {"days": days, "report": _aws_report(days)}
-
-
-@router.get("/releases")
-def platform_releases(session: Session = Depends(padmin_gate)):
-    """⭐ WAVE 20 (owner item 12, ruling R6) — WHAT IS RUNNING WHERE, and what else could be.
-
-    Owner: *"Make this part of the deploy skill. Also ability to revert to any version we want.
-    Make sure App versioning is something that our company admin (loopable, non-tenant) can
-    easily see."* This is the SEEING half; promoting stays a CLI command by R6, so nothing here
-    writes and no web session can move production.
-
-    ⛔ THE HUB READS LIVE IN `core/releases.py`, NOT HERE. `ops/verify_portability.py` B2 forbids
-    the HuggingFace SDK anywhere under `aios-web/api/` — the API process is host-agnostic by
-    design — and it caught this endpoint's first draft doing exactly that. Same delegation shape
-    as `routes_assets` -> `core/assets.py`.
-    """
-    import core.releases as releases
-
-    return {"here": os.environ.get("AIOS_VERSION") or "unknown",
-            "environments": releases.environments(),
-            "releases": releases.history(),
-            # The runbook, in the payload, because the panel is read-only BY DESIGN and a user
-            # looking at it is exactly the person who needs to know how to move a version.
-            "promote": "python aios-web/deploy_web.py --promote=vN   (or --promote=staging)"}
+"""routes_platform_admin.py — THE LOOPABLE ADMIN PLANE (wave 19, owner item 13 / R3+R4).
+
+Every other admin surface in this product answers questions about ONE tenant. This one answers
+questions about the PLATFORM: who our customers are, what they are running, whether their data
+sources are alive, and what the automation fleet costs. It is the first cross-tenant reader that
+has ever existed here, which is why it is also the most carefully walled.
+
+⛔ THE WALL. `padmin_gate` is `core.platform_admin.is_platform_admin` — a DOUBLE lock (the record
+flag AND the `loopable` tenant), fail-closed, applied to every single route in this file through
+one dependency. A tenant admin is NOT admitted: `role: 'admin'` is Royal's or Nurilab's authority
+over their own workspace and it must never widen into a view of each other. `verify_api.py`'s
+W19-ADMIN section proves that by ENUMERATING this router and having a tenant admin try every path
+it declares, so a route added later cannot quietly ship without the wall.
+
+⛔ CROSS-TENANT READS GO THROUGH EACH TENANT'S OWN RUNTIME. `runtime.get_runtime(slug)` per tenant,
+then `rt.get(...)` — never `core.store.get("<raw key>")`. The runtime is what applies the store
+NAMESPACE (`t/<slug>/…`) or binds the tenant's OWN dataset repo (R2), so reading raw keys would
+silently return tenant #0's data labelled as somebody else's — a wrong answer that looks right,
+which is the worst failure this plane could have.
+
+HONEST DEGRADATION IS THE WHOLE DESIGN, NOT AN ERROR PATH. This plane reads six subsystems across
+N tenants; on any given day one of them can be unreachable (a suspended tenant record, a locked
+keychain, an HF repo hiccup, no AWS credentials in this container). A 500 would take the entire
+dashboard down because one cell could not be filled. So every collector catches, and every row can
+carry an `error` string that the pane RENDERS — "unknown" is a real answer and it is never
+rendered as a zero. ([[gate-can-report-green-on-nothing]]: a fabricated 0 and a true 0 must not
+look alike.)
+
+EVERY COUNT DRILLS TO ROWS. `/overview`'s per-tenant counts are computed by the SAME collector
+functions the `/users`, `/databases`, `/connectors` and `/automations` routes serve rows from, so
+a number and its drill-down cannot disagree — they are one computation, projected twice
+([[no-unverifiable-aggregates]]).
+"""
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from fastapi import APIRouter, Depends
+
+import core.platform_admin as platform_admin
+import core.store as store
+from deps import Session, err, require_session, users
+
+router = APIRouter(prefix="/api/v1/platform-admin")
+
+
+def _now_iso():
+    """UTC, offset-bearing — the one stamp format anything client-side may subtract from."""
+    import datetime as _dt
+    return _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds")
+
+
+def padmin_gate(session: Session = Depends(require_session)) -> Session:
+    """401 without a session, 403 unless this account is a Loopable platform operator.
+
+    ONE dependency for the whole router. A per-route check is a per-route chance to forget, and
+    the thing being forgotten here would be every customer's data at once.
+
+    The message deliberately does not confirm that a platform plane exists for somebody else —
+    a tenant admin who pokes at this URL learns only that their account cannot open it.
+    """
+    if not platform_admin.is_platform_admin(session.user):
+        raise err(403, "forbidden", "your account does not have access to this surface")
+    return session
+
+
+# ══════════════════════════════════════════════════════════════════════════ tenants
+
+
+def _tenant_bucket():
+    """The control-plane `tenants` records, or {} — a platform fact, in the DEFAULT store."""
+    from harness import runtime
+    try:
+        recs = store.get(runtime.TENANTS_KEY) or {}
+        return {str(k).strip().lower(): v for k, v in recs.items() if isinstance(v, dict)}
+    except Exception:
+        return {}
+
+
+def _slugs():
+    """Every tenant this deployment knows: compiled builders + control-plane records.
+
+    `runtime.known_tenants()` is the union and it is the same list login resolves against, so
+    this plane cannot show a customer the door does not recognise (or miss one it does).
+    """
+    from harness import runtime
+    try:
+        return list(runtime.known_tenants())
+    except Exception:
+        return sorted(_tenant_bucket())
+
+
+def _runtime_for(slug):
+    """(runtime, error). A tenant whose runtime will not build is a ROW WITH A NOTE, never a 500.
+
+    Two real cases produce one: a SUSPENDED record (`get_runtime` raises KeyError by design —
+    "which tenants exist" is not a question the login path answers), and tenant #0's builder,
+    which makes a LIVE Odoo call (`harness.tenants.royal_imports` → `excluded_customer_ids`) and
+    therefore fails on a box that cannot reach the ERP. Neither may take the dashboard down.
+    """
+    from harness import runtime
+    try:
+        return runtime.get_runtime(slug), ""
+    except KeyError:
+        return None, "not resolvable (suspended, or no builder and no active record)"
+    except Exception as e:                                        # noqa: BLE001
+        return None, f"runtime unavailable ({type(e).__name__})"
+
+
+def _scan(want=""):
+    """[(row, runtime)] — every tenant (or one), with its runtime RESOLVED EXACTLY ONCE.
+
+    The one-resolution rule is not tidiness. `get_runtime` is LRU-cached on success, but a tenant
+    that FAILS to build is not cached, and tenant #0's builder makes a live Odoo call — so a route
+    that asked twice would pay the timeout twice, and `/overview` (which asks about six
+    subsystems) would pay it six times. Resolve once, pass the handle down.
+    """
+    bucket = _tenant_bucket()
+    want = str(want or "").strip().lower()
+    out = []
+    for slug in _slugs():
+        if want and slug != want:
+            continue
+        rec = bucket.get(slug) or {}
+        rt, error = _runtime_for(slug)
+        out.append(({
+            "slug": slug,
+            # The record's name, else the built runtime's, else the slug. Tenant #0 is compiled
+            # and has no record, so without the runtime fallback it would render as "royal-imports".
+            "name": str(rec.get("name") or (getattr(rt, "name", "") if rt else "") or slug),
+            "source": "record" if rec else "compiled",
+            "status": str(rec.get("status") or ("active" if rt else "unknown")),
+            "domains": list(rec.get("domains") or []),
+            "modules": rec.get("modules", "all" if not rec else []),
+            # R2: the isolation shape. "own repo" and "shared repo + prefix" are genuinely
+            # different blast radii and an operator should be able to see which is which.
+            "storeRepo": rec.get("store_repo") or ("shared (tenant #0 repo)" if not rec else ""),
+            "storePrefix": getattr(rt, "store_namespace", "") if rt else "",
+            "error": error,
+        }, rt))
+    return out
+
+
+# ══════════════════════════════════════════════════════════════════════════ users
+
+
+def _user_rows(tenant=None):
+    """Accounts across every tenant, from the GLOBAL registry (`users.json` is control-plane).
+
+    ⛔ NEVER `salt` OR `hash`. This projection is the only one these routes use, mirroring
+    `routes_admin._view`'s discipline: one function that can leak, and it does not.
+
+    R4's two new fields ride here — `lastLogin` / `lastActive`, absent on every pre-wave record,
+    rendered as "never" rather than as a fabricated date.
+    """
+    try:
+        reg = users.registry() or {}
+    except Exception:
+        return []
+    want = str(tenant or "").strip().lower()
+    rows = []
+    for uname, rec in sorted(reg.items()):
+        if not isinstance(rec, dict):
+            continue
+        slug = str(rec.get("tenant") or "royal-imports").strip().lower()
+        if want and slug != want:
+            continue
+        rows.append({
+            "username": uname,
+            "name": rec.get("name") or uname,
+            "email": rec.get("email") or "",
+            "tenant": slug,
+            "role": rec.get("role", "user"),
+            "active": bool(rec.get("active", True)),
+            "lastLogin": rec.get("last_login") or "",
+            "lastActive": rec.get("last_active") or "",
+            "platformAdmin": rec.get("platform_admin") is True,
+        })
+    return rows
+
+
+# ══════════════════════════════════════════════════════════════════════════ databases
+
+
+def _database_rows(slug, rt):
+    """A tenant's user-created databases (`ut_*`) with their row counts.
+
+    Via `core.user_tables.all_tables(st=rt)` — the TenantRuntime, never the module-global, which
+    the engine's own header (`automation_engine.py:49-52`) flags as a cross-tenant defect for
+    every R2 tenant. That booked defect is exactly the mistake a cross-tenant reader would make
+    most easily, so it is stated at the call site too.
+    """
+    try:
+        import core.user_tables as ut
+        tables = ut.all_tables(st=rt) or {}
+    except Exception as e:                                        # noqa: BLE001
+        return [], f"databases unreadable ({type(e).__name__})"
+    rows = []
+    for key, t in sorted(tables.items(), key=lambda kv: (kv[1].get("label") or "").lower()):
+        if not isinstance(t, dict):
+            continue
+        rows.append({
+            "tenant": slug,
+            "key": key,
+            "label": t.get("label") or key,
+            "source": t.get("source") or "Blank",
+            "createdBy": t.get("createdBy") or "",
+            "created": t.get("created") or "",
+            "fields": len(t.get("fields") or []),
+            "rowCount": len(t.get("rows") or {}),
+        })
+    return rows, ""
+
+
+# ══════════════════════════════════════════════════════════════════════════ connectors
+
+
+def _connector_rows(slug, rt):
+    """A tenant's data sources and which one is actually RESOLVED (i.e. would serve a query).
+
+    `_resolved_odoo_key` is imported from `routes_keychain` rather than re-derived. It is the
+    route-level mirror of `TenantRuntime.odoo_source()`, it takes a runtime (not a session), and
+    a second copy of that resolution here would be a copy that drifts — at which point this plane
+    would confidently name the wrong live connector. Reused, not restated.
+    """
+    try:
+        import core.keychain as keychain
+        from routes_keychain import _CONNECTOR_FLAGS_KEY, _resolved_odoo_key
+        entries = keychain.list_entries(rt)
+        locked = not keychain.unlocked()
+        resolved, _flag = _resolved_odoo_key(rt)
+        flags = rt.get(_CONNECTOR_FLAGS_KEY) or {}
+    except Exception as e:                                        # noqa: BLE001
+        return [], f"connectors unreadable ({type(e).__name__})", False
+
+    rows = []
+    if slug == "royal-imports" and os.environ.get("ODOO_URL"):
+        rows.append({"tenant": slug, "key": "odoo-env", "label": "Odoo (environment)",
+                     "type": "odoo", "source": "env", "active": resolved == "env",
+                     "paused": bool((flags.get("odoo-env") or {}).get("paused"))})
+    for e in entries:
+        rows.append({"tenant": slug, "key": e["id"], "label": e["label"], "type": e["type"],
+                     "source": "keychain",
+                     "active": e["type"] == "odoo" and resolved == f"keychain:{e['id']}",
+                     "paused": bool((flags.get(e["id"]) or {}).get("paused"))})
+    return rows, "", locked
+
+
+# ══════════════════════════════════════════════════════════════════════════ automations + cost
+
+#: THE UNIT MODEL, from `ops/provision_automation_cron.py` (its cost note at :25-28 and the
+#: function it actually provisions at :211 / :269). Restated as constants rather than as prose so
+#: the arithmetic below is re-checkable against the thing that was really deployed:
+#: EventBridge Scheduler `rate(15 minutes)` → a 128 MB, 30 s-timeout Lambda that POSTs the tick.
+TICK_CADENCE = "rate(15 minutes)"
+TICK_PER_DAY = 96                       # 1440 / 15
+LAMBDA_MB = 128
+FREE_LAMBDA_REQUESTS = 1_000_000        # AWS always-free, per month
+FREE_SCHEDULER_INVOCATIONS = 14_000_000
+DAYS_PER_MONTH = 30.4
+
+
+def _runs_per_day(cron):
+    """Scheduled runs/day for the five-field crons this product offers, or None.
+
+    ⚠ DELIBERATELY NARROW. It answers exactly the shapes `automation_engine.CRON_PRESETS` can
+    produce (every-N-minutes, hourly, daily, weekly, monthly) and returns None for anything else
+    — an unparsed cadence is reported as "custom", never as a guessed number that would then be
+    multiplied into a cost. A wrong denominator is worse than an absent one.
+
+    ⚠ AND IT IS NOT MEASURED FROM HISTORY, on purpose: `automation_engine.MAX_RUNS` trims run
+    history to 20 entries, so a 15-minute automation retains ~5 hours of it. Deriving runs/day
+    from that window would understate by ~5x. History is reported as what it is — the last N runs.
+    """
+    parts = str(cron or "").split()
+    if len(parts) != 5:
+        return None
+    minute, hour, dom, _mon, dow = parts
+    if minute.startswith("*/") and hour == "*":
+        try:
+            step = int(minute[2:])
+        except ValueError:
+            return None
+        return (1440.0 / step) if step > 0 else None
+    if minute.isdigit() and hour == "*":
+        return 24.0
+    if minute.isdigit() and hour.isdigit():
+        if dom.isdigit():
+            return 1.0 / DAYS_PER_MONTH          # monthly
+        if dow.isdigit():
+            return 1.0 / 7.0                     # weekly
+        return 1.0                               # daily
+    return None
+
+
+def _automation_rows(slug, rt):
+    """A tenant's automations, their schedules, and their retained run history."""
+    try:
+        import automation_engine as engine
+        defs = engine.all_definitions(rt) or {}
+        max_runs = int(getattr(engine, "MAX_RUNS", 20))
+    except Exception as e:                                        # noqa: BLE001
+        return [], f"automations unreadable ({type(e).__name__})", 20
+    rows = []
+    for auto_id, d in sorted(defs.items(), key=lambda kv: (kv[1].get("name") or "").lower()):
+        if not isinstance(d, dict):
+            continue
+        sched = d.get("schedule") or {}
+        status = d.get("status") or {}
+        runs = list(d.get("runs") or [])
+        cron = sched.get("cron") or ""
+        per_day = _runs_per_day(cron) if sched.get("enabled") else 0.0
+        rows.append({
+            "tenant": slug,
+            "id": auto_id,
+            "name": d.get("name") or auto_id,
+            "kind": d.get("kind") or "",
+            "enabled": bool(sched.get("enabled")),
+            "cron": cron,
+            "runsPerDay": round(per_day, 2) if per_day is not None else None,
+            "state": status.get("state") or "idle",
+            "lastRunAt": status.get("lastRunAt") or "",
+            "lastSummary": status.get("lastSummary") or "",
+            # The retained window, named as such — see `_runs_per_day`'s second warning.
+            "runsRetained": len(runs),
+            "failedRetained": sum(1 for r in runs if isinstance(r, dict) and not r.get("ok")),
+            "createdBy": d.get("createdBy") or "",
+            "created": d.get("created") or "",
+        })
+    return rows, "", max_runs
+
+
+def _automation_cost(auto_rows):
+    """The estimated monthly cost of running the automation fleet — and the honest shape of it.
+
+    THE POINT THIS BLOCK EXISTS TO MAKE, which is not intuitive: **the external cron does not
+    scale with automations or tenants.** One EventBridge schedule fires one Lambda, which POSTs
+    one tick, and that tick runs every DUE automation for every tenant (`provision_automation_cron`
+    states this as the reason it stays $0 "at ten tenants"). So the AWS bill is a function of the
+    CADENCE alone — the fleet below adds work inside the API container, which is already paid for.
+
+    WHAT IS NOT COMPUTED HERE, deliberately: Lambda GB-seconds. That needs the real average
+    duration of the function, which only CloudWatch knows; assuming one would be inventing the
+    larger half of the free-tier calculation. `/aws` reports the measured figure when credentials
+    are available, and this block says so rather than filling the gap with a plausible number.
+    """
+    invocations = TICK_PER_DAY * DAYS_PER_MONTH
+    fleet_runs = sum(r["runsPerDay"] or 0 for r in auto_rows if r.get("enabled"))
+    unknown_cadence = sum(1 for r in auto_rows if r.get("enabled") and r.get("runsPerDay") is None)
+    return {
+        "cadence": TICK_CADENCE,
+        "invocationsPerMonth": int(round(invocations)),
+        "freeRequestsPct": round(100.0 * invocations / FREE_LAMBDA_REQUESTS, 3),
+        "freeSchedulerPct": round(100.0 * invocations / FREE_SCHEDULER_INVOCATIONS, 4),
+        "lambdaMb": LAMBDA_MB,
+        "usd": 0.0,
+        "fleetRunsPerDay": round(fleet_runs, 2),
+        "unknownCadence": unknown_cadence,
+        "basis": (
+            f"One EventBridge schedule ({TICK_CADENCE}) fires one {LAMBDA_MB} MB Lambda that "
+            f"POSTs the tick; that ONE tick runs every due automation for every tenant, so the "
+            f"AWS cost is set by the cadence and does not grow with the fleet. "
+            f"{int(round(invocations)):,} invocations/month is "
+            f"{round(100.0 * invocations / FREE_LAMBDA_REQUESTS, 3)}% of the 1,000,000-request "
+            f"always-free tier, so the marginal cost of the automations below is $0.00. "
+            f"Compute (GB-seconds) depends on measured durations and is NOT estimated here — "
+            f"the AWS report reads the real figure when credentials are available."
+        ),
+    }
+
+
+# ════════════════════════════════���═════════════════════════════════════════ the AWS report
+
+#: `ops/aws_usage_report.py`, relative to this file: aios-web/api/ -> repo root -> ops/.
+_AWS_REPORT = Path(__file__).resolve().parents[2] / "ops" / "aws_usage_report.py"
+_AWS_TIMEOUT = 60
+
+
+def _aws_report(days=7):
+    """The AWS usage report as text, or an honest block saying why there is none.
+
+    ⛔ SUBPROCESS, NEVER `import`. Two concrete reasons, both found by reading that file rather
+    than by running it:
+      * it reassigns `sys.stdout` to a UTF-8 wrapper AT MODULE IMPORT (a cp1252 fix for this
+        box) — importing it would mutate the API process's stdout as a side effect;
+      * its `main()` calls `argparse.parse_args()` with no argv, so inside a server it would
+        parse UVICORN's arguments and can `sys.exit(2)` — and `SystemExit` is a `BaseException`,
+        which `except Exception` does not catch. A route that "cannot crash" would crash.
+
+    ⚠ ON THE SPACE THIS IS THE NORMAL PATH, NOT THE ERROR PATH. `deploy_web.py` ships `api/*.py`
+    and `web/`; `ops/` is not in the image, and AWS credentials live in a local `.env` that is
+    never deployed. So the honest block below is what the deployed plane shows, and it is written
+    to be read by an operator as information ("run it here") rather than as a fault.
+    """
+    if not _AWS_REPORT.is_file():
+        return {"available": False, "text": "",
+                "note": ("The AWS usage report is not part of this deployment — `ops/` ships "
+                         "with the repository, not with the container image. Run "
+                         "`python ops/aws_usage_report.py` locally for the live figures.")}
+    try:
+        proc = subprocess.run(
+            [sys.executable, str(_AWS_REPORT), "--days", str(int(days))],
+            capture_output=True, text=True, timeout=_AWS_TIMEOUT,
+            cwd=str(_AWS_REPORT.parent.parent))
+    except subprocess.TimeoutExpired:
+        return {"available": False, "text": "",
+                "note": (f"The AWS report did not answer within {_AWS_TIMEOUT}s — CloudWatch may "
+                         f"be unreachable from here. Nothing was assumed about usage.")}
+    except Exception as e:                                        # noqa: BLE001
+        return {"available": False, "text": "",
+                "note": f"The AWS report could not be run here ({type(e).__name__})."}
+    out = (proc.stdout or "").strip()
+    if proc.returncode != 0 or not out:
+        detail = (proc.stderr or "").strip().splitlines()
+        return {"available": False, "text": out,
+                "note": ("AWS credentials are not available here, or boto3 is not installed — "
+                         "no usage could be read, and none is guessed. "
+                         + (detail[-1][:200] if detail else ""))}
+    return {"available": True, "text": out, "note": ""}
+
+
+# ══════════════════════════════════════════════════════════════════════════ routes
+
+
+@router.get("/overview")
+def overview(session: Session = Depends(padmin_gate)):
+    """THE PLANE'S ONE TABLE: every tenant, with the counts that drill to the rows below.
+
+    Each count is produced by the same collector its `/…` route serves, so the number and its
+    drill-down are one computation projected twice. A subsystem that cannot be read contributes
+    an `errors` entry on that tenant's row and a NULL count — never a zero, which would read as
+    "this customer has no databases" when the truth is "we could not look".
+    """
+    t0 = time.time()
+    all_users = _user_rows()
+    users_by_tenant = {}
+    for u in all_users:
+        users_by_tenant.setdefault(u["tenant"], []).append(u)
+
+    rows = []
+    for t, rt in _scan():
+        slug = t["slug"]
+        row = dict(t)
+        row["users"] = len(users_by_tenant.get(slug, []))
+        row["admins"] = sum(1 for u in users_by_tenant.get(slug, []) if u["role"] == "admin")
+        errors = [t["error"]] if t["error"] else []
+        if rt is None:
+            # An unresolvable tenant still shows its ACCOUNTS (they live in the global registry,
+            # which is readable regardless) — everything tenant-store-shaped is honestly unknown.
+            row.update({"databases": None, "rows": None, "connectors": None,
+                        "automations": None, "keychainLocked": None, "errors": errors})
+            rows.append(row)
+            continue
+        dbs, db_err = _database_rows(slug, rt)
+        conns, conn_err, locked = _connector_rows(slug, rt)
+        autos, auto_err, _mr = _automation_rows(slug, rt)
+        errors += [e for e in (db_err, conn_err, auto_err) if e]
+        row.update({
+            "databases": None if db_err else len(dbs),
+            "rows": None if db_err else sum(d["rowCount"] for d in dbs),
+            "connectors": None if conn_err else len(conns),
+            "connectorsPaused": None if conn_err else sum(1 for c in conns if c["paused"]),
+            "automations": None if auto_err else len(autos),
+            "automationsEnabled": None if auto_err else sum(1 for a in autos if a["enabled"]),
+            "keychainLocked": None if conn_err else locked,
+            "errors": errors,
+        })
+        rows.append(row)
+
+    return {
+        "tenants": rows,
+        "totals": {
+            "tenants": len(rows),
+            # EVERY account, not the sum of the rows: an account whose `tenant` names a slug this
+            # deployment no longer knows belongs in the platform total and would vanish from a
+            # per-row sum. `orphanUsers` names that gap instead of hiding it.
+            "users": len(all_users),
+            "orphanUsers": len(all_users) - sum(r["users"] for r in rows),
+            # Sums SKIP unknowns rather than treating them as 0, and say how many were skipped —
+            # a total that silently absorbs an unreadable tenant is a fabricated total.
+            "databases": sum(r["databases"] or 0 for r in rows),
+            "rows": sum(r["rows"] or 0 for r in rows),
+            "automations": sum(r["automations"] or 0 for r in rows),
+            "unknownTenants": sum(1 for r in rows if r["databases"] is None),
+        },
+        "storeAvailable": bool(_store_ok()),
+        # ⚠ OFFSET-BEARING, and that is not pedantry. The client renders this as "read 2 minutes
+        # ago" via `Date.parse`, which reads a NAIVE stamp as browser-local — so a UTC container
+        # and a US viewer would turn "just now" into "5 hours ago", or into a future date that
+        # renders as "just now" forever. The stamps written by `core.users` carry an offset for
+        # the same reason; anything a browser subtracts from `Date.now()` must say what zone it
+        # is in. `verify_api` asserts the offset so this cannot regress to `strftime`.
+        "generatedAt": _now_iso(),
+        "tookMs": int((time.time() - t0) * 1000),
+    }
+
+
+def _store_ok():
+    try:
+        return store.available()
+    except Exception:
+        return False
+
+
+@router.get("/users")
+def platform_users(tenant: str = "", session: Session = Depends(padmin_gate)):
+    """Every account on the platform, or one tenant's — the drill behind the Users count.
+
+    R4's stamps are the columns that did not exist before this wave: `lastLogin` is written by
+    `routes_auth.login`, `lastActive` by `deps.require_session` (throttled to once an hour per
+    account per process). Absent means never seen, and the pane renders it as "never".
+    """
+    rows = _user_rows(tenant)
+    return {"users": rows, "count": len(rows),
+            "stampsNote": ("Login and activity stamps started with this release — accounts that "
+                           "have not signed in since show no date rather than an invented one. "
+                           "Activity is recorded at most once an hour per account.")}
+
+
+@router.get("/databases")
+def platform_databases(tenant: str = "", session: Session = Depends(padmin_gate)):
+    """Every tenant's user-created databases and row counts — the drill behind Databases/Rows."""
+    out, errors = [], {}
+    for t, rt in _scan(tenant):
+        slug = t["slug"]
+        if rt is None:
+            errors[slug] = t["error"]
+            continue
+        rows, err = _database_rows(slug, rt)
+        if err:
+            errors[slug] = err
+            continue
+        out += rows
+    return {"databases": out, "count": len(out),
+            "rows": sum(d["rowCount"] for d in out), "errors": errors}
+
+
+@router.get("/connectors")
+def platform_connectors(tenant: str = "", session: Session = Depends(padmin_gate)):
+    """Every tenant's data sources, which one is live, and which are paused.
+
+    METADATA ONLY — `keychain.list_entries` never decrypts, so no credential, and no masked
+    preview either: a platform operator needs to know a source EXISTS and whether it serves, not
+    what the secret looks like. The tenant's own admin surface is where previews belong.
+    """
+    out, errors, locked_any = [], {}, {}
+    for t, rt in _scan(tenant):
+        slug = t["slug"]
+        if rt is None:
+            errors[slug] = t["error"]
+            continue
+        rows, err, locked = _connector_rows(slug, rt)
+        if err:
+            errors[slug] = err
+            continue
+        locked_any[slug] = locked
+        out += rows
+    return {"connectors": out, "count": len(out), "keychainLocked": locked_any,
+            "errors": errors,
+            "note": ("A locked keychain means this container has no `AIOS_KEYCHAIN_KEY` — stored "
+                     "credentials cannot be read, so a tenant's sources fail closed rather than "
+                     "falling back to anyone else's.")}
+
+
+@router.get("/automations")
+def platform_automations(tenant: str = "", session: Session = Depends(padmin_gate)):
+    """Every tenant's automations, their schedules and run history, plus the fleet cost model."""
+    out, errors, retained = [], {}, 20
+    for t, rt in _scan(tenant):
+        slug = t["slug"]
+        if rt is None:
+            errors[slug] = t["error"]
+            continue
+        rows, err, max_runs = _automation_rows(slug, rt)
+        if err:
+            errors[slug] = err
+            continue
+        retained = max_runs
+        out += rows
+    return {"automations": out, "count": len(out),
+            "enabled": sum(1 for a in out if a["enabled"]),
+            "historyRetained": retained,
+            "cost": _automation_cost(out), "errors": errors,
+            "tickEnabled": os.environ.get("AIOS_AUTOMATIONS") == "1"}
+
+
+@router.get("/aws")
+def platform_aws(days: int = 7, session: Session = Depends(padmin_gate)):
+    """The AWS cron's usage report, verbatim, or an honest note explaining its absence."""
+    days = max(1, min(int(days or 7), 90))
+    return {"days": days, "report": _aws_report(days)}
+
+
+@router.get("/releases")
+def platform_releases(session: Session = Depends(padmin_gate)):
+    """⭐ WAVE 20 (owner item 12, ruling R6) — WHAT IS RUNNING WHERE, and what else could be.
+
+    Owner: *"Make this part of the deploy skill. Also ability to revert to any version we want.
+    Make sure App versioning is something that our company admin (loopable, non-tenant) can
+    easily see."* This is the SEEING half; promoting stays a CLI command by R6, so nothing here
+    writes and no web session can move production.
+
+    ⛔ THE HUB READS LIVE IN `core/releases.py`, NOT HERE. `ops/verify_portability.py` B2 forbids
+    the HuggingFace SDK anywhere under `aios-web/api/` — the API process is host-agnostic by
+    design — and it caught this endpoint's first draft doing exactly that. Same delegation shape
+    as `routes_assets` -> `core/assets.py`.
+    """
+    import core.releases as releases
+
+    return {"here": os.environ.get("AIOS_VERSION") or "unknown",
+            "environments": releases.environments(),
+            "releases": releases.history(),
+            # The runbook, in the payload, because the panel is read-only BY DESIGN and a user
+            # looking at it is exactly the person who needs to know how to move a version.
+            "promote": "python aios-web/deploy_web.py --promote=vN   (or --promote=staging)"}

api/routes_products.py

@@ -1,294 +1,294 @@
-"""routes_products.py — the PRODUCT table's read seam (wave 15 item 9/10, contract C-TOPIC).
-
-The proof that C-TOPIC's bet is real: **a second table object is a pool module plus a route, not
-a second component tree**. Everything structural here is borrowed rather than re-implemented —
-the permission wall (`core.perm_scope`), the row builder (`aios_grid.rows_from_pool`), the
-scope-keyed stale-while-refresh cache (`scope_cache`), the error shape, the module gate.
-
-Landed nav-less in wave 15 ON PURPOSE (no registry row, so no user could navigate to a
-half-built surface while the server half hardened); wave 16 shipped the `product_data`
-registry row, the client `topic` prop and the write path, so the surface has been REACHABLE
-from the nav since — this header stayed stale until 2026-08-04 (the wave-18 debt sweep) and
-cost readers a false "you can't get there from here".
-
-Wave 16 (C-TOPIC's second half): the WRITE PATH exists now, and it is exactly what the wave-15
-header demanded before one could — its OWN table workspace bucket
-(`modules.product_data.TABLE_OPS`, store key 'product_table_workspace') and its own event
-validation (the events route builds the ctx over the PRODUCT field contract + product pids +
-the product ops). ⛔ The separate bucket is load-bearing, not tidy: product pids are CRC32
-hashes and customer pids are Odoo partner ids — one shared overlay bucket and a hash collision
-silently writes a product note onto somebody's customer.
-"""
-import time
-
-from fastapi import Body, Depends
-
-from fastapi import APIRouter
-
-import scope_cache
-from deps import Session, err, module_gate
-
-router = APIRouter(prefix="/api/v1")
-
-#: The registry key this surface WILL carry. The gate is live now even though the nav is not, so
-#: the day the registry row appears the wall is already the one that was tested.
-MODULE = "product_data"
-
-_CACHE_TTL = 900
-
-
-def _pool_for(rt, team_id):
-    """The cached SKU pool for one scope. Same stale-while-refresh discipline as the customer
-    pool: only a scope's FIRST-ever build blocks, and the cache key is the SCOPE, never the user
-    — the customer route learned that the hard way (a per-user payload cached on a scope key
-    served one user's private columns to another)."""
-    import modules.product_data as pd
-
-    # ⚠ Signature is (cache, key, ttl, build) — the wave-15 version passed `ttl=` as a keyword
-    # after the build lambda and DIED on every call ("multiple values for 'ttl'"). Latent until
-    # wave 16 because nothing drove this route end-to-end: verify_perm_scope's section H stubs
-    # the pool a layer below. verify_api's W16 section now exercises the real call.
-    key = ("product_pool", team_id)
-
-    # ⭐ D-10 (wave 24) — THE PRODUCT POOL HONOURS THE CONNECTOR PAUSE. It did not, and that was
-    # a shipped defect on a live surface: the CUSTOMER pool got this guard at DEBT-2 and its
-    # sibling — written from the same template, four files away — never did. So pausing Odoo
-    # froze the Customer grid and the Product grid kept reading live, with the Settings toggle
-    # reporting success. Sibling caches diverge exactly this way and nothing greps for
-    # "the other one".
-    #
-    # ⚠ NO SNAPSHOT LEG, and that is the honest difference from the customer path rather than an
-    # omission: `save_pool_snapshots` persists the `odoo_pool` scopes only — there is no product
-    # snapshot bucket to serve. So this serves the in-process copy AT ANY AGE, and answers 503
-    # naming the pause when there is none. Minting a product snapshot here would be a new
-    # persistence format at a wave tail; refusing with a sentence is the answer the user can act
-    # on, and it is the same 503 the customer path already gives for an unsnapshotted scope.
-    import routes_keychain
-    if routes_keychain.odoo_paused(rt):
-        hit = rt.pool_cache.get(key)
-        if hit:
-            return hit[1]
-        raise err(503, "connector_paused",
-                  "this data source is paused and nothing has been read since — "
-                  "an admin can resume it under Settings → Connectors")
-
-    return scope_cache.get(rt.pool_cache, key, _CACHE_TTL,
-                           lambda: pd.pool(team_id=team_id))
-
-
-def scoped_pool(session: Session):
-    """`(pids, team_id, rows_src, fields_base)` — THE PRODUCT WALL, on its own.
-
-    Extracted from `product_assembly` (wave 19, item 12) so a caller that needs only "which
-    products may this session touch" — record comments, say — asks the SAME question in the same
-    order rather than re-deriving it: pool scope from the permanent filter, rows, THEN the row
-    wall, THEN the pids. Re-deriving it is how a second wall drifts from the first, and the
-    walls are the whole point of this route.
-
-    ⚠ The caller is responsible for the GRANT (`session.require(MODULE)`); this is the row half.
-    """
-    import core.perm_scope as perm_scope
-
-    team_id, _agent = perm_scope.derive_pool_scope(session.user, MODULE)
-    try:
-        rows_src = _pool_for(session.runtime, team_id)
-    except Exception as e:
-        raise err(503, "pool_unavailable",
-                  f"the product catalogue could not be built — {str(e)[:160]}")
-    fields_base = pd_fields(consolidated=team_id is None)
-    # The SAME wall the customer assembly applies, in the same order: rows first (before pids
-    # are taken, so an out-of-filter row never enters allowed_pids), then the field closure,
-    # then the values stripped from the rows as well as the field list.
-    rows_src = perm_scope.apply_row_scope(rows_src, session.user, MODULE, fields_base)
-    pids = frozenset(r["pid"] for r in rows_src if r.get("pid") is not None)
-    return pids, team_id, rows_src, fields_base
-
-
-def product_assembly(session: Session, scope: str = "product", storage_key: str = "",
-                     consume_corrections: bool = True):
-    """The product topic's mirror of `routes_customers.grid_assembly` — SAME g-dict keys, so
-    the /workspace and events routes consume either interchangeably.
-
-    One deliberate absence, a topic fact rather than a gap:
-      * `measures`/`measure_sets` are EMPTY — `core.measure_resolve` is CUSTOMER-grain (the
-        C-TOPIC v1 descope, booked in the wave doc); the events ctx therefore refuses measure
-        creates on this surface, which is the correct fail-closed shape.
-
-    ⭐ WAVE 19 / R9 — `lists` IS NO LONGER EMPTY. Wave 16 passed `with_cohorts=False` because
-    there was one customer-keyed cohort bucket and product pids are CRC32 hashes of SKU codes;
-    intersecting the two id spaces would have printed a plausible, meaningless member count. The
-    owner's ruling is that a cohort belongs to its database, so `modules.cohort` grew a bucket
-    per topic and the product surface reads `product_cohorts` — ids from this pool, resolved
-    against this pool. `derived` carries their membership cells (the Cohorts column) for the same
-    reason it does on the customer surface; the measure half of that channel stays empty.
-    """
-    import aios_grid
-    import core.perm_scope as perm_scope
-    import modules.product_data as pd
-    from core import grid_events
-
-    pids, team_id, rows_src, fields_base = scoped_pool(session)
-
-    ctx = grid_events.EventCtx(
-        uname=session.uname, allowed_pids=pids, fields=[],
-        hidden_keys=perm_scope.hidden_keys(session.user, MODULE, fields_base),
-        admin=session.admin, fallback_ws=None, seen_ids={},
-        scope_key="product", table=pd.TABLE_OPS)
-    ws = grid_events.table_workspace(ctx, allowed_pids=pids,
-                                     consume_corrections=consume_corrections)
-    workspace, fields, views, lists = aios_grid.workspace_wire(
-        ws, session.uname, set(pids), defs={}, scope_key=scope, storage_key=storage_key,
-        fields_base=fields_base)
-
-    hidden = perm_scope.hidden_keys(session.user, MODULE, fields)
-    if hidden:
-        fields = [f for f in fields if f.get("key") not in hidden]
-        rows_src = [perm_scope.strip_row(r, hidden) for r in rows_src]
-
-    return {"rows_src": rows_src, "pids": pids, "ws": ws, "workspace": workspace,
-            "fields": fields, "views": views, "lists": lists,
-            # R9: the Cohorts column's cells, built from THIS topic's lists. Same read-only
-            # `derived` channel the customer assembly uses — the measure half stays empty.
-            "derived": aios_grid.cohort_cells(lists),
-            "measures": [], "measure_sets": {}, "today": time.strftime("%Y-%m-%d"),
-            "team_id": team_id}
-
-
-@router.get("/products")
-def products(session: Session = Depends(module_gate(MODULE))):
-    """The product table for this session's scope — the /customers envelope byte-for-byte
-    (`{fields, rows, today, pulled_at}`) plus two additive keys (`identity`, `scope`).
-
-    The BU scope is DERIVED FROM THE PERMANENT FILTER (`perm_scope.derive_pool_scope`), exactly
-    as the customer route derives it — and for the same reason, which is worth restating because
-    it is the wave's central lesson: `team_id` shapes the revenue VALUES on each row, so a BU
-    enforced as a post-filter yields a correct row list carrying both units' numbers.
-    """
-    import aios_grid
-
-    g = product_assembly(session)
-    rows = _seed_image(aios_grid.rows_from_pool(
-        g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"]),
-        g["fields"])
-    return {"fields": g["fields"], "rows": rows,
-            "today": g["today"], "pulled_at": time.strftime("%Y-%m-%d %H:%M"),
-            "identity": {"pid": "pid", "businessKey": "code"},
-            "scope": {"team_id": g["team_id"], "consolidated": g["team_id"] is None}}
-
-
-@router.patch("/products/{pid}")
-def patch_product(pid: int, body: dict = Body(default=None),
-                  session: Session = Depends(module_gate(MODULE))):
-    """Write the product table's EDITABLE overlay stratum — the customers PATCH, on the product
-    topic's ctx. Routed through `core.grid_events.handle_one` so the per-key `permissions.edit`
-    wall, the pid wall and the truncation rules stay ONE implementation; the ctx's `table` ops
-    aim the write at the PRODUCT bucket."""
-    import modules.product_data as pd
-    from core import grid_events
-
-    updates = dict(body or {})
-    if not updates:
-        raise err(400, "empty_patch", "no fields to update")
-    g = product_assembly(session, consume_corrections=False)
-    if pid not in g["pids"]:
-        # 403, not 404 — the code may exist; it is simply not in this session's catalogue.
-        raise err(403, "out_of_scope", "that product is not in your catalogue")
-    import core.perm_scope as perm_scope
-
-    ctx = grid_events.EventCtx(
-        uname=session.uname, allowed_pids=g["pids"], fields=g["fields"],
-        admin=session.admin, fallback_ws=None, seen_ids={},
-        hidden_keys=perm_scope.hidden_keys(
-            session.user, MODULE, pd_fields(consolidated=g["team_id"] is None)),
-        scope_key="product", table=pd.TABLE_OPS)
-    try:
-        grid_events.handle_one(
-            {"id": f"patch:product:{pid}:{time.time_ns()}", "type": "overlay_patch",
-             "pid": pid, "updates": updates}, ctx)
-    except grid_events.StoreUnavailable:
-        raise err(503, "store_unavailable",
-                  "the tenant store is unavailable — your change was not saved")
-
-    # What actually landed, read back from the PRODUCT bucket rather than echoed from the
-    # request: a refused key or a truncated value must not be reported as accepted.
-    stored = (grid_events.table_workspace(ctx, allowed_pids=None)
-              .get("overlays") or {}).get(str(pid)) or {}
-    accepted = {k: stored.get(k) for k in updates if k in stored}
-    refused = sorted(k for k in updates
-                     if k not in accepted or stored.get(k) != str(updates[k]))
-    out = {"pid": pid, "updates": accepted}
-    if refused:
-        out["refused"] = refused
-    return out
-
-
-#: ⭐ WAVE 19 R7 — the RI Product table's built-in picture column. `source: 'overlay'` (editable,
-#: so a user can upload a different shot for one SKU) with its DEFAULT supplied per render from
-#: the row's `code` — see `_seed_image`. A stamped overlay value would have been the other way to
-#: do it and it is the wrong one twice over: it is a 1,142-row migration that has to be right
-#: once, and it FREEZES the code into the cell, so a re-coded SKU would keep pointing at the old
-#: master with nothing saying why.
-PRODUCT_IMAGE_KEY = "image"
-
-
-def _seed_image(rows, fields):
-    """R7's "auto-seeded from SKU `code`", as a per-render DEFAULT rather than stored data.
-
-    Royal's 1,142 masters are named for `default_code`, so an untouched product row already names
-    its own picture; this is what makes them appear with nothing uploaded. A user's own value is
-    NON-EMPTY and therefore wins — the fallback only fills a cell nobody has set.
-
-    ⚠ Clearing the cell restores the SKU's own picture rather than blanking it, and that is the
-    documented meaning of empty on this column ("no override"). A product with no master on file
-    still shows an empty frame, because the reference resolves to a 404 — the honest outcome, and
-    the record modal names the failing reference in words.
-
-    ⛔ GATED ON THE SERVED FIELD LIST, and that is C-PERM, not tidiness. `product_assembly` strips
-    a hidden field from BOTH wires — the field list and the row payload — because narrowing only
-    the first leaves the value sitting in the second where anything can read it. An unconditional
-    seed would put the key straight back onto every row AFTER that strip, re-creating exactly the
-    shape the rule forbids. (The value here is the visible `code`, so nothing new escapes today;
-    the contract is the point, and a future non-code default would escape.)
-
-    ⚠ STATED CONSEQUENCE: hiding `code` blanks this column, because the reference IS the code.
-    That coupling is inherent to seeding from a business key, not a bug — and it fails in the safe
-    direction (an empty frame, never another row's picture).
-    """
-    if not any(f.get("key") == PRODUCT_IMAGE_KEY for f in fields or ()):
-        return rows
-    for row in rows:
-        if not row.get(PRODUCT_IMAGE_KEY):
-            row[PRODUCT_IMAGE_KEY] = row.get("code") or ""
-    return rows
-
-
-def pd_fields(consolidated=True):
-    """The product field contract, minus the CONSOLIDATED-only columns when the caller is scoped.
-
-    ⛔ The omission is the SCOPE RULE, not a display preference (see `modules/product_data`
-    decision 2): `inventory.sku_inventory` is brand-independent, so serving those columns to a
-    BU-scoped caller would put company-wide stock beside BU-shaped revenue in one row. A column
-    that is absent asks a question; one that is silently company-wide answers a different one.
-    """
-    import json
-    from pathlib import Path
-
-    import aios_grid
-
-    doc = json.loads((Path(aios_grid.__file__).resolve().parent /
-                      "aios_grid_fields.json").read_text(encoding="utf-8"))
-    fields = list((doc.get("product_data") or {}).get("fields") or [])
-    # R7: the Image column is BUILT IN on this table, injected here rather than added to
-    # `aios_grid_fields.json`. That file is the ODOO-SOURCED contract — every key in it is a
-    # column `modules.product_data.pool()` reads off a SKU — and this one is neither read from
-    # Odoo nor written to it. Injected after the JSON so the canonical file stays the answer to
-    # "what does Odoo give us", which is the question `verify_fields_contract` referees.
-    fields = fields + [{
-        "key": PRODUCT_IMAGE_KEY, "label": "Image", "type": "image", "source": "overlay",
-        "note": "The product's picture. Empty shows the SKU's own master image; upload one "
-                "from the record panel to override it.",
-    }]
-    if consolidated:
-        return fields
-    import modules.product_data as pd
-    return [f for f in fields if f.get("key") not in pd.CONSOLIDATED_ONLY]
+"""routes_products.py — the PRODUCT table's read seam (wave 15 item 9/10, contract C-TOPIC).
+
+The proof that C-TOPIC's bet is real: **a second table object is a pool module plus a route, not
+a second component tree**. Everything structural here is borrowed rather than re-implemented —
+the permission wall (`core.perm_scope`), the row builder (`aios_grid.rows_from_pool`), the
+scope-keyed stale-while-refresh cache (`scope_cache`), the error shape, the module gate.
+
+Landed nav-less in wave 15 ON PURPOSE (no registry row, so no user could navigate to a
+half-built surface while the server half hardened); wave 16 shipped the `product_data`
+registry row, the client `topic` prop and the write path, so the surface has been REACHABLE
+from the nav since — this header stayed stale until 2026-08-04 (the wave-18 debt sweep) and
+cost readers a false "you can't get there from here".
+
+Wave 16 (C-TOPIC's second half): the WRITE PATH exists now, and it is exactly what the wave-15
+header demanded before one could — its OWN table workspace bucket
+(`modules.product_data.TABLE_OPS`, store key 'product_table_workspace') and its own event
+validation (the events route builds the ctx over the PRODUCT field contract + product pids +
+the product ops). ⛔ The separate bucket is load-bearing, not tidy: product pids are CRC32
+hashes and customer pids are Odoo partner ids — one shared overlay bucket and a hash collision
+silently writes a product note onto somebody's customer.
+"""
+import time
+
+from fastapi import Body, Depends
+
+from fastapi import APIRouter
+
+import scope_cache
+from deps import Session, err, module_gate
+
+router = APIRouter(prefix="/api/v1")
+
+#: The registry key this surface WILL carry. The gate is live now even though the nav is not, so
+#: the day the registry row appears the wall is already the one that was tested.
+MODULE = "product_data"
+
+_CACHE_TTL = 900
+
+
+def _pool_for(rt, team_id):
+    """The cached SKU pool for one scope. Same stale-while-refresh discipline as the customer
+    pool: only a scope's FIRST-ever build blocks, and the cache key is the SCOPE, never the user
+    — the customer route learned that the hard way (a per-user payload cached on a scope key
+    served one user's private columns to another)."""
+    import modules.product_data as pd
+
+    # ⚠ Signature is (cache, key, ttl, build) — the wave-15 version passed `ttl=` as a keyword
+    # after the build lambda and DIED on every call ("multiple values for 'ttl'"). Latent until
+    # wave 16 because nothing drove this route end-to-end: verify_perm_scope's section H stubs
+    # the pool a layer below. verify_api's W16 section now exercises the real call.
+    key = ("product_pool", team_id)
+
+    # ⭐ D-10 (wave 24) — THE PRODUCT POOL HONOURS THE CONNECTOR PAUSE. It did not, and that was
+    # a shipped defect on a live surface: the CUSTOMER pool got this guard at DEBT-2 and its
+    # sibling — written from the same template, four files away — never did. So pausing Odoo
+    # froze the Customer grid and the Product grid kept reading live, with the Settings toggle
+    # reporting success. Sibling caches diverge exactly this way and nothing greps for
+    # "the other one".
+    #
+    # ⚠ NO SNAPSHOT LEG, and that is the honest difference from the customer path rather than an
+    # omission: `save_pool_snapshots` persists the `odoo_pool` scopes only — there is no product
+    # snapshot bucket to serve. So this serves the in-process copy AT ANY AGE, and answers 503
+    # naming the pause when there is none. Minting a product snapshot here would be a new
+    # persistence format at a wave tail; refusing with a sentence is the answer the user can act
+    # on, and it is the same 503 the customer path already gives for an unsnapshotted scope.
+    import routes_keychain
+    if routes_keychain.odoo_paused(rt):
+        hit = rt.pool_cache.get(key)
+        if hit:
+            return hit[1]
+        raise err(503, "connector_paused",
+                  "this data source is paused and nothing has been read since — "
+                  "an admin can resume it under Settings → Connectors")
+
+    return scope_cache.get(rt.pool_cache, key, _CACHE_TTL,
+                           lambda: pd.pool(team_id=team_id))
+
+
+def scoped_pool(session: Session):
+    """`(pids, team_id, rows_src, fields_base)` — THE PRODUCT WALL, on its own.
+
+    Extracted from `product_assembly` (wave 19, item 12) so a caller that needs only "which
+    products may this session touch" — record comments, say — asks the SAME question in the same
+    order rather than re-deriving it: pool scope from the permanent filter, rows, THEN the row
+    wall, THEN the pids. Re-deriving it is how a second wall drifts from the first, and the
+    walls are the whole point of this route.
+
+    ⚠ The caller is responsible for the GRANT (`session.require(MODULE)`); this is the row half.
+    """
+    import core.perm_scope as perm_scope
+
+    team_id, _agent = perm_scope.derive_pool_scope(session.user, MODULE)
+    try:
+        rows_src = _pool_for(session.runtime, team_id)
+    except Exception as e:
+        raise err(503, "pool_unavailable",
+                  f"the product catalogue could not be built — {str(e)[:160]}")
+    fields_base = pd_fields(consolidated=team_id is None)
+    # The SAME wall the customer assembly applies, in the same order: rows first (before pids
+    # are taken, so an out-of-filter row never enters allowed_pids), then the field closure,
+    # then the values stripped from the rows as well as the field list.
+    rows_src = perm_scope.apply_row_scope(rows_src, session.user, MODULE, fields_base)
+    pids = frozenset(r["pid"] for r in rows_src if r.get("pid") is not None)
+    return pids, team_id, rows_src, fields_base
+
+
+def product_assembly(session: Session, scope: str = "product", storage_key: str = "",
+                     consume_corrections: bool = True):
+    """The product topic's mirror of `routes_customers.grid_assembly` — SAME g-dict keys, so
+    the /workspace and events routes consume either interchangeably.
+
+    One deliberate absence, a topic fact rather than a gap:
+      * `measures`/`measure_sets` are EMPTY — `core.measure_resolve` is CUSTOMER-grain (the
+        C-TOPIC v1 descope, booked in the wave doc); the events ctx therefore refuses measure
+        creates on this surface, which is the correct fail-closed shape.
+
+    ⭐ WAVE 19 / R9 — `lists` IS NO LONGER EMPTY. Wave 16 passed `with_cohorts=False` because
+    there was one customer-keyed cohort bucket and product pids are CRC32 hashes of SKU codes;
+    intersecting the two id spaces would have printed a plausible, meaningless member count. The
+    owner's ruling is that a cohort belongs to its database, so `modules.cohort` grew a bucket
+    per topic and the product surface reads `product_cohorts` — ids from this pool, resolved
+    against this pool. `derived` carries their membership cells (the Cohorts column) for the same
+    reason it does on the customer surface; the measure half of that channel stays empty.
+    """
+    import aios_grid
+    import core.perm_scope as perm_scope
+    import modules.product_data as pd
+    from core import grid_events
+
+    pids, team_id, rows_src, fields_base = scoped_pool(session)
+
+    ctx = grid_events.EventCtx(
+        uname=session.uname, allowed_pids=pids, fields=[],
+        hidden_keys=perm_scope.hidden_keys(session.user, MODULE, fields_base),
+        admin=session.admin, fallback_ws=None, seen_ids={},
+        scope_key="product", table=pd.TABLE_OPS)
+    ws = grid_events.table_workspace(ctx, allowed_pids=pids,
+                                     consume_corrections=consume_corrections)
+    workspace, fields, views, lists = aios_grid.workspace_wire(
+        ws, session.uname, set(pids), defs={}, scope_key=scope, storage_key=storage_key,
+        fields_base=fields_base)
+
+    hidden = perm_scope.hidden_keys(session.user, MODULE, fields)
+    if hidden:
+        fields = [f for f in fields if f.get("key") not in hidden]
+        rows_src = [perm_scope.strip_row(r, hidden) for r in rows_src]
+
+    return {"rows_src": rows_src, "pids": pids, "ws": ws, "workspace": workspace,
+            "fields": fields, "views": views, "lists": lists,
+            # R9: the Cohorts column's cells, built from THIS topic's lists. Same read-only
+            # `derived` channel the customer assembly uses — the measure half stays empty.
+            "derived": aios_grid.cohort_cells(lists),
+            "measures": [], "measure_sets": {}, "today": time.strftime("%Y-%m-%d"),
+            "team_id": team_id}
+
+
+@router.get("/products")
+def products(session: Session = Depends(module_gate(MODULE))):
+    """The product table for this session's scope — the /customers envelope byte-for-byte
+    (`{fields, rows, today, pulled_at}`) plus two additive keys (`identity`, `scope`).
+
+    The BU scope is DERIVED FROM THE PERMANENT FILTER (`perm_scope.derive_pool_scope`), exactly
+    as the customer route derives it — and for the same reason, which is worth restating because
+    it is the wave's central lesson: `team_id` shapes the revenue VALUES on each row, so a BU
+    enforced as a post-filter yields a correct row list carrying both units' numbers.
+    """
+    import aios_grid
+
+    g = product_assembly(session)
+    rows = _seed_image(aios_grid.rows_from_pool(
+        g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"]),
+        g["fields"])
+    return {"fields": g["fields"], "rows": rows,
+            "today": g["today"], "pulled_at": time.strftime("%Y-%m-%d %H:%M"),
+            "identity": {"pid": "pid", "businessKey": "code"},
+            "scope": {"team_id": g["team_id"], "consolidated": g["team_id"] is None}}
+
+
+@router.patch("/products/{pid}")
+def patch_product(pid: int, body: dict = Body(default=None),
+                  session: Session = Depends(module_gate(MODULE))):
+    """Write the product table's EDITABLE overlay stratum — the customers PATCH, on the product
+    topic's ctx. Routed through `core.grid_events.handle_one` so the per-key `permissions.edit`
+    wall, the pid wall and the truncation rules stay ONE implementation; the ctx's `table` ops
+    aim the write at the PRODUCT bucket."""
+    import modules.product_data as pd
+    from core import grid_events
+
+    updates = dict(body or {})
+    if not updates:
+        raise err(400, "empty_patch", "no fields to update")
+    g = product_assembly(session, consume_corrections=False)
+    if pid not in g["pids"]:
+        # 403, not 404 — the code may exist; it is simply not in this session's catalogue.
+        raise err(403, "out_of_scope", "that product is not in your catalogue")
+    import core.perm_scope as perm_scope
+
+    ctx = grid_events.EventCtx(
+        uname=session.uname, allowed_pids=g["pids"], fields=g["fields"],
+        admin=session.admin, fallback_ws=None, seen_ids={},
+        hidden_keys=perm_scope.hidden_keys(
+            session.user, MODULE, pd_fields(consolidated=g["team_id"] is None)),
+        scope_key="product", table=pd.TABLE_OPS)
+    try:
+        grid_events.handle_one(
+            {"id": f"patch:product:{pid}:{time.time_ns()}", "type": "overlay_patch",
+             "pid": pid, "updates": updates}, ctx)
+    except grid_events.StoreUnavailable:
+        raise err(503, "store_unavailable",
+                  "the tenant store is unavailable — your change was not saved")
+
+    # What actually landed, read back from the PRODUCT bucket rather than echoed from the
+    # request: a refused key or a truncated value must not be reported as accepted.
+    stored = (grid_events.table_workspace(ctx, allowed_pids=None)
+              .get("overlays") or {}).get(str(pid)) or {}
+    accepted = {k: stored.get(k) for k in updates if k in stored}
+    refused = sorted(k for k in updates
+                     if k not in accepted or stored.get(k) != str(updates[k]))
+    out = {"pid": pid, "updates": accepted}
+    if refused:
+        out["refused"] = refused
+    return out
+
+
+#: ⭐ WAVE 19 R7 — the RI Product table's built-in picture column. `source: 'overlay'` (editable,
+#: so a user can upload a different shot for one SKU) with its DEFAULT supplied per render from
+#: the row's `code` — see `_seed_image`. A stamped overlay value would have been the other way to
+#: do it and it is the wrong one twice over: it is a 1,142-row migration that has to be right
+#: once, and it FREEZES the code into the cell, so a re-coded SKU would keep pointing at the old
+#: master with nothing saying why.
+PRODUCT_IMAGE_KEY = "image"
+
+
+def _seed_image(rows, fields):
+    """R7's "auto-seeded from SKU `code`", as a per-render DEFAULT rather than stored data.
+
+    Royal's 1,142 masters are named for `default_code`, so an untouched product row already names
+    its own picture; this is what makes them appear with nothing uploaded. A user's own value is
+    NON-EMPTY and therefore wins — the fallback only fills a cell nobody has set.
+
+    ⚠ Clearing the cell restores the SKU's own picture rather than blanking it, and that is the
+    documented meaning of empty on this column ("no override"). A product with no master on file
+    still shows an empty frame, because the reference resolves to a 404 — the honest outcome, and
+    the record modal names the failing reference in words.
+
+    ⛔ GATED ON THE SERVED FIELD LIST, and that is C-PERM, not tidiness. `product_assembly` strips
+    a hidden field from BOTH wires — the field list and the row payload — because narrowing only
+    the first leaves the value sitting in the second where anything can read it. An unconditional
+    seed would put the key straight back onto every row AFTER that strip, re-creating exactly the
+    shape the rule forbids. (The value here is the visible `code`, so nothing new escapes today;
+    the contract is the point, and a future non-code default would escape.)
+
+    ⚠ STATED CONSEQUENCE: hiding `code` blanks this column, because the reference IS the code.
+    That coupling is inherent to seeding from a business key, not a bug — and it fails in the safe
+    direction (an empty frame, never another row's picture).
+    """
+    if not any(f.get("key") == PRODUCT_IMAGE_KEY for f in fields or ()):
+        return rows
+    for row in rows:
+        if not row.get(PRODUCT_IMAGE_KEY):
+            row[PRODUCT_IMAGE_KEY] = row.get("code") or ""
+    return rows
+
+
+def pd_fields(consolidated=True):
+    """The product field contract, minus the CONSOLIDATED-only columns when the caller is scoped.
+
+    ⛔ The omission is the SCOPE RULE, not a display preference (see `modules/product_data`
+    decision 2): `inventory.sku_inventory` is brand-independent, so serving those columns to a
+    BU-scoped caller would put company-wide stock beside BU-shaped revenue in one row. A column
+    that is absent asks a question; one that is silently company-wide answers a different one.
+    """
+    import json
+    from pathlib import Path
+
+    import aios_grid
+
+    doc = json.loads((Path(aios_grid.__file__).resolve().parent /
+                      "aios_grid_fields.json").read_text(encoding="utf-8"))
+    fields = list((doc.get("product_data") or {}).get("fields") or [])
+    # R7: the Image column is BUILT IN on this table, injected here rather than added to
+    # `aios_grid_fields.json`. That file is the ODOO-SOURCED contract — every key in it is a
+    # column `modules.product_data.pool()` reads off a SKU — and this one is neither read from
+    # Odoo nor written to it. Injected after the JSON so the canonical file stays the answer to
+    # "what does Odoo give us", which is the question `verify_fields_contract` referees.
+    fields = fields + [{
+        "key": PRODUCT_IMAGE_KEY, "label": "Image", "type": "image", "source": "overlay",
+        "note": "The product's picture. Empty shows the SKU's own master image; upload one "
+                "from the record panel to override it.",
+    }]
+    if consolidated:
+        return fields
+    import modules.product_data as pd
+    return [f for f in fields if f.get("key") not in pd.CONSOLIDATED_ONLY]

platform/core/links.py

@@ -1,59 +1,59 @@
-"""Deep links into the app — ?page=<key>&entity=<kind>:<id>&src=<source>.
-
-The app (app.py) consumes these params once per session right after login and routes to the page,
-opening the entity drawer when an entity is present. Digest/alert/mention emails build their links
-here so every emailed number lands the reader on the exact row it came from. `src` tags where the
-click came from (digest / alert / mention) — the app logs it as the click-through read receipt.
-"""
-import os
-import sys
-from urllib.parse import quote
-
-#: ⛔ THE ONE HOST LITERAL LEFT IN THE RUNTIME PATH, and it is a MIGRATION HAZARD — named here
-#: rather than buried in a default argument, because the day we change hosts this is what silently
-#: keeps mailing customers a link to the DEAD one. Found by `ops/verify_portability.py` on its
-#: first run (2026-07-30).
-#:
-#: Why it is still here instead of raising: `deeplink()` has exactly one family of callers
-#: (`modules/digest.py`, 7 sites, all building email hrefs), `DIGEST_ENABLED` defaults to ON, and
-#: no deploy sets `APP_BASE_URL` today — so refusing to guess would break a LIVE feature to fix a
-#: latent one. Instead: both deploy scripts now push `APP_BASE_URL`, which makes the fallback
-#: unreachable in a deployed environment, and reaching it prints an operator warning.
-#:
-#: ⇒ EXIT CONDITION for this constant: once a deploy has set `APP_BASE_URL` and it is confirmed
-#: present in the running environment, delete the fallback and let `deeplink()` raise instead. It
-#: is declared in the portability gate's RESIDUALS so the gate reports it honestly rather than
-#: reporting green over it.
-_LEGACY_HF_FALLBACK = 'https://royal-imports-cfo-os.hf.space'
-
-BASE_URL = (os.environ.get('APP_BASE_URL') or _LEGACY_HF_FALLBACK).rstrip('/')
-
-#: Warned LAZILY and ONCE — at the first link actually built, not at import. An import-time print
-#: fires in every gate, every subprocess and every unit test that so much as touches `core`, which
-#: is how a real warning becomes noise nobody reads.
-_WARNED = [False]
-
-
-def _warn_once_if_defaulted():
-    if _WARNED[0] or os.environ.get('APP_BASE_URL'):
-        return
-    _WARNED[0] = True
-    print(f"[links] APP_BASE_URL is not set - emailed deep links will point at "
-          f"{_LEGACY_HF_FALLBACK}, which is correct ONLY while that is where the app lives. "
-          f"Set APP_BASE_URL in the deployed environment.", file=sys.stderr)
-
-# entity kinds the URL scheme supports (must stay in sync with app.py's _desc_from_param)
-LINK_KINDS = ('customer', 'sku', 'agent', 'account')
-
-
-def deeplink(page=None, kind=None, ident=None, src=None):
-    """An absolute app URL. deeplink('customer_data', 'customer', 1234, src='digest')."""
-    _warn_once_if_defaulted()
-    parts = []
-    if page:
-        parts.append(f"page={quote(str(page), safe='')}")
-    if kind in LINK_KINDS and ident not in (None, ''):
-        parts.append(f"entity={quote(f'{kind}:{ident}', safe=':')}")
-    if src:
-        parts.append(f"src={quote(str(src), safe='')}")
-    return BASE_URL + ('/?' + '&'.join(parts) if parts else '/')
+"""Deep links into the app — ?page=<key>&entity=<kind>:<id>&src=<source>.
+
+The app (app.py) consumes these params once per session right after login and routes to the page,
+opening the entity drawer when an entity is present. Digest/alert/mention emails build their links
+here so every emailed number lands the reader on the exact row it came from. `src` tags where the
+click came from (digest / alert / mention) — the app logs it as the click-through read receipt.
+"""
+import os
+import sys
+from urllib.parse import quote
+
+#: ⛔ THE ONE HOST LITERAL LEFT IN THE RUNTIME PATH, and it is a MIGRATION HAZARD — named here
+#: rather than buried in a default argument, because the day we change hosts this is what silently
+#: keeps mailing customers a link to the DEAD one. Found by `ops/verify_portability.py` on its
+#: first run (2026-07-30).
+#:
+#: Why it is still here instead of raising: `deeplink()` has exactly one family of callers
+#: (`modules/digest.py`, 7 sites, all building email hrefs), `DIGEST_ENABLED` defaults to ON, and
+#: no deploy sets `APP_BASE_URL` today — so refusing to guess would break a LIVE feature to fix a
+#: latent one. Instead: both deploy scripts now push `APP_BASE_URL`, which makes the fallback
+#: unreachable in a deployed environment, and reaching it prints an operator warning.
+#:
+#: ⇒ EXIT CONDITION for this constant: once a deploy has set `APP_BASE_URL` and it is confirmed
+#: present in the running environment, delete the fallback and let `deeplink()` raise instead. It
+#: is declared in the portability gate's RESIDUALS so the gate reports it honestly rather than
+#: reporting green over it.
+_LEGACY_HF_FALLBACK = 'https://royal-imports-cfo-os.hf.space'
+
+BASE_URL = (os.environ.get('APP_BASE_URL') or _LEGACY_HF_FALLBACK).rstrip('/')
+
+#: Warned LAZILY and ONCE — at the first link actually built, not at import. An import-time print
+#: fires in every gate, every subprocess and every unit test that so much as touches `core`, which
+#: is how a real warning becomes noise nobody reads.
+_WARNED = [False]
+
+
+def _warn_once_if_defaulted():
+    if _WARNED[0] or os.environ.get('APP_BASE_URL'):
+        return
+    _WARNED[0] = True
+    print(f"[links] APP_BASE_URL is not set - emailed deep links will point at "
+          f"{_LEGACY_HF_FALLBACK}, which is correct ONLY while that is where the app lives. "
+          f"Set APP_BASE_URL in the deployed environment.", file=sys.stderr)
+
+# entity kinds the URL scheme supports (must stay in sync with app.py's _desc_from_param)
+LINK_KINDS = ('customer', 'sku', 'agent', 'account')
+
+
+def deeplink(page=None, kind=None, ident=None, src=None):
+    """An absolute app URL. deeplink('customer_data', 'customer', 1234, src='digest')."""
+    _warn_once_if_defaulted()
+    parts = []
+    if page:
+        parts.append(f"page={quote(str(page), safe='')}")
+    if kind in LINK_KINDS and ident not in (None, ''):
+        parts.append(f"entity={quote(f'{kind}:{ident}', safe=':')}")
+    if src:
+        parts.append(f"src={quote(str(src), safe='')}")
+    return BASE_URL + ('/?' + '&'.join(parts) if parts else '/')

platform/core/registry.py

@@ -1,199 +1,199 @@
-"""Module registry — the single source of truth for the dashboards.
-
-`app.py` builds the sidebar nav from this, and decides whether the global Brand (DBA) filter
-applies to a page. `validate.py` runs each module's validate() from this. Adding a module =
-add one row here + a page function in app.py + a module in modules/.
-
-Fields:
-  key     stable id (matches the modules/<key>.py file and the app page_<key> function)
-  label   sidebar/title text (no emojis)
-  brand   True  -> DBA-filterable (honours the Fisch/Royal selector)
-          False -> consolidated/company-level (ignores the brand selector)
-  hq      True  -> HQ / company-level (cash flow, balance sheet, AR/AP, consolidated)
-  validate True -> module exposes validate() and is included in validate.py
-  parent  set -> this row is a SUB-MODULE of <parent key>: it leaves the Workflows dropdown and
-          renders as a sub-nav button when its parent (or a sibling) is the active module; a
-          parent grant covers its sub-modules (owner nav redesign 2026-07-23)
-  archived True -> RETIRED from the UI for EVERYONE (owner 2026-07-27, supersedes the
-          2026-07-23 per-user-restore semantics): no nav entry, no Settings>Modules checkbox,
-          prewarm and validate.py skip it. Code and data layer stay in the repo but are NOT
-          maintained — spend no effort on archived modules until the owner un-archives.
-          2026-07-23 pass: backorders, pricecomp, o2c, bookings, spend, expenses.
-          2026-07-27 pass (keep = Sales + Customers family + Agents + Procurement +
-          Collections + Analyst/plumbing): products, assortment, financial, management,
-          pricing, inventory, vendor, warehouse, returns, outreach, complexity, health.
-  note    one-line scope note shown in the UI / docs
-"""
-# WAVE-9 I8 — `'source'`: which connected system a module's data comes from.
-#
-# The owner's model: every nav entry is "a piece of database from a source", so the nav shows the
-# source beside the name ("Sales · Odoo"). It is a REGISTRY FACT rather than a string in the nav
-# code precisely so the nav needs no edit when a second connector lands — a user-created blank
-# table simply carries a different source, and a module with no `source` (Metric Dictionary,
-# Settings, the Analyst) renders no badge because it is not a database at all.
-# See [[connector-onboarding]]: the plug-in seam is datastore.py, and Odoo has no delegated
-# OAuth, so the "+ New" connect flow is the credential-form shape, not an OAuth redirect.
-REGISTRY = [
-    # ARCHIVED wave 16 (owner item 7, R3/R11, 2026-08-02): the PAGE went on the strength of
-    # C-CHARTCAP — every Sales block shape (YoY compare series, KPI delta tiles, group-by
-    # tables) is now assemblable BY HAND from the grid's chart/dashboard views, which is what
-    # R3 required before deletion. `modules/sales.py` (the data layer) STAYS — drawers and the
-    # briefing still read it, and pages_sales.py survives UNREGISTERED as the Y1 envelope's
-    # template + verify_api's fixture.
-    {'key': 'sales',     'label': 'Sales',              'brand': True,  'hq': False, 'validate': True, 'source': 'Odoo', 'archived': True,
-     'note': 'Revenue, YoY, seasonality, reps, customers, SKUs — by BU. Retired wave 16: '
-             'rebuild as grid chart/dashboard views (compare series, KPI deltas, tables).'},
-    # ARCHIVED AS A PAGE (owner item 14, wave 8): "archive the current form of the Customer
-    # dashboard completely, i want to redesign it, exactly with the backend we have". So the
-    # PAGE goes and the DATA LAYER stays — modules/customers.py still powers the Customer table's
-    # metrics and still validates against Odoo, which is what the redesign will be built on.
-    #
-    # ⚠ NOT 'archived': True. Archived means invisible to everyone, and this row is the parent of
-    # customer_data + cohort — archiving it would take the whole family out of the nav and strand
-    # its children. 'group_only' says exactly what is true: this key names a FOLDER, never a
-    # destination. It has no PAGE_FUNCS entry, the nav never renders it as a leaf, and a stale
-    # deep link to it redirects to the family's first visible member.
-    {'key': 'customers', 'label': 'Customers',          'brand': True,  'hq': False, 'validate': True,
-     'group_only': True,
-     'note': 'Folder for the customer surfaces (Customer table, Cohort). The old Customers '
-             'dashboard was retired for redesign (owner item 14, 2026-07-28); its metric layer '
-             '(modules/customers.py) still backs the table and still validates against Odoo.'},
-    # LABEL renamed 'Customer List' -> 'Data' (owner 2026-07-25) -> 'Customer' (owner item 5,
-    # 2026-07-27); KEY renamed 'customer_list' -> 'customer_data' (owner 2026-07-26). The key
-    # rename is safe ONLY because _LEGACY_KEYS (ui/session.py) migrates grants, Library prefs
-    # and ?page= deep links ON READ — stored user records are never edited, exactly as
-    # myday->customer_list was done. The STORE keys are deliberately NOT renamed:
-    # 'customer_table_workspace' and 'customer_lists' hold real user data, and renaming them
-    # would orphan every saved view. Label-only changes need none of that machinery.
-    {'key': 'customer_data', 'label': 'Customer',       'brand': True,  'hq': False, 'validate': False, 'source': 'Odoo', 'parent': 'customers',
-     'note': 'Build, filter and save customer lists: the whole scoped book with per-customer '
-             'metrics; saved lists are visible, editable formulas (Call list and Win-back ship '
-             'as templates) plus hand-picked members. Sub-module of Customers (owner nav redesign 2026-07-23; replaced My Day).'},
-    # Cohort (owner item 6, 2026-07-26): the SAME table as Data over a FIXED set. The
-    # difference is membership semantics, not layout — a saved view re-populates as the
-    # data moves, a cohort only changes when a person edits it. validate:False because
-    # there is no Odoo aggregate to reconcile a hand-picked list against; its metrics are
-    # the customers module's, already validated there.
-    # ARCHIVED wave 16 (owner item 5, R10 — the fold-in): every cohort now projects as a
-    # LOCKED VIEW in the Customer rail's "Cohorts" section (wave-15 C-LOCK), so the separate
-    # nav destination is gone. ALL cohort machinery stays: `scope=cohort` still works
-    # (routes_grid._SCOPES, storage keys, events), page_cohort remains in app.py, and
-    # _LEGACY_KEYS maps cohort→customer_data so grants + ?page= deep links land on the grid
-    # that now hosts the cohorts.
-    {'key': 'cohort',    'label': 'Cohort',             'brand': True,  'hq': False, 'validate': False, 'source': 'Odoo', 'parent': 'customers', 'archived': True,
-     'note': 'Hand-curated, unchanging customer lists — folded into the Customer rail as '
-             'locked views (wave 16). The set is fixed: it changes only when someone adds '
-             'or removes a member. Open them from Customer > Views > Cohorts.'},
-    # ARCHIVED wave 16 (owner item 7, R11, 2026-08-02) beside Sales. The agent DRAWER and the
-    # data layer (modules/agent.py, agent_* caches) STAY — agent entities still open from
-    # customer surfaces; an own-book agent login's home is the Customer grid narrowed by the
-    # R1 permanent filter ("Agent is X"), not this page.
-    {'key': 'agent',     'label': 'Agents',             'brand': True,  'hq': False, 'validate': True, 'source': 'Odoo', 'archived': True,
-     'note': 'Per-agent book: sales (custom dates), returns, top SKUs, full customer list incl. inactive. '
-             'Retired wave 16: agent drawers + the R1 own-book filter carry the use case.'},
-    # Wave 16 C-TOPIC (owner items 9+10, R4): the PRODUCT table family — the second object on
-    # the table-page factory. `products_family` is the folder head (the `customers` pattern:
-    # group_only, never a destination); `product_data` is the grid over the SKU dataset, with
-    # its OWN workspace bucket ('product_table_workspace') and the /products + scope=product
-    # seams. The archived Streamlit `products` (SKU) row below stays archived and untouched,
-    # exactly as R4 rules.
-    {'key': 'products_family', 'label': 'Products',     'brand': True,  'hq': False, 'validate': False,
-     'group_only': True,
-     'note': 'Folder for the product surfaces (Product table). The archived SKU dashboard is '
-             'not part of this family.'},
-    {'key': 'product_data', 'label': 'Product',         'brand': True,  'hq': False, 'validate': True, 'source': 'Odoo', 'parent': 'products_family',
-     'note': 'The SKU catalogue as a grid: per-product revenue, units and (consolidated) '
-             'stock columns, with saved views and custom fields. Identity = the SKU code.'},
-    {'key': 'products',  'label': 'SKU',                'brand': True,  'hq': False, 'validate': True, 'archived': True,
-     'note': 'SKU movers, zombies, velocity, coverage, drawers — by BU (sales-derived).'},
-    {'key': 'assortment', 'label': 'Assortment',        'brand': True,  'hq': False, 'validate': True, 'archived': True,
-     'note': 'Facet-level performance (category/color/occasion/collection/season) + season readiness — by BU.'},
-    {'key': 'financial', 'label': 'Financial',          'brand': True,  'hq': False, 'validate': True, 'archived': True,
-     'note': 'Gross margin by BU/category/SKU. Cash-conversion cycle is HQ-consolidated.'},
-    {'key': 'pricing',   'label': 'Pricing',            'brand': True,  'hq': False, 'validate': True, 'archived': True,
-     'note': 'Per-SKU margin/markup/LTM sales + allocated net P&L (channel-rate cost-to-SKU) for pricing decisions.'},
-    {'key': 'management', 'label': 'Management P&L',     'brand': False, 'hq': True,  'validate': True, 'archived': True,
-     'nav': False,   # rendered INSIDE the Financial module (view toggle) — archived WITH financial
-     'note': 'Operating-model management income statements (FFS/RI/GD/BU-M) reproduced from raw Odoo, Sep-2024+.'},
-    {'key': 'inventory', 'label': 'Inventory',          'brand': False, 'hq': False, 'validate': True, 'archived': True,
-     'note': 'On-hand stock is physically consolidated (shared warehouse); not DBA-split.'},
-    {'key': 'procurement', 'label': 'Procurement',      'brand': False, 'hq': False, 'validate': True, 'source': 'Odoo',
-     'validate_only': True,
-     'note': 'PAGE RETIRED 2026-08-03 (owner wave-17 item 13: "We should be able to replace '
-             'Procurement completely, and add it as part of the Product database"). The buy '
-             'list is now a saved VIEW on the Product grid, filtered on a FORMULA field over '
-             'the supplier/lead-time columns and the demand measure — the owner\'s ruling R3: '
-             '"Buy list is just a View, with a Filter from a Formula field that taps into '
-             'Metrics Fields... the 8-month demand baseline etc. is just math in a Formula '
-             'field." The ROW STAYS validate_only: `modules/procurement.py` still owns the '
-             'supplier master map (procurement_suppliers.json, 3,963 SKUs) that seeds those '
-             'columns, and its validate() is the proof they reconcile.'},
-    {'key': 'vendor',    'label': 'Vendors',            'brand': False, 'hq': False, 'validate': False, 'archived': True,
-     'note': 'Vendor master data + the SKUs each supplies; multiple-vendor / cheapest-price view.'},
-    {'key': 'warehouse', 'label': 'Warehouse',          'brand': False, 'hq': False, 'validate': True, 'archived': True,
-     'note': 'Movement & efficiency: on-time ship, Pick-Pack-Ship cycle times, throughput, backlog age, shrinkage. Physical ops (consolidated).'},
-    {'key': 'ar',        'label': 'Collections',        'brand': False, 'hq': True,  'validate': True,
-     'source': 'Odoo', 'api_surface': False, 'admin_only': True,
-     'note': 'PAGE RETIRED 2026-08-03 (owner wave-17 item 15: "Collections should also be '
-             'entirely replicable as just a View under Customer"). The worklist is the shared '
-             '"Collections" view on the Customer grid — same numbers, from this module\'s own '
-             'reconciled blocks (ar_open/ar_overdue/ar_exposure/days_to_pay + the four aging '
-             'buckets). The ROW STAYS validate_only so validate.py keeps running ar.validate(), '
-             'which is the proof those columns rest on; archiving it would have skipped the '
-             'reconciliation while the numbers kept shipping. ⚠ NOT `validate_only`, and the '
-             'difference is a LIVE WORKFLOW: this page also mounts the admin-gated STATEMENTS '
-             'sender (app._collections_statements -> modules/collections_send), the ONE '
-             'sanctioned Odoo writer, which the same ruling says stays untouched. So the row '
-             'keeps a Streamlit page for ADMINS ONLY (`admin_only`) and leaves the API payload '
-             'entirely (`api_surface: False`) — no "Collections" in the React nav, no second '
-             'worklist, and the biweekly send keeps its door.'},
-    {'key': 'returns',   'label': 'Returns',            'brand': False, 'hq': True,  'validate': True, 'archived': True,
-     'note': 'Credit-note lens: refund concentration by SKU (quality) and customer (behavior). Company-level.'},
-    {'key': 'outreach',  'label': 'Outreach',           'brand': True,  'hq': False, 'validate': False, 'archived': True,
-     'note': 'Campaign emails to customer segments: templates, suppression, send log, revenue attribution. Sending is admin-gated behind SAFE_MODE.'},
-    {'key': 'backorders', 'label': 'Backorders',        'brand': True,  'hq': False, 'validate': True, 'archived': True,
-     'note': 'Confirmed-undelivered order lines aged vs promise date, valued, with a supply-aware next action per row (ship / expedite / call). Wholesale scope.'},
-    {'key': 'pricecomp', 'label': 'Price Compliance',   'brand': True,  'hq': False, 'validate': True, 'archived': True,
-     'note': 'Selling below the customer pricelist tier (LTM, per customer x SKU): the pocket-price floor worklist with annualized leak $. Sub-30% ratios usually mean a stale or pack-basis RULE — fix the rule, not the rep.'},
-    {'key': 'o2c',       'label': 'Cash Timing',        'brand': True,  'hq': False, 'validate': True, 'archived': True,
-     'note': 'Order-to-cash stage decomposition (order-to-ship / ship-to-invoice / invoice-to-paid, each with its owner) + the terms-gap rollup: contractual vs actual days per payment term with the free-credit $ it strands.'},
-    {'key': 'bookings',  'label': 'Order Book',         'brand': True,  'hq': False, 'validate': True, 'archived': True,
-     'note': 'Pre-season booking coverage: cumulative booked $ for Aug-Dec delivery vs last year same-week; category TY-vs-LY-as-of-date. The container-program decision, months ahead.'},
-    {'key': 'spend',     'label': 'Spend & Payables',   'brand': False, 'hq': True,  'validate': True, 'archived': True,
-     'note': 'Vendor-bill side: payment-terms capture (early-pay cash surrendered), duplicate-bill review, the opex spend cube (fragmentation, consolidate+rebid) and freight recovery. Company-level.'},
-    {'key': 'complexity', 'label': 'SKU Complexity',    'brand': False, 'hq': False, 'validate': True, 'archived': True,
-     'note': 'BCG tail rationalization: every SKU re-costed by ACTIVITY (lines, picks, returns) + 25%/yr carrying; KILL candidates rest on hard math (GM minus carrying), REVIEW on the pooled activity estimate. All-channel.'},
-    {'key': 'expenses',  'label': 'Expenses',           'brand': False, 'hq': True,  'validate': True, 'archived': True,
-     'note': 'Operating expense from the GL (all expense-type accounts; COGS excluded): trend, operating leverage (opex % of revenue), the YoY cost bridge, XmR control-limit spike watch list, fixed/variable split and a drill-to-ledger category directory. Company-level.'},
-    {'key': 'health',    'label': 'Data Health',        'brand': False, 'hq': True,  'validate': True, 'archived': True,
-     'note': 'Close/reconciliation scan; period-filtered, mostly company-level. ARCHITECTURE '
-             '(owner 2026-07-23): every discrepancy / potential-error marker lives here — '
-             'procurement mapping gaps, count-trust (unverified on-hand counts), untracked-on-'
-             'order — so operational workflows stay clean for doing the work.'},
-    {'key': 'dictionary', 'label': 'Metric Dictionary', 'brand': False, 'hq': True,  'validate': True,
-     'nav': False, 'validate_only': True,
-     'note': 'PAGE RETIRED 2026-07-23 (owner: broken/not customer-facing) — row kept ONLY so '
-             'validate.py keeps running the semantic-layer contracts (the Analyst grounding '
-             'proof). No nav, no page. Wave 17 R8 ("I don\'t even know what it does — delete '
-             'them") made that literal: `validate_only` takes it out of the account menu too, '
-             'which is the last place it was still visible. The proof survives; the door does not.'},
-    {'key': 'automation', 'label': 'Automation',        'brand': False, 'hq': True,  'validate': False,
-     'nav': True,
-     'note': 'Wave 18 (C-AUTONAV): the Automation surface — scheduled jobs that create and '
-             'refresh user databases (website scrape-to-DB, the Instagram field). React-only '
-             'surface (no PAGE_FUNCS entry, the no-new-Streamlit rule); admins hold it via '
-             '"all", other users need the explicit grant — fail-closed default.'},
-    {'key': 'settings',  'label': 'Settings',           'brand': False, 'hq': True,  'validate': False,
-     'nav': False,   # sidebar sentinel (account group) — owner IA 2026-07-12
-     'note': 'User scope settings: the Business Unit toggle (strict isolation) and the Data basis '
-             'toggle (Orders vs Invoiced) moved here from the sidebar.'},
-    {'key': 'analyst',   'label': 'AIOS Analyst',       'brand': False, 'hq': True,  'validate': False,
-     'nav': False,   # sidebar sentinel button; eval gate = harness/evals.py (run pre-ship, NOT in validate.py — live LLM cost)
-     'note': 'Ask the business a question in plain language: a small AI model calls governed tools over the semantic layer — answers carry their query trace and drill links. AI-generated output (Art. 50 labeled).'},
-]
-
-BY_KEY = {m['key']: m for m in REGISTRY}
-
-
-def brand_filterable(key) -> bool:
-    return bool(BY_KEY.get(key, {}).get('brand'))
+"""Module registry — the single source of truth for the dashboards.
+
+`app.py` builds the sidebar nav from this, and decides whether the global Brand (DBA) filter
+applies to a page. `validate.py` runs each module's validate() from this. Adding a module =
+add one row here + a page function in app.py + a module in modules/.
+
+Fields:
+  key     stable id (matches the modules/<key>.py file and the app page_<key> function)
+  label   sidebar/title text (no emojis)
+  brand   True  -> DBA-filterable (honours the Fisch/Royal selector)
+          False -> consolidated/company-level (ignores the brand selector)
+  hq      True  -> HQ / company-level (cash flow, balance sheet, AR/AP, consolidated)
+  validate True -> module exposes validate() and is included in validate.py
+  parent  set -> this row is a SUB-MODULE of <parent key>: it leaves the Workflows dropdown and
+          renders as a sub-nav button when its parent (or a sibling) is the active module; a
+          parent grant covers its sub-modules (owner nav redesign 2026-07-23)
+  archived True -> RETIRED from the UI for EVERYONE (owner 2026-07-27, supersedes the
+          2026-07-23 per-user-restore semantics): no nav entry, no Settings>Modules checkbox,
+          prewarm and validate.py skip it. Code and data layer stay in the repo but are NOT
+          maintained — spend no effort on archived modules until the owner un-archives.
+          2026-07-23 pass: backorders, pricecomp, o2c, bookings, spend, expenses.
+          2026-07-27 pass (keep = Sales + Customers family + Agents + Procurement +
+          Collections + Analyst/plumbing): products, assortment, financial, management,
+          pricing, inventory, vendor, warehouse, returns, outreach, complexity, health.
+  note    one-line scope note shown in the UI / docs
+"""
+# WAVE-9 I8 — `'source'`: which connected system a module's data comes from.
+#
+# The owner's model: every nav entry is "a piece of database from a source", so the nav shows the
+# source beside the name ("Sales · Odoo"). It is a REGISTRY FACT rather than a string in the nav
+# code precisely so the nav needs no edit when a second connector lands — a user-created blank
+# table simply carries a different source, and a module with no `source` (Metric Dictionary,
+# Settings, the Analyst) renders no badge because it is not a database at all.
+# See [[connector-onboarding]]: the plug-in seam is datastore.py, and Odoo has no delegated
+# OAuth, so the "+ New" connect flow is the credential-form shape, not an OAuth redirect.
+REGISTRY = [
+    # ARCHIVED wave 16 (owner item 7, R3/R11, 2026-08-02): the PAGE went on the strength of
+    # C-CHARTCAP — every Sales block shape (YoY compare series, KPI delta tiles, group-by
+    # tables) is now assemblable BY HAND from the grid's chart/dashboard views, which is what
+    # R3 required before deletion. `modules/sales.py` (the data layer) STAYS — drawers and the
+    # briefing still read it, and pages_sales.py survives UNREGISTERED as the Y1 envelope's
+    # template + verify_api's fixture.
+    {'key': 'sales',     'label': 'Sales',              'brand': True,  'hq': False, 'validate': True, 'source': 'Odoo', 'archived': True,
+     'note': 'Revenue, YoY, seasonality, reps, customers, SKUs — by BU. Retired wave 16: '
+             'rebuild as grid chart/dashboard views (compare series, KPI deltas, tables).'},
+    # ARCHIVED AS A PAGE (owner item 14, wave 8): "archive the current form of the Customer
+    # dashboard completely, i want to redesign it, exactly with the backend we have". So the
+    # PAGE goes and the DATA LAYER stays — modules/customers.py still powers the Customer table's
+    # metrics and still validates against Odoo, which is what the redesign will be built on.
+    #
+    # ⚠ NOT 'archived': True. Archived means invisible to everyone, and this row is the parent of
+    # customer_data + cohort — archiving it would take the whole family out of the nav and strand
+    # its children. 'group_only' says exactly what is true: this key names a FOLDER, never a
+    # destination. It has no PAGE_FUNCS entry, the nav never renders it as a leaf, and a stale
+    # deep link to it redirects to the family's first visible member.
+    {'key': 'customers', 'label': 'Customers',          'brand': True,  'hq': False, 'validate': True,
+     'group_only': True,
+     'note': 'Folder for the customer surfaces (Customer table, Cohort). The old Customers '
+             'dashboard was retired for redesign (owner item 14, 2026-07-28); its metric layer '
+             '(modules/customers.py) still backs the table and still validates against Odoo.'},
+    # LABEL renamed 'Customer List' -> 'Data' (owner 2026-07-25) -> 'Customer' (owner item 5,
+    # 2026-07-27); KEY renamed 'customer_list' -> 'customer_data' (owner 2026-07-26). The key
+    # rename is safe ONLY because _LEGACY_KEYS (ui/session.py) migrates grants, Library prefs
+    # and ?page= deep links ON READ — stored user records are never edited, exactly as
+    # myday->customer_list was done. The STORE keys are deliberately NOT renamed:
+    # 'customer_table_workspace' and 'customer_lists' hold real user data, and renaming them
+    # would orphan every saved view. Label-only changes need none of that machinery.
+    {'key': 'customer_data', 'label': 'Customer',       'brand': True,  'hq': False, 'validate': False, 'source': 'Odoo', 'parent': 'customers',
+     'note': 'Build, filter and save customer lists: the whole scoped book with per-customer '
+             'metrics; saved lists are visible, editable formulas (Call list and Win-back ship '
+             'as templates) plus hand-picked members. Sub-module of Customers (owner nav redesign 2026-07-23; replaced My Day).'},
+    # Cohort (owner item 6, 2026-07-26): the SAME table as Data over a FIXED set. The
+    # difference is membership semantics, not layout — a saved view re-populates as the
+    # data moves, a cohort only changes when a person edits it. validate:False because
+    # there is no Odoo aggregate to reconcile a hand-picked list against; its metrics are
+    # the customers module's, already validated there.
+    # ARCHIVED wave 16 (owner item 5, R10 — the fold-in): every cohort now projects as a
+    # LOCKED VIEW in the Customer rail's "Cohorts" section (wave-15 C-LOCK), so the separate
+    # nav destination is gone. ALL cohort machinery stays: `scope=cohort` still works
+    # (routes_grid._SCOPES, storage keys, events), page_cohort remains in app.py, and
+    # _LEGACY_KEYS maps cohort→customer_data so grants + ?page= deep links land on the grid
+    # that now hosts the cohorts.
+    {'key': 'cohort',    'label': 'Cohort',             'brand': True,  'hq': False, 'validate': False, 'source': 'Odoo', 'parent': 'customers', 'archived': True,
+     'note': 'Hand-curated, unchanging customer lists — folded into the Customer rail as '
+             'locked views (wave 16). The set is fixed: it changes only when someone adds '
+             'or removes a member. Open them from Customer > Views > Cohorts.'},
+    # ARCHIVED wave 16 (owner item 7, R11, 2026-08-02) beside Sales. The agent DRAWER and the
+    # data layer (modules/agent.py, agent_* caches) STAY — agent entities still open from
+    # customer surfaces; an own-book agent login's home is the Customer grid narrowed by the
+    # R1 permanent filter ("Agent is X"), not this page.
+    {'key': 'agent',     'label': 'Agents',             'brand': True,  'hq': False, 'validate': True, 'source': 'Odoo', 'archived': True,
+     'note': 'Per-agent book: sales (custom dates), returns, top SKUs, full customer list incl. inactive. '
+             'Retired wave 16: agent drawers + the R1 own-book filter carry the use case.'},
+    # Wave 16 C-TOPIC (owner items 9+10, R4): the PRODUCT table family — the second object on
+    # the table-page factory. `products_family` is the folder head (the `customers` pattern:
+    # group_only, never a destination); `product_data` is the grid over the SKU dataset, with
+    # its OWN workspace bucket ('product_table_workspace') and the /products + scope=product
+    # seams. The archived Streamlit `products` (SKU) row below stays archived and untouched,
+    # exactly as R4 rules.
+    {'key': 'products_family', 'label': 'Products',     'brand': True,  'hq': False, 'validate': False,
+     'group_only': True,
+     'note': 'Folder for the product surfaces (Product table). The archived SKU dashboard is '
+             'not part of this family.'},
+    {'key': 'product_data', 'label': 'Product',         'brand': True,  'hq': False, 'validate': True, 'source': 'Odoo', 'parent': 'products_family',
+     'note': 'The SKU catalogue as a grid: per-product revenue, units and (consolidated) '
+             'stock columns, with saved views and custom fields. Identity = the SKU code.'},
+    {'key': 'products',  'label': 'SKU',                'brand': True,  'hq': False, 'validate': True, 'archived': True,
+     'note': 'SKU movers, zombies, velocity, coverage, drawers — by BU (sales-derived).'},
+    {'key': 'assortment', 'label': 'Assortment',        'brand': True,  'hq': False, 'validate': True, 'archived': True,
+     'note': 'Facet-level performance (category/color/occasion/collection/season) + season readiness — by BU.'},
+    {'key': 'financial', 'label': 'Financial',          'brand': True,  'hq': False, 'validate': True, 'archived': True,
+     'note': 'Gross margin by BU/category/SKU. Cash-conversion cycle is HQ-consolidated.'},
+    {'key': 'pricing',   'label': 'Pricing',            'brand': True,  'hq': False, 'validate': True, 'archived': True,
+     'note': 'Per-SKU margin/markup/LTM sales + allocated net P&L (channel-rate cost-to-SKU) for pricing decisions.'},
+    {'key': 'management', 'label': 'Management P&L',     'brand': False, 'hq': True,  'validate': True, 'archived': True,
+     'nav': False,   # rendered INSIDE the Financial module (view toggle) — archived WITH financial
+     'note': 'Operating-model management income statements (FFS/RI/GD/BU-M) reproduced from raw Odoo, Sep-2024+.'},
+    {'key': 'inventory', 'label': 'Inventory',          'brand': False, 'hq': False, 'validate': True, 'archived': True,
+     'note': 'On-hand stock is physically consolidated (shared warehouse); not DBA-split.'},
+    {'key': 'procurement', 'label': 'Procurement',      'brand': False, 'hq': False, 'validate': True, 'source': 'Odoo',
+     'validate_only': True,
+     'note': 'PAGE RETIRED 2026-08-03 (owner wave-17 item 13: "We should be able to replace '
+             'Procurement completely, and add it as part of the Product database"). The buy '
+             'list is now a saved VIEW on the Product grid, filtered on a FORMULA field over '
+             'the supplier/lead-time columns and the demand measure — the owner\'s ruling R3: '
+             '"Buy list is just a View, with a Filter from a Formula field that taps into '
+             'Metrics Fields... the 8-month demand baseline etc. is just math in a Formula '
+             'field." The ROW STAYS validate_only: `modules/procurement.py` still owns the '
+             'supplier master map (procurement_suppliers.json, 3,963 SKUs) that seeds those '
+             'columns, and its validate() is the proof they reconcile.'},
+    {'key': 'vendor',    'label': 'Vendors',            'brand': False, 'hq': False, 'validate': False, 'archived': True,
+     'note': 'Vendor master data + the SKUs each supplies; multiple-vendor / cheapest-price view.'},
+    {'key': 'warehouse', 'label': 'Warehouse',          'brand': False, 'hq': False, 'validate': True, 'archived': True,
+     'note': 'Movement & efficiency: on-time ship, Pick-Pack-Ship cycle times, throughput, backlog age, shrinkage. Physical ops (consolidated).'},
+    {'key': 'ar',        'label': 'Collections',        'brand': False, 'hq': True,  'validate': True,
+     'source': 'Odoo', 'api_surface': False, 'admin_only': True,
+     'note': 'PAGE RETIRED 2026-08-03 (owner wave-17 item 15: "Collections should also be '
+             'entirely replicable as just a View under Customer"). The worklist is the shared '
+             '"Collections" view on the Customer grid — same numbers, from this module\'s own '
+             'reconciled blocks (ar_open/ar_overdue/ar_exposure/days_to_pay + the four aging '
+             'buckets). The ROW STAYS validate_only so validate.py keeps running ar.validate(), '
+             'which is the proof those columns rest on; archiving it would have skipped the '
+             'reconciliation while the numbers kept shipping. ⚠ NOT `validate_only`, and the '
+             'difference is a LIVE WORKFLOW: this page also mounts the admin-gated STATEMENTS '
+             'sender (app._collections_statements -> modules/collections_send), the ONE '
+             'sanctioned Odoo writer, which the same ruling says stays untouched. So the row '
+             'keeps a Streamlit page for ADMINS ONLY (`admin_only`) and leaves the API payload '
+             'entirely (`api_surface: False`) — no "Collections" in the React nav, no second '
+             'worklist, and the biweekly send keeps its door.'},
+    {'key': 'returns',   'label': 'Returns',            'brand': False, 'hq': True,  'validate': True, 'archived': True,
+     'note': 'Credit-note lens: refund concentration by SKU (quality) and customer (behavior). Company-level.'},
+    {'key': 'outreach',  'label': 'Outreach',           'brand': True,  'hq': False, 'validate': False, 'archived': True,
+     'note': 'Campaign emails to customer segments: templates, suppression, send log, revenue attribution. Sending is admin-gated behind SAFE_MODE.'},
+    {'key': 'backorders', 'label': 'Backorders',        'brand': True,  'hq': False, 'validate': True, 'archived': True,
+     'note': 'Confirmed-undelivered order lines aged vs promise date, valued, with a supply-aware next action per row (ship / expedite / call). Wholesale scope.'},
+    {'key': 'pricecomp', 'label': 'Price Compliance',   'brand': True,  'hq': False, 'validate': True, 'archived': True,
+     'note': 'Selling below the customer pricelist tier (LTM, per customer x SKU): the pocket-price floor worklist with annualized leak $. Sub-30% ratios usually mean a stale or pack-basis RULE — fix the rule, not the rep.'},
+    {'key': 'o2c',       'label': 'Cash Timing',        'brand': True,  'hq': False, 'validate': True, 'archived': True,
+     'note': 'Order-to-cash stage decomposition (order-to-ship / ship-to-invoice / invoice-to-paid, each with its owner) + the terms-gap rollup: contractual vs actual days per payment term with the free-credit $ it strands.'},
+    {'key': 'bookings',  'label': 'Order Book',         'brand': True,  'hq': False, 'validate': True, 'archived': True,
+     'note': 'Pre-season booking coverage: cumulative booked $ for Aug-Dec delivery vs last year same-week; category TY-vs-LY-as-of-date. The container-program decision, months ahead.'},
+    {'key': 'spend',     'label': 'Spend & Payables',   'brand': False, 'hq': True,  'validate': True, 'archived': True,
+     'note': 'Vendor-bill side: payment-terms capture (early-pay cash surrendered), duplicate-bill review, the opex spend cube (fragmentation, consolidate+rebid) and freight recovery. Company-level.'},
+    {'key': 'complexity', 'label': 'SKU Complexity',    'brand': False, 'hq': False, 'validate': True, 'archived': True,
+     'note': 'BCG tail rationalization: every SKU re-costed by ACTIVITY (lines, picks, returns) + 25%/yr carrying; KILL candidates rest on hard math (GM minus carrying), REVIEW on the pooled activity estimate. All-channel.'},
+    {'key': 'expenses',  'label': 'Expenses',           'brand': False, 'hq': True,  'validate': True, 'archived': True,
+     'note': 'Operating expense from the GL (all expense-type accounts; COGS excluded): trend, operating leverage (opex % of revenue), the YoY cost bridge, XmR control-limit spike watch list, fixed/variable split and a drill-to-ledger category directory. Company-level.'},
+    {'key': 'health',    'label': 'Data Health',        'brand': False, 'hq': True,  'validate': True, 'archived': True,
+     'note': 'Close/reconciliation scan; period-filtered, mostly company-level. ARCHITECTURE '
+             '(owner 2026-07-23): every discrepancy / potential-error marker lives here — '
+             'procurement mapping gaps, count-trust (unverified on-hand counts), untracked-on-'
+             'order — so operational workflows stay clean for doing the work.'},
+    {'key': 'dictionary', 'label': 'Metric Dictionary', 'brand': False, 'hq': True,  'validate': True,
+     'nav': False, 'validate_only': True,
+     'note': 'PAGE RETIRED 2026-07-23 (owner: broken/not customer-facing) — row kept ONLY so '
+             'validate.py keeps running the semantic-layer contracts (the Analyst grounding '
+             'proof). No nav, no page. Wave 17 R8 ("I don\'t even know what it does — delete '
+             'them") made that literal: `validate_only` takes it out of the account menu too, '
+             'which is the last place it was still visible. The proof survives; the door does not.'},
+    {'key': 'automation', 'label': 'Automation',        'brand': False, 'hq': True,  'validate': False,
+     'nav': True,
+     'note': 'Wave 18 (C-AUTONAV): the Automation surface — scheduled jobs that create and '
+             'refresh user databases (website scrape-to-DB, the Instagram field). React-only '
+             'surface (no PAGE_FUNCS entry, the no-new-Streamlit rule); admins hold it via '
+             '"all", other users need the explicit grant — fail-closed default.'},
+    {'key': 'settings',  'label': 'Settings',           'brand': False, 'hq': True,  'validate': False,
+     'nav': False,   # sidebar sentinel (account group) — owner IA 2026-07-12
+     'note': 'User scope settings: the Business Unit toggle (strict isolation) and the Data basis '
+             'toggle (Orders vs Invoiced) moved here from the sidebar.'},
+    {'key': 'analyst',   'label': 'AIOS Analyst',       'brand': False, 'hq': True,  'validate': False,
+     'nav': False,   # sidebar sentinel button; eval gate = harness/evals.py (run pre-ship, NOT in validate.py — live LLM cost)
+     'note': 'Ask the business a question in plain language: a small AI model calls governed tools over the semantic layer — answers carry their query trace and drill links. AI-generated output (Art. 50 labeled).'},
+]
+
+BY_KEY = {m['key']: m for m in REGISTRY}
+
+
+def brand_filterable(key) -> bool:
+    return bool(BY_KEY.get(key, {}).get('brand'))

platform/core/store_pg.py

@@ -1,325 +1,325 @@
-"""core/store_pg.py — `core/store.py`'s interface, backed by Postgres (X4 / EXIT-2b, 2026-07-30).
-
-THE INTERFACE IS THE CONTRACT, and it is `core/store.py`'s nine functions:
-
-    available() · get(name, fresh=False) · exists(name) · put(name, data)
-    update(name, fn, flush='sync') · upload_bytes(path, data, message=None)
-    download_bytes(path) · delete_path(path) · flush(name=None, timeout=30.0)
-
-Same names, same signatures, same return types, same failure semantics — so switching backends is
-an env var (`STORE_BACKEND=hf|pg`) and not a rewrite of every caller. `core/store_backend.py`
-does the selection; nothing above it needs to know which store it is talking to.
-
-✅ VERIFIED against a real managed Postgres 2026-08-04 (W19: Neon us-east-2; `verify_store_pg.py`
-80/80 INCLUDING the integration half — schema apply, tenant provisioning, jsonb/bytea round-trips,
-80 concurrent FOR-UPDATE writes — run from HF egress; the owner's local network resets TLS:5432).
-The CUTOVER remains parked behind C1e's triggers and this module is not the default backend.
-Without `DATABASE_URL` the gate still SKIPS its integration half LOUDLY, never silently.
-The schema is `harness/pg/schema.sql`. Sequenced around the blocker, never stubbed past it.
-
-WHAT POSTGRES FIXES, precisely (C1c — these are the reasons, not a preference):
-  * **`get()` is cache-first on the HF store**, so a write from another process is invisible to a
-    running app until restart. Observed live in wave 11. Here a read is a SELECT: cross-process
-    coherence is the default rather than a thing to remember.
-  * **`update()` was read-modify-write with no concurrency control** — two writers raced and the
-    loser vanished silently. Here it runs inside ONE transaction with `SELECT … FOR UPDATE`, so
-    the second writer waits and then sees the first writer's value.
-  * **A write was an HTTP commit** against a 256-commits/hour repo budget, which is why the hot
-    path needed a coalescing async flusher at all. A Postgres write is a write; `flush='async'`
-    stays in the signature and becomes a no-op, because there is nothing to coalesce.
-
-⚠ ONE DELIBERATE DIFFERENCE FROM THE HF BACKEND, and it is a fix. `store.get()` swallows transient
-read failures and hands back a cached-or-empty dict, because a display read must not break a page.
-That leniency is exactly what wiped the user registry once (an empty read merged into a write), and
-`_read_strict` exists to opt out of it. Postgres has no equivalent "the network blipped" state
-worth hiding: a connection failure RAISES from `get()` here. Callers that must not break on a read
-should catch it — silently returning `{}` from a database that is simply unreachable is how an
-empty dict gets written back over real data.
-"""
-import json
-import os
-import threading
-
-_URL_ENV = 'DATABASE_URL'
-_LOCK = threading.RLock()
-_POOL = {'pool': None, 'url': None, 'schema': None}
-
-
-def _url():
-    return os.environ.get(_URL_ENV) or None
-
-
-def _schema_for(tenant_slug=None):
-    """`t_<slug>` with `-` normalised to `_` (a hyphen is not legal in an unquoted identifier).
-
-    Mirrors `control.provision_tenant_schema` exactly — the two MUST agree or a write lands in a
-    schema the DDL never created. `AIOS_TENANT` names the tenant this process serves; it defaults
-    to tenant #0 so the default behaviour is unchanged, the same rule `harness.datastore.path_for`
-    follows for the DuckDB filename.
-    """
-    slug = (tenant_slug or os.environ.get('AIOS_TENANT') or 'royal-imports').strip().lower()
-    return 't_' + slug.replace('-', '_')
-
-
-def _pool():
-    """The psycopg connection pool, opened once per process.
-
-    psycopg is imported LAZILY and only here: `STORE_BACKEND=hf` must not require the dependency
-    to be installed at all, which is what keeps this file safe to commit before B-3 unblocks.
-    """
-    with _LOCK:
-        url = _url()
-        if not url:
-            raise RuntimeError(
-                f'{_URL_ENV} is not set — the Postgres store backend has nothing to connect to.')
-        if _POOL['pool'] is not None and _POOL['url'] == url:
-            return _POOL['pool']
-        try:
-            from psycopg_pool import ConnectionPool
-        except ImportError as e:                  # pragma: no cover - depends on B-3
-            raise RuntimeError(
-                'STORE_BACKEND=pg needs psycopg[binary,pool]. It is deliberately NOT in '
-                'requirements.txt until the database exists (owner blocker B-3), so that the '
-                'default hf backend installs nothing it does not use.') from e
-        if _POOL['pool'] is not None:
-            try:
-                _POOL['pool'].close()
-            except Exception:
-                pass
-        # min_size=0 so a process that never touches the store opens no connection at all — the
-        # shared API serves plenty of requests (health, static, a cached payload) that never read.
-        _POOL['pool'] = ConnectionPool(url, min_size=0, max_size=8, open=True, timeout=10.0)
-        _POOL['url'] = url
-        return _POOL['pool']
-
-
-def available():
-    """True when a connection can actually be MADE, not merely when a URL is configured.
-
-    `core.store.available()` only checks for a token, which is all it can cheaply do. Here the
-    honest answer needs a round-trip, so the result is memoised per process: callers use this to
-    decide whether to degrade the UI, and a `SELECT 1` per render would be absurd.
-    """
-    if not _url():
-        return False
-    if _POOL.get('ok'):
-        return True
-    try:
-        with _pool().connection() as con:
-            con.execute('SELECT 1')
-        _POOL['ok'] = True
-        return True
-    except Exception:
-        return False
-
-
-def _table(kind, tenant_slug=None):
-    """`"t_slug"."store_kv"` — the qualified table, safely quoted."""
-    from psycopg import sql
-    return sql.SQL('{}.{}').format(sql.Identifier(_schema_for(tenant_slug)),
-                                   sql.Identifier(kind))
-
-
-def _q(template, kind, tenant_slug=None):
-    """Compose `template` with `{tbl}` = the QUALIFIED table and `{bare}` = the table name alone.
-
-    ⚠ THE TWO ARE NOT INTERCHANGEABLE, and getting it wrong is a runtime syntax error nothing
-    local would catch (no database here — owner blocker B-3). Inside `ON CONFLICT … DO UPDATE`,
-    Postgres refers to the conflicting row by the table's ALIAS, which defaults to the bare
-    table name: `store_kv.rev` is valid, `t_royal_imports.store_kv.rev` is not. So the FROM
-    position takes `{tbl}` and the DO-UPDATE position takes `{bare}`.
-
-    Identifiers go through `psycopg.sql.Identifier`, so the schema name — derived from a tenant
-    slug — cannot be an injection vector even though it is interpolated. The slug is ALSO
-    regex-constrained at its source (`control.tenants`), which is the belt to this brace.
-    """
-    from psycopg import sql
-    return sql.SQL(template).format(tbl=_table(kind, tenant_slug),
-                                    bare=sql.Identifier(kind))
-
-
-def get(name, fresh=False, tenant_slug=None):
-    """The value stored under `name`, or `{}` when the key is genuinely absent.
-
-    `fresh` is accepted and IGNORED: it exists in the HF signature to bypass a process cache, and
-    there is no cache here — every read is a SELECT. Keeping the parameter means callers do not
-    branch on the backend.
-    """
-    with _pool().connection() as con:
-        row = con.execute(
-            _q('SELECT value FROM {tbl} WHERE key = %s', 'store_kv', tenant_slug),
-            (str(name),)).fetchone()
-    return dict(row[0]) if row and isinstance(row[0], dict) else (row[0] if row else {})
-
-
-def exists(name, tenant_slug=None):
-    """True/False — and unlike the HF backend this is NEVER "True on uncertainty".
-
-    `core.store.exists` returns True on any error so a caller that would seed the store cannot
-    clobber a registry it merely failed to reach. That guard exists because a FILE HOST cannot
-    distinguish "absent" from "unreachable". Postgres can: an absent row is a fact, and an
-    unreachable server raises instead of answering.
-    """
-    with _pool().connection() as con:
-        row = con.execute(
-            _q('SELECT 1 FROM {tbl} WHERE key = %s', 'store_kv', tenant_slug),
-            (str(name),)).fetchone()
-    return row is not None
-
-
-def put(name, data, tenant_slug=None):
-    with _pool().connection() as con:
-        con.execute(
-            _q('INSERT INTO {tbl} (key, value) VALUES (%s, %s::jsonb) '
-               'ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, '
-               'updated_at = now(), rev = {bare}.rev + 1', 'store_kv', tenant_slug),
-            (str(name), json.dumps(data)))
-    return data
-
-
-def update(name, fn, flush='sync', tenant_slug=None):
-    """Read-modify-write inside ONE transaction, with the row LOCKED for the duration.
-
-    This is the operation the HF backend could not make safe. There, `update` read over HTTP,
-    applied `fn`, and uploaded — so two concurrent writers both read the old value and the second
-    upload silently discarded the first writer's change. `SELECT … FOR UPDATE` makes the second
-    writer WAIT and then apply `fn` to the first writer's result, which is what "read-modify-write"
-    was always supposed to mean.
-
-    `flush` is accepted and ignored (see the module docstring): there is no commit budget to
-    coalesce against, so 'async' has nothing to defer.
-    """
-    with _pool().connection() as con:
-        with con.transaction():
-            row = con.execute(
-                _q('SELECT value FROM {tbl} WHERE key = %s FOR UPDATE',
-                   'store_kv', tenant_slug),
-                (str(name),)).fetchone()
-            data = dict(row[0]) if row and isinstance(row[0], dict) else (row[0] if row else {})
-            result = fn(data)
-            data = result if result is not None else data
-            con.execute(
-                _q('INSERT INTO {tbl} (key, value) VALUES (%s, %s::jsonb) '
-                   'ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, '
-                   'updated_at = now(), rev = {bare}.rev + 1', 'store_kv', tenant_slug),
-                (str(name), json.dumps(data)))
-    return data
-
-
-def upload_bytes(path_in_repo, data, message=None, tenant_slug=None):
-    with _pool().connection() as con:
-        con.execute(
-            _q('INSERT INTO {tbl} (path, bytes, message) VALUES (%s, %s, %s) '
-               'ON CONFLICT (path) DO UPDATE SET bytes = EXCLUDED.bytes, '
-               'message = EXCLUDED.message, updated_at = now()', 'store_blobs', tenant_slug),
-            (str(path_in_repo), bytes(data), message))
-
-
-def download_bytes(path_in_repo, tenant_slug=None):
-    """Raw bytes, or None when absent — the same contract as the HF backend: a missing attachment
-    degrades to "that file is gone", never to a broken page."""
-    with _pool().connection() as con:
-        row = con.execute(
-            _q('SELECT bytes FROM {tbl} WHERE path = %s', 'store_blobs', tenant_slug),
-            (str(path_in_repo),)).fetchone()
-    return bytes(row[0]) if row else None
-
-
-def delete_path(path_in_repo, tenant_slug=None):
-    """Absent is SUCCESS — deleting what is already gone is the goal (HF backend's contract)."""
-    with _pool().connection() as con:
-        con.execute(_q('DELETE FROM {tbl} WHERE path = %s', 'store_blobs', tenant_slug),
-                    (str(path_in_repo),))
-    return True
-
-
-def flush(name=None, timeout=30.0):
-    """A no-op that returns True: every write above is already committed when it returns. Kept in
-    the interface because QA gates and shutdown hooks call it and must not branch on the backend."""
-    return True
-
-
-def close():
-    """Release the pool (tests, and a process that is shutting down cleanly)."""
-    with _LOCK:
-        if _POOL['pool'] is not None:
-            try:
-                _POOL['pool'].close()
-            finally:
-                _POOL['pool'] = None
-                _POOL['url'] = None
-                _POOL.pop('ok', None)
-
-
-# ---------------------------------------------------------------------------------------------
-# WAVE 20 (R1 / D-4) — THE TENANT-BOUND HANDLE. This is what made the cutover a small change.
-#
-# `core/store.py` grew a CLASS in wave 18 because a tenant can own its own dataset REPO, and
-# `harness.runtime.TenantRuntime` carries one bound instance per tenant. Postgres isolates by
-# SCHEMA instead (`t_<slug>`, see harness/pg/schema.sql's own argument for schema-over-RLS), so
-# the two models meet here: one object, bound to one slug, exposing `core.store.Store`'s methods.
-#
-# ⚠ THE BINDING IS THE POINT. The module functions above default their schema from `AIOS_TENANT`,
-# which is a PROCESS-wide answer to a PER-REQUEST question — correct for a single-tenant worker,
-# wrong for the shared API that serves four tenants from one process. A handle carries its slug
-# explicitly, so a write cannot land in another tenant's schema because some env var was right
-# for the last request. That is the same property `TenantRuntime.store_handle` already gives the
-# HF backend (EXIT-4b proof #3), reached a different way.
-# ---------------------------------------------------------------------------------------------
-class PgStore:
-    """`core.store.Store`'s interface for ONE tenant's schema.
-
-    Deliberately a thin binder over the module functions rather than a reimplementation: every
-    behaviour argument (FOR UPDATE in `update`, absent-is-success in `delete_path`, `fresh`
-    ignored because a SELECT has no cache to bypass) is stated once, up there, and cannot drift
-    between the two entry points.
-    """
-
-    def __init__(self, tenant_slug):
-        self.tenant_slug = str(tenant_slug or '').strip().lower() or 'royal-imports'
-        #: Kept so `Store`-shaped debugging (`repr`, telemetry, the admin panes) reads the same
-        #: on both backends. There is no repo here; the schema is the address.
-        self.repo = f'pg:{_schema_for(self.tenant_slug)}'
-
-    def __repr__(self):
-        return f'<PgStore {self.repo}>'
-
-    def available(self):
-        return available()
-
-    def get(self, name, fresh=False):
-        return get(name, fresh=fresh, tenant_slug=self.tenant_slug)
-
-    def _read_strict(self, name):
-        """Interface parity with the HF Store. There, `get` is lenient (swallows a transient
-        failure) and `_read_strict` opts out so a failed read ABORTS a read-modify-write instead
-        of merging into `{}`. Here `get` ALREADY raises — the leniency it opts out of does not
-        exist — so the strict read is the ordinary one, and saying so beats a second code path."""
-        return get(name, tenant_slug=self.tenant_slug)
-
-    def exists(self, name):
-        return exists(name, tenant_slug=self.tenant_slug)
-
-    def put(self, name, data):
-        return put(name, data, tenant_slug=self.tenant_slug)
-
-    def update(self, name, fn, flush='sync'):
-        return update(name, fn, flush=flush, tenant_slug=self.tenant_slug)
-
-    def upload_bytes(self, path_in_repo, data, message=None):
-        return upload_bytes(path_in_repo, data, message=message, tenant_slug=self.tenant_slug)
-
-    def download_bytes(self, path_in_repo):
-        return download_bytes(path_in_repo, tenant_slug=self.tenant_slug)
-
-    def delete_path(self, path_in_repo):
-        return delete_path(path_in_repo, tenant_slug=self.tenant_slug)
-
-    def flush(self, name=None, timeout=30.0):
-        return True
-
-    def _flush_now_at_exit(self):
-        """The atexit hook `core.store` registers for its instances. Nothing is buffered here —
-        every write above committed before it returned — so this is honestly a no-op rather than
-        an unimplemented method that would raise during interpreter shutdown."""
-        return True
+"""core/store_pg.py — `core/store.py`'s interface, backed by Postgres (X4 / EXIT-2b, 2026-07-30).
+
+THE INTERFACE IS THE CONTRACT, and it is `core/store.py`'s nine functions:
+
+    available() · get(name, fresh=False) · exists(name) · put(name, data)
+    update(name, fn, flush='sync') · upload_bytes(path, data, message=None)
+    download_bytes(path) · delete_path(path) · flush(name=None, timeout=30.0)
+
+Same names, same signatures, same return types, same failure semantics — so switching backends is
+an env var (`STORE_BACKEND=hf|pg`) and not a rewrite of every caller. `core/store_backend.py`
+does the selection; nothing above it needs to know which store it is talking to.
+
+✅ VERIFIED against a real managed Postgres 2026-08-04 (W19: Neon us-east-2; `verify_store_pg.py`
+80/80 INCLUDING the integration half — schema apply, tenant provisioning, jsonb/bytea round-trips,
+80 concurrent FOR-UPDATE writes — run from HF egress; the owner's local network resets TLS:5432).
+The CUTOVER remains parked behind C1e's triggers and this module is not the default backend.
+Without `DATABASE_URL` the gate still SKIPS its integration half LOUDLY, never silently.
+The schema is `harness/pg/schema.sql`. Sequenced around the blocker, never stubbed past it.
+
+WHAT POSTGRES FIXES, precisely (C1c — these are the reasons, not a preference):
+  * **`get()` is cache-first on the HF store**, so a write from another process is invisible to a
+    running app until restart. Observed live in wave 11. Here a read is a SELECT: cross-process
+    coherence is the default rather than a thing to remember.
+  * **`update()` was read-modify-write with no concurrency control** — two writers raced and the
+    loser vanished silently. Here it runs inside ONE transaction with `SELECT … FOR UPDATE`, so
+    the second writer waits and then sees the first writer's value.
+  * **A write was an HTTP commit** against a 256-commits/hour repo budget, which is why the hot
+    path needed a coalescing async flusher at all. A Postgres write is a write; `flush='async'`
+    stays in the signature and becomes a no-op, because there is nothing to coalesce.
+
+⚠ ONE DELIBERATE DIFFERENCE FROM THE HF BACKEND, and it is a fix. `store.get()` swallows transient
+read failures and hands back a cached-or-empty dict, because a display read must not break a page.
+That leniency is exactly what wiped the user registry once (an empty read merged into a write), and
+`_read_strict` exists to opt out of it. Postgres has no equivalent "the network blipped" state
+worth hiding: a connection failure RAISES from `get()` here. Callers that must not break on a read
+should catch it — silently returning `{}` from a database that is simply unreachable is how an
+empty dict gets written back over real data.
+"""
+import json
+import os
+import threading
+
+_URL_ENV = 'DATABASE_URL'
+_LOCK = threading.RLock()
+_POOL = {'pool': None, 'url': None, 'schema': None}
+
+
+def _url():
+    return os.environ.get(_URL_ENV) or None
+
+
+def _schema_for(tenant_slug=None):
+    """`t_<slug>` with `-` normalised to `_` (a hyphen is not legal in an unquoted identifier).
+
+    Mirrors `control.provision_tenant_schema` exactly — the two MUST agree or a write lands in a
+    schema the DDL never created. `AIOS_TENANT` names the tenant this process serves; it defaults
+    to tenant #0 so the default behaviour is unchanged, the same rule `harness.datastore.path_for`
+    follows for the DuckDB filename.
+    """
+    slug = (tenant_slug or os.environ.get('AIOS_TENANT') or 'royal-imports').strip().lower()
+    return 't_' + slug.replace('-', '_')
+
+
+def _pool():
+    """The psycopg connection pool, opened once per process.
+
+    psycopg is imported LAZILY and only here: `STORE_BACKEND=hf` must not require the dependency
+    to be installed at all, which is what keeps this file safe to commit before B-3 unblocks.
+    """
+    with _LOCK:
+        url = _url()
+        if not url:
+            raise RuntimeError(
+                f'{_URL_ENV} is not set — the Postgres store backend has nothing to connect to.')
+        if _POOL['pool'] is not None and _POOL['url'] == url:
+            return _POOL['pool']
+        try:
+            from psycopg_pool import ConnectionPool
+        except ImportError as e:                  # pragma: no cover - depends on B-3
+            raise RuntimeError(
+                'STORE_BACKEND=pg needs psycopg[binary,pool]. It is deliberately NOT in '
+                'requirements.txt until the database exists (owner blocker B-3), so that the '
+                'default hf backend installs nothing it does not use.') from e
+        if _POOL['pool'] is not None:
+            try:
+                _POOL['pool'].close()
+            except Exception:
+                pass
+        # min_size=0 so a process that never touches the store opens no connection at all — the
+        # shared API serves plenty of requests (health, static, a cached payload) that never read.
+        _POOL['pool'] = ConnectionPool(url, min_size=0, max_size=8, open=True, timeout=10.0)
+        _POOL['url'] = url
+        return _POOL['pool']
+
+
+def available():
+    """True when a connection can actually be MADE, not merely when a URL is configured.
+
+    `core.store.available()` only checks for a token, which is all it can cheaply do. Here the
+    honest answer needs a round-trip, so the result is memoised per process: callers use this to
+    decide whether to degrade the UI, and a `SELECT 1` per render would be absurd.
+    """
+    if not _url():
+        return False
+    if _POOL.get('ok'):
+        return True
+    try:
+        with _pool().connection() as con:
+            con.execute('SELECT 1')
+        _POOL['ok'] = True
+        return True
+    except Exception:
+        return False
+
+
+def _table(kind, tenant_slug=None):
+    """`"t_slug"."store_kv"` — the qualified table, safely quoted."""
+    from psycopg import sql
+    return sql.SQL('{}.{}').format(sql.Identifier(_schema_for(tenant_slug)),
+                                   sql.Identifier(kind))
+
+
+def _q(template, kind, tenant_slug=None):
+    """Compose `template` with `{tbl}` = the QUALIFIED table and `{bare}` = the table name alone.
+
+    ⚠ THE TWO ARE NOT INTERCHANGEABLE, and getting it wrong is a runtime syntax error nothing
+    local would catch (no database here — owner blocker B-3). Inside `ON CONFLICT … DO UPDATE`,
+    Postgres refers to the conflicting row by the table's ALIAS, which defaults to the bare
+    table name: `store_kv.rev` is valid, `t_royal_imports.store_kv.rev` is not. So the FROM
+    position takes `{tbl}` and the DO-UPDATE position takes `{bare}`.
+
+    Identifiers go through `psycopg.sql.Identifier`, so the schema name — derived from a tenant
+    slug — cannot be an injection vector even though it is interpolated. The slug is ALSO
+    regex-constrained at its source (`control.tenants`), which is the belt to this brace.
+    """
+    from psycopg import sql
+    return sql.SQL(template).format(tbl=_table(kind, tenant_slug),
+                                    bare=sql.Identifier(kind))
+
+
+def get(name, fresh=False, tenant_slug=None):
+    """The value stored under `name`, or `{}` when the key is genuinely absent.
+
+    `fresh` is accepted and IGNORED: it exists in the HF signature to bypass a process cache, and
+    there is no cache here — every read is a SELECT. Keeping the parameter means callers do not
+    branch on the backend.
+    """
+    with _pool().connection() as con:
+        row = con.execute(
+            _q('SELECT value FROM {tbl} WHERE key = %s', 'store_kv', tenant_slug),
+            (str(name),)).fetchone()
+    return dict(row[0]) if row and isinstance(row[0], dict) else (row[0] if row else {})
+
+
+def exists(name, tenant_slug=None):
+    """True/False — and unlike the HF backend this is NEVER "True on uncertainty".
+
+    `core.store.exists` returns True on any error so a caller that would seed the store cannot
+    clobber a registry it merely failed to reach. That guard exists because a FILE HOST cannot
+    distinguish "absent" from "unreachable". Postgres can: an absent row is a fact, and an
+    unreachable server raises instead of answering.
+    """
+    with _pool().connection() as con:
+        row = con.execute(
+            _q('SELECT 1 FROM {tbl} WHERE key = %s', 'store_kv', tenant_slug),
+            (str(name),)).fetchone()
+    return row is not None
+
+
+def put(name, data, tenant_slug=None):
+    with _pool().connection() as con:
+        con.execute(
+            _q('INSERT INTO {tbl} (key, value) VALUES (%s, %s::jsonb) '
+               'ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, '
+               'updated_at = now(), rev = {bare}.rev + 1', 'store_kv', tenant_slug),
+            (str(name), json.dumps(data)))
+    return data
+
+
+def update(name, fn, flush='sync', tenant_slug=None):
+    """Read-modify-write inside ONE transaction, with the row LOCKED for the duration.
+
+    This is the operation the HF backend could not make safe. There, `update` read over HTTP,
+    applied `fn`, and uploaded — so two concurrent writers both read the old value and the second
+    upload silently discarded the first writer's change. `SELECT … FOR UPDATE` makes the second
+    writer WAIT and then apply `fn` to the first writer's result, which is what "read-modify-write"
+    was always supposed to mean.
+
+    `flush` is accepted and ignored (see the module docstring): there is no commit budget to
+    coalesce against, so 'async' has nothing to defer.
+    """
+    with _pool().connection() as con:
+        with con.transaction():
+            row = con.execute(
+                _q('SELECT value FROM {tbl} WHERE key = %s FOR UPDATE',
+                   'store_kv', tenant_slug),
+                (str(name),)).fetchone()
+            data = dict(row[0]) if row and isinstance(row[0], dict) else (row[0] if row else {})
+            result = fn(data)
+            data = result if result is not None else data
+            con.execute(
+                _q('INSERT INTO {tbl} (key, value) VALUES (%s, %s::jsonb) '
+                   'ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, '
+                   'updated_at = now(), rev = {bare}.rev + 1', 'store_kv', tenant_slug),
+                (str(name), json.dumps(data)))
+    return data
+
+
+def upload_bytes(path_in_repo, data, message=None, tenant_slug=None):
+    with _pool().connection() as con:
+        con.execute(
+            _q('INSERT INTO {tbl} (path, bytes, message) VALUES (%s, %s, %s) '
+               'ON CONFLICT (path) DO UPDATE SET bytes = EXCLUDED.bytes, '
+               'message = EXCLUDED.message, updated_at = now()', 'store_blobs', tenant_slug),
+            (str(path_in_repo), bytes(data), message))
+
+
+def download_bytes(path_in_repo, tenant_slug=None):
+    """Raw bytes, or None when absent — the same contract as the HF backend: a missing attachment
+    degrades to "that file is gone", never to a broken page."""
+    with _pool().connection() as con:
+        row = con.execute(
+            _q('SELECT bytes FROM {tbl} WHERE path = %s', 'store_blobs', tenant_slug),
+            (str(path_in_repo),)).fetchone()
+    return bytes(row[0]) if row else None
+
+
+def delete_path(path_in_repo, tenant_slug=None):
+    """Absent is SUCCESS — deleting what is already gone is the goal (HF backend's contract)."""
+    with _pool().connection() as con:
+        con.execute(_q('DELETE FROM {tbl} WHERE path = %s', 'store_blobs', tenant_slug),
+                    (str(path_in_repo),))
+    return True
+
+
+def flush(name=None, timeout=30.0):
+    """A no-op that returns True: every write above is already committed when it returns. Kept in
+    the interface because QA gates and shutdown hooks call it and must not branch on the backend."""
+    return True
+
+
+def close():
+    """Release the pool (tests, and a process that is shutting down cleanly)."""
+    with _LOCK:
+        if _POOL['pool'] is not None:
+            try:
+                _POOL['pool'].close()
+            finally:
+                _POOL['pool'] = None
+                _POOL['url'] = None
+                _POOL.pop('ok', None)
+
+
+# ---------------------------------------------------------------------------------------------
+# WAVE 20 (R1 / D-4) — THE TENANT-BOUND HANDLE. This is what made the cutover a small change.
+#
+# `core/store.py` grew a CLASS in wave 18 because a tenant can own its own dataset REPO, and
+# `harness.runtime.TenantRuntime` carries one bound instance per tenant. Postgres isolates by
+# SCHEMA instead (`t_<slug>`, see harness/pg/schema.sql's own argument for schema-over-RLS), so
+# the two models meet here: one object, bound to one slug, exposing `core.store.Store`'s methods.
+#
+# ⚠ THE BINDING IS THE POINT. The module functions above default their schema from `AIOS_TENANT`,
+# which is a PROCESS-wide answer to a PER-REQUEST question — correct for a single-tenant worker,
+# wrong for the shared API that serves four tenants from one process. A handle carries its slug
+# explicitly, so a write cannot land in another tenant's schema because some env var was right
+# for the last request. That is the same property `TenantRuntime.store_handle` already gives the
+# HF backend (EXIT-4b proof #3), reached a different way.
+# ---------------------------------------------------------------------------------------------
+class PgStore:
+    """`core.store.Store`'s interface for ONE tenant's schema.
+
+    Deliberately a thin binder over the module functions rather than a reimplementation: every
+    behaviour argument (FOR UPDATE in `update`, absent-is-success in `delete_path`, `fresh`
+    ignored because a SELECT has no cache to bypass) is stated once, up there, and cannot drift
+    between the two entry points.
+    """
+
+    def __init__(self, tenant_slug):
+        self.tenant_slug = str(tenant_slug or '').strip().lower() or 'royal-imports'
+        #: Kept so `Store`-shaped debugging (`repr`, telemetry, the admin panes) reads the same
+        #: on both backends. There is no repo here; the schema is the address.
+        self.repo = f'pg:{_schema_for(self.tenant_slug)}'
+
+    def __repr__(self):
+        return f'<PgStore {self.repo}>'
+
+    def available(self):
+        return available()
+
+    def get(self, name, fresh=False):
+        return get(name, fresh=fresh, tenant_slug=self.tenant_slug)
+
+    def _read_strict(self, name):
+        """Interface parity with the HF Store. There, `get` is lenient (swallows a transient
+        failure) and `_read_strict` opts out so a failed read ABORTS a read-modify-write instead
+        of merging into `{}`. Here `get` ALREADY raises — the leniency it opts out of does not
+        exist — so the strict read is the ordinary one, and saying so beats a second code path."""
+        return get(name, tenant_slug=self.tenant_slug)
+
+    def exists(self, name):
+        return exists(name, tenant_slug=self.tenant_slug)
+
+    def put(self, name, data):
+        return put(name, data, tenant_slug=self.tenant_slug)
+
+    def update(self, name, fn, flush='sync'):
+        return update(name, fn, flush=flush, tenant_slug=self.tenant_slug)
+
+    def upload_bytes(self, path_in_repo, data, message=None):
+        return upload_bytes(path_in_repo, data, message=message, tenant_slug=self.tenant_slug)
+
+    def download_bytes(self, path_in_repo):
+        return download_bytes(path_in_repo, tenant_slug=self.tenant_slug)
+
+    def delete_path(self, path_in_repo):
+        return delete_path(path_in_repo, tenant_slug=self.tenant_slug)
+
+    def flush(self, name=None, timeout=30.0):
+        return True
+
+    def _flush_now_at_exit(self):
+        """The atexit hook `core.store` registers for its instances. Nothing is buffered here —
+        every write above committed before it returned — so this is honestly a no-op rather than
+        an unimplemented method that would raise during interpreter shutdown."""
+        return True

platform/core/table_store.py

@@ -1,595 +1,595 @@
-"""The generic per-user TABLE WORKSPACE store — the persistence half of the table-page factory.
-
-One durable store key holds one table OBJECT's per-user Airtable-style state:
-
-    {username: {'views':    {view_id: SavedView},
-                'fields':   {field_key: Field},        # notes + custom_ + measure_ strata
-                'overlays': {str(pid): {field_key: value}}}}
-
-`make(table_key)` returns the six operations a table page's host loop needs, closed over that
-key. The Customer table's ops (`modules/customer_data.py`, key 'customer_table_workspace') are
-these exact functions — the logic MOVED here 2026-07-27 so that duplicating the Customer table
-pattern to a new object is a registry row + a config, not a copy of the store plumbing
-(owner directive: the table-page factory).
-
-A LIST (membership/formula semantics) is deliberately a different store from a VIEW
-(presentation/query state) — see modules/customer_data.py's customer_lists key.
-"""
-import core.store as store
-
-#: Wave-9 I17 — the SHARED bucket. Views whose permissions make them visible to anyone but
-#: their creator live here instead of in a personal workspace, under a key that cannot collide
-#: with a username (usernames come from core/users.py and are never dunder-wrapped; `is_shared`
-#: guards it anyway). ONE HOME PER VIEW, never both: a view moved to personal is REMOVED from
-#: here, and a view shared is removed from its creator's workspace. Two homes would mean two
-#: divergent copies the moment either was edited.
-SHARED_KEY = '__shared__'
-
-
-def _may_see(view, viewer, is_admin=False):
-    """Visibility for ONE shared view, fail-closed.
-
-    'collaborative' = everyone who can already open the module (the caller has gated that).
-    'users'         = the named users, plus the creator, plus admins — an admin who could not
-                      see a view could not administer it either.
-    Anything unrecognised returns False rather than defaulting open: an unreadable permission
-    must never widen access ([[aios-permissioning]] — no fail-open defaults).
-    """
-    if not isinstance(view, dict):
-        return False
-    if view.get('createdBy') == viewer or is_admin:
-        return True
-    perms = view.get('permissions') or {}
-    edit = perms.get('edit')
-    if edit == 'collaborative':
-        return True
-    if edit == 'users':
-        return viewer in set(perms.get('users') or ())
-    return False                      # 'personal', absent, or junk
-
-
-def _may_edit(view, viewer, is_admin=False):
-    """Who may WRITE a shared view. Same set as visibility today — the owner's item asks 'who
-    can edit' and lists who 'can have access', i.e. seeing and editing are one grant. Kept as a
-    separate function so they can diverge (a future read-only share) without hunting callers."""
-    return _may_see(view, viewer, is_admin)
-
-
-def _may_administer(view, viewer, is_admin=False):
-    """Who may change a view's PERMISSIONS, or delete it: the creator or an admin ONLY.
-
-    Deliberately narrower than _may_edit. If a collaborator could rewrite `permissions` they
-    could grant themselves sole ownership of somebody else's view, or quietly widen a
-    users-scoped view to everyone — the classic privilege-escalation-by-edit hole.
-    """
-    if not isinstance(view, dict):
-        return False
-    return bool(is_admin) or view.get('createdBy') == viewer
-
-
-def is_shared(view):
-    """A view belongs in the shared bucket when its permissions reach beyond its creator."""
-    return ((view or {}).get('permissions') or {}).get('edit') in ('collaborative', 'users')
-
-
-def _unique_name(wanted, existing, *, fallback='Untitled', max_len=120):
-    """Allocate one human-facing name inside a store.update transaction.
-
-    Keys/ids remain structural identity.  Names compare case-insensitively after collapsing
-    whitespace, because those variants are indistinguishable in the UI.  This helper belongs
-    in the store layer: allocating from a pre-write snapshot lets two concurrent requests both
-    choose the same free name before either write lands.
-    """
-    limit = max(1, int(max_len))
-
-    def _clean(value):
-        return ' '.join(str(value or '').split())
-
-    base = (_clean(wanted) or _clean(fallback) or 'Untitled')[:limit].rstrip()
-    taken = {_clean(value).casefold() for value in existing if _clean(value)}
-    if base.casefold() not in taken:
-        return base
-    index = 2
-    while True:
-        suffix = f' {index}'
-        stem = base[:max(0, limit - len(suffix))].rstrip()
-        candidate = f'{stem}{suffix}' if stem else str(index)[-limit:]
-        if candidate.casefold() not in taken:
-            return candidate
-        index += 1
-
-
-class TableStore:
-    """The six store operations for one table object's workspace, closed over its store key.
-
-    `st` (wave 18, C3-UT) is the STORE HANDLE — anything exposing `get(name)` /
-    `update(name, fn, flush=)`. Default = `core.store` (tenant #0, every existing caller,
-    zero behaviour change). The API passes the session's `TenantRuntime`, whose accessors
-    apply the tenant prefix / repo binding — which is what makes a user table created by a
-    Nurilab admin land in Nurilab's store instead of Royal's.
-    """
-
-    def __init__(self, table_key, st=None):
-        self.table_key = table_key
-        self._st = st if st is not None else store
-
-    @property
-    def st(self):
-        """The bound store handle — for SIBLING registries (core/shares) that must read the
-        same tenant's buckets this workspace lives in (wave 21, C1)."""
-        return self._st
-
-    def find_view(self, view_id):
-        """`(owner_username, view)` for a view living in ANY personal stratum, else None.
-
-        ⭐ Wave 21 (item 9, C1): the R10 grant registry names bare ids, so projecting a granted
-        view means locating the OWNER's record inside this topic's bucket. Personal strata
-        only — the `__shared__` bucket has its own read path (`shared_views`), and serving one
-        view from two finders is how two copies drift."""
-        vid = str(view_id or '').strip()
-        if not vid:
-            return None
-        try:
-            data = self._st.get(self.table_key) or {}
-        except Exception:
-            return None
-        for username, ws in data.items():
-            if username == SHARED_KEY or not isinstance(ws, dict):
-                continue
-            v = (ws.get('views') or {}).get(vid)
-            if isinstance(v, dict):
-                return str(username), dict(v)
-        return None
-
-    def find_folder(self, folder_id):
-        """`(owner_username, folder_row, {view_id: view})` for a VIEWS folder living in any
-        personal stratum, else None. `find_view`'s sibling, and here for the same reason.
-
-        ⭐ D-37 (wave 20's R10 remainder, closed 2026-08-05): the grant registry accepts kind
-        `folder` and has since wave 20, but only the VIEW kind was ever projected — so "share
-        this folder with Karen" recorded a row, listed under Shared with me, and put nothing on
-        Karen's screen. Projecting a folder means two lookups the view path does not need: WHO
-        owns it, and WHICH views are filed in it. Folder membership lives in the owner's
-        `itemFolders` map (item id -> folder id), never on the view record, so the views are
-        found by asking that map rather than by reading a list off the folder.
-
-        Views only (`folders['views']`): the cohort surface has its own store and its own
-        sharing question, and answering both here would make one function mean two things.
-        """
-        fid = str(folder_id or '').strip()
-        if not fid:
-            return None
-        try:
-            data = self._st.get(self.table_key) or {}
-        except Exception:
-            return None
-        for username, ws in data.items():
-            if username == SHARED_KEY or not isinstance(ws, dict):
-                continue
-            rows = (ws.get('folders') or {}).get('views') or []
-            hit = next((f for f in rows
-                        if isinstance(f, dict) and str(f.get('id') or '') == fid), None)
-            if not hit:
-                continue
-            # ⚠ `itemFolders` IS KEYED BY SURFACE FIRST (`{'views': {itemId: folderId}, …}`) —
-            # reading item ids off the top level finds the surface names instead and matches
-            # nothing, so the projection silently returns an EMPTY folder and the feature looks
-            # exactly as broken as it was before the fix. Caught by this change's own gate,
-            # which is the entire argument for writing one.
-            placed = (ws.get('itemFolders') or {}).get('views') or {}
-            views = ws.get('views') or {}
-            inside = {str(vid): dict(v) for vid, v in views.items()
-                      if isinstance(v, dict) and str(placed.get(str(vid)) or '') == fid}
-            return str(username), dict(hit), inside
-        return None
-
-    # ---------------------------------------------------------------- read
-    def workspace(self, username, consume_corrections=True):
-        """One user's durable workspace: always the full three-strata shape."""
-        try:
-            data = self._st.get(self.table_key) or {}
-            ws = data.get(username, {}) or {}
-            # A collision acknowledgement is protocol state, not part of a field definition.
-            # Consume it with the first fresh workspace payload after the correcting write,
-            # then splice a bounded copy into that payload only.  Keeping it out of `fields`
-            # prevents an old request id surviving forever and overriding a later rename.
-            corrections = {}
-            if consume_corrections and ws.get('fieldCorrections'):
-                def _take(current):
-                    current_ws = current.get(username) or {}
-                    pending = current_ws.get('fieldCorrections') or {}
-                    corrections.update({
-                        str(key)[:80]: dict(value)
-                        for key, value in pending.items()
-                        if isinstance(value, dict)
-                    })
-                    current_ws.pop('fieldCorrections', None)
-                    return current
-
-                data = self._st.update(self.table_key, _take, flush='async')
-                ws = (data or {}).get(username, {}) or {}
-        except Exception:
-            ws = {}
-            corrections = {}
-        fields = {
-            key: dict(value) if isinstance(value, dict) else value
-            for key, value in (ws.get('fields') or {}).items()
-        }
-        for key, ack in corrections.items():
-            field = fields.get(key)
-            accepted_label = str(ack.get('label') or '')[:120]
-            requested_label = str(ack.get('labelCorrectedFrom') or '')[:120]
-            correction_id = str(ack.get('labelCorrectionId') or '')[:180]
-            # A newer field write clears/replaces the pending ack in the SAME transaction.
-            # The label check is an extra belt against ever attaching a stale ack to a newer
-            # definition if a future store implementation weakens that ordering.
-            if (isinstance(field, dict) and accepted_label
-                    and str(field.get('label') or '') == accepted_label
-                    and requested_label and correction_id):
-                field['labelCorrectedFrom'] = requested_label
-                field['labelCorrectionId'] = correction_id
-        out = {
-            'views': dict(ws.get('views') or {}),
-            'fields': fields,
-            'overlays': dict(ws.get('overlays') or {}),
-            # wave-8 I11 (C4): folders over the saved views / cohorts sidebars. A FOURTH
-            # stratum rather than a key on each item — see aios_grid.clean_folders for why
-            # (a cohort lives in another store, and filing is an organising act, not part of
-            # what a view is). Absent for every workspace saved before this wave, which is
-            # exactly "no folders yet".
-            'folders': dict(ws.get('folders') or {}),
-            'itemFolders': dict(ws.get('itemFolders') or {}),
-        }
-        # 2026-07-31 (owner item 3): WHERE THE USER LEFT OFF survives a new browser. The
-        # client's localStorage copy wins when present; this is the server's answer for a
-        # fresh profile, which used to fall all the way to the system default view.
-        if ws.get('activeViewId'):
-            out['activeViewId'] = str(ws['activeViewId'])
-        # Wave 2026-08-02 (C-LAYOUT): the per-user record-detail field order. A fifth
-        # stratum, absent until the user first reorders — exactly "default order".
-        if isinstance(ws.get('recordLayout'), dict):
-            out['recordLayout'] = dict(ws['recordLayout'])
-        return out
-
-    # ---------------------------------------------------------------- write
-    def _update(self, username, change):
-        def _up(data):
-            ws = data.setdefault(username, {})
-            ws.setdefault('views', {})
-            ws.setdefault('fields', {})
-            ws.setdefault('overlays', {})
-            ws.setdefault('folders', {})
-            ws.setdefault('itemFolders', {})
-            change(ws)
-            return data
-        # flush='async' (wave-7 W3): this is THE hot path — every autosaved filter tweak,
-        # column note and typed overlay cell lands here inside the component round-trip, and
-        # the historical synchronous hub commit cost seconds per edit. The mutation applies to
-        # the in-process cache (read-your-writes for every subsequent render); the hub write
-        # coalesces in the background. Registry/auth writes elsewhere stay flush='sync'.
-        return self._st.update(self.table_key, _up, flush='async')
-
-    def rename_choice_values(self, username, change):
-        """Apply an arbitrary workspace rewrite (wave 20, item 15 / C-RENAME).
-
-        ⚠ NAMED FOR ITS ONE CALLER RATHER THAN EXPOSED AS A GENERIC `mutate`, deliberately. A
-        public "do anything to the workspace" method is an invitation to put write logic in
-        callers instead of here, and every OTHER method on this class exists precisely because
-        that logic belongs in one place. Renaming a choice is the one operation that must touch
-        three strata AT ONCE — the field's `choices`, the cells in `overlays`, and the views that
-        filter or colour by the old value — inside a SINGLE transaction, because a rename that
-        updated the cells and not the filters would leave a saved view matching nothing.
-
-        `change(ws)` receives the whole workspace with every stratum pre-created (see `_update`).
-        """
-        return self._update(username, change)
-
-    def save_active_view(self, username, view_id):
-        """Remember which view this user last opened (owner item 3, 2026-07-31).
-
-        Presentation state, not authorisation: the READ side re-validates the id against what
-        the caller may actually see, so a stale or foreign id degrades to the default view
-        rather than granting anything. Stored per user like every other stratum.
-        """
-        vid = str(view_id or '').strip()[:120]
-        if not vid or username == SHARED_KEY:
-            return
-
-        def _set(ws):
-            ws['activeViewId'] = vid
-        self._update(username, _set)
-
-    def save_record_layout(self, username, order):
-        """The per-user RECORD-DETAIL field order (wave 2026-08-02, C-LAYOUT).
-
-        Presentation state for ONE surface — the record modal. Deliberately not view config:
-        the owner's ask is per-user, not per-view, and it must never reorder grid columns.
-        The event handler validated keys against the live field set; the wire re-validates at
-        serve time (aios_grid.workspace_wire), so a deleted field cannot outlive itself here.
-        An empty order clears the stratum back to "default order".
-        """
-        if username == SHARED_KEY:
-            return
-        clean, seen = [], set()
-        for key in (order or [])[:200]:
-            key = str(key or '').strip()[:80]
-            if key and key not in seen:
-                seen.add(key)
-                clean.append(key)
-
-        def _set(ws):
-            if clean:
-                ws['recordLayout'] = {'order': clean}
-            else:
-                ws.pop('recordLayout', None)
-
-        self._update(username, _set)
-
-    def save_folders(self, username, folders, item_folders):
-        """Replace the folder stratum wholesale (wave-8 I11).
-
-        Wholesale rather than per-folder because the caller has ALREADY validated the complete
-        picture through aios_grid.clean_folders / clean_item_folders, and those two are
-        interdependent: a placement is only legal while its folder exists, so committing them
-        separately would leave a window where a reader sees an item filed into a folder that is
-        not there yet. One write, one consistent state.
-        """
-        def _set(ws):
-            ws['folders'] = dict(folders or {})
-            ws['itemFolders'] = dict(item_folders or {})
-        self._update(username, _set)
-
-    def save_view_order(self, username, order):
-        """⭐ WAVE-27 item 5 (contract C7) — this user's own ORDER for the views rail.
-
-        Wholesale, like `save_folders` above and for the same reason: the client sends the full
-        list it is looking at, not a delta, because a partial order cannot say where an UNNAMED
-        view went.
-
-        ⛔ PER USER, and it belongs in this stratum rather than on the view records themselves.
-        `aios_grid`'s own folder note argues it out for placements and every word applies: an
-        arrangement is a per-user ORGANISING act, not part of what a view IS — so keeping it out
-        of the view config means duplicating, sharing or exporting a view does not drag one
-        person's rail position along with it. It also means a SHARED view can sit in a different
-        place for each person who can see it, which is the only coherent answer once two people
-        share one view.
-
-        An empty list CLEARS the arrangement (back to server order) rather than storing `[]`.
-        """
-        def _set(ws):
-            clean = []
-            seen = set()
-            for vid in (order or []):
-                vid = str(vid).strip()[:120]
-                if vid and vid not in seen:
-                    seen.add(vid)
-                    clean.append(vid)
-            if clean:
-                ws['viewOrder'] = clean
-            else:
-                ws.pop('viewOrder', None)
-        self._update(username, _set)
-
-    def shared_views(self, viewer, is_admin=False):
-        """Every SHARED view this viewer may see, by id (wave-9 I17).
-
-        Read-only and independent of the viewer's own workspace: the caller merges. Returns
-        only what `_may_see` allows, so a caller cannot accidentally render somebody else's
-        personal view by forgetting to filter.
-        """
-        try:
-            bucket = ((self._st.get(self.table_key) or {}).get(SHARED_KEY) or {}).get('views') or {}
-        except Exception:
-            return {}
-        return {vid: dict(v) for vid, v in bucket.items()
-                if _may_see(v, viewer, is_admin)}
-
-    def shared_view(self, view_id):
-        """One shared view RAW — no visibility filter. For authorisation decisions only: a
-        caller must know a view exists and who owns it before it can decide whether the actor
-        may touch it. Never hand the result to a renderer without checking `_may_see`."""
-        try:
-            return ((self._st.get(self.table_key) or {}).get(SHARED_KEY) or {}
-                    ).get('views', {}).get(str(view_id))
-        except Exception:
-            return None
-
-    def save_view(self, username, view, shared=None, reserved_names=(), is_admin=False):
-        """Upsert a SavedView into its ONE home — personal workspace or the shared bucket.
-
-        `shared` defaults to reading the view's own permissions (`is_shared`). Whichever home
-        it lands in, the view is REMOVED from the other, so a view can never exist as two
-        copies that diverge on the next edit.
-
-        ⚠ AUTHORISATION IS THE CALLER'S JOB and must happen BEFORE this is called — this layer
-        moves data and does not know who is asking. `_cl_handle_one` is the wall.
-        """
-        view_id = str((view or {}).get('id') or '').strip()
-        if not view_id:
-            raise ValueError('view id is required')
-        if username == SHARED_KEY:
-            raise ValueError('reserved username')
-        to_shared = is_shared(view) if shared is None else bool(shared)
-        requested = dict(view)
-        accepted = {}
-
-        def _up(data):
-            # View names are tenant-global: every personal workspace plus the shared bucket.
-            # This deliberately includes views the actor cannot see.  The only disclosed fact
-            # is that a display name is already taken, while the categorical "no duplicate
-            # view names" contract remains true when a personal view is later shared.
-            names = list(reserved_names or ())
-            for workspace in data.values():
-                if not isinstance(workspace, dict):
-                    continue
-                names.extend(
-                    value.get('name')
-                    for candidate_id, value in (workspace.get('views') or {}).items()
-                    if candidate_id != view_id and isinstance(value, dict)
-                )
-            payload = dict(requested)
-            payload['name'] = _unique_name(payload.get('name'), names)
-            accepted.clear()
-            accepted.update(payload)
-            if to_shared:
-                bucket = data.setdefault(SHARED_KEY, {})
-                bucket.setdefault('views', {})[view_id] = payload
-                # it may have lived in the creator's workspace before being shared
-                owner = data.get(payload.get('createdBy') or username) or {}
-                (owner.get('views') or {}).pop(view_id, None)
-            else:
-                ws = data.setdefault(username, {})
-                ws.setdefault('views', {})[view_id] = payload
-                (data.get(SHARED_KEY, {}).get('views') or {}).pop(view_id, None)
-            return data
-
-        self._st.update(self.table_key, _up, flush='async')
-        return dict(accepted)
-
-    def delete_view(self, username, view_id):
-        """Delete a custom/list view override. The system all-rows view is guarded by caller.
-
-        Removes from BOTH homes: the caller has already authorised the delete, and leaving a
-        stale copy in the other bucket would resurrect the view on the next read.
-        """
-        vid = str(view_id)
-
-        def _up(data):
-            (data.get(username, {}).get('views') or {}).pop(vid, None)
-            (data.get(SHARED_KEY, {}).get('views') or {}).pop(vid, None)
-            return data
-
-        self._st.update(self.table_key, _up, flush='async')
-
-    def save_field(self, username, field, reserved_names=(), correction_id=None):
-        """Persist a column note or a user-created (custom_/measure_) field definition."""
-        key = str((field or {}).get('key') or '').strip()
-        if not key:
-            raise ValueError('field key is required')
-        requested = dict(field)
-        accepted = {}
-
-        def _save(ws):
-            names = list(reserved_names or ())
-            names.extend(
-                value.get('label')
-                for candidate_key, value in (ws.get('fields') or {}).items()
-                if candidate_key != key and isinstance(value, dict)
-            )
-            payload = dict(requested)
-            payload.pop('labelCorrectedFrom', None)
-            payload.pop('labelCorrectionId', None)
-            requested_label = ' '.join(
-                str(payload.get('label') or 'Untitled').split())[:120].rstrip()
-            payload['label'] = _unique_name(requested_label, names)
-            corrections = ws.setdefault('fieldCorrections', {})
-            corrections.pop(key, None)
-            if payload['label'] != requested_label and correction_id:
-                corrections[key] = {
-                    'label': payload['label'],
-                    'labelCorrectedFrom': requested_label,
-                    'labelCorrectionId': str(correction_id)[:180],
-                }
-            if not corrections:
-                ws.pop('fieldCorrections', None)
-            accepted.clear()
-            accepted.update(payload)
-            # A cleared note on an immutable source field returns to the canonical schema
-            # instead of leaving a meaningless override row. Custom fields remain even with
-            # an empty note — and so does a PRESET field carrying a measure-window override
-            # (wave-2 item 8) or a DISPLAY-format override (wave-5 item 10): the note may be
-            # empty but the period/format is real user state.
-            if (not payload.get('custom') and not str(payload.get('note') or '').strip()
-                    and not isinstance(payload.get('measure'), dict)
-                    and not isinstance(payload.get('format'), dict)):
-                ws['fields'].pop(key, None)
-            else:
-                ws['fields'][key] = payload
-
-        self._update(username, _save)
-        return dict(accepted)
-
-    def duplicate_field(self, username, source_key, new_key, field,
-                        reserved_names=(), correction_id=None):
-        """Clone a user-created field in ONE store transaction (wave-5 item 1): the new
-        definition plus — for `custom_` overlay sources only — every stored cell value under
-        the source key. One transaction, because a def without its values (or values without a
-        def) is exactly the orphan state delete_field exists to prevent, in reverse.
-        The caller validated both keys (same created stratum) and stamped the clone's
-        createdBy; this layer only moves data."""
-        source_key = str(source_key or '').strip()
-        new_key = str(new_key or '').strip()
-        if not source_key or not new_key or source_key == new_key:
-            raise ValueError('duplicate_field needs two distinct keys')
-        requested = dict(field)
-        accepted = {}
-
-        def _dup(ws):
-            names = list(reserved_names or ())
-            names.extend(
-                value.get('label')
-                for candidate_key, value in (ws.get('fields') or {}).items()
-                if candidate_key != new_key and isinstance(value, dict)
-            )
-            payload = dict(requested)
-            payload.pop('labelCorrectedFrom', None)
-            payload.pop('labelCorrectionId', None)
-            requested_label = ' '.join(
-                str(payload.get('label') or 'Untitled').split())[:120].rstrip()
-            payload['label'] = _unique_name(requested_label, names)
-            corrections = ws.setdefault('fieldCorrections', {})
-            corrections.pop(new_key, None)
-            if payload['label'] != requested_label and correction_id:
-                corrections[new_key] = {
-                    'label': payload['label'],
-                    'labelCorrectedFrom': requested_label,
-                    'labelCorrectionId': str(correction_id)[:180],
-                }
-            if not corrections:
-                ws.pop('fieldCorrections', None)
-            accepted.clear()
-            accepted.update(payload)
-            ws['fields'][new_key] = payload
-            if source_key.startswith('custom_'):
-                for row in ws['overlays'].values():
-                    if isinstance(row, dict) and source_key in row:
-                        row[new_key] = row[source_key]
-
-        self._update(username, _dup)
-        return dict(accepted)
-
-    def delete_field(self, username, key):
-        """Delete a USER-CREATED field definition outright (owner gap closed 2026-07-27).
-
-        Only the created strata ever reach here (`custom_` overlay fields, `measure_` formula
-        columns — the caller enforces the prefix). The stored overlay VALUES for the key are
-        scrubbed with it: a deleted column's cells must not linger as orphan data that would
-        silently resurface if the key were ever reused. Views referencing the key self-heal on
-        their next autosave (an unknown colId is dropped) — the rule every stale key rides.
-        """
-        key = str(key or '').strip()
-        if not key:
-            return
-
-        def _drop(ws):
-            ws['fields'].pop(key, None)
-            for row in ws['overlays'].values():
-                if isinstance(row, dict):
-                    row.pop(key, None)
-
-        self._update(username, _drop)
-
-    def patch_overlay(self, username, pid, updates):
-        """Patch only the external editable stratum; never writes to the source system."""
-        clean = dict(updates or {})
-        if not clean:
-            return
-
-        def _patch(ws):
-            ws['overlays'].setdefault(str(int(pid)), {}).update(clean)
-
-        self._update(username, _patch)
-
-
-def make(table_key, st=None):
-    return TableStore(table_key, st=st)
+"""The generic per-user TABLE WORKSPACE store — the persistence half of the table-page factory.
+
+One durable store key holds one table OBJECT's per-user Airtable-style state:
+
+    {username: {'views':    {view_id: SavedView},
+                'fields':   {field_key: Field},        # notes + custom_ + measure_ strata
+                'overlays': {str(pid): {field_key: value}}}}
+
+`make(table_key)` returns the six operations a table page's host loop needs, closed over that
+key. The Customer table's ops (`modules/customer_data.py`, key 'customer_table_workspace') are
+these exact functions — the logic MOVED here 2026-07-27 so that duplicating the Customer table
+pattern to a new object is a registry row + a config, not a copy of the store plumbing
+(owner directive: the table-page factory).
+
+A LIST (membership/formula semantics) is deliberately a different store from a VIEW
+(presentation/query state) — see modules/customer_data.py's customer_lists key.
+"""
+import core.store as store
+
+#: Wave-9 I17 — the SHARED bucket. Views whose permissions make them visible to anyone but
+#: their creator live here instead of in a personal workspace, under a key that cannot collide
+#: with a username (usernames come from core/users.py and are never dunder-wrapped; `is_shared`
+#: guards it anyway). ONE HOME PER VIEW, never both: a view moved to personal is REMOVED from
+#: here, and a view shared is removed from its creator's workspace. Two homes would mean two
+#: divergent copies the moment either was edited.
+SHARED_KEY = '__shared__'
+
+
+def _may_see(view, viewer, is_admin=False):
+    """Visibility for ONE shared view, fail-closed.
+
+    'collaborative' = everyone who can already open the module (the caller has gated that).
+    'users'         = the named users, plus the creator, plus admins — an admin who could not
+                      see a view could not administer it either.
+    Anything unrecognised returns False rather than defaulting open: an unreadable permission
+    must never widen access ([[aios-permissioning]] — no fail-open defaults).
+    """
+    if not isinstance(view, dict):
+        return False
+    if view.get('createdBy') == viewer or is_admin:
+        return True
+    perms = view.get('permissions') or {}
+    edit = perms.get('edit')
+    if edit == 'collaborative':
+        return True
+    if edit == 'users':
+        return viewer in set(perms.get('users') or ())
+    return False                      # 'personal', absent, or junk
+
+
+def _may_edit(view, viewer, is_admin=False):
+    """Who may WRITE a shared view. Same set as visibility today — the owner's item asks 'who
+    can edit' and lists who 'can have access', i.e. seeing and editing are one grant. Kept as a
+    separate function so they can diverge (a future read-only share) without hunting callers."""
+    return _may_see(view, viewer, is_admin)
+
+
+def _may_administer(view, viewer, is_admin=False):
+    """Who may change a view's PERMISSIONS, or delete it: the creator or an admin ONLY.
+
+    Deliberately narrower than _may_edit. If a collaborator could rewrite `permissions` they
+    could grant themselves sole ownership of somebody else's view, or quietly widen a
+    users-scoped view to everyone — the classic privilege-escalation-by-edit hole.
+    """
+    if not isinstance(view, dict):
+        return False
+    return bool(is_admin) or view.get('createdBy') == viewer
+
+
+def is_shared(view):
+    """A view belongs in the shared bucket when its permissions reach beyond its creator."""
+    return ((view or {}).get('permissions') or {}).get('edit') in ('collaborative', 'users')
+
+
+def _unique_name(wanted, existing, *, fallback='Untitled', max_len=120):
+    """Allocate one human-facing name inside a store.update transaction.
+
+    Keys/ids remain structural identity.  Names compare case-insensitively after collapsing
+    whitespace, because those variants are indistinguishable in the UI.  This helper belongs
+    in the store layer: allocating from a pre-write snapshot lets two concurrent requests both
+    choose the same free name before either write lands.
+    """
+    limit = max(1, int(max_len))
+
+    def _clean(value):
+        return ' '.join(str(value or '').split())
+
+    base = (_clean(wanted) or _clean(fallback) or 'Untitled')[:limit].rstrip()
+    taken = {_clean(value).casefold() for value in existing if _clean(value)}
+    if base.casefold() not in taken:
+        return base
+    index = 2
+    while True:
+        suffix = f' {index}'
+        stem = base[:max(0, limit - len(suffix))].rstrip()
+        candidate = f'{stem}{suffix}' if stem else str(index)[-limit:]
+        if candidate.casefold() not in taken:
+            return candidate
+        index += 1
+
+
+class TableStore:
+    """The six store operations for one table object's workspace, closed over its store key.
+
+    `st` (wave 18, C3-UT) is the STORE HANDLE — anything exposing `get(name)` /
+    `update(name, fn, flush=)`. Default = `core.store` (tenant #0, every existing caller,
+    zero behaviour change). The API passes the session's `TenantRuntime`, whose accessors
+    apply the tenant prefix / repo binding — which is what makes a user table created by a
+    Nurilab admin land in Nurilab's store instead of Royal's.
+    """
+
+    def __init__(self, table_key, st=None):
+        self.table_key = table_key
+        self._st = st if st is not None else store
+
+    @property
+    def st(self):
+        """The bound store handle — for SIBLING registries (core/shares) that must read the
+        same tenant's buckets this workspace lives in (wave 21, C1)."""
+        return self._st
+
+    def find_view(self, view_id):
+        """`(owner_username, view)` for a view living in ANY personal stratum, else None.
+
+        ⭐ Wave 21 (item 9, C1): the R10 grant registry names bare ids, so projecting a granted
+        view means locating the OWNER's record inside this topic's bucket. Personal strata
+        only — the `__shared__` bucket has its own read path (`shared_views`), and serving one
+        view from two finders is how two copies drift."""
+        vid = str(view_id or '').strip()
+        if not vid:
+            return None
+        try:
+            data = self._st.get(self.table_key) or {}
+        except Exception:
+            return None
+        for username, ws in data.items():
+            if username == SHARED_KEY or not isinstance(ws, dict):
+                continue
+            v = (ws.get('views') or {}).get(vid)
+            if isinstance(v, dict):
+                return str(username), dict(v)
+        return None
+
+    def find_folder(self, folder_id):
+        """`(owner_username, folder_row, {view_id: view})` for a VIEWS folder living in any
+        personal stratum, else None. `find_view`'s sibling, and here for the same reason.
+
+        ⭐ D-37 (wave 20's R10 remainder, closed 2026-08-05): the grant registry accepts kind
+        `folder` and has since wave 20, but only the VIEW kind was ever projected — so "share
+        this folder with Karen" recorded a row, listed under Shared with me, and put nothing on
+        Karen's screen. Projecting a folder means two lookups the view path does not need: WHO
+        owns it, and WHICH views are filed in it. Folder membership lives in the owner's
+        `itemFolders` map (item id -> folder id), never on the view record, so the views are
+        found by asking that map rather than by reading a list off the folder.
+
+        Views only (`folders['views']`): the cohort surface has its own store and its own
+        sharing question, and answering both here would make one function mean two things.
+        """
+        fid = str(folder_id or '').strip()
+        if not fid:
+            return None
+        try:
+            data = self._st.get(self.table_key) or {}
+        except Exception:
+            return None
+        for username, ws in data.items():
+            if username == SHARED_KEY or not isinstance(ws, dict):
+                continue
+            rows = (ws.get('folders') or {}).get('views') or []
+            hit = next((f for f in rows
+                        if isinstance(f, dict) and str(f.get('id') or '') == fid), None)
+            if not hit:
+                continue
+            # ⚠ `itemFolders` IS KEYED BY SURFACE FIRST (`{'views': {itemId: folderId}, …}`) —
+            # reading item ids off the top level finds the surface names instead and matches
+            # nothing, so the projection silently returns an EMPTY folder and the feature looks
+            # exactly as broken as it was before the fix. Caught by this change's own gate,
+            # which is the entire argument for writing one.
+            placed = (ws.get('itemFolders') or {}).get('views') or {}
+            views = ws.get('views') or {}
+            inside = {str(vid): dict(v) for vid, v in views.items()
+                      if isinstance(v, dict) and str(placed.get(str(vid)) or '') == fid}
+            return str(username), dict(hit), inside
+        return None
+
+    # ---------------------------------------------------------------- read
+    def workspace(self, username, consume_corrections=True):
+        """One user's durable workspace: always the full three-strata shape."""
+        try:
+            data = self._st.get(self.table_key) or {}
+            ws = data.get(username, {}) or {}
+            # A collision acknowledgement is protocol state, not part of a field definition.
+            # Consume it with the first fresh workspace payload after the correcting write,
+            # then splice a bounded copy into that payload only.  Keeping it out of `fields`
+            # prevents an old request id surviving forever and overriding a later rename.
+            corrections = {}
+            if consume_corrections and ws.get('fieldCorrections'):
+                def _take(current):
+                    current_ws = current.get(username) or {}
+                    pending = current_ws.get('fieldCorrections') or {}
+                    corrections.update({
+                        str(key)[:80]: dict(value)
+                        for key, value in pending.items()
+                        if isinstance(value, dict)
+                    })
+                    current_ws.pop('fieldCorrections', None)
+                    return current
+
+                data = self._st.update(self.table_key, _take, flush='async')
+                ws = (data or {}).get(username, {}) or {}
+        except Exception:
+            ws = {}
+            corrections = {}
+        fields = {
+            key: dict(value) if isinstance(value, dict) else value
+            for key, value in (ws.get('fields') or {}).items()
+        }
+        for key, ack in corrections.items():
+            field = fields.get(key)
+            accepted_label = str(ack.get('label') or '')[:120]
+            requested_label = str(ack.get('labelCorrectedFrom') or '')[:120]
+            correction_id = str(ack.get('labelCorrectionId') or '')[:180]
+            # A newer field write clears/replaces the pending ack in the SAME transaction.
+            # The label check is an extra belt against ever attaching a stale ack to a newer
+            # definition if a future store implementation weakens that ordering.
+            if (isinstance(field, dict) and accepted_label
+                    and str(field.get('label') or '') == accepted_label
+                    and requested_label and correction_id):
+                field['labelCorrectedFrom'] = requested_label
+                field['labelCorrectionId'] = correction_id
+        out = {
+            'views': dict(ws.get('views') or {}),
+            'fields': fields,
+            'overlays': dict(ws.get('overlays') or {}),
+            # wave-8 I11 (C4): folders over the saved views / cohorts sidebars. A FOURTH
+            # stratum rather than a key on each item — see aios_grid.clean_folders for why
+            # (a cohort lives in another store, and filing is an organising act, not part of
+            # what a view is). Absent for every workspace saved before this wave, which is
+            # exactly "no folders yet".
+            'folders': dict(ws.get('folders') or {}),
+            'itemFolders': dict(ws.get('itemFolders') or {}),
+        }
+        # 2026-07-31 (owner item 3): WHERE THE USER LEFT OFF survives a new browser. The
+        # client's localStorage copy wins when present; this is the server's answer for a
+        # fresh profile, which used to fall all the way to the system default view.
+        if ws.get('activeViewId'):
+            out['activeViewId'] = str(ws['activeViewId'])
+        # Wave 2026-08-02 (C-LAYOUT): the per-user record-detail field order. A fifth
+        # stratum, absent until the user first reorders — exactly "default order".
+        if isinstance(ws.get('recordLayout'), dict):
+            out['recordLayout'] = dict(ws['recordLayout'])
+        return out
+
+    # ---------------------------------------------------------------- write
+    def _update(self, username, change):
+        def _up(data):
+            ws = data.setdefault(username, {})
+            ws.setdefault('views', {})
+            ws.setdefault('fields', {})
+            ws.setdefault('overlays', {})
+            ws.setdefault('folders', {})
+            ws.setdefault('itemFolders', {})
+            change(ws)
+            return data
+        # flush='async' (wave-7 W3): this is THE hot path — every autosaved filter tweak,
+        # column note and typed overlay cell lands here inside the component round-trip, and
+        # the historical synchronous hub commit cost seconds per edit. The mutation applies to
+        # the in-process cache (read-your-writes for every subsequent render); the hub write
+        # coalesces in the background. Registry/auth writes elsewhere stay flush='sync'.
+        return self._st.update(self.table_key, _up, flush='async')
+
+    def rename_choice_values(self, username, change):
+        """Apply an arbitrary workspace rewrite (wave 20, item 15 / C-RENAME).
+
+        ⚠ NAMED FOR ITS ONE CALLER RATHER THAN EXPOSED AS A GENERIC `mutate`, deliberately. A
+        public "do anything to the workspace" method is an invitation to put write logic in
+        callers instead of here, and every OTHER method on this class exists precisely because
+        that logic belongs in one place. Renaming a choice is the one operation that must touch
+        three strata AT ONCE — the field's `choices`, the cells in `overlays`, and the views that
+        filter or colour by the old value — inside a SINGLE transaction, because a rename that
+        updated the cells and not the filters would leave a saved view matching nothing.
+
+        `change(ws)` receives the whole workspace with every stratum pre-created (see `_update`).
+        """
+        return self._update(username, change)
+
+    def save_active_view(self, username, view_id):
+        """Remember which view this user last opened (owner item 3, 2026-07-31).
+
+        Presentation state, not authorisation: the READ side re-validates the id against what
+        the caller may actually see, so a stale or foreign id degrades to the default view
+        rather than granting anything. Stored per user like every other stratum.
+        """
+        vid = str(view_id or '').strip()[:120]
+        if not vid or username == SHARED_KEY:
+            return
+
+        def _set(ws):
+            ws['activeViewId'] = vid
+        self._update(username, _set)
+
+    def save_record_layout(self, username, order):
+        """The per-user RECORD-DETAIL field order (wave 2026-08-02, C-LAYOUT).
+
+        Presentation state for ONE surface — the record modal. Deliberately not view config:
+        the owner's ask is per-user, not per-view, and it must never reorder grid columns.
+        The event handler validated keys against the live field set; the wire re-validates at
+        serve time (aios_grid.workspace_wire), so a deleted field cannot outlive itself here.
+        An empty order clears the stratum back to "default order".
+        """
+        if username == SHARED_KEY:
+            return
+        clean, seen = [], set()
+        for key in (order or [])[:200]:
+            key = str(key or '').strip()[:80]
+            if key and key not in seen:
+                seen.add(key)
+                clean.append(key)
+
+        def _set(ws):
+            if clean:
+                ws['recordLayout'] = {'order': clean}
+            else:
+                ws.pop('recordLayout', None)
+
+        self._update(username, _set)
+
+    def save_folders(self, username, folders, item_folders):
+        """Replace the folder stratum wholesale (wave-8 I11).
+
+        Wholesale rather than per-folder because the caller has ALREADY validated the complete
+        picture through aios_grid.clean_folders / clean_item_folders, and those two are
+        interdependent: a placement is only legal while its folder exists, so committing them
+        separately would leave a window where a reader sees an item filed into a folder that is
+        not there yet. One write, one consistent state.
+        """
+        def _set(ws):
+            ws['folders'] = dict(folders or {})
+            ws['itemFolders'] = dict(item_folders or {})
+        self._update(username, _set)
+
+    def save_view_order(self, username, order):
+        """⭐ WAVE-27 item 5 (contract C7) — this user's own ORDER for the views rail.
+
+        Wholesale, like `save_folders` above and for the same reason: the client sends the full
+        list it is looking at, not a delta, because a partial order cannot say where an UNNAMED
+        view went.
+
+        ⛔ PER USER, and it belongs in this stratum rather than on the view records themselves.
+        `aios_grid`'s own folder note argues it out for placements and every word applies: an
+        arrangement is a per-user ORGANISING act, not part of what a view IS — so keeping it out
+        of the view config means duplicating, sharing or exporting a view does not drag one
+        person's rail position along with it. It also means a SHARED view can sit in a different
+        place for each person who can see it, which is the only coherent answer once two people
+        share one view.
+
+        An empty list CLEARS the arrangement (back to server order) rather than storing `[]`.
+        """
+        def _set(ws):
+            clean = []
+            seen = set()
+            for vid in (order or []):
+                vid = str(vid).strip()[:120]
+                if vid and vid not in seen:
+                    seen.add(vid)
+                    clean.append(vid)
+            if clean:
+                ws['viewOrder'] = clean
+            else:
+                ws.pop('viewOrder', None)
+        self._update(username, _set)
+
+    def shared_views(self, viewer, is_admin=False):
+        """Every SHARED view this viewer may see, by id (wave-9 I17).
+
+        Read-only and independent of the viewer's own workspace: the caller merges. Returns
+        only what `_may_see` allows, so a caller cannot accidentally render somebody else's
+        personal view by forgetting to filter.
+        """
+        try:
+            bucket = ((self._st.get(self.table_key) or {}).get(SHARED_KEY) or {}).get('views') or {}
+        except Exception:
+            return {}
+        return {vid: dict(v) for vid, v in bucket.items()
+                if _may_see(v, viewer, is_admin)}
+
+    def shared_view(self, view_id):
+        """One shared view RAW — no visibility filter. For authorisation decisions only: a
+        caller must know a view exists and who owns it before it can decide whether the actor
+        may touch it. Never hand the result to a renderer without checking `_may_see`."""
+        try:
+            return ((self._st.get(self.table_key) or {}).get(SHARED_KEY) or {}
+                    ).get('views', {}).get(str(view_id))
+        except Exception:
+            return None
+
+    def save_view(self, username, view, shared=None, reserved_names=(), is_admin=False):
+        """Upsert a SavedView into its ONE home — personal workspace or the shared bucket.
+
+        `shared` defaults to reading the view's own permissions (`is_shared`). Whichever home
+        it lands in, the view is REMOVED from the other, so a view can never exist as two
+        copies that diverge on the next edit.
+
+        ⚠ AUTHORISATION IS THE CALLER'S JOB and must happen BEFORE this is called — this layer
+        moves data and does not know who is asking. `_cl_handle_one` is the wall.
+        """
+        view_id = str((view or {}).get('id') or '').strip()
+        if not view_id:
+            raise ValueError('view id is required')
+        if username == SHARED_KEY:
+            raise ValueError('reserved username')
+        to_shared = is_shared(view) if shared is None else bool(shared)
+        requested = dict(view)
+        accepted = {}
+
+        def _up(data):
+            # View names are tenant-global: every personal workspace plus the shared bucket.
+            # This deliberately includes views the actor cannot see.  The only disclosed fact
+            # is that a display name is already taken, while the categorical "no duplicate
+            # view names" contract remains true when a personal view is later shared.
+            names = list(reserved_names or ())
+            for workspace in data.values():
+                if not isinstance(workspace, dict):
+                    continue
+                names.extend(
+                    value.get('name')
+                    for candidate_id, value in (workspace.get('views') or {}).items()
+                    if candidate_id != view_id and isinstance(value, dict)
+                )
+            payload = dict(requested)
+            payload['name'] = _unique_name(payload.get('name'), names)
+            accepted.clear()
+            accepted.update(payload)
+            if to_shared:
+                bucket = data.setdefault(SHARED_KEY, {})
+                bucket.setdefault('views', {})[view_id] = payload
+                # it may have lived in the creator's workspace before being shared
+                owner = data.get(payload.get('createdBy') or username) or {}
+                (owner.get('views') or {}).pop(view_id, None)
+            else:
+                ws = data.setdefault(username, {})
+                ws.setdefault('views', {})[view_id] = payload
+                (data.get(SHARED_KEY, {}).get('views') or {}).pop(view_id, None)
+            return data
+
+        self._st.update(self.table_key, _up, flush='async')
+        return dict(accepted)
+
+    def delete_view(self, username, view_id):
+        """Delete a custom/list view override. The system all-rows view is guarded by caller.
+
+        Removes from BOTH homes: the caller has already authorised the delete, and leaving a
+        stale copy in the other bucket would resurrect the view on the next read.
+        """
+        vid = str(view_id)
+
+        def _up(data):
+            (data.get(username, {}).get('views') or {}).pop(vid, None)
+            (data.get(SHARED_KEY, {}).get('views') or {}).pop(vid, None)
+            return data
+
+        self._st.update(self.table_key, _up, flush='async')
+
+    def save_field(self, username, field, reserved_names=(), correction_id=None):
+        """Persist a column note or a user-created (custom_/measure_) field definition."""
+        key = str((field or {}).get('key') or '').strip()
+        if not key:
+            raise ValueError('field key is required')
+        requested = dict(field)
+        accepted = {}
+
+        def _save(ws):
+            names = list(reserved_names or ())
+            names.extend(
+                value.get('label')
+                for candidate_key, value in (ws.get('fields') or {}).items()
+                if candidate_key != key and isinstance(value, dict)
+            )
+            payload = dict(requested)
+            payload.pop('labelCorrectedFrom', None)
+            payload.pop('labelCorrectionId', None)
+            requested_label = ' '.join(
+                str(payload.get('label') or 'Untitled').split())[:120].rstrip()
+            payload['label'] = _unique_name(requested_label, names)
+            corrections = ws.setdefault('fieldCorrections', {})
+            corrections.pop(key, None)
+            if payload['label'] != requested_label and correction_id:
+                corrections[key] = {
+                    'label': payload['label'],
+                    'labelCorrectedFrom': requested_label,
+                    'labelCorrectionId': str(correction_id)[:180],
+                }
+            if not corrections:
+                ws.pop('fieldCorrections', None)
+            accepted.clear()
+            accepted.update(payload)
+            # A cleared note on an immutable source field returns to the canonical schema
+            # instead of leaving a meaningless override row. Custom fields remain even with
+            # an empty note — and so does a PRESET field carrying a measure-window override
+            # (wave-2 item 8) or a DISPLAY-format override (wave-5 item 10): the note may be
+            # empty but the period/format is real user state.
+            if (not payload.get('custom') and not str(payload.get('note') or '').strip()
+                    and not isinstance(payload.get('measure'), dict)
+                    and not isinstance(payload.get('format'), dict)):
+                ws['fields'].pop(key, None)
+            else:
+                ws['fields'][key] = payload
+
+        self._update(username, _save)
+        return dict(accepted)
+
+    def duplicate_field(self, username, source_key, new_key, field,
+                        reserved_names=(), correction_id=None):
+        """Clone a user-created field in ONE store transaction (wave-5 item 1): the new
+        definition plus — for `custom_` overlay sources only — every stored cell value under
+        the source key. One transaction, because a def without its values (or values without a
+        def) is exactly the orphan state delete_field exists to prevent, in reverse.
+        The caller validated both keys (same created stratum) and stamped the clone's
+        createdBy; this layer only moves data."""
+        source_key = str(source_key or '').strip()
+        new_key = str(new_key or '').strip()
+        if not source_key or not new_key or source_key == new_key:
+            raise ValueError('duplicate_field needs two distinct keys')
+        requested = dict(field)
+        accepted = {}
+
+        def _dup(ws):
+            names = list(reserved_names or ())
+            names.extend(
+                value.get('label')
+                for candidate_key, value in (ws.get('fields') or {}).items()
+                if candidate_key != new_key and isinstance(value, dict)
+            )
+            payload = dict(requested)
+            payload.pop('labelCorrectedFrom', None)
+            payload.pop('labelCorrectionId', None)
+            requested_label = ' '.join(
+                str(payload.get('label') or 'Untitled').split())[:120].rstrip()
+            payload['label'] = _unique_name(requested_label, names)
+            corrections = ws.setdefault('fieldCorrections', {})
+            corrections.pop(new_key, None)
+            if payload['label'] != requested_label and correction_id:
+                corrections[new_key] = {
+                    'label': payload['label'],
+                    'labelCorrectedFrom': requested_label,
+                    'labelCorrectionId': str(correction_id)[:180],
+                }
+            if not corrections:
+                ws.pop('fieldCorrections', None)
+            accepted.clear()
+            accepted.update(payload)
+            ws['fields'][new_key] = payload
+            if source_key.startswith('custom_'):
+                for row in ws['overlays'].values():
+                    if isinstance(row, dict) and source_key in row:
+                        row[new_key] = row[source_key]
+
+        self._update(username, _dup)
+        return dict(accepted)
+
+    def delete_field(self, username, key):
+        """Delete a USER-CREATED field definition outright (owner gap closed 2026-07-27).
+
+        Only the created strata ever reach here (`custom_` overlay fields, `measure_` formula
+        columns — the caller enforces the prefix). The stored overlay VALUES for the key are
+        scrubbed with it: a deleted column's cells must not linger as orphan data that would
+        silently resurface if the key were ever reused. Views referencing the key self-heal on
+        their next autosave (an unknown colId is dropped) — the rule every stale key rides.
+        """
+        key = str(key or '').strip()
+        if not key:
+            return
+
+        def _drop(ws):
+            ws['fields'].pop(key, None)
+            for row in ws['overlays'].values():
+                if isinstance(row, dict):
+                    row.pop(key, None)
+
+        self._update(username, _drop)
+
+    def patch_overlay(self, username, pid, updates):
+        """Patch only the external editable stratum; never writes to the source system."""
+        clean = dict(updates or {})
+        if not clean:
+            return
+
+        def _patch(ws):
+            ws['overlays'].setdefault(str(int(pid)), {}).update(clean)
+
+        self._update(username, _patch)
+
+
+def make(table_key, st=None):
+    return TableStore(table_key, st=st)

platform/core/user_tables.py

@@ -676,6 +676,23 @@ ROLLUP_CONDITION_OPS = ('eq', 'neq', 'contains', 'not_contains', 'is_empty', 'is
                         'gt', 'gte', 'lt', 'lte')
 ROLLUP_CONDITION_CONJ = ('and', 'or')
 ROLLUP_MAX_CONDITIONS = 20
+
+#: The date-window KINDS a source-backed rollup may name. MIRRORS `harness/windows.py`'s
+#: `WINDOW_KINDS`, deliberately as a local literal — `core` stays dependency-light and does not
+#: import up, the same reason `UT_FIELD_TYPES` is a literal rather than an `aios_grid` import.
+#: ⚠ This list VALIDATES; it never RESOLVES. `harness.windows.resolve(spec, today)` owns turning a
+#: kind into a date pair, so there is exactly one implementation of what "ytd" means and this
+#: module cannot drift into a second one. A kind added there and not here is simply not offerable
+#: on a rollup yet — the fail-closed direction.
+ROLLUP_SOURCE_WINDOWS = (
+    'all_time', 'today', 'yesterday', 'this_week', 'last_week', 'this_month', 'last_month',
+    'this_quarter', 'last_quarter', 'this_year', 'last_year', 'ytd', 'ytd_last_year',
+    'ltm', 'past_week', 'past_month', 'past_year',
+)
+#: ⛔ DELIBERATELY ABSENT: `last_n_days`, `next_n_days`, `custom`. Each needs a PARAMETER (an `n`,
+#: or a date pair) that this bag has nowhere to carry, and a parameterised kind accepted without
+#: its parameter would resolve to something arbitrary — a window that looks configured and
+#: measures the wrong period. They land when the bag learns to carry the parameter, not before.
 #: The ceiling on `limit`. Not a performance bound — `MAX_ROWS` is that — but a refusal to let a
 #: column claim a window bigger than a table can hold.
 ROLLUP_MAX_LIMIT = MAX_ROWS
@@ -747,6 +764,41 @@ def _clean_rollup(raw):
     """
     if not isinstance(raw, dict):
         return None
+    # ⭐ A SOURCE-BACKED ROLLUP — the read-through kind (owner 2026-08-09: *"make rollup be able to
+    # capture up to 1 million rows of a linked database … ok to push rollup filter etc to SQL"*).
+    #
+    # ⛔ WHY IT IS A DIFFERENT SHAPE RATHER THAN A BIGGER `link`. A linked rollup folds ROWS THAT
+    # EXIST IN THE STORE, and `MAX_ROWS = 5000` bounds them because every `ut_*` table lives in one
+    # JSON blob that is parsed and deep-copied per request (MEASURED: 5.1 MB / 1,567 rows = 67 ms a
+    # read). 256,810 order lines cannot live there and never will. This kind never COPIES the rows
+    # at all: it names a governed semantic TOPIC and a METRIC KEY, and one grouped SQL query
+    # answers every parent row at once (MEASURED: 1,748 customers over 256,810 lines in 232 ms).
+    #
+    # ⚠ A METRIC KEY, NEVER A FILTER FRAGMENT, and that is the load-bearing decision. `model/
+    # metrics/*.yml` already carries each metric's scope, its `store_filter_sql` AND the matching
+    # `live_domain` — whose own comment says *"BOTH or store_parity compares two different
+    # questions"*. Binding to the key inherits the scope and the live-parity oracle; letting a
+    # rollup carry SQL would mint a second definition of a number the semantic layer exists to
+    # define once.
+    #
+    # ⚠ `window` is a date-window KIND (`ytd`, `this_month`, …) resolved against `today` at
+    # COMPUTE time, never a literal date pair — a hand-computed year start is correct until
+    # 1 January and wrong after it, with nothing to notice ([[date-window-vocabulary]]).
+    src = raw.get('source')
+    if isinstance(src, dict):
+        topic = _field_key(src.get('topic'))
+        measure = _field_key(src.get('measure'))
+        group_by = _field_key(src.get('groupBy'))
+        on = _field_key(src.get('on'))
+        if not (topic and measure and group_by and on):
+            return None
+        bag = {'topic': topic, 'measure': measure, 'groupBy': group_by, 'on': on}
+        window = str(src.get('window') or '').strip().lower()
+        if window:
+            if window not in ROLLUP_SOURCE_WINDOWS:
+                return None
+            bag['window'] = window
+        return {'source': bag}
     link = _field_key(raw.get('link'))
     field = _field_key(raw.get('field'))
     fn = str(raw.get('fn') or '').strip().lower()

platform/evals/analyst_golden.yml

@@ -1,104 +1,104 @@
-# Analyst golden eval set v1 (OM-4 gate, 2026-07-11; truths REFRESHED 2026-07-17 after the
-# Jul-15 Odoo mass-recompute + hard-delete reconciliation — closed windows DO drift when docs
-# are edited/deleted; refresh truths from the parity-proven layer, never loosen tolerances).
-# Original header: truths computed from the PARITY-PROVEN
-# semantic layer over CLOSED windows (H1 2026 = 2026-01-01..2026-06-30) so live data drift cannot
-# break them. Checks are DETERMINISTIC (number within tolerance + required substrings + tool-use
-# assertions) — the validate() culture applied to AI answers. Run: harness/evals.py.
-# expect.value tolerance: abs or rel (fraction). expect.contains: ALL substrings (case-insensitive).
-# expect.tools: tool names that MUST appear in the trace (the answer must come FROM the tools).
-# expect.not_tools: tool names that must NOT appear (the over-refusal guard — an answerable ask
-# must never end in report_gap; a gap ask must never end in a forced wrong query).
-items:
-  - id: rev_h1
-    ask: "What was our wholesale revenue for the first half of 2026 (Jan 1 through Jun 30)?"
-    expect: {value: 3501508.33, rel: 0.001, tools: [run_semantic_query]}
-  - id: rev_h1_fisch
-    ask: "Fisch revenue only, H1 2026 (Jan 1 - Jun 30)?"
-    expect: {value: 2494244.70, rel: 0.001, tools: [run_semantic_query]}
-  - id: rev_h1_royal
-    ask: "And Royal's revenue for the same H1 2026 window?"
-    expect: {value: 1007263.63, rel: 0.001, tools: [run_semantic_query]}
-  - id: rev_june
-    ask: "Revenue for June 2026?"
-    expect: {value: 535046.06, rel: 0.001, tools: [run_semantic_query]}
-  - id: margin_h1
-    ask: "Gross margin dollars for H1 2026 (Jan-Jun), wholesale?"
-    expect: {value: 2067509.45, rel: 0.001, tools: [run_semantic_query]}
-  - id: margin_pct_h1
-    ask: "What gross margin percentage did we run in H1 2026?"
-    expect: {value: 0.59, abs: 0.005, allow_pct_form: true, tools: [run_semantic_query]}
-  - id: orders_h1
-    ask: "How many confirmed wholesale orders did we take in H1 2026 (Jan 1 - Jun 30)?"
-    expect: {value: 4989, abs: 1, tools: [run_semantic_query]}
-  - id: customers_h1
-    ask: "How many distinct customers bought from us in H1 2026?"
-    expect: {value: 1037, abs: 1, tools: [run_semantic_query]}
-  - id: top_customer
-    ask: "Who was our biggest customer by revenue in H1 2026?"
-    expect: {contains: ["Poppy Flowers"], tools: [run_semantic_query], not_tools: [report_gap]}
-  - id: opex_h1
-    ask: "Total operating expense on the GL for H1 2026 (Jan 1 - Jun 30)?"
-    expect: {value: 4683428.81, rel: 0.001, tools: [run_semantic_query]}
-  - id: top_expense
-    ask: "What is our single largest expense account in H1 2026?"
-    expect: {contains: ["FBA"], tools: [run_semantic_query]}
-  - id: chart_request
-    ask: "Make me a line chart of monthly wholesale revenue for H1 2026."
-    expect: {artifact: chart, tools: [run_semantic_query, make_chart]}
-  - id: bu_guard
-    ask: "Show one single revenue line combining Fisch and Royal together per month for H1 2026."
-    expect: {tools: [run_semantic_query]}   # combined-total ok; the guard is it must NOT error
-  - id: name_resolution
-    ask: "How much revenue did the customer 'flower' — I don't remember the exact name, something with FLOWERS in it — bring in H1 2026? Pick the top match."
-    expect: {tools: [get_field_values, run_semantic_query]}
-  - id: map_request
-    ask: "Put my top 20 customers by H1 2026 revenue on a map."
-    expect: {artifact: chart, tools: [run_semantic_query, make_chart]}
-  # --- the gap loop + location/YoY competence (added 2026-07-16 with the debug fixes) ---
-  - id: city_filter
-    ask: "Which customer in Brooklyn brought us the most revenue in H1 2026 (Jan 1 - Jun 30)?"
-    expect: {value: 48785.00, rel: 0.001, contains: ["J KAY"],
-             tools: [get_field_values, run_semantic_query], not_tools: [report_gap]}
-  - id: yoy_decliners
-    ask: "Which Fisch customer declined the most in revenue in H1 2026 (Jan 1 - Jun 30) versus the same window of 2025? Give the dollar decline."
-    expect: {value: 16451.25, rel: 0.005, contains: ["JUNE"],
-             tools: [run_semantic_query, transform_result], not_tools: [report_gap]}
-  # --- the agent dimension (added 2026-07-17: res.partner.agent_ids m2m sync — the #1 logged
-  # gap, closed). agent_book is VERBATIM the old gap_refusal ask: yesterday's honest refusal
-  # must become today's answer.
-  - id: agent_book
-    ask: "Who are the top customers handled by our salesperson Naomi in H1 2026?"
-    expect: {contains: ["Poppy Flowers"], tools: [get_field_values, run_semantic_query],
-             not_tools: [report_gap]}
-  - id: agent_revenue
-    ask: "How much revenue did agent Naomi's book of customers bring in H1 2026 (Jan 1 - Jun 30)?"
-    expect: {value: 872869.98, rel: 0.005, tools: [run_semantic_query], not_tools: [report_gap]}
-  # --- the TWO agent sources (added 2026-07-28). Odoo holds a customer-master book AND a
-  # per-invoice-line commission agent; they name different people, and the commission table also
-  # carries internal SALESPEOPLE who are not agents. These three lock the distinction: the
-  # unallocated bucket must be answerable at all, and Anna/Shantal must never be called agents.
-  - id: agent_unallocated
-    ask: "Using the invoice-line basis, how much of Fisch's 2025 sales was NOT allocated to an agent?"
-    expect: {value: 1447579.59, rel: 0.01, tools: [run_semantic_query], not_tools: [report_gap]}
-  - id: agent_not_salesperson
-    ask: "Who are our agents on the Fisch invoice lines in 2025, and what did each generate?"
-    expect: {contains: ["Pasternak"], not_contains: ["Anna", "Shantal"],
-             tools: [run_semantic_query], not_tools: [report_gap]}
-  - id: agent_allocated_2025
-    ask: "On the invoice-line basis, how much of Fisch's 2025 sales was allocated to a real agent?"
-    expect: {value: 2995664.75, rel: 0.01, tools: [run_semantic_query], not_tools: [report_gap]}
-  - id: gap_refusal
-    ask: "How many units of our best-selling SKU do we physically have in stock right now?"
-    expect: {tools: [report_gap]}   # stock-on-hand has NO topic in the store — must self-report, never guess
-  # --- the analytics transform library (added 2026-07-18: 60-op Tableau-class set). Truths from
-  # the parity-proven semantic layer over the CLOSED H1 2026 window.
-  - id: abc_a_tier
-    ask: "Using an ABC / Pareto analysis of H1 2026 revenue (Jan 1 - Jun 30), how many customers fall in the A tier — the vital few that make up the first 80% of revenue?"
-    expect: {value: 311, abs: 6, tools: [run_semantic_query, transform_result], not_tools: [report_gap]}
-  - id: ytd_customers
-    ask: "How many distinct customers had we sold to cumulatively from Jan 1 through the end of March 2026?"
-    expect: {value: 790, abs: 1, tools: [run_semantic_query], not_tools: [report_gap]}
-  - id: concentration_top5
-    ask: "What percent of our H1 2026 revenue (Jan 1 - Jun 30) is accounted for by our top 5 customers?"
-    expect: {value: 7.84, abs: 0.5, tools: [run_semantic_query], not_tools: [report_gap]}
+# Analyst golden eval set v1 (OM-4 gate, 2026-07-11; truths REFRESHED 2026-07-17 after the
+# Jul-15 Odoo mass-recompute + hard-delete reconciliation — closed windows DO drift when docs
+# are edited/deleted; refresh truths from the parity-proven layer, never loosen tolerances).
+# Original header: truths computed from the PARITY-PROVEN
+# semantic layer over CLOSED windows (H1 2026 = 2026-01-01..2026-06-30) so live data drift cannot
+# break them. Checks are DETERMINISTIC (number within tolerance + required substrings + tool-use
+# assertions) — the validate() culture applied to AI answers. Run: harness/evals.py.
+# expect.value tolerance: abs or rel (fraction). expect.contains: ALL substrings (case-insensitive).
+# expect.tools: tool names that MUST appear in the trace (the answer must come FROM the tools).
+# expect.not_tools: tool names that must NOT appear (the over-refusal guard — an answerable ask
+# must never end in report_gap; a gap ask must never end in a forced wrong query).
+items:
+  - id: rev_h1
+    ask: "What was our wholesale revenue for the first half of 2026 (Jan 1 through Jun 30)?"
+    expect: {value: 3501508.33, rel: 0.001, tools: [run_semantic_query]}
+  - id: rev_h1_fisch
+    ask: "Fisch revenue only, H1 2026 (Jan 1 - Jun 30)?"
+    expect: {value: 2494244.70, rel: 0.001, tools: [run_semantic_query]}
+  - id: rev_h1_royal
+    ask: "And Royal's revenue for the same H1 2026 window?"
+    expect: {value: 1007263.63, rel: 0.001, tools: [run_semantic_query]}
+  - id: rev_june
+    ask: "Revenue for June 2026?"
+    expect: {value: 535046.06, rel: 0.001, tools: [run_semantic_query]}
+  - id: margin_h1
+    ask: "Gross margin dollars for H1 2026 (Jan-Jun), wholesale?"
+    expect: {value: 2067509.45, rel: 0.001, tools: [run_semantic_query]}
+  - id: margin_pct_h1
+    ask: "What gross margin percentage did we run in H1 2026?"
+    expect: {value: 0.59, abs: 0.005, allow_pct_form: true, tools: [run_semantic_query]}
+  - id: orders_h1
+    ask: "How many confirmed wholesale orders did we take in H1 2026 (Jan 1 - Jun 30)?"
+    expect: {value: 4989, abs: 1, tools: [run_semantic_query]}
+  - id: customers_h1
+    ask: "How many distinct customers bought from us in H1 2026?"
+    expect: {value: 1037, abs: 1, tools: [run_semantic_query]}
+  - id: top_customer
+    ask: "Who was our biggest customer by revenue in H1 2026?"
+    expect: {contains: ["Poppy Flowers"], tools: [run_semantic_query], not_tools: [report_gap]}
+  - id: opex_h1
+    ask: "Total operating expense on the GL for H1 2026 (Jan 1 - Jun 30)?"
+    expect: {value: 4683428.81, rel: 0.001, tools: [run_semantic_query]}
+  - id: top_expense
+    ask: "What is our single largest expense account in H1 2026?"
+    expect: {contains: ["FBA"], tools: [run_semantic_query]}
+  - id: chart_request
+    ask: "Make me a line chart of monthly wholesale revenue for H1 2026."
+    expect: {artifact: chart, tools: [run_semantic_query, make_chart]}
+  - id: bu_guard
+    ask: "Show one single revenue line combining Fisch and Royal together per month for H1 2026."
+    expect: {tools: [run_semantic_query]}   # combined-total ok; the guard is it must NOT error
+  - id: name_resolution
+    ask: "How much revenue did the customer 'flower' — I don't remember the exact name, something with FLOWERS in it — bring in H1 2026? Pick the top match."
+    expect: {tools: [get_field_values, run_semantic_query]}
+  - id: map_request
+    ask: "Put my top 20 customers by H1 2026 revenue on a map."
+    expect: {artifact: chart, tools: [run_semantic_query, make_chart]}
+  # --- the gap loop + location/YoY competence (added 2026-07-16 with the debug fixes) ---
+  - id: city_filter
+    ask: "Which customer in Brooklyn brought us the most revenue in H1 2026 (Jan 1 - Jun 30)?"
+    expect: {value: 48785.00, rel: 0.001, contains: ["J KAY"],
+             tools: [get_field_values, run_semantic_query], not_tools: [report_gap]}
+  - id: yoy_decliners
+    ask: "Which Fisch customer declined the most in revenue in H1 2026 (Jan 1 - Jun 30) versus the same window of 2025? Give the dollar decline."
+    expect: {value: 16451.25, rel: 0.005, contains: ["JUNE"],
+             tools: [run_semantic_query, transform_result], not_tools: [report_gap]}
+  # --- the agent dimension (added 2026-07-17: res.partner.agent_ids m2m sync — the #1 logged
+  # gap, closed). agent_book is VERBATIM the old gap_refusal ask: yesterday's honest refusal
+  # must become today's answer.
+  - id: agent_book
+    ask: "Who are the top customers handled by our salesperson Naomi in H1 2026?"
+    expect: {contains: ["Poppy Flowers"], tools: [get_field_values, run_semantic_query],
+             not_tools: [report_gap]}
+  - id: agent_revenue
+    ask: "How much revenue did agent Naomi's book of customers bring in H1 2026 (Jan 1 - Jun 30)?"
+    expect: {value: 872869.98, rel: 0.005, tools: [run_semantic_query], not_tools: [report_gap]}
+  # --- the TWO agent sources (added 2026-07-28). Odoo holds a customer-master book AND a
+  # per-invoice-line commission agent; they name different people, and the commission table also
+  # carries internal SALESPEOPLE who are not agents. These three lock the distinction: the
+  # unallocated bucket must be answerable at all, and Anna/Shantal must never be called agents.
+  - id: agent_unallocated
+    ask: "Using the invoice-line basis, how much of Fisch's 2025 sales was NOT allocated to an agent?"
+    expect: {value: 1447579.59, rel: 0.01, tools: [run_semantic_query], not_tools: [report_gap]}
+  - id: agent_not_salesperson
+    ask: "Who are our agents on the Fisch invoice lines in 2025, and what did each generate?"
+    expect: {contains: ["Pasternak"], not_contains: ["Anna", "Shantal"],
+             tools: [run_semantic_query], not_tools: [report_gap]}
+  - id: agent_allocated_2025
+    ask: "On the invoice-line basis, how much of Fisch's 2025 sales was allocated to a real agent?"
+    expect: {value: 2995664.75, rel: 0.01, tools: [run_semantic_query], not_tools: [report_gap]}
+  - id: gap_refusal
+    ask: "How many units of our best-selling SKU do we physically have in stock right now?"
+    expect: {tools: [report_gap]}   # stock-on-hand has NO topic in the store — must self-report, never guess
+  # --- the analytics transform library (added 2026-07-18: 60-op Tableau-class set). Truths from
+  # the parity-proven semantic layer over the CLOSED H1 2026 window.
+  - id: abc_a_tier
+    ask: "Using an ABC / Pareto analysis of H1 2026 revenue (Jan 1 - Jun 30), how many customers fall in the A tier — the vital few that make up the first 80% of revenue?"
+    expect: {value: 311, abs: 6, tools: [run_semantic_query, transform_result], not_tools: [report_gap]}
+  - id: ytd_customers
+    ask: "How many distinct customers had we sold to cumulatively from Jan 1 through the end of March 2026?"
+    expect: {value: 790, abs: 1, tools: [run_semantic_query], not_tools: [report_gap]}
+  - id: concentration_top5
+    ask: "What percent of our H1 2026 revenue (Jan 1 - Jun 30) is accounted for by our top 5 customers?"
+    expect: {value: 7.84, abs: 0.5, tools: [run_semantic_query], not_tools: [report_gap]}

platform/harness/filter_sql.py

@@ -1,673 +1,673 @@
-"""harness/filter_sql.py — the grid's filter/sort engine, compiled to SQL (CG-1).
-
-THE PORT. `customer-grid/useVisibleRows.ts` evaluates the Airtable-parity filter TREE and the
-multi-level sort in TypeScript, per row, in the browser. That works at customer grain (1,550 rows,
-576 KB) and does NOT work at line grain, so a line-grain table has to filter server-side. This
-module is the second implementation of that contract, emitting parameterized SQL instead of
-booleans. `aios_grid.clean_filter_tree` (the validator) is the third. All three are held in
-lock-step by `aios-web/verify_filter_engine.py`, which runs the SAME cases through the TS engine,
-this compiler (executed on DuckDB), and the validator, and compares row sets.
-
-Design: this file is PURE — no model, no store, no app imports. It takes a filter tree plus a
-`columns` spec and returns SQL + params. `harness/semantic.store_columns` builds the spec from a
-topic; nothing else here knows what a topic is.
-
-  columns = {colId: {"sql": <SQL expression>, "type": <field type>, "aggregate": bool}}
-
-`sql` is a trusted IDENTIFIER/expression from the semantic model (never user input); every VALUE
-is a bound parameter. That split is the whole injection story.
-
---------------------------------------------------------------------------------------------
-TRI-STATE, AND WHY IT BECOMES COMPILE-TIME PRUNING
---------------------------------------------------------------------------------------------
-`evalNode` in TS returns true | false | null, where null means "this node is INACTIVE and its
-parent must IGNORE it". Get that wrong and a half-typed condition returns true, makes its `or`
-group true, and shows every record.
-
-Activeness reads ONLY the rule (op, value, value2, is-the-column-known) — never the row. So in
-SQL it is not a third truth value at all: it is decided while COMPILING. An inactive node emits
-no SQL, a group with no active children emits no SQL, and a root with nothing active emits NO
-PREDICATE AT ALL (`compile_filter_tree` returns None) — which is exactly `matchFilterTree`
-returning true for every row.
-
---------------------------------------------------------------------------------------------
-THE FOUR PLACES A NAIVE PORT SILENTLY DIVERGES
---------------------------------------------------------------------------------------------
-JavaScript coerces null to 0 / "" before comparing; SQL propagates NULL and drops the row.
-
-  1. `toNum(null)` is 0, so a NULL revenue PASSES `>= 0`.  SQL: NULL >= 0 -> NULL -> dropped.
-  2. `String(null)` is "", so a NULL state PASSES `is not FL`. SQL: NULL <> 'fl' -> dropped.
-  3. `"" <= "2026-01-01"` is true, so a NULL date PASSES `is before`. SQL: dropped.
-  4. `contains` is a LITERAL substring test. `LIKE '%v%'` treats % and _ as wildcards, so a
-     value containing either matches the wrong rows. Hence `strpos`, not LIKE.
-
-Every column is therefore read through `_value_sql`, which COALESCEs to the same zero-value
-JavaScript would have coerced to. The one thing that must NOT be coalesced away is the
-blank test itself — `isBlank` looks at the RAW value, and numeric 0 is NOT blank.
-
---------------------------------------------------------------------------------------------
-AND THE FIFTH: `default: return true` IS ACTIVE, NOT INACTIVE
---------------------------------------------------------------------------------------------
-`matchFilter`'s per-type switch ends in `default: return true`, reachable whenever an operator
-does not apply to the field type — `contains` on a currency/date field, or `gt`/`between` on a
-text field. A persisted tree can hold such a pair. That rule is ACTIVE and evaluates TRUE for
-every row, which is NOT the same as inactive: under `or` it makes the whole group true and shows
-everything. We emit `1=1` for those, and the gate asserts the difference is observable.
-
---------------------------------------------------------------------------------------------
-INPUT CONTRACT
---------------------------------------------------------------------------------------------
-Feed this CLEANED trees (`aios_grid.clean_filter_tree`). It is deliberately faithful to the TS
-engine rather than fail-closed on garbage — an unknown OP compiles to `1=1` exactly as TS's
-`default:` branch returns true — because the validator's job is to reject garbage and this
-module's job is to mean the same thing as the client. The gate proves the composition.
-
-Ported ahead of their consumer (CG-2) and gated at the same fidelity as the tree:
-`compile_search` (`matchSearch`) and `member_ids` (the hand-picked-members union in
-`useVisibleRows`).
-"""
-import math
-import re
-from collections import namedtuple
-
-# Mirrors customer-grid/types.ts FilterOp. verify_filter_engine.py asserts this set is
-# byte-identical to aios_grid.FILTER_OPS — three copies of a vocabulary need a drift gate.
-FILTER_OPS = frozenset({
-    'contains', 'doesNotContain', 'eq', 'neq', 'isEmpty', 'isNotEmpty',
-    'gt', 'gte', 'lt', 'lte', 'between', 'within',
-    'topN', 'bottomN', 'inTopPct', 'inBottomPct',
-    'aboveAvg', 'belowAvg', 'inQuartile', 'inDecile',
-})
-#: Wave 2026-08-02 (C-OPS): the RANK subset — set-ranked over the sibling-filtered domain.
-#: Vocabulary here, execution NOWHERE in this module: a per-row WHERE cannot express Top-N,
-#: and compiling to 1=0 would answer "nothing" to a question that has an answer, under a
-#: row_count that still looks authoritative. `_compile_leaf` therefore REFUSES (ValueError),
-#: the same server-side posture as a relative anchor with no `today`. The TS engine
-#:  evaluates these as a set pass in useVisibleRows (gated by web/verify_rank_filters.py).
-RANK_OPS = frozenset({'topN', 'bottomN', 'inTopPct', 'inBottomPct',
-                      'aboveAvg', 'belowAvg', 'inQuartile', 'inDecile'})
-#: The RESERVED pseudo-column of a cohort-membership leaf. Mirrors types.ts COHORT_FIELD.
-COHORT_FIELD = '__cohort__'
-#: Set operators over a SET of cohorts. Mirrors types.ts COHORT_OPS; DISJOINT from FILTER_OPS.
-COHORT_OPS = frozenset({'anyOf', 'allOf', 'noneOf'})
-#: The single-cohort ops the leaf shipped with, kept as permanent aliases. types.ts mirrors this.
-COHORT_OP_ALIASES = {'eq': 'anyOf', 'neq': 'noneOf'}
-#: Mirrors types.ts MAX_COHORT_IDS.
-MAX_COHORT_IDS = 20
-
-
-def parse_cohort_ids(value):
-    """The cohorts a leaf names. Mirrors types.ts `cohortIds()` and aios_grid.parse_cohort_ids."""
-    out = []
-    for raw in ('' if value is None else str(value)).split(','):
-        cid = raw.strip()[:120]
-        if not cid or cid in out:
-            continue
-        out.append(cid)
-        if len(out) >= MAX_COHORT_IDS:
-            break
-    return out
-# types.ts VALUE_FREE_OPS: no value control is rendered, and they must never be judged
-# "inactive because the value is blank" — that would turn them into no-ops.
-VALUE_FREE_OPS = frozenset({'isEmpty', 'isNotEmpty', 'aboveAvg', 'belowAvg'})
-# types.ts isNumericType()
-NUMERIC_TYPES = frozenset({'currency', 'int', 'pct'})
-TEXTUAL_TYPES = frozenset({'text', 'status'})
-
-SQL_TRUE = '1=1'
-
-_NUM_CMP = {'gt': '>', 'gte': '>=', 'lt': '<', 'lte': '<=', 'eq': '=', 'neq': '<>'}
-_DATE_CMP = dict(_NUM_CMP)
-
-#: sql = the predicate (already parenthesised); params = bound values, positional;
-#: uses_aggregate = the predicate references an aggregate column, so it belongs in HAVING
-#: rather than WHERE; columns_used = colIds actually referenced in the emitted SQL (an
-#: always-true `1=1` branch references nothing, and must not force HAVING routing).
-Compiled = namedtuple('Compiled', 'sql params uses_aggregate columns_used')
-
-
-# --------------------------------------------------------------------------- value coercion
-
-# JS `Number(string)` trims exactly this set (WhiteSpace + LineTerminator). Python's float() and
-# str.strip() use a DIFFERENT set -- notably U+0085 NEL, which Python treats as whitespace and JS
-# does not -- so the set is spelled out rather than left to strip().
-_JS_WS = "".join(chr(c) for c in (9, 10, 11, 12, 13, 32, 160, 5760, 8232, 8233,
-                                  8239, 8287, 12288, 65279)) + \
-         "".join(chr(c) for c in range(8192, 8203))
-# ASCII-ONLY on purpose: `\d` in a Python str pattern matches every Unicode decimal digit, so
-# `\d` here would parse the fullwidth "２５０" that JS rejects -- reintroducing the exact bug
-# this function exists to avoid.
-_JS_DEC = re.compile(r"^[+-]?(?:[0-9]+\.?[0-9]*|\.[0-9]+)(?:[eE][+-]?[0-9]+)?$")
-_JS_INF = re.compile(r"^[+-]?Infinity$")
-_JS_RADIX = ((re.compile(r"^0[xX][0-9a-fA-F]+$"), 16),
-             (re.compile(r"^0[oO][0-7]+$"), 8),
-             (re.compile(r"^0[bB][01]+$"), 2))
-
-
-def to_num(v):
-    """Port of `toNum`: JS `Number(v)`, then `Number.isFinite` or 0.
-
-    NOT `float(v)`. Python's float() is MORE permissive than JS's Number() in ways that make SQL
-    narrow where the client shows everything -- the worse direction, because at line grain that
-    is a silent under-fetch sitting beside an honest-looking row_count:
-
-        "1_000"   float() -> 1000.0 (PEP-515 underscores)   Number() -> NaN -> 0
-        "２５０"     float() -> 250.0 (any Unicode Nd)      Number() -> NaN -> 0
-        "\\u0085" + "12"  float() -> 12.0 (NEL is Python whitespace)  Number() -> NaN -> 0
-
-    and LESS permissive in one family, which errs the other way:
-
-        "0x10"    float() -> raises -> 0                    Number() -> 16   (also 0b, 0o)
-
-    A tree carrying any of these is reachable: the React builder renders <input type="number">,
-    but persisted / seeded / imported view JSON goes through `clean_filter_tree`, which passes
-    the value string through untouched by design (it validates structure, not numeric syntax).
-
-    Agreed by construction on the rest: ""/None -> 0, "abc"/"12,000" -> 0, " 250 " -> 250,
-    ".5"/"5."/"+5", "1e400" -> Infinity -> 0, "-0" -> 0, and float64 truncation of
-    "9007199254740993" -> 9007199254740992.
-    """
-    if isinstance(v, bool):
-        return 1.0 if v else 0.0                       # JS Number(true) === 1
-    if isinstance(v, (int, float)):
-        n = float(v)
-        return n if math.isfinite(n) else 0.0
-    if v is None:
-        return 0.0                                     # JS Number(null) === 0
-    s = str(v).strip(_JS_WS)
-    if s == "":
-        return 0.0                                     # JS Number("") === 0
-    if _JS_INF.match(s):
-        return 0.0                                     # Infinity is not finite -> 0
-    for pattern, base in _JS_RADIX:
-        if pattern.match(s):
-            return float(int(s[2:], base))
-    if not _JS_DEC.match(s):
-        return 0.0                                     # JS NaN -> 0
-    n = float(s)
-    return n if math.isfinite(n) else 0.0
-
-
-def _value_sql(spec):
-    """The ONE expression for a column, used by BOTH the filter and the sort.
-
-    Two expressions would let two rows tie in the grid and not tie in SQL (dates truncated for
-    comparison but ordered by the raw timestamp is the obvious way to get that wrong), so the
-    next sort key would break the tie in one engine and not the other.
-
-    numeric: `round_even(x, 0)` reproduces `aios_grid._round`, which is Python's round() =
-    BANKER'S rounding. DuckDB's plain ROUND() rounds half AWAY from zero, so ROUND(1234.5)=1235
-    while the grid shows 1234 — `eq 1234` would then match on screen and miss in SQL. The grid
-    displays rounded values; filters must agree with what is on screen.
-    date: truncate to the 10-char ISO shape the payload carries, so lexical compare is
-    chronological and a timestamp column cannot smuggle ' 00:00:00' into the comparison.
-    text: lowercased, matching `String(raw ?? "").toLowerCase()`.
-    """
-    e = spec['sql']
-    t = spec['type']
-    if t in NUMERIC_TYPES:
-        return f"COALESCE(round_even(TRY_CAST({e} AS DOUBLE), 0), 0)"
-    if t == 'date':
-        return f"COALESCE(SUBSTR(CAST({e} AS VARCHAR), 1, 10), '')"
-    return f"LOWER(COALESCE(CAST({e} AS VARCHAR), ''))"
-
-
-def _blank_sql(spec):
-    """Port of `isBlank`: null/undefined/"" are blank — numeric 0 is NOT.
-
-    Reads the RAW column, never `_value_sql` (which has already coalesced blanks into 0/"",
-    the very distinction this test exists to make).
-    """
-    e = spec['sql']
-    if spec['type'] in NUMERIC_TYPES:
-        # 0 stays non-blank: CAST(0 AS VARCHAR) is '0'. The '' arm covers a text-typed column
-        # holding "", which `_round` passes through unchanged into the payload.
-        return f"(({e}) IS NULL OR CAST({e} AS VARCHAR) = '')"
-    if spec['type'] == 'date':
-        return f"(COALESCE(SUBSTR(CAST({e} AS VARCHAR), 1, 10), '') = '')"
-    return f"(COALESCE(CAST({e} AS VARCHAR), '') = '')"
-
-
-# --------------------------------------------------------------------------- activeness
-
-def is_rule_active(rule, columns):
-    """Port of `isRuleActive` + `evalNode`'s two leaf guards. Row-independent by construction.
-
-    Unknown column -> inactive (evalNode returns null before matchFilter is ever called).
-    Value-free ops are always active. `between` needs BOTH bounds.
-
-    ⚠ The four VALUE-FREE ANCHOR MODES (`is before [today]`) carry no value, and the historical
-    "blank value = inactive" rule would IGNORE them — widening the result under a count nobody
-    would doubt. Same shape as the isEmpty/isNotEmpty no-op bug, arriving by a different door.
-    """
-    if not isinstance(rule, dict):
-        return False
-    col = rule.get('colId')
-    if col == COHORT_FIELD:                       # a cohort leaf has no column to look up
-        # Driven by the SET it names, so a value of "," is INACTIVE rather than active-and-
-        # unanswerable. Mirrors the cohort branch at the top of types.ts isRuleActive.
-        return bool(parse_cohort_ids(rule.get('value')))
-    if col not in columns:
-        return False
-    op = rule.get('op')
-    if op in VALUE_FREE_OPS:
-        return True
-    if op == 'within':
-        return _window_bounds(rule.get('dateWindow'), None, probe=True)
-    if rule.get('rhs') is not None:
-        rhs = rule['rhs']
-        # An rhs naming a column this table does not have is IGNORED, by the same rule as an
-        # unknown left column two lines above — for EITHER kind. Ignoring one side and hiding
-        # every row for the other would make the comparison asymmetric in a way nobody could
-        # predict. Doing it here rather than in _compile_leaf keeps activeness the single place
-        # that decides, which is what makes the compiled branch below provably unreachable.
-        if not isinstance(rhs, dict) or rhs.get('colId') not in columns:
-            return False
-        return _rhs_complete(rhs)
-    if rule.get('dateMode') in _ANCHOR_VALUE_FREE:
-        return True
-    value = _as_str(rule.get('value'))
-    if op == 'between':
-        v2 = rule.get('value2')
-        return value != '' and v2 is not None and _as_str(v2) != ''
-    return value != ''
-
-
-def _rhs_complete(rhs):
-    """Port of types.ts isRhsComplete. An incomplete rhs makes the rule INACTIVE, exactly as a
-    half-typed value does."""
-    if not isinstance(rhs, dict) or not rhs.get('colId'):
-        return False
-    if rhs.get('kind') == 'measure':
-        return _windows().normalize(rhs.get('window')) is not None
-    return rhs.get('kind') == 'field'
-
-
-def _windows():
-    """`harness.windows` imported lazily, so this module stays importable on its own.
-
-    filter_sql is otherwise PURE (no model/store/app imports) and that property is what lets
-    aios_grid embed the grid anywhere. windows.py is the one exception and it is a deliberate
-    one: the date vocabulary is a two-ENGINE contract, and a third copy of "what the past month
-    means" is precisely the drift verify_windows.py exists to prevent. It imports nothing but
-    datetime, so purity is preserved in substance.
-    """
-    from harness import windows as _w
-    return _w
-
-
-#: Mirrors windows.ANCHOR_VALUE_FREE, resolved lazily on first use (see _windows).
-class _AnchorValueFree:
-    def __contains__(self, mode):
-        return mode in _windows().ANCHOR_VALUE_FREE
-
-
-_ANCHOR_VALUE_FREE = _AnchorValueFree()
-
-
-def _window_bounds(spec, today, probe=False):
-    """Resolve a date-condition RANGE, or refuse.
-
-    `probe=True` answers only "is this a resolvable window?" without needing `today` — which is
-    what activeness has to know while compiling, before any date is in hand.
-
-    ⚠ A missing `today` on the real path RAISES rather than widening. The client's answer to the
-    same gap is to match nothing; the server's must be to refuse, because a server that quietly
-    drops a condition reports an authoritative row_count for a query nobody asked for. Same rule
-    as the sibling/depth caps: truncate on the client, refuse on the server.
-    """
-    w = _windows()
-    if probe:
-        return w.normalize(spec) is not None
-    if today is None:
-        raise ValueError(
-            'a relative-date condition needs `today` — compile_filter_tree(today=...). '
-            'Refusing rather than dropping the condition, which would widen the result while '
-            'the count beside it still looked authoritative.')
-    return w.resolve(spec, today)
-
-
-def _as_str(v):
-    """The builder stores values as raw input strings; be tolerant of a number that survived
-    an older payload. `str(500) != ''` is active and `to_num` reads it back, matching JS where
-    `500 === ""` is false."""
-    return '' if v is None else str(v)
-
-
-# --------------------------------------------------------------------------- leaf
-
-def _compile_leaf(rule, columns, state):
-    """Port of `matchFilter`. Returns (sql, params) or None when the rule is INACTIVE."""
-    if not is_rule_active(rule, columns):
-        return None
-    col_id = rule['colId']
-    op = rule.get('op')
-    value = _as_str(rule.get('value'))
-
-    # --- owner item 5: a COHORT leaf, before any column lookup -------------------------------
-    # `__cohort__` is not a column. Handled first for the same reason evalNode handles it first:
-    # falling through to the column path would make it INACTIVE, and inactive means every row.
-    if col_id == COHORT_FIELD:
-        return _compile_cohort(rule, state)
-
-    # --- C-OPS (wave 2026-08-02): a RANK leaf is structurally unanswerable at row grain ------
-    # Top-N / quantile membership is a property of the SET, not the row; the client engine
-    # answers it with a set pass over the sibling-filtered domain. Refuse loudly rather than
-    # compile something that means a different question (see RANK_OPS).
-    if op in RANK_OPS:
-        raise ValueError(
-            f'rank operator {op!r} cannot compile to row SQL - evaluate it as a set pass '
-            f'(the client engine) or pre-resolve the matching ids before compiling')
-
-    spec = columns[col_id]
-
-    def used(sql, params=()):
-        state['used'].add(col_id)
-        if spec.get('aggregate'):
-            state['aggregate'] = True
-        return (sql, list(params))
-
-    # --- value-free ops, BEFORE any value-based short-circuit (the no-op bug) ---------------
-    if op == 'isEmpty':
-        return used(_blank_sql(spec))
-    if op == 'isNotEmpty':
-        return used(f"NOT {_blank_sql(spec)}")
-
-    v = _value_sql(spec)
-    t = spec['type']
-
-    # --- CG-9: the comparand is another COLUMN, coerced through the LEFT field's type --------
-    # `_value_sql` on a spec whose `sql` is the RIGHT column and whose `type` is the LEFT one —
-    # exactly what TS does (`toNum(other)` for a numeric LHS, `String(other ?? "")` for a date,
-    # `.toLowerCase()` for text). Reading the right column through its OWN type would compare a
-    # rounded number against an unrounded one and disagree on the ties.
-    rhs_v = None
-    if rule.get('rhs') is not None:
-        # No `rspec is None` branch: `is_rule_active` already rejected an rhs naming a column
-        # this table does not have, so it cannot be missing here. A defensive fallback would be
-        # unreachable, and the negative control showed exactly that — deleting it changed
-        # nothing, which is how dead code hides behind a careful-looking line.
-        rspec = columns[rule['rhs']['colId']]
-        rhs_v = _value_sql({'sql': rspec['sql'], 'type': t})
-        state['used'].add(rule['rhs']['colId'])
-        if rspec.get('aggregate'):
-            state['aggregate'] = True
-
-    if t in NUMERIC_TYPES:
-        if rhs_v is not None:
-            return used(f"({v} {_NUM_CMP[op]} {rhs_v})") if op in _NUM_CMP else (SQL_TRUE, [])
-        if op == 'between':
-            a, b = to_num(value), to_num(rule.get('value2'))
-            return used(f"({v} >= ? AND {v} <= ?)", [min(a, b), max(a, b)])
-        if op in _NUM_CMP:
-            return used(f"({v} {_NUM_CMP[op]} ?)", [to_num(value)])
-        return (SQL_TRUE, [])          # contains/doesNotContain on a number -> default: true
-
-    if t == 'date':
-        if op == 'within':
-            bounds = _window_bounds(rule.get('dateWindow'), state.get('today'))
-            if bounds is None:
-                return ('1=0', [])     # unreachable: activeness probed it. Never widen.
-            lo, hi = bounds
-            # `{v} <> ''` is NOT redundant. `_value_sql` COALESCEs a NULL date to '', and
-            # '' <= any upper bound is true — so an open-ended window would sweep in every
-            # never-ordered customer. TS guards it with `if (a === "") return false`.
-            parts, params = [f"{v} <> ''"], []
-            if lo is not None:
-                parts.append(f"{v} >= ?")
-                params.append(lo)
-            if hi is not None:
-                parts.append(f"{v} <= ?")
-                params.append(hi)
-            return used('(' + ' AND '.join(parts) + ')', params)
-        if rhs_v is not None:
-            return used(f"({v} {_DATE_CMP[op]} {rhs_v})") if op in _DATE_CMP else (SQL_TRUE, [])
-        if op == 'between':
-            v2 = _as_str(rule.get('value2'))
-            lo, hi = (value, v2) if value < v2 else (v2, value)
-            return used(f"({v} >= ? AND {v} <= ?)", [lo, hi])
-        if op in _DATE_CMP:
-            anchor = _resolve_anchor(rule.get('dateMode'), value, state.get('today'))
-            if anchor is None:
-                return ('1=0', [])     # unresolvable anchor -> matches nothing (TS: false)
-            return used(f"({v} {_DATE_CMP[op]} ?)", [anchor])
-        return (SQL_TRUE, [])          # contains/doesNotContain on a date -> default: true
-
-    # text / status — case-insensitive. strpos, not LIKE: `includes` is a LITERAL substring
-    # test, so a value holding % or _ must not act as a wildcard.
-    #
-    # BOTH SIDES fold in SQL (`LOWER(?)`, never Python's str.lower()). Python and JS agree on
-    # case folding; DuckDB does NOT — LOWER('ISTANBUL' with a dotted capital I) drops the dot
-    # while both languages keep it as i + combining dot. Folding the needle in Python and the
-    # haystack in DuckDB therefore produced two different strings, and a value could fail to
-    # match ITSELF. One folder for both operands is the only version that cannot do that.
-    if rhs_v is not None:
-        # Both operands are already folded by `_value_sql` (text branch), so no LOWER(?) here.
-        if op == 'contains':
-            return used(f"(strpos({v}, {rhs_v}) > 0)")
-        if op == 'doesNotContain':
-            return used(f"(strpos({v}, {rhs_v}) = 0)")
-        if op == 'eq':
-            return used(f"({v} = {rhs_v})")
-        if op == 'neq':
-            return used(f"({v} <> {rhs_v})")
-        return (SQL_TRUE, [])
-    if op == 'contains':
-        return used(f"(strpos({v}, LOWER(?)) > 0)", [value])
-    if op == 'doesNotContain':
-        return used(f"(strpos({v}, LOWER(?)) = 0)", [value])
-    if op == 'eq':
-        return used(f"({v} = LOWER(?))", [value])
-    if op == 'neq':
-        return used(f"({v} <> LOWER(?))", [value])
-    return (SQL_TRUE, [])              # gt/gte/lt/lte/between/within on text -> default: true
-
-
-def _resolve_anchor(mode, value, today):
-    """A date condition's anchor -> one ISO date, or None. `today` may be absent ONLY for the
-    `exact` mode, which does not use it.
-
-    The sentinel is deliberate and load-bearing for BACK-COMPAT: every date filter that existed
-    before anchors is `exact`, and every caller that compiles one (store_query, store_rows)
-    passes no `today`. Requiring it unconditionally would turn a working filter into an
-    exception. A RELATIVE anchor still refuses — the server never widens.
-    """
-    mode = mode or 'exact'
-    if today is None:
-        if mode != 'exact':
-            raise ValueError(
-                f"the date anchor {mode!r} is relative and needs `today` — "
-                f"compile_filter_tree(today=...). Refusing rather than dropping the condition, "
-                f"which would widen the result under an authoritative-looking count.")
-        # `exact` ignores `today` entirely (verify_windows resolves it across 11 probe dates and
-        # gets the same answer every time), so any valid date serves as the unused argument.
-        today = '1970-01-01'
-    return _windows().resolve_anchor(mode, value, today)
-
-
-def _compile_cohort(rule, state):
-    """Port of evalNode's cohort branch: membership in a SET of hand-curated sets of row ids.
-
-    Owner 2026-07-27: the leaf names one OR MORE cohorts and asks `anyOf` / `allOf` / `noneOf`.
-    A single id is a one-element set, so the shipped `is part of` compiles down this same path.
-
-    States, mirroring TS exactly:
-      every set present         -> the union (anyOf / noneOf) or the intersection (allOf)
-      a set present but EMPTY   -> that member contributes 1=0, because nobody is in an empty
-                                   cohort. So `allOf` collapses to 1=0 and `noneOf` to 1=1 —
-                                   which is what `set.has(pid)` on an empty Set does in TS.
-      ANY set ABSENT            -> 1=0 for ALL THREE ops. The condition is unanswerable, and
-                                   unanswerable matches nothing: answering "everything" to
-                                   `is none of [a cohort we cannot see]` is the widening sin
-                                   wearing a plausible face, and answering it for the members we
-                                   DO have would silently ask a different question.
-
-    COALESCE(... , FALSE) because a NULL row id makes `id IN (...)` NULL, and `NOT NULL` is NULL
-    — SQL would drop the row where TS keeps it.
-    """
-    sets = state.get('cohort_sets')
-    if sets is None:
-        raise ValueError(
-            'a cohort condition needs cohort_sets — compile_filter_tree(cohort_sets=...). '
-            'Refusing rather than dropping it: a dropped condition widens the result while the '
-            'count beside it still looks authoritative.')
-    id_sql = state.get('id_sql')
-    if not id_sql:
-        raise ValueError('a cohort condition needs id_sql (the row-identity column)')
-    op = COHORT_OP_ALIASES.get(rule.get('op'), rule.get('op'))
-    named = parse_cohort_ids(rule.get('value'))
-    members = [sets.get(cid) for cid in named]
-    if not named or any(m is None for m in members):
-        return ('1=0', [])
-
-    parts, params = [], []
-    for ids in members:
-        ids = [int(x) for x in ids]
-        if not ids:
-            parts.append('1=0')
-            continue
-        parts.append(f"COALESCE({id_sql} IN ({','.join('?' for _ in ids)}), FALSE)")
-        params.extend(ids)
-    if op == 'allOf':
-        return ('(' + ' AND '.join(parts) + ')', params)
-    union = '(' + ' OR '.join(parts) + ')'
-    return ((f"(NOT {union})" if op == 'noneOf' else union), params)
-
-
-# --------------------------------------------------------------------------- tree
-
-def _compile_node(node, columns, state):
-    """Port of `evalNode`. Returns (sql, params), or None when the node is INACTIVE.
-
-    A group combines only its ACTIVE children with its OWN conjunction; a group with no active
-    children is itself inactive and disappears. That is what stops a half-built group from
-    either zeroing the grid (`and`) or disabling it (`or`).
-    """
-    if not isinstance(node, dict):
-        return None
-    if isinstance(node.get('children'), list):
-        parts, params = [], []
-        for child in node['children']:
-            got = _compile_node(child, columns, state)
-            if got is None:
-                continue                                   # inactive -> ignored entirely
-            parts.append(got[0])
-            params.extend(got[1])
-        if not parts:
-            return None
-        joiner = ' OR ' if node.get('conj') == 'or' else ' AND '
-        return ('(' + joiner.join(parts) + ')', params)
-    return _compile_leaf(node, columns, state)
-
-
-def compile_filter_tree(nodes, conj='and', columns=None, member_ids=None, id_sql=None,
-                        today=None, cohort_sets=None):
-    """Port of `matchFilterTree` (+ the `memberPids` union in `useVisibleRows`).
-
-    Returns a `Compiled`, or **None when nothing is active** — meaning no predicate at all, not
-    a false one. `matchFilterTree` returns true when the tree is inactive, so emitting anything
-    here would narrow rows the client would have shown.
-
-    `member_ids` reproduces `members.has(r.pid) || matchFilterTree(...)`. Note the union lives
-    INSIDE `if (filters.length)` and is OR'd with a tree that is true for everything when
-    inactive — so an inactive tree must emit NOTHING, never `pid IN (...)`, which would narrow
-    to just the hand-picked members. Same family of bug as the tri-state one, inverted.
-
-    `today` is the TENANT'S today, required by any relative date condition (`is within …`,
-    `is before [one month ago]`) and by nothing else — an `exact` date needs none, which is what
-    keeps every pre-anchor caller working unchanged. `cohort_sets` is `{cohortId: [pid, ...]}`
-    for cohort-membership leaves. Both REFUSE when needed and missing; neither defaults.
-    """
-    state = {'aggregate': False, 'used': set(),
-             'today': today, 'cohort_sets': cohort_sets, 'id_sql': id_sql}
-    got = _compile_node({'conj': conj, 'children': list(nodes or [])}, columns or {}, state)
-    if got is None:
-        return None
-    sql, params = got
-    if member_ids:
-        if not id_sql:
-            raise ValueError('member_ids requires id_sql (the row-identity column)')
-        ids = [int(x) for x in member_ids]
-        sql = f"({sql} OR {id_sql} IN ({','.join('?' for _ in ids)}))"
-        params = list(params) + ids
-    return Compiled(sql, list(params), state['aggregate'], frozenset(state['used']))
-
-
-def compile_search(q, columns):
-    """Port of `matchSearch`: the narrowing search box.
-
-    True if ANY human-readable (text/status) column contains `q`, case-insensitively. NUMERIC
-    columns are skipped on purpose so a query like "10" does not match revenue or order counts.
-    Dates are skipped too — `matchSearch` tests only text and status.
-
-    The caller ANDs this with the filter predicate, matching the TS pipeline order
-    (filter -> search). It is deliberately OUTSIDE the `member_ids` union: in `useVisibleRows`
-    the union applies to the filter step only, so a hand-picked member is still searchable away.
-    """
-    # `.strip(_JS_WS)`, not `.strip()`: the client trims with JS String.trim(), whose whitespace
-    # set differs from Python's in BOTH directions (Python strips U+0085 NEL and U+001C..1F,
-    # JS does not; JS strips U+FEFF, Python does not). A query of just those characters is
-    # blank to one engine and a real search to the other. Folding is left to SQL — see the
-    # LOWER(?) note in _compile_leaf.
-    q = (q or '').strip(_JS_WS)
-    if not q:
-        return None
-    parts, params, used = [], [], set()
-    aggregate = False
-    for col_id, spec in (columns or {}).items():
-        if spec['type'] not in TEXTUAL_TYPES:
-            continue
-        parts.append(f"(strpos({_value_sql(spec)}, LOWER(?)) > 0)")
-        params.append(q)
-        used.add(col_id)
-        aggregate = aggregate or bool(spec.get('aggregate'))
-    if not parts:
-        # No searchable column: `matchSearch` returns false for every row, so the search
-        # narrows to nothing. That is a real predicate, not an absent one.
-        return Compiled('1=0', [], False, frozenset())
-    return Compiled('(' + ' OR '.join(parts) + ')', params, aggregate, frozenset(used))
-
-
-def compile_order_by(sorts, columns, tiebreak_sql=None):
-    """Port of `makeComparator`. Returns an ORDER BY body, or None when nothing sorts.
-
-    `tiebreak_sql` (the row-identity column) is appended as a final ASC key and is REQUIRED for
-    any windowed fetch. `Array.prototype.sort` is stable, so TS leaves tied rows in their
-    incoming order; SQL guarantees NOTHING for ties, so LIMIT/OFFSET paging over a non-total
-    order can repeat a row on one page and drop it from another. Appending row identity makes
-    the order total. It is a STRENGTHENING of the TS guarantee, not a divergence: the payload a
-    windowed fetch produces is itself in this order, so the client never re-sorts it differently.
-
-    BLANKS SORT LAST IN BOTH DIRECTIONS (Airtable's behavior, and the reason descending
-    "Last order" leads with the most recent rather than with never-ordered customers). Each key
-    contributes TWO terms: an always-ASC blank flag, then the value in the requested direction.
-    Two blanks tie on both terms, so the NEXT key decides — matching the comparator's
-    `if (aBlank && bBlank) continue`.
-
-    An unknown column is skipped: in TS its values are `undefined` on both sides, so both are
-    blank and the key is a no-op tiebreak.
-
-    Direction: `s.dir === "asc" ? c : -c` — only the exact string "asc" ascends, anything else
-    descends. Faithfully reproduced; do not "fix" it to default ASC.
-
-    Residual divergence, deliberate: TS uses `localeCompare`, we use LOWER() + DuckDB's binary
-    collation. They agree on case-insensitive ordering of ASCII and on ISO dates (unaffected by
-    LOWER), and differ on locale tie-breaks between case-variants of the same string ("a" vs
-    "A" sort adjacent under localeCompare, tie under LOWER) and on accent ordering.
-    """
-    terms = []
-    for s in (sorts or []):
-        if not isinstance(s, dict):
-            continue
-        spec = (columns or {}).get(s.get('colId'))
-        if spec is None:
-            continue
-        terms.append(f"CASE WHEN {_blank_sql(spec)} THEN 1 ELSE 0 END ASC")
-        terms.append(f"{_value_sql(spec)} {'ASC' if s.get('dir') == 'asc' else 'DESC'}")
-    # Append the tiebreak even when NO sort key survived (all unknown, or none given). A
-    # windowed fetch needs a total order regardless of what the user sorted by — an unsorted
-    # LIMIT/OFFSET is exactly as unstable as a tied one. Callers wanting pure client parity
-    # pass no tiebreak_sql and still get None.
-    if tiebreak_sql:
-        terms.append(f"{tiebreak_sql} ASC")
-    return ', '.join(terms) or None
+"""harness/filter_sql.py — the grid's filter/sort engine, compiled to SQL (CG-1).
+
+THE PORT. `customer-grid/useVisibleRows.ts` evaluates the Airtable-parity filter TREE and the
+multi-level sort in TypeScript, per row, in the browser. That works at customer grain (1,550 rows,
+576 KB) and does NOT work at line grain, so a line-grain table has to filter server-side. This
+module is the second implementation of that contract, emitting parameterized SQL instead of
+booleans. `aios_grid.clean_filter_tree` (the validator) is the third. All three are held in
+lock-step by `aios-web/verify_filter_engine.py`, which runs the SAME cases through the TS engine,
+this compiler (executed on DuckDB), and the validator, and compares row sets.
+
+Design: this file is PURE — no model, no store, no app imports. It takes a filter tree plus a
+`columns` spec and returns SQL + params. `harness/semantic.store_columns` builds the spec from a
+topic; nothing else here knows what a topic is.
+
+  columns = {colId: {"sql": <SQL expression>, "type": <field type>, "aggregate": bool}}
+
+`sql` is a trusted IDENTIFIER/expression from the semantic model (never user input); every VALUE
+is a bound parameter. That split is the whole injection story.
+
+--------------------------------------------------------------------------------------------
+TRI-STATE, AND WHY IT BECOMES COMPILE-TIME PRUNING
+--------------------------------------------------------------------------------------------
+`evalNode` in TS returns true | false | null, where null means "this node is INACTIVE and its
+parent must IGNORE it". Get that wrong and a half-typed condition returns true, makes its `or`
+group true, and shows every record.
+
+Activeness reads ONLY the rule (op, value, value2, is-the-column-known) — never the row. So in
+SQL it is not a third truth value at all: it is decided while COMPILING. An inactive node emits
+no SQL, a group with no active children emits no SQL, and a root with nothing active emits NO
+PREDICATE AT ALL (`compile_filter_tree` returns None) — which is exactly `matchFilterTree`
+returning true for every row.
+
+--------------------------------------------------------------------------------------------
+THE FOUR PLACES A NAIVE PORT SILENTLY DIVERGES
+--------------------------------------------------------------------------------------------
+JavaScript coerces null to 0 / "" before comparing; SQL propagates NULL and drops the row.
+
+  1. `toNum(null)` is 0, so a NULL revenue PASSES `>= 0`.  SQL: NULL >= 0 -> NULL -> dropped.
+  2. `String(null)` is "", so a NULL state PASSES `is not FL`. SQL: NULL <> 'fl' -> dropped.
+  3. `"" <= "2026-01-01"` is true, so a NULL date PASSES `is before`. SQL: dropped.
+  4. `contains` is a LITERAL substring test. `LIKE '%v%'` treats % and _ as wildcards, so a
+     value containing either matches the wrong rows. Hence `strpos`, not LIKE.
+
+Every column is therefore read through `_value_sql`, which COALESCEs to the same zero-value
+JavaScript would have coerced to. The one thing that must NOT be coalesced away is the
+blank test itself — `isBlank` looks at the RAW value, and numeric 0 is NOT blank.
+
+--------------------------------------------------------------------------------------------
+AND THE FIFTH: `default: return true` IS ACTIVE, NOT INACTIVE
+--------------------------------------------------------------------------------------------
+`matchFilter`'s per-type switch ends in `default: return true`, reachable whenever an operator
+does not apply to the field type — `contains` on a currency/date field, or `gt`/`between` on a
+text field. A persisted tree can hold such a pair. That rule is ACTIVE and evaluates TRUE for
+every row, which is NOT the same as inactive: under `or` it makes the whole group true and shows
+everything. We emit `1=1` for those, and the gate asserts the difference is observable.
+
+--------------------------------------------------------------------------------------------
+INPUT CONTRACT
+--------------------------------------------------------------------------------------------
+Feed this CLEANED trees (`aios_grid.clean_filter_tree`). It is deliberately faithful to the TS
+engine rather than fail-closed on garbage — an unknown OP compiles to `1=1` exactly as TS's
+`default:` branch returns true — because the validator's job is to reject garbage and this
+module's job is to mean the same thing as the client. The gate proves the composition.
+
+Ported ahead of their consumer (CG-2) and gated at the same fidelity as the tree:
+`compile_search` (`matchSearch`) and `member_ids` (the hand-picked-members union in
+`useVisibleRows`).
+"""
+import math
+import re
+from collections import namedtuple
+
+# Mirrors customer-grid/types.ts FilterOp. verify_filter_engine.py asserts this set is
+# byte-identical to aios_grid.FILTER_OPS — three copies of a vocabulary need a drift gate.
+FILTER_OPS = frozenset({
+    'contains', 'doesNotContain', 'eq', 'neq', 'isEmpty', 'isNotEmpty',
+    'gt', 'gte', 'lt', 'lte', 'between', 'within',
+    'topN', 'bottomN', 'inTopPct', 'inBottomPct',
+    'aboveAvg', 'belowAvg', 'inQuartile', 'inDecile',
+})
+#: Wave 2026-08-02 (C-OPS): the RANK subset — set-ranked over the sibling-filtered domain.
+#: Vocabulary here, execution NOWHERE in this module: a per-row WHERE cannot express Top-N,
+#: and compiling to 1=0 would answer "nothing" to a question that has an answer, under a
+#: row_count that still looks authoritative. `_compile_leaf` therefore REFUSES (ValueError),
+#: the same server-side posture as a relative anchor with no `today`. The TS engine
+#:  evaluates these as a set pass in useVisibleRows (gated by web/verify_rank_filters.py).
+RANK_OPS = frozenset({'topN', 'bottomN', 'inTopPct', 'inBottomPct',
+                      'aboveAvg', 'belowAvg', 'inQuartile', 'inDecile'})
+#: The RESERVED pseudo-column of a cohort-membership leaf. Mirrors types.ts COHORT_FIELD.
+COHORT_FIELD = '__cohort__'
+#: Set operators over a SET of cohorts. Mirrors types.ts COHORT_OPS; DISJOINT from FILTER_OPS.
+COHORT_OPS = frozenset({'anyOf', 'allOf', 'noneOf'})
+#: The single-cohort ops the leaf shipped with, kept as permanent aliases. types.ts mirrors this.
+COHORT_OP_ALIASES = {'eq': 'anyOf', 'neq': 'noneOf'}
+#: Mirrors types.ts MAX_COHORT_IDS.
+MAX_COHORT_IDS = 20
+
+
+def parse_cohort_ids(value):
+    """The cohorts a leaf names. Mirrors types.ts `cohortIds()` and aios_grid.parse_cohort_ids."""
+    out = []
+    for raw in ('' if value is None else str(value)).split(','):
+        cid = raw.strip()[:120]
+        if not cid or cid in out:
+            continue
+        out.append(cid)
+        if len(out) >= MAX_COHORT_IDS:
+            break
+    return out
+# types.ts VALUE_FREE_OPS: no value control is rendered, and they must never be judged
+# "inactive because the value is blank" — that would turn them into no-ops.
+VALUE_FREE_OPS = frozenset({'isEmpty', 'isNotEmpty', 'aboveAvg', 'belowAvg'})
+# types.ts isNumericType()
+NUMERIC_TYPES = frozenset({'currency', 'int', 'pct'})
+TEXTUAL_TYPES = frozenset({'text', 'status'})
+
+SQL_TRUE = '1=1'
+
+_NUM_CMP = {'gt': '>', 'gte': '>=', 'lt': '<', 'lte': '<=', 'eq': '=', 'neq': '<>'}
+_DATE_CMP = dict(_NUM_CMP)
+
+#: sql = the predicate (already parenthesised); params = bound values, positional;
+#: uses_aggregate = the predicate references an aggregate column, so it belongs in HAVING
+#: rather than WHERE; columns_used = colIds actually referenced in the emitted SQL (an
+#: always-true `1=1` branch references nothing, and must not force HAVING routing).
+Compiled = namedtuple('Compiled', 'sql params uses_aggregate columns_used')
+
+
+# --------------------------------------------------------------------------- value coercion
+
+# JS `Number(string)` trims exactly this set (WhiteSpace + LineTerminator). Python's float() and
+# str.strip() use a DIFFERENT set -- notably U+0085 NEL, which Python treats as whitespace and JS
+# does not -- so the set is spelled out rather than left to strip().
+_JS_WS = "".join(chr(c) for c in (9, 10, 11, 12, 13, 32, 160, 5760, 8232, 8233,
+                                  8239, 8287, 12288, 65279)) + \
+         "".join(chr(c) for c in range(8192, 8203))
+# ASCII-ONLY on purpose: `\d` in a Python str pattern matches every Unicode decimal digit, so
+# `\d` here would parse the fullwidth "２５０" that JS rejects -- reintroducing the exact bug
+# this function exists to avoid.
+_JS_DEC = re.compile(r"^[+-]?(?:[0-9]+\.?[0-9]*|\.[0-9]+)(?:[eE][+-]?[0-9]+)?$")
+_JS_INF = re.compile(r"^[+-]?Infinity$")
+_JS_RADIX = ((re.compile(r"^0[xX][0-9a-fA-F]+$"), 16),
+             (re.compile(r"^0[oO][0-7]+$"), 8),
+             (re.compile(r"^0[bB][01]+$"), 2))
+
+
+def to_num(v):
+    """Port of `toNum`: JS `Number(v)`, then `Number.isFinite` or 0.
+
+    NOT `float(v)`. Python's float() is MORE permissive than JS's Number() in ways that make SQL
+    narrow where the client shows everything -- the worse direction, because at line grain that
+    is a silent under-fetch sitting beside an honest-looking row_count:
+
+        "1_000"   float() -> 1000.0 (PEP-515 underscores)   Number() -> NaN -> 0
+        "２５０"     float() -> 250.0 (any Unicode Nd)      Number() -> NaN -> 0
+        "\\u0085" + "12"  float() -> 12.0 (NEL is Python whitespace)  Number() -> NaN -> 0
+
+    and LESS permissive in one family, which errs the other way:
+
+        "0x10"    float() -> raises -> 0                    Number() -> 16   (also 0b, 0o)
+
+    A tree carrying any of these is reachable: the React builder renders <input type="number">,
+    but persisted / seeded / imported view JSON goes through `clean_filter_tree`, which passes
+    the value string through untouched by design (it validates structure, not numeric syntax).
+
+    Agreed by construction on the rest: ""/None -> 0, "abc"/"12,000" -> 0, " 250 " -> 250,
+    ".5"/"5."/"+5", "1e400" -> Infinity -> 0, "-0" -> 0, and float64 truncation of
+    "9007199254740993" -> 9007199254740992.
+    """
+    if isinstance(v, bool):
+        return 1.0 if v else 0.0                       # JS Number(true) === 1
+    if isinstance(v, (int, float)):
+        n = float(v)
+        return n if math.isfinite(n) else 0.0
+    if v is None:
+        return 0.0                                     # JS Number(null) === 0
+    s = str(v).strip(_JS_WS)
+    if s == "":
+        return 0.0                                     # JS Number("") === 0
+    if _JS_INF.match(s):
+        return 0.0                                     # Infinity is not finite -> 0
+    for pattern, base in _JS_RADIX:
+        if pattern.match(s):
+            return float(int(s[2:], base))
+    if not _JS_DEC.match(s):
+        return 0.0                                     # JS NaN -> 0
+    n = float(s)
+    return n if math.isfinite(n) else 0.0
+
+
+def _value_sql(spec):
+    """The ONE expression for a column, used by BOTH the filter and the sort.
+
+    Two expressions would let two rows tie in the grid and not tie in SQL (dates truncated for
+    comparison but ordered by the raw timestamp is the obvious way to get that wrong), so the
+    next sort key would break the tie in one engine and not the other.
+
+    numeric: `round_even(x, 0)` reproduces `aios_grid._round`, which is Python's round() =
+    BANKER'S rounding. DuckDB's plain ROUND() rounds half AWAY from zero, so ROUND(1234.5)=1235
+    while the grid shows 1234 — `eq 1234` would then match on screen and miss in SQL. The grid
+    displays rounded values; filters must agree with what is on screen.
+    date: truncate to the 10-char ISO shape the payload carries, so lexical compare is
+    chronological and a timestamp column cannot smuggle ' 00:00:00' into the comparison.
+    text: lowercased, matching `String(raw ?? "").toLowerCase()`.
+    """
+    e = spec['sql']
+    t = spec['type']
+    if t in NUMERIC_TYPES:
+        return f"COALESCE(round_even(TRY_CAST({e} AS DOUBLE), 0), 0)"
+    if t == 'date':
+        return f"COALESCE(SUBSTR(CAST({e} AS VARCHAR), 1, 10), '')"
+    return f"LOWER(COALESCE(CAST({e} AS VARCHAR), ''))"
+
+
+def _blank_sql(spec):
+    """Port of `isBlank`: null/undefined/"" are blank — numeric 0 is NOT.
+
+    Reads the RAW column, never `_value_sql` (which has already coalesced blanks into 0/"",
+    the very distinction this test exists to make).
+    """
+    e = spec['sql']
+    if spec['type'] in NUMERIC_TYPES:
+        # 0 stays non-blank: CAST(0 AS VARCHAR) is '0'. The '' arm covers a text-typed column
+        # holding "", which `_round` passes through unchanged into the payload.
+        return f"(({e}) IS NULL OR CAST({e} AS VARCHAR) = '')"
+    if spec['type'] == 'date':
+        return f"(COALESCE(SUBSTR(CAST({e} AS VARCHAR), 1, 10), '') = '')"
+    return f"(COALESCE(CAST({e} AS VARCHAR), '') = '')"
+
+
+# --------------------------------------------------------------------------- activeness
+
+def is_rule_active(rule, columns):
+    """Port of `isRuleActive` + `evalNode`'s two leaf guards. Row-independent by construction.
+
+    Unknown column -> inactive (evalNode returns null before matchFilter is ever called).
+    Value-free ops are always active. `between` needs BOTH bounds.
+
+    ⚠ The four VALUE-FREE ANCHOR MODES (`is before [today]`) carry no value, and the historical
+    "blank value = inactive" rule would IGNORE them — widening the result under a count nobody
+    would doubt. Same shape as the isEmpty/isNotEmpty no-op bug, arriving by a different door.
+    """
+    if not isinstance(rule, dict):
+        return False
+    col = rule.get('colId')
+    if col == COHORT_FIELD:                       # a cohort leaf has no column to look up
+        # Driven by the SET it names, so a value of "," is INACTIVE rather than active-and-
+        # unanswerable. Mirrors the cohort branch at the top of types.ts isRuleActive.
+        return bool(parse_cohort_ids(rule.get('value')))
+    if col not in columns:
+        return False
+    op = rule.get('op')
+    if op in VALUE_FREE_OPS:
+        return True
+    if op == 'within':
+        return _window_bounds(rule.get('dateWindow'), None, probe=True)
+    if rule.get('rhs') is not None:
+        rhs = rule['rhs']
+        # An rhs naming a column this table does not have is IGNORED, by the same rule as an
+        # unknown left column two lines above — for EITHER kind. Ignoring one side and hiding
+        # every row for the other would make the comparison asymmetric in a way nobody could
+        # predict. Doing it here rather than in _compile_leaf keeps activeness the single place
+        # that decides, which is what makes the compiled branch below provably unreachable.
+        if not isinstance(rhs, dict) or rhs.get('colId') not in columns:
+            return False
+        return _rhs_complete(rhs)
+    if rule.get('dateMode') in _ANCHOR_VALUE_FREE:
+        return True
+    value = _as_str(rule.get('value'))
+    if op == 'between':
+        v2 = rule.get('value2')
+        return value != '' and v2 is not None and _as_str(v2) != ''
+    return value != ''
+
+
+def _rhs_complete(rhs):
+    """Port of types.ts isRhsComplete. An incomplete rhs makes the rule INACTIVE, exactly as a
+    half-typed value does."""
+    if not isinstance(rhs, dict) or not rhs.get('colId'):
+        return False
+    if rhs.get('kind') == 'measure':
+        return _windows().normalize(rhs.get('window')) is not None
+    return rhs.get('kind') == 'field'
+
+
+def _windows():
+    """`harness.windows` imported lazily, so this module stays importable on its own.
+
+    filter_sql is otherwise PURE (no model/store/app imports) and that property is what lets
+    aios_grid embed the grid anywhere. windows.py is the one exception and it is a deliberate
+    one: the date vocabulary is a two-ENGINE contract, and a third copy of "what the past month
+    means" is precisely the drift verify_windows.py exists to prevent. It imports nothing but
+    datetime, so purity is preserved in substance.
+    """
+    from harness import windows as _w
+    return _w
+
+
+#: Mirrors windows.ANCHOR_VALUE_FREE, resolved lazily on first use (see _windows).
+class _AnchorValueFree:
+    def __contains__(self, mode):
+        return mode in _windows().ANCHOR_VALUE_FREE
+
+
+_ANCHOR_VALUE_FREE = _AnchorValueFree()
+
+
+def _window_bounds(spec, today, probe=False):
+    """Resolve a date-condition RANGE, or refuse.
+
+    `probe=True` answers only "is this a resolvable window?" without needing `today` — which is
+    what activeness has to know while compiling, before any date is in hand.
+
+    ⚠ A missing `today` on the real path RAISES rather than widening. The client's answer to the
+    same gap is to match nothing; the server's must be to refuse, because a server that quietly
+    drops a condition reports an authoritative row_count for a query nobody asked for. Same rule
+    as the sibling/depth caps: truncate on the client, refuse on the server.
+    """
+    w = _windows()
+    if probe:
+        return w.normalize(spec) is not None
+    if today is None:
+        raise ValueError(
+            'a relative-date condition needs `today` — compile_filter_tree(today=...). '
+            'Refusing rather than dropping the condition, which would widen the result while '
+            'the count beside it still looked authoritative.')
+    return w.resolve(spec, today)
+
+
+def _as_str(v):
+    """The builder stores values as raw input strings; be tolerant of a number that survived
+    an older payload. `str(500) != ''` is active and `to_num` reads it back, matching JS where
+    `500 === ""` is false."""
+    return '' if v is None else str(v)
+
+
+# --------------------------------------------------------------------------- leaf
+
+def _compile_leaf(rule, columns, state):
+    """Port of `matchFilter`. Returns (sql, params) or None when the rule is INACTIVE."""
+    if not is_rule_active(rule, columns):
+        return None
+    col_id = rule['colId']
+    op = rule.get('op')
+    value = _as_str(rule.get('value'))
+
+    # --- owner item 5: a COHORT leaf, before any column lookup -------------------------------
+    # `__cohort__` is not a column. Handled first for the same reason evalNode handles it first:
+    # falling through to the column path would make it INACTIVE, and inactive means every row.
+    if col_id == COHORT_FIELD:
+        return _compile_cohort(rule, state)
+
+    # --- C-OPS (wave 2026-08-02): a RANK leaf is structurally unanswerable at row grain ------
+    # Top-N / quantile membership is a property of the SET, not the row; the client engine
+    # answers it with a set pass over the sibling-filtered domain. Refuse loudly rather than
+    # compile something that means a different question (see RANK_OPS).
+    if op in RANK_OPS:
+        raise ValueError(
+            f'rank operator {op!r} cannot compile to row SQL - evaluate it as a set pass '
+            f'(the client engine) or pre-resolve the matching ids before compiling')
+
+    spec = columns[col_id]
+
+    def used(sql, params=()):
+        state['used'].add(col_id)
+        if spec.get('aggregate'):
+            state['aggregate'] = True
+        return (sql, list(params))
+
+    # --- value-free ops, BEFORE any value-based short-circuit (the no-op bug) ---------------
+    if op == 'isEmpty':
+        return used(_blank_sql(spec))
+    if op == 'isNotEmpty':
+        return used(f"NOT {_blank_sql(spec)}")
+
+    v = _value_sql(spec)
+    t = spec['type']
+
+    # --- CG-9: the comparand is another COLUMN, coerced through the LEFT field's type --------
+    # `_value_sql` on a spec whose `sql` is the RIGHT column and whose `type` is the LEFT one —
+    # exactly what TS does (`toNum(other)` for a numeric LHS, `String(other ?? "")` for a date,
+    # `.toLowerCase()` for text). Reading the right column through its OWN type would compare a
+    # rounded number against an unrounded one and disagree on the ties.
+    rhs_v = None
+    if rule.get('rhs') is not None:
+        # No `rspec is None` branch: `is_rule_active` already rejected an rhs naming a column
+        # this table does not have, so it cannot be missing here. A defensive fallback would be
+        # unreachable, and the negative control showed exactly that — deleting it changed
+        # nothing, which is how dead code hides behind a careful-looking line.
+        rspec = columns[rule['rhs']['colId']]
+        rhs_v = _value_sql({'sql': rspec['sql'], 'type': t})
+        state['used'].add(rule['rhs']['colId'])
+        if rspec.get('aggregate'):
+            state['aggregate'] = True
+
+    if t in NUMERIC_TYPES:
+        if rhs_v is not None:
+            return used(f"({v} {_NUM_CMP[op]} {rhs_v})") if op in _NUM_CMP else (SQL_TRUE, [])
+        if op == 'between':
+            a, b = to_num(value), to_num(rule.get('value2'))
+            return used(f"({v} >= ? AND {v} <= ?)", [min(a, b), max(a, b)])
+        if op in _NUM_CMP:
+            return used(f"({v} {_NUM_CMP[op]} ?)", [to_num(value)])
+        return (SQL_TRUE, [])          # contains/doesNotContain on a number -> default: true
+
+    if t == 'date':
+        if op == 'within':
+            bounds = _window_bounds(rule.get('dateWindow'), state.get('today'))
+            if bounds is None:
+                return ('1=0', [])     # unreachable: activeness probed it. Never widen.
+            lo, hi = bounds
+            # `{v} <> ''` is NOT redundant. `_value_sql` COALESCEs a NULL date to '', and
+            # '' <= any upper bound is true — so an open-ended window would sweep in every
+            # never-ordered customer. TS guards it with `if (a === "") return false`.
+            parts, params = [f"{v} <> ''"], []
+            if lo is not None:
+                parts.append(f"{v} >= ?")
+                params.append(lo)
+            if hi is not None:
+                parts.append(f"{v} <= ?")
+                params.append(hi)
+            return used('(' + ' AND '.join(parts) + ')', params)
+        if rhs_v is not None:
+            return used(f"({v} {_DATE_CMP[op]} {rhs_v})") if op in _DATE_CMP else (SQL_TRUE, [])
+        if op == 'between':
+            v2 = _as_str(rule.get('value2'))
+            lo, hi = (value, v2) if value < v2 else (v2, value)
+            return used(f"({v} >= ? AND {v} <= ?)", [lo, hi])
+        if op in _DATE_CMP:
+            anchor = _resolve_anchor(rule.get('dateMode'), value, state.get('today'))
+            if anchor is None:
+                return ('1=0', [])     # unresolvable anchor -> matches nothing (TS: false)
+            return used(f"({v} {_DATE_CMP[op]} ?)", [anchor])
+        return (SQL_TRUE, [])          # contains/doesNotContain on a date -> default: true
+
+    # text / status — case-insensitive. strpos, not LIKE: `includes` is a LITERAL substring
+    # test, so a value holding % or _ must not act as a wildcard.
+    #
+    # BOTH SIDES fold in SQL (`LOWER(?)`, never Python's str.lower()). Python and JS agree on
+    # case folding; DuckDB does NOT — LOWER('ISTANBUL' with a dotted capital I) drops the dot
+    # while both languages keep it as i + combining dot. Folding the needle in Python and the
+    # haystack in DuckDB therefore produced two different strings, and a value could fail to
+    # match ITSELF. One folder for both operands is the only version that cannot do that.
+    if rhs_v is not None:
+        # Both operands are already folded by `_value_sql` (text branch), so no LOWER(?) here.
+        if op == 'contains':
+            return used(f"(strpos({v}, {rhs_v}) > 0)")
+        if op == 'doesNotContain':
+            return used(f"(strpos({v}, {rhs_v}) = 0)")
+        if op == 'eq':
+            return used(f"({v} = {rhs_v})")
+        if op == 'neq':
+            return used(f"({v} <> {rhs_v})")
+        return (SQL_TRUE, [])
+    if op == 'contains':
+        return used(f"(strpos({v}, LOWER(?)) > 0)", [value])
+    if op == 'doesNotContain':
+        return used(f"(strpos({v}, LOWER(?)) = 0)", [value])
+    if op == 'eq':
+        return used(f"({v} = LOWER(?))", [value])
+    if op == 'neq':
+        return used(f"({v} <> LOWER(?))", [value])
+    return (SQL_TRUE, [])              # gt/gte/lt/lte/between/within on text -> default: true
+
+
+def _resolve_anchor(mode, value, today):
+    """A date condition's anchor -> one ISO date, or None. `today` may be absent ONLY for the
+    `exact` mode, which does not use it.
+
+    The sentinel is deliberate and load-bearing for BACK-COMPAT: every date filter that existed
+    before anchors is `exact`, and every caller that compiles one (store_query, store_rows)
+    passes no `today`. Requiring it unconditionally would turn a working filter into an
+    exception. A RELATIVE anchor still refuses — the server never widens.
+    """
+    mode = mode or 'exact'
+    if today is None:
+        if mode != 'exact':
+            raise ValueError(
+                f"the date anchor {mode!r} is relative and needs `today` — "
+                f"compile_filter_tree(today=...). Refusing rather than dropping the condition, "
+                f"which would widen the result under an authoritative-looking count.")
+        # `exact` ignores `today` entirely (verify_windows resolves it across 11 probe dates and
+        # gets the same answer every time), so any valid date serves as the unused argument.
+        today = '1970-01-01'
+    return _windows().resolve_anchor(mode, value, today)
+
+
+def _compile_cohort(rule, state):
+    """Port of evalNode's cohort branch: membership in a SET of hand-curated sets of row ids.
+
+    Owner 2026-07-27: the leaf names one OR MORE cohorts and asks `anyOf` / `allOf` / `noneOf`.
+    A single id is a one-element set, so the shipped `is part of` compiles down this same path.
+
+    States, mirroring TS exactly:
+      every set present         -> the union (anyOf / noneOf) or the intersection (allOf)
+      a set present but EMPTY   -> that member contributes 1=0, because nobody is in an empty
+                                   cohort. So `allOf` collapses to 1=0 and `noneOf` to 1=1 —
+                                   which is what `set.has(pid)` on an empty Set does in TS.
+      ANY set ABSENT            -> 1=0 for ALL THREE ops. The condition is unanswerable, and
+                                   unanswerable matches nothing: answering "everything" to
+                                   `is none of [a cohort we cannot see]` is the widening sin
+                                   wearing a plausible face, and answering it for the members we
+                                   DO have would silently ask a different question.
+
+    COALESCE(... , FALSE) because a NULL row id makes `id IN (...)` NULL, and `NOT NULL` is NULL
+    — SQL would drop the row where TS keeps it.
+    """
+    sets = state.get('cohort_sets')
+    if sets is None:
+        raise ValueError(
+            'a cohort condition needs cohort_sets — compile_filter_tree(cohort_sets=...). '
+            'Refusing rather than dropping it: a dropped condition widens the result while the '
+            'count beside it still looks authoritative.')
+    id_sql = state.get('id_sql')
+    if not id_sql:
+        raise ValueError('a cohort condition needs id_sql (the row-identity column)')
+    op = COHORT_OP_ALIASES.get(rule.get('op'), rule.get('op'))
+    named = parse_cohort_ids(rule.get('value'))
+    members = [sets.get(cid) for cid in named]
+    if not named or any(m is None for m in members):
+        return ('1=0', [])
+
+    parts, params = [], []
+    for ids in members:
+        ids = [int(x) for x in ids]
+        if not ids:
+            parts.append('1=0')
+            continue
+        parts.append(f"COALESCE({id_sql} IN ({','.join('?' for _ in ids)}), FALSE)")
+        params.extend(ids)
+    if op == 'allOf':
+        return ('(' + ' AND '.join(parts) + ')', params)
+    union = '(' + ' OR '.join(parts) + ')'
+    return ((f"(NOT {union})" if op == 'noneOf' else union), params)
+
+
+# --------------------------------------------------------------------------- tree
+
+def _compile_node(node, columns, state):
+    """Port of `evalNode`. Returns (sql, params), or None when the node is INACTIVE.
+
+    A group combines only its ACTIVE children with its OWN conjunction; a group with no active
+    children is itself inactive and disappears. That is what stops a half-built group from
+    either zeroing the grid (`and`) or disabling it (`or`).
+    """
+    if not isinstance(node, dict):
+        return None
+    if isinstance(node.get('children'), list):
+        parts, params = [], []
+        for child in node['children']:
+            got = _compile_node(child, columns, state)
+            if got is None:
+                continue                                   # inactive -> ignored entirely
+            parts.append(got[0])
+            params.extend(got[1])
+        if not parts:
+            return None
+        joiner = ' OR ' if node.get('conj') == 'or' else ' AND '
+        return ('(' + joiner.join(parts) + ')', params)
+    return _compile_leaf(node, columns, state)
+
+
+def compile_filter_tree(nodes, conj='and', columns=None, member_ids=None, id_sql=None,
+                        today=None, cohort_sets=None):
+    """Port of `matchFilterTree` (+ the `memberPids` union in `useVisibleRows`).
+
+    Returns a `Compiled`, or **None when nothing is active** — meaning no predicate at all, not
+    a false one. `matchFilterTree` returns true when the tree is inactive, so emitting anything
+    here would narrow rows the client would have shown.
+
+    `member_ids` reproduces `members.has(r.pid) || matchFilterTree(...)`. Note the union lives
+    INSIDE `if (filters.length)` and is OR'd with a tree that is true for everything when
+    inactive — so an inactive tree must emit NOTHING, never `pid IN (...)`, which would narrow
+    to just the hand-picked members. Same family of bug as the tri-state one, inverted.
+
+    `today` is the TENANT'S today, required by any relative date condition (`is within …`,
+    `is before [one month ago]`) and by nothing else — an `exact` date needs none, which is what
+    keeps every pre-anchor caller working unchanged. `cohort_sets` is `{cohortId: [pid, ...]}`
+    for cohort-membership leaves. Both REFUSE when needed and missing; neither defaults.
+    """
+    state = {'aggregate': False, 'used': set(),
+             'today': today, 'cohort_sets': cohort_sets, 'id_sql': id_sql}
+    got = _compile_node({'conj': conj, 'children': list(nodes or [])}, columns or {}, state)
+    if got is None:
+        return None
+    sql, params = got
+    if member_ids:
+        if not id_sql:
+            raise ValueError('member_ids requires id_sql (the row-identity column)')
+        ids = [int(x) for x in member_ids]
+        sql = f"({sql} OR {id_sql} IN ({','.join('?' for _ in ids)}))"
+        params = list(params) + ids
+    return Compiled(sql, list(params), state['aggregate'], frozenset(state['used']))
+
+
+def compile_search(q, columns):
+    """Port of `matchSearch`: the narrowing search box.
+
+    True if ANY human-readable (text/status) column contains `q`, case-insensitively. NUMERIC
+    columns are skipped on purpose so a query like "10" does not match revenue or order counts.
+    Dates are skipped too — `matchSearch` tests only text and status.
+
+    The caller ANDs this with the filter predicate, matching the TS pipeline order
+    (filter -> search). It is deliberately OUTSIDE the `member_ids` union: in `useVisibleRows`
+    the union applies to the filter step only, so a hand-picked member is still searchable away.
+    """
+    # `.strip(_JS_WS)`, not `.strip()`: the client trims with JS String.trim(), whose whitespace
+    # set differs from Python's in BOTH directions (Python strips U+0085 NEL and U+001C..1F,
+    # JS does not; JS strips U+FEFF, Python does not). A query of just those characters is
+    # blank to one engine and a real search to the other. Folding is left to SQL — see the
+    # LOWER(?) note in _compile_leaf.
+    q = (q or '').strip(_JS_WS)
+    if not q:
+        return None
+    parts, params, used = [], [], set()
+    aggregate = False
+    for col_id, spec in (columns or {}).items():
+        if spec['type'] not in TEXTUAL_TYPES:
+            continue
+        parts.append(f"(strpos({_value_sql(spec)}, LOWER(?)) > 0)")
+        params.append(q)
+        used.add(col_id)
+        aggregate = aggregate or bool(spec.get('aggregate'))
+    if not parts:
+        # No searchable column: `matchSearch` returns false for every row, so the search
+        # narrows to nothing. That is a real predicate, not an absent one.
+        return Compiled('1=0', [], False, frozenset())
+    return Compiled('(' + ' OR '.join(parts) + ')', params, aggregate, frozenset(used))
+
+
+def compile_order_by(sorts, columns, tiebreak_sql=None):
+    """Port of `makeComparator`. Returns an ORDER BY body, or None when nothing sorts.
+
+    `tiebreak_sql` (the row-identity column) is appended as a final ASC key and is REQUIRED for
+    any windowed fetch. `Array.prototype.sort` is stable, so TS leaves tied rows in their
+    incoming order; SQL guarantees NOTHING for ties, so LIMIT/OFFSET paging over a non-total
+    order can repeat a row on one page and drop it from another. Appending row identity makes
+    the order total. It is a STRENGTHENING of the TS guarantee, not a divergence: the payload a
+    windowed fetch produces is itself in this order, so the client never re-sorts it differently.
+
+    BLANKS SORT LAST IN BOTH DIRECTIONS (Airtable's behavior, and the reason descending
+    "Last order" leads with the most recent rather than with never-ordered customers). Each key
+    contributes TWO terms: an always-ASC blank flag, then the value in the requested direction.
+    Two blanks tie on both terms, so the NEXT key decides — matching the comparator's
+    `if (aBlank && bBlank) continue`.
+
+    An unknown column is skipped: in TS its values are `undefined` on both sides, so both are
+    blank and the key is a no-op tiebreak.
+
+    Direction: `s.dir === "asc" ? c : -c` — only the exact string "asc" ascends, anything else
+    descends. Faithfully reproduced; do not "fix" it to default ASC.
+
+    Residual divergence, deliberate: TS uses `localeCompare`, we use LOWER() + DuckDB's binary
+    collation. They agree on case-insensitive ordering of ASCII and on ISO dates (unaffected by
+    LOWER), and differ on locale tie-breaks between case-variants of the same string ("a" vs
+    "A" sort adjacent under localeCompare, tie under LOWER) and on accent ordering.
+    """
+    terms = []
+    for s in (sorts or []):
+        if not isinstance(s, dict):
+            continue
+        spec = (columns or {}).get(s.get('colId'))
+        if spec is None:
+            continue
+        terms.append(f"CASE WHEN {_blank_sql(spec)} THEN 1 ELSE 0 END ASC")
+        terms.append(f"{_value_sql(spec)} {'ASC' if s.get('dir') == 'asc' else 'DESC'}")
+    # Append the tiebreak even when NO sort key survived (all unknown, or none given). A
+    # windowed fetch needs a total order regardless of what the user sorted by — an unsorted
+    # LIMIT/OFFSET is exactly as unstable as a tied one. Callers wanting pure client parity
+    # pass no tiebreak_sql and still get None.
+    if tiebreak_sql:
+        terms.append(f"{tiebreak_sql} ASC")
+    return ', '.join(terms) or None

platform/harness/semantic.py

@@ -608,6 +608,12 @@ def store_columns(topic, include_measures=True, grain="aggregate"):
     return cols
 
 
+#: The ceiling for a GROUPED `store_query`. One row per group, so this bounds DIMENSION
+#: CARDINALITY, not payload — a tenant would need 200,000 distinct customers (or products, or
+#: cities) to reach it. Deliberately NOT unbounded: a runaway group-by should fail, not swap.
+MAX_GROUPS = 200_000
+
+
 def store_query(topic, measures, group_by=None, grain=None, date_from=None, date_to=None,
                 team_id=None, filters=None, sort=None, limit=1000, exclude_services=False,
                 filter_tree=None, filter_conj="and", today=None):
@@ -619,7 +625,24 @@ def store_query(topic, measures, group_by=None, grain=None, date_from=None, date
     s = t["store"]
     alias = s["alias"]
     dims = s.get("dims") or {}
-    limit = max(1, min(int(limit or 1000), 5000))
+    # ⭐ A GROUPED QUERY IS BOUNDED BY GROUPS, NOT BY ROWS — and the 5,000 row ceiling applied to
+    # both, which made it a SILENT TRUNCATION of the answer rather than of a payload.
+    #
+    # ⛔ MEASURED 2026-08-09 on the Royal mirror, grouping 256,810 order lines by customer:
+    #       limit=100  -> 100 groups, total    1,644,181.65
+    #       limit=1000 -> 1000 groups, total   9,042,614.10
+    #       limit=5000 -> 1748 groups, total  14,567,929.72
+    # The TOTAL MOVES WITH THE CAP. A row window is honest because counts and totals are computed
+    # over the full scope beside it (`store_rows`' whole design); a GROUP window has no such
+    # companion — the groups ARE the answer, so dropping one is dropping data with nothing to
+    # notice. Royal has 1,943 customers so it passes today and would have passed every test,
+    # then gone quietly wrong for the first tenant with more ([[no-unverifiable-aggregates]]).
+    #
+    # ⚠ The ceiling is not removed, because unbounded is its own failure. It is raised to a bound
+    # no realistic dimension reaches, and — the load-bearing half — truncation is now a FACT the
+    # caller can read rather than something it must infer from `len(rows)`.
+    grouped = bool(group_by)
+    limit = max(1, min(int(limit or 1000), MAX_GROUPS if grouped else 5000))
 
     base_keys, requested = _expand_measures(list(measures or []))
     if not base_keys:
@@ -722,7 +745,9 @@ def store_query(topic, measures, group_by=None, grain=None, date_from=None, date
         sql += f" ORDER BY {key} {'DESC' if sort.startswith('-') else 'ASC'}"
     elif grain:
         sql += " ORDER BY period"
-    sql += f" LIMIT {limit}"
+    # ⚠ `limit + 1` — ONE extra row, so "did this truncate" is a FACT and not the guess
+    # `len(rows) == limit` makes (which is wrong exactly when the count lands on the cap).
+    sql += f" LIMIT {limit + 1}"
 
     con = _store_con()
     try:
@@ -738,8 +763,14 @@ def store_query(topic, measures, group_by=None, grain=None, date_from=None, date
                 row[k] = _post_compute(row, k)
         if "period" in row and row["period"] is not None:
             row["period"] = str(row["period"])[:10]
+    truncated = len(rows) > limit
+    if truncated:
+        rows = rows[:limit]
     return {"topic": topic, "rows": rows, "row_count": len(rows), "sql": sql,
-            "measures": requested, "group_by": gb, "grain": grain}
+            "measures": requested, "group_by": gb, "grain": grain,
+            # ⛔ A CALLER THAT AGGREGATES THESE ROWS MUST CHECK THIS. For a grouped query the
+            # groups ARE the answer, so a truncated result is a WRONG NUMBER, not a short list.
+            "truncated": truncated}
 
 
 def store_rows(topic, date_from=None, date_to=None, team_id=None, filter_tree=None,

platform/harness/tables.py

@@ -1,129 +1,129 @@
-"""harness/tables.py — a topic-backed TABLE for the grid (CG-2).
-
-The grid's first table (customers) is built from `modules.customer_data.pool()`: one row per
-customer, the whole book shipped as component args, filtered client-side. That works at 1,550
-rows and does not work at line grain — `sales_lines` is 201,558 rows / ~89 MB.
-
-This module builds the SECOND table: rows come from `semantic.store_rows`, so the fetch is
-WINDOWED and the filtering is SQL. Its whole job is to hand the grid a payload in the same
-host-neutral shape the React component already speaks, plus the one thing a windowed table must
-carry that a whole-book table never needed:
-
-    counts = {matched, total, shown, windowed}
-
-`matched` and `total` come from their own queries over the FULL scope; `shown` is the size of
-this window. The component renders "showing SHOWN of MATCHED (filtered from TOTAL)" from those
-numbers and NEVER from `rows.length` — which is the difference between an honest window and a
-silent `[:N]` wearing a total ([[no-unverifiable-aggregates]]).
-
-The field CONTRACT is derived from the topic, not hand-written: labels and types come from the
-model's dims and metrics, so a new metric cannot arrive as an untyped, unlabelled column and the
-grid can never disagree with the semantic layer about what a column means.
-"""
-from harness import semantic as _sem
-
-#: Topic-backed tables the grid can open. `key` is the storage key its saved views live under —
-#: separate from the customer table's, so the two tables' views can never collide.
-TOPIC_TABLES = {
-    "sales_lines": {
-        "label": "Sales lines",
-        "storage_key": "sales_lines_table_workspace",
-        # the columns worth defaulting to visible, in order; everything else stays available
-        "default_visible": ["date", "order_partner", "product", "category", "state", "agent",
-                            "team", "revenue", "units", "margin"],
-        # a line-grain table is unusable sorted by nothing in particular
-        "default_sorts": [{"colId": "date", "dir": "desc"}],
-    },
-}
-
-#: how many rows one window carries. Small enough that the payload stays a few hundred KB at
-#: ~440 B/row, large enough to scroll. The honest counts make the window visible rather than
-#: silent, so this is a performance knob and not a correctness one.
-PAGE_ROWS = 200
-
-
-def _labels(topic):
-    """colId -> human label, taken from the MODEL (dim labels, metric labels)."""
-    t = _sem.topics()[topic]
-    out = {}
-    for key, d in ((t.get("store") or {}).get("dims") or {}).items():
-        out[key] = d.get("label") or key.replace("_", " ").title()
-        out[f"{key}_id"] = f"{out[key]} id"
-    out["date"] = "Date"
-    for k, m in _sem.metrics().items():
-        if m.get("topic") == topic:
-            out[k] = m.get("label") or k
-    return out
-
-
-def table_fields(topic):
-    """The grid field contract for a topic, derived from the semantic model.
-
-    Every column is `source='odoo'` — read-only. A line is a fact from the ERP; unlike the
-    customer table there is no overlay stratum here (notes/tags hang off a CUSTOMER, not off an
-    individual order line), so the two-strata split simply does not arise.
-    """
-    cfg = TOPIC_TABLES[topic]
-    cols = _sem.store_columns(topic, grain="row")
-    labels = _labels(topic)
-    order = [k for k in cfg["default_visible"] if k in cols]
-    order += [k for k in cols if k not in order]
-    return [{
-        "key": k,
-        "label": labels.get(k, k.replace("_", " ").title()),
-        "type": cols[k]["type"],
-        "source": "odoo",
-        "default": k in cfg["default_visible"],
-    } for k in order]
-
-
-def table_payload(topic, config=None, offset=0, limit=None, team_id=None,
-                  date_from=None, date_to=None):
-    """Fetch ONE window of a topic-backed table plus its scope-wide counts and totals.
-
-    `config` is a grid ViewConfig (filters / filterConj / sorts / search) — the same shape the
-    customer table persists, so a saved view means the same thing on either table.
-
-    Returns the component payload: {fields, rows, counts, aggregates, storageKey}.
-    """
-    if topic not in TOPIC_TABLES:
-        raise _sem.ModelError(f"no topic-backed table registered for {topic!r}")
-    cfg = TOPIC_TABLES[topic]
-    config = config or {}
-    limit = PAGE_ROWS if limit is None else limit
-
-    got = _sem.store_rows(
-        topic,
-        filter_tree=config.get("filters") or [],
-        filter_conj=config.get("filterConj") or "and",
-        search=config.get("search") or None,
-        sorts=config.get("sorts") or cfg["default_sorts"],
-        member_ids=config.get("memberPids") or None,
-        limit=limit, offset=offset,
-        team_id=team_id, date_from=date_from, date_to=date_to,
-    )
-
-    rows = []
-    for i, r in enumerate(got["rows"]):
-        # `pid` is the grid's row identity contract (selection, detail, overlay all key on it).
-        # At line grain that identity is the order LINE id, which store_rows returns as _rid.
-        row = {k: v for k, v in r.items() if k != "_rid"}
-        row["pid"] = r["_rid"]
-        rows.append(row)
-
-    return {
-        "fields": table_fields(topic),
-        "rows": rows,
-        # THE honest window. `matched`/`total` are scope-wide queries; `shown` is this window.
-        # A caller must never recompute `matched` from len(rows).
-        "counts": {
-            "shown": len(rows),
-            "matched": got["row_count"],
-            "total": got["total_count"],
-            "windowed": True,
-        },
-        "aggregates": got["aggregates"],      # over the whole FILTERED scope, not the window
-        "storageKey": cfg["storage_key"],
-        "label": cfg["label"],
-        "window": got["window"],
-    }
+"""harness/tables.py — a topic-backed TABLE for the grid (CG-2).
+
+The grid's first table (customers) is built from `modules.customer_data.pool()`: one row per
+customer, the whole book shipped as component args, filtered client-side. That works at 1,550
+rows and does not work at line grain — `sales_lines` is 201,558 rows / ~89 MB.
+
+This module builds the SECOND table: rows come from `semantic.store_rows`, so the fetch is
+WINDOWED and the filtering is SQL. Its whole job is to hand the grid a payload in the same
+host-neutral shape the React component already speaks, plus the one thing a windowed table must
+carry that a whole-book table never needed:
+
+    counts = {matched, total, shown, windowed}
+
+`matched` and `total` come from their own queries over the FULL scope; `shown` is the size of
+this window. The component renders "showing SHOWN of MATCHED (filtered from TOTAL)" from those
+numbers and NEVER from `rows.length` — which is the difference between an honest window and a
+silent `[:N]` wearing a total ([[no-unverifiable-aggregates]]).
+
+The field CONTRACT is derived from the topic, not hand-written: labels and types come from the
+model's dims and metrics, so a new metric cannot arrive as an untyped, unlabelled column and the
+grid can never disagree with the semantic layer about what a column means.
+"""
+from harness import semantic as _sem
+
+#: Topic-backed tables the grid can open. `key` is the storage key its saved views live under —
+#: separate from the customer table's, so the two tables' views can never collide.
+TOPIC_TABLES = {
+    "sales_lines": {
+        "label": "Sales lines",
+        "storage_key": "sales_lines_table_workspace",
+        # the columns worth defaulting to visible, in order; everything else stays available
+        "default_visible": ["date", "order_partner", "product", "category", "state", "agent",
+                            "team", "revenue", "units", "margin"],
+        # a line-grain table is unusable sorted by nothing in particular
+        "default_sorts": [{"colId": "date", "dir": "desc"}],
+    },
+}
+
+#: how many rows one window carries. Small enough that the payload stays a few hundred KB at
+#: ~440 B/row, large enough to scroll. The honest counts make the window visible rather than
+#: silent, so this is a performance knob and not a correctness one.
+PAGE_ROWS = 200
+
+
+def _labels(topic):
+    """colId -> human label, taken from the MODEL (dim labels, metric labels)."""
+    t = _sem.topics()[topic]
+    out = {}
+    for key, d in ((t.get("store") or {}).get("dims") or {}).items():
+        out[key] = d.get("label") or key.replace("_", " ").title()
+        out[f"{key}_id"] = f"{out[key]} id"
+    out["date"] = "Date"
+    for k, m in _sem.metrics().items():
+        if m.get("topic") == topic:
+            out[k] = m.get("label") or k
+    return out
+
+
+def table_fields(topic):
+    """The grid field contract for a topic, derived from the semantic model.
+
+    Every column is `source='odoo'` — read-only. A line is a fact from the ERP; unlike the
+    customer table there is no overlay stratum here (notes/tags hang off a CUSTOMER, not off an
+    individual order line), so the two-strata split simply does not arise.
+    """
+    cfg = TOPIC_TABLES[topic]
+    cols = _sem.store_columns(topic, grain="row")
+    labels = _labels(topic)
+    order = [k for k in cfg["default_visible"] if k in cols]
+    order += [k for k in cols if k not in order]
+    return [{
+        "key": k,
+        "label": labels.get(k, k.replace("_", " ").title()),
+        "type": cols[k]["type"],
+        "source": "odoo",
+        "default": k in cfg["default_visible"],
+    } for k in order]
+
+
+def table_payload(topic, config=None, offset=0, limit=None, team_id=None,
+                  date_from=None, date_to=None):
+    """Fetch ONE window of a topic-backed table plus its scope-wide counts and totals.
+
+    `config` is a grid ViewConfig (filters / filterConj / sorts / search) — the same shape the
+    customer table persists, so a saved view means the same thing on either table.
+
+    Returns the component payload: {fields, rows, counts, aggregates, storageKey}.
+    """
+    if topic not in TOPIC_TABLES:
+        raise _sem.ModelError(f"no topic-backed table registered for {topic!r}")
+    cfg = TOPIC_TABLES[topic]
+    config = config or {}
+    limit = PAGE_ROWS if limit is None else limit
+
+    got = _sem.store_rows(
+        topic,
+        filter_tree=config.get("filters") or [],
+        filter_conj=config.get("filterConj") or "and",
+        search=config.get("search") or None,
+        sorts=config.get("sorts") or cfg["default_sorts"],
+        member_ids=config.get("memberPids") or None,
+        limit=limit, offset=offset,
+        team_id=team_id, date_from=date_from, date_to=date_to,
+    )
+
+    rows = []
+    for i, r in enumerate(got["rows"]):
+        # `pid` is the grid's row identity contract (selection, detail, overlay all key on it).
+        # At line grain that identity is the order LINE id, which store_rows returns as _rid.
+        row = {k: v for k, v in r.items() if k != "_rid"}
+        row["pid"] = r["_rid"]
+        rows.append(row)
+
+    return {
+        "fields": table_fields(topic),
+        "rows": rows,
+        # THE honest window. `matched`/`total` are scope-wide queries; `shown` is this window.
+        # A caller must never recompute `matched` from len(rows).
+        "counts": {
+            "shown": len(rows),
+            "matched": got["row_count"],
+            "total": got["total_count"],
+            "windowed": True,
+        },
+        "aggregates": got["aggregates"],      # over the whole FILTERED scope, not the window
+        "storageKey": cfg["storage_key"],
+        "label": cfg["label"],
+        "window": got["window"],
+    }

platform/harness/tools.py

@@ -1,510 +1,510 @@
-"""harness/tools.py — the compounding TOOL REGISTRY (OM-4 spine, 2026-07-11).
-
-The formal tool surface the (small) model calls — the productization directive's "tools we keep
-compounding". Every tool wraps the SEMANTIC layer (harness/semantic.py): the model navigates by
-registry keys and recipe plans (model/skills/*.skill.yml — recipes and these tools version
-TOGETHER), never by SQL. Adding a connector/topic extends what the SAME tools reach — that is the
-compounding. Exported in OpenAI function-calling format (`openai_tools()`) — OpenRouter-compatible,
-so any cheap model with tool-calling drives the platform.
-
-Correctness posture (Part VI of the plan): whitelisted keys only; values parameterized downstream;
-every query result carries a result_id + drill note; artifact tools (save/compose/schedule/alert)
-are explicit and confirm-gated by recipe. Errors return a uniform envelope the model can read.
-"""
-import json
-import time
-import uuid
-from pathlib import Path
-
-import harness.semantic as SEM
-
-VIEWS_PATH = Path(__file__).resolve().parents[1] / "data" / "store" / "views.json"
-
-_RESULTS = {}          # result_id -> query result (session-scoped working memory for chart tools)
-_RESULTS_CAP = 40
-
-# The exhaustive chart vocabulary (2026-07-16): every Zelazny comparison form has a kind, so the
-# Analyst never lacks a shape. The model picks by the CHART PICKER guide (analyst.py) + the
-# charting skill recipes; the platform owns every pixel (app._render_analyst_artifact).
-CHART_KINDS = (
-    "line", "bar", "area", "scatter", "kpi", "map",              # the original six
-    "pie", "donut",                                              # part-to-whole (≤6 slices)
-    "stacked_bar", "grouped_bar", "ranked_bar", "stacked_pct",   # composition / rank forms
-    "combo", "yoy_bars",                                         # level+rate; this-vs-last-year
-    "waterfall", "pareto", "histogram", "heatmap", "treemap",    # bridge / concentration / distribution
-    "funnel", "bullet", "bubble", "sparkline",                   # stages / target / 3-measure / mini
-)
-
-# Per-kind param contract (beyond x): what else the spec must carry to be renderable.
-_KIND_NEEDS = {
-    "combo": ("y", "y2"), "bullet": ("y", "y2"), "bubble": ("y", "size"),
-    "heatmap": ("y", "value"), "histogram": (),                  # histogram bins x itself
-    "stacked_bar": ("y", "series"), "grouped_bar": ("y", "series"),
-    "stacked_pct": ("y", "series"),
-}
-_QUERY_KEYS = ("topic", "measures", "group_by", "grain", "date_from", "date_to",
-               "team_id", "filters", "sort", "limit", "exclude_services")
-
-
-def _remember(res):
-    rid = uuid.uuid4().hex[:10]
-    _RESULTS[rid] = res
-    while len(_RESULTS) > _RESULTS_CAP:
-        _RESULTS.pop(next(iter(_RESULTS)))
-    return rid
-
-
-def _ok(data):
-    return {"ok": True, "data": data}
-
-
-def _err(msg):
-    return {"ok": False, "error": str(msg)[:400]}
-
-
-# ------------------------------------------------------------------ schema tools
-
-def list_topics():
-    """The 'what data exists' tool."""
-    out = []
-    for k, t in SEM.topics().items():
-        out.append({"topic": k, "label": t.get("label"), "entity": t.get("entity"),
-                    "grain": t.get("grain"),
-                    "dims": list((t.get("store") or {}).get("dims") or {}),
-                    "metrics": [m for m, d in SEM.metrics().items() if d["topic"] == k]})
-    return out
-
-
-def describe_topic(topic):
-    """The schema-learning tool: scope, grain, dims, metrics w/ definitions, and ai_context."""
-    t = SEM.topics().get(topic)
-    if not t:
-        raise SEM.ModelError(f"unknown topic {topic!r} (use list_topics)")
-    mets = {k: {"label": m.get("label"), "description": m.get("description"),
-                "format": m.get("format"), "ai_context": m.get("ai_context")}
-            for k, m in SEM.metrics().items() if m["topic"] == topic}
-    return {"topic": topic, "label": t.get("label"), "scope": t.get("scope"),
-            "grain": t.get("grain"), "ai_context": t.get("ai_context"),
-            "dims": {k: v.get("label") for k, v in ((t.get("store") or {}).get("dims") or {}).items()},
-            "metrics": mets}
-
-
-# ------------------------------------------------------------------ query tools
-
-def run_semantic_query(topic, measures, group_by=None, grain=None, date_from=None, date_to=None,
-                       team_id=None, filters=None, sort=None, limit=1000, exclude_services=False):
-    # limit defaults HIGH (1000): transforms/charts operate on the FULL result while the model
-    # only ever sees rows[:100] — a small default silently truncated per-customer analytics
-    # (the BELLA FLORIST wrong-decliner incident, 2026-07-17).
-    res = SEM.store_query(topic, measures, group_by=group_by, grain=grain, date_from=date_from,
-                          date_to=date_to, team_id=team_id, filters=filters, sort=sort,
-                          limit=limit, exclude_services=exclude_services)
-    # Echo the full query onto the result: chart specs built from it carry the query, so a SAVED
-    # view is a re-runnable QUERY (the OM-3 viewer re-executes it live), never a stale snapshot.
-    res["query"] = {"topic": topic, "measures": list(measures or []), "group_by": group_by,
-                    "grain": grain, "date_from": date_from, "date_to": date_to, "team_id": team_id,
-                    "filters": filters, "sort": sort, "limit": limit,
-                    "exclude_services": exclude_services}
-    rid = _remember(res)
-    # The EFFECTIVE window, stated by the platform — the model must repeat this, never guess
-    # (a query without dates covers all recorded history; there is no hidden default window).
-    if date_from and date_to:
-        window = f"{date_from} to {date_to}"
-    elif date_from or date_to:
-        window = f"{'from ' + date_from if date_from else 'through ' + date_to}"
-    else:
-        window = "ALL recorded history (no date filter was applied)"
-    out = {"result_id": rid, "rows": res["rows"][:100], "row_count": res["row_count"],
-           "measures": res["measures"], "group_by": res["group_by"], "grain": res["grain"],
-           "window": window,
-           "note": "every number here is drillable; cite result_id when charting"}
-    if res["row_count"] >= (limit or 1000):        # surface every truncation (plan hard line)
-        out["warning"] = (f"TRUNCATED: the result hit limit={limit} — the full set is larger. "
-                          "Re-run with a higher limit (max 5000) BEFORE ranking, comparing or "
-                          "aggregating, or your answer will be computed on a partial set.")
-    return out
-
-
-def get_field_values(topic, dim, search=None):
-    return SEM.store_field_values(topic, dim, search=search)
-
-
-# ------------------------------------------------------------------ transform tool (governed)
-
-def transform_result(result_id, transforms):
-    """Apply governed ANALYTICS TRANSFORMS to a query result -> a NEW result_id to chart/table.
-    The chain is recorded on the derived result, so saved views replay query -> transforms live."""
-    res = _RESULTS.get(result_id)
-    if not res:
-        raise SEM.ModelError(f"unknown result_id {result_id!r} — run run_semantic_query first")
-    import harness.transforms as TR
-    rows, applied = TR.apply(res, transforms, run_query=_run_query)
-    new = {**res, "rows": rows, "row_count": len(rows),
-           "transforms": (res.get("transforms") or []) + applied}
-    rid = _remember(new)
-    return {"result_id": rid, "rows": rows[:100], "row_count": len(rows),
-            "columns": sorted(rows[0]) if rows else [],
-            "note": "derived result — chart THIS result_id to show the transform"}
-
-
-def _run_query(q):
-    return SEM.store_query(**{k: q.get(k) for k in _QUERY_KEYS if q.get(k) is not None})
-
-
-# ------------------------------------------------------------------ viz tools (emit OUR specs)
-
-def make_chart(result_id, kind, x, y=None, title=None, series=None, y2=None, size=None,
-               value=None, facet=None):
-    """Returns a validated CHART SPEC the platform renders with its own primitives (design system
-    enforced — the model never emits HTML/vega). Extra encodings per kind: combo/bullet need y2
-    (line/target), bubble needs size, heatmap needs value (the colour measure); facet (a dim
-    column) turns line|bar|area|scatter into small multiples."""
-    res = _RESULTS.get(result_id)
-    if not res:
-        raise SEM.ModelError(f"unknown result_id {result_id!r} — run run_semantic_query first")
-    if kind not in CHART_KINDS:
-        raise SEM.ModelError(f"kind must be one of {CHART_KINDS}")
-    cols = set(res["rows"][0]) if res["rows"] else set()
-    if y is None and kind != "histogram":
-        raise SEM.ModelError(f"kind={kind!r} needs y (only histogram bins x by itself)")
-    for ref, nm in ((x, "x"), (y, "y"), (series, "series"), (y2, "y2"), (size, "size"),
-                    (value, "value"), (facet, "facet")):
-        if ref and ref not in cols:
-            raise SEM.ModelError(f"{nm}={ref!r} not in result columns {sorted(cols)}")
-    given = {"y": y, "y2": y2, "size": size, "value": value, "series": series}
-    missing = [p for p in _KIND_NEEDS.get(kind, ()) if not given.get(p)]
-    if missing:
-        raise SEM.ModelError(f"kind={kind!r} also needs {missing} "
-                             f"(pick from result columns {sorted(cols)})")
-    if facet and kind not in ("line", "bar", "area", "scatter"):
-        raise SEM.ModelError("facet (small multiples) works with line|bar|area|scatter only")
-    if kind == "yoy_bars" and f"{y}_ly" not in cols:
-        raise SEM.ModelError(f"yoy_bars needs a {y}_ly column — run transform_result "
-                             "[{'op':'yoy'}] on the result first")
-    spec = {"kind": kind, "x": x, "y": y, "series": series,
-            "title": title or f"{y or x} by {x}", "result_id": result_id,
-            "query": res.get("query"), "rows": res["rows"]}
-    for k, v in (("y2", y2), ("size", size), ("value", value), ("facet", facet),
-                 ("transforms", res.get("transforms"))):
-        if v:
-            spec[k] = v
-    out = {"chart": spec}
-    if kind in ("pie", "donut") and len(res["rows"]) > 6:
-        out["note"] = (f"{len(res['rows'])} slices — the platform will show the top 5 plus an "
-                       "'Other' bucket; for a cleaner story run transform_result top_n first")
-    return out
-
-
-def make_table(result_id, columns=None, title=None):
-    """First-class TABLE artifact: the exact rows, house-formatted (sortable, totals row, the
-    drill IS the table). columns (optional) picks and orders a subset."""
-    res = _RESULTS.get(result_id)
-    if not res:
-        raise SEM.ModelError(f"unknown result_id {result_id!r} — run run_semantic_query first")
-    rows = res["rows"]
-    if columns:
-        cols = set(rows[0]) if rows else set()
-        bad = [c for c in columns if c not in cols]
-        if bad:
-            raise SEM.ModelError(f"columns {bad} not in result columns {sorted(cols)}")
-        rows = [{c: r.get(c) for c in columns} for r in rows]
-    return {"table": {"kind": "table", "title": title, "columns": columns,
-                      "result_id": result_id, "query": res.get("query"),
-                      "transforms": res.get("transforms"), "rows": rows}}
-
-
-def make_kpi_card(result_id, metric, compare_result_id=None):
-    res = _RESULTS.get(result_id)
-    if not res or not res["rows"]:
-        raise SEM.ModelError("result_id missing/empty — run a scalar run_semantic_query first")
-    val = res["rows"][0].get(metric)
-    if val is None:
-        raise SEM.ModelError(f"{metric!r} not in result")
-    card = {"kpi": {"metric": metric, "value": val, "result_id": result_id,
-                    "query": res.get("query")}}
-    if compare_result_id and _RESULTS.get(compare_result_id, {}).get("rows"):
-        prev = _RESULTS[compare_result_id]["rows"][0].get(metric)
-        if prev:
-            card["kpi"]["delta_pct"] = (val - prev) / abs(prev)
-            card["kpi"]["compare_result_id"] = compare_result_id
-            card["kpi"]["compare_query"] = _RESULTS[compare_result_id].get("query")
-    return card
-
-
-# ------------------------------------------------------------------ artifact tools (v0: local)
-
-def _load_views():
-    if VIEWS_PATH.exists():
-        return json.loads(VIEWS_PATH.read_text(encoding="utf-8"))
-    return {"views": {}, "dashboards": {}}
-
-
-def _save_views(d):
-    VIEWS_PATH.parent.mkdir(parents=True, exist_ok=True)
-    VIEWS_PATH.write_text(json.dumps(d, indent=1), encoding="utf-8")
-
-
-def save_view(name, chart):
-    """Persist a chart/KPI spec (from make_chart / make_kpi_card) as a named view. Specs persist
-    WITH their semantic query and WITHOUT rows — the OM-3 viewer re-executes the query live, so a
-    saved view is always current, never a snapshot."""
-    d = _load_views()
-    spec = chart.get("chart") or chart.get("kpi") or chart.get("table") or chart
-    spec = {k: v for k, v in spec.items() if k != "rows"}
-    if "kpi" in chart and not spec.get("kind"):
-        spec["kind"] = "kpi"
-    if "table" in chart and not spec.get("kind"):
-        spec["kind"] = "table"
-    if not spec.get("query"):
-        raise SEM.ModelError("spec carries no query — pass the exact object returned by "
-                             "make_chart / make_kpi_card (from a fresh run_semantic_query)")
-    d["views"][name] = {"chart": spec, "saved_at": time.strftime("%Y-%m-%d %H:%M")}
-    _save_views(d)
-    return {"saved": name, "views": list(d["views"])}
-
-
-def compose_dashboard(name, views):
-    """'Spawn a dashboard': compose saved views into a named dashboard spec (rendered at OM-3)."""
-    d = _load_views()
-    missing = [v for v in views if v not in d["views"]]
-    if missing:
-        raise SEM.ModelError(f"unknown views {missing} — save_view them first")
-    d["dashboards"][name] = {"views": views, "created_at": time.strftime("%Y-%m-%d %H:%M")}
-    _save_views(d)
-    return {"dashboard": name, "views": views}
-
-
-# ------------------------------------------------------------------ the GAP LOOP (rung 4)
-
-GAP_KINDS = ("dimension", "metric", "transform", "chart_kind", "data_source", "other")
-GAPS_KEY = "analyst_gaps"
-GAPS_CAP = 500
-
-
-def report_gap(kind, missing, question, workaround=None):
-    """Log a CAPABILITY GAP: the model determined (after checking the schema) that no registered
-    dim/metric/transform/kind can answer. The entry lands in telemetry AND the durable store —
-    the admin Gaps view aggregates them into the platform build backlog. This is how every
-    honest 'I can't' becomes the next dim, transform, or recipe."""
-    if kind not in GAP_KINDS:
-        raise SEM.ModelError(f"kind must be one of {GAP_KINDS}")
-    entry = {"ts": time.strftime("%Y-%m-%d %H:%M:%S"), "kind": kind,
-             "missing": str(missing)[:120], "question": str(question)[:300],
-             "workaround": (str(workaround)[:200] if workaround else None)}
-    import harness.telemetry as TEL
-    TEL.log("analyst_gap", **{("gap_kind" if k == "kind" else k): v for k, v in entry.items()})
-    try:                                    # durable copy — async, the chatlog write posture
-        import threading
-
-        import core.store as store
-        if store.available():
-            def _fn(data):
-                data = list(data or [])
-                data.append(entry)
-                return data[-GAPS_CAP:]
-            threading.Thread(target=lambda: store.update(GAPS_KEY, _fn),
-                             daemon=True, name="analyst-gap").start()
-    except Exception:
-        pass
-    return {"logged": True,
-            "note": "gap recorded for the platform backlog — now tell the user in ONE sentence "
-                    "what is missing and offer the nearest ask that IS answerable"}
-
-
-# ------------------------------------------------------------------ workspace tools (OM-3/P11)
-
-def list_workspace():
-    """Everything in the tenant workspace (uniform modular objects) + available templates."""
-    import harness.workspace as W
-    return {"objects": W.items(), "templates": W.templates()}
-
-
-def instantiate_template(filename, new_name=None):
-    """Stamp a tenant-agnostic template into this workspace as NEW objects (never overwrites)."""
-    import harness.workspace as W
-    return W.instantiate_template(filename, new_name)
-
-
-def update_view(name, changes):
-    """Patch an existing view (spec and/or query) — validated by re-execution before saving."""
-    import harness.views as V
-    return V.update_view(name, changes)
-
-
-def update_workbook(name, views=None, new_name=None):
-    """Recompose and/or rename a workbook (dashboard); renames follow into schedules."""
-    import harness.views as V
-    return V.update_dashboard(name, views_list=views, new_name=new_name)
-
-
-def delete_object(kind, name):
-    """Delete any workspace object. DESTRUCTIVE — the recipe requires explicit confirmation."""
-    import harness.workspace as W
-    W.delete(kind, name)
-    return {"deleted": f"{kind} · {name}"}
-
-
-# ------------------------------------------------------------------ registry + dispatch
-
-def _p(props, required):
-    return {"type": "object", "properties": props, "required": required}
-
-
-TOOLS = {
-    "list_topics": {"fn": lambda **kw: list_topics(),
-        "description": "List the datasets (topics) available: their metrics, dims, and grain. Start here.",
-        "parameters": _p({}, [])},
-    "describe_topic": {"fn": lambda **kw: describe_topic(kw["topic"]),
-        "description": "Full schema of one topic: scope rules, metric definitions, dims, and the business context you must respect.",
-        "parameters": _p({"topic": {"type": "string"}}, ["topic"])},
-    "get_field_values": {"fn": lambda **kw: get_field_values(kw["topic"], kw["dim"], kw.get("search")),
-        "description": "Resolve real filter values (ids+names) for a dim. ALWAYS use before filtering by a typed name.",
-        "parameters": _p({"topic": {"type": "string"}, "dim": {"type": "string"},
-                          "search": {"type": "string"}}, ["topic", "dim"])},
-    "run_semantic_query": {"fn": lambda **kw: run_semantic_query(**kw),
-        "description": "Run a governed query: registered measures over a topic, optional group_by dims / time grain / filters. The ONLY way to read data.",
-        "parameters": _p({"topic": {"type": "string"},
-                          "measures": {"type": "array", "items": {"type": "string"}},
-                          "group_by": {"type": "array", "items": {"type": "string"}},
-                          "grain": {"type": "string", "enum": ["month", "week", "day"]},
-                          "date_from": {"type": "string"}, "date_to": {"type": "string"},
-                          "team_id": {"type": "integer"},
-                          "filters": {"type": "object"},
-                          "sort": {"type": "string"}, "limit": {"type": "integer"},
-                          "exclude_services": {"type": "boolean"}},
-                         ["topic", "measures"])},
-    "transform_result": {"fn": lambda **kw: transform_result(kw["result_id"], kw["transforms"]),
-        "description": "Apply governed analytics transforms to a result -> a NEW result_id (a "
-                       "CHAINABLE list of {op, ...}). The Tableau-class analytics library — pick "
-                       "op names (full catalog + recipes in the analytics skill). Families: "
-                       "ordering/rank (sort, head, bottom_n, rank, rank_pct, ntile, top_n, "
-                       "add_total) · part-to-whole (share_of_total, cum_share) · running/moving "
-                       "(running_total/avg/max/min, running_count, moving_average/sum/median, "
-                       "rolling_std) · period-over-period (diff, pct_change, lag, lead, "
-                       "diff_from_first, index_to_100, percent_of_max, compare) · distribution/"
-                       "stats (bin, describe, zscore, outliers, winsorize, clip, normalize, "
-                       "correlate, weighted_average, safe_ratio, product) · business (abc_classify, "
-                       "concentration, contribution_to_change, rfm, funnel_rates) · modeling "
-                       "(trend_line, regression, cagr, growth_rate) · reference lines as columns "
-                       "(reference_line, reference_band, target_line, xmr_limits) · reshape (pivot, "
-                       "unpivot, filter_rows, dedupe, resample) · re-query windows (yoy, ytd, "
-                       "rolling, forecast). ADDITIVITY LAW: accumulating ops "
-                       "(running_total/share_of_total/cum_share/moving_sum/abc_classify/"
-                       "concentration) work on ADDITIVE measures (revenue/units/margin/orders); "
-                       "for a cumulative/trailing DISTINCT count (customers) or ratio use ytd/"
-                       "rolling (they re-query) — never running_total. NEVER compute any of these "
-                       "yourself; transform, then chart/table the new result_id.",
-        "parameters": _p({"result_id": {"type": "string"},
-                          "transforms": {"type": "array", "items": {"type": "object"}}},
-                         ["result_id", "transforms"])},
-    "make_chart": {"fn": lambda **kw: make_chart(**kw),
-        "description": "Turn a query result into a platform chart. kinds: line|bar|area|scatter|"
-                       "map|pie|donut|stacked_bar|grouped_bar|ranked_bar|stacked_pct|combo|"
-                       "yoy_bars|waterfall|pareto|histogram|heatmap|treemap|funnel|bullet|bubble|"
-                       "sparkline. x/y/series must be result columns. Extra encodings: combo "
-                       "(bars y + line y2, dual axis), bullet (value y vs target y2), bubble "
-                       "(scatter + size), heatmap (dims x,y + colour value), histogram (bins x, "
-                       "no y), facet (a dim column -> small multiples of line|bar|area|scatter). "
-                       "yoy_bars needs the yoy transform first. kind='map' plots customers "
-                       "geographically: x = the customer dim, dot size = y.",
-        "parameters": _p({"result_id": {"type": "string"}, "kind": {"type": "string", "enum": list(CHART_KINDS)},
-                          "x": {"type": "string"}, "y": {"type": "string"},
-                          "title": {"type": "string"}, "series": {"type": "string"},
-                          "y2": {"type": "string"}, "size": {"type": "string"},
-                          "value": {"type": "string"}, "facet": {"type": "string"}},
-                         ["result_id", "kind", "x"])},
-    "make_table": {"fn": lambda **kw: make_table(kw["result_id"], kw.get("columns"),
-                                                 kw.get("title")),
-        "description": "Turn a query result into a first-class TABLE artifact (house-formatted, "
-                       "totals row, drillable). Use when the user wants exact figures, many "
-                       "columns, or a list — not a shape. columns (optional) picks and orders.",
-        "parameters": _p({"result_id": {"type": "string"},
-                          "columns": {"type": "array", "items": {"type": "string"}},
-                          "title": {"type": "string"}}, ["result_id"])},
-    "make_kpi_card": {"fn": lambda **kw: make_kpi_card(**kw),
-        "description": "Turn a scalar query result into a KPI card; optional compare_result_id adds a YoY delta.",
-        "parameters": _p({"result_id": {"type": "string"}, "metric": {"type": "string"},
-                          "compare_result_id": {"type": "string"}}, ["result_id", "metric"])},
-    "report_gap": {"fn": lambda **kw: report_gap(kw["kind"], kw["missing"], kw["question"],
-                                                 kw.get("workaround")),
-        "description": "LAST RESORT — log a capability gap. Call ONLY after list_topics/"
-                       "describe_topic confirm that NO registered dimension, metric, transform "
-                       "or chart kind can answer the user's question (e.g. stock on hand, "
-                       "which has no topic). NOT a gap: YoY/decline/growth compares "
-                       "(transform_result yoy), rankings/top-N, shares, running totals, "
-                       "distributions — those are ANSWERABLE via transform_result. Then tell "
-                       "the user plainly what is missing and offer the nearest answerable ask. "
-                       "NEVER call this for something the tools support, and NEVER guess "
-                       "instead of calling it.",
-        "parameters": _p({"kind": {"type": "string", "enum": list(GAP_KINDS)},
-                          "missing": {"type": "string",
-                                      "description": "what does not exist, short (e.g. 'inventory/stock-on-hand topic')"},
-                          "question": {"type": "string",
-                                       "description": "the user's question, verbatim"},
-                          "workaround": {"type": "string",
-                                         "description": "the nearest answerable alternative you offered"}},
-                         ["kind", "missing", "question"])},
-    "save_view": {"fn": lambda **kw: save_view(kw["name"], kw["chart"]),
-        "description": "Save a chart as a named view (confirm with the user first).",
-        "parameters": _p({"name": {"type": "string"}, "chart": {"type": "object"}}, ["name", "chart"])},
-    "compose_dashboard": {"fn": lambda **kw: compose_dashboard(kw["name"], kw["views"]),
-        "description": "Compose saved views into a named dashboard (confirm with the user first).",
-        "parameters": _p({"name": {"type": "string"},
-                          "views": {"type": "array", "items": {"type": "string"}}}, ["name", "views"])},
-    "list_workspace": {"fn": lambda **kw: list_workspace(),
-        "description": "List the tenant workspace: every saved view/dashboard/alert/report "
-                       "(modular objects) plus available templates. Use when the user asks what "
-                       "exists, wants to reuse/manage artifacts, or before composing.",
-        "parameters": _p({}, [])},
-    "instantiate_template": {"fn": lambda **kw: instantiate_template(kw["filename"],
-                                                                     kw.get("new_name")),
-        "description": "Stamp a tenant-agnostic template (from list_workspace) into the "
-                       "workspace as NEW objects — never overwrites. Confirm with the user first.",
-        "parameters": _p({"filename": {"type": "string"}, "new_name": {"type": "string"}},
-                         ["filename"])},
-    "update_view": {"fn": lambda **kw: update_view(kw["name"], kw.get("changes")),
-        "description": "UPDATE an existing saved view: patch spec keys (title/kind/x/y/series) "
-                       "and/or 'query' subkeys (measures, group_by, grain, date_from, date_to, "
-                       "team_id, filters, sort, limit; null REMOVES a key). The patched query is "
-                       "re-executed before saving — invalid updates are rejected. Confirm first.",
-        "parameters": _p({"name": {"type": "string"}, "changes": {"type": "object"}},
-                         ["name", "changes"])},
-    "update_workbook": {"fn": lambda **kw: update_workbook(kw["name"], kw.get("views"),
-                                                           kw.get("new_name")),
-        "description": "UPDATE a workbook (dashboard): recompose its views (list = new display "
-                       "order; add/remove by including/omitting) and/or rename it. Confirm first.",
-        "parameters": _p({"name": {"type": "string"},
-                          "views": {"type": "array", "items": {"type": "string"}},
-                          "new_name": {"type": "string"}}, ["name"])},
-    "delete_object": {"fn": lambda **kw: delete_object(kw["kind"], kw["name"]),
-        "description": "DELETE a workspace object (view|dashboard|alert|report). DESTRUCTIVE — "
-                       "requires the user's explicit confirmation in this conversation first.",
-        "parameters": _p({"kind": {"type": "string",
-                                   "enum": ["view", "dashboard", "alert", "report"]},
-                          "name": {"type": "string"}}, ["kind", "name"])},
-}
-
-
-def openai_tools():
-    """The registry in OpenAI function-calling format (OpenRouter-compatible)."""
-    return [{"type": "function",
-             "function": {"name": k, "description": v["description"], "parameters": v["parameters"]}}
-            for k, v in TOOLS.items()]
-
-
-def dispatch(name, arguments):
-    """Uniform tool execution for the Analyst loop: JSON-safe result or a readable error the
-    model can act on. Never raises."""
-    t = TOOLS.get(name)
-    if not t:
-        return _err(f"unknown tool {name!r} (tools: {list(TOOLS)})")
-    try:
-        args = json.loads(arguments) if isinstance(arguments, str) else dict(arguments or {})
-        missing = [r for r in t["parameters"].get("required", []) if r not in args]
-        if missing:
-            return _err(f"missing required arguments: {missing}")
-        return _ok(t["fn"](**args))
-    except SEM.ModelError as e:
-        return _err(e)
-    except Exception as e:
-        return _err(f"{type(e).__name__}: {e}")
+"""harness/tools.py — the compounding TOOL REGISTRY (OM-4 spine, 2026-07-11).
+
+The formal tool surface the (small) model calls — the productization directive's "tools we keep
+compounding". Every tool wraps the SEMANTIC layer (harness/semantic.py): the model navigates by
+registry keys and recipe plans (model/skills/*.skill.yml — recipes and these tools version
+TOGETHER), never by SQL. Adding a connector/topic extends what the SAME tools reach — that is the
+compounding. Exported in OpenAI function-calling format (`openai_tools()`) — OpenRouter-compatible,
+so any cheap model with tool-calling drives the platform.
+
+Correctness posture (Part VI of the plan): whitelisted keys only; values parameterized downstream;
+every query result carries a result_id + drill note; artifact tools (save/compose/schedule/alert)
+are explicit and confirm-gated by recipe. Errors return a uniform envelope the model can read.
+"""
+import json
+import time
+import uuid
+from pathlib import Path
+
+import harness.semantic as SEM
+
+VIEWS_PATH = Path(__file__).resolve().parents[1] / "data" / "store" / "views.json"
+
+_RESULTS = {}          # result_id -> query result (session-scoped working memory for chart tools)
+_RESULTS_CAP = 40
+
+# The exhaustive chart vocabulary (2026-07-16): every Zelazny comparison form has a kind, so the
+# Analyst never lacks a shape. The model picks by the CHART PICKER guide (analyst.py) + the
+# charting skill recipes; the platform owns every pixel (app._render_analyst_artifact).
+CHART_KINDS = (
+    "line", "bar", "area", "scatter", "kpi", "map",              # the original six
+    "pie", "donut",                                              # part-to-whole (≤6 slices)
+    "stacked_bar", "grouped_bar", "ranked_bar", "stacked_pct",   # composition / rank forms
+    "combo", "yoy_bars",                                         # level+rate; this-vs-last-year
+    "waterfall", "pareto", "histogram", "heatmap", "treemap",    # bridge / concentration / distribution
+    "funnel", "bullet", "bubble", "sparkline",                   # stages / target / 3-measure / mini
+)
+
+# Per-kind param contract (beyond x): what else the spec must carry to be renderable.
+_KIND_NEEDS = {
+    "combo": ("y", "y2"), "bullet": ("y", "y2"), "bubble": ("y", "size"),
+    "heatmap": ("y", "value"), "histogram": (),                  # histogram bins x itself
+    "stacked_bar": ("y", "series"), "grouped_bar": ("y", "series"),
+    "stacked_pct": ("y", "series"),
+}
+_QUERY_KEYS = ("topic", "measures", "group_by", "grain", "date_from", "date_to",
+               "team_id", "filters", "sort", "limit", "exclude_services")
+
+
+def _remember(res):
+    rid = uuid.uuid4().hex[:10]
+    _RESULTS[rid] = res
+    while len(_RESULTS) > _RESULTS_CAP:
+        _RESULTS.pop(next(iter(_RESULTS)))
+    return rid
+
+
+def _ok(data):
+    return {"ok": True, "data": data}
+
+
+def _err(msg):
+    return {"ok": False, "error": str(msg)[:400]}
+
+
+# ------------------------------------------------------------------ schema tools
+
+def list_topics():
+    """The 'what data exists' tool."""
+    out = []
+    for k, t in SEM.topics().items():
+        out.append({"topic": k, "label": t.get("label"), "entity": t.get("entity"),
+                    "grain": t.get("grain"),
+                    "dims": list((t.get("store") or {}).get("dims") or {}),
+                    "metrics": [m for m, d in SEM.metrics().items() if d["topic"] == k]})
+    return out
+
+
+def describe_topic(topic):
+    """The schema-learning tool: scope, grain, dims, metrics w/ definitions, and ai_context."""
+    t = SEM.topics().get(topic)
+    if not t:
+        raise SEM.ModelError(f"unknown topic {topic!r} (use list_topics)")
+    mets = {k: {"label": m.get("label"), "description": m.get("description"),
+                "format": m.get("format"), "ai_context": m.get("ai_context")}
+            for k, m in SEM.metrics().items() if m["topic"] == topic}
+    return {"topic": topic, "label": t.get("label"), "scope": t.get("scope"),
+            "grain": t.get("grain"), "ai_context": t.get("ai_context"),
+            "dims": {k: v.get("label") for k, v in ((t.get("store") or {}).get("dims") or {}).items()},
+            "metrics": mets}
+
+
+# ------------------------------------------------------------------ query tools
+
+def run_semantic_query(topic, measures, group_by=None, grain=None, date_from=None, date_to=None,
+                       team_id=None, filters=None, sort=None, limit=1000, exclude_services=False):
+    # limit defaults HIGH (1000): transforms/charts operate on the FULL result while the model
+    # only ever sees rows[:100] — a small default silently truncated per-customer analytics
+    # (the BELLA FLORIST wrong-decliner incident, 2026-07-17).
+    res = SEM.store_query(topic, measures, group_by=group_by, grain=grain, date_from=date_from,
+                          date_to=date_to, team_id=team_id, filters=filters, sort=sort,
+                          limit=limit, exclude_services=exclude_services)
+    # Echo the full query onto the result: chart specs built from it carry the query, so a SAVED
+    # view is a re-runnable QUERY (the OM-3 viewer re-executes it live), never a stale snapshot.
+    res["query"] = {"topic": topic, "measures": list(measures or []), "group_by": group_by,
+                    "grain": grain, "date_from": date_from, "date_to": date_to, "team_id": team_id,
+                    "filters": filters, "sort": sort, "limit": limit,
+                    "exclude_services": exclude_services}
+    rid = _remember(res)
+    # The EFFECTIVE window, stated by the platform — the model must repeat this, never guess
+    # (a query without dates covers all recorded history; there is no hidden default window).
+    if date_from and date_to:
+        window = f"{date_from} to {date_to}"
+    elif date_from or date_to:
+        window = f"{'from ' + date_from if date_from else 'through ' + date_to}"
+    else:
+        window = "ALL recorded history (no date filter was applied)"
+    out = {"result_id": rid, "rows": res["rows"][:100], "row_count": res["row_count"],
+           "measures": res["measures"], "group_by": res["group_by"], "grain": res["grain"],
+           "window": window,
+           "note": "every number here is drillable; cite result_id when charting"}
+    if res["row_count"] >= (limit or 1000):        # surface every truncation (plan hard line)
+        out["warning"] = (f"TRUNCATED: the result hit limit={limit} — the full set is larger. "
+                          "Re-run with a higher limit (max 5000) BEFORE ranking, comparing or "
+                          "aggregating, or your answer will be computed on a partial set.")
+    return out
+
+
+def get_field_values(topic, dim, search=None):
+    return SEM.store_field_values(topic, dim, search=search)
+
+
+# ------------------------------------------------------------------ transform tool (governed)
+
+def transform_result(result_id, transforms):
+    """Apply governed ANALYTICS TRANSFORMS to a query result -> a NEW result_id to chart/table.
+    The chain is recorded on the derived result, so saved views replay query -> transforms live."""
+    res = _RESULTS.get(result_id)
+    if not res:
+        raise SEM.ModelError(f"unknown result_id {result_id!r} — run run_semantic_query first")
+    import harness.transforms as TR
+    rows, applied = TR.apply(res, transforms, run_query=_run_query)
+    new = {**res, "rows": rows, "row_count": len(rows),
+           "transforms": (res.get("transforms") or []) + applied}
+    rid = _remember(new)
+    return {"result_id": rid, "rows": rows[:100], "row_count": len(rows),
+            "columns": sorted(rows[0]) if rows else [],
+            "note": "derived result — chart THIS result_id to show the transform"}
+
+
+def _run_query(q):
+    return SEM.store_query(**{k: q.get(k) for k in _QUERY_KEYS if q.get(k) is not None})
+
+
+# ------------------------------------------------------------------ viz tools (emit OUR specs)
+
+def make_chart(result_id, kind, x, y=None, title=None, series=None, y2=None, size=None,
+               value=None, facet=None):
+    """Returns a validated CHART SPEC the platform renders with its own primitives (design system
+    enforced — the model never emits HTML/vega). Extra encodings per kind: combo/bullet need y2
+    (line/target), bubble needs size, heatmap needs value (the colour measure); facet (a dim
+    column) turns line|bar|area|scatter into small multiples."""
+    res = _RESULTS.get(result_id)
+    if not res:
+        raise SEM.ModelError(f"unknown result_id {result_id!r} — run run_semantic_query first")
+    if kind not in CHART_KINDS:
+        raise SEM.ModelError(f"kind must be one of {CHART_KINDS}")
+    cols = set(res["rows"][0]) if res["rows"] else set()
+    if y is None and kind != "histogram":
+        raise SEM.ModelError(f"kind={kind!r} needs y (only histogram bins x by itself)")
+    for ref, nm in ((x, "x"), (y, "y"), (series, "series"), (y2, "y2"), (size, "size"),
+                    (value, "value"), (facet, "facet")):
+        if ref and ref not in cols:
+            raise SEM.ModelError(f"{nm}={ref!r} not in result columns {sorted(cols)}")
+    given = {"y": y, "y2": y2, "size": size, "value": value, "series": series}
+    missing = [p for p in _KIND_NEEDS.get(kind, ()) if not given.get(p)]
+    if missing:
+        raise SEM.ModelError(f"kind={kind!r} also needs {missing} "
+                             f"(pick from result columns {sorted(cols)})")
+    if facet and kind not in ("line", "bar", "area", "scatter"):
+        raise SEM.ModelError("facet (small multiples) works with line|bar|area|scatter only")
+    if kind == "yoy_bars" and f"{y}_ly" not in cols:
+        raise SEM.ModelError(f"yoy_bars needs a {y}_ly column — run transform_result "
+                             "[{'op':'yoy'}] on the result first")
+    spec = {"kind": kind, "x": x, "y": y, "series": series,
+            "title": title or f"{y or x} by {x}", "result_id": result_id,
+            "query": res.get("query"), "rows": res["rows"]}
+    for k, v in (("y2", y2), ("size", size), ("value", value), ("facet", facet),
+                 ("transforms", res.get("transforms"))):
+        if v:
+            spec[k] = v
+    out = {"chart": spec}
+    if kind in ("pie", "donut") and len(res["rows"]) > 6:
+        out["note"] = (f"{len(res['rows'])} slices — the platform will show the top 5 plus an "
+                       "'Other' bucket; for a cleaner story run transform_result top_n first")
+    return out
+
+
+def make_table(result_id, columns=None, title=None):
+    """First-class TABLE artifact: the exact rows, house-formatted (sortable, totals row, the
+    drill IS the table). columns (optional) picks and orders a subset."""
+    res = _RESULTS.get(result_id)
+    if not res:
+        raise SEM.ModelError(f"unknown result_id {result_id!r} — run run_semantic_query first")
+    rows = res["rows"]
+    if columns:
+        cols = set(rows[0]) if rows else set()
+        bad = [c for c in columns if c not in cols]
+        if bad:
+            raise SEM.ModelError(f"columns {bad} not in result columns {sorted(cols)}")
+        rows = [{c: r.get(c) for c in columns} for r in rows]
+    return {"table": {"kind": "table", "title": title, "columns": columns,
+                      "result_id": result_id, "query": res.get("query"),
+                      "transforms": res.get("transforms"), "rows": rows}}
+
+
+def make_kpi_card(result_id, metric, compare_result_id=None):
+    res = _RESULTS.get(result_id)
+    if not res or not res["rows"]:
+        raise SEM.ModelError("result_id missing/empty — run a scalar run_semantic_query first")
+    val = res["rows"][0].get(metric)
+    if val is None:
+        raise SEM.ModelError(f"{metric!r} not in result")
+    card = {"kpi": {"metric": metric, "value": val, "result_id": result_id,
+                    "query": res.get("query")}}
+    if compare_result_id and _RESULTS.get(compare_result_id, {}).get("rows"):
+        prev = _RESULTS[compare_result_id]["rows"][0].get(metric)
+        if prev:
+            card["kpi"]["delta_pct"] = (val - prev) / abs(prev)
+            card["kpi"]["compare_result_id"] = compare_result_id
+            card["kpi"]["compare_query"] = _RESULTS[compare_result_id].get("query")
+    return card
+
+
+# ------------------------------------------------------------------ artifact tools (v0: local)
+
+def _load_views():
+    if VIEWS_PATH.exists():
+        return json.loads(VIEWS_PATH.read_text(encoding="utf-8"))
+    return {"views": {}, "dashboards": {}}
+
+
+def _save_views(d):
+    VIEWS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    VIEWS_PATH.write_text(json.dumps(d, indent=1), encoding="utf-8")
+
+
+def save_view(name, chart):
+    """Persist a chart/KPI spec (from make_chart / make_kpi_card) as a named view. Specs persist
+    WITH their semantic query and WITHOUT rows — the OM-3 viewer re-executes the query live, so a
+    saved view is always current, never a snapshot."""
+    d = _load_views()
+    spec = chart.get("chart") or chart.get("kpi") or chart.get("table") or chart
+    spec = {k: v for k, v in spec.items() if k != "rows"}
+    if "kpi" in chart and not spec.get("kind"):
+        spec["kind"] = "kpi"
+    if "table" in chart and not spec.get("kind"):
+        spec["kind"] = "table"
+    if not spec.get("query"):
+        raise SEM.ModelError("spec carries no query — pass the exact object returned by "
+                             "make_chart / make_kpi_card (from a fresh run_semantic_query)")
+    d["views"][name] = {"chart": spec, "saved_at": time.strftime("%Y-%m-%d %H:%M")}
+    _save_views(d)
+    return {"saved": name, "views": list(d["views"])}
+
+
+def compose_dashboard(name, views):
+    """'Spawn a dashboard': compose saved views into a named dashboard spec (rendered at OM-3)."""
+    d = _load_views()
+    missing = [v for v in views if v not in d["views"]]
+    if missing:
+        raise SEM.ModelError(f"unknown views {missing} — save_view them first")
+    d["dashboards"][name] = {"views": views, "created_at": time.strftime("%Y-%m-%d %H:%M")}
+    _save_views(d)
+    return {"dashboard": name, "views": views}
+
+
+# ------------------------------------------------------------------ the GAP LOOP (rung 4)
+
+GAP_KINDS = ("dimension", "metric", "transform", "chart_kind", "data_source", "other")
+GAPS_KEY = "analyst_gaps"
+GAPS_CAP = 500
+
+
+def report_gap(kind, missing, question, workaround=None):
+    """Log a CAPABILITY GAP: the model determined (after checking the schema) that no registered
+    dim/metric/transform/kind can answer. The entry lands in telemetry AND the durable store —
+    the admin Gaps view aggregates them into the platform build backlog. This is how every
+    honest 'I can't' becomes the next dim, transform, or recipe."""
+    if kind not in GAP_KINDS:
+        raise SEM.ModelError(f"kind must be one of {GAP_KINDS}")
+    entry = {"ts": time.strftime("%Y-%m-%d %H:%M:%S"), "kind": kind,
+             "missing": str(missing)[:120], "question": str(question)[:300],
+             "workaround": (str(workaround)[:200] if workaround else None)}
+    import harness.telemetry as TEL
+    TEL.log("analyst_gap", **{("gap_kind" if k == "kind" else k): v for k, v in entry.items()})
+    try:                                    # durable copy — async, the chatlog write posture
+        import threading
+
+        import core.store as store
+        if store.available():
+            def _fn(data):
+                data = list(data or [])
+                data.append(entry)
+                return data[-GAPS_CAP:]
+            threading.Thread(target=lambda: store.update(GAPS_KEY, _fn),
+                             daemon=True, name="analyst-gap").start()
+    except Exception:
+        pass
+    return {"logged": True,
+            "note": "gap recorded for the platform backlog — now tell the user in ONE sentence "
+                    "what is missing and offer the nearest ask that IS answerable"}
+
+
+# ------------------------------------------------------------------ workspace tools (OM-3/P11)
+
+def list_workspace():
+    """Everything in the tenant workspace (uniform modular objects) + available templates."""
+    import harness.workspace as W
+    return {"objects": W.items(), "templates": W.templates()}
+
+
+def instantiate_template(filename, new_name=None):
+    """Stamp a tenant-agnostic template into this workspace as NEW objects (never overwrites)."""
+    import harness.workspace as W
+    return W.instantiate_template(filename, new_name)
+
+
+def update_view(name, changes):
+    """Patch an existing view (spec and/or query) — validated by re-execution before saving."""
+    import harness.views as V
+    return V.update_view(name, changes)
+
+
+def update_workbook(name, views=None, new_name=None):
+    """Recompose and/or rename a workbook (dashboard); renames follow into schedules."""
+    import harness.views as V
+    return V.update_dashboard(name, views_list=views, new_name=new_name)
+
+
+def delete_object(kind, name):
+    """Delete any workspace object. DESTRUCTIVE — the recipe requires explicit confirmation."""
+    import harness.workspace as W
+    W.delete(kind, name)
+    return {"deleted": f"{kind} · {name}"}
+
+
+# ------------------------------------------------------------------ registry + dispatch
+
+def _p(props, required):
+    return {"type": "object", "properties": props, "required": required}
+
+
+TOOLS = {
+    "list_topics": {"fn": lambda **kw: list_topics(),
+        "description": "List the datasets (topics) available: their metrics, dims, and grain. Start here.",
+        "parameters": _p({}, [])},
+    "describe_topic": {"fn": lambda **kw: describe_topic(kw["topic"]),
+        "description": "Full schema of one topic: scope rules, metric definitions, dims, and the business context you must respect.",
+        "parameters": _p({"topic": {"type": "string"}}, ["topic"])},
+    "get_field_values": {"fn": lambda **kw: get_field_values(kw["topic"], kw["dim"], kw.get("search")),
+        "description": "Resolve real filter values (ids+names) for a dim. ALWAYS use before filtering by a typed name.",
+        "parameters": _p({"topic": {"type": "string"}, "dim": {"type": "string"},
+                          "search": {"type": "string"}}, ["topic", "dim"])},
+    "run_semantic_query": {"fn": lambda **kw: run_semantic_query(**kw),
+        "description": "Run a governed query: registered measures over a topic, optional group_by dims / time grain / filters. The ONLY way to read data.",
+        "parameters": _p({"topic": {"type": "string"},
+                          "measures": {"type": "array", "items": {"type": "string"}},
+                          "group_by": {"type": "array", "items": {"type": "string"}},
+                          "grain": {"type": "string", "enum": ["month", "week", "day"]},
+                          "date_from": {"type": "string"}, "date_to": {"type": "string"},
+                          "team_id": {"type": "integer"},
+                          "filters": {"type": "object"},
+                          "sort": {"type": "string"}, "limit": {"type": "integer"},
+                          "exclude_services": {"type": "boolean"}},
+                         ["topic", "measures"])},
+    "transform_result": {"fn": lambda **kw: transform_result(kw["result_id"], kw["transforms"]),
+        "description": "Apply governed analytics transforms to a result -> a NEW result_id (a "
+                       "CHAINABLE list of {op, ...}). The Tableau-class analytics library — pick "
+                       "op names (full catalog + recipes in the analytics skill). Families: "
+                       "ordering/rank (sort, head, bottom_n, rank, rank_pct, ntile, top_n, "
+                       "add_total) · part-to-whole (share_of_total, cum_share) · running/moving "
+                       "(running_total/avg/max/min, running_count, moving_average/sum/median, "
+                       "rolling_std) · period-over-period (diff, pct_change, lag, lead, "
+                       "diff_from_first, index_to_100, percent_of_max, compare) · distribution/"
+                       "stats (bin, describe, zscore, outliers, winsorize, clip, normalize, "
+                       "correlate, weighted_average, safe_ratio, product) · business (abc_classify, "
+                       "concentration, contribution_to_change, rfm, funnel_rates) · modeling "
+                       "(trend_line, regression, cagr, growth_rate) · reference lines as columns "
+                       "(reference_line, reference_band, target_line, xmr_limits) · reshape (pivot, "
+                       "unpivot, filter_rows, dedupe, resample) · re-query windows (yoy, ytd, "
+                       "rolling, forecast). ADDITIVITY LAW: accumulating ops "
+                       "(running_total/share_of_total/cum_share/moving_sum/abc_classify/"
+                       "concentration) work on ADDITIVE measures (revenue/units/margin/orders); "
+                       "for a cumulative/trailing DISTINCT count (customers) or ratio use ytd/"
+                       "rolling (they re-query) — never running_total. NEVER compute any of these "
+                       "yourself; transform, then chart/table the new result_id.",
+        "parameters": _p({"result_id": {"type": "string"},
+                          "transforms": {"type": "array", "items": {"type": "object"}}},
+                         ["result_id", "transforms"])},
+    "make_chart": {"fn": lambda **kw: make_chart(**kw),
+        "description": "Turn a query result into a platform chart. kinds: line|bar|area|scatter|"
+                       "map|pie|donut|stacked_bar|grouped_bar|ranked_bar|stacked_pct|combo|"
+                       "yoy_bars|waterfall|pareto|histogram|heatmap|treemap|funnel|bullet|bubble|"
+                       "sparkline. x/y/series must be result columns. Extra encodings: combo "
+                       "(bars y + line y2, dual axis), bullet (value y vs target y2), bubble "
+                       "(scatter + size), heatmap (dims x,y + colour value), histogram (bins x, "
+                       "no y), facet (a dim column -> small multiples of line|bar|area|scatter). "
+                       "yoy_bars needs the yoy transform first. kind='map' plots customers "
+                       "geographically: x = the customer dim, dot size = y.",
+        "parameters": _p({"result_id": {"type": "string"}, "kind": {"type": "string", "enum": list(CHART_KINDS)},
+                          "x": {"type": "string"}, "y": {"type": "string"},
+                          "title": {"type": "string"}, "series": {"type": "string"},
+                          "y2": {"type": "string"}, "size": {"type": "string"},
+                          "value": {"type": "string"}, "facet": {"type": "string"}},
+                         ["result_id", "kind", "x"])},
+    "make_table": {"fn": lambda **kw: make_table(kw["result_id"], kw.get("columns"),
+                                                 kw.get("title")),
+        "description": "Turn a query result into a first-class TABLE artifact (house-formatted, "
+                       "totals row, drillable). Use when the user wants exact figures, many "
+                       "columns, or a list — not a shape. columns (optional) picks and orders.",
+        "parameters": _p({"result_id": {"type": "string"},
+                          "columns": {"type": "array", "items": {"type": "string"}},
+                          "title": {"type": "string"}}, ["result_id"])},
+    "make_kpi_card": {"fn": lambda **kw: make_kpi_card(**kw),
+        "description": "Turn a scalar query result into a KPI card; optional compare_result_id adds a YoY delta.",
+        "parameters": _p({"result_id": {"type": "string"}, "metric": {"type": "string"},
+                          "compare_result_id": {"type": "string"}}, ["result_id", "metric"])},
+    "report_gap": {"fn": lambda **kw: report_gap(kw["kind"], kw["missing"], kw["question"],
+                                                 kw.get("workaround")),
+        "description": "LAST RESORT — log a capability gap. Call ONLY after list_topics/"
+                       "describe_topic confirm that NO registered dimension, metric, transform "
+                       "or chart kind can answer the user's question (e.g. stock on hand, "
+                       "which has no topic). NOT a gap: YoY/decline/growth compares "
+                       "(transform_result yoy), rankings/top-N, shares, running totals, "
+                       "distributions — those are ANSWERABLE via transform_result. Then tell "
+                       "the user plainly what is missing and offer the nearest answerable ask. "
+                       "NEVER call this for something the tools support, and NEVER guess "
+                       "instead of calling it.",
+        "parameters": _p({"kind": {"type": "string", "enum": list(GAP_KINDS)},
+                          "missing": {"type": "string",
+                                      "description": "what does not exist, short (e.g. 'inventory/stock-on-hand topic')"},
+                          "question": {"type": "string",
+                                       "description": "the user's question, verbatim"},
+                          "workaround": {"type": "string",
+                                         "description": "the nearest answerable alternative you offered"}},
+                         ["kind", "missing", "question"])},
+    "save_view": {"fn": lambda **kw: save_view(kw["name"], kw["chart"]),
+        "description": "Save a chart as a named view (confirm with the user first).",
+        "parameters": _p({"name": {"type": "string"}, "chart": {"type": "object"}}, ["name", "chart"])},
+    "compose_dashboard": {"fn": lambda **kw: compose_dashboard(kw["name"], kw["views"]),
+        "description": "Compose saved views into a named dashboard (confirm with the user first).",
+        "parameters": _p({"name": {"type": "string"},
+                          "views": {"type": "array", "items": {"type": "string"}}}, ["name", "views"])},
+    "list_workspace": {"fn": lambda **kw: list_workspace(),
+        "description": "List the tenant workspace: every saved view/dashboard/alert/report "
+                       "(modular objects) plus available templates. Use when the user asks what "
+                       "exists, wants to reuse/manage artifacts, or before composing.",
+        "parameters": _p({}, [])},
+    "instantiate_template": {"fn": lambda **kw: instantiate_template(kw["filename"],
+                                                                     kw.get("new_name")),
+        "description": "Stamp a tenant-agnostic template (from list_workspace) into the "
+                       "workspace as NEW objects — never overwrites. Confirm with the user first.",
+        "parameters": _p({"filename": {"type": "string"}, "new_name": {"type": "string"}},
+                         ["filename"])},
+    "update_view": {"fn": lambda **kw: update_view(kw["name"], kw.get("changes")),
+        "description": "UPDATE an existing saved view: patch spec keys (title/kind/x/y/series) "
+                       "and/or 'query' subkeys (measures, group_by, grain, date_from, date_to, "
+                       "team_id, filters, sort, limit; null REMOVES a key). The patched query is "
+                       "re-executed before saving — invalid updates are rejected. Confirm first.",
+        "parameters": _p({"name": {"type": "string"}, "changes": {"type": "object"}},
+                         ["name", "changes"])},
+    "update_workbook": {"fn": lambda **kw: update_workbook(kw["name"], kw.get("views"),
+                                                           kw.get("new_name")),
+        "description": "UPDATE a workbook (dashboard): recompose its views (list = new display "
+                       "order; add/remove by including/omitting) and/or rename it. Confirm first.",
+        "parameters": _p({"name": {"type": "string"},
+                          "views": {"type": "array", "items": {"type": "string"}},
+                          "new_name": {"type": "string"}}, ["name"])},
+    "delete_object": {"fn": lambda **kw: delete_object(kw["kind"], kw["name"]),
+        "description": "DELETE a workspace object (view|dashboard|alert|report). DESTRUCTIVE — "
+                       "requires the user's explicit confirmation in this conversation first.",
+        "parameters": _p({"kind": {"type": "string",
+                                   "enum": ["view", "dashboard", "alert", "report"]},
+                          "name": {"type": "string"}}, ["kind", "name"])},
+}
+
+
+def openai_tools():
+    """The registry in OpenAI function-calling format (OpenRouter-compatible)."""
+    return [{"type": "function",
+             "function": {"name": k, "description": v["description"], "parameters": v["parameters"]}}
+            for k, v in TOOLS.items()]
+
+
+def dispatch(name, arguments):
+    """Uniform tool execution for the Analyst loop: JSON-safe result or a readable error the
+    model can act on. Never raises."""
+    t = TOOLS.get(name)
+    if not t:
+        return _err(f"unknown tool {name!r} (tools: {list(TOOLS)})")
+    try:
+        args = json.loads(arguments) if isinstance(arguments, str) else dict(arguments or {})
+        missing = [r for r in t["parameters"].get("required", []) if r not in args]
+        if missing:
+            return _err(f"missing required arguments: {missing}")
+        return _ok(t["fn"](**args))
+    except SEM.ModelError as e:
+        return _err(e)
+    except Exception as e:
+        return _err(f"{type(e).__name__}: {e}")

platform/harness/windows.py

@@ -1,390 +1,390 @@
-"""harness/windows.py — the DATE WINDOW vocabulary (CG-7, owner item 2, 2026-07-26).
-
-A filter condition on a measure reads:
-
-    Where [Sales] [in the last 90 days] [>] [5,000]
-
-The middle bracket is this module. It turns a window SPEC — a small JSON object a saved view can
-persist — into a concrete `(date_from, date_to)` pair of ISO dates.
-
-WHY IT IS ITS OWN MODULE, AND WHY IT TAKES `today` AS AN ARGUMENT
------------------------------------------------------------------------------------------------
-Two engines must agree on what "this quarter" means: this one (which compiles the SQL) and
-`customer-grid/windows.ts` (which renders the label the user reads and the bounds the client
-engine would use). If they disagree by one day, the grid shows a number the label denies, and
-nothing errors. `aios-web/verify_windows.py` holds them in lock-step over a fixed set of probe
-dates, exactly as verify_filter_engine.py does for the filter tree.
-
-`today` is a PARAMETER, never `date.today()` read inside. Three reasons, all learned:
-  - a gate cannot compare two engines on "now" — the two runs are milliseconds apart and land on
-    different sides of midnight roughly once every few thousand runs, which is the worst kind of
-    flake because it looks like a real divergence
-  - a window resolved during a request must not shift between the count query and the row query
-  - the tenant's day boundary is the tenant's, not the server's
-
-DESIGN NOTES THAT ARE EASY TO GET WRONG
------------------------------------------------------------------------------------------------
-  - Bounds are INCLUSIVE at both ends and are DATES, not timestamps. `store_query` casts both
-    sides to TIMESTAMP and appends 23:59:59 to the upper bound, so a bare date is correct there;
-    the client compares the 10-char ISO prefix, so a bare date is correct there too.
-  - "Last N days" INCLUDES today. Airtable's "the past week" means the last 7 days up to and
-    including now, not the 7 days before yesterday. Off-by-one here silently drops today's
-    orders from every "recent" filter — invisible until someone asks why a sale they just
-    entered is missing.
-  - Week starts MONDAY (ISO 8601). Stated rather than defaulted: Python's weekday() is
-    Monday=0 and JavaScript's getDay() is Sunday=0, so the two engines disagree unless one of
-    them is explicitly corrected. That correction is the single most likely divergence in this
-    file, and the gate probes a Sunday and a Monday for exactly that reason.
-  - A `custom` window with only one bound is legal and means open-ended on the other side.
-  - An UNRESOLVABLE window returns None rather than a default. A window that quietly becomes
-    "all time" would widen a filter while still reporting an authoritative count.
-"""
-import datetime as _dt
-
-#: Every window kind the UI may offer. Mirrors WINDOW_KINDS in customer-grid/windows.ts;
-#: verify_windows.py asserts the two lists are identical, because a kind the client can emit and
-#: the server cannot resolve is a filter that silently stops narrowing.
-WINDOW_KINDS = (
-    "all_time",
-    "today",
-    "yesterday",
-    "this_week",
-    "last_week",
-    "this_month",
-    "last_month",
-    "this_quarter",
-    "last_quarter",
-    "this_year",
-    "last_year",
-    "ytd",
-    "ytd_last_year",
-    "ltm",
-    "past_week",
-    "past_month",
-    "past_year",
-    "last_n_days",
-    "next_n_days",
-    "custom",
-)
-
-#: Kinds that carry an integer `n`.
-N_KINDS = frozenset({"last_n_days", "next_n_days"})
-
-#: How each kind reads in a sentence. The UI renders these; they are here so the label and the
-#: arithmetic cannot drift apart in the one place a user would never think to check.
-WINDOW_LABELS = {
-    "all_time": "all time",
-    "today": "today",
-    "yesterday": "yesterday",
-    "this_week": "this week",
-    "last_week": "last week",
-    "this_month": "this month",
-    "last_month": "last month",
-    "this_quarter": "this quarter",
-    "last_quarter": "last quarter",
-    "this_year": "this year",
-    "last_year": "last year",
-    "ytd": "year to date",
-    # "last year to date" (LYTD), not "year to date, last year": the longer phrasing CLIPPED to
-    # "year to date, last ye" in the 146px window select — and this vocabulary is CLOSED, so
-    # the rule for it is that it stays readable rather than that it fits. Seen in a live
-    # screenshot of the owner's own comparison; every assertion in that run was green.
-    "ytd_last_year": "last year to date",
-    "ltm": "the last 12 months",
-    "past_week": "the past week",
-    "past_month": "the past month",
-    "past_year": "the past year",
-    "last_n_days": "the last {n} days",
-    "next_n_days": "the next {n} days",
-    "custom": "a custom range",
-}
-
-MAX_N = 3650          # ten years; a bound, not a business rule
-
-# --- the DATE-VALUE anchors (owner item 3, 2026-07-26) ----------------------------------------
-# The second half of a date CONDITION, as distinct from a measure's window:
-#
-#     Where [Last order] [is before] [one month ago]
-#                          ^ op        ^ THIS
-#
-# A window answers "over what period do I sum"; an anchor answers "which single date am I
-# comparing against". Both live in this module for one reason: they are the same two-engine
-# contract, resolved from the same `today`, and a gate that holds one in lock-step and not the
-# other would leave half the sentence free to drift.
-
-#: Anchor modes, in the order the picker offers them. `exact` is the historical behaviour — a
-#: rule with NO mode is an `exact` rule whose value is an ISO date, which is what every view
-#: saved before this change carries.
-ANCHOR_MODES = (
-    "today",
-    "yesterday",
-    "one_week_ago",
-    "one_month_ago",
-    "n_days_ago",
-    "exact",
-)
-
-#: Modes that carry NO value. ⚠ This set is load-bearing far outside this module: a rule whose
-#: value is blank normally reads as INACTIVE, and an inactive rule is IGNORED — which WIDENS the
-#: result under a count nobody would doubt. Every activeness check (`isRuleActive` in TS,
-#: `filter_sql.is_rule_active`, and the validator's value handling) has to know these four are
-#: active with an empty value.
-ANCHOR_VALUE_FREE = frozenset({"today", "yesterday", "one_week_ago", "one_month_ago"})
-
-ANCHOR_LABELS = {
-    "today": "today",
-    "yesterday": "yesterday",
-    "one_week_ago": "one week ago",
-    "one_month_ago": "one month ago",
-    "n_days_ago": "{n} days ago",
-    "exact": "an exact date",
-}
-
-
-def _iso(d):
-    return d.isoformat()
-
-
-def _month_start(d):
-    return d.replace(day=1)
-
-
-def _month_end(d):
-    return _next_month(d.replace(day=1)) - _dt.timedelta(days=1)
-
-
-def _next_month(d):
-    return (d.replace(day=28) + _dt.timedelta(days=4)).replace(day=1)
-
-
-def _quarter_start(d):
-    return _dt.date(d.year, 3 * ((d.month - 1) // 3) + 1, 1)
-
-
-def _days_in_month(y, m):
-    return (_dt.date(y + (m == 12), 1 if m == 12 else m + 1, 1) - _dt.timedelta(days=1)).day
-
-
-def _shift_months(d, n):
-    """`d` moved `n` months, CLAMPING the day to the target month's length.
-
-    Jan 31 back one month is Dec 31, but Mar 31 back one month is Feb 28 (or 29) — there is no
-    Feb 31 to land on. Both engines must clamp identically or "the past month" differs by up to
-    three days for a third of the calendar; the gate probes a 31st and a leap day for exactly it.
-    """
-    total = (d.year * 12 + (d.month - 1)) + n
-    y, m = divmod(total, 12)
-    m += 1
-    return _dt.date(y, m, min(d.day, _days_in_month(y, m)))
-
-
-def _parse_date(v):
-    """Accept 'YYYY-MM-DD' (and tolerate a longer ISO timestamp by taking its date part)."""
-    if isinstance(v, _dt.date):
-        return v
-    s = str(v or "").strip()[:10]
-    if not s:
-        return None
-    try:
-        return _dt.date.fromisoformat(s)
-    except ValueError:
-        return None
-
-
-def normalize(spec):
-    """Coerce an untrusted window spec to `{kind, n?, from?, to?}` or None.
-
-    Fail-closed on the KIND (an unknown kind is not a window), tolerant on the rest — the same
-    split `clean_filter_tree` uses, so one malformed window cannot cost a user their saved view.
-    """
-    if not isinstance(spec, dict):
-        return None
-    kind = spec.get("kind")
-    if kind not in WINDOW_KINDS:
-        return None
-    out = {"kind": kind}
-    if kind in N_KINDS:
-        try:
-            n = int(spec.get("n"))
-        except (TypeError, ValueError):
-            return None
-        if n < 1 or n > MAX_N:
-            return None
-        out["n"] = n
-    if kind == "custom":
-        f, t = _parse_date(spec.get("from")), _parse_date(spec.get("to"))
-        if f is None and t is None:
-            return None                    # a custom range with no bounds is not a window
-        if f is not None and t is not None and f > t:
-            f, t = t, f                    # the builder cannot enforce order; the engine can
-        if f is not None:
-            out["from"] = _iso(f)
-        if t is not None:
-            out["to"] = _iso(t)
-    return out
-
-
-def resolve(spec, today):
-    """Window spec + the tenant's today -> `(date_from, date_to)`, both inclusive ISO dates.
-
-    Either side may be None, meaning open-ended. Returns None when the spec is not a window at
-    all — callers MUST treat that as "this condition cannot be evaluated" and refuse, never as
-    "no window", which would silently widen the result to all time.
-    """
-    spec = normalize(spec)
-    if spec is None:
-        return None
-    kind = spec["kind"]
-    d = _parse_date(today)
-    if d is None:
-        raise ValueError("resolve() needs an explicit `today` — see this module's docstring")
-
-    if kind == "all_time":
-        return (None, None)
-    if kind == "today":
-        return (_iso(d), _iso(d))
-    if kind == "yesterday":
-        y = d - _dt.timedelta(days=1)
-        return (_iso(y), _iso(y))
-
-    # ISO 8601: the week starts MONDAY. Python's weekday() is already Monday=0; the TS mirror
-    # has to correct getDay(), which is Sunday=0. The gate probes both a Sunday and a Monday.
-    if kind == "this_week":
-        start = d - _dt.timedelta(days=d.weekday())
-        return (_iso(start), _iso(start + _dt.timedelta(days=6)))
-    if kind == "last_week":
-        start = d - _dt.timedelta(days=d.weekday() + 7)
-        return (_iso(start), _iso(start + _dt.timedelta(days=6)))
-
-    if kind == "this_month":
-        return (_iso(_month_start(d)), _iso(_month_end(d)))
-    if kind == "last_month":
-        prev = _month_start(d) - _dt.timedelta(days=1)
-        return (_iso(_month_start(prev)), _iso(prev))
-
-    if kind == "this_quarter":
-        qs = _quarter_start(d)
-        qe = _month_end(_dt.date(qs.year, qs.month + 2, 1))
-        return (_iso(qs), _iso(qe))
-    if kind == "last_quarter":
-        prev_end = _quarter_start(d) - _dt.timedelta(days=1)
-        qs = _quarter_start(prev_end)
-        return (_iso(qs), _iso(prev_end))
-
-    if kind == "this_year":
-        return (_iso(_dt.date(d.year, 1, 1)), _iso(_dt.date(d.year, 12, 31)))
-    if kind == "last_year":
-        return (_iso(_dt.date(d.year - 1, 1, 1)), _iso(_dt.date(d.year - 1, 12, 31)))
-    if kind == "ytd":
-        # year-to-date ENDS TODAY, unlike this_year which runs to Dec 31. The distinction is the
-        # whole reason both exist: comparing "this year" against last year double-counts the
-        # months that have not happened yet.
-        return (_iso(_dt.date(d.year, 1, 1)), _iso(d))
-    if kind == "ytd_last_year":
-        # SAME PERIOD last year — Jan 1 LY through today's month/day LY. This is the honest
-        # partner of `ytd`, and it is not a nicety: it mirrors `core.periods.ytd_last_year`
-        # EXACTLY (including the Feb 29 -> Feb 28 clamp), which is what `pool()` computes the
-        # `revenue_ly` column from. `Sales[ytd] < Sales[ytd_last_year]` therefore reproduces the
-        # retired `at_risk > 0` condition rather than approximating it. Comparing `ytd` against
-        # `last_year` instead would pit seven months against twelve.
-        return (_iso(_dt.date(d.year - 1, 1, 1)), _iso(_shift_months(d, -12)))
-    if kind == "ltm":
-        # the last twelve months INCLUDING today: 365 days back, both ends inclusive
-        return (_iso(d - _dt.timedelta(days=364)), _iso(d))
-
-    # "The past week/month/year" are ROLLING and end TODAY — Airtable's wording, and NOT the
-    # calendar kinds above: `last_week` is the previous Monday-Sunday, `past_week` is the seven
-    # days ending today. Both are offered because a user means different things by them, and
-    # picking one to serve both would silently answer the other question.
-    #   past_week  = the same rule as last_n_days(7) — one period back, PLUS ONE DAY, so today
-    #                is included and the span is exactly 7 days rather than 8.
-    #   past_year  agrees with `ltm` except across a leap day, where the calendar shift keeps the
-    #              same month/day and the 364-day subtraction cannot.
-    if kind == "past_week":
-        return (_iso(d - _dt.timedelta(days=6)), _iso(d))
-    if kind == "past_month":
-        return (_iso(_shift_months(d, -1) + _dt.timedelta(days=1)), _iso(d))
-    if kind == "past_year":
-        return (_iso(_shift_months(d, -12) + _dt.timedelta(days=1)), _iso(d))
-
-    if kind == "last_n_days":
-        # INCLUSIVE of today — "the last 7 days" is today and the 6 before it, not the 7 before
-        # yesterday. Getting this wrong drops today's orders from every recent-activity filter.
-        return (_iso(d - _dt.timedelta(days=spec["n"] - 1)), _iso(d))
-    if kind == "next_n_days":
-        return (_iso(d), _iso(d + _dt.timedelta(days=spec["n"] - 1)))
-
-    if kind == "custom":
-        return (spec.get("from"), spec.get("to"))
-    raise AssertionError(f"unhandled window kind {kind!r}")   # unreachable; WINDOW_KINDS is closed
-
-
-def label(spec):
-    """How a window reads in the condition sentence ('in the last 90 days')."""
-    spec = normalize(spec)
-    if spec is None:
-        return "an invalid range"
-    return WINDOW_LABELS[spec["kind"]].format(n=spec.get("n"))
-
-
-def resolve_anchor(mode, value, today):
-    """A date condition's right-hand side -> ONE inclusive ISO date, or None.
-
-    `mode` is an entry of ANCHOR_MODES; None/'' means `exact`, which is what every view saved
-    before anchors existed carries (op + an ISO date in `value`). `value` supplies the number for
-    `n_days_ago` and the date for `exact`, and is ignored by the four value-free modes.
-
-    Returns None when the anchor cannot be resolved — an unknown mode, a non-numeric N, a value
-    that is not a date. The caller must then treat the CONDITION as unanswerable and match
-    nothing. It must NOT fall through to "no condition": that widens the result while the count
-    beside it still looks authoritative, which is the whole reason this returns None rather than
-    a best guess (same contract as `resolve()` above).
-
-    `n_days_ago` accepts n = 0 where a WINDOW requires n >= 1. A zero-day window is empty and
-    could only be a mistake; "0 days ago" is today, which is a date a person can mean.
-    """
-    m = mode or "exact"
-    if m not in ANCHOR_MODES:
-        return None
-    d = _parse_date(today)
-    if d is None:
-        raise ValueError("resolve_anchor() needs an explicit `today` — see this module's "
-                         "docstring on why the clock is never read here")
-    if m == "today":
-        return _iso(d)
-    if m == "yesterday":
-        return _iso(d - _dt.timedelta(days=1))
-    if m == "one_week_ago":
-        # A week ago is a DATE (today minus 7), not the past-week RANGE. The two read almost
-        # identically in English and mean different things in a comparison.
-        return _iso(d - _dt.timedelta(days=7))
-    if m == "one_month_ago":
-        return _iso(_shift_months(d, -1))
-    if m == "n_days_ago":
-        s = str("" if value is None else value).strip()
-        # `[0-9]` not `\d`: a Python \d matches every Unicode decimal digit, so a fullwidth
-        # '３０' would resolve here and be rejected by the TS mirror's Number() — the exact
-        # two-engine divergence filter_sql.to_num was rewritten to avoid.
-        if not s or not all("0" <= ch <= "9" for ch in s):
-            return None
-        n = int(s)
-        # No `n < 0` guard: the digit test above already excludes a sign, so it would be
-        # unreachable. The negative control proved that — removing it changed nothing, which is
-        # how dead code hides in a defensive-looking line. The CAP is the live guard.
-        if n > MAX_N:
-            return None
-        return _iso(d - _dt.timedelta(days=n))
-    parsed = _parse_date(value)                      # exact
-    return None if parsed is None else _iso(parsed)
-
-
-def anchor_label(mode, value):
-    """How an anchor reads in the condition sentence ('one month ago', '30 days ago')."""
-    m = mode or "exact"
-    if m not in ANCHOR_MODES:
-        return "an invalid date"
-    if m == "n_days_ago":
-        return ANCHOR_LABELS[m].format(n=str("" if value is None else value).strip() or "N")
-    if m == "exact":
-        return str("" if value is None else value).strip() or ANCHOR_LABELS[m]
-    return ANCHOR_LABELS[m]
+"""harness/windows.py — the DATE WINDOW vocabulary (CG-7, owner item 2, 2026-07-26).
+
+A filter condition on a measure reads:
+
+    Where [Sales] [in the last 90 days] [>] [5,000]
+
+The middle bracket is this module. It turns a window SPEC — a small JSON object a saved view can
+persist — into a concrete `(date_from, date_to)` pair of ISO dates.
+
+WHY IT IS ITS OWN MODULE, AND WHY IT TAKES `today` AS AN ARGUMENT
+-----------------------------------------------------------------------------------------------
+Two engines must agree on what "this quarter" means: this one (which compiles the SQL) and
+`customer-grid/windows.ts` (which renders the label the user reads and the bounds the client
+engine would use). If they disagree by one day, the grid shows a number the label denies, and
+nothing errors. `aios-web/verify_windows.py` holds them in lock-step over a fixed set of probe
+dates, exactly as verify_filter_engine.py does for the filter tree.
+
+`today` is a PARAMETER, never `date.today()` read inside. Three reasons, all learned:
+  - a gate cannot compare two engines on "now" — the two runs are milliseconds apart and land on
+    different sides of midnight roughly once every few thousand runs, which is the worst kind of
+    flake because it looks like a real divergence
+  - a window resolved during a request must not shift between the count query and the row query
+  - the tenant's day boundary is the tenant's, not the server's
+
+DESIGN NOTES THAT ARE EASY TO GET WRONG
+-----------------------------------------------------------------------------------------------
+  - Bounds are INCLUSIVE at both ends and are DATES, not timestamps. `store_query` casts both
+    sides to TIMESTAMP and appends 23:59:59 to the upper bound, so a bare date is correct there;
+    the client compares the 10-char ISO prefix, so a bare date is correct there too.
+  - "Last N days" INCLUDES today. Airtable's "the past week" means the last 7 days up to and
+    including now, not the 7 days before yesterday. Off-by-one here silently drops today's
+    orders from every "recent" filter — invisible until someone asks why a sale they just
+    entered is missing.
+  - Week starts MONDAY (ISO 8601). Stated rather than defaulted: Python's weekday() is
+    Monday=0 and JavaScript's getDay() is Sunday=0, so the two engines disagree unless one of
+    them is explicitly corrected. That correction is the single most likely divergence in this
+    file, and the gate probes a Sunday and a Monday for exactly that reason.
+  - A `custom` window with only one bound is legal and means open-ended on the other side.
+  - An UNRESOLVABLE window returns None rather than a default. A window that quietly becomes
+    "all time" would widen a filter while still reporting an authoritative count.
+"""
+import datetime as _dt
+
+#: Every window kind the UI may offer. Mirrors WINDOW_KINDS in customer-grid/windows.ts;
+#: verify_windows.py asserts the two lists are identical, because a kind the client can emit and
+#: the server cannot resolve is a filter that silently stops narrowing.
+WINDOW_KINDS = (
+    "all_time",
+    "today",
+    "yesterday",
+    "this_week",
+    "last_week",
+    "this_month",
+    "last_month",
+    "this_quarter",
+    "last_quarter",
+    "this_year",
+    "last_year",
+    "ytd",
+    "ytd_last_year",
+    "ltm",
+    "past_week",
+    "past_month",
+    "past_year",
+    "last_n_days",
+    "next_n_days",
+    "custom",
+)
+
+#: Kinds that carry an integer `n`.
+N_KINDS = frozenset({"last_n_days", "next_n_days"})
+
+#: How each kind reads in a sentence. The UI renders these; they are here so the label and the
+#: arithmetic cannot drift apart in the one place a user would never think to check.
+WINDOW_LABELS = {
+    "all_time": "all time",
+    "today": "today",
+    "yesterday": "yesterday",
+    "this_week": "this week",
+    "last_week": "last week",
+    "this_month": "this month",
+    "last_month": "last month",
+    "this_quarter": "this quarter",
+    "last_quarter": "last quarter",
+    "this_year": "this year",
+    "last_year": "last year",
+    "ytd": "year to date",
+    # "last year to date" (LYTD), not "year to date, last year": the longer phrasing CLIPPED to
+    # "year to date, last ye" in the 146px window select — and this vocabulary is CLOSED, so
+    # the rule for it is that it stays readable rather than that it fits. Seen in a live
+    # screenshot of the owner's own comparison; every assertion in that run was green.
+    "ytd_last_year": "last year to date",
+    "ltm": "the last 12 months",
+    "past_week": "the past week",
+    "past_month": "the past month",
+    "past_year": "the past year",
+    "last_n_days": "the last {n} days",
+    "next_n_days": "the next {n} days",
+    "custom": "a custom range",
+}
+
+MAX_N = 3650          # ten years; a bound, not a business rule
+
+# --- the DATE-VALUE anchors (owner item 3, 2026-07-26) ----------------------------------------
+# The second half of a date CONDITION, as distinct from a measure's window:
+#
+#     Where [Last order] [is before] [one month ago]
+#                          ^ op        ^ THIS
+#
+# A window answers "over what period do I sum"; an anchor answers "which single date am I
+# comparing against". Both live in this module for one reason: they are the same two-engine
+# contract, resolved from the same `today`, and a gate that holds one in lock-step and not the
+# other would leave half the sentence free to drift.
+
+#: Anchor modes, in the order the picker offers them. `exact` is the historical behaviour — a
+#: rule with NO mode is an `exact` rule whose value is an ISO date, which is what every view
+#: saved before this change carries.
+ANCHOR_MODES = (
+    "today",
+    "yesterday",
+    "one_week_ago",
+    "one_month_ago",
+    "n_days_ago",
+    "exact",
+)
+
+#: Modes that carry NO value. ⚠ This set is load-bearing far outside this module: a rule whose
+#: value is blank normally reads as INACTIVE, and an inactive rule is IGNORED — which WIDENS the
+#: result under a count nobody would doubt. Every activeness check (`isRuleActive` in TS,
+#: `filter_sql.is_rule_active`, and the validator's value handling) has to know these four are
+#: active with an empty value.
+ANCHOR_VALUE_FREE = frozenset({"today", "yesterday", "one_week_ago", "one_month_ago"})
+
+ANCHOR_LABELS = {
+    "today": "today",
+    "yesterday": "yesterday",
+    "one_week_ago": "one week ago",
+    "one_month_ago": "one month ago",
+    "n_days_ago": "{n} days ago",
+    "exact": "an exact date",
+}
+
+
+def _iso(d):
+    return d.isoformat()
+
+
+def _month_start(d):
+    return d.replace(day=1)
+
+
+def _month_end(d):
+    return _next_month(d.replace(day=1)) - _dt.timedelta(days=1)
+
+
+def _next_month(d):
+    return (d.replace(day=28) + _dt.timedelta(days=4)).replace(day=1)
+
+
+def _quarter_start(d):
+    return _dt.date(d.year, 3 * ((d.month - 1) // 3) + 1, 1)
+
+
+def _days_in_month(y, m):
+    return (_dt.date(y + (m == 12), 1 if m == 12 else m + 1, 1) - _dt.timedelta(days=1)).day
+
+
+def _shift_months(d, n):
+    """`d` moved `n` months, CLAMPING the day to the target month's length.
+
+    Jan 31 back one month is Dec 31, but Mar 31 back one month is Feb 28 (or 29) — there is no
+    Feb 31 to land on. Both engines must clamp identically or "the past month" differs by up to
+    three days for a third of the calendar; the gate probes a 31st and a leap day for exactly it.
+    """
+    total = (d.year * 12 + (d.month - 1)) + n
+    y, m = divmod(total, 12)
+    m += 1
+    return _dt.date(y, m, min(d.day, _days_in_month(y, m)))
+
+
+def _parse_date(v):
+    """Accept 'YYYY-MM-DD' (and tolerate a longer ISO timestamp by taking its date part)."""
+    if isinstance(v, _dt.date):
+        return v
+    s = str(v or "").strip()[:10]
+    if not s:
+        return None
+    try:
+        return _dt.date.fromisoformat(s)
+    except ValueError:
+        return None
+
+
+def normalize(spec):
+    """Coerce an untrusted window spec to `{kind, n?, from?, to?}` or None.
+
+    Fail-closed on the KIND (an unknown kind is not a window), tolerant on the rest — the same
+    split `clean_filter_tree` uses, so one malformed window cannot cost a user their saved view.
+    """
+    if not isinstance(spec, dict):
+        return None
+    kind = spec.get("kind")
+    if kind not in WINDOW_KINDS:
+        return None
+    out = {"kind": kind}
+    if kind in N_KINDS:
+        try:
+            n = int(spec.get("n"))
+        except (TypeError, ValueError):
+            return None
+        if n < 1 or n > MAX_N:
+            return None
+        out["n"] = n
+    if kind == "custom":
+        f, t = _parse_date(spec.get("from")), _parse_date(spec.get("to"))
+        if f is None and t is None:
+            return None                    # a custom range with no bounds is not a window
+        if f is not None and t is not None and f > t:
+            f, t = t, f                    # the builder cannot enforce order; the engine can
+        if f is not None:
+            out["from"] = _iso(f)
+        if t is not None:
+            out["to"] = _iso(t)
+    return out
+
+
+def resolve(spec, today):
+    """Window spec + the tenant's today -> `(date_from, date_to)`, both inclusive ISO dates.
+
+    Either side may be None, meaning open-ended. Returns None when the spec is not a window at
+    all — callers MUST treat that as "this condition cannot be evaluated" and refuse, never as
+    "no window", which would silently widen the result to all time.
+    """
+    spec = normalize(spec)
+    if spec is None:
+        return None
+    kind = spec["kind"]
+    d = _parse_date(today)
+    if d is None:
+        raise ValueError("resolve() needs an explicit `today` — see this module's docstring")
+
+    if kind == "all_time":
+        return (None, None)
+    if kind == "today":
+        return (_iso(d), _iso(d))
+    if kind == "yesterday":
+        y = d - _dt.timedelta(days=1)
+        return (_iso(y), _iso(y))
+
+    # ISO 8601: the week starts MONDAY. Python's weekday() is already Monday=0; the TS mirror
+    # has to correct getDay(), which is Sunday=0. The gate probes both a Sunday and a Monday.
+    if kind == "this_week":
+        start = d - _dt.timedelta(days=d.weekday())
+        return (_iso(start), _iso(start + _dt.timedelta(days=6)))
+    if kind == "last_week":
+        start = d - _dt.timedelta(days=d.weekday() + 7)
+        return (_iso(start), _iso(start + _dt.timedelta(days=6)))
+
+    if kind == "this_month":
+        return (_iso(_month_start(d)), _iso(_month_end(d)))
+    if kind == "last_month":
+        prev = _month_start(d) - _dt.timedelta(days=1)
+        return (_iso(_month_start(prev)), _iso(prev))
+
+    if kind == "this_quarter":
+        qs = _quarter_start(d)
+        qe = _month_end(_dt.date(qs.year, qs.month + 2, 1))
+        return (_iso(qs), _iso(qe))
+    if kind == "last_quarter":
+        prev_end = _quarter_start(d) - _dt.timedelta(days=1)
+        qs = _quarter_start(prev_end)
+        return (_iso(qs), _iso(prev_end))
+
+    if kind == "this_year":
+        return (_iso(_dt.date(d.year, 1, 1)), _iso(_dt.date(d.year, 12, 31)))
+    if kind == "last_year":
+        return (_iso(_dt.date(d.year - 1, 1, 1)), _iso(_dt.date(d.year - 1, 12, 31)))
+    if kind == "ytd":
+        # year-to-date ENDS TODAY, unlike this_year which runs to Dec 31. The distinction is the
+        # whole reason both exist: comparing "this year" against last year double-counts the
+        # months that have not happened yet.
+        return (_iso(_dt.date(d.year, 1, 1)), _iso(d))
+    if kind == "ytd_last_year":
+        # SAME PERIOD last year — Jan 1 LY through today's month/day LY. This is the honest
+        # partner of `ytd`, and it is not a nicety: it mirrors `core.periods.ytd_last_year`
+        # EXACTLY (including the Feb 29 -> Feb 28 clamp), which is what `pool()` computes the
+        # `revenue_ly` column from. `Sales[ytd] < Sales[ytd_last_year]` therefore reproduces the
+        # retired `at_risk > 0` condition rather than approximating it. Comparing `ytd` against
+        # `last_year` instead would pit seven months against twelve.
+        return (_iso(_dt.date(d.year - 1, 1, 1)), _iso(_shift_months(d, -12)))
+    if kind == "ltm":
+        # the last twelve months INCLUDING today: 365 days back, both ends inclusive
+        return (_iso(d - _dt.timedelta(days=364)), _iso(d))
+
+    # "The past week/month/year" are ROLLING and end TODAY — Airtable's wording, and NOT the
+    # calendar kinds above: `last_week` is the previous Monday-Sunday, `past_week` is the seven
+    # days ending today. Both are offered because a user means different things by them, and
+    # picking one to serve both would silently answer the other question.
+    #   past_week  = the same rule as last_n_days(7) — one period back, PLUS ONE DAY, so today
+    #                is included and the span is exactly 7 days rather than 8.
+    #   past_year  agrees with `ltm` except across a leap day, where the calendar shift keeps the
+    #              same month/day and the 364-day subtraction cannot.
+    if kind == "past_week":
+        return (_iso(d - _dt.timedelta(days=6)), _iso(d))
+    if kind == "past_month":
+        return (_iso(_shift_months(d, -1) + _dt.timedelta(days=1)), _iso(d))
+    if kind == "past_year":
+        return (_iso(_shift_months(d, -12) + _dt.timedelta(days=1)), _iso(d))
+
+    if kind == "last_n_days":
+        # INCLUSIVE of today — "the last 7 days" is today and the 6 before it, not the 7 before
+        # yesterday. Getting this wrong drops today's orders from every recent-activity filter.
+        return (_iso(d - _dt.timedelta(days=spec["n"] - 1)), _iso(d))
+    if kind == "next_n_days":
+        return (_iso(d), _iso(d + _dt.timedelta(days=spec["n"] - 1)))
+
+    if kind == "custom":
+        return (spec.get("from"), spec.get("to"))
+    raise AssertionError(f"unhandled window kind {kind!r}")   # unreachable; WINDOW_KINDS is closed
+
+
+def label(spec):
+    """How a window reads in the condition sentence ('in the last 90 days')."""
+    spec = normalize(spec)
+    if spec is None:
+        return "an invalid range"
+    return WINDOW_LABELS[spec["kind"]].format(n=spec.get("n"))
+
+
+def resolve_anchor(mode, value, today):
+    """A date condition's right-hand side -> ONE inclusive ISO date, or None.
+
+    `mode` is an entry of ANCHOR_MODES; None/'' means `exact`, which is what every view saved
+    before anchors existed carries (op + an ISO date in `value`). `value` supplies the number for
+    `n_days_ago` and the date for `exact`, and is ignored by the four value-free modes.
+
+    Returns None when the anchor cannot be resolved — an unknown mode, a non-numeric N, a value
+    that is not a date. The caller must then treat the CONDITION as unanswerable and match
+    nothing. It must NOT fall through to "no condition": that widens the result while the count
+    beside it still looks authoritative, which is the whole reason this returns None rather than
+    a best guess (same contract as `resolve()` above).
+
+    `n_days_ago` accepts n = 0 where a WINDOW requires n >= 1. A zero-day window is empty and
+    could only be a mistake; "0 days ago" is today, which is a date a person can mean.
+    """
+    m = mode or "exact"
+    if m not in ANCHOR_MODES:
+        return None
+    d = _parse_date(today)
+    if d is None:
+        raise ValueError("resolve_anchor() needs an explicit `today` — see this module's "
+                         "docstring on why the clock is never read here")
+    if m == "today":
+        return _iso(d)
+    if m == "yesterday":
+        return _iso(d - _dt.timedelta(days=1))
+    if m == "one_week_ago":
+        # A week ago is a DATE (today minus 7), not the past-week RANGE. The two read almost
+        # identically in English and mean different things in a comparison.
+        return _iso(d - _dt.timedelta(days=7))
+    if m == "one_month_ago":
+        return _iso(_shift_months(d, -1))
+    if m == "n_days_ago":
+        s = str("" if value is None else value).strip()
+        # `[0-9]` not `\d`: a Python \d matches every Unicode decimal digit, so a fullwidth
+        # '３０' would resolve here and be rejected by the TS mirror's Number() — the exact
+        # two-engine divergence filter_sql.to_num was rewritten to avoid.
+        if not s or not all("0" <= ch <= "9" for ch in s):
+            return None
+        n = int(s)
+        # No `n < 0` guard: the digit test above already excludes a sign, so it would be
+        # unreachable. The negative control proved that — removing it changed nothing, which is
+        # how dead code hides in a defensive-looking line. The CAP is the live guard.
+        if n > MAX_N:
+            return None
+        return _iso(d - _dt.timedelta(days=n))
+    parsed = _parse_date(value)                      # exact
+    return None if parsed is None else _iso(parsed)
+
+
+def anchor_label(mode, value):
+    """How an anchor reads in the condition sentence ('one month ago', '30 days ago')."""
+    m = mode or "exact"
+    if m not in ANCHOR_MODES:
+        return "an invalid date"
+    if m == "n_days_ago":
+        return ANCHOR_LABELS[m].format(n=str("" if value is None else value).strip() or "N")
+    if m == "exact":
+        return str("" if value is None else value).strip() or ANCHOR_LABELS[m]
+    return ANCHOR_LABELS[m]

platform/model/metrics/returns.yml

@@ -1,55 +1,55 @@
-# Metrics: returns — the credit-note lens, defined once (2026-07-27, owner's ask).
-#
-# `modules/returns.py` has read these numbers from Odoo since it shipped; this file makes them
-# MODEL metrics so the Analyst, the metric dictionary and the customer-grid condition builder all
-# resolve the same definition instead of three.
-topic: credit_notes
-metrics:
-  - key: returns
-    label: Returns $
-    agg: sum
-    field: amount_untaxed_signed
-    negate: true
-    format: usd
-    description: >-
-      Untaxed value of posted customer credit notes (refunds), reported POSITIVE.
-    ai_context: >-
-      ⚠ NEGATE IS LOAD-BEARING. `amount_untaxed_signed` is negative on a credit note, so the raw
-      sum is negative and this metric flips it. A returns figure that arrives negative means the
-      negation was lost somewhere — and it will read as "no returns" rather than as an error.
-      Company-level: credit notes are not business-unit tagged (they all carry team_id 1), so
-      never attribute a returns number to Fisch or Royal. Attribute by CUSTOMER instead.
-    validate:
-      method: returns_sign
-      note: >-
-        Independent check: the metric must equal the ABSOLUTE untaxed total of the same posted
-        credit notes read straight from Odoo, and must be positive. Catches a lost or doubled
-        negation, which self-consistency cannot see.
-
-  - key: invoiced
-    label: Invoiced $
-    topic: customer_invoices
-    agg: sum
-    field: amount_untaxed_signed
-    format: usd
-    description: >-
-      Untaxed value of posted customer invoices — the denominator the business rates returns
-      against.
-    ai_context: >-
-      NOT `revenue`. `revenue` is order-LINE subtotals of confirmed sales orders; this is posted
-      billing documents, and the two differ by unbilled orders and by billing timing. Use
-      `revenue` for "sales" and this only as the return-rate denominator.
-
-  - key: returns_pct
-    label: Return %
-    agg: ratio
-    numerator: returns
-    denominator: invoiced
-    format: pct
-    description: "Returns as a share of invoiced sales — the rate modules/returns.py reports."
-    ai_context: >-
-      A FRACTION (0-1), like every other pct metric here — 0.0159 is 1.59%. The condition builder
-      divides a typed percentage by 100 before comparing (`input_scale`), so a user types 5 and
-      means 5%. Guarded against zero invoiced (returns 0). Cross-topic: the numerator is on
-      credit_notes and the denominator on customer_invoices, so it is resolved per customer by
-      computing both and combining, never by one query.
+# Metrics: returns — the credit-note lens, defined once (2026-07-27, owner's ask).
+#
+# `modules/returns.py` has read these numbers from Odoo since it shipped; this file makes them
+# MODEL metrics so the Analyst, the metric dictionary and the customer-grid condition builder all
+# resolve the same definition instead of three.
+topic: credit_notes
+metrics:
+  - key: returns
+    label: Returns $
+    agg: sum
+    field: amount_untaxed_signed
+    negate: true
+    format: usd
+    description: >-
+      Untaxed value of posted customer credit notes (refunds), reported POSITIVE.
+    ai_context: >-
+      ⚠ NEGATE IS LOAD-BEARING. `amount_untaxed_signed` is negative on a credit note, so the raw
+      sum is negative and this metric flips it. A returns figure that arrives negative means the
+      negation was lost somewhere — and it will read as "no returns" rather than as an error.
+      Company-level: credit notes are not business-unit tagged (they all carry team_id 1), so
+      never attribute a returns number to Fisch or Royal. Attribute by CUSTOMER instead.
+    validate:
+      method: returns_sign
+      note: >-
+        Independent check: the metric must equal the ABSOLUTE untaxed total of the same posted
+        credit notes read straight from Odoo, and must be positive. Catches a lost or doubled
+        negation, which self-consistency cannot see.
+
+  - key: invoiced
+    label: Invoiced $
+    topic: customer_invoices
+    agg: sum
+    field: amount_untaxed_signed
+    format: usd
+    description: >-
+      Untaxed value of posted customer invoices — the denominator the business rates returns
+      against.
+    ai_context: >-
+      NOT `revenue`. `revenue` is order-LINE subtotals of confirmed sales orders; this is posted
+      billing documents, and the two differ by unbilled orders and by billing timing. Use
+      `revenue` for "sales" and this only as the return-rate denominator.
+
+  - key: returns_pct
+    label: Return %
+    agg: ratio
+    numerator: returns
+    denominator: invoiced
+    format: pct
+    description: "Returns as a share of invoiced sales — the rate modules/returns.py reports."
+    ai_context: >-
+      A FRACTION (0-1), like every other pct metric here — 0.0159 is 1.59%. The condition builder
+      divides a typed percentage by 100 before comparing (`input_scale`), so a user types 5 and
+      means 5%. Guarded against zero invoiced (returns 0). Cross-topic: the numerator is on
+      credit_notes and the denominator on customer_invoices, so it is resolved per customer by
+      computing both and combining, never by one query.

platform/model/skills/sales.skill.yml

@@ -1,184 +1,184 @@
-# In-product SKILL: sales analysis recipes (v0, 2026-07-11) — the first "strong skills for
-# small-model AI" (the productization directive; omni-adoption addendum §3).
-#
-# WHAT THIS IS: short task recipes a SMALL model loads before acting. Each recipe maps a user ask
-# to an explicit TOOL-CALL PLAN over the semantic layer — the model navigates by recipe + changes
-# parameters, it never invents joins, scope, or SQL. This file is ALSO the binding spec for the
-# OM-4 tool registry: the tools named here (run_semantic_query, make_chart, make_kpi_card,
-# get_field_values, compose_dashboard) are the signatures OM-4
-# implements — recipes and tools ship and version TOGETHER (drift between them = a build error).
-#
-# Recipe fields: ask (the intent pattern, [brackets] = user-changeable parameters) · plan (the
-# tool calls, in order) · params (what the model may vary + allowed values) · guard (what it must
-# never do here). Every numeric answer inherits the platform rule: it must carry its drill link.
-key: sales
-label: Sales analysis
-topic: sales_lines          # default topic; recipes may name another (sales_orders)
-metrics: [revenue, units, margin, cogs, margin_pct, orders, customers, aov]
-
-recipes:
-  - ask: "revenue trend [monthly|weekly] [this year|LTM|a date range] [for Fisch|Royal|both]"
-    plan: >
-      run_semantic_query(topic=sales_lines, measures=[revenue], grain=month|week,
-      date_from=?, date_to=?, team_id=5|6|null) -> make_chart(kind=line, x=grain, y=revenue)
-    params: {grain: [month, week], team_id: [5, 6, null], window: "any date range"}
-    guard: "one BU per series; if the user asks 'both', emit two series (team_id=5 and 6), never a mixed line"
-
-  - ask: "top [N] customers [by revenue|margin] [window] [BU]"
-    plan: >
-      run_semantic_query(topic=sales_lines, measures=[revenue, margin], group_by=order_partner,
-      date_from=?, date_to=?, team_id=?, sort=-revenue, limit=N) -> make_chart(kind=bar)
-    params: {N: "5-50 (default 15)", sort: [revenue, margin]}
-    guard: "group_by uses DIRECT m2o fields only (order_partner, product) — dot-path groupings fail on this platform"
-
-  - ask: "top [N] products/SKUs [window] [BU]"
-    plan: >
-      run_semantic_query(topic=sales_lines, measures=[revenue, units, margin], group_by=product,
-      date_from=?, date_to=?, team_id=?, sort=-revenue, limit=N, exclude_services=true)
-      -> make_chart(kind=bar)
-    guard: "always exclude_services=true for SKU rankings (Delivery Charges pollutes top movers)"
-
-  - ask: "what gross margin [%] did we run [window]? (NO business-unit words in the ask)"
-    plan: >
-      run_semantic_query(topic=sales_lines, measures=[revenue, margin, margin_pct],
-      date_from=?, date_to=?)   # NO group_by — a plain margin question wants the CONSOLIDATED figure
-    guard: "only split by BU when the user says 'by business unit' / 'per BU' / 'Fisch vs Royal'"
-
-  - ask: "gross margin [%] BY BUSINESS UNIT / per BU / Fisch vs Royal [window]"
-    plan: >
-      run_semantic_query(topic=sales_lines, measures=[revenue, margin, margin_pct],
-      group_by=team, date_from=?, date_to=?) -> make_chart(kind=bar, y=margin_pct)
-    guard: "margin_pct is a ratio — computed at scope, never averaged from sub-rows"
-
-  - ask: "how are sales doing [window]? / sales KPIs"
-    plan: >
-      run_semantic_query(topic=sales_lines, measures=[revenue, margin_pct, orders, aov],
-      date_from=?, date_to=?, team_id=?) -> make_kpi_card(each metric, with same-window-last-year
-      deltas via a second query shifted -1 year)
-    guard: "deltas compare IDENTICAL windows year-over-year; never partial-vs-full periods"
-
-  - ask: "revenue by state / by product category / where do we sell the most"
-    plan: >
-      run_semantic_query(topic=sales_lines, measures=[revenue], group_by=[state|category],
-      sort=-revenue) -> make_chart(kind=bar, x=state|category, y=revenue)
-    guard: >
-      'state' = the customer's billing state; 'category' = the product's category, where the
-      root bucket literally named "All" is UNCATEGORIZED product — say so when it ranks
-
-  - ask: "top customers BASED IN / located in [New York|a state|a city]"
-    plan: >
-      get_field_values(topic=sales_lines, dim=state|city, search=<place>) -> run_semantic_query(
-      measures=[revenue], group_by=[order_partner], filters={state|city: [ids]}, sort=-revenue,
-      limit=N, date_from=?, date_to=?) -> make_table or ranked_bar
-    guard: >
-      location = the state/city dims, NEVER a customer-name search ('WEST NEW YORK FLORIST' is
-      not necessarily in New York). "New York" is ambiguous — check BOTH: if the state and the
-      city both match, ask which one (or default to the state and say so). City master data is
-      MESSY (case/trailing-space variants: 'BROOKLYN'/'Brooklyn'/'Brooklyn ') — include EVERY
-      matching variant from get_field_values in the filter. Always pass an explicit window and
-      state it.
-
-  - ask: "[salesperson/agent]'s customers / sales / top customers for [Naomi|an agent] [window]"
-    plan: >
-      get_field_values(topic=sales_lines, dim=agent, search=<name>) -> run_semantic_query(
-      topic=sales_lines, measures=[revenue], group_by=[order_partner], filters={agent: [id]},
-      date_from=?, date_to=?, sort=-revenue, limit=N) -> make_table or ranked_bar
-    guard: >
-      agent = the CUSTOMER's assigned sales agent (book attribution: every order of that
-      customer counts toward their agent) — resolve the agent's real name via get_field_values
-      on the agent dim FIRST, never from customer names. For the agent's TOTAL (not per
-      customer) drop the group_by. State the window.
-
-  - ask: "revenue [or orders] BY AGENT / how did the agents do / rank the agents [window]"
-    plan: >
-      run_semantic_query(topic=sales_lines, measures=[revenue, margin], group_by=[agent],
-      date_from=?, date_to=?, sort=-revenue) -> make_chart(kind=ranked_bar) or make_table
-    guard: >
-      the NULL agent group is customers with NO agent assigned — present it as "(no agent)"
-      and keep it in totals (it is usually large: house accounts). Order counts by agent run
-      on topic=sales_orders with the same agent dim.
-
-  - ask: "which customers are DECLINING / negative YoY / dropped the most [BU] [window]"
-    plan: >
-      run_semantic_query(measures=[revenue], group_by=[order_partner], team_id=?, date_from=?,
-      date_to=?, limit=1000) -> transform_result([{op: yoy}, {op: sort, by: revenue_delta,
-      direction: asc}, {op: head, n: 20}]) -> make_table(columns=[order_partner, revenue,
-      revenue_ly, revenue_delta, revenue_yoy_pct])
-    guard: >
-      YoY per customer comes ONLY from the yoy transform (adds revenue_ly, revenue_delta,
-      revenue_yoy_pct per row) — never join two queries by hand. sort revenue_delta asc + head
-      = biggest $ decline first. yoy needs explicit date_from/date_to on the source query.
-
-  - ask: "export to Excel / send me a spreadsheet / CSV"
-    plan: >
-      run_semantic_query(...) -> make_table(result_id, title=?) — then tell the user: the table
-      below has a 'Download CSV (opens in Excel)' button under it
-    guard: >
-      you cannot SEND files or email; the platform renders a download button under every chart's
-      data expander and every table. Never claim to have sent anything.
-
-  - ask: "map my customers / where are my [top] customers [by revenue]"
-    plan: >
-      run_semantic_query(topic=sales_lines, measures=[revenue], group_by=[order_partner],
-      sort=-revenue, limit=20..100) -> make_chart(kind=map, x=order_partner, y=revenue)
-    guard: >
-      the platform places each customer at its geocoded address, dot size = the measure; rows
-      without a geocoded address are skipped and counted on screen — no need to fetch
-      coordinates yourself
-
-  - ask: "compare this year to last year [monthly] [BU]"
-    plan: >
-      run_semantic_query(... grain=month, window=this year) + run_semantic_query(... window=last
-      year shifted) -> make_chart(kind=line, two series: this year, last year)
-
-  - ask: "which customer/product values are valid? (before filtering by name)"
-    plan: >
-      get_field_values(topic=sales_lines, field=order_partner|product, search=?) — resolve the
-      user's spelling to the real record BEFORE querying ('NYC Florist' vs the actual name)
-    guard: "never filter on a free-typed name; always resolve via get_field_values first"
-
-  - ask: "save this as a dashboard / add to my dashboard"
-    plan: >
-      save_view(each query above, name=?) -> compose_dashboard(views=[...], name=?)
-    guard: >
-      pass save_view the EXACT object make_chart/make_kpi_card returned (it carries the query —
-      saved views RE-RUN live; a spec without its query is rejected). After compose_dashboard,
-      tell the user the dashboard is now in the sidebar Workflows menu as 'Saved · <name>'
-      and stays current (every open re-runs the queries).
-
-  - ask: "change/edit that view or workbook — different window, add a breakdown, rename, reorder"
-    plan: >
-      list_workspace() to find the exact name -> update_view(name, changes={title?/kind?/x?/y?/
-      series?, query: {date_from?/date_to?/group_by?/grain?/filters?/limit?/...}}) for a view |
-      update_workbook(name, views=[new order], new_name=?) for a workbook (dashboard)
-    guard: >
-      UPDATE tools modify existing objects — state exactly what will change and confirm first;
-      update_view re-runs the patched query before saving, so report its row_count back. To
-      REMOVE a query key (e.g. drop a group_by), pass it as null.
-
-  - ask: "delete that view/dashboard/alert/report"
-    plan: "list_workspace() to resolve the exact kind+name -> delete_object(kind, name)"
-    guard: >
-      DESTRUCTIVE — never call delete_object unless the user explicitly confirmed THE NAMED
-      object in this conversation; deleting a view also removes it from workbooks that use it
-
-  - ask: "what dashboards/views/alerts do I have? / reuse that template"
-    plan: >
-      list_workspace() -> answer from the objects list; to reuse a template:
-      instantiate_template(filename, new_name=?) — it stamps NEW objects, never overwrites
-    guard: >
-      instantiate_template is an ARTIFACT tool — confirm with the user first; afterwards point
-      them to the new dashboard in the sidebar Workflows menu ('Saved · <name>')
-
-  - ask: "send me this every [Monday|month-start] / watch this KPI / alert me about X"
-    plan: >
-      (retired 2026-07-23 with the Routines module) say scheduled reports and KPI alerts are not
-      offered right now; offer the live alternative — save the view/dashboard so it re-runs
-      fresh on every open, and answer the underlying question NOW with run_semantic_query
-    guard: "never claim a schedule or alert was created; the schedule_report/create_alert/schedule_insight tools no longer exist"
-
-context: >
-  All recipes inherit the sales_lines topic scope (confirmed wholesale orders, untaxed amounts,
-  Amazon/GIFTWARE excluded, BUs strictly isolated — see the topic's ai_context). Order COUNTS come
-  from the sales_orders topic (order grain). Every number answered must link its drill-down rows;
-  if a query returns something that cannot be drilled, say so instead of presenting it.
+# In-product SKILL: sales analysis recipes (v0, 2026-07-11) — the first "strong skills for
+# small-model AI" (the productization directive; omni-adoption addendum §3).
+#
+# WHAT THIS IS: short task recipes a SMALL model loads before acting. Each recipe maps a user ask
+# to an explicit TOOL-CALL PLAN over the semantic layer — the model navigates by recipe + changes
+# parameters, it never invents joins, scope, or SQL. This file is ALSO the binding spec for the
+# OM-4 tool registry: the tools named here (run_semantic_query, make_chart, make_kpi_card,
+# get_field_values, compose_dashboard) are the signatures OM-4
+# implements — recipes and tools ship and version TOGETHER (drift between them = a build error).
+#
+# Recipe fields: ask (the intent pattern, [brackets] = user-changeable parameters) · plan (the
+# tool calls, in order) · params (what the model may vary + allowed values) · guard (what it must
+# never do here). Every numeric answer inherits the platform rule: it must carry its drill link.
+key: sales
+label: Sales analysis
+topic: sales_lines          # default topic; recipes may name another (sales_orders)
+metrics: [revenue, units, margin, cogs, margin_pct, orders, customers, aov]
+
+recipes:
+  - ask: "revenue trend [monthly|weekly] [this year|LTM|a date range] [for Fisch|Royal|both]"
+    plan: >
+      run_semantic_query(topic=sales_lines, measures=[revenue], grain=month|week,
+      date_from=?, date_to=?, team_id=5|6|null) -> make_chart(kind=line, x=grain, y=revenue)
+    params: {grain: [month, week], team_id: [5, 6, null], window: "any date range"}
+    guard: "one BU per series; if the user asks 'both', emit two series (team_id=5 and 6), never a mixed line"
+
+  - ask: "top [N] customers [by revenue|margin] [window] [BU]"
+    plan: >
+      run_semantic_query(topic=sales_lines, measures=[revenue, margin], group_by=order_partner,
+      date_from=?, date_to=?, team_id=?, sort=-revenue, limit=N) -> make_chart(kind=bar)
+    params: {N: "5-50 (default 15)", sort: [revenue, margin]}
+    guard: "group_by uses DIRECT m2o fields only (order_partner, product) — dot-path groupings fail on this platform"
+
+  - ask: "top [N] products/SKUs [window] [BU]"
+    plan: >
+      run_semantic_query(topic=sales_lines, measures=[revenue, units, margin], group_by=product,
+      date_from=?, date_to=?, team_id=?, sort=-revenue, limit=N, exclude_services=true)
+      -> make_chart(kind=bar)
+    guard: "always exclude_services=true for SKU rankings (Delivery Charges pollutes top movers)"
+
+  - ask: "what gross margin [%] did we run [window]? (NO business-unit words in the ask)"
+    plan: >
+      run_semantic_query(topic=sales_lines, measures=[revenue, margin, margin_pct],
+      date_from=?, date_to=?)   # NO group_by — a plain margin question wants the CONSOLIDATED figure
+    guard: "only split by BU when the user says 'by business unit' / 'per BU' / 'Fisch vs Royal'"
+
+  - ask: "gross margin [%] BY BUSINESS UNIT / per BU / Fisch vs Royal [window]"
+    plan: >
+      run_semantic_query(topic=sales_lines, measures=[revenue, margin, margin_pct],
+      group_by=team, date_from=?, date_to=?) -> make_chart(kind=bar, y=margin_pct)
+    guard: "margin_pct is a ratio — computed at scope, never averaged from sub-rows"
+
+  - ask: "how are sales doing [window]? / sales KPIs"
+    plan: >
+      run_semantic_query(topic=sales_lines, measures=[revenue, margin_pct, orders, aov],
+      date_from=?, date_to=?, team_id=?) -> make_kpi_card(each metric, with same-window-last-year
+      deltas via a second query shifted -1 year)
+    guard: "deltas compare IDENTICAL windows year-over-year; never partial-vs-full periods"
+
+  - ask: "revenue by state / by product category / where do we sell the most"
+    plan: >
+      run_semantic_query(topic=sales_lines, measures=[revenue], group_by=[state|category],
+      sort=-revenue) -> make_chart(kind=bar, x=state|category, y=revenue)
+    guard: >
+      'state' = the customer's billing state; 'category' = the product's category, where the
+      root bucket literally named "All" is UNCATEGORIZED product — say so when it ranks
+
+  - ask: "top customers BASED IN / located in [New York|a state|a city]"
+    plan: >
+      get_field_values(topic=sales_lines, dim=state|city, search=<place>) -> run_semantic_query(
+      measures=[revenue], group_by=[order_partner], filters={state|city: [ids]}, sort=-revenue,
+      limit=N, date_from=?, date_to=?) -> make_table or ranked_bar
+    guard: >
+      location = the state/city dims, NEVER a customer-name search ('WEST NEW YORK FLORIST' is
+      not necessarily in New York). "New York" is ambiguous — check BOTH: if the state and the
+      city both match, ask which one (or default to the state and say so). City master data is
+      MESSY (case/trailing-space variants: 'BROOKLYN'/'Brooklyn'/'Brooklyn ') — include EVERY
+      matching variant from get_field_values in the filter. Always pass an explicit window and
+      state it.
+
+  - ask: "[salesperson/agent]'s customers / sales / top customers for [Naomi|an agent] [window]"
+    plan: >
+      get_field_values(topic=sales_lines, dim=agent, search=<name>) -> run_semantic_query(
+      topic=sales_lines, measures=[revenue], group_by=[order_partner], filters={agent: [id]},
+      date_from=?, date_to=?, sort=-revenue, limit=N) -> make_table or ranked_bar
+    guard: >
+      agent = the CUSTOMER's assigned sales agent (book attribution: every order of that
+      customer counts toward their agent) — resolve the agent's real name via get_field_values
+      on the agent dim FIRST, never from customer names. For the agent's TOTAL (not per
+      customer) drop the group_by. State the window.
+
+  - ask: "revenue [or orders] BY AGENT / how did the agents do / rank the agents [window]"
+    plan: >
+      run_semantic_query(topic=sales_lines, measures=[revenue, margin], group_by=[agent],
+      date_from=?, date_to=?, sort=-revenue) -> make_chart(kind=ranked_bar) or make_table
+    guard: >
+      the NULL agent group is customers with NO agent assigned — present it as "(no agent)"
+      and keep it in totals (it is usually large: house accounts). Order counts by agent run
+      on topic=sales_orders with the same agent dim.
+
+  - ask: "which customers are DECLINING / negative YoY / dropped the most [BU] [window]"
+    plan: >
+      run_semantic_query(measures=[revenue], group_by=[order_partner], team_id=?, date_from=?,
+      date_to=?, limit=1000) -> transform_result([{op: yoy}, {op: sort, by: revenue_delta,
+      direction: asc}, {op: head, n: 20}]) -> make_table(columns=[order_partner, revenue,
+      revenue_ly, revenue_delta, revenue_yoy_pct])
+    guard: >
+      YoY per customer comes ONLY from the yoy transform (adds revenue_ly, revenue_delta,
+      revenue_yoy_pct per row) — never join two queries by hand. sort revenue_delta asc + head
+      = biggest $ decline first. yoy needs explicit date_from/date_to on the source query.
+
+  - ask: "export to Excel / send me a spreadsheet / CSV"
+    plan: >
+      run_semantic_query(...) -> make_table(result_id, title=?) — then tell the user: the table
+      below has a 'Download CSV (opens in Excel)' button under it
+    guard: >
+      you cannot SEND files or email; the platform renders a download button under every chart's
+      data expander and every table. Never claim to have sent anything.
+
+  - ask: "map my customers / where are my [top] customers [by revenue]"
+    plan: >
+      run_semantic_query(topic=sales_lines, measures=[revenue], group_by=[order_partner],
+      sort=-revenue, limit=20..100) -> make_chart(kind=map, x=order_partner, y=revenue)
+    guard: >
+      the platform places each customer at its geocoded address, dot size = the measure; rows
+      without a geocoded address are skipped and counted on screen — no need to fetch
+      coordinates yourself
+
+  - ask: "compare this year to last year [monthly] [BU]"
+    plan: >
+      run_semantic_query(... grain=month, window=this year) + run_semantic_query(... window=last
+      year shifted) -> make_chart(kind=line, two series: this year, last year)
+
+  - ask: "which customer/product values are valid? (before filtering by name)"
+    plan: >
+      get_field_values(topic=sales_lines, field=order_partner|product, search=?) — resolve the
+      user's spelling to the real record BEFORE querying ('NYC Florist' vs the actual name)
+    guard: "never filter on a free-typed name; always resolve via get_field_values first"
+
+  - ask: "save this as a dashboard / add to my dashboard"
+    plan: >
+      save_view(each query above, name=?) -> compose_dashboard(views=[...], name=?)
+    guard: >
+      pass save_view the EXACT object make_chart/make_kpi_card returned (it carries the query —
+      saved views RE-RUN live; a spec without its query is rejected). After compose_dashboard,
+      tell the user the dashboard is now in the sidebar Workflows menu as 'Saved · <name>'
+      and stays current (every open re-runs the queries).
+
+  - ask: "change/edit that view or workbook — different window, add a breakdown, rename, reorder"
+    plan: >
+      list_workspace() to find the exact name -> update_view(name, changes={title?/kind?/x?/y?/
+      series?, query: {date_from?/date_to?/group_by?/grain?/filters?/limit?/...}}) for a view |
+      update_workbook(name, views=[new order], new_name=?) for a workbook (dashboard)
+    guard: >
+      UPDATE tools modify existing objects — state exactly what will change and confirm first;
+      update_view re-runs the patched query before saving, so report its row_count back. To
+      REMOVE a query key (e.g. drop a group_by), pass it as null.
+
+  - ask: "delete that view/dashboard/alert/report"
+    plan: "list_workspace() to resolve the exact kind+name -> delete_object(kind, name)"
+    guard: >
+      DESTRUCTIVE — never call delete_object unless the user explicitly confirmed THE NAMED
+      object in this conversation; deleting a view also removes it from workbooks that use it
+
+  - ask: "what dashboards/views/alerts do I have? / reuse that template"
+    plan: >
+      list_workspace() -> answer from the objects list; to reuse a template:
+      instantiate_template(filename, new_name=?) — it stamps NEW objects, never overwrites
+    guard: >
+      instantiate_template is an ARTIFACT tool — confirm with the user first; afterwards point
+      them to the new dashboard in the sidebar Workflows menu ('Saved · <name>')
+
+  - ask: "send me this every [Monday|month-start] / watch this KPI / alert me about X"
+    plan: >
+      (retired 2026-07-23 with the Routines module) say scheduled reports and KPI alerts are not
+      offered right now; offer the live alternative — save the view/dashboard so it re-runs
+      fresh on every open, and answer the underlying question NOW with run_semantic_query
+    guard: "never claim a schedule or alert was created; the schedule_report/create_alert/schedule_insight tools no longer exist"
+
+context: >
+  All recipes inherit the sales_lines topic scope (confirmed wholesale orders, untaxed amounts,
+  Amazon/GIFTWARE excluded, BUs strictly isolated — see the topic's ai_context). Order COUNTS come
+  from the sales_orders topic (order grain). Every number answered must link its drill-down rows;
+  if a query returns something that cannot be drilled, say so instead of presenting it.

platform/model/topics/credit_notes.yml

@@ -1,48 +1,48 @@
-# Topic: credit_notes — posted customer CREDIT NOTES (returns), at document grain.
-#
-# Why its own topic rather than a filtered measure on a shared one: a FILTERED measure
-# (`store_filter_sql`) exists only on the store path, and `semantic.metric()` resolves a sum by
-# handing the metric's `field` to `O.sum_field(entity, domain, field)` with no room for a
-# per-measure filter. A metric that can be computed on one path and not the other cannot be
-# parity-checked — and parity is the admission bar for filtering on it. Two topics with two
-# DOMAINS give both paths the same scope by construction.
-key: credit_notes
-label: Customer credit notes (returns)
-entity: account.move
-domain_builder: credit_note_domain
-
-scope:
-  documents: "posted customer credit notes only (move_type = out_refund, state = posted)"
-  channels: >-
-    COMPANY-LEVEL. Credit notes carry team_id = 1 for everything, so a business-unit filter on
-    the document is meaningless — modules/returns.py says the same and attributes by the
-    CUSTOMER instead. A BU-scoped caller is refused rather than given a company number wearing
-    their name.
-  excluded: >-
-    Nothing. modules/returns.py — the number the business already reads — does not exclude the
-    GIFTWARE DEALS partner the wholesale sales topics do. Matching it keeps one definition of
-    "returns"; the customer-grid pool is wholesale anyway, so the intersection makes the
-    difference unobservable there.
-  basis: "untaxed document amounts (amount_untaxed_signed, NEGATED — see the metric)"
-  date_field: "invoice_date"
-
-grain: "one row per posted credit note; time-filterable by invoice_date"
-
-store:
-  table: account_move
-  alias: m
-  join: "LEFT JOIN res_partner rp ON rp.id = m.partner_id"
-  date_col: "m.invoice_date"
-  scope_sql: "m.state = 'posted' AND m.move_type = 'out_refund'"
-  dims:
-    partner: {col: "m.partner_id", name_col: "m.partner_name", label: "Customer"}
-
-ai_context: >
-  Posted customer credit notes — refunds/returns. ⚠ `amount_untaxed_signed` is NEGATIVE on a
-  credit note (verified on the tenant store 2026-07-27: all 3,006 posted refunds are negative,
-  summing to -358,141.70), so the `returns` metric declares `negate: true` and reports a POSITIVE
-  amount. A returns figure that comes out negative means the negation was lost, and it will read
-  as "we have no returns" rather than as an error. This topic is COMPANY-LEVEL: credit notes are
-  not business-unit tagged, so never present a returns number as belonging to Fisch or Royal.
-  Odoo has no return-REASON field, so concentration (which customers, which SKUs) is the only
-  diagnostic available.
+# Topic: credit_notes — posted customer CREDIT NOTES (returns), at document grain.
+#
+# Why its own topic rather than a filtered measure on a shared one: a FILTERED measure
+# (`store_filter_sql`) exists only on the store path, and `semantic.metric()` resolves a sum by
+# handing the metric's `field` to `O.sum_field(entity, domain, field)` with no room for a
+# per-measure filter. A metric that can be computed on one path and not the other cannot be
+# parity-checked — and parity is the admission bar for filtering on it. Two topics with two
+# DOMAINS give both paths the same scope by construction.
+key: credit_notes
+label: Customer credit notes (returns)
+entity: account.move
+domain_builder: credit_note_domain
+
+scope:
+  documents: "posted customer credit notes only (move_type = out_refund, state = posted)"
+  channels: >-
+    COMPANY-LEVEL. Credit notes carry team_id = 1 for everything, so a business-unit filter on
+    the document is meaningless — modules/returns.py says the same and attributes by the
+    CUSTOMER instead. A BU-scoped caller is refused rather than given a company number wearing
+    their name.
+  excluded: >-
+    Nothing. modules/returns.py — the number the business already reads — does not exclude the
+    GIFTWARE DEALS partner the wholesale sales topics do. Matching it keeps one definition of
+    "returns"; the customer-grid pool is wholesale anyway, so the intersection makes the
+    difference unobservable there.
+  basis: "untaxed document amounts (amount_untaxed_signed, NEGATED — see the metric)"
+  date_field: "invoice_date"
+
+grain: "one row per posted credit note; time-filterable by invoice_date"
+
+store:
+  table: account_move
+  alias: m
+  join: "LEFT JOIN res_partner rp ON rp.id = m.partner_id"
+  date_col: "m.invoice_date"
+  scope_sql: "m.state = 'posted' AND m.move_type = 'out_refund'"
+  dims:
+    partner: {col: "m.partner_id", name_col: "m.partner_name", label: "Customer"}
+
+ai_context: >
+  Posted customer credit notes — refunds/returns. ⚠ `amount_untaxed_signed` is NEGATIVE on a
+  credit note (verified on the tenant store 2026-07-27: all 3,006 posted refunds are negative,
+  summing to -358,141.70), so the `returns` metric declares `negate: true` and reports a POSITIVE
+  amount. A returns figure that comes out negative means the negation was lost, and it will read
+  as "we have no returns" rather than as an error. This topic is COMPANY-LEVEL: credit notes are
+  not business-unit tagged, so never present a returns number as belonging to Fisch or Royal.
+  Odoo has no return-REASON field, so concentration (which customers, which SKUs) is the only
+  diagnostic available.

platform/modules/customer_data.py

@@ -1,684 +1,684 @@
-"""Customer List — build, filter and save customer lists (replaces My Day, owner IA 2026-07-23).
-
-The page is a customer-list WORKBENCH in two parts:
-  1. BUILDER — the whole scoped book, one row per customer with a consistent metric surface
-     (YTD / LY revenue, at-risk $, cadence, overdue days, estimated missed $ …): filter, sort,
-     SELECT customers and add them to a list.
-  2. LISTS — saved lists whose membership is a visible, editable FORMULA (a rule set over the
-     metric columns) plus hand-picked members. 'Call list' and 'Win-back' ship as TEMPLATES —
-     the exact formulas the old My Day queues used — and the user can change or reset them.
-
-Composes already-validated customers-module functions; no separate validate() — the page's
-counts derive FROM the lists it renders (rule 8b). Persistence: HF store key 'customer_lists'
-({username: {list_name: {rules, sort, members, note}}}); templates are virtual until edited.
-
-The user↔agent link (users.py 'agent' field) scopes the pool to that agent's book; users with
-no link (owner/CFO/admin) see the whole book.
-"""
-import core.odoo as O
-import core.periods as P
-import core.store as store
-import core.table_store as table_store
-import modules.ar as ar
-import modules.customers as cust
-import modules.map as map_mod
-import modules.sales as S
-
-LIMIT = 500          # honest builder display cap — always shown with the full count, never silent
-KEY = 'customer_lists'
-TABLE_KEY = 'customer_table_workspace'
-
-# ------------------------------------------------------------------ the metric pool
-# Field metadata for the rule builder: key -> (label, kind). 'num' fields take >=/<=/>/</=,
-# 'text' fields take contains/=. Every field is a column of pool() rows.
-FIELDS = {
-    'customer':         ('Customer', 'text'),
-    'status':           ('Status', 'text'),
-    'agent':            ('Agent', 'text'),
-    'city':             ('City', 'text'),
-    'state':            ('State', 'text'),
-    'revenue_ytd':      ('YTD $', 'num'),
-    'revenue_ly':       ('LY (same period) $', 'num'),
-    'yoy_pct':          ('YoY %', 'num'),
-    'at_risk':          ('At risk $', 'num'),
-    'ltm_rev':          ('LTM $', 'num'),
-    'orders_24m':       ('Orders (24M)', 'num'),
-    'aov':              ('Avg order $', 'num'),
-    'days_since':       ('Days since last order', 'num'),
-    'typical_gap_days': ('Typical gap (days)', 'num'),
-    'overdue_days':     ('Overdue vs cadence (days)', 'num'),
-    'est_missed':       ('Est. missed $', 'num'),
-}
-NUM_OPS = ('>=', '<=', '>', '<', '=')
-TEXT_OPS = ('contains', '=')
-
-
-def agent_pids(agent_name):
-    """Partner ids of an agent's book (None = unscoped/whole book)."""
-    return cust.agent_partner_ids(agent_name) if agent_name else None
-
-
-#: Wave 17 R2 — `ar` bucket label -> the grid's column key. ONE mapping, read by the attribute
-#: builder, the empty-row default and validate(), so a bucket cannot exist under two spellings.
-AR_BUCKET_FIELDS = {'1-30': 'ar_aged_1_30', '31-60': 'ar_aged_31_60',
-                    '61-90': 'ar_aged_61_90', '90+': 'ar_aged_90_plus'}
-
-
-def _ar_attrs(t=None):
-    """{pid: {ar_open, ar_overdue, ar_outstanding, ar_exposure}} — the AR family.
-
-    Wave 21 R1: `ar_open` is the NOT-YET-DUE half of a disjoint split (label "AR current $" —
-    key kept so saved views keep working); `ar_outstanding` is the total (current + overdue),
-    which is what "open AR" means everywhere else.
-
-    Composed from `modules/ar.credit_exposure()`, NOT re-derived: it is already reconciled to
-    Odoo by `ar.validate()`, so the Customer table and the Collections page cannot disagree about
-    what a customer owes. Read from the UNFILTERED `_all_rows` — `rows` is a display-truncated
-    top-40, and a column built off that would silently blank everybody else.
-
-    ⚠ `credit_limit` is deliberately NOT a column: 20 of 1,548 customers have one. EXPOSURE is
-    the number that answers "how much are we out on this customer", and it needs no limit.
-
-    ⚠ `days_to_pay` is NOT COMPUTED here — it is READ from a nightly snapshot. MEASURED
-    2026-07-27: `ar.credit_exposure()` costs 9s; `ar.days_to_pay()` costs **301s**, because
-    settlement date means walking three years of reconciled receivable lines and their
-    full-reconcile groups. Computing it in `pool()` would add five minutes to every Customer-table
-    build and every Space container start; computing it LAZILY would just move those five minutes
-    onto whoever opened the page first. So the expensive half runs on the app's existing
-    background store-sync thread (`ar.refresh_days_to_pay_snapshot`) and this reads the answer
-    out of the store for nothing. A missing snapshot yields a blank column, never a slow page.
-    """
-    out = {}
-    try:
-        exp = ar.credit_exposure(t)
-        for r in exp.get('_all_rows') or []:
-            out[r['pid']] = {
-                'ar_open': r.get('open', 0.0) or 0.0,
-                'ar_overdue': r.get('overdue', 0.0) or 0.0,
-                # Wave 21 R1 — the TOTAL owed. Sum of the two halves ar.credit_exposure already
-                # reconciles to Odoo's residual read_group (ar.py validate), so no second oracle.
-                'ar_outstanding': (r.get('open', 0.0) or 0.0) + (r.get('overdue', 0.0) or 0.0),
-                'ar_exposure': r.get('exposure', 0.0) or 0.0,
-                # Wave 17 R2 — the aging split, so a saved VIEW can be the collections
-                # worklist. Keys mirror `ar.OVERDUE_BUCKETS` through AR_BUCKET_FIELDS; the four
-                # sum EXACTLY to `ar_overdue` (gated in validate()).
-                **{k: r.get(f'aged_{b}', 0.0) or 0.0
-                   for b, k in AR_BUCKET_FIELDS.items()},
-            }
-    except Exception:
-        pass
-    for pid, avg in ar.days_to_pay_snapshot().items():
-        # A customer with an AR row but no settled invoice in the window keeps `None` — blank,
-        # not 0. "Pays in 0 days" is a claim, and a false one.
-        out.setdefault(pid, {})['days_to_pay'] = avg
-    return out
-
-
-def _mix_attrs(pids=None, t=None):
-    """{pid: {top_category, sku_count, top_sku, top_category_pct}} — the product-mix family.
-
-    ONE read_group over sale.order.line by (partner, product) across the LTM window, then the
-    product->category map, then aggregation in Python. Line grain is the only grain that can
-    answer "what does this customer buy", and it is deliberately ALL-CHANNEL scope-wise for the
-    same reason inventory analysis is (see [[ri-channel-scope-amazon]]): a customer's product mix
-    is a fact about the customer, not about a sales team.
-
-    `top_category_pct` is that category's share of the customer's LTM line revenue — the number
-    that says whether "top" means dominant or merely first.
-
-    ⚠ There is NO `team_id` parameter, and its absence is the point rather than an omission: for
-    a BU-scoped viewer the revenue columns beside this one ARE team-scoped while these are not,
-    so "top category" can name products bought through a channel that viewer's revenue figures
-    exclude. That is the same trade the inventory modules make, and it is the right one — a
-    customer's product mix is a fact about the customer.
-    """
-    t = t or P.today()
-    mf, mt = P.ltm(t)
-    # ⚠ `pids` NARROWS THE RESULT, NEVER THE DOMAIN — and that is not a style choice. Putting
-    # the caller's ~1,500 partner ids into an `in` clause on a LINE-grain read_group makes Odoo
-    # answer **502 Bad Gateway**; the same query unfiltered returns in 22s. Measured 2026-07-27,
-    # after the filtered form took the live Customer page past 20 MINUTES without rendering.
-    # The grouped result is per-partner anyway, so dropping the extras in Python costs nothing.
-    dom = [('order_id.state', 'in', ['sale', 'done']),
-           ('order_id.date_order', '>=', str(mf)), ('order_id.date_order', '<=', str(mt))]
-    keep = set(pids) if pids else None
-    rows = O.read_group('sale.order.line', dom, ['price_subtotal:sum'],
-                        ['order_partner_id', 'product_id'], lazy=False)
-    prod_ids = {O.m2o_id(r.get('product_id')) for r in rows if r.get('product_id')}
-    prod_ids.discard(None)
-    cats = {}
-    plist = list(prod_ids)
-    for i in range(0, len(plist), 5000):
-        for p in O.search_read('product.product', [('id', 'in', plist[i:i + 5000])], ['categ_id']):
-            # `categ_id`'s display name is the full PATH ("All / Foams & Finishes / Styrofoam").
-            # The column takes the LEAF, because a column and a group label have to be readable —
-            # and the path's own root ("All") carries no information. ⚠ Two categories that share
-            # a leaf name would merge in a group-by; measured against this catalogue that does not
-            # happen, and readability is worth more than defending against a rename.
-            full = O.m2o_name(p.get('categ_id')) or ''
-            cats[p['id']] = (full.split(' / ')[-1].strip() or '(none)') if full else '(none)'
-
-    per = {}
-    for r in rows:
-        pid = O.m2o_id(r.get('order_partner_id'))
-        prod = O.m2o_id(r.get('product_id'))
-        if pid is None or prod is None or (keep is not None and pid not in keep):
-            continue
-        val = r.get('price_subtotal', 0.0) or 0.0
-        e = per.setdefault(pid, {'skus': set(), 'by_cat': {}, 'by_sku': {}, 'total': 0.0})
-        e['skus'].add(prod)
-        e['by_cat'][cats.get(prod, '(none)')] = e['by_cat'].get(cats.get(prod, '(none)'), 0.0) + val
-        e['by_sku'][prod] = e['by_sku'].get(prod, 0.0) + val
-        e['total'] += val
-
-    top_prod_ids = {max(e['by_sku'], key=e['by_sku'].get) for e in per.values() if e['by_sku']}
-    names = {}
-    tlist = list(top_prod_ids)
-    for i in range(0, len(tlist), 5000):
-        for p in O.search_read('product.product', [('id', 'in', tlist[i:i + 5000])], ['name']):
-            names[p['id']] = p.get('name') or ''
-
-    out = {}
-    for pid, e in per.items():
-        cat = max(e['by_cat'], key=e['by_cat'].get) if e['by_cat'] else '(none)'
-        sku = max(e['by_sku'], key=e['by_sku'].get) if e['by_sku'] else None
-        out[pid] = {
-            'top_category': cat,
-            'top_category_pct': (e['by_cat'][cat] / e['total']) if e['total'] else None,
-            'sku_count': len(e['skus']),
-            'top_sku': names.get(sku, '(none)') if sku is not None else '(none)',
-        }
-    return out
-
-
-def _salesperson_attrs(pids=None, t=None):
-    """{pid: salesperson} — the DOMINANT order-taker over LTM, by order count.
-
-    ⚠ Salesperson is NOT the Agent, and they are not interchangeable (owner, 2026-07-27):
-    the SALESPERSON is whoever entered and took the order, the AGENT is the person the customer
-    is assigned to and who earns the commission — including when the customer orders through the
-    office and somebody else keys it in. So this reads `sale.order.user_id` (the ORDER's taker,
-    fully populated: 20 people over $6.2M LTM) and NOT `res.partner.user_id`, which is a
-    different, near-empty field.
-
-    A customer can have several over a year, so the column takes the one who took the MOST of
-    their orders — a single value the table can group and filter cleanly. Ties break toward the
-    larger revenue.
-    """
-    t = t or P.today()
-    mf, mt = P.ltm(t)
-    # Same rule as `_mix_attrs`: the pid list narrows the RESULT, not the domain. Order grain is
-    # far smaller than line grain so this one never actually 502'd, but a caller's id list has no
-    # business being pushed into a query whose grouping already answers per partner.
-    keep = set(pids) if pids else None
-    dom = S.order_domain(str(mf), str(mt), None)
-    rows = O.read_group('sale.order', dom, ['amount_untaxed:sum'],
-                        ['partner_id', 'user_id'], lazy=False)
-    per = {}
-    for r in rows:
-        pid = O.m2o_id(r.get('partner_id'))
-        if pid is None or (keep is not None and pid not in keep):
-            continue
-        who = O.m2o_name(r.get('user_id')) or '(none)'
-        n, rev = r.get('__count', 0) or 0, r.get('amount_untaxed', 0.0) or 0.0
-        cur = per.get(pid)
-        if cur is None or (n, rev) > (cur[1], cur[2]):
-            per[pid] = (who, n, rev)
-    return {pid: v[0] for pid, v in per.items()}
-
-
-def pool(agent_name=None, team_id=None):
-    """One row per customer across the scoped book: the union of YTD buyers, same-period-LY
-    buyers and anyone with an order in the 24-month cadence window — so lapsed/win-back
-    accounts are in the pool, not just YTD actives. Reuses the customers module's validated
-    building blocks (_cust_rev / _cadence_bulk / _partner_attrs) so every metric matches the
-    Customers page definitions; est_missed is the Call-list formula (min(cycles missed, 3) × AOV)."""
-    return _pool_build(agent_name, team_id, limit=None)['rows']
-
-
-def pool_first(agent_name=None, team_id=None, limit=100):
-    """Wave-7 W1 (C1 as amended): the cold-load FAST SLICE — the pool's first `limit` rows in
-    its own default order + the true total, built from the CHEAP families only (revenue ×3,
-    cadence, status, est_missed, partner attributes ≈ 12s measured). The AR / product-mix /
-    salesperson / coords columns stay BLANK until the full build swaps in: `_mix_attrs` alone
-    is a whole-book 20s read_group whose domain must never be pid-narrowed (502 — see its
-    docstring), so "all columns on 100 rows" measured 44.6s vs 45.1s full — no win. A partial
-    payload is a UI PHASE, never a reporting basis — validate() reconciles the full pool only."""
-    return _pool_build(agent_name, team_id, limit=limit, fast=True)
-
-
-def _dba_attrs(pids, t):
-    """{pid: 'Fisch' | 'Royal' | 'Both'} — which brand(s) a customer's confirmed orders carry
-    over the pool's own 24-month universe (C-DBA, wave 2026-08-02).
-
-    GIFTWARE DEALS (the Amazon channel) is deliberately NOT a DBA — a customer buying only
-    through it stays blank here, exactly as ARCHITECTURE.md §4's wholesale scope treats that
-    team. Blank also covers the ledger-retained customers whose activity predates the window:
-    blank means "no brand attributable in 24 months", never a guess. One read_group, grouped
-    (partner, team); degrades to {} like the other attr families — a blank column beats a
-    page that cannot render.
-    """
-    try:
-        import datetime as _dt
-        d_from = (_dt.date.fromisoformat(str(t)) - _dt.timedelta(days=731)).isoformat()
-        pairs = O.read_group(
-            'sale.order',
-            [('state', 'in', ('sale', 'done')), ('date_order', '>=', d_from),
-             ('partner_id', 'in', list(pids)), ('team_id', 'in', (5, 6))],
-            ['partner_id'], ['partner_id', 'team_id'], lazy=False)
-        teams = {}
-        for r in pairs:
-            pid = O.m2o_id(r.get('partner_id'))
-            tid = O.m2o_id(r.get('team_id'))
-            if pid and tid in (5, 6):
-                teams.setdefault(pid, set()).add(tid)
-        label = {5: 'Fisch', 6: 'Royal'}
-        return {pid: ('Both' if len(ts) == 2 else label[next(iter(ts))])
-                for pid, ts in teams.items()}
-    except Exception:
-        return {}
-
-
-def _book_pids(team_id=None, agent_pids=None):
-    """⭐ WAVE 20 (owner items 8 + 27, ruling R3) — THE WHOLE BOOK, not just who bought recently.
-
-    Owner: *"Martin Pasternak showing only 313 accounts when I filter agent, whereas in Odoo it is
-    494 … I want our App to show complete source of truth, even if no sale.order at all or not.
-    Its important to see what customer is getting assigned to Martin or whether we can retarget
-    them."* The pool was a 24-MONTH SALES universe (YTD ∪ LY-YTD ∪ cadence-window buyers), so a
-    customer assigned to an agent who has never ordered — precisely a retargeting target — did not
-    exist in the app at all.
-
-    R3's definition, MEASURED against live Odoo 2026-08-05:
-        customer_rank>0 active .............. 3,614
-        ever ordered (confirmed, team 5/6) ...  1,748
-        UNION ............................... 3,723   (vs 1,555 in the old 24-month pool)
-    Martin's book under this rule is **494** — the owner's Odoo number, to the account.
-
-    ⛔ **THE "agent-assigned" LEG OF R3 IS DELIBERATELY NOT A THIRD TERM, and that is a
-    measurement, not a shortcut.** Taken literally it added 174 partners and pushed Martin to 503;
-    every one of the 9 extras on his book was an ODOO ADDRESS RECORD rather than an account —
-    `type` in (`delivery`, `other`), most carrying a `parent_id`, and TWO with `name: False`.
-    Shipping them would have put nameless rows in the customer table and made "how many customers
-    does Martin have" answer 503 against an Odoo screen that says 494.
-    Excluding address types wholesale is also wrong (`type not in (delivery, invoice, other,
-    private)` measured **488** — it drops 6 genuine accounts that happen to carry a delivery
-    type). `customer_rank > 0` is the predicate that means "this partner is a customer record",
-    it reproduces the owner's number exactly, and every agent-assigned ACCOUNT already satisfies
-    it — so the leg is subsumed rather than dropped. Item 27's actual ask (the 126 assigned
-    partners with no `sale.order` at all) is fully served: they are rank>0 and they are in.
-
-    ⚠ ACTIVE ONLY. Archived partners stay out (R3): they are ex-customers, and putting them in
-    every count would make "how many customers do we have" unanswerable. The agent-LOGIN scope
-    (`customers.agent_partner_ids`) deliberately still includes archived — an agent's own book is
-    their whole history — and the two remain compatible because that set is INTERSECTED with this
-    pool, so archived rows drop out of the table without narrowing the agent's own permissions.
-
-    ⚠ BU SCOPE IS APPLIED THROUGH ORDERS, NOT THROUGH THE PARTNER. `res.partner` carries no team,
-    so a BU-scoped caller gets the partners who have ORDERED in that BU (plus their own agent
-    book). Widening it to every partner for a scoped user would cross the BU isolation rule that
-    the whole permissioning model rests on.
-    """
-    try:
-        if team_id:
-            # Scoped: partners with confirmed orders in THIS BU, ever. `read_group` on partner_id
-            # rather than a search_read of orders — the group is the distinct set, and it is one
-            # round trip instead of paging tens of thousands of order rows.
-            rows = O.read_group('sale.order',
-                                [('state', 'in', ('sale', 'done')), ('team_id', '=', team_id)],
-                                ['partner_id'], ['partner_id'], lazy=False)
-            book = {O.m2o_id(r.get('partner_id')) for r in rows}
-            book.discard(None)
-        else:
-            rank = O.search_read('res.partner',
-                                 [('customer_rank', '>', 0), ('active', '=', True)],
-                                 ['id'], limit=200000)
-            # `ever` is NOT redundant with rank>0: a partner can be archived-then-reactivated, or
-            # have had its rank reset, and an account that demonstrably bought from us belongs in
-            # the book whatever its flags say now. An ORDER is a fact; a rank is a setting.
-            rows = O.read_group('sale.order',
-                                [('state', 'in', ('sale', 'done')), ('team_id', 'in', (5, 6))],
-                                ['partner_id'], ['partner_id'], lazy=False)
-            ever = {O.m2o_id(r.get('partner_id')) for r in rows}
-            ever.discard(None)
-            book = {r['id'] for r in rank} | ever
-        # An agent filter NARROWS the book to that agent's partners — never widens it. The
-        # intersection is what keeps an agent-login user inside their own book while still
-        # gaining every no-order account assigned to them, which is the whole point of item 27.
-        return (book & set(agent_pids)) if agent_pids is not None else book
-    except Exception as e:
-        # Degrade to the sales-derived universe rather than failing the page — but LOUDLY.
-        #
-        # ⛔ THIS DEGRADATION IS NOT LIKE THE OTHERS IN THIS MODULE, and the difference is what
-        # makes silence wrong here. Every other family (`_ar_attrs`, `_mix_attrs`, …) degrades to
-        # a blank COLUMN, which is visible: the user sees an empty column and asks why. This one
-        # degrades to absent ROWS. The pool still builds from the sales legs, so the page renders
-        # perfectly, the counts look plausible, and Martin is quietly back at 313 with nothing
-        # anywhere saying the book leg failed. An invisible degradation of a COUNT is the failure
-        # mode this codebase keeps writing rules against ([[no-unverifiable-aggregates]]).
-        try:
-            import harness.telemetry as _tel
-            _tel.error('customer_data:_book_pids', e, fallback='sales-derived pool only')
-        except Exception:
-            pass
-        print(f"[aios] WARNING customer_data._book_pids failed ({type(e).__name__}: {e}) - the "
-              f"customer pool is falling back to the 24-month SALES universe, so accounts with "
-              f"no recent orders (owner item 27) are MISSING from this build.")
-        return set()
-
-
-def _pool_build(agent_name, team_id, limit, fast=False):
-    t = P.today()
-    yf, yt = P.ytd(t)
-    lf, lt = P.ytd_last_year(t)
-    mf, mt = P.ltm(t)
-    pids = agent_pids(agent_name)
-    this = cust._cust_rev(yf, yt, team_id, pids)
-    last = cust._cust_rev(lf, lt, team_id, pids)
-    ltm = cust._cust_rev(mf, mt, team_id, pids)
-    cad = cust._cadence_bulk(t, team_id, agent_pids=pids)
-    all_pids = set(this) | set(last) | set(cad) | _book_pids(team_id, pids)
-    total = len(all_pids)
-    if limit is not None and total > limit:
-        # the SAME ordering the assembled pool ships (see the sort below) — the slice must be
-        # the first page of the very list the full build renders, or the swap-in reshuffles.
-        ranked = sorted(all_pids,
-                        key=lambda p: -((this.get(p) or {}).get('rev', 0.0)
-                                        + (last.get(p) or {}).get('rev', 0.0)))
-        all_pids = set(ranked[:limit])
-    attrs = cust._partner_attrs(list(all_pids))
-    if fast:
-        # C1 fast phase: the slow families stay empty — their columns render blank behind the
-        # toolbar's partial indicator until the full build swaps in.
-        ar_a, mix_a, sp_a, geo_a, dba_a = {}, {}, {}, {}, {}
-    else:
-        # The three families the owner asked for (2026-07-27). Each degrades to {} rather than
-        # raising: a customer table that cannot render because AR is momentarily unreachable is
-        # a worse failure than one with a blank column.
-        ar_a = _ar_attrs(t)
-        mix_a = _mix_attrs(all_pids, t)
-        sp_a = _salesperson_attrs(all_pids, t)
-        # W11 (wave-7): coordinates for the Map VIEW — Odoo coords else the geocode cache,
-        # read-only reuse (coords_for never geocodes); missing → null lat/lon, and the
-        # client's map view discloses the count.
-        geo_a = map_mod.coords_for(list(all_pids))
-        # C-DBA (2026-08-02): the brand attribute rides the full build only, like the rest.
-        dba_a = _dba_attrs(all_pids, t)
-    # customers whose only activity sits in the older half of the 24-month cadence window
-    # appear in no revenue map — fetch their names directly (else the lapsed cohort, exactly
-    # the win-back targets this union exists for, would render as '?')
-    unnamed = [pid for pid in all_pids
-               if not ((this.get(pid) or {}).get('name') or (last.get(pid) or {}).get('name')
-                       or (ltm.get(pid) or {}).get('name'))]
-    extra_names = ({r['id']: r['name'] for r in
-                    O.search_read('res.partner', [('id', 'in', unnamed)], ['name'])}
-                   if unnamed else {})
-    rows = []
-    for pid in all_pids:
-        tv = this.get(pid) or {}
-        lv = last.get(pid) or {}
-        c = cad.get(pid) or {}
-        rev, ly = tv.get('rev', 0.0), lv.get('rev', 0.0)
-        gap = c.get('typical_gap_days')
-        overdue = c.get('overdue_days')
-        aov = c.get('aov', 0.0)
-        est = (min(overdue / gap, 3.0) * aov) if (gap and overdue and overdue > 0) else 0.0
-        status = ('New' if rev > 0 and ly <= 0 else
-                  'Lost' if ly > 0 and rev <= 0 else
-                  'Declining' if 0 < rev < ly else
-                  'Growing' if rev > 0 else 'Dormant')
-        a = attrs.get(pid) or {}
-        rows.append({
-            'pid': pid,
-            'customer': tv.get('name') or lv.get('name')
-                        or (ltm.get(pid) or {}).get('name') or extra_names.get(pid) or '?',
-            'status': status,
-            'agent': a.get('agent', '(none)'), 'city': a.get('city', '(none)'),
-            # C-DBA: blank (not '(none)') — a select's blank is its own honest empty state.
-            'dba': dba_a.get(pid, ''),
-            'state': a.get('state', '(none)'),
-            # Owner 2026-07-27, the partner-attribute family. `.get(..., default)` is not
-            # defensive habit here: search_read returned 1,548 of 1,550 pool pids — two partners
-            # in the sales history are archived or deleted — so a customer with NO attrs row is
-            # a real case, and it must render as '(none)' rather than KeyError the whole page.
-            'country': a.get('country', '(none)'), 'zip': a.get('zip', '(none)'),
-            'payment_terms': a.get('payment_terms', '(none)'),
-            'customer_since': a.get('customer_since', ''),
-            # Row-level datum for the `created_time` field type (wave-5 item 11) — rides every
-            # row like pid, no column of its own until a user creates one.
-            '_created': a.get('created_at', ''),
-            'tags': a.get('tags', '(none)'), 'pricelist': a.get('pricelist', '(none)'),
-            # AR / credit exposure — composed from the already-reconciled ar.py blocks, so the
-            # Customer table and the Collections page cannot disagree.
-            'ar_open': (ar_a.get(pid) or {}).get('ar_open', 0.0),
-            'ar_overdue': (ar_a.get(pid) or {}).get('ar_overdue', 0.0),
-            'ar_outstanding': (ar_a.get(pid) or {}).get('ar_outstanding', 0.0),
-            'ar_exposure': (ar_a.get(pid) or {}).get('ar_exposure', 0.0),
-            'days_to_pay': (ar_a.get(pid) or {}).get('days_to_pay'),
-            **{k: (ar_a.get(pid) or {}).get(k, 0.0) for k in AR_BUCKET_FIELDS.values()},
-            # Product mix, LTM, line grain, ALL-channel.
-            'top_category': (mix_a.get(pid) or {}).get('top_category', '(none)'),
-            'top_category_pct': (mix_a.get(pid) or {}).get('top_category_pct'),
-            'sku_count': (mix_a.get(pid) or {}).get('sku_count', 0),
-            'top_sku': (mix_a.get(pid) or {}).get('top_sku', '(none)'),
-            # The ORDER-TAKER, not the agent. Different people, different questions.
-            'salesperson': sp_a.get(pid, '(none)'),
-            # W11: nullable — the Map view pins what it can and counts what it cannot.
-            'lat': (geo_a.get(pid) or {}).get('lat'),
-            'lon': (geo_a.get(pid) or {}).get('lon'),
-            'revenue_ytd': rev, 'revenue_ly': ly,
-            'yoy_pct': P.yoy_pct(rev, ly),
-            'at_risk': max(ly - rev, 0.0),
-            'ltm_rev': (ltm.get(pid) or {}).get('rev', 0.0),
-            'orders_24m': c.get('n_orders', 0), 'aov': aov,
-            'last_order': c.get('last_order', ''),
-            'days_since': c.get('days_since'),
-            'typical_gap_days': gap, 'overdue_days': overdue,
-            'est_missed': est,
-        })
-    for r in rows:
-        r['odoo_status'] = 'Active'
-    # I13 (owner item 13, contract C6): RETAIN customers that disappear from Odoo.
-    # Only the FULL build reconciles the ledger — the fast slice is 100 rows by construction,
-    # so letting it write would mark ~1,450 living customers archived on every cold load.
-    if not fast:
-        rows, total = _reconcile_ledger(rows, total, agent_name, team_id)
-    rows.sort(key=lambda r: -(r['revenue_ytd'] + r['revenue_ly']))
-    return {'rows': rows, 'total': total}
-
-
-LEDGER_KEY = 'customer_ledger'
-
-
-def _reconcile_ledger(rows, total, agent_name, team_id):
-    """Remember every customer we have ever seen, and keep serving the ones Odoo stopped
-    returning (owner item 13: "if it is deleted, that it goes to an archived tag immediately —
-    so stored in our platform even if deleted in Odoo").
-
-    Why a ledger at all: this pool is built from SALES HISTORY, not from a partner list, so a
-    partner deleted in Odoo usually keeps appearing (their order lines remain) — until the day
-    the lines go too, when the row would silently vanish along with every note, tag and cohort
-    membership attached to it. Nothing else in the app would notice. The ledger is the only
-    record that the customer ever existed, which is why it starts recording now rather than
-    when the surfacing is finished: history you did not write down is not recoverable later.
-
-    ⚠ SCOPE-SAFE. The ledger is written ONLY from an UNSCOPED build (no agent, no BU). A scoped
-    build legitimately sees a fraction of the book, and reconciling from it would mark every
-    customer outside that scope 'Archived' for everyone — the failure would look exactly like
-    the data loss this is meant to prevent. Scoped builds READ the ledger and resurrect nothing
-    they cannot prove they should see.
-    """
-    try:
-        ledger = dict(store.get(LEDGER_KEY) or {})
-    except Exception:
-        return rows, total                  # a ledger we cannot read must not break the table
-    today = str(P.today())
-    live = {r['pid'] for r in rows}
-    unscoped = agent_name is None and team_id is None
-
-    if unscoped:
-        for r in rows:
-            e = ledger.get(str(r['pid'])) or {}
-            e.update({'name': r['customer'], 'last_seen': today})
-            e.setdefault('first_seen', today)
-            ledger[str(r['pid'])] = e
-
-    # Rows the ledger knows and this build did not return. On an unscoped build that means
-    # "gone from Odoo"; on a scoped one it usually just means "not in this agent's book", so
-    # only the unscoped build may surface them.
-    revived = []
-    if unscoped:
-        for key, e in ledger.items():
-            try:
-                pid = int(key)
-            except (TypeError, ValueError):
-                continue
-            if pid in live:
-                continue
-            revived.append({
-                'pid': pid, 'customer': e.get('name') or '?', 'status': 'Dormant',
-                'odoo_status': 'Archived',
-                # Everything else is genuinely UNKNOWN now — the record is gone. Blank is the
-                # honest rendering; carrying the last-known numbers forward would state figures
-                # as current that nothing can reconcile ([[no-unverifiable-aggregates]]).
-                'agent': '(none)', 'city': '(none)', 'state': '(none)', 'country': '(none)',
-                'zip': '(none)', 'payment_terms': '(none)', 'customer_since': '',
-                '_created': '', 'tags': '(none)', 'pricelist': '(none)',
-                'ar_open': 0.0, 'ar_overdue': 0.0, 'ar_outstanding': 0.0, 'ar_exposure': 0.0,
-                'days_to_pay': None,
-                **{k: 0.0 for k in AR_BUCKET_FIELDS.values()},
-                'top_category': '(none)', 'top_category_pct': None, 'sku_count': 0,
-                'top_sku': '(none)', 'salesperson': '(none)', 'lat': None, 'lon': None,
-                'revenue_ytd': 0.0, 'revenue_ly': 0.0, 'yoy_pct': None, 'at_risk': 0.0,
-                'ltm_rev': 0.0, 'orders_24m': 0, 'aov': 0.0, 'last_order': '',
-                'days_since': None, 'typical_gap_days': None, 'overdue_days': None,
-                'est_missed': 0.0,
-            })
-        if store.available():
-            try:
-                store.update(LEDGER_KEY, lambda cur: {**cur, **ledger}, flush='async')
-            except Exception:
-                pass                        # recording is best-effort; the table is not
-    return rows + revived, total + len(revived)
-
-
-# ------------------------------------------------------------------ the rule engine
-# A list's formula = [{'field','op','value'}, ...] over FIELDS + a 'sort' key ('-x' = desc).
-# The two templates ARE the old My Day queue formulas, expressed as visible rules.
-#
-# 'note' is a SEED, not the source of truth (owner 2026-07-25). It is what a list reads
-# BEFORE anyone edits it; the moment a user saves a description the stored one wins, and
-# an empty stored description stays empty — the template must never resurrect. That
-# precedence lives in aios_grid.views_from_defs (a saved view replaces its template-derived
-# one wholesale) and is pinned by _qa_grid_view_note.py. Edit the prose here only to change
-# what a NEW user starts with.
-TEMPLATES = {
-    'Call list': {
-        'rules': [{'field': 'orders_24m', 'op': '>=', 'value': 3},
-                  {'field': 'overdue_days', 'op': '>', 'value': 0},
-                  {'field': 'days_since', 'op': '<=', 'value': 365}],
-        'sort': '-est_missed',
-        'note': 'Customers overdue against their OWN reorder cadence (3+ orders, a real gap '
-                'pattern, ordered within 365d), ranked by estimated missed revenue.'},
-    'Win-back': {
-        'rules': [{'field': 'revenue_ly', 'op': '>=', 'value': 2000},
-                  {'field': 'at_risk', 'op': '>', 'value': 0}],
-        'sort': '-at_risk',
-        'note': 'Bought materially last year (over $2,000), down or gone this year, ranked by '
-                'dollars at risk.'},
-}
-
-
-def _match(row, rule):
-    """One rule against one row. None/missing numeric values fail every numeric comparison
-    (a customer with no cadence is never 'overdue'); text ops are case-insensitive."""
-    field, op, val = rule.get('field'), rule.get('op'), rule.get('value')
-    if field not in FIELDS:
-        return True                                   # unknown field → rule is inert, not a crash
-    v = row.get(field)
-    if FIELDS[field][1] == 'text':
-        s, q = str(v or '').lower(), str(val or '').lower()
-        return q in s if op == 'contains' else s == q
-    try:
-        v, val = float(v), float(val)
-    except (TypeError, ValueError):
-        return False
-    return {'>=': v >= val, '<=': v <= val, '>': v > val, '<': v < val,
-            '=': v == val}.get(op, False)
-
-
-def apply_rules(rows, rules, sort=None):
-    """Filter the pool through a formula (AND of all rules) and apply the list's sort."""
-    out = [r for r in rows if all(_match(r, ru) for ru in (rules or []))]
-    if sort:
-        key = sort.lstrip('-')
-        out.sort(key=lambda r: (r.get(key) is None,
-                                -(r.get(key) or 0) if sort.startswith('-') else (r.get(key) or 0))
-                 if FIELDS.get(key, ('', 'num'))[1] == 'num'
-                 else str(r.get(key) or '').lower(), reverse=False)
-    return out
-
-
-# ------------------------------------------------------------------ persistence (HF store)
-def saved_lists(username):
-    """{list_name: {'rules','sort','members','note'}} for one user ({} when none / store down)."""
-    try:
-        return (store.get(KEY) or {}).get(username, {}) or {}
-    except Exception:
-        return {}
-
-
-def save_list(username, name, definition):
-    def _up(d):
-        d.setdefault(username, {})[name] = definition
-        return d
-    store.update(KEY, _up)
-
-
-def delete_list(username, name):
-    def _up(d):
-        (d.get(username) or {}).pop(name, None)
-        return d
-    store.update(KEY, _up)
-
-
-# ------------------------------------------------------------------ Airtable-style table workspace
-# This is intentionally separate from `customer_lists`: a LIST owns membership/formula
-# semantics, while a VIEW owns presentation/query state (filters, multi-sort, grouping,
-# visible fields, widths, color, row height). List views can reference the same formula
-# without conflating the two persistence contracts.
-#
-# The store logic MOVED to core/table_store.py 2026-07-27 (the table-page factory): these
-# names are the Customer table's instance of the generic per-object workspace store, kept as
-# module functions so every existing caller (app.py's host loop, QA gates) is untouched.
-# A NEW table object gets its own `core.table_store.make('<its>_table_workspace')`.
-_TSTORE = table_store.make(TABLE_KEY)
-
-#: Wave 16 C-TOPIC — the ops OBJECT, for callers that select a table by TOPIC (grid_events'
-#: `EventCtx.table`). The module-level re-exports below stay for every existing caller.
-TABLE_OPS = _TSTORE
-
-table_workspace = _TSTORE.workspace
-shared_table_views = _TSTORE.shared_views      # wave-9 I17: views shared WITH this viewer
-shared_table_view = _TSTORE.shared_view        #   ...and one raw, for authorisation only
-save_table_view = _TSTORE.save_view
-delete_table_view = _TSTORE.delete_view
-save_table_field = _TSTORE.save_field
-delete_table_field = _TSTORE.delete_field
-duplicate_table_field = _TSTORE.duplicate_field
-patch_table_overlay = _TSTORE.patch_overlay
-save_table_folders = _TSTORE.save_folders
-save_table_active_view = _TSTORE.save_active_view   # owner item 3: last-opened view, per user
-save_table_record_layout = _TSTORE.save_record_layout  # 2026-08-02 C-LAYOUT: record-detail order
-
-
-# ------------------------------------------------------------------ digest compatibility
-def queues(agent_name=None, team_id=None, limit=200):
-    """The two canonical morning lists (call list + win-back) for the daily digest email —
-    unchanged formulas via the customers module (the digest always uses the CANONICAL templates,
-    not a user's edited copy, so every rep's email means the same thing)."""
-    pids = agent_pids(agent_name)
-    return {
-        'calls': cust.contact_recommendations(team_id=team_id, limit=limit, agent_pids=pids),
-        'risk': cust.at_risk(team_id=team_id, limit=limit, agent_pids=pids),
-    }
+"""Customer List — build, filter and save customer lists (replaces My Day, owner IA 2026-07-23).
+
+The page is a customer-list WORKBENCH in two parts:
+  1. BUILDER — the whole scoped book, one row per customer with a consistent metric surface
+     (YTD / LY revenue, at-risk $, cadence, overdue days, estimated missed $ …): filter, sort,
+     SELECT customers and add them to a list.
+  2. LISTS — saved lists whose membership is a visible, editable FORMULA (a rule set over the
+     metric columns) plus hand-picked members. 'Call list' and 'Win-back' ship as TEMPLATES —
+     the exact formulas the old My Day queues used — and the user can change or reset them.
+
+Composes already-validated customers-module functions; no separate validate() — the page's
+counts derive FROM the lists it renders (rule 8b). Persistence: HF store key 'customer_lists'
+({username: {list_name: {rules, sort, members, note}}}); templates are virtual until edited.
+
+The user↔agent link (users.py 'agent' field) scopes the pool to that agent's book; users with
+no link (owner/CFO/admin) see the whole book.
+"""
+import core.odoo as O
+import core.periods as P
+import core.store as store
+import core.table_store as table_store
+import modules.ar as ar
+import modules.customers as cust
+import modules.map as map_mod
+import modules.sales as S
+
+LIMIT = 500          # honest builder display cap — always shown with the full count, never silent
+KEY = 'customer_lists'
+TABLE_KEY = 'customer_table_workspace'
+
+# ------------------------------------------------------------------ the metric pool
+# Field metadata for the rule builder: key -> (label, kind). 'num' fields take >=/<=/>/</=,
+# 'text' fields take contains/=. Every field is a column of pool() rows.
+FIELDS = {
+    'customer':         ('Customer', 'text'),
+    'status':           ('Status', 'text'),
+    'agent':            ('Agent', 'text'),
+    'city':             ('City', 'text'),
+    'state':            ('State', 'text'),
+    'revenue_ytd':      ('YTD $', 'num'),
+    'revenue_ly':       ('LY (same period) $', 'num'),
+    'yoy_pct':          ('YoY %', 'num'),
+    'at_risk':          ('At risk $', 'num'),
+    'ltm_rev':          ('LTM $', 'num'),
+    'orders_24m':       ('Orders (24M)', 'num'),
+    'aov':              ('Avg order $', 'num'),
+    'days_since':       ('Days since last order', 'num'),
+    'typical_gap_days': ('Typical gap (days)', 'num'),
+    'overdue_days':     ('Overdue vs cadence (days)', 'num'),
+    'est_missed':       ('Est. missed $', 'num'),
+}
+NUM_OPS = ('>=', '<=', '>', '<', '=')
+TEXT_OPS = ('contains', '=')
+
+
+def agent_pids(agent_name):
+    """Partner ids of an agent's book (None = unscoped/whole book)."""
+    return cust.agent_partner_ids(agent_name) if agent_name else None
+
+
+#: Wave 17 R2 — `ar` bucket label -> the grid's column key. ONE mapping, read by the attribute
+#: builder, the empty-row default and validate(), so a bucket cannot exist under two spellings.
+AR_BUCKET_FIELDS = {'1-30': 'ar_aged_1_30', '31-60': 'ar_aged_31_60',
+                    '61-90': 'ar_aged_61_90', '90+': 'ar_aged_90_plus'}
+
+
+def _ar_attrs(t=None):
+    """{pid: {ar_open, ar_overdue, ar_outstanding, ar_exposure}} — the AR family.
+
+    Wave 21 R1: `ar_open` is the NOT-YET-DUE half of a disjoint split (label "AR current $" —
+    key kept so saved views keep working); `ar_outstanding` is the total (current + overdue),
+    which is what "open AR" means everywhere else.
+
+    Composed from `modules/ar.credit_exposure()`, NOT re-derived: it is already reconciled to
+    Odoo by `ar.validate()`, so the Customer table and the Collections page cannot disagree about
+    what a customer owes. Read from the UNFILTERED `_all_rows` — `rows` is a display-truncated
+    top-40, and a column built off that would silently blank everybody else.
+
+    ⚠ `credit_limit` is deliberately NOT a column: 20 of 1,548 customers have one. EXPOSURE is
+    the number that answers "how much are we out on this customer", and it needs no limit.
+
+    ⚠ `days_to_pay` is NOT COMPUTED here — it is READ from a nightly snapshot. MEASURED
+    2026-07-27: `ar.credit_exposure()` costs 9s; `ar.days_to_pay()` costs **301s**, because
+    settlement date means walking three years of reconciled receivable lines and their
+    full-reconcile groups. Computing it in `pool()` would add five minutes to every Customer-table
+    build and every Space container start; computing it LAZILY would just move those five minutes
+    onto whoever opened the page first. So the expensive half runs on the app's existing
+    background store-sync thread (`ar.refresh_days_to_pay_snapshot`) and this reads the answer
+    out of the store for nothing. A missing snapshot yields a blank column, never a slow page.
+    """
+    out = {}
+    try:
+        exp = ar.credit_exposure(t)
+        for r in exp.get('_all_rows') or []:
+            out[r['pid']] = {
+                'ar_open': r.get('open', 0.0) or 0.0,
+                'ar_overdue': r.get('overdue', 0.0) or 0.0,
+                # Wave 21 R1 — the TOTAL owed. Sum of the two halves ar.credit_exposure already
+                # reconciles to Odoo's residual read_group (ar.py validate), so no second oracle.
+                'ar_outstanding': (r.get('open', 0.0) or 0.0) + (r.get('overdue', 0.0) or 0.0),
+                'ar_exposure': r.get('exposure', 0.0) or 0.0,
+                # Wave 17 R2 — the aging split, so a saved VIEW can be the collections
+                # worklist. Keys mirror `ar.OVERDUE_BUCKETS` through AR_BUCKET_FIELDS; the four
+                # sum EXACTLY to `ar_overdue` (gated in validate()).
+                **{k: r.get(f'aged_{b}', 0.0) or 0.0
+                   for b, k in AR_BUCKET_FIELDS.items()},
+            }
+    except Exception:
+        pass
+    for pid, avg in ar.days_to_pay_snapshot().items():
+        # A customer with an AR row but no settled invoice in the window keeps `None` — blank,
+        # not 0. "Pays in 0 days" is a claim, and a false one.
+        out.setdefault(pid, {})['days_to_pay'] = avg
+    return out
+
+
+def _mix_attrs(pids=None, t=None):
+    """{pid: {top_category, sku_count, top_sku, top_category_pct}} — the product-mix family.
+
+    ONE read_group over sale.order.line by (partner, product) across the LTM window, then the
+    product->category map, then aggregation in Python. Line grain is the only grain that can
+    answer "what does this customer buy", and it is deliberately ALL-CHANNEL scope-wise for the
+    same reason inventory analysis is (see [[ri-channel-scope-amazon]]): a customer's product mix
+    is a fact about the customer, not about a sales team.
+
+    `top_category_pct` is that category's share of the customer's LTM line revenue — the number
+    that says whether "top" means dominant or merely first.
+
+    ⚠ There is NO `team_id` parameter, and its absence is the point rather than an omission: for
+    a BU-scoped viewer the revenue columns beside this one ARE team-scoped while these are not,
+    so "top category" can name products bought through a channel that viewer's revenue figures
+    exclude. That is the same trade the inventory modules make, and it is the right one — a
+    customer's product mix is a fact about the customer.
+    """
+    t = t or P.today()
+    mf, mt = P.ltm(t)
+    # ⚠ `pids` NARROWS THE RESULT, NEVER THE DOMAIN — and that is not a style choice. Putting
+    # the caller's ~1,500 partner ids into an `in` clause on a LINE-grain read_group makes Odoo
+    # answer **502 Bad Gateway**; the same query unfiltered returns in 22s. Measured 2026-07-27,
+    # after the filtered form took the live Customer page past 20 MINUTES without rendering.
+    # The grouped result is per-partner anyway, so dropping the extras in Python costs nothing.
+    dom = [('order_id.state', 'in', ['sale', 'done']),
+           ('order_id.date_order', '>=', str(mf)), ('order_id.date_order', '<=', str(mt))]
+    keep = set(pids) if pids else None
+    rows = O.read_group('sale.order.line', dom, ['price_subtotal:sum'],
+                        ['order_partner_id', 'product_id'], lazy=False)
+    prod_ids = {O.m2o_id(r.get('product_id')) for r in rows if r.get('product_id')}
+    prod_ids.discard(None)
+    cats = {}
+    plist = list(prod_ids)
+    for i in range(0, len(plist), 5000):
+        for p in O.search_read('product.product', [('id', 'in', plist[i:i + 5000])], ['categ_id']):
+            # `categ_id`'s display name is the full PATH ("All / Foams & Finishes / Styrofoam").
+            # The column takes the LEAF, because a column and a group label have to be readable —
+            # and the path's own root ("All") carries no information. ⚠ Two categories that share
+            # a leaf name would merge in a group-by; measured against this catalogue that does not
+            # happen, and readability is worth more than defending against a rename.
+            full = O.m2o_name(p.get('categ_id')) or ''
+            cats[p['id']] = (full.split(' / ')[-1].strip() or '(none)') if full else '(none)'
+
+    per = {}
+    for r in rows:
+        pid = O.m2o_id(r.get('order_partner_id'))
+        prod = O.m2o_id(r.get('product_id'))
+        if pid is None or prod is None or (keep is not None and pid not in keep):
+            continue
+        val = r.get('price_subtotal', 0.0) or 0.0
+        e = per.setdefault(pid, {'skus': set(), 'by_cat': {}, 'by_sku': {}, 'total': 0.0})
+        e['skus'].add(prod)
+        e['by_cat'][cats.get(prod, '(none)')] = e['by_cat'].get(cats.get(prod, '(none)'), 0.0) + val
+        e['by_sku'][prod] = e['by_sku'].get(prod, 0.0) + val
+        e['total'] += val
+
+    top_prod_ids = {max(e['by_sku'], key=e['by_sku'].get) for e in per.values() if e['by_sku']}
+    names = {}
+    tlist = list(top_prod_ids)
+    for i in range(0, len(tlist), 5000):
+        for p in O.search_read('product.product', [('id', 'in', tlist[i:i + 5000])], ['name']):
+            names[p['id']] = p.get('name') or ''
+
+    out = {}
+    for pid, e in per.items():
+        cat = max(e['by_cat'], key=e['by_cat'].get) if e['by_cat'] else '(none)'
+        sku = max(e['by_sku'], key=e['by_sku'].get) if e['by_sku'] else None
+        out[pid] = {
+            'top_category': cat,
+            'top_category_pct': (e['by_cat'][cat] / e['total']) if e['total'] else None,
+            'sku_count': len(e['skus']),
+            'top_sku': names.get(sku, '(none)') if sku is not None else '(none)',
+        }
+    return out
+
+
+def _salesperson_attrs(pids=None, t=None):
+    """{pid: salesperson} — the DOMINANT order-taker over LTM, by order count.
+
+    ⚠ Salesperson is NOT the Agent, and they are not interchangeable (owner, 2026-07-27):
+    the SALESPERSON is whoever entered and took the order, the AGENT is the person the customer
+    is assigned to and who earns the commission — including when the customer orders through the
+    office and somebody else keys it in. So this reads `sale.order.user_id` (the ORDER's taker,
+    fully populated: 20 people over $6.2M LTM) and NOT `res.partner.user_id`, which is a
+    different, near-empty field.
+
+    A customer can have several over a year, so the column takes the one who took the MOST of
+    their orders — a single value the table can group and filter cleanly. Ties break toward the
+    larger revenue.
+    """
+    t = t or P.today()
+    mf, mt = P.ltm(t)
+    # Same rule as `_mix_attrs`: the pid list narrows the RESULT, not the domain. Order grain is
+    # far smaller than line grain so this one never actually 502'd, but a caller's id list has no
+    # business being pushed into a query whose grouping already answers per partner.
+    keep = set(pids) if pids else None
+    dom = S.order_domain(str(mf), str(mt), None)
+    rows = O.read_group('sale.order', dom, ['amount_untaxed:sum'],
+                        ['partner_id', 'user_id'], lazy=False)
+    per = {}
+    for r in rows:
+        pid = O.m2o_id(r.get('partner_id'))
+        if pid is None or (keep is not None and pid not in keep):
+            continue
+        who = O.m2o_name(r.get('user_id')) or '(none)'
+        n, rev = r.get('__count', 0) or 0, r.get('amount_untaxed', 0.0) or 0.0
+        cur = per.get(pid)
+        if cur is None or (n, rev) > (cur[1], cur[2]):
+            per[pid] = (who, n, rev)
+    return {pid: v[0] for pid, v in per.items()}
+
+
+def pool(agent_name=None, team_id=None):
+    """One row per customer across the scoped book: the union of YTD buyers, same-period-LY
+    buyers and anyone with an order in the 24-month cadence window — so lapsed/win-back
+    accounts are in the pool, not just YTD actives. Reuses the customers module's validated
+    building blocks (_cust_rev / _cadence_bulk / _partner_attrs) so every metric matches the
+    Customers page definitions; est_missed is the Call-list formula (min(cycles missed, 3) × AOV)."""
+    return _pool_build(agent_name, team_id, limit=None)['rows']
+
+
+def pool_first(agent_name=None, team_id=None, limit=100):
+    """Wave-7 W1 (C1 as amended): the cold-load FAST SLICE — the pool's first `limit` rows in
+    its own default order + the true total, built from the CHEAP families only (revenue ×3,
+    cadence, status, est_missed, partner attributes ≈ 12s measured). The AR / product-mix /
+    salesperson / coords columns stay BLANK until the full build swaps in: `_mix_attrs` alone
+    is a whole-book 20s read_group whose domain must never be pid-narrowed (502 — see its
+    docstring), so "all columns on 100 rows" measured 44.6s vs 45.1s full — no win. A partial
+    payload is a UI PHASE, never a reporting basis — validate() reconciles the full pool only."""
+    return _pool_build(agent_name, team_id, limit=limit, fast=True)
+
+
+def _dba_attrs(pids, t):
+    """{pid: 'Fisch' | 'Royal' | 'Both'} — which brand(s) a customer's confirmed orders carry
+    over the pool's own 24-month universe (C-DBA, wave 2026-08-02).
+
+    GIFTWARE DEALS (the Amazon channel) is deliberately NOT a DBA — a customer buying only
+    through it stays blank here, exactly as ARCHITECTURE.md §4's wholesale scope treats that
+    team. Blank also covers the ledger-retained customers whose activity predates the window:
+    blank means "no brand attributable in 24 months", never a guess. One read_group, grouped
+    (partner, team); degrades to {} like the other attr families — a blank column beats a
+    page that cannot render.
+    """
+    try:
+        import datetime as _dt
+        d_from = (_dt.date.fromisoformat(str(t)) - _dt.timedelta(days=731)).isoformat()
+        pairs = O.read_group(
+            'sale.order',
+            [('state', 'in', ('sale', 'done')), ('date_order', '>=', d_from),
+             ('partner_id', 'in', list(pids)), ('team_id', 'in', (5, 6))],
+            ['partner_id'], ['partner_id', 'team_id'], lazy=False)
+        teams = {}
+        for r in pairs:
+            pid = O.m2o_id(r.get('partner_id'))
+            tid = O.m2o_id(r.get('team_id'))
+            if pid and tid in (5, 6):
+                teams.setdefault(pid, set()).add(tid)
+        label = {5: 'Fisch', 6: 'Royal'}
+        return {pid: ('Both' if len(ts) == 2 else label[next(iter(ts))])
+                for pid, ts in teams.items()}
+    except Exception:
+        return {}
+
+
+def _book_pids(team_id=None, agent_pids=None):
+    """⭐ WAVE 20 (owner items 8 + 27, ruling R3) — THE WHOLE BOOK, not just who bought recently.
+
+    Owner: *"Martin Pasternak showing only 313 accounts when I filter agent, whereas in Odoo it is
+    494 … I want our App to show complete source of truth, even if no sale.order at all or not.
+    Its important to see what customer is getting assigned to Martin or whether we can retarget
+    them."* The pool was a 24-MONTH SALES universe (YTD ∪ LY-YTD ∪ cadence-window buyers), so a
+    customer assigned to an agent who has never ordered — precisely a retargeting target — did not
+    exist in the app at all.
+
+    R3's definition, MEASURED against live Odoo 2026-08-05:
+        customer_rank>0 active .............. 3,614
+        ever ordered (confirmed, team 5/6) ...  1,748
+        UNION ............................... 3,723   (vs 1,555 in the old 24-month pool)
+    Martin's book under this rule is **494** — the owner's Odoo number, to the account.
+
+    ⛔ **THE "agent-assigned" LEG OF R3 IS DELIBERATELY NOT A THIRD TERM, and that is a
+    measurement, not a shortcut.** Taken literally it added 174 partners and pushed Martin to 503;
+    every one of the 9 extras on his book was an ODOO ADDRESS RECORD rather than an account —
+    `type` in (`delivery`, `other`), most carrying a `parent_id`, and TWO with `name: False`.
+    Shipping them would have put nameless rows in the customer table and made "how many customers
+    does Martin have" answer 503 against an Odoo screen that says 494.
+    Excluding address types wholesale is also wrong (`type not in (delivery, invoice, other,
+    private)` measured **488** — it drops 6 genuine accounts that happen to carry a delivery
+    type). `customer_rank > 0` is the predicate that means "this partner is a customer record",
+    it reproduces the owner's number exactly, and every agent-assigned ACCOUNT already satisfies
+    it — so the leg is subsumed rather than dropped. Item 27's actual ask (the 126 assigned
+    partners with no `sale.order` at all) is fully served: they are rank>0 and they are in.
+
+    ⚠ ACTIVE ONLY. Archived partners stay out (R3): they are ex-customers, and putting them in
+    every count would make "how many customers do we have" unanswerable. The agent-LOGIN scope
+    (`customers.agent_partner_ids`) deliberately still includes archived — an agent's own book is
+    their whole history — and the two remain compatible because that set is INTERSECTED with this
+    pool, so archived rows drop out of the table without narrowing the agent's own permissions.
+
+    ⚠ BU SCOPE IS APPLIED THROUGH ORDERS, NOT THROUGH THE PARTNER. `res.partner` carries no team,
+    so a BU-scoped caller gets the partners who have ORDERED in that BU (plus their own agent
+    book). Widening it to every partner for a scoped user would cross the BU isolation rule that
+    the whole permissioning model rests on.
+    """
+    try:
+        if team_id:
+            # Scoped: partners with confirmed orders in THIS BU, ever. `read_group` on partner_id
+            # rather than a search_read of orders — the group is the distinct set, and it is one
+            # round trip instead of paging tens of thousands of order rows.
+            rows = O.read_group('sale.order',
+                                [('state', 'in', ('sale', 'done')), ('team_id', '=', team_id)],
+                                ['partner_id'], ['partner_id'], lazy=False)
+            book = {O.m2o_id(r.get('partner_id')) for r in rows}
+            book.discard(None)
+        else:
+            rank = O.search_read('res.partner',
+                                 [('customer_rank', '>', 0), ('active', '=', True)],
+                                 ['id'], limit=200000)
+            # `ever` is NOT redundant with rank>0: a partner can be archived-then-reactivated, or
+            # have had its rank reset, and an account that demonstrably bought from us belongs in
+            # the book whatever its flags say now. An ORDER is a fact; a rank is a setting.
+            rows = O.read_group('sale.order',
+                                [('state', 'in', ('sale', 'done')), ('team_id', 'in', (5, 6))],
+                                ['partner_id'], ['partner_id'], lazy=False)
+            ever = {O.m2o_id(r.get('partner_id')) for r in rows}
+            ever.discard(None)
+            book = {r['id'] for r in rank} | ever
+        # An agent filter NARROWS the book to that agent's partners — never widens it. The
+        # intersection is what keeps an agent-login user inside their own book while still
+        # gaining every no-order account assigned to them, which is the whole point of item 27.
+        return (book & set(agent_pids)) if agent_pids is not None else book
+    except Exception as e:
+        # Degrade to the sales-derived universe rather than failing the page — but LOUDLY.
+        #
+        # ⛔ THIS DEGRADATION IS NOT LIKE THE OTHERS IN THIS MODULE, and the difference is what
+        # makes silence wrong here. Every other family (`_ar_attrs`, `_mix_attrs`, …) degrades to
+        # a blank COLUMN, which is visible: the user sees an empty column and asks why. This one
+        # degrades to absent ROWS. The pool still builds from the sales legs, so the page renders
+        # perfectly, the counts look plausible, and Martin is quietly back at 313 with nothing
+        # anywhere saying the book leg failed. An invisible degradation of a COUNT is the failure
+        # mode this codebase keeps writing rules against ([[no-unverifiable-aggregates]]).
+        try:
+            import harness.telemetry as _tel
+            _tel.error('customer_data:_book_pids', e, fallback='sales-derived pool only')
+        except Exception:
+            pass
+        print(f"[aios] WARNING customer_data._book_pids failed ({type(e).__name__}: {e}) - the "
+              f"customer pool is falling back to the 24-month SALES universe, so accounts with "
+              f"no recent orders (owner item 27) are MISSING from this build.")
+        return set()
+
+
+def _pool_build(agent_name, team_id, limit, fast=False):
+    t = P.today()
+    yf, yt = P.ytd(t)
+    lf, lt = P.ytd_last_year(t)
+    mf, mt = P.ltm(t)
+    pids = agent_pids(agent_name)
+    this = cust._cust_rev(yf, yt, team_id, pids)
+    last = cust._cust_rev(lf, lt, team_id, pids)
+    ltm = cust._cust_rev(mf, mt, team_id, pids)
+    cad = cust._cadence_bulk(t, team_id, agent_pids=pids)
+    all_pids = set(this) | set(last) | set(cad) | _book_pids(team_id, pids)
+    total = len(all_pids)
+    if limit is not None and total > limit:
+        # the SAME ordering the assembled pool ships (see the sort below) — the slice must be
+        # the first page of the very list the full build renders, or the swap-in reshuffles.
+        ranked = sorted(all_pids,
+                        key=lambda p: -((this.get(p) or {}).get('rev', 0.0)
+                                        + (last.get(p) or {}).get('rev', 0.0)))
+        all_pids = set(ranked[:limit])
+    attrs = cust._partner_attrs(list(all_pids))
+    if fast:
+        # C1 fast phase: the slow families stay empty — their columns render blank behind the
+        # toolbar's partial indicator until the full build swaps in.
+        ar_a, mix_a, sp_a, geo_a, dba_a = {}, {}, {}, {}, {}
+    else:
+        # The three families the owner asked for (2026-07-27). Each degrades to {} rather than
+        # raising: a customer table that cannot render because AR is momentarily unreachable is
+        # a worse failure than one with a blank column.
+        ar_a = _ar_attrs(t)
+        mix_a = _mix_attrs(all_pids, t)
+        sp_a = _salesperson_attrs(all_pids, t)
+        # W11 (wave-7): coordinates for the Map VIEW — Odoo coords else the geocode cache,
+        # read-only reuse (coords_for never geocodes); missing → null lat/lon, and the
+        # client's map view discloses the count.
+        geo_a = map_mod.coords_for(list(all_pids))
+        # C-DBA (2026-08-02): the brand attribute rides the full build only, like the rest.
+        dba_a = _dba_attrs(all_pids, t)
+    # customers whose only activity sits in the older half of the 24-month cadence window
+    # appear in no revenue map — fetch their names directly (else the lapsed cohort, exactly
+    # the win-back targets this union exists for, would render as '?')
+    unnamed = [pid for pid in all_pids
+               if not ((this.get(pid) or {}).get('name') or (last.get(pid) or {}).get('name')
+                       or (ltm.get(pid) or {}).get('name'))]
+    extra_names = ({r['id']: r['name'] for r in
+                    O.search_read('res.partner', [('id', 'in', unnamed)], ['name'])}
+                   if unnamed else {})
+    rows = []
+    for pid in all_pids:
+        tv = this.get(pid) or {}
+        lv = last.get(pid) or {}
+        c = cad.get(pid) or {}
+        rev, ly = tv.get('rev', 0.0), lv.get('rev', 0.0)
+        gap = c.get('typical_gap_days')
+        overdue = c.get('overdue_days')
+        aov = c.get('aov', 0.0)
+        est = (min(overdue / gap, 3.0) * aov) if (gap and overdue and overdue > 0) else 0.0
+        status = ('New' if rev > 0 and ly <= 0 else
+                  'Lost' if ly > 0 and rev <= 0 else
+                  'Declining' if 0 < rev < ly else
+                  'Growing' if rev > 0 else 'Dormant')
+        a = attrs.get(pid) or {}
+        rows.append({
+            'pid': pid,
+            'customer': tv.get('name') or lv.get('name')
+                        or (ltm.get(pid) or {}).get('name') or extra_names.get(pid) or '?',
+            'status': status,
+            'agent': a.get('agent', '(none)'), 'city': a.get('city', '(none)'),
+            # C-DBA: blank (not '(none)') — a select's blank is its own honest empty state.
+            'dba': dba_a.get(pid, ''),
+            'state': a.get('state', '(none)'),
+            # Owner 2026-07-27, the partner-attribute family. `.get(..., default)` is not
+            # defensive habit here: search_read returned 1,548 of 1,550 pool pids — two partners
+            # in the sales history are archived or deleted — so a customer with NO attrs row is
+            # a real case, and it must render as '(none)' rather than KeyError the whole page.
+            'country': a.get('country', '(none)'), 'zip': a.get('zip', '(none)'),
+            'payment_terms': a.get('payment_terms', '(none)'),
+            'customer_since': a.get('customer_since', ''),
+            # Row-level datum for the `created_time` field type (wave-5 item 11) — rides every
+            # row like pid, no column of its own until a user creates one.
+            '_created': a.get('created_at', ''),
+            'tags': a.get('tags', '(none)'), 'pricelist': a.get('pricelist', '(none)'),
+            # AR / credit exposure — composed from the already-reconciled ar.py blocks, so the
+            # Customer table and the Collections page cannot disagree.
+            'ar_open': (ar_a.get(pid) or {}).get('ar_open', 0.0),
+            'ar_overdue': (ar_a.get(pid) or {}).get('ar_overdue', 0.0),
+            'ar_outstanding': (ar_a.get(pid) or {}).get('ar_outstanding', 0.0),
+            'ar_exposure': (ar_a.get(pid) or {}).get('ar_exposure', 0.0),
+            'days_to_pay': (ar_a.get(pid) or {}).get('days_to_pay'),
+            **{k: (ar_a.get(pid) or {}).get(k, 0.0) for k in AR_BUCKET_FIELDS.values()},
+            # Product mix, LTM, line grain, ALL-channel.
+            'top_category': (mix_a.get(pid) or {}).get('top_category', '(none)'),
+            'top_category_pct': (mix_a.get(pid) or {}).get('top_category_pct'),
+            'sku_count': (mix_a.get(pid) or {}).get('sku_count', 0),
+            'top_sku': (mix_a.get(pid) or {}).get('top_sku', '(none)'),
+            # The ORDER-TAKER, not the agent. Different people, different questions.
+            'salesperson': sp_a.get(pid, '(none)'),
+            # W11: nullable — the Map view pins what it can and counts what it cannot.
+            'lat': (geo_a.get(pid) or {}).get('lat'),
+            'lon': (geo_a.get(pid) or {}).get('lon'),
+            'revenue_ytd': rev, 'revenue_ly': ly,
+            'yoy_pct': P.yoy_pct(rev, ly),
+            'at_risk': max(ly - rev, 0.0),
+            'ltm_rev': (ltm.get(pid) or {}).get('rev', 0.0),
+            'orders_24m': c.get('n_orders', 0), 'aov': aov,
+            'last_order': c.get('last_order', ''),
+            'days_since': c.get('days_since'),
+            'typical_gap_days': gap, 'overdue_days': overdue,
+            'est_missed': est,
+        })
+    for r in rows:
+        r['odoo_status'] = 'Active'
+    # I13 (owner item 13, contract C6): RETAIN customers that disappear from Odoo.
+    # Only the FULL build reconciles the ledger — the fast slice is 100 rows by construction,
+    # so letting it write would mark ~1,450 living customers archived on every cold load.
+    if not fast:
+        rows, total = _reconcile_ledger(rows, total, agent_name, team_id)
+    rows.sort(key=lambda r: -(r['revenue_ytd'] + r['revenue_ly']))
+    return {'rows': rows, 'total': total}
+
+
+LEDGER_KEY = 'customer_ledger'
+
+
+def _reconcile_ledger(rows, total, agent_name, team_id):
+    """Remember every customer we have ever seen, and keep serving the ones Odoo stopped
+    returning (owner item 13: "if it is deleted, that it goes to an archived tag immediately —
+    so stored in our platform even if deleted in Odoo").
+
+    Why a ledger at all: this pool is built from SALES HISTORY, not from a partner list, so a
+    partner deleted in Odoo usually keeps appearing (their order lines remain) — until the day
+    the lines go too, when the row would silently vanish along with every note, tag and cohort
+    membership attached to it. Nothing else in the app would notice. The ledger is the only
+    record that the customer ever existed, which is why it starts recording now rather than
+    when the surfacing is finished: history you did not write down is not recoverable later.
+
+    ⚠ SCOPE-SAFE. The ledger is written ONLY from an UNSCOPED build (no agent, no BU). A scoped
+    build legitimately sees a fraction of the book, and reconciling from it would mark every
+    customer outside that scope 'Archived' for everyone — the failure would look exactly like
+    the data loss this is meant to prevent. Scoped builds READ the ledger and resurrect nothing
+    they cannot prove they should see.
+    """
+    try:
+        ledger = dict(store.get(LEDGER_KEY) or {})
+    except Exception:
+        return rows, total                  # a ledger we cannot read must not break the table
+    today = str(P.today())
+    live = {r['pid'] for r in rows}
+    unscoped = agent_name is None and team_id is None
+
+    if unscoped:
+        for r in rows:
+            e = ledger.get(str(r['pid'])) or {}
+            e.update({'name': r['customer'], 'last_seen': today})
+            e.setdefault('first_seen', today)
+            ledger[str(r['pid'])] = e
+
+    # Rows the ledger knows and this build did not return. On an unscoped build that means
+    # "gone from Odoo"; on a scoped one it usually just means "not in this agent's book", so
+    # only the unscoped build may surface them.
+    revived = []
+    if unscoped:
+        for key, e in ledger.items():
+            try:
+                pid = int(key)
+            except (TypeError, ValueError):
+                continue
+            if pid in live:
+                continue
+            revived.append({
+                'pid': pid, 'customer': e.get('name') or '?', 'status': 'Dormant',
+                'odoo_status': 'Archived',
+                # Everything else is genuinely UNKNOWN now — the record is gone. Blank is the
+                # honest rendering; carrying the last-known numbers forward would state figures
+                # as current that nothing can reconcile ([[no-unverifiable-aggregates]]).
+                'agent': '(none)', 'city': '(none)', 'state': '(none)', 'country': '(none)',
+                'zip': '(none)', 'payment_terms': '(none)', 'customer_since': '',
+                '_created': '', 'tags': '(none)', 'pricelist': '(none)',
+                'ar_open': 0.0, 'ar_overdue': 0.0, 'ar_outstanding': 0.0, 'ar_exposure': 0.0,
+                'days_to_pay': None,
+                **{k: 0.0 for k in AR_BUCKET_FIELDS.values()},
+                'top_category': '(none)', 'top_category_pct': None, 'sku_count': 0,
+                'top_sku': '(none)', 'salesperson': '(none)', 'lat': None, 'lon': None,
+                'revenue_ytd': 0.0, 'revenue_ly': 0.0, 'yoy_pct': None, 'at_risk': 0.0,
+                'ltm_rev': 0.0, 'orders_24m': 0, 'aov': 0.0, 'last_order': '',
+                'days_since': None, 'typical_gap_days': None, 'overdue_days': None,
+                'est_missed': 0.0,
+            })
+        if store.available():
+            try:
+                store.update(LEDGER_KEY, lambda cur: {**cur, **ledger}, flush='async')
+            except Exception:
+                pass                        # recording is best-effort; the table is not
+    return rows + revived, total + len(revived)
+
+
+# ------------------------------------------------------------------ the rule engine
+# A list's formula = [{'field','op','value'}, ...] over FIELDS + a 'sort' key ('-x' = desc).
+# The two templates ARE the old My Day queue formulas, expressed as visible rules.
+#
+# 'note' is a SEED, not the source of truth (owner 2026-07-25). It is what a list reads
+# BEFORE anyone edits it; the moment a user saves a description the stored one wins, and
+# an empty stored description stays empty — the template must never resurrect. That
+# precedence lives in aios_grid.views_from_defs (a saved view replaces its template-derived
+# one wholesale) and is pinned by _qa_grid_view_note.py. Edit the prose here only to change
+# what a NEW user starts with.
+TEMPLATES = {
+    'Call list': {
+        'rules': [{'field': 'orders_24m', 'op': '>=', 'value': 3},
+                  {'field': 'overdue_days', 'op': '>', 'value': 0},
+                  {'field': 'days_since', 'op': '<=', 'value': 365}],
+        'sort': '-est_missed',
+        'note': 'Customers overdue against their OWN reorder cadence (3+ orders, a real gap '
+                'pattern, ordered within 365d), ranked by estimated missed revenue.'},
+    'Win-back': {
+        'rules': [{'field': 'revenue_ly', 'op': '>=', 'value': 2000},
+                  {'field': 'at_risk', 'op': '>', 'value': 0}],
+        'sort': '-at_risk',
+        'note': 'Bought materially last year (over $2,000), down or gone this year, ranked by '
+                'dollars at risk.'},
+}
+
+
+def _match(row, rule):
+    """One rule against one row. None/missing numeric values fail every numeric comparison
+    (a customer with no cadence is never 'overdue'); text ops are case-insensitive."""
+    field, op, val = rule.get('field'), rule.get('op'), rule.get('value')
+    if field not in FIELDS:
+        return True                                   # unknown field → rule is inert, not a crash
+    v = row.get(field)
+    if FIELDS[field][1] == 'text':
+        s, q = str(v or '').lower(), str(val or '').lower()
+        return q in s if op == 'contains' else s == q
+    try:
+        v, val = float(v), float(val)
+    except (TypeError, ValueError):
+        return False
+    return {'>=': v >= val, '<=': v <= val, '>': v > val, '<': v < val,
+            '=': v == val}.get(op, False)
+
+
+def apply_rules(rows, rules, sort=None):
+    """Filter the pool through a formula (AND of all rules) and apply the list's sort."""
+    out = [r for r in rows if all(_match(r, ru) for ru in (rules or []))]
+    if sort:
+        key = sort.lstrip('-')
+        out.sort(key=lambda r: (r.get(key) is None,
+                                -(r.get(key) or 0) if sort.startswith('-') else (r.get(key) or 0))
+                 if FIELDS.get(key, ('', 'num'))[1] == 'num'
+                 else str(r.get(key) or '').lower(), reverse=False)
+    return out
+
+
+# ------------------------------------------------------------------ persistence (HF store)
+def saved_lists(username):
+    """{list_name: {'rules','sort','members','note'}} for one user ({} when none / store down)."""
+    try:
+        return (store.get(KEY) or {}).get(username, {}) or {}
+    except Exception:
+        return {}
+
+
+def save_list(username, name, definition):
+    def _up(d):
+        d.setdefault(username, {})[name] = definition
+        return d
+    store.update(KEY, _up)
+
+
+def delete_list(username, name):
+    def _up(d):
+        (d.get(username) or {}).pop(name, None)
+        return d
+    store.update(KEY, _up)
+
+
+# ------------------------------------------------------------------ Airtable-style table workspace
+# This is intentionally separate from `customer_lists`: a LIST owns membership/formula
+# semantics, while a VIEW owns presentation/query state (filters, multi-sort, grouping,
+# visible fields, widths, color, row height). List views can reference the same formula
+# without conflating the two persistence contracts.
+#
+# The store logic MOVED to core/table_store.py 2026-07-27 (the table-page factory): these
+# names are the Customer table's instance of the generic per-object workspace store, kept as
+# module functions so every existing caller (app.py's host loop, QA gates) is untouched.
+# A NEW table object gets its own `core.table_store.make('<its>_table_workspace')`.
+_TSTORE = table_store.make(TABLE_KEY)
+
+#: Wave 16 C-TOPIC — the ops OBJECT, for callers that select a table by TOPIC (grid_events'
+#: `EventCtx.table`). The module-level re-exports below stay for every existing caller.
+TABLE_OPS = _TSTORE
+
+table_workspace = _TSTORE.workspace
+shared_table_views = _TSTORE.shared_views      # wave-9 I17: views shared WITH this viewer
+shared_table_view = _TSTORE.shared_view        #   ...and one raw, for authorisation only
+save_table_view = _TSTORE.save_view
+delete_table_view = _TSTORE.delete_view
+save_table_field = _TSTORE.save_field
+delete_table_field = _TSTORE.delete_field
+duplicate_table_field = _TSTORE.duplicate_field
+patch_table_overlay = _TSTORE.patch_overlay
+save_table_folders = _TSTORE.save_folders
+save_table_active_view = _TSTORE.save_active_view   # owner item 3: last-opened view, per user
+save_table_record_layout = _TSTORE.save_record_layout  # 2026-08-02 C-LAYOUT: record-detail order
+
+
+# ------------------------------------------------------------------ digest compatibility
+def queues(agent_name=None, team_id=None, limit=200):
+    """The two canonical morning lists (call list + win-back) for the daily digest email —
+    unchanged formulas via the customers module (the digest always uses the CANONICAL templates,
+    not a user's edited copy, so every rep's email means the same thing)."""
+    pids = agent_pids(agent_name)
+    return {
+        'calls': cust.contact_recommendations(team_id=team_id, limit=limit, agent_pids=pids),
+        'risk': cust.at_risk(team_id=team_id, limit=limit, agent_pids=pids),
+    }

platform/modules/digest.py

@@ -1,227 +1,227 @@
-"""Daily agent digest — "Your book this morning": one email per user, their queue only.
-
-Delivery reuses the ONE sanctioned Odoo write path (modules/collections_send.py: mail.mail
-create through the Office 365 relay) including its SAFE_MODE allow-list — while the guardrail
-is ON no digest can leave the allow-list. Content rules (adoption canon, engagement-adoption
-brief): ≤10 lines, only non-empty sections, every line deep-links back to the exact row
-(?src=digest), and the email is SKIPPED entirely when there is nothing to act on — silence
-keeps opens high. Internal mail: no model/res_id (these must NOT land in customer chatter).
-
-Scheduling: app.py starts one daemon ticker (in the cache_resource singleton) that calls
-run_due() every few minutes; run_due sends at most once per (weekday, user) after
-DIGEST_UTC_HOUR (default 11:00 UTC = 7am ET in summer), idempotent across Space restarts via
-the store key 'digest_log' (empty-skips are logged too, so a quiet day isn't rebuilt all day).
-
-BU isolation carries into email: a single-BU user's digest is scoped to that BU's team_id.
-"""
-import os
-import html as _html
-import datetime as dt
-
-import core.store as store
-import core.users as users
-import core.links as links
-import modules.collections_send as cs
-import modules.customer_data as md   # call-list / win-back queues (ex-myday, ex-customer_list)
-import modules.tasks as tasks
-import modules.customers as cust
-
-KEY = 'digest_log'
-UTC_HOUR = int(os.environ.get('DIGEST_UTC_HOUR', '11'))
-WEEKDAYS_ONLY = os.environ.get('DIGEST_WEEKDAYS_ONLY', '1').strip().lower() \
-    not in ('0', 'false', 'no', '')
-ENABLED = os.environ.get('DIGEST_ENABLED', '1').strip().lower() not in ('0', 'false', 'no', '')
-
-_NAVY, _GOLD, _MUTED = '#5B8FD9', '#D9A93A', '#6B7280'
-
-
-def _team_for(user):
-    """Single-BU users get a digest scoped to that BU — isolation carries into email."""
-    bus = (user or {}).get('bus', 'all')
-    if isinstance(bus, (list, tuple)) and len(bus) == 1:
-        return bus[0]
-    return None
-
-
-def _m(x):
-    try:
-        return f"${float(x):,.0f}"
-    except (TypeError, ValueError):
-        return '—'
-
-
-def _line(text, href, meta=''):
-    t = _html.escape(str(text))
-    m = f" <span style='color:{_MUTED}'>{_html.escape(str(meta))}</span>" if meta else ''
-    return (f"<tr><td style='padding:6px 0;border-bottom:1px solid #ECEFF3;font-size:14px'>"
-            f"<a href='{href}' style='color:{_NAVY};text-decoration:none;font-weight:600'>{t}</a>"
-            f"{m}</td></tr>")
-
-
-def _sec(title):
-    return (f"<tr><td style='padding:14px 0 4px;font-size:12.5px;font-weight:700;"
-            f"color:{_MUTED}'>{_html.escape(title)}</td></tr>")
-
-
-def build(user, t=None):
-    """(subject, html, n_actionable) for one user. n_actionable == 0 → skip the send."""
-    t = t or dt.date.today()
-    uname = user.get('username', '')
-    agent = user.get('agent')
-    team_id = _team_for(user)
-    pids = md.agent_pids(agent)
-
-    today = t.isoformat()
-    my = [x for x in tasks.for_owner(uname)] if store.available() else []
-    due = [x for x in my if (x.get('due') or '9999-12-31') <= today]
-    q = md.queues(agent, team_id, limit=25)
-    calls, risk = q['calls'][:5], q['risk'][:3]
-
-    # yesterday's orders for the book (one read_group; skip silently on a transport error —
-    # the digest must never fail because one section couldn't be pulled)
-    yday = (t - dt.timedelta(days=1)).isoformat()
-    y_rev = y_orders = 0
-    try:
-        rev_map = cust._cust_rev(yday, yday, team_id, pids)
-        y_rev = sum(v.get('rev', 0.0) for v in rev_map.values())
-        y_orders = sum(v.get('orders', 0) for v in rev_map.values())
-    except Exception:
-        pass
-
-    n = len(due) + len(calls) + len(risk)
-    if n == 0 and y_orders == 0:
-        return None, None, 0
-
-    rows = []
-    if due:
-        rows.append(_sec(f'Tasks due ({len(due)})'))
-        for x in due[:5]:
-            ent = x.get('entity') or {}
-            href = links.deeplink('customer_data', src='digest')
-            if ent.get('kind') and ent.get('id') is not None:
-                href = links.deeplink('customer_data', ent['kind'], ent['id'], src='digest')
-            meta = f"due {x.get('due') or '—'}"
-            rows.append(_line(x.get('title', 'Task'), href, meta))
-    if calls:
-        rows.append(_sec('Call today — overdue vs their own cadence'))
-        for r in calls:
-            href = links.deeplink('customer_data', 'customer', r['pid'], src='digest')
-            meta = (f"{int(r.get('overdue_days') or 0)}d past cycle · "
-                    f"est. missed {_m(r.get('est_missed'))}")
-            rows.append(_line(r.get('customer', '?'), href, meta))
-    if risk:
-        rows.append(_sec('Win-back — down vs last year'))
-        for r in risk:
-            href = links.deeplink('customer_data', 'customer', r['pid'], src='digest')
-            meta = f"{_m(r.get('at_risk'))} at risk · {r.get('status', '')}"
-            rows.append(_line(r.get('customer', '?'), href, meta))
-    if y_orders:
-        rows.append(_sec('Yesterday'))
-        # Wave 16: the Sales page is retired (registry row archived) — yesterday's orders now
-        # link to the Customer grid, the surface that carries the book. A link to an archived
-        # page would fall through to the landing and read as a broken link.
-        rows.append(_line(f"{y_orders} orders · {_m(y_rev)}",
-                          links.deeplink('customer_data', src='digest')))
-
-    scope = f"{agent}'s book" if agent else 'the whole book'
-    list_url = links.deeplink('customer_data', src='digest')
-    html_body = f"""
-<div style='font-family:Calibri,Arial,sans-serif;color:#1A2332;max-width:600px;margin:0 auto'>
-  <div style='border-top:3px solid {_GOLD};padding:16px 0 4px'>
-    <div style='font-size:18px;font-weight:700;color:{_NAVY}'>Your book this morning</div>
-    <div style='font-size:12px;color:{_MUTED}'>{t.strftime('%A, %B %d')} · {scope}</div>
-  </div>
-  <table style='width:100%;border-collapse:collapse'>{''.join(rows)}</table>
-  <div style='padding:16px 0;font-size:13px'>
-    <a href='{list_url}' style='color:{_NAVY};font-weight:700'>Open your Customer List →</a>
-  </div>
-  <div style='font-size:11px;color:{_MUTED};border-top:1px solid #ECEFF3;padding-top:8px'>
-    Internal daily digest from Loopable.
-    Sent only on days with something to act on.
-  </div>
-</div>"""
-    subject = f"Your book this morning — {n} to act on · {t.strftime('%b %d')}"
-    return subject, html_body, n
-
-
-def send_one(user, odoo=None, override_to=None):
-    """Build + queue one digest. Returns a short result string (never raises past itself)."""
-    to = override_to or user.get('email')
-    if not to:
-        return 'no-email'
-    subject, body, n = build(user)
-    if n == 0:
-        return 'empty-skip'
-    if not cs.safe_recipient_ok(to):
-        return 'safe-mode-blocked'
-    odoo = odoo or cs.Odoo()
-    mid = odoo.queue_mail({
-        'subject': subject, 'body_html': body,
-        'email_to': to, 'email_from': cs.SENDER_DISPLAY, 'reply_to': cs.REPLY_TO,
-        'mail_server_id': cs.ROYAL_MAIL_SERVER_ID, 'author_id': cs.ROYAL_AUTHOR_ID,
-        'state': 'outgoing', 'auto_delete': False,
-        # This Odoo runs the custom rt_multi_dba module whose mail-create hook browses
-        # env[mail.model].browse(mail.res_id) — a mail WITHOUT model/res_id crashes with
-        # KeyError: False (verified 2026-07-05). Anchor internal mail on the house partner
-        # (Royal Imports, cs.ROYAL_AUTHOR_ID) so nothing lands in a CUSTOMER's chatter.
-        'model': 'res.partner', 'res_id': cs.ROYAL_AUTHOR_ID,
-    })
-    return f'queued:{mid}'
-
-
-def run_due(force_user=None, override_to=None):
-    """The ticker entry point. Normal path: after UTC_HOUR on weekdays, send each active
-    emailed user their digest at most once per day (dedup via digest_log, including
-    empty-skips). force_user bypasses the schedule/dedup (the 'Send my digest now' button)
-    but NEVER the SAFE_MODE guardrail; forced sends are not logged (the 7am run still runs)."""
-    if not store.available():
-        return {}
-    now = dt.datetime.utcnow()
-    today = now.date().isoformat()
-    if force_user is None:
-        if not ENABLED:
-            return {}
-        if WEEKDAYS_ONLY and now.weekday() >= 5:
-            return {}
-        if now.hour < UTC_HOUR:
-            return {}
-    try:
-        reg = users.registry()
-    except Exception:
-        return {}
-    already = (store.get(KEY) or {}).get(today, {}) if force_user is None else {}
-    results = {}
-    odoo = None
-    for un, u in sorted(reg.items()):
-        if force_user is not None and un != force_user:
-            continue
-        if not u.get('active', True) or not u.get('email'):
-            continue
-        if force_user is None and un in already:
-            continue
-        pub = users._public(un, u)
-        try:
-            if odoo is None:
-                odoo = cs.Odoo()
-            results[un] = send_one(pub, odoo, override_to=override_to)
-        except cs.SafeModeBlocked:
-            results[un] = 'safe-mode-blocked'
-        except Exception as e:
-            results[un] = f'error:{str(e)[:80]}'
-    if force_user is None and results:
-        stamp = now.strftime('%H:%M')
-
-        def _rec(d):
-            day = d.setdefault(today, {})
-            for un, r in results.items():
-                day[un] = {'at': stamp, 'result': r}
-            return d
-        try:
-            store.update(KEY, _rec)
-        except Exception:
-            pass
-    return results
-
-
-def today_log():
-    return (store.get(KEY) or {}).get(dt.date.today().isoformat(), {})
+"""Daily agent digest — "Your book this morning": one email per user, their queue only.
+
+Delivery reuses the ONE sanctioned Odoo write path (modules/collections_send.py: mail.mail
+create through the Office 365 relay) including its SAFE_MODE allow-list — while the guardrail
+is ON no digest can leave the allow-list. Content rules (adoption canon, engagement-adoption
+brief): ≤10 lines, only non-empty sections, every line deep-links back to the exact row
+(?src=digest), and the email is SKIPPED entirely when there is nothing to act on — silence
+keeps opens high. Internal mail: no model/res_id (these must NOT land in customer chatter).
+
+Scheduling: app.py starts one daemon ticker (in the cache_resource singleton) that calls
+run_due() every few minutes; run_due sends at most once per (weekday, user) after
+DIGEST_UTC_HOUR (default 11:00 UTC = 7am ET in summer), idempotent across Space restarts via
+the store key 'digest_log' (empty-skips are logged too, so a quiet day isn't rebuilt all day).
+
+BU isolation carries into email: a single-BU user's digest is scoped to that BU's team_id.
+"""
+import os
+import html as _html
+import datetime as dt
+
+import core.store as store
+import core.users as users
+import core.links as links
+import modules.collections_send as cs
+import modules.customer_data as md   # call-list / win-back queues (ex-myday, ex-customer_list)
+import modules.tasks as tasks
+import modules.customers as cust
+
+KEY = 'digest_log'
+UTC_HOUR = int(os.environ.get('DIGEST_UTC_HOUR', '11'))
+WEEKDAYS_ONLY = os.environ.get('DIGEST_WEEKDAYS_ONLY', '1').strip().lower() \
+    not in ('0', 'false', 'no', '')
+ENABLED = os.environ.get('DIGEST_ENABLED', '1').strip().lower() not in ('0', 'false', 'no', '')
+
+_NAVY, _GOLD, _MUTED = '#5B8FD9', '#D9A93A', '#6B7280'
+
+
+def _team_for(user):
+    """Single-BU users get a digest scoped to that BU — isolation carries into email."""
+    bus = (user or {}).get('bus', 'all')
+    if isinstance(bus, (list, tuple)) and len(bus) == 1:
+        return bus[0]
+    return None
+
+
+def _m(x):
+    try:
+        return f"${float(x):,.0f}"
+    except (TypeError, ValueError):
+        return '—'
+
+
+def _line(text, href, meta=''):
+    t = _html.escape(str(text))
+    m = f" <span style='color:{_MUTED}'>{_html.escape(str(meta))}</span>" if meta else ''
+    return (f"<tr><td style='padding:6px 0;border-bottom:1px solid #ECEFF3;font-size:14px'>"
+            f"<a href='{href}' style='color:{_NAVY};text-decoration:none;font-weight:600'>{t}</a>"
+            f"{m}</td></tr>")
+
+
+def _sec(title):
+    return (f"<tr><td style='padding:14px 0 4px;font-size:12.5px;font-weight:700;"
+            f"color:{_MUTED}'>{_html.escape(title)}</td></tr>")
+
+
+def build(user, t=None):
+    """(subject, html, n_actionable) for one user. n_actionable == 0 → skip the send."""
+    t = t or dt.date.today()
+    uname = user.get('username', '')
+    agent = user.get('agent')
+    team_id = _team_for(user)
+    pids = md.agent_pids(agent)
+
+    today = t.isoformat()
+    my = [x for x in tasks.for_owner(uname)] if store.available() else []
+    due = [x for x in my if (x.get('due') or '9999-12-31') <= today]
+    q = md.queues(agent, team_id, limit=25)
+    calls, risk = q['calls'][:5], q['risk'][:3]
+
+    # yesterday's orders for the book (one read_group; skip silently on a transport error —
+    # the digest must never fail because one section couldn't be pulled)
+    yday = (t - dt.timedelta(days=1)).isoformat()
+    y_rev = y_orders = 0
+    try:
+        rev_map = cust._cust_rev(yday, yday, team_id, pids)
+        y_rev = sum(v.get('rev', 0.0) for v in rev_map.values())
+        y_orders = sum(v.get('orders', 0) for v in rev_map.values())
+    except Exception:
+        pass
+
+    n = len(due) + len(calls) + len(risk)
+    if n == 0 and y_orders == 0:
+        return None, None, 0
+
+    rows = []
+    if due:
+        rows.append(_sec(f'Tasks due ({len(due)})'))
+        for x in due[:5]:
+            ent = x.get('entity') or {}
+            href = links.deeplink('customer_data', src='digest')
+            if ent.get('kind') and ent.get('id') is not None:
+                href = links.deeplink('customer_data', ent['kind'], ent['id'], src='digest')
+            meta = f"due {x.get('due') or '—'}"
+            rows.append(_line(x.get('title', 'Task'), href, meta))
+    if calls:
+        rows.append(_sec('Call today — overdue vs their own cadence'))
+        for r in calls:
+            href = links.deeplink('customer_data', 'customer', r['pid'], src='digest')
+            meta = (f"{int(r.get('overdue_days') or 0)}d past cycle · "
+                    f"est. missed {_m(r.get('est_missed'))}")
+            rows.append(_line(r.get('customer', '?'), href, meta))
+    if risk:
+        rows.append(_sec('Win-back — down vs last year'))
+        for r in risk:
+            href = links.deeplink('customer_data', 'customer', r['pid'], src='digest')
+            meta = f"{_m(r.get('at_risk'))} at risk · {r.get('status', '')}"
+            rows.append(_line(r.get('customer', '?'), href, meta))
+    if y_orders:
+        rows.append(_sec('Yesterday'))
+        # Wave 16: the Sales page is retired (registry row archived) — yesterday's orders now
+        # link to the Customer grid, the surface that carries the book. A link to an archived
+        # page would fall through to the landing and read as a broken link.
+        rows.append(_line(f"{y_orders} orders · {_m(y_rev)}",
+                          links.deeplink('customer_data', src='digest')))
+
+    scope = f"{agent}'s book" if agent else 'the whole book'
+    list_url = links.deeplink('customer_data', src='digest')
+    html_body = f"""
+<div style='font-family:Calibri,Arial,sans-serif;color:#1A2332;max-width:600px;margin:0 auto'>
+  <div style='border-top:3px solid {_GOLD};padding:16px 0 4px'>
+    <div style='font-size:18px;font-weight:700;color:{_NAVY}'>Your book this morning</div>
+    <div style='font-size:12px;color:{_MUTED}'>{t.strftime('%A, %B %d')} · {scope}</div>
+  </div>
+  <table style='width:100%;border-collapse:collapse'>{''.join(rows)}</table>
+  <div style='padding:16px 0;font-size:13px'>
+    <a href='{list_url}' style='color:{_NAVY};font-weight:700'>Open your Customer List →</a>
+  </div>
+  <div style='font-size:11px;color:{_MUTED};border-top:1px solid #ECEFF3;padding-top:8px'>
+    Internal daily digest from Loopable.
+    Sent only on days with something to act on.
+  </div>
+</div>"""
+    subject = f"Your book this morning — {n} to act on · {t.strftime('%b %d')}"
+    return subject, html_body, n
+
+
+def send_one(user, odoo=None, override_to=None):
+    """Build + queue one digest. Returns a short result string (never raises past itself)."""
+    to = override_to or user.get('email')
+    if not to:
+        return 'no-email'
+    subject, body, n = build(user)
+    if n == 0:
+        return 'empty-skip'
+    if not cs.safe_recipient_ok(to):
+        return 'safe-mode-blocked'
+    odoo = odoo or cs.Odoo()
+    mid = odoo.queue_mail({
+        'subject': subject, 'body_html': body,
+        'email_to': to, 'email_from': cs.SENDER_DISPLAY, 'reply_to': cs.REPLY_TO,
+        'mail_server_id': cs.ROYAL_MAIL_SERVER_ID, 'author_id': cs.ROYAL_AUTHOR_ID,
+        'state': 'outgoing', 'auto_delete': False,
+        # This Odoo runs the custom rt_multi_dba module whose mail-create hook browses
+        # env[mail.model].browse(mail.res_id) — a mail WITHOUT model/res_id crashes with
+        # KeyError: False (verified 2026-07-05). Anchor internal mail on the house partner
+        # (Royal Imports, cs.ROYAL_AUTHOR_ID) so nothing lands in a CUSTOMER's chatter.
+        'model': 'res.partner', 'res_id': cs.ROYAL_AUTHOR_ID,
+    })
+    return f'queued:{mid}'
+
+
+def run_due(force_user=None, override_to=None):
+    """The ticker entry point. Normal path: after UTC_HOUR on weekdays, send each active
+    emailed user their digest at most once per day (dedup via digest_log, including
+    empty-skips). force_user bypasses the schedule/dedup (the 'Send my digest now' button)
+    but NEVER the SAFE_MODE guardrail; forced sends are not logged (the 7am run still runs)."""
+    if not store.available():
+        return {}
+    now = dt.datetime.utcnow()
+    today = now.date().isoformat()
+    if force_user is None:
+        if not ENABLED:
+            return {}
+        if WEEKDAYS_ONLY and now.weekday() >= 5:
+            return {}
+        if now.hour < UTC_HOUR:
+            return {}
+    try:
+        reg = users.registry()
+    except Exception:
+        return {}
+    already = (store.get(KEY) or {}).get(today, {}) if force_user is None else {}
+    results = {}
+    odoo = None
+    for un, u in sorted(reg.items()):
+        if force_user is not None and un != force_user:
+            continue
+        if not u.get('active', True) or not u.get('email'):
+            continue
+        if force_user is None and un in already:
+            continue
+        pub = users._public(un, u)
+        try:
+            if odoo is None:
+                odoo = cs.Odoo()
+            results[un] = send_one(pub, odoo, override_to=override_to)
+        except cs.SafeModeBlocked:
+            results[un] = 'safe-mode-blocked'
+        except Exception as e:
+            results[un] = f'error:{str(e)[:80]}'
+    if force_user is None and results:
+        stamp = now.strftime('%H:%M')
+
+        def _rec(d):
+            day = d.setdefault(today, {})
+            for un, r in results.items():
+                day[un] = {'at': stamp, 'result': r}
+            return d
+        try:
+            store.update(KEY, _rec)
+        except Exception:
+            pass
+    return results
+
+
+def today_log():
+    return (store.get(KEY) or {}).get(dt.date.today().isoformat(), {})

platform/modules/pricing.py

@@ -1,395 +1,395 @@
-"""Pricing module — per-SKU economics for pricing decisions.
-
-For every SKU (LTM): units, revenue, unit cost, avg selling price, GROSS margin $/%, markup %
-(= revenue/COGS − 1), and a fully-loaded NET margin after allocating operating expenses to the SKU.
-
-COST-TO-SKU ALLOCATION (tiered, channel-scoped, SELECTABLE driver):
-  COGS is per-SKU already (Odoo Margin module). Operating expenses live per analytic
-  (Fisch/Royal/Amazon/HQ). Each channel pool = its analytic opex; we distribute it across that
-  channel's SKUs by a chosen DRIVER, and HQ overhead across all SKUs by the same driver:
-     pool_C   = channel_rate_C * Σ(channel revenue)        # rate-based magnitude (robust to Amazon
-     opex(sku)= Σ_C pool_C * driverC(sku)/Σ driverC  +  pool_HQ * driver(sku)/Σ driver
-                                                          #  invoice revenue not fully visible per-SKU)
-  Driver options:
-    - 'cogs'   : cost-weighted (default) — higher-cost items bear more overhead.
-    - 'cbm'    : physical size — units × volume (m³); BIGGER/bulkier SKUs absorb more (storage/freight/
-                 FBA scale with size). Volume is on ~24% of SKUs in Odoo; the rest are imputed at the
-                 category (else global) median volume. Weight is unusable (~0% populated).
-    - 'revenue': % of sale (reduces to channel_rate × revenue).
-    - 'units'  : per-unit.
-  net(sku) = gross_margin(sku) − opex(sku). NET is a decision estimate; GROSS (margin/markup) is exact.
-
-Brand-filterable: team_id None = all channels (incl Amazon); 5 = Fisch, 6 = Royal (wholesale scope).
-READ-ONLY.
-"""
-import sys
-import statistics
-import datetime as dt
-from pathlib import Path
-sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
-import core.odoo as O
-import core.periods as P
-
-_ANA = {1: 'Fisch', 2: 'Royal', 3: 'Amazon', 4: 'HQ', 5: 'Internal'}
-# Period: calendar 2025 (not LTM) so the pricing P&L ties to the 2025 P&L / GL / vendor analyses.
-_FY = ('2025-01-01', '2025-12-31')
-_FY_LABEL = 'FY2025'
-DRIVERS = {'cogs': 'COGS (cost-weighted)', 'cbm': 'CBM / volume (size)', 'revenue': 'Revenue', 'units': 'Units'}
-_DRIVER_SHORT = {'cogs': 'COGS', 'cbm': 'CBM', 'units': 'Units', 'revenue': 'Revenue'}
-
-
-def has_driver_data(row, driver):
-    """True if the SKU has REAL (not imputed / defaulted) data for the chosen allocation driver."""
-    if driver == 'cbm':
-        return bool(row.get('vol_known'))         # volume on file in Odoo (else category-median imputed)
-    if driver == 'cogs':
-        return (row.get('cogs') or 0) > 0         # has a real product cost (else uncosted)
-    if driver == 'units':
-        return (row.get('units') or 0) > 0
-    return (row.get('revenue') or 0) > 0          # revenue: always present in the table
-
-
-def rates(t=None):
-    """LTM opex rates per channel + HQ, from the analytic ledger. {channel: opex/revenue}."""
-    lf, lt = _FY
-    o = O.get_odoo()
-    rev = {_ANA.get(O.m2o_id(r['account_id'])): (r['amount'] or 0.0) for r in o.read_group(
-        'account.analytic.line', [('date', '>=', lf), ('date', '<=', lt),
-        ('general_account_id.account_type', 'in', ['income', 'income_other'])],
-        ['amount:sum', 'account_id'], ['account_id'], lazy=False) if O.m2o_id(r['account_id']) in _ANA}
-    opx = {_ANA.get(O.m2o_id(r['account_id'])): -(r['amount'] or 0.0) for r in o.read_group(
-        'account.analytic.line', [('date', '>=', lf), ('date', '<=', lt),
-        ('general_account_id.account_type', 'in', ['expense', 'expense_depreciation'])],
-        ['amount:sum', 'account_id'], ['account_id'], lazy=False) if O.m2o_id(r['account_id']) in _ANA}
-    tot_rev = sum(rev.values()) or 1.0
-    def rate(k):
-        return (opx.get(k, 0.0) / rev[k]) if rev.get(k) else 0.0
-    return {'Fisch': rate('Fisch'), 'Royal': rate('Royal'), 'Amazon': rate('Amazon'),
-            'HQ': (opx.get('HQ', 0.0) + opx.get('Internal', 0.0)) / tot_rev,
-            'window': _FY_LABEL, '_rev': rev, '_opex': opx, '_tot_rev': tot_rev}
-
-
-def _meta(pids):
-    prods = O.search_read('product.product', [('id', 'in', pids), ('active', 'in', [True, False])],
-                          ['default_code', 'name', 'categ_id', 'volume'])
-    cats = {}
-    for c in O.search_read('product.category', [], ['id', 'complete_name']):
-        parts = [x.strip() for x in (c['complete_name'] or '').split('/')]
-        cats[c['id']] = parts[1] if len(parts) >= 2 else (parts[0] if parts else None)
-    # median volume per category + global, to impute the SKUs without volume on file
-    by_cat = {}
-    allv = []
-    for p in prods:
-        v = p.get('volume') or 0.0
-        if v > 0:
-            allv.append(v)
-            by_cat.setdefault(O.m2o_id(p.get('categ_id')), []).append(v)
-    gmed = statistics.median(allv) if allv else 0.0
-    cmed = {c: statistics.median(vs) for c, vs in by_cat.items()}
-    out = {}
-    for p in prods:
-        cid = O.m2o_id(p.get('categ_id'))
-        v = p.get('volume') or 0.0
-        out[p['id']] = {'sku': p.get('default_code') or f"#{p['id']}", 'name': p.get('name') or '',
-                        'category': cats.get(cid) or '(uncategorized)',
-                        'volume': v, 'vol_used': v if v > 0 else (cmed.get(cid) or gmed), 'vol_known': v > 0}
-    return out
-
-
-def _build(team_id=None, driver='cogs', t=None):
-    t = t or P.today()
-    lf, lt = _FY
-    o = O.get_odoo()
-    rt = rates(t)
-    gift = list(O.excluded_partner_ids())
-    win = [('order_id.date_order', '>=', f'{lf} 00:00:00'), ('order_id.date_order', '<=', f'{lt} 23:59:59')]
-    sbase = [('order_id.state', 'in', ['sale', 'done']), ('product_id.type', '!=', 'service')] + win
-
-    def by_prod(extra, fields):
-        return {O.m2o_id(r['product_id']): r for r in o.read_group('sale.order.line', sbase + extra,
-                fields + ['product_id'], ['product_id'], lazy=False) if r.get('product_id')}
-
-    if team_id in (5, 6):                       # one wholesale BU
-        allc = by_prod([('order_id.team_id', '=', team_id), ('order_partner_id', 'not in', gift)],
-                       ['price_subtotal:sum', 'product_uom_qty:sum', 'margin:sum'])
-        chan_of = {pid: ('Fisch' if team_id == 5 else 'Royal') for pid in allc}
-        chan_rev = {pid: {('Fisch' if team_id == 5 else 'Royal'): (a['price_subtotal'] or 0.0)} for pid, a in allc.items()}
-    else:                                       # all channels
-        allc = by_prod([], ['price_subtotal:sum', 'product_uom_qty:sum', 'margin:sum'])
-        rf = by_prod([('order_id.team_id', '=', 5), ('order_partner_id', 'not in', gift)], ['price_subtotal:sum'])
-        rr = by_prod([('order_id.team_id', '=', 6), ('order_partner_id', 'not in', gift)], ['price_subtotal:sum'])
-        ra = by_prod([('order_partner_id', 'in', gift)] if gift else [('id', '=', -1)], ['price_subtotal:sum'])
-        chan_rev = {pid: {'Fisch': (rf.get(pid, {}).get('price_subtotal') or 0.0),
-                          'Royal': (rr.get(pid, {}).get('price_subtotal') or 0.0),
-                          'Amazon': (ra.get(pid, {}).get('price_subtotal') or 0.0)} for pid in allc}
-
-    meta = _meta(list(allc))
-    # assemble per-SKU base
-    skus = {}
-    for pid, a in allc.items():
-        rev = a['price_subtotal'] or 0.0
-        if rev <= 0:
-            continue
-        units = a['product_uom_qty'] or 0.0
-        gm = a['margin'] or 0.0
-        cogs = rev - gm
-        m = meta.get(pid, {})
-        skus[pid] = {'rev': rev, 'units': units, 'gm': gm, 'cogs': cogs, 'cr': chan_rev.get(pid, {}),
-                     'cbm': units * (m.get('vol_used') or 0.0), 'm': m}
-
-    # driver value per SKU + its apportionment to each channel (by revenue mix)
-    def dval(s):
-        return {'cogs': s['cogs'], 'cbm': s['cbm'], 'units': s['units'], 'revenue': s['rev']}.get(driver, s['cogs'])
-    chans = ['Fisch', 'Royal', 'Amazon']
-    pool = {C: rt[C] * sum(s['cr'].get(C, 0.0) for s in skus.values()) for C in chans}     # rate × visible channel rev
-    pool_hq = rt['HQ'] * sum(s['rev'] for s in skus.values())
-    sumdrvC = {C: sum(dval(s) * (s['cr'].get(C, 0.0) / s['rev']) for s in skus.values() if s['rev']) for C in chans}
-    sumdrv = sum(dval(s) for s in skus.values()) or 1.0
-
-    rows = []
-    for pid, s in skus.items():
-        load = pool_hq * (dval(s) / sumdrv)
-        for C in chans:
-            if sumdrvC[C] > 0 and s['rev']:
-                load += pool[C] * (dval(s) * (s['cr'].get(C, 0.0) / s['rev'])) / sumdrvC[C]
-        rev, gm, cogs, units = s['rev'], s['gm'], s['cogs'], s['units']
-        net = gm - load
-        m = s['m']
-        rows.append({
-            'product_id': pid, 'sku': m.get('sku', f'#{pid}'), 'code': m.get('sku', f'#{pid}'),
-            'product': m.get('name', ''), 'name': m.get('name', ''), 'category': m.get('category', '(uncategorized)'),
-            'units': units, 'revenue': rev, 'cogs': cogs,
-            'unit_cost': (cogs / units) if units else 0.0, 'avg_price': (rev / units) if units else 0.0,
-            'cbm_unit': m.get('volume', 0.0), 'cbm_used': m.get('vol_used', 0.0), 'cbm_total': s['cbm'],
-            'vol_known': m.get('vol_known', False), 'cbm_src': ('on file' if m.get('vol_known') else 'imputed'),
-            'gm_dollars': gm, 'gm_pct': (gm / rev * 100) if rev else 0.0,
-            'markup_pct': (gm / cogs * 100) if cogs > 0 else None,
-            'opex_load': load, 'opex_pct': (load / rev * 100) if rev else 0.0,
-            'net_dollars': net, 'net_pct': (net / rev * 100) if rev else 0.0,
-            'status': ('Below cost' if gm < 0 else 'Net-negative' if net < 0 else 'Thin (<10% net)' if (net / rev) < 0.10 else 'Healthy'),
-        })
-    rows.sort(key=lambda r: -r['revenue'])
-    return rows, rt
-
-
-def table(team_id=None, driver='cogs', t=None):
-    return _build(team_id, driver, t)[0]
-
-
-def summary(team_id=None, driver='cogs', t=None, built=None):
-    rows, rt = built or _build(team_id, driver, t)
-    rev = sum(r['revenue'] for r in rows)
-    gm = sum(r['gm_dollars'] for r in rows)
-    net = sum(r['net_dollars'] for r in rows)
-    mk = [r['markup_pct'] for r in rows if r['markup_pct'] is not None]
-    vol_known = sum(1 for r in rows if r['vol_known'])
-    driver_known = sum(1 for r in rows if has_driver_data(r, driver))
-    return {
-        'window': rt['window'], 'skus': len(rows), 'revenue': rev, 'driver': driver, 'driver_label': DRIVERS.get(driver, driver),
-        'driver_short': _DRIVER_SHORT.get(driver, driver),
-        'gm_dollars': gm, 'gm_pct': (gm / rev * 100) if rev else 0.0,
-        'net_dollars': net, 'net_pct': (net / rev * 100) if rev else 0.0,
-        'avg_markup': (sum(mk) / len(mk)) if mk else 0.0,
-        'below_cost_skus': sum(1 for r in rows if r['gm_dollars'] < 0),
-        'net_negative_skus': sum(1 for r in rows if r['net_dollars'] < 0),
-        'net_negative_rev': sum(r['revenue'] for r in rows if r['net_dollars'] < 0),
-        'vol_coverage': (vol_known / len(rows) * 100) if rows else 0.0,
-        'driver_known': driver_known, 'driver_coverage': (driver_known / len(rows) * 100) if rows else 0.0,
-        'rates': {k: round(rt[k] * 100, 1) for k in ('Fisch', 'Royal', 'Amazon', 'HQ')},
-    }
-
-
-def cost_drift(t=None, team_id=None):
-    """Replacement-cost drift from confirmed PO lines: the net price paid per unit in the LAST
-    12 months vs the 12 months BEFORE, per product, joined to what the SELL price did over the
-    same two windows (BU-scoped sell side; cost is company-wide). ERODING = cost up >5% while
-    the selling price followed by less than half — the margin leaks silently until repriced.
-    cost_impact_12m = (cost_now − cost_prior) × units sold last 12m (the annualized $ at stake)."""
-    t = t or P.today()
-    d24 = (t - dt.timedelta(days=730)).isoformat()
-    d12 = (t - dt.timedelta(days=365)).isoformat()
-    lines = O.search_read('purchase.order.line',
-                          [('order_id.state', 'in', ('purchase', 'done')),
-                           ('order_id.date_order', '>=', d24),
-                           ('product_qty', '>', 0), ('price_unit', '>', 0)],
-                          ['product_id', 'product_qty', 'product_uom_qty', 'price_subtotal',
-                           'order_id'])
-    oids = list({O.m2o_id(l['order_id']) for l in lines if l.get('order_id')})
-    od = {}
-    for i in range(0, len(oids), 5000):
-        for o_ in O.search_read('purchase.order', [('id', 'in', oids[i:i + 5000])], ['date_order']):
-            od[o_['id']] = str(o_['date_order'])[:10]
-    cur, prior = {}, {}                    # pid -> [net spend, qty]
-    for l in lines:
-        pid = O.m2o_id(l.get('product_id'))
-        d = od.get(O.m2o_id(l.get('order_id')))
-        if not pid or not d:
-            continue
-        e = (cur if d >= d12 else prior).setdefault(pid, [0.0, 0.0])
-        e[0] += l.get('price_subtotal') or 0.0
-        # BASE-UoM qty, so a piece→case purchase-UoM switch doesn't fake a price spike
-        e[1] += l.get('product_uom_qty') or l.get('product_qty') or 0.0
-    both = [p for p in cur if p in prior and prior[p][1] > 0 and cur[p][1] > 0]
-
-    def _sell(a, b_):
-        out = {}
-        for g in O.read_group('sale.order.line', O.sale_line_domain(a, b_, team_id),
-                              ['price_subtotal:sum', 'product_uom_qty:sum'], ['product_id'],
-                              lazy=False):
-            pid = O.m2o_id(g.get('product_id'))
-            if pid:
-                out[pid] = (g.get('price_subtotal') or 0.0, g.get('product_uom_qty') or 0.0)
-        return out
-    s_now, s_pri = _sell(d12, t.isoformat()), _sell(d24, d12)
-
-    meta = {}
-    for i in range(0, len(both), 5000):
-        for p in O.search_read('product.product',
-                               [('id', 'in', both[i:i + 5000]), ('active', 'in', [True, False])],
-                               ['default_code', 'name', 'standard_price']):
-            meta[p['id']] = p
-    rows = []
-    for pid in both:
-        c_now, c_pri = cur[pid][0] / cur[pid][1], prior[pid][0] / prior[pid][1]
-        if c_pri <= 0:
-            continue
-        rn, qn = s_now.get(pid, (0.0, 0.0))
-        rp, qp = s_pri.get(pid, (0.0, 0.0))
-        asp_now = rn / qn if qn else None
-        asp_pri = rp / qp if qp else None
-        p = meta.get(pid, {})
-        rows.append({'pid': pid, 'code': (p.get('default_code') or '').strip(),
-                     'product': p.get('name') or '',
-                     'cost_prior': c_pri, 'cost_now': c_now,
-                     'drift_pct': (c_now / c_pri - 1) * 100,
-                     'buy_qty_12m': cur[pid][1], 'std_cost': p.get('standard_price') or 0.0,
-                     'asp_now': asp_now, 'asp_prior': asp_pri,
-                     'price_chg_pct': ((asp_now / asp_pri - 1) * 100)
-                                      if (asp_now and asp_pri) else None,
-                     'units_12m': qn, 'cost_impact_12m': (c_now - c_pri) * qn,
-                     'gm_pct_now': ((asp_now - c_now) / asp_now * 100) if asp_now else None})
-    # a >3x (or <1/3) per-base-unit move is a UoM/master-data break, not market inflation —
-    # surfaced as its own data-quality list so it can't pollute the erosion signal
-    breaks = sorted((r for r in rows if not (1 / 3 <= (r['cost_now'] / r['cost_prior']) <= 3)),
-                    key=lambda r: -abs(r['drift_pct']))
-    broken = {r['pid'] for r in breaks}
-    eroding = sorted((r for r in rows
-                      if r['pid'] not in broken
-                      and r['drift_pct'] > 5 and (r['units_12m'] or 0) > 0
-                      and (r['price_chg_pct'] is None or r['price_chg_pct'] < r['drift_pct'] / 2)),
-                     key=lambda r: -(r['cost_impact_12m'] or 0))
-    improving = sorted((r for r in rows if r['pid'] not in broken
-                        and r['drift_pct'] < -5 and (r['units_12m'] or 0) > 0),
-                       key=lambda r: r['cost_impact_12m'])
-    return {'rows': rows, 'eroding': eroding, 'improving': improving, 'breaks': breaks,
-            'n_products': len(rows),
-            'erosion_total': sum(r['cost_impact_12m'] for r in eroding),
-            'tailwind_total': sum(r['cost_impact_12m'] for r in improving),
-            '_cur_spend': sum(e[0] for e in cur.values()),
-            '_cur_domain_from': d12, 'windows': (d24, d12, t.isoformat())}
-
-
-def cost_drift_validate(cd, t=None):
-    """The 12m PO spend our per-product weighting is built on == the server-side sum over the
-    identical domain (two independent aggregation paths)."""
-    t = t or P.today()
-    dom = [('order_id.state', 'in', ('purchase', 'done')),
-           ('order_id.date_order', '>=', cd['_cur_domain_from']),
-           ('product_qty', '>', 0), ('price_unit', '>', 0)]
-    srv = O.sum_field('purchase.order.line', dom, 'price_subtotal')
-    return [{'check': 'Cost drift: Σ(per-product 12m PO spend) == server Σ(line subtotal), same domain',
-             'a': round(cd['_cur_spend'], 2), 'b': round(srv, 2),
-             'gap': round(cd['_cur_spend'] - srv, 2),
-             'ok': abs(cd['_cur_spend'] - srv) <= max(1.0, abs(srv) * 0.001)}]
-
-
-def _pnl_entities(t=None):
-    """Actual LTM P&L per analytic entity (the basis the Management P&L is built from)."""
-    lf, lt = _FY
-    o = O.get_odoo()
-    def grp(types):
-        return {_ANA.get(O.m2o_id(r['account_id'])): (r['amount'] or 0.0) for r in o.read_group(
-            'account.analytic.line', [('date', '>=', lf), ('date', '<=', lt),
-            ('general_account_id.account_type', 'in', types)], ['amount:sum', 'account_id'], ['account_id'], lazy=False)
-            if O.m2o_id(r['account_id']) in _ANA}
-    inc, cog, opx = grp(['income', 'income_other']), grp(['expense_direct_cost']), grp(['expense', 'expense_depreciation'])
-    return {k: {'revenue': inc.get(k, 0.0), 'cogs': -cog.get(k, 0.0), 'opex': -opx.get(k, 0.0)} for k in _ANA.values()}
-
-
-def gl_pnl(t=None):
-    """Actual LTM P&L straight from the posted GL (the official books) — the independent reconciliation
-    target. Revenue − COGS − Opex = Net."""
-    lf, lt = _FY
-    def s(types):
-        return O.sum_field('account.move.line', [('parent_state', '=', 'posted'), ('date', '>=', lf),
-                           ('date', '<=', lt), ('account_id.account_type', 'in', types)], 'balance')
-    rev = -s(['income', 'income_other'])           # income is credit → flip to positive
-    cogs = s(['expense_direct_cost'])
-    opex = s(['expense', 'expense_depreciation'])
-    return {'revenue': rev, 'cogs': cogs, 'gm': rev - cogs, 'opex': opex, 'net': rev - cogs - opex}
-
-
-def reconcile(team_id=None, driver='cogs', t=None, built=None):
-    """Bridge the per-SKU P&L to the ACTUAL P&L: attributed SKUs + unattributed (Amazon-direct, not
-    booked per-SKU) = the displayed P&L. Ties by construction; the unattributed line is the residual."""
-    rows, rt = built or _build(team_id, driver, t)
-    ent = _pnl_entities(t)
-    tot_rev = sum(e['revenue'] for e in ent.values()) or 1.0
-    hq_rate = (ent['HQ']['opex'] + ent['Internal']['opex']) / tot_rev
-    if team_id in (5, 6):
-        k = 'Fisch' if team_id == 5 else 'Royal'
-        rev_t, cogs_t = ent[k]['revenue'], ent[k]['cogs']
-        opex_t = ent[k]['opex'] + hq_rate * ent[k]['revenue']          # BU opex + its share of HQ
-    else:
-        rev_t = sum(e['revenue'] for e in ent.values())
-        cogs_t = sum(e['cogs'] for e in ent.values())
-        opex_t = sum(e['opex'] for e in ent.values())                  # all opex incl HQ
-    net_t = rev_t - cogs_t - opex_t
-    rev_s = sum(r['revenue'] for r in rows)
-    gm_s = sum(r['gm_dollars'] for r in rows)
-    cogs_s, opex_s = rev_s - gm_s, sum(r['opex_load'] for r in rows)
-    net_s = gm_s - opex_s
-    una = {'revenue': rev_t - rev_s, 'cogs': cogs_t - cogs_s, 'gm': (rev_t - rev_s) - (cogs_t - cogs_s),
-           'opex': opex_t - opex_s, 'net': net_t - net_s}
-    pnl = {'revenue': rev_t, 'cogs': cogs_t, 'gm': rev_t - cogs_t, 'opex': opex_t, 'net': net_t}
-    sku = {'revenue': rev_s, 'cogs': cogs_s, 'gm': gm_s, 'opex': opex_s, 'net': net_s}
-    return {'pnl': pnl, 'sku': sku, 'unattrib': una, 'ties': abs((net_s + una['net']) - net_t) < 1.0}
-
-
-def page_data(team_id=None, driver='cogs', t=None):
-    """One build → rows + summary + reconciliation + validation (avoids rebuilding 4×)."""
-    built = _build(team_id, driver, t)
-    return {'rows': built[0], 'summary': summary(team_id, driver, t, built=built),
-            'reconcile': reconcile(team_id, driver, t, built=built),
-            'validation': validate(team_id, driver, t, built=built)}
-
-
-def validate(team_id=None, driver='cogs', t=None, built=None):
-    rows, rt = built or _build(team_id, driver, t)
-    checks = []
-    lf, lt = _FY
-    gift = list(O.excluded_partner_ids())
-    dom = [('order_id.state', 'in', ['sale', 'done']), ('order_id.date_order', '>=', f'{lf} 00:00:00'),
-           ('order_id.date_order', '<=', f'{lt} 23:59:59'), ('product_id.type', '!=', 'service'), ('price_subtotal', '>', 0)]
-    if team_id in (5, 6):
-        dom += [('order_id.team_id', '=', team_id), ('order_partner_id', 'not in', gift)]
-    indep = O.sum_field('sale.order.line', dom, 'price_subtotal')
-    ours = sum(r['revenue'] for r in rows)
-    checks.append({'check': 'Σ per-SKU revenue == scoped FY2025 (positive lines)', 'a': round(ours, 0),
-                   'b': round(indep, 0), 'gap': round(ours - indep, 0), 'ok': abs(ours - indep) <= max(50.0, indep * 0.01)})
-    if rows:
-        s = rows[0]
-        checks.append({'check': f"GM == revenue−COGS (sample {s['sku']})", 'a': round(s['gm_dollars'], 2),
-                       'b': round(s['revenue'] - s['cogs'], 2), 'gap': round(s['gm_dollars'] - (s['revenue'] - s['cogs']), 2),
-                       'ok': abs(s['gm_dollars'] - (s['revenue'] - s['cogs'])) <= 0.5})
-    # THE finance check — per-SKU P&L reconciles to the actual P&L (and that target ties to the posted GL)
-    rc = reconcile(team_id, driver, t, built=(rows, rt))
-    checks.append({'check': 'Attributed SKUs + unattributed net == P&L net (reconciles)',
-                   'a': round(rc['sku']['net'] + rc['unattrib']['net'], 0), 'b': round(rc['pnl']['net'], 0),
-                   'gap': round(rc['sku']['net'] + rc['unattrib']['net'] - rc['pnl']['net'], 0), 'ok': rc['ties']})
-    if team_id is None:
-        gl = gl_pnl(t)
-        checks.append({'check': 'P&L target (analytic) == posted GL net (actual books)',
-                       'a': round(rc['pnl']['net'], 0), 'b': round(gl['net'], 0),
-                       'gap': round(rc['pnl']['net'] - gl['net'], 0), 'ok': abs(rc['pnl']['net'] - gl['net']) <= 2.0})
-    return checks
+"""Pricing module — per-SKU economics for pricing decisions.
+
+For every SKU (LTM): units, revenue, unit cost, avg selling price, GROSS margin $/%, markup %
+(= revenue/COGS − 1), and a fully-loaded NET margin after allocating operating expenses to the SKU.
+
+COST-TO-SKU ALLOCATION (tiered, channel-scoped, SELECTABLE driver):
+  COGS is per-SKU already (Odoo Margin module). Operating expenses live per analytic
+  (Fisch/Royal/Amazon/HQ). Each channel pool = its analytic opex; we distribute it across that
+  channel's SKUs by a chosen DRIVER, and HQ overhead across all SKUs by the same driver:
+     pool_C   = channel_rate_C * Σ(channel revenue)        # rate-based magnitude (robust to Amazon
+     opex(sku)= Σ_C pool_C * driverC(sku)/Σ driverC  +  pool_HQ * driver(sku)/Σ driver
+                                                          #  invoice revenue not fully visible per-SKU)
+  Driver options:
+    - 'cogs'   : cost-weighted (default) — higher-cost items bear more overhead.
+    - 'cbm'    : physical size — units × volume (m³); BIGGER/bulkier SKUs absorb more (storage/freight/
+                 FBA scale with size). Volume is on ~24% of SKUs in Odoo; the rest are imputed at the
+                 category (else global) median volume. Weight is unusable (~0% populated).
+    - 'revenue': % of sale (reduces to channel_rate × revenue).
+    - 'units'  : per-unit.
+  net(sku) = gross_margin(sku) − opex(sku). NET is a decision estimate; GROSS (margin/markup) is exact.
+
+Brand-filterable: team_id None = all channels (incl Amazon); 5 = Fisch, 6 = Royal (wholesale scope).
+READ-ONLY.
+"""
+import sys
+import statistics
+import datetime as dt
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import core.odoo as O
+import core.periods as P
+
+_ANA = {1: 'Fisch', 2: 'Royal', 3: 'Amazon', 4: 'HQ', 5: 'Internal'}
+# Period: calendar 2025 (not LTM) so the pricing P&L ties to the 2025 P&L / GL / vendor analyses.
+_FY = ('2025-01-01', '2025-12-31')
+_FY_LABEL = 'FY2025'
+DRIVERS = {'cogs': 'COGS (cost-weighted)', 'cbm': 'CBM / volume (size)', 'revenue': 'Revenue', 'units': 'Units'}
+_DRIVER_SHORT = {'cogs': 'COGS', 'cbm': 'CBM', 'units': 'Units', 'revenue': 'Revenue'}
+
+
+def has_driver_data(row, driver):
+    """True if the SKU has REAL (not imputed / defaulted) data for the chosen allocation driver."""
+    if driver == 'cbm':
+        return bool(row.get('vol_known'))         # volume on file in Odoo (else category-median imputed)
+    if driver == 'cogs':
+        return (row.get('cogs') or 0) > 0         # has a real product cost (else uncosted)
+    if driver == 'units':
+        return (row.get('units') or 0) > 0
+    return (row.get('revenue') or 0) > 0          # revenue: always present in the table
+
+
+def rates(t=None):
+    """LTM opex rates per channel + HQ, from the analytic ledger. {channel: opex/revenue}."""
+    lf, lt = _FY
+    o = O.get_odoo()
+    rev = {_ANA.get(O.m2o_id(r['account_id'])): (r['amount'] or 0.0) for r in o.read_group(
+        'account.analytic.line', [('date', '>=', lf), ('date', '<=', lt),
+        ('general_account_id.account_type', 'in', ['income', 'income_other'])],
+        ['amount:sum', 'account_id'], ['account_id'], lazy=False) if O.m2o_id(r['account_id']) in _ANA}
+    opx = {_ANA.get(O.m2o_id(r['account_id'])): -(r['amount'] or 0.0) for r in o.read_group(
+        'account.analytic.line', [('date', '>=', lf), ('date', '<=', lt),
+        ('general_account_id.account_type', 'in', ['expense', 'expense_depreciation'])],
+        ['amount:sum', 'account_id'], ['account_id'], lazy=False) if O.m2o_id(r['account_id']) in _ANA}
+    tot_rev = sum(rev.values()) or 1.0
+    def rate(k):
+        return (opx.get(k, 0.0) / rev[k]) if rev.get(k) else 0.0
+    return {'Fisch': rate('Fisch'), 'Royal': rate('Royal'), 'Amazon': rate('Amazon'),
+            'HQ': (opx.get('HQ', 0.0) + opx.get('Internal', 0.0)) / tot_rev,
+            'window': _FY_LABEL, '_rev': rev, '_opex': opx, '_tot_rev': tot_rev}
+
+
+def _meta(pids):
+    prods = O.search_read('product.product', [('id', 'in', pids), ('active', 'in', [True, False])],
+                          ['default_code', 'name', 'categ_id', 'volume'])
+    cats = {}
+    for c in O.search_read('product.category', [], ['id', 'complete_name']):
+        parts = [x.strip() for x in (c['complete_name'] or '').split('/')]
+        cats[c['id']] = parts[1] if len(parts) >= 2 else (parts[0] if parts else None)
+    # median volume per category + global, to impute the SKUs without volume on file
+    by_cat = {}
+    allv = []
+    for p in prods:
+        v = p.get('volume') or 0.0
+        if v > 0:
+            allv.append(v)
+            by_cat.setdefault(O.m2o_id(p.get('categ_id')), []).append(v)
+    gmed = statistics.median(allv) if allv else 0.0
+    cmed = {c: statistics.median(vs) for c, vs in by_cat.items()}
+    out = {}
+    for p in prods:
+        cid = O.m2o_id(p.get('categ_id'))
+        v = p.get('volume') or 0.0
+        out[p['id']] = {'sku': p.get('default_code') or f"#{p['id']}", 'name': p.get('name') or '',
+                        'category': cats.get(cid) or '(uncategorized)',
+                        'volume': v, 'vol_used': v if v > 0 else (cmed.get(cid) or gmed), 'vol_known': v > 0}
+    return out
+
+
+def _build(team_id=None, driver='cogs', t=None):
+    t = t or P.today()
+    lf, lt = _FY
+    o = O.get_odoo()
+    rt = rates(t)
+    gift = list(O.excluded_partner_ids())
+    win = [('order_id.date_order', '>=', f'{lf} 00:00:00'), ('order_id.date_order', '<=', f'{lt} 23:59:59')]
+    sbase = [('order_id.state', 'in', ['sale', 'done']), ('product_id.type', '!=', 'service')] + win
+
+    def by_prod(extra, fields):
+        return {O.m2o_id(r['product_id']): r for r in o.read_group('sale.order.line', sbase + extra,
+                fields + ['product_id'], ['product_id'], lazy=False) if r.get('product_id')}
+
+    if team_id in (5, 6):                       # one wholesale BU
+        allc = by_prod([('order_id.team_id', '=', team_id), ('order_partner_id', 'not in', gift)],
+                       ['price_subtotal:sum', 'product_uom_qty:sum', 'margin:sum'])
+        chan_of = {pid: ('Fisch' if team_id == 5 else 'Royal') for pid in allc}
+        chan_rev = {pid: {('Fisch' if team_id == 5 else 'Royal'): (a['price_subtotal'] or 0.0)} for pid, a in allc.items()}
+    else:                                       # all channels
+        allc = by_prod([], ['price_subtotal:sum', 'product_uom_qty:sum', 'margin:sum'])
+        rf = by_prod([('order_id.team_id', '=', 5), ('order_partner_id', 'not in', gift)], ['price_subtotal:sum'])
+        rr = by_prod([('order_id.team_id', '=', 6), ('order_partner_id', 'not in', gift)], ['price_subtotal:sum'])
+        ra = by_prod([('order_partner_id', 'in', gift)] if gift else [('id', '=', -1)], ['price_subtotal:sum'])
+        chan_rev = {pid: {'Fisch': (rf.get(pid, {}).get('price_subtotal') or 0.0),
+                          'Royal': (rr.get(pid, {}).get('price_subtotal') or 0.0),
+                          'Amazon': (ra.get(pid, {}).get('price_subtotal') or 0.0)} for pid in allc}
+
+    meta = _meta(list(allc))
+    # assemble per-SKU base
+    skus = {}
+    for pid, a in allc.items():
+        rev = a['price_subtotal'] or 0.0
+        if rev <= 0:
+            continue
+        units = a['product_uom_qty'] or 0.0
+        gm = a['margin'] or 0.0
+        cogs = rev - gm
+        m = meta.get(pid, {})
+        skus[pid] = {'rev': rev, 'units': units, 'gm': gm, 'cogs': cogs, 'cr': chan_rev.get(pid, {}),
+                     'cbm': units * (m.get('vol_used') or 0.0), 'm': m}
+
+    # driver value per SKU + its apportionment to each channel (by revenue mix)
+    def dval(s):
+        return {'cogs': s['cogs'], 'cbm': s['cbm'], 'units': s['units'], 'revenue': s['rev']}.get(driver, s['cogs'])
+    chans = ['Fisch', 'Royal', 'Amazon']
+    pool = {C: rt[C] * sum(s['cr'].get(C, 0.0) for s in skus.values()) for C in chans}     # rate × visible channel rev
+    pool_hq = rt['HQ'] * sum(s['rev'] for s in skus.values())
+    sumdrvC = {C: sum(dval(s) * (s['cr'].get(C, 0.0) / s['rev']) for s in skus.values() if s['rev']) for C in chans}
+    sumdrv = sum(dval(s) for s in skus.values()) or 1.0
+
+    rows = []
+    for pid, s in skus.items():
+        load = pool_hq * (dval(s) / sumdrv)
+        for C in chans:
+            if sumdrvC[C] > 0 and s['rev']:
+                load += pool[C] * (dval(s) * (s['cr'].get(C, 0.0) / s['rev'])) / sumdrvC[C]
+        rev, gm, cogs, units = s['rev'], s['gm'], s['cogs'], s['units']
+        net = gm - load
+        m = s['m']
+        rows.append({
+            'product_id': pid, 'sku': m.get('sku', f'#{pid}'), 'code': m.get('sku', f'#{pid}'),
+            'product': m.get('name', ''), 'name': m.get('name', ''), 'category': m.get('category', '(uncategorized)'),
+            'units': units, 'revenue': rev, 'cogs': cogs,
+            'unit_cost': (cogs / units) if units else 0.0, 'avg_price': (rev / units) if units else 0.0,
+            'cbm_unit': m.get('volume', 0.0), 'cbm_used': m.get('vol_used', 0.0), 'cbm_total': s['cbm'],
+            'vol_known': m.get('vol_known', False), 'cbm_src': ('on file' if m.get('vol_known') else 'imputed'),
+            'gm_dollars': gm, 'gm_pct': (gm / rev * 100) if rev else 0.0,
+            'markup_pct': (gm / cogs * 100) if cogs > 0 else None,
+            'opex_load': load, 'opex_pct': (load / rev * 100) if rev else 0.0,
+            'net_dollars': net, 'net_pct': (net / rev * 100) if rev else 0.0,
+            'status': ('Below cost' if gm < 0 else 'Net-negative' if net < 0 else 'Thin (<10% net)' if (net / rev) < 0.10 else 'Healthy'),
+        })
+    rows.sort(key=lambda r: -r['revenue'])
+    return rows, rt
+
+
+def table(team_id=None, driver='cogs', t=None):
+    return _build(team_id, driver, t)[0]
+
+
+def summary(team_id=None, driver='cogs', t=None, built=None):
+    rows, rt = built or _build(team_id, driver, t)
+    rev = sum(r['revenue'] for r in rows)
+    gm = sum(r['gm_dollars'] for r in rows)
+    net = sum(r['net_dollars'] for r in rows)
+    mk = [r['markup_pct'] for r in rows if r['markup_pct'] is not None]
+    vol_known = sum(1 for r in rows if r['vol_known'])
+    driver_known = sum(1 for r in rows if has_driver_data(r, driver))
+    return {
+        'window': rt['window'], 'skus': len(rows), 'revenue': rev, 'driver': driver, 'driver_label': DRIVERS.get(driver, driver),
+        'driver_short': _DRIVER_SHORT.get(driver, driver),
+        'gm_dollars': gm, 'gm_pct': (gm / rev * 100) if rev else 0.0,
+        'net_dollars': net, 'net_pct': (net / rev * 100) if rev else 0.0,
+        'avg_markup': (sum(mk) / len(mk)) if mk else 0.0,
+        'below_cost_skus': sum(1 for r in rows if r['gm_dollars'] < 0),
+        'net_negative_skus': sum(1 for r in rows if r['net_dollars'] < 0),
+        'net_negative_rev': sum(r['revenue'] for r in rows if r['net_dollars'] < 0),
+        'vol_coverage': (vol_known / len(rows) * 100) if rows else 0.0,
+        'driver_known': driver_known, 'driver_coverage': (driver_known / len(rows) * 100) if rows else 0.0,
+        'rates': {k: round(rt[k] * 100, 1) for k in ('Fisch', 'Royal', 'Amazon', 'HQ')},
+    }
+
+
+def cost_drift(t=None, team_id=None):
+    """Replacement-cost drift from confirmed PO lines: the net price paid per unit in the LAST
+    12 months vs the 12 months BEFORE, per product, joined to what the SELL price did over the
+    same two windows (BU-scoped sell side; cost is company-wide). ERODING = cost up >5% while
+    the selling price followed by less than half — the margin leaks silently until repriced.
+    cost_impact_12m = (cost_now − cost_prior) × units sold last 12m (the annualized $ at stake)."""
+    t = t or P.today()
+    d24 = (t - dt.timedelta(days=730)).isoformat()
+    d12 = (t - dt.timedelta(days=365)).isoformat()
+    lines = O.search_read('purchase.order.line',
+                          [('order_id.state', 'in', ('purchase', 'done')),
+                           ('order_id.date_order', '>=', d24),
+                           ('product_qty', '>', 0), ('price_unit', '>', 0)],
+                          ['product_id', 'product_qty', 'product_uom_qty', 'price_subtotal',
+                           'order_id'])
+    oids = list({O.m2o_id(l['order_id']) for l in lines if l.get('order_id')})
+    od = {}
+    for i in range(0, len(oids), 5000):
+        for o_ in O.search_read('purchase.order', [('id', 'in', oids[i:i + 5000])], ['date_order']):
+            od[o_['id']] = str(o_['date_order'])[:10]
+    cur, prior = {}, {}                    # pid -> [net spend, qty]
+    for l in lines:
+        pid = O.m2o_id(l.get('product_id'))
+        d = od.get(O.m2o_id(l.get('order_id')))
+        if not pid or not d:
+            continue
+        e = (cur if d >= d12 else prior).setdefault(pid, [0.0, 0.0])
+        e[0] += l.get('price_subtotal') or 0.0
+        # BASE-UoM qty, so a piece→case purchase-UoM switch doesn't fake a price spike
+        e[1] += l.get('product_uom_qty') or l.get('product_qty') or 0.0
+    both = [p for p in cur if p in prior and prior[p][1] > 0 and cur[p][1] > 0]
+
+    def _sell(a, b_):
+        out = {}
+        for g in O.read_group('sale.order.line', O.sale_line_domain(a, b_, team_id),
+                              ['price_subtotal:sum', 'product_uom_qty:sum'], ['product_id'],
+                              lazy=False):
+            pid = O.m2o_id(g.get('product_id'))
+            if pid:
+                out[pid] = (g.get('price_subtotal') or 0.0, g.get('product_uom_qty') or 0.0)
+        return out
+    s_now, s_pri = _sell(d12, t.isoformat()), _sell(d24, d12)
+
+    meta = {}
+    for i in range(0, len(both), 5000):
+        for p in O.search_read('product.product',
+                               [('id', 'in', both[i:i + 5000]), ('active', 'in', [True, False])],
+                               ['default_code', 'name', 'standard_price']):
+            meta[p['id']] = p
+    rows = []
+    for pid in both:
+        c_now, c_pri = cur[pid][0] / cur[pid][1], prior[pid][0] / prior[pid][1]
+        if c_pri <= 0:
+            continue
+        rn, qn = s_now.get(pid, (0.0, 0.0))
+        rp, qp = s_pri.get(pid, (0.0, 0.0))
+        asp_now = rn / qn if qn else None
+        asp_pri = rp / qp if qp else None
+        p = meta.get(pid, {})
+        rows.append({'pid': pid, 'code': (p.get('default_code') or '').strip(),
+                     'product': p.get('name') or '',
+                     'cost_prior': c_pri, 'cost_now': c_now,
+                     'drift_pct': (c_now / c_pri - 1) * 100,
+                     'buy_qty_12m': cur[pid][1], 'std_cost': p.get('standard_price') or 0.0,
+                     'asp_now': asp_now, 'asp_prior': asp_pri,
+                     'price_chg_pct': ((asp_now / asp_pri - 1) * 100)
+                                      if (asp_now and asp_pri) else None,
+                     'units_12m': qn, 'cost_impact_12m': (c_now - c_pri) * qn,
+                     'gm_pct_now': ((asp_now - c_now) / asp_now * 100) if asp_now else None})
+    # a >3x (or <1/3) per-base-unit move is a UoM/master-data break, not market inflation —
+    # surfaced as its own data-quality list so it can't pollute the erosion signal
+    breaks = sorted((r for r in rows if not (1 / 3 <= (r['cost_now'] / r['cost_prior']) <= 3)),
+                    key=lambda r: -abs(r['drift_pct']))
+    broken = {r['pid'] for r in breaks}
+    eroding = sorted((r for r in rows
+                      if r['pid'] not in broken
+                      and r['drift_pct'] > 5 and (r['units_12m'] or 0) > 0
+                      and (r['price_chg_pct'] is None or r['price_chg_pct'] < r['drift_pct'] / 2)),
+                     key=lambda r: -(r['cost_impact_12m'] or 0))
+    improving = sorted((r for r in rows if r['pid'] not in broken
+                        and r['drift_pct'] < -5 and (r['units_12m'] or 0) > 0),
+                       key=lambda r: r['cost_impact_12m'])
+    return {'rows': rows, 'eroding': eroding, 'improving': improving, 'breaks': breaks,
+            'n_products': len(rows),
+            'erosion_total': sum(r['cost_impact_12m'] for r in eroding),
+            'tailwind_total': sum(r['cost_impact_12m'] for r in improving),
+            '_cur_spend': sum(e[0] for e in cur.values()),
+            '_cur_domain_from': d12, 'windows': (d24, d12, t.isoformat())}
+
+
+def cost_drift_validate(cd, t=None):
+    """The 12m PO spend our per-product weighting is built on == the server-side sum over the
+    identical domain (two independent aggregation paths)."""
+    t = t or P.today()
+    dom = [('order_id.state', 'in', ('purchase', 'done')),
+           ('order_id.date_order', '>=', cd['_cur_domain_from']),
+           ('product_qty', '>', 0), ('price_unit', '>', 0)]
+    srv = O.sum_field('purchase.order.line', dom, 'price_subtotal')
+    return [{'check': 'Cost drift: Σ(per-product 12m PO spend) == server Σ(line subtotal), same domain',
+             'a': round(cd['_cur_spend'], 2), 'b': round(srv, 2),
+             'gap': round(cd['_cur_spend'] - srv, 2),
+             'ok': abs(cd['_cur_spend'] - srv) <= max(1.0, abs(srv) * 0.001)}]
+
+
+def _pnl_entities(t=None):
+    """Actual LTM P&L per analytic entity (the basis the Management P&L is built from)."""
+    lf, lt = _FY
+    o = O.get_odoo()
+    def grp(types):
+        return {_ANA.get(O.m2o_id(r['account_id'])): (r['amount'] or 0.0) for r in o.read_group(
+            'account.analytic.line', [('date', '>=', lf), ('date', '<=', lt),
+            ('general_account_id.account_type', 'in', types)], ['amount:sum', 'account_id'], ['account_id'], lazy=False)
+            if O.m2o_id(r['account_id']) in _ANA}
+    inc, cog, opx = grp(['income', 'income_other']), grp(['expense_direct_cost']), grp(['expense', 'expense_depreciation'])
+    return {k: {'revenue': inc.get(k, 0.0), 'cogs': -cog.get(k, 0.0), 'opex': -opx.get(k, 0.0)} for k in _ANA.values()}
+
+
+def gl_pnl(t=None):
+    """Actual LTM P&L straight from the posted GL (the official books) — the independent reconciliation
+    target. Revenue − COGS − Opex = Net."""
+    lf, lt = _FY
+    def s(types):
+        return O.sum_field('account.move.line', [('parent_state', '=', 'posted'), ('date', '>=', lf),
+                           ('date', '<=', lt), ('account_id.account_type', 'in', types)], 'balance')
+    rev = -s(['income', 'income_other'])           # income is credit → flip to positive
+    cogs = s(['expense_direct_cost'])
+    opex = s(['expense', 'expense_depreciation'])
+    return {'revenue': rev, 'cogs': cogs, 'gm': rev - cogs, 'opex': opex, 'net': rev - cogs - opex}
+
+
+def reconcile(team_id=None, driver='cogs', t=None, built=None):
+    """Bridge the per-SKU P&L to the ACTUAL P&L: attributed SKUs + unattributed (Amazon-direct, not
+    booked per-SKU) = the displayed P&L. Ties by construction; the unattributed line is the residual."""
+    rows, rt = built or _build(team_id, driver, t)
+    ent = _pnl_entities(t)
+    tot_rev = sum(e['revenue'] for e in ent.values()) or 1.0
+    hq_rate = (ent['HQ']['opex'] + ent['Internal']['opex']) / tot_rev
+    if team_id in (5, 6):
+        k = 'Fisch' if team_id == 5 else 'Royal'
+        rev_t, cogs_t = ent[k]['revenue'], ent[k]['cogs']
+        opex_t = ent[k]['opex'] + hq_rate * ent[k]['revenue']          # BU opex + its share of HQ
+    else:
+        rev_t = sum(e['revenue'] for e in ent.values())
+        cogs_t = sum(e['cogs'] for e in ent.values())
+        opex_t = sum(e['opex'] for e in ent.values())                  # all opex incl HQ
+    net_t = rev_t - cogs_t - opex_t
+    rev_s = sum(r['revenue'] for r in rows)
+    gm_s = sum(r['gm_dollars'] for r in rows)
+    cogs_s, opex_s = rev_s - gm_s, sum(r['opex_load'] for r in rows)
+    net_s = gm_s - opex_s
+    una = {'revenue': rev_t - rev_s, 'cogs': cogs_t - cogs_s, 'gm': (rev_t - rev_s) - (cogs_t - cogs_s),
+           'opex': opex_t - opex_s, 'net': net_t - net_s}
+    pnl = {'revenue': rev_t, 'cogs': cogs_t, 'gm': rev_t - cogs_t, 'opex': opex_t, 'net': net_t}
+    sku = {'revenue': rev_s, 'cogs': cogs_s, 'gm': gm_s, 'opex': opex_s, 'net': net_s}
+    return {'pnl': pnl, 'sku': sku, 'unattrib': una, 'ties': abs((net_s + una['net']) - net_t) < 1.0}
+
+
+def page_data(team_id=None, driver='cogs', t=None):
+    """One build → rows + summary + reconciliation + validation (avoids rebuilding 4×)."""
+    built = _build(team_id, driver, t)
+    return {'rows': built[0], 'summary': summary(team_id, driver, t, built=built),
+            'reconcile': reconcile(team_id, driver, t, built=built),
+            'validation': validate(team_id, driver, t, built=built)}
+
+
+def validate(team_id=None, driver='cogs', t=None, built=None):
+    rows, rt = built or _build(team_id, driver, t)
+    checks = []
+    lf, lt = _FY
+    gift = list(O.excluded_partner_ids())
+    dom = [('order_id.state', 'in', ['sale', 'done']), ('order_id.date_order', '>=', f'{lf} 00:00:00'),
+           ('order_id.date_order', '<=', f'{lt} 23:59:59'), ('product_id.type', '!=', 'service'), ('price_subtotal', '>', 0)]
+    if team_id in (5, 6):
+        dom += [('order_id.team_id', '=', team_id), ('order_partner_id', 'not in', gift)]
+    indep = O.sum_field('sale.order.line', dom, 'price_subtotal')
+    ours = sum(r['revenue'] for r in rows)
+    checks.append({'check': 'Σ per-SKU revenue == scoped FY2025 (positive lines)', 'a': round(ours, 0),
+                   'b': round(indep, 0), 'gap': round(ours - indep, 0), 'ok': abs(ours - indep) <= max(50.0, indep * 0.01)})
+    if rows:
+        s = rows[0]
+        checks.append({'check': f"GM == revenue−COGS (sample {s['sku']})", 'a': round(s['gm_dollars'], 2),
+                       'b': round(s['revenue'] - s['cogs'], 2), 'gap': round(s['gm_dollars'] - (s['revenue'] - s['cogs']), 2),
+                       'ok': abs(s['gm_dollars'] - (s['revenue'] - s['cogs'])) <= 0.5})
+    # THE finance check — per-SKU P&L reconciles to the actual P&L (and that target ties to the posted GL)
+    rc = reconcile(team_id, driver, t, built=(rows, rt))
+    checks.append({'check': 'Attributed SKUs + unattributed net == P&L net (reconciles)',
+                   'a': round(rc['sku']['net'] + rc['unattrib']['net'], 0), 'b': round(rc['pnl']['net'], 0),
+                   'gap': round(rc['sku']['net'] + rc['unattrib']['net'] - rc['pnl']['net'], 0), 'ok': rc['ties']})
+    if team_id is None:
+        gl = gl_pnl(t)
+        checks.append({'check': 'P&L target (analytic) == posted GL net (actual books)',
+                       'a': round(rc['pnl']['net'], 0), 'b': round(gl['net'], 0),
+                       'gap': round(rc['pnl']['net'] - gl['net'], 0), 'ok': abs(rc['pnl']['net'] - gl['net']) <= 2.0})
+    return checks

requirements.txt

@@ -1,47 +1,47 @@
-# AIOS web API — the FastAPI backend + the platform data-layer deps it reuses.
-#
-# ⛔ STREAMLIT IS GONE (EXIT-6, 2026-08-04) — do not add it back. The line here read
-# `streamlit==1.58.0` with the comment "included only because the shared modules/core may import
-# it at load; it is never served". That stopped being true when the shared layer was cleaned, and
-# it stayed in THIS file — the one the Dockerfile actually installs — while `api/requirements.txt`
-# had already dropped it and a gate reported the omission "verified". ~250 MB of image for a
-# package nothing imported.
-#
-# The lesson is the file, not the package: the PINNED intent and the SHIPPED manifest are two
-# different documents, and checking only the one you wrote is how the other rots.
-# `api/verify_no_streamlit.py` now checks BOTH, and proves the API imports with streamlit,
-# plotly, altair, openpyxl, reportlab and jinja2 all blocked at sys.meta_path.
-# No altair/plotly/reportlab either — those were Streamlit UI/export only. openpyxl RETURNED in
-# wave 21 (C5) as a LAZY dep of routes_uploads.py — the boot proof above still holds because the
-# import lives inside the handler, and the gate now asserts this line exists here.
-fastapi>=0.139
-uvicorn[standard]>=0.30
-python-dotenv>=1.0
-pandas>=2.0
-requests>=2.28
-huggingface_hub>=0.20
-duckdb>=1.0
-pyyaml>=6.0
-pillow>=10.0
-beautifulsoup4>=4.12
-lxml>=5.0
-cryptography>=42.0
-# ⭐ WAVE 20 (R1 / D-4) — THE POSTGRES DRIVER, AND IT IS LOAD-BEARING IN THIS FILE SPECIFICALLY.
-# `core/store_pg.py` is the store backend from this wave on, and it is deliberately FAIL-CLOSED:
-# `_pool()` raises rather than falling back to the HF file store, so a container that gets
-# `STORE_BACKEND=pg` without this line does not degrade — it refuses every request that touches
-# the store, which is every authenticated request.
-#
-# ⛔ AND THIS IS THE FILE THAT MATTERS: the Dockerfile does `COPY requirements.txt` from the
-# Space root, i.e. THIS manifest, not `api/requirements.txt`. That header's own streamlit story
-# is the same defect in the other direction — the pinned intent and the shipped manifest are two
-# documents. psycopg is now in BOTH, and `ops/verify_portability.py` gates the pair.
-psycopg[binary,pool]>=3.2
-# ⭐ WAVE 21 (item 11, C5) — .xlsx preview for Select-from-file; lazy-imported in
-# routes_uploads.py only. verify_no_streamlit asserts this line in BOTH manifests.
-openpyxl>=3.1
-# ⛔ AND ITS TRANSPORT, learned from a RUNTIME_ERROR on the first v6 boot: FastAPI demands
-# python-multipart AT IMPORT TIME for any route declaring File(...)/Form(...). Every local gate
-# was green because the dev box happens to have it for unrelated reasons — the container
-# installs exactly this file. The environment-parity twin of the streamlit lesson above.
-python-multipart>=0.0.20
+# AIOS web API — the FastAPI backend + the platform data-layer deps it reuses.
+#
+# ⛔ STREAMLIT IS GONE (EXIT-6, 2026-08-04) — do not add it back. The line here read
+# `streamlit==1.58.0` with the comment "included only because the shared modules/core may import
+# it at load; it is never served". That stopped being true when the shared layer was cleaned, and
+# it stayed in THIS file — the one the Dockerfile actually installs — while `api/requirements.txt`
+# had already dropped it and a gate reported the omission "verified". ~250 MB of image for a
+# package nothing imported.
+#
+# The lesson is the file, not the package: the PINNED intent and the SHIPPED manifest are two
+# different documents, and checking only the one you wrote is how the other rots.
+# `api/verify_no_streamlit.py` now checks BOTH, and proves the API imports with streamlit,
+# plotly, altair, openpyxl, reportlab and jinja2 all blocked at sys.meta_path.
+# No altair/plotly/reportlab either — those were Streamlit UI/export only. openpyxl RETURNED in
+# wave 21 (C5) as a LAZY dep of routes_uploads.py — the boot proof above still holds because the
+# import lives inside the handler, and the gate now asserts this line exists here.
+fastapi>=0.139
+uvicorn[standard]>=0.30
+python-dotenv>=1.0
+pandas>=2.0
+requests>=2.28
+huggingface_hub>=0.20
+duckdb>=1.0
+pyyaml>=6.0
+pillow>=10.0
+beautifulsoup4>=4.12
+lxml>=5.0
+cryptography>=42.0
+# ⭐ WAVE 20 (R1 / D-4) — THE POSTGRES DRIVER, AND IT IS LOAD-BEARING IN THIS FILE SPECIFICALLY.
+# `core/store_pg.py` is the store backend from this wave on, and it is deliberately FAIL-CLOSED:
+# `_pool()` raises rather than falling back to the HF file store, so a container that gets
+# `STORE_BACKEND=pg` without this line does not degrade — it refuses every request that touches
+# the store, which is every authenticated request.
+#
+# ⛔ AND THIS IS THE FILE THAT MATTERS: the Dockerfile does `COPY requirements.txt` from the
+# Space root, i.e. THIS manifest, not `api/requirements.txt`. That header's own streamlit story
+# is the same defect in the other direction — the pinned intent and the shipped manifest are two
+# documents. psycopg is now in BOTH, and `ops/verify_portability.py` gates the pair.
+psycopg[binary,pool]>=3.2
+# ⭐ WAVE 21 (item 11, C5) — .xlsx preview for Select-from-file; lazy-imported in
+# routes_uploads.py only. verify_no_streamlit asserts this line in BOTH manifests.
+openpyxl>=3.1
+# ⛔ AND ITS TRANSPORT, learned from a RUNTIME_ERROR on the first v6 boot: FastAPI demands
+# python-multipart AT IMPORT TIME for any route declaring File(...)/Form(...). Every local gate
+# was green because the dev box happens to have it for unrelated reasons — the container
+# installs exactly this file. The environment-parity twin of the streamlit lesson above.
+python-multipart>=0.0.20

web/public/sample_customers.json

@@ -1,529 +1,529 @@
-{
-  "fields": [
-    {
-      "key": "customer",
-      "label": "Customer",
-      "type": "text",
-      "source": "odoo",
-      "pinned": true,
-      "default": true,
-      "description": "The customer's name in Odoo. One row per customer who ordered in the last 24 months."
-    },
-    {
-      "key": "odoo_status",
-      "label": "Odoo record",
-      "type": "status",
-      "source": "odoo",
-      "default": false,
-      "description": "Whether this customer still exists in Odoo. Archived means deleted there."
-    },
-    {
-      "key": "agent",
-      "label": "Agent",
-      "type": "text",
-      "source": "odoo",
-      "default": true,
-      "description": "The sales agent who owns this account."
-    },
-    {
-      "key": "dba",
-      "label": "DBA",
-      "type": "select",
-      "source": "odoo",
-      "default": false,
-      "options": [
-        "Fisch",
-        "Royal",
-        "Both"
-      ],
-      "description": "The brand this customer buys from - Fisch, Royal, or both. Amazon-channel orders are not a DBA."
-    },
-    {
-      "key": "salesperson",
-      "label": "Salesperson",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "Who keyed in most of this customer's orders — not the Agent, who owns the account."
-    },
-    {
-      "key": "city",
-      "label": "City",
-      "type": "text",
-      "source": "odoo",
-      "default": true,
-      "description": "City on the customer's Odoo address."
-    },
-    {
-      "key": "state",
-      "label": "State",
-      "type": "text",
-      "source": "odoo",
-      "default": true,
-      "description": "State or province on the customer's Odoo address."
-    },
-    {
-      "key": "country",
-      "label": "Country",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "Country on the customer's Odoo address."
-    },
-    {
-      "key": "zip",
-      "label": "ZIP",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "Postal code on the customer's Odoo address."
-    },
-    {
-      "key": "customer_since",
-      "label": "Customer since",
-      "type": "date",
-      "source": "odoo",
-      "default": false,
-      "description": "When this customer was first set up in Odoo."
-    },
-    {
-      "key": "tags",
-      "label": "Tags",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "Odoo labels on this customer, comma-separated."
-    },
-    {
-      "key": "pricelist",
-      "label": "Price list",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "The price list this customer buys on."
-    },
-    {
-      "key": "payment_terms",
-      "label": "Payment terms",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "Payment terms on this customer's account — Net 30, for example."
-    },
-    {
-      "key": "last_order",
-      "label": "Last order",
-      "type": "date",
-      "source": "odoo",
-      "default": true,
-      "description": "Date of the most recent confirmed order."
-    },
-    {
-      "key": "overdue_days",
-      "label": "Overdue days",
-      "type": "int",
-      "source": "odoo",
-      "default": true,
-      "description": "How many days late this customer is running against their own usual ordering rhythm."
-    },
-    {
-      "_note": "filterable:false — DERIVED ANALYTIC: est_missed is min(cycles missed, 3) x AOV, a score we compute rather than an object the business has, so a condition on it would read as a fact about the customer when it is a fact about our arithmetic. It still displays and still sorts. Until wave 6 this flag also covered the frozen-window presets (revenue_ytd / revenue_ly / orders_24m / aov / yoy_pct); those are now DELETED outright under the owner's no-buildable-presets rule — see _comment. est_missed itself STAYS: no creatable measure or formula reproduces the cadence model behind it.",
-      "key": "est_missed",
-      "label": "Est. missed $",
-      "type": "currency",
-      "source": "odoo",
-      "default": true,
-      "agg": "sum",
-      "filterable": false,
-      "description": "Estimated sales missed while quiet: missed orders (capped at 3) times average order value. An estimate, not money owed."
-    },
-    {
-      "_note": "wave 21 R1 — KEY UNCHANGED, LABEL RENAMED. The computation is a DISJOINT split (ar.py credit_exposure): this column is only the not-yet-due residual, its sibling is the past-grace residual, and the two sum to the total. Under the label 'AR open $' the majority-late book read as 'Overdue > Open', which is nonsense in AR vocabulary — 'open' universally means the total. The label now says what the number is; the key stays so saved views and filters keep working.",
-      "key": "ar_open",
-      "label": "AR current $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "Invoiced money owed but not yet due (a 5-day grace applies before it counts as overdue)."
-    },
-    {
-      "key": "ar_overdue",
-      "label": "AR overdue $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "Invoiced money past due — same basis as the Collections page."
-    },
-    {
-      "_note": "wave 21 R1 — the TOTAL, added beside the rename above. AR current $ + AR overdue $, i.e. what most people mean by 'open AR'. Composed from the same ar.credit_exposure rows the siblings use, so it is transitively reconciled by ar.validate()'s residual read_group tie — no second oracle.",
-      "key": "ar_outstanding",
-      "label": "AR outstanding $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "Total invoiced money owed right now: AR current $ plus AR overdue $."
-    },
-    {
-      "key": "ar_exposure",
-      "label": "Credit exposure $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "The most you could be out if they stopped paying today: open, overdue, draft and not-yet-invoiced."
-    },
-    {
-      "key": "ar_aged_1_30",
-      "label": "1-30 days $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "Overdue between 1 and 30 days. The four aging buckets sum to AR overdue $."
-    },
-    {
-      "key": "ar_aged_31_60",
-      "label": "31-60 days $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "Overdue between 31 and 60 days. The four aging buckets sum to AR overdue $."
-    },
-    {
-      "key": "ar_aged_61_90",
-      "label": "61-90 days $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "Overdue between 61 and 90 days. The four aging buckets sum to AR overdue $."
-    },
-    {
-      "key": "ar_aged_90_plus",
-      "label": "90+ days $",
-      "type": "currency",
-      "source": "odoo",
-      "default": false,
-      "description": "Overdue by more than 90 days. The four aging buckets sum to AR overdue $."
-    },
-    {
-      "key": "days_to_pay",
-      "label": "Days to pay",
-      "type": "int",
-      "source": "odoo",
-      "default": false,
-      "description": "Average days to pay an invoice in full. Blank means no fully paid invoice yet."
-    },
-    {
-      "key": "top_category",
-      "label": "Top category",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "The category this customer spent the most on in the last 12 months."
-    },
-    {
-      "key": "top_category_pct",
-      "label": "Top category %",
-      "type": "pct",
-      "source": "odoo",
-      "default": false,
-      "description": "Share of last-12-months spend that went to the top category."
-    },
-    {
-      "key": "sku_count",
-      "label": "SKUs bought",
-      "type": "int",
-      "source": "odoo",
-      "default": false,
-      "description": "Distinct products bought in the last 12 months."
-    },
-    {
-      "key": "top_sku",
-      "label": "Top SKU",
-      "type": "text",
-      "source": "odoo",
-      "default": false,
-      "description": "The product this customer spent the most on in the last 12 months."
-    },
-    {
-      "key": "days_since",
-      "label": "Days since order",
-      "type": "int",
-      "source": "odoo",
-      "default": false,
-      "description": "Days since the last confirmed order."
-    },
-    {
-      "key": "typical_gap_days",
-      "label": "Typical gap days",
-      "type": "int",
-      "source": "odoo",
-      "default": false,
-      "description": "Days this customer usually goes between orders, from their own history."
-    },
-    {
-      "key": "notes",
-      "label": "Notes",
-      "type": "text",
-      "source": "overlay",
-      "default": false,
-      "description": "Your notes on this customer. Saved in this app only, visible only to you."
-    }
-  ],
-  "rows": [
-    {
-      "pid": 101,
-      "customer": "Poppy Flowers",
-      "status": "New",
-      "agent": "Naomi Linnell Rivera",
-      "city": "Charlottesville",
-      "state": "Virginia (US)",
-      "last_order": "2026-07-21",
-      "est_missed": 0,
-      "notes": "",
-      "country": "United States",
-      "zip": "02720",
-      "payment_terms": "30 Days",
-      "pricelist": "Fisch 1 (USD)",
-      "tags": "Royal",
-      "customer_since": "2023-01-10",
-      "salesperson": "Jessica",
-      "ar_open": 0,
-      "ar_overdue": 0,
-      "ar_exposure": 0,
-      "top_category": "Styrofoam",
-      "top_category_pct": 0.47,
-      "sku_count": 93,
-      "top_sku": "AQUAFOAM FLORAL FOAM BRICK | 48-Piece per Pack",
-      "days_to_pay": 34,
-      "_created": "2023-01-15 09:10:00",
-      "lat": 25.7617,
-      "lon": -80.1918,
-      "odoo_status": "Archived",
-      "dba": "Royal",
-      "ar_outstanding": 0
-    },
-    {
-      "pid": 102,
-      "customer": "Meadow & Vine Wholesale",
-      "status": "Growing",
-      "agent": "Carla Jimenez",
-      "city": "Portland",
-      "state": "Oregon (US)",
-      "last_order": "2026-07-19",
-      "est_missed": 0,
-      "notes": "Expanding to a second storefront.",
-      "country": "United States",
-      "zip": "77041",
-      "payment_terms": "Immediate Payment",
-      "pricelist": "Royal 1 (USD)",
-      "tags": "Royal, Key account",
-      "customer_since": "2024-02-11",
-      "salesperson": "Naomi",
-      "ar_open": 1240.5,
-      "ar_overdue": 0,
-      "ar_exposure": 1740.5,
-      "top_category": "Ribbon",
-      "top_category_pct": 0.95,
-      "sku_count": 4,
-      "top_sku": "2\" X 24\" X 36\" GREEN STYROFOAM BOARD",
-      "days_to_pay": null,
-      "_created": "2023-02-15 09:11:00",
-      "lat": 27.9506,
-      "lon": -82.4572,
-      "odoo_status": "Active",
-      "dba": "Fisch",
-      "ar_outstanding": 1240.5
-    },
-    {
-      "pid": 103,
-      "customer": "Bluestem Floral Supply",
-      "status": "Growing",
-      "agent": "Naomi Linnell Rivera",
-      "city": "Kansas City",
-      "state": "Missouri (US)",
-      "last_order": "2026-07-17",
-      "est_missed": 0,
-      "notes": "",
-      "country": "United States",
-      "zip": "11219",
-      "payment_terms": "60 Days",
-      "pricelist": "Royal 1 (USD)",
-      "tags": "Fisch",
-      "customer_since": "2025-03-12",
-      "salesperson": "Karen",
-      "ar_open": 0,
-      "ar_overdue": 5120.25,
-      "ar_exposure": 5120.25,
-      "top_category": "Foams & Finishes",
-      "top_category_pct": 0.31,
-      "sku_count": 27,
-      "top_sku": "SATIN RIBBON 2IN",
-      "days_to_pay": 61,
-      "_created": "2023-03-15 09:12:00",
-      "lat": 28.5384,
-      "lon": -81.3789,
-      "odoo_status": "Active",
-      "dba": "Both",
-      "ar_outstanding": 5120.25
-    },
-    {
-      "pid": 104,
-      "customer": "Camellia Row Florist",
-      "status": "Declining",
-      "agent": "Devon Marsh",
-      "city": "Savannah",
-      "state": "Georgia (US)",
-      "last_order": "2026-05-30",
-      "est_missed": 41200,
-      "notes": "Switched some volume to a local grower.",
-      "country": "United States",
-      "zip": "07649",
-      "payment_terms": "30 Days",
-      "pricelist": "Fisch 1 (USD)",
-      "tags": "(none)",
-      "customer_since": "2026-04-13",
-      "salesperson": "(none)",
-      "ar_open": 8300,
-      "ar_overdue": 940,
-      "ar_exposure": 11440,
-      "top_category": "All",
-      "top_category_pct": 1.0,
-      "sku_count": 1,
-      "top_sku": "(none)",
-      "days_to_pay": 12,
-      "_created": "2023-04-15 09:13:00",
-      "lat": 30.3322,
-      "lon": -81.6557,
-      "odoo_status": "Active",
-      "dba": "Royal",
-      "ar_outstanding": 9240
-    },
-    {
-      "pid": 105,
-      "customer": "Harborlight Wholesale Blooms",
-      "status": "Growing",
-      "agent": "Carla Jimenez",
-      "city": "Seattle",
-      "state": "Washington (US)",
-      "last_order": "2026-07-22",
-      "est_missed": 0,
-      "notes": "Top-10 account.",
-      "country": "United States",
-      "zip": "33125",
-      "payment_terms": "Immediate Payment",
-      "pricelist": "Royal 1 (USD)",
-      "tags": "Royal",
-      "customer_since": "2023-05-14",
-      "salesperson": "Jessica",
-      "ar_open": 0,
-      "ar_overdue": 0,
-      "ar_exposure": 0,
-      "top_category": "Styrofoam",
-      "top_category_pct": 0.47,
-      "sku_count": 93,
-      "top_sku": "AQUAFOAM FLORAL FOAM BRICK | 48-Piece per Pack",
-      "days_to_pay": 34,
-      "_created": "2023-05-15 09:14:00",
-      "lat": 26.1224,
-      "lon": -80.1373,
-      "odoo_status": "Active",
-      "dba": "",
-      "ar_outstanding": 0
-    },
-    {
-      "pid": 106,
-      "customer": "Dogwood & Fern Co.",
-      "status": "Dormant",
-      "agent": "Devon Marsh",
-      "city": "Asheville",
-      "state": "North Carolina (US)",
-      "last_order": "2026-02-11",
-      "est_missed": 52400,
-      "notes": "No spring order this year.",
-      "country": "United States",
-      "zip": "90210",
-      "payment_terms": "60 Days",
-      "pricelist": "Royal 1 (USD)",
-      "tags": "Royal, Key account",
-      "customer_since": "2024-06-15",
-      "salesperson": "Naomi",
-      "ar_open": 1240.5,
-      "ar_overdue": 0,
-      "ar_exposure": 1740.5,
-      "top_category": "Ribbon",
-      "top_category_pct": 0.95,
-      "sku_count": 4,
-      "top_sku": "2\" X 24\" X 36\" GREEN STYROFOAM BOARD",
-      "days_to_pay": null,
-      "_created": "2023-06-15 09:15:00",
-      "lat": 27.3364,
-      "lon": -82.5307,
-      "odoo_status": "Active",
-      "dba": "Fisch",
-      "ar_outstanding": 1240.5
-    },
-    {
-      "pid": 107,
-      "customer": "Verbena Market Florals",
-      "status": "Lost",
-      "agent": "Naomi Linnell Rivera",
-      "city": "Austin",
-      "state": "Texas (US)",
-      "last_order": "2025-11-04",
-      "est_missed": 78300,
-      "notes": "Went with a competitor on freight terms.",
-      "country": "United States",
-      "zip": "08701",
-      "payment_terms": "30 Days",
-      "pricelist": "Fisch 1 (USD)",
-      "tags": "Fisch",
-      "customer_since": "2025-07-16",
-      "salesperson": "Karen",
-      "ar_open": 0,
-      "ar_overdue": 5120.25,
-      "ar_exposure": 5120.25,
-      "top_category": "Foams & Finishes",
-      "top_category_pct": 0.31,
-      "sku_count": 27,
-      "top_sku": "SATIN RIBBON 2IN",
-      "days_to_pay": 61,
-      "_created": "2023-07-15 09:16:00",
-      "lat": null,
-      "lon": null,
-      "odoo_status": "Active",
-      "dba": "Both",
-      "ar_outstanding": 5120.25
-    },
-    {
-      "pid": 108,
-      "customer": "Larkspur Lane Supply",
-      "status": "New",
-      "agent": "Carla Jimenez",
-      "city": "Denver",
-      "state": "Colorado (US)",
-      "last_order": "2026-07-14",
-      "est_missed": 0,
-      "notes": "First order in April.",
-      "country": "United States",
-      "zip": "60614",
-      "payment_terms": "Immediate Payment",
-      "pricelist": "Royal 1 (USD)",
-      "tags": "(none)",
-      "customer_since": "2026-08-17",
-      "salesperson": "(none)",
-      "ar_open": 8300,
-      "ar_overdue": 940,
-      "ar_exposure": 11440,
-      "top_category": "All",
-      "top_category_pct": 1.0,
-      "sku_count": 1,
-      "top_sku": "(none)",
-      "days_to_pay": 12,
-      "_created": "2023-08-15 09:17:00",
-      "lat": 33.749,
-      "lon": -84.388,
-      "odoo_status": "Active",
-      "dba": "Royal",
-      "ar_outstanding": 9240
-    }
-  ]
-}
+{
+  "fields": [
+    {
+      "key": "customer",
+      "label": "Customer",
+      "type": "text",
+      "source": "odoo",
+      "pinned": true,
+      "default": true,
+      "description": "The customer's name in Odoo. One row per customer who ordered in the last 24 months."
+    },
+    {
+      "key": "odoo_status",
+      "label": "Odoo record",
+      "type": "status",
+      "source": "odoo",
+      "default": false,
+      "description": "Whether this customer still exists in Odoo. Archived means deleted there."
+    },
+    {
+      "key": "agent",
+      "label": "Agent",
+      "type": "text",
+      "source": "odoo",
+      "default": true,
+      "description": "The sales agent who owns this account."
+    },
+    {
+      "key": "dba",
+      "label": "DBA",
+      "type": "select",
+      "source": "odoo",
+      "default": false,
+      "options": [
+        "Fisch",
+        "Royal",
+        "Both"
+      ],
+      "description": "The brand this customer buys from - Fisch, Royal, or both. Amazon-channel orders are not a DBA."
+    },
+    {
+      "key": "salesperson",
+      "label": "Salesperson",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "Who keyed in most of this customer's orders — not the Agent, who owns the account."
+    },
+    {
+      "key": "city",
+      "label": "City",
+      "type": "text",
+      "source": "odoo",
+      "default": true,
+      "description": "City on the customer's Odoo address."
+    },
+    {
+      "key": "state",
+      "label": "State",
+      "type": "text",
+      "source": "odoo",
+      "default": true,
+      "description": "State or province on the customer's Odoo address."
+    },
+    {
+      "key": "country",
+      "label": "Country",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "Country on the customer's Odoo address."
+    },
+    {
+      "key": "zip",
+      "label": "ZIP",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "Postal code on the customer's Odoo address."
+    },
+    {
+      "key": "customer_since",
+      "label": "Customer since",
+      "type": "date",
+      "source": "odoo",
+      "default": false,
+      "description": "When this customer was first set up in Odoo."
+    },
+    {
+      "key": "tags",
+      "label": "Tags",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "Odoo labels on this customer, comma-separated."
+    },
+    {
+      "key": "pricelist",
+      "label": "Price list",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "The price list this customer buys on."
+    },
+    {
+      "key": "payment_terms",
+      "label": "Payment terms",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "Payment terms on this customer's account — Net 30, for example."
+    },
+    {
+      "key": "last_order",
+      "label": "Last order",
+      "type": "date",
+      "source": "odoo",
+      "default": true,
+      "description": "Date of the most recent confirmed order."
+    },
+    {
+      "key": "overdue_days",
+      "label": "Overdue days",
+      "type": "int",
+      "source": "odoo",
+      "default": true,
+      "description": "How many days late this customer is running against their own usual ordering rhythm."
+    },
+    {
+      "_note": "filterable:false — DERIVED ANALYTIC: est_missed is min(cycles missed, 3) x AOV, a score we compute rather than an object the business has, so a condition on it would read as a fact about the customer when it is a fact about our arithmetic. It still displays and still sorts. Until wave 6 this flag also covered the frozen-window presets (revenue_ytd / revenue_ly / orders_24m / aov / yoy_pct); those are now DELETED outright under the owner's no-buildable-presets rule — see _comment. est_missed itself STAYS: no creatable measure or formula reproduces the cadence model behind it.",
+      "key": "est_missed",
+      "label": "Est. missed $",
+      "type": "currency",
+      "source": "odoo",
+      "default": true,
+      "agg": "sum",
+      "filterable": false,
+      "description": "Estimated sales missed while quiet: missed orders (capped at 3) times average order value. An estimate, not money owed."
+    },
+    {
+      "_note": "wave 21 R1 — KEY UNCHANGED, LABEL RENAMED. The computation is a DISJOINT split (ar.py credit_exposure): this column is only the not-yet-due residual, its sibling is the past-grace residual, and the two sum to the total. Under the label 'AR open $' the majority-late book read as 'Overdue > Open', which is nonsense in AR vocabulary — 'open' universally means the total. The label now says what the number is; the key stays so saved views and filters keep working.",
+      "key": "ar_open",
+      "label": "AR current $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "Invoiced money owed but not yet due (a 5-day grace applies before it counts as overdue)."
+    },
+    {
+      "key": "ar_overdue",
+      "label": "AR overdue $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "Invoiced money past due — same basis as the Collections page."
+    },
+    {
+      "_note": "wave 21 R1 — the TOTAL, added beside the rename above. AR current $ + AR overdue $, i.e. what most people mean by 'open AR'. Composed from the same ar.credit_exposure rows the siblings use, so it is transitively reconciled by ar.validate()'s residual read_group tie — no second oracle.",
+      "key": "ar_outstanding",
+      "label": "AR outstanding $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "Total invoiced money owed right now: AR current $ plus AR overdue $."
+    },
+    {
+      "key": "ar_exposure",
+      "label": "Credit exposure $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "The most you could be out if they stopped paying today: open, overdue, draft and not-yet-invoiced."
+    },
+    {
+      "key": "ar_aged_1_30",
+      "label": "1-30 days $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "Overdue between 1 and 30 days. The four aging buckets sum to AR overdue $."
+    },
+    {
+      "key": "ar_aged_31_60",
+      "label": "31-60 days $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "Overdue between 31 and 60 days. The four aging buckets sum to AR overdue $."
+    },
+    {
+      "key": "ar_aged_61_90",
+      "label": "61-90 days $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "Overdue between 61 and 90 days. The four aging buckets sum to AR overdue $."
+    },
+    {
+      "key": "ar_aged_90_plus",
+      "label": "90+ days $",
+      "type": "currency",
+      "source": "odoo",
+      "default": false,
+      "description": "Overdue by more than 90 days. The four aging buckets sum to AR overdue $."
+    },
+    {
+      "key": "days_to_pay",
+      "label": "Days to pay",
+      "type": "int",
+      "source": "odoo",
+      "default": false,
+      "description": "Average days to pay an invoice in full. Blank means no fully paid invoice yet."
+    },
+    {
+      "key": "top_category",
+      "label": "Top category",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "The category this customer spent the most on in the last 12 months."
+    },
+    {
+      "key": "top_category_pct",
+      "label": "Top category %",
+      "type": "pct",
+      "source": "odoo",
+      "default": false,
+      "description": "Share of last-12-months spend that went to the top category."
+    },
+    {
+      "key": "sku_count",
+      "label": "SKUs bought",
+      "type": "int",
+      "source": "odoo",
+      "default": false,
+      "description": "Distinct products bought in the last 12 months."
+    },
+    {
+      "key": "top_sku",
+      "label": "Top SKU",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "The product this customer spent the most on in the last 12 months."
+    },
+    {
+      "key": "days_since",
+      "label": "Days since order",
+      "type": "int",
+      "source": "odoo",
+      "default": false,
+      "description": "Days since the last confirmed order."
+    },
+    {
+      "key": "typical_gap_days",
+      "label": "Typical gap days",
+      "type": "int",
+      "source": "odoo",
+      "default": false,
+      "description": "Days this customer usually goes between orders, from their own history."
+    },
+    {
+      "key": "notes",
+      "label": "Notes",
+      "type": "text",
+      "source": "overlay",
+      "default": false,
+      "description": "Your notes on this customer. Saved in this app only, visible only to you."
+    }
+  ],
+  "rows": [
+    {
+      "pid": 101,
+      "customer": "Poppy Flowers",
+      "status": "New",
+      "agent": "Naomi Linnell Rivera",
+      "city": "Charlottesville",
+      "state": "Virginia (US)",
+      "last_order": "2026-07-21",
+      "est_missed": 0,
+      "notes": "",
+      "country": "United States",
+      "zip": "02720",
+      "payment_terms": "30 Days",
+      "pricelist": "Fisch 1 (USD)",
+      "tags": "Royal",
+      "customer_since": "2023-01-10",
+      "salesperson": "Jessica",
+      "ar_open": 0,
+      "ar_overdue": 0,
+      "ar_exposure": 0,
+      "top_category": "Styrofoam",
+      "top_category_pct": 0.47,
+      "sku_count": 93,
+      "top_sku": "AQUAFOAM FLORAL FOAM BRICK | 48-Piece per Pack",
+      "days_to_pay": 34,
+      "_created": "2023-01-15 09:10:00",
+      "lat": 25.7617,
+      "lon": -80.1918,
+      "odoo_status": "Archived",
+      "dba": "Royal",
+      "ar_outstanding": 0
+    },
+    {
+      "pid": 102,
+      "customer": "Meadow & Vine Wholesale",
+      "status": "Growing",
+      "agent": "Carla Jimenez",
+      "city": "Portland",
+      "state": "Oregon (US)",
+      "last_order": "2026-07-19",
+      "est_missed": 0,
+      "notes": "Expanding to a second storefront.",
+      "country": "United States",
+      "zip": "77041",
+      "payment_terms": "Immediate Payment",
+      "pricelist": "Royal 1 (USD)",
+      "tags": "Royal, Key account",
+      "customer_since": "2024-02-11",
+      "salesperson": "Naomi",
+      "ar_open": 1240.5,
+      "ar_overdue": 0,
+      "ar_exposure": 1740.5,
+      "top_category": "Ribbon",
+      "top_category_pct": 0.95,
+      "sku_count": 4,
+      "top_sku": "2\" X 24\" X 36\" GREEN STYROFOAM BOARD",
+      "days_to_pay": null,
+      "_created": "2023-02-15 09:11:00",
+      "lat": 27.9506,
+      "lon": -82.4572,
+      "odoo_status": "Active",
+      "dba": "Fisch",
+      "ar_outstanding": 1240.5
+    },
+    {
+      "pid": 103,
+      "customer": "Bluestem Floral Supply",
+      "status": "Growing",
+      "agent": "Naomi Linnell Rivera",
+      "city": "Kansas City",
+      "state": "Missouri (US)",
+      "last_order": "2026-07-17",
+      "est_missed": 0,
+      "notes": "",
+      "country": "United States",
+      "zip": "11219",
+      "payment_terms": "60 Days",
+      "pricelist": "Royal 1 (USD)",
+      "tags": "Fisch",
+      "customer_since": "2025-03-12",
+      "salesperson": "Karen",
+      "ar_open": 0,
+      "ar_overdue": 5120.25,
+      "ar_exposure": 5120.25,
+      "top_category": "Foams & Finishes",
+      "top_category_pct": 0.31,
+      "sku_count": 27,
+      "top_sku": "SATIN RIBBON 2IN",
+      "days_to_pay": 61,
+      "_created": "2023-03-15 09:12:00",
+      "lat": 28.5384,
+      "lon": -81.3789,
+      "odoo_status": "Active",
+      "dba": "Both",
+      "ar_outstanding": 5120.25
+    },
+    {
+      "pid": 104,
+      "customer": "Camellia Row Florist",
+      "status": "Declining",
+      "agent": "Devon Marsh",
+      "city": "Savannah",
+      "state": "Georgia (US)",
+      "last_order": "2026-05-30",
+      "est_missed": 41200,
+      "notes": "Switched some volume to a local grower.",
+      "country": "United States",
+      "zip": "07649",
+      "payment_terms": "30 Days",
+      "pricelist": "Fisch 1 (USD)",
+      "tags": "(none)",
+      "customer_since": "2026-04-13",
+      "salesperson": "(none)",
+      "ar_open": 8300,
+      "ar_overdue": 940,
+      "ar_exposure": 11440,
+      "top_category": "All",
+      "top_category_pct": 1.0,
+      "sku_count": 1,
+      "top_sku": "(none)",
+      "days_to_pay": 12,
+      "_created": "2023-04-15 09:13:00",
+      "lat": 30.3322,
+      "lon": -81.6557,
+      "odoo_status": "Active",
+      "dba": "Royal",
+      "ar_outstanding": 9240
+    },
+    {
+      "pid": 105,
+      "customer": "Harborlight Wholesale Blooms",
+      "status": "Growing",
+      "agent": "Carla Jimenez",
+      "city": "Seattle",
+      "state": "Washington (US)",
+      "last_order": "2026-07-22",
+      "est_missed": 0,
+      "notes": "Top-10 account.",
+      "country": "United States",
+      "zip": "33125",
+      "payment_terms": "Immediate Payment",
+      "pricelist": "Royal 1 (USD)",
+      "tags": "Royal",
+      "customer_since": "2023-05-14",
+      "salesperson": "Jessica",
+      "ar_open": 0,
+      "ar_overdue": 0,
+      "ar_exposure": 0,
+      "top_category": "Styrofoam",
+      "top_category_pct": 0.47,
+      "sku_count": 93,
+      "top_sku": "AQUAFOAM FLORAL FOAM BRICK | 48-Piece per Pack",
+      "days_to_pay": 34,
+      "_created": "2023-05-15 09:14:00",
+      "lat": 26.1224,
+      "lon": -80.1373,
+      "odoo_status": "Active",
+      "dba": "",
+      "ar_outstanding": 0
+    },
+    {
+      "pid": 106,
+      "customer": "Dogwood & Fern Co.",
+      "status": "Dormant",
+      "agent": "Devon Marsh",
+      "city": "Asheville",
+      "state": "North Carolina (US)",
+      "last_order": "2026-02-11",
+      "est_missed": 52400,
+      "notes": "No spring order this year.",
+      "country": "United States",
+      "zip": "90210",
+      "payment_terms": "60 Days",
+      "pricelist": "Royal 1 (USD)",
+      "tags": "Royal, Key account",
+      "customer_since": "2024-06-15",
+      "salesperson": "Naomi",
+      "ar_open": 1240.5,
+      "ar_overdue": 0,
+      "ar_exposure": 1740.5,
+      "top_category": "Ribbon",
+      "top_category_pct": 0.95,
+      "sku_count": 4,
+      "top_sku": "2\" X 24\" X 36\" GREEN STYROFOAM BOARD",
+      "days_to_pay": null,
+      "_created": "2023-06-15 09:15:00",
+      "lat": 27.3364,
+      "lon": -82.5307,
+      "odoo_status": "Active",
+      "dba": "Fisch",
+      "ar_outstanding": 1240.5
+    },
+    {
+      "pid": 107,
+      "customer": "Verbena Market Florals",
+      "status": "Lost",
+      "agent": "Naomi Linnell Rivera",
+      "city": "Austin",
+      "state": "Texas (US)",
+      "last_order": "2025-11-04",
+      "est_missed": 78300,
+      "notes": "Went with a competitor on freight terms.",
+      "country": "United States",
+      "zip": "08701",
+      "payment_terms": "30 Days",
+      "pricelist": "Fisch 1 (USD)",
+      "tags": "Fisch",
+      "customer_since": "2025-07-16",
+      "salesperson": "Karen",
+      "ar_open": 0,
+      "ar_overdue": 5120.25,
+      "ar_exposure": 5120.25,
+      "top_category": "Foams & Finishes",
+      "top_category_pct": 0.31,
+      "sku_count": 27,
+      "top_sku": "SATIN RIBBON 2IN",
+      "days_to_pay": 61,
+      "_created": "2023-07-15 09:16:00",
+      "lat": null,
+      "lon": null,
+      "odoo_status": "Active",
+      "dba": "Both",
+      "ar_outstanding": 5120.25
+    },
+    {
+      "pid": 108,
+      "customer": "Larkspur Lane Supply",
+      "status": "New",
+      "agent": "Carla Jimenez",
+      "city": "Denver",
+      "state": "Colorado (US)",
+      "last_order": "2026-07-14",
+      "est_missed": 0,
+      "notes": "First order in April.",
+      "country": "United States",
+      "zip": "60614",
+      "payment_terms": "Immediate Payment",
+      "pricelist": "Royal 1 (USD)",
+      "tags": "(none)",
+      "customer_since": "2026-08-17",
+      "salesperson": "(none)",
+      "ar_open": 8300,
+      "ar_overdue": 940,
+      "ar_exposure": 11440,
+      "top_category": "All",
+      "top_category_pct": 1.0,
+      "sku_count": 1,
+      "top_sku": "(none)",
+      "days_to_pay": 12,
+      "_created": "2023-08-15 09:17:00",
+      "lat": 33.749,
+      "lon": -84.388,
+      "odoo_status": "Active",
+      "dba": "Royal",
+      "ar_outstanding": 9240
+    }
+  ]
+}

web/src/alerts/AlertsPane.tsx

@@ -1,329 +1,329 @@
-// ---------------------------------------------------------------------------
-// alerts/AlertsPane.tsx — WAVE 20 item 25 (C-ALERT): the inbox.
-//
-// Two lists, one panel, and the order is the point: what HAPPENED first, what is
-// WATCHING second. An inbox that opens on its own configuration is a settings
-// screen wearing a bell.
-//
-// A drawer rather than a route, for the same reason the AI note is a modal: the
-// nav is server-filtered and an undeclared surface is denied by design (this
-// shell has no client-invented pages). Alerts are not a granted module — they
-// are this account's own inbox over its own views.
-// ---------------------------------------------------------------------------
-
-import { useCallback, useEffect, useState } from "react";
-import {
-  deleteAlert,
-  fetchAlerts,
-  fetchInbox,
-  markRead,
-  runAlert,
-} from "./alertsApi";
-import {
-  EMPTY_INBOX,
-  applyRead,
-  inboxOrder,
-  isAutomationOutcome,
-  isAutomationReview,
-  routeForTopic,
-  stampText,
-} from "./alertsModel";
-import type { Alert, Inbox, Notification } from "./alertsModel";
-// WAVE 27 C5 — the ONE generated loop mark, consumed rather than redrawn (C7's rule).
-import { Mark } from "../shell/Brand";
-
-/** The clock face this pane uses for its one glyph — drawn, never an emoji. */
-function BellIcon() {
-  return (
-    <svg className="alerts-bell" viewBox="0 0 16 16" aria-hidden="true">
-      <path d="M8 2.2a3.6 3.6 0 0 1 3.6 3.6v2.4l1.2 2H3.2l1.2-2V5.8A3.6 3.6 0 0 1 8 2.2Z" />
-      <path d="M6.6 12.6a1.5 1.5 0 0 0 2.8 0" />
-    </svg>
-  );
-}
-
-export default function AlertsPane({
-  onClose,
-  onOpenView,
-  onOpenAutomation,
-  onInbox,
-  onToast,
-}: {
-  onClose: () => void;
-  /** Navigate to the alert's view. The FRAME owns routing; this pane owns the row. */
-  onOpenView: (topic: string, viewId: string) => void;
-  /**
-   * WAVE 23 (C6, wiring W23-W5) — the same division for a REVIEW notification: the frame routes
-   * to `#/automation` and asks the surface to select this automation.
-   *
-   * ⛔ REQUIRED, NOT OPTIONAL, and that is the wave-20 lesson written into a type. An optional
-   * callback the frame forgot to pass degrades to "clicking a review notification does nothing",
-   * which is indistinguishable from "the feature was never built" and goes red in no gate. A
-   * required prop fails `tsc` the moment it is unmounted.
-   */
-  onOpenAutomation: (autoId: string, stageId?: string) => void;
-  /** Hand the freshly-read inbox back so the nav badge and the pane agree. */
-  onInbox: (inbox: Inbox) => void;
-  onToast: (message: string) => void;
-}) {
-  const [inbox, setInbox] = useState<Inbox>(EMPTY_INBOX);
-  const [alerts, setAlerts] = useState<Alert[]>([]);
-  const [error, setError] = useState("");
-  const [busy, setBusy] = useState(false);
-
-  const publish = useCallback(
-    (next: Inbox) => {
-      setInbox(next);
-      onInbox(next);
-    },
-    [onInbox]
-  );
-
-  const load = useCallback(async () => {
-    const [inboxRes, alertRes] = await Promise.all([fetchInbox(), fetchAlerts()]);
-    if (inboxRes.ok) publish(inboxRes.value);
-    else setError(inboxRes.message);
-    if (alertRes.ok) setAlerts(alertRes.value);
-  }, [publish]);
-
-  useEffect(() => {
-    void load();
-  }, [load]);
-
-  // ⛔ Escape closes it, like every other panel in this shell — a scrim with no
-  // keyboard way out is a trap (the wave-18 lesson, kept).
-  useEffect(() => {
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape") onClose();
-    };
-    window.addEventListener("keydown", onKey);
-    return () => window.removeEventListener("keydown", onKey);
-  }, [onClose]);
-
-  const toggleRead = useCallback(
-    (n: Notification) => {
-      // Optimistic, with the server's own convention (`ids`, `read`) sent
-      // explicitly — and reverted out loud if the write is refused, because a
-      // badge that silently disagrees with the list is how a reader learns to
-      // stop trusting it.
-      const before = inbox;
-      publish(applyRead(inbox, [n.id], !n.read));
-      void markRead([n.id], !n.read).then((r) => {
-        if (!r.ok) {
-          publish(before);
-          onToast(r.message);
-        }
-      });
-    },
-    [inbox, publish, onToast]
-  );
-
-  const markAll = useCallback(() => {
-    const before = inbox;
-    publish(applyRead(inbox, null, true));
-    void markRead(null, true).then((r) => {
-      if (!r.ok) {
-        publish(before);
-        onToast(r.message);
-      }
-    });
-  }, [inbox, publish, onToast]);
-
-  const open = useCallback(
-    (n: Notification) => {
-      if (!n.read) {
-        publish(applyRead(inbox, [n.id], true));
-        void markRead([n.id], true);
-      }
-      // ⛔ WAVE 23 C6 — THE KIND BRANCH COMES FIRST, AND ITS ORDER IS THE WHOLE FIX. A review
-      // notification has no `topic` a grid could render, so the view guard below would have
-      // caught every one of them and told the reader their table was "no longer available" —
-      // a confidently wrong sentence about a feature that is working. The destination decides
-      // which guard applies, so the destination is decided first.
-      if (isAutomationReview(n)) {
-        onOpenAutomation(n.autoId!, n.stageId);
-        onClose();
-        return;
-      }
-      // ⭐ WAVE 27 C5 — a RUN OUTCOME routes to its automation too, and it carries the id in
-      // `alertId` rather than `autoId` (`core.alerts.notify`'s shape, not `_queue_review`'s).
-      // Beside the review branch and after it: a review notification satisfies BOTH predicates,
-      // and only the review one knows about the stage to scroll to.
-      if (isAutomationOutcome(n)) {
-        onOpenAutomation(n.alertId, undefined);
-        onClose();
-        return;
-      }
-      // A route this client cannot resolve opens NOTHING and says so — alerts
-      // outlive the surfaces they were made from.
-      if (!routeForTopic(n.topic)) {
-        onToast("That alert's table is no longer available to this account.");
-        return;
-      }
-      onOpenView(n.topic, n.viewId);
-      onClose();
-    },
-    [inbox, publish, onOpenView, onOpenAutomation, onClose, onToast]
-  );
-
-  const rows = inboxOrder(inbox.items);
-
-  return (
-    <div className="shell-newdb-scrim" onClick={onClose}>
-      <aside
-        className="alerts-pane"
-        role="dialog"
-        aria-label="Alerts"
-        onClick={(e) => e.stopPropagation()}
-      >
-        <header className="alerts-head">
-          <h2>
-            <BellIcon /> Alerts
-          </h2>
-          <button
-            type="button"
-            className="alerts-markall"
-            disabled={inbox.unread === 0}
-            onClick={markAll}
-          >
-            Mark all read
-          </button>
-        </header>
-
-        {error ? <p className="shell-newdb-err">{error}</p> : null}
-
-        <div className="alerts-scroll">
-          {rows.length === 0 ? (
-            <p className="alerts-empty">
-              Nothing new. An alert watches ONE view and tells you when a record it had
-              never matched arrives in it — make one from a view's ··· menu.
-            </p>
-          ) : (
-            <ul className="alerts-list">
-              {rows.map((n) => (
-                <li key={n.id} className={"alerts-row" + (n.read ? "" : " is-unread")}>
-                  <button
-                    type="button"
-                    className="alerts-row-main"
-                    onClick={() => open(n)}
-                    // The hover names the DESTINATION, which is now two different places.
-                    // "Open the alert's view" over a review notification described a journey
-                    // the click does not take.
-                    title={
-                      isAutomationReview(n) || isAutomationOutcome(n)
-                        ? "Open the automation"
-                        : `Open ${n.alertLabel || "the alert's view"}`
-                    }
-                  >
-                    {/* ⭐ WAVE 27 C5 — an automation's row wears the LOOP MARK.
-                        ⛔ NOT A STATUS DOT, and not a second one: wave-26 R14 deleted every
-                        status dot in the automation module on the grounds that *"these
-                        automations are basically loops"*, and a run that FAILED is already said
-                        in `n.label` (the run summary) in words. A coloured dot here would
-                        reintroduce, in the inbox, the vocabulary that was deleted from the
-                        surface it points at.
-                        ⛔ The generated `Mark`, never a redrawn path: `shell/Brand.tsx`'s header
-                        records a hand-copied version silently painting LAST WAVE'S BRAND while
-                        a comment claimed parity. */}
-                    <span className="alerts-row-label">
-                      {isAutomationOutcome(n) || isAutomationReview(n) ? (
-                        // ⚠ INSIDE the label span, not beside it. `.alerts-row-main` is a flex
-                        // COLUMN, so a sibling here becomes a third ROW stacked above the text
-                        // ([[wrong-parent-not-broken-control]]); inline, it sits on the line it
-                        // annotates and rides the same ellipsis.
-                        <span className="alerts-row-mark">
-                          <Mark size={12} />
-                        </span>
-                      ) : null}
-                      {n.label}
-                    </span>
-                    <span className="alerts-row-meta">
-                      {n.alertLabel ? `${n.alertLabel} · ` : ""}
-                      {/* Readable, but never re-derived: `stampText` is string surgery
-                          over the server's own UTC-with-offset stamp (D-18). Parsing it
-                          into a browser Date is how a tenant a day ahead gets told an
-                          event happened tomorrow. */}
-                      {stampText(n.at)}
-                    </span>
-                  </button>
-                  <button
-                    type="button"
-                    className="alerts-row-toggle"
-                    aria-label={n.read ? `Mark ${n.label} unread` : `Mark ${n.label} read`}
-                    title={n.read ? "Mark unread" : "Mark read"}
-                    onClick={() => toggleRead(n)}
-                  >
-                    {/* The ACTION, not the state: "Read" beside an unread row reads as
-                        a label for the row itself. */}
-                    {n.read ? "Mark unread" : "Mark read"}
-                  </button>
-                </li>
-              ))}
-            </ul>
-          )}
-
-          {alerts.length > 0 ? (
-            <section className="alerts-watching">
-              <h3>Watching</h3>
-              {alerts.map((a) => (
-                <div key={a.id} className="alerts-watch-row">
-                  <span className="alerts-watch-label">{a.label}</span>
-                  <span className="alerts-watch-meta">
-                    {/* The remembered set's SIZE, which is what "no news" means here:
-                        an alert with 40 matches and nothing new is working. */}
-                    {a.matched.toLocaleString()} matched
-                    {a.lastError ? ` · ${a.lastError}` : ""}
-                  </span>
-                  <button
-                    type="button"
-                    className="alerts-watch-run"
-                    disabled={busy}
-                    onClick={() => {
-                      setBusy(true);
-                      void runAlert(a.id).then((r) => {
-                        setBusy(false);
-                        if (!r.ok) return onToast(r.message);
-                        const v = r.value as { new?: unknown[]; skipped?: string };
-                        onToast(
-                          v?.skipped
-                            ? `Skipped: ${v.skipped}`
-                            : `${(v?.new ?? []).length} new since the last check.`
-                        );
-                        void load();
-                      });
-                    }}
-                  >
-                    Check now
-                  </button>
-                  <button
-                    type="button"
-                    className="alerts-watch-del"
-                    disabled={busy}
-                    aria-label={`Delete the alert ${a.label}`}
-                    onClick={() => {
-                      setBusy(true);
-                      void deleteAlert(a.id).then((r) => {
-                        setBusy(false);
-                        if (!r.ok) return onToast(r.message);
-                        setAlerts((cur) => cur.filter((x) => x.id !== a.id));
-                        void load();
-                      });
-                    }}
-                  >
-                    Delete
-                  </button>
-                </div>
-              ))}
-            </section>
-          ) : null}
-        </div>
-
-        <div className="shell-newdb-actions alerts-foot">
-          <button type="button" className="login-submit" onClick={onClose}>
-            Close
-          </button>
-        </div>
-      </aside>
-    </div>
-  );
-}
+// ---------------------------------------------------------------------------
+// alerts/AlertsPane.tsx — WAVE 20 item 25 (C-ALERT): the inbox.
+//
+// Two lists, one panel, and the order is the point: what HAPPENED first, what is
+// WATCHING second. An inbox that opens on its own configuration is a settings
+// screen wearing a bell.
+//
+// A drawer rather than a route, for the same reason the AI note is a modal: the
+// nav is server-filtered and an undeclared surface is denied by design (this
+// shell has no client-invented pages). Alerts are not a granted module — they
+// are this account's own inbox over its own views.
+// ---------------------------------------------------------------------------
+
+import { useCallback, useEffect, useState } from "react";
+import {
+  deleteAlert,
+  fetchAlerts,
+  fetchInbox,
+  markRead,
+  runAlert,
+} from "./alertsApi";
+import {
+  EMPTY_INBOX,
+  applyRead,
+  inboxOrder,
+  isAutomationOutcome,
+  isAutomationReview,
+  routeForTopic,
+  stampText,
+} from "./alertsModel";
+import type { Alert, Inbox, Notification } from "./alertsModel";
+// WAVE 27 C5 — the ONE generated loop mark, consumed rather than redrawn (C7's rule).
+import { Mark } from "../shell/Brand";
+
+/** The clock face this pane uses for its one glyph — drawn, never an emoji. */
+function BellIcon() {
+  return (
+    <svg className="alerts-bell" viewBox="0 0 16 16" aria-hidden="true">
+      <path d="M8 2.2a3.6 3.6 0 0 1 3.6 3.6v2.4l1.2 2H3.2l1.2-2V5.8A3.6 3.6 0 0 1 8 2.2Z" />
+      <path d="M6.6 12.6a1.5 1.5 0 0 0 2.8 0" />
+    </svg>
+  );
+}
+
+export default function AlertsPane({
+  onClose,
+  onOpenView,
+  onOpenAutomation,
+  onInbox,
+  onToast,
+}: {
+  onClose: () => void;
+  /** Navigate to the alert's view. The FRAME owns routing; this pane owns the row. */
+  onOpenView: (topic: string, viewId: string) => void;
+  /**
+   * WAVE 23 (C6, wiring W23-W5) — the same division for a REVIEW notification: the frame routes
+   * to `#/automation` and asks the surface to select this automation.
+   *
+   * ⛔ REQUIRED, NOT OPTIONAL, and that is the wave-20 lesson written into a type. An optional
+   * callback the frame forgot to pass degrades to "clicking a review notification does nothing",
+   * which is indistinguishable from "the feature was never built" and goes red in no gate. A
+   * required prop fails `tsc` the moment it is unmounted.
+   */
+  onOpenAutomation: (autoId: string, stageId?: string) => void;
+  /** Hand the freshly-read inbox back so the nav badge and the pane agree. */
+  onInbox: (inbox: Inbox) => void;
+  onToast: (message: string) => void;
+}) {
+  const [inbox, setInbox] = useState<Inbox>(EMPTY_INBOX);
+  const [alerts, setAlerts] = useState<Alert[]>([]);
+  const [error, setError] = useState("");
+  const [busy, setBusy] = useState(false);
+
+  const publish = useCallback(
+    (next: Inbox) => {
+      setInbox(next);
+      onInbox(next);
+    },
+    [onInbox]
+  );
+
+  const load = useCallback(async () => {
+    const [inboxRes, alertRes] = await Promise.all([fetchInbox(), fetchAlerts()]);
+    if (inboxRes.ok) publish(inboxRes.value);
+    else setError(inboxRes.message);
+    if (alertRes.ok) setAlerts(alertRes.value);
+  }, [publish]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  // ⛔ Escape closes it, like every other panel in this shell — a scrim with no
+  // keyboard way out is a trap (the wave-18 lesson, kept).
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [onClose]);
+
+  const toggleRead = useCallback(
+    (n: Notification) => {
+      // Optimistic, with the server's own convention (`ids`, `read`) sent
+      // explicitly — and reverted out loud if the write is refused, because a
+      // badge that silently disagrees with the list is how a reader learns to
+      // stop trusting it.
+      const before = inbox;
+      publish(applyRead(inbox, [n.id], !n.read));
+      void markRead([n.id], !n.read).then((r) => {
+        if (!r.ok) {
+          publish(before);
+          onToast(r.message);
+        }
+      });
+    },
+    [inbox, publish, onToast]
+  );
+
+  const markAll = useCallback(() => {
+    const before = inbox;
+    publish(applyRead(inbox, null, true));
+    void markRead(null, true).then((r) => {
+      if (!r.ok) {
+        publish(before);
+        onToast(r.message);
+      }
+    });
+  }, [inbox, publish, onToast]);
+
+  const open = useCallback(
+    (n: Notification) => {
+      if (!n.read) {
+        publish(applyRead(inbox, [n.id], true));
+        void markRead([n.id], true);
+      }
+      // ⛔ WAVE 23 C6 — THE KIND BRANCH COMES FIRST, AND ITS ORDER IS THE WHOLE FIX. A review
+      // notification has no `topic` a grid could render, so the view guard below would have
+      // caught every one of them and told the reader their table was "no longer available" —
+      // a confidently wrong sentence about a feature that is working. The destination decides
+      // which guard applies, so the destination is decided first.
+      if (isAutomationReview(n)) {
+        onOpenAutomation(n.autoId!, n.stageId);
+        onClose();
+        return;
+      }
+      // ⭐ WAVE 27 C5 — a RUN OUTCOME routes to its automation too, and it carries the id in
+      // `alertId` rather than `autoId` (`core.alerts.notify`'s shape, not `_queue_review`'s).
+      // Beside the review branch and after it: a review notification satisfies BOTH predicates,
+      // and only the review one knows about the stage to scroll to.
+      if (isAutomationOutcome(n)) {
+        onOpenAutomation(n.alertId, undefined);
+        onClose();
+        return;
+      }
+      // A route this client cannot resolve opens NOTHING and says so — alerts
+      // outlive the surfaces they were made from.
+      if (!routeForTopic(n.topic)) {
+        onToast("That alert's table is no longer available to this account.");
+        return;
+      }
+      onOpenView(n.topic, n.viewId);
+      onClose();
+    },
+    [inbox, publish, onOpenView, onOpenAutomation, onClose, onToast]
+  );
+
+  const rows = inboxOrder(inbox.items);
+
+  return (
+    <div className="shell-newdb-scrim" onClick={onClose}>
+      <aside
+        className="alerts-pane"
+        role="dialog"
+        aria-label="Alerts"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <header className="alerts-head">
+          <h2>
+            <BellIcon /> Alerts
+          </h2>
+          <button
+            type="button"
+            className="alerts-markall"
+            disabled={inbox.unread === 0}
+            onClick={markAll}
+          >
+            Mark all read
+          </button>
+        </header>
+
+        {error ? <p className="shell-newdb-err">{error}</p> : null}
+
+        <div className="alerts-scroll">
+          {rows.length === 0 ? (
+            <p className="alerts-empty">
+              Nothing new. An alert watches ONE view and tells you when a record it had
+              never matched arrives in it — make one from a view's ··· menu.
+            </p>
+          ) : (
+            <ul className="alerts-list">
+              {rows.map((n) => (
+                <li key={n.id} className={"alerts-row" + (n.read ? "" : " is-unread")}>
+                  <button
+                    type="button"
+                    className="alerts-row-main"
+                    onClick={() => open(n)}
+                    // The hover names the DESTINATION, which is now two different places.
+                    // "Open the alert's view" over a review notification described a journey
+                    // the click does not take.
+                    title={
+                      isAutomationReview(n) || isAutomationOutcome(n)
+                        ? "Open the automation"
+                        : `Open ${n.alertLabel || "the alert's view"}`
+                    }
+                  >
+                    {/* ⭐ WAVE 27 C5 — an automation's row wears the LOOP MARK.
+                        ⛔ NOT A STATUS DOT, and not a second one: wave-26 R14 deleted every
+                        status dot in the automation module on the grounds that *"these
+                        automations are basically loops"*, and a run that FAILED is already said
+                        in `n.label` (the run summary) in words. A coloured dot here would
+                        reintroduce, in the inbox, the vocabulary that was deleted from the
+                        surface it points at.
+                        ⛔ The generated `Mark`, never a redrawn path: `shell/Brand.tsx`'s header
+                        records a hand-copied version silently painting LAST WAVE'S BRAND while
+                        a comment claimed parity. */}
+                    <span className="alerts-row-label">
+                      {isAutomationOutcome(n) || isAutomationReview(n) ? (
+                        // ⚠ INSIDE the label span, not beside it. `.alerts-row-main` is a flex
+                        // COLUMN, so a sibling here becomes a third ROW stacked above the text
+                        // ([[wrong-parent-not-broken-control]]); inline, it sits on the line it
+                        // annotates and rides the same ellipsis.
+                        <span className="alerts-row-mark">
+                          <Mark size={12} />
+                        </span>
+                      ) : null}
+                      {n.label}
+                    </span>
+                    <span className="alerts-row-meta">
+                      {n.alertLabel ? `${n.alertLabel} · ` : ""}
+                      {/* Readable, but never re-derived: `stampText` is string surgery
+                          over the server's own UTC-with-offset stamp (D-18). Parsing it
+                          into a browser Date is how a tenant a day ahead gets told an
+                          event happened tomorrow. */}
+                      {stampText(n.at)}
+                    </span>
+                  </button>
+                  <button
+                    type="button"
+                    className="alerts-row-toggle"
+                    aria-label={n.read ? `Mark ${n.label} unread` : `Mark ${n.label} read`}
+                    title={n.read ? "Mark unread" : "Mark read"}
+                    onClick={() => toggleRead(n)}
+                  >
+                    {/* The ACTION, not the state: "Read" beside an unread row reads as
+                        a label for the row itself. */}
+                    {n.read ? "Mark unread" : "Mark read"}
+                  </button>
+                </li>
+              ))}
+            </ul>
+          )}
+
+          {alerts.length > 0 ? (
+            <section className="alerts-watching">
+              <h3>Watching</h3>
+              {alerts.map((a) => (
+                <div key={a.id} className="alerts-watch-row">
+                  <span className="alerts-watch-label">{a.label}</span>
+                  <span className="alerts-watch-meta">
+                    {/* The remembered set's SIZE, which is what "no news" means here:
+                        an alert with 40 matches and nothing new is working. */}
+                    {a.matched.toLocaleString()} matched
+                    {a.lastError ? ` · ${a.lastError}` : ""}
+                  </span>
+                  <button
+                    type="button"
+                    className="alerts-watch-run"
+                    disabled={busy}
+                    onClick={() => {
+                      setBusy(true);
+                      void runAlert(a.id).then((r) => {
+                        setBusy(false);
+                        if (!r.ok) return onToast(r.message);
+                        const v = r.value as { new?: unknown[]; skipped?: string };
+                        onToast(
+                          v?.skipped
+                            ? `Skipped: ${v.skipped}`
+                            : `${(v?.new ?? []).length} new since the last check.`
+                        );
+                        void load();
+                      });
+                    }}
+                  >
+                    Check now
+                  </button>
+                  <button
+                    type="button"
+                    className="alerts-watch-del"
+                    disabled={busy}
+                    aria-label={`Delete the alert ${a.label}`}
+                    onClick={() => {
+                      setBusy(true);
+                      void deleteAlert(a.id).then((r) => {
+                        setBusy(false);
+                        if (!r.ok) return onToast(r.message);
+                        setAlerts((cur) => cur.filter((x) => x.id !== a.id));
+                        void load();
+                      });
+                    }}
+                  >
+                    Delete
+                  </button>
+                </div>
+              ))}
+            </section>
+          ) : null}
+        </div>
+
+        <div className="shell-newdb-actions alerts-foot">
+          <button type="button" className="login-submit" onClick={onClose}>
+            Close
+          </button>
+        </div>
+      </aside>
+    </div>
+  );
+}

web/src/apiContract.ts

@@ -1,237 +1,237 @@
-// ---------------------------------------------------------------------------
-// apiContract.ts — the handful of constants BOTH trees need, and the two
-// browser-level signals the data layer raises to the frame.
-//
-// WHY A ROOT-LEVEL LEAF. `shell/session.ts` and `customer-grid/apiBridge.ts`
-// both speak X2, so both need the version prefix and the credentials word. The
-// alternatives were worse: a second copy of `"/api/v1"` is a string that drifts
-// (this codebase keeps a lock-step GATE for exactly that class of duplication),
-// and importing shell code from `customer-grid/**` would point the dependency
-// edge the wrong way — the grid is the ASSET, the shell is the disposable
-// frame, and the embed bundle must never grow a reason to pull the frame in.
-// A leaf both import is the only arrangement with no cycle and no drift.
-//
-// It imports nothing, by construction.
-// ---------------------------------------------------------------------------
-
-/** X2: every route lives under this prefix. `/api/health` is the one exception
- *  and is not ours — it is the unauthenticated liveness probe. */
-export const API_V1 = "/api/v1";
-
-/**
- * ⚠ EXPLICIT, not defaulted. Same-origin is already the browser default, but
- * this is the one word that decides whether the X3 session cookie rides the
- * request at all — and the cookie is HttpOnly, so getting it wrong produces no
- * client-side symptom, just a 401 from a server that never saw a session. An
- * implicit default is not something a reader (or a gate) can check.
- */
-export const CREDENTIALS: RequestCredentials = "same-origin";
-
-/**
- * THE SESSION DIED UNDER US. Raised by any authenticated call that comes back
- * 401, and handled by the shell (sign out, show the door).
- *
- * A DOM CustomEvent rather than an import, deliberately: `customer-grid/**` is
- * host-neutral and must not know a shell exists — it is the same tree the
- * Streamlit embed ships. The window is the one channel both sides already
- * share (`hostBridge` uses it for the host-render signal for the same reason).
- */
-export const UNAUTHORIZED_EVENT = "aios:unauthorized";
-
-/**
- * ⭐ THE TENANT THIS RESPONSE WAS SERVED FOR — the header that closes a
- * cross-tenant SIGHTING the 401 path structurally cannot catch.
- *
- * ⛔ THE BUG, owner-reported 2026-08-09: *"I am able to see the automation of
- * tenant Nurilab, when logged into Royal Import's."* MEASURED: it is not a
- * server leak. Automations live in per-tenant dataset REPOS, `/automations`
- * reads `session.runtime` = `get_runtime(claims["t"])` off the SIGNED cookie,
- * and `_user_for` refuses when the cookie's tenant is not the account's. Every
- * link holds. What does NOT hold is the browser:
- *
- *   `aios_session` is ONE cookie, `path="/"`, per ORIGIN. So one browser can
- *   hold exactly one tenant session at a time. Sign into tenant B in a second
- *   tab and the FIRST tab is silently repointed — it keeps painting tenant A's
- *   chrome (nav, page, the automations it already fetched) while every new
- *   request it makes is answered for tenant B. Two tenants on one screen, and
- *   the server was right every time.
- *
- * ⚠ AND IT IS NOT COSMETIC: a write issued from the stale tab lands in the
- * OTHER tenant's store, because the cookie decides. That is the same event the
- * owner reports as "I updated the data and it doesn't register the change" —
- * it registered, in the wrong tenant.
- *
- * `handledUnauthorized` cannot see this: a repointed tab gets 200s, not 401s.
- * Its own comment already names the neighbouring hazard ("one browser, two
- * accounts, and a cached book served across the boundary") — this is that rule
- * one level up, at the TENANT boundary rather than the user one.
- */
-export const TENANT_HEADER = "X-AIOS-Tenant";
-
-/** The tenant this frame BOOTED for; `null` until the first authenticated
- *  answer names one. Module-level on purpose — it must outlive every component
- *  that could be unmounted by the very reset it triggers. */
-let bootTenant: string | null = null;
-
-/** Test seam ONLY — `verify_login.py` drives the comparator without a browser. */
-export function _resetTenantGuard(): void {
-  bootTenant = null;
-}
-
-export function currentTenant(): string | null {
-  return bootTenant;
-}
-
-/**
- * Compare a response's tenant stamp against the one this frame booted with.
- * Returns true when it detected a SWAP and handled it.
- *
- * ⚠ RELOAD, NEVER A PARTIAL RESET. There is no correct way to re-point a live
- * frame at another tenant: its nav, its route, its grid caches, its localStorage
- * bucket and its in-flight requests were all resolved for the old one. A full
- * reload is the only action that cannot leave two tenants blended, and it lands
- * the user in the tenant they actually signed into.
- *
- * ⚠ An ABSENT header is not a mismatch. Unauthenticated routes and any older
- * build serve none, and treating absent as "changed" would reload the app in a
- * loop — the failure mode that would be worse than the bug.
- */
-export function checkTenant(res: { headers: { get(name: string): string | null } }): boolean {
-  let seen: string | null = null;
-  try {
-    seen = res.headers.get(TENANT_HEADER);
-  } catch {
-    return false;
-  }
-  if (!seen) return false;
-  if (bootTenant === null) {
-    bootTenant = seen;
-    return false;
-  }
-  if (bootTenant === seen) return false;
-  bootTenant = seen;
-  try {
-    if (typeof window !== "undefined" && window.location) window.location.reload();
-  } catch {
-    /* node (the gate) has no window — the comparator is what is under test */
-  }
-  return true;
-}
-
-/** The authenticated read FAILED for a reason that is not authentication. The
- *  frame says so plainly; it never substitutes sample data (see apiBridge). */
-export const DATA_ERROR_EVENT = "aios:data-error";
-
-/** The server sent a human-readable confirmation with a write (X2's `toast`).
- *  `detail` is the string. */
-export const TOAST_EVENT = "aios:toast";
-
-/**
- * owner item 2 (2026-08-03) — the events response carried DERIVED CELLS with it.
- *
- * Creating a measure column used to take two sequential round trips before a number appeared:
- * one to persist the field, one to compute it. The server now computes right after the write
- * and returns the values on the same response; `detail` is `{[pid: string]: {[key]: value}}`,
- * exactly the `derived` shape `/workspace` sends.
- *
- * ⚠ A SHORTCUT, NEVER A PATH. `WORKSPACE_STALE_EVENT` still fires beside it and the re-read
- * still delivers the same values — so a browser that misses this, or a server that could not
- * compute it, behaves exactly as it did before. Nothing may be built on it arriving.
- */
-export const DERIVED_CELLS_EVENT = "aios:derived-cells";
-
-/** A write CHANGED durable workspace state (a cohort's membership, a list add, a
- *  folder move) and the client's copy is now stale.
- *
- *  ⛔ WHY THIS EXISTS. `/customers` carries rows; the workspace lives at its own
- *  URL. So in the embed the Streamlit host reruns and the left panel repaints,
- *  while standalone had NOTHING — the server's `toast` was the only evidence a
- *  cohort add had happened, and the panel beside it still showed the old
- *  membership. A toast is a receipt, not a refresh. */
-export const WORKSPACE_STALE_EVENT = "aios:workspace-stale";
-
-/** Owner item 10 (2026-07-31): the user CLICKED INTO THE WORK SURFACE (a saved view, a grid
- *  cell) — the frame should fold its navigation rail down to the slim strip so the table gets
- *  the width. Raised by the grid, handled by the shell; a no-op in the embed (no listener),
- *  which is exactly the host-neutral contract the other signals follow. */
-export const NAV_MINIMIZE_EVENT = "aios:nav-minimize";
-
-/** Wave 18 (C3-UT): rows changed OUTSIDE the grid's own write path — a shell "Add record",
- *  an automation run — and the current topic's rows should be refetched. The grid clears its
- *  rows cache and reloads; senders call `clearCustomersCache()` first so the refetch cannot
- *  be served from the 5-minute memo. */
-export const ROWS_STALE_EVENT = "aios:rows-stale";
-
-export function signal(name: string, detail?: unknown): void {
-  if (typeof window === "undefined") return;
-  window.dispatchEvent(new CustomEvent(name, { detail }));
-}
-
-/**
- * Wave 20 (item 25) — the shell→grid channel for an alert's click-through.
- *
- * A notification names `{topic, viewId}`; the SHELL routes to the table and the GRID owns view
- * selection, so neither has to learn the other's state. An alert for a view the reader can no
- * longer see must do NOTHING rather than throw — the listener checks its own view list first.
- */
-export const VIEW_OPEN_EVENT = "aios:view-open";
-
-/** `detail` of {@link VIEW_OPEN_EVENT}. */
-export interface ViewOpenDetail {
-  topic: string;
-  viewId: string;
-}
-
-/**
- * WAVE 23 (contract C6, wiring W23-W5) — the shell→automation channel for a review
- * notification's click-through.
- *
- * ⛔ THE SAME SHAPE AS `VIEW_OPEN_EVENT` ABOVE, FOR THE SAME REASON, and wave 20 is why both
- * exist as constants in this leaf rather than as a string typed twice. A card arriving at a
- * review stage queues an `automation_review` notification naming `{autoId, stageId, count}`;
- * clicking it has to do TWO things that live on opposite sides of an ownership fence — route to
- * `#/automation` (the SHELL's hash) and select that automation in the rail (`AutomationSurface`'s
- * own `activeId`, which the shell cannot see and must not learn). So the frame navigates and
- * then ASKS, and the surface answers if it can.
- *
- * ⚠ THE LISTENER IS THE HALF THAT CAN BE ABSENT. Wave 20 shipped item 25's click-through with
- * this exact shape and NO listener — the event was dispatched into nothing, every gate green,
- * the notification landing the reader on the right table and doing nothing else. Declared here
- * on the wave's first day precisely so the surface can wire the listener while it is being
- * built rather than at close-out; the wiring row (W23-W5) asserts both ends.
- *
- * An automation the reader can no longer open must do NOTHING rather than throw — the listener
- * checks its own list first, exactly as the grid does for a view it cannot see.
- */
-export const AUTOMATION_OPEN_EVENT = "aios:automation-open";
-
-/** `detail` of {@link AUTOMATION_OPEN_EVENT}. `stageId` is advisory — a surface that does not
- *  scroll to a stage simply selects the automation. */
-export interface AutomationOpenDetail {
-  autoId: string;
-  stageId?: string;
-}
-
-/*
- * ⛔ `AUTOMATION_CREATE_EVENT` STOOD HERE AND IS DELETED WHOLE (wave 25 item 5a, ruling R8).
- *
- * It existed for ONE purpose: the "Automated database" doors on Home, in the Database flyout's
- * create menu and in the New-database dialog routed to `#/automation` and then raised this so the
- * surface would open its create flow. R8 deletes all three doors — "creating a database is one
- * act; pointing an automation at it is another" — and `Shell.tsx`'s `openAutomated` was this
- * event's ONLY signaller.
- *
- * ⛔ SO IT HAD TO GO WITH THEM, and the reason is this repo's own scar tissue rather than tidiness.
- * Left behind, it would be a constant with a listener and no signaller — the exact mirror of the
- * defect wave 24 found here (declared, signalled, consumed NOWHERE, every gate green, three doors
- * that navigated and then did nothing). A one-sided event is indistinguishable from a working one
- * from every direction except a grep, in BOTH directions, so the fix is symmetric: delete the side
- * that is left, never leave the half that compiles.
- *
- * ⚠ `AUTOMATION_OPEN_EVENT` above is UNAFFECTED and still two-sided (the shell signals it from
- * Home's automation tiles and the alerts click-through; `AutomationSurface` listens at module
- * scope). `verify_automation_ui.py` now DERIVES that rule instead of naming these two constants:
- * every `AUTOMATION_*_EVENT` declared in this file must have a signal site AND a listener site.
- * Creating an automation has one door and it is on the automation surface, which is where W24 put
- * the front door anyway (`AutomationSurface`'s rail button and its empty state).
- */
+// ---------------------------------------------------------------------------
+// apiContract.ts — the handful of constants BOTH trees need, and the two
+// browser-level signals the data layer raises to the frame.
+//
+// WHY A ROOT-LEVEL LEAF. `shell/session.ts` and `customer-grid/apiBridge.ts`
+// both speak X2, so both need the version prefix and the credentials word. The
+// alternatives were worse: a second copy of `"/api/v1"` is a string that drifts
+// (this codebase keeps a lock-step GATE for exactly that class of duplication),
+// and importing shell code from `customer-grid/**` would point the dependency
+// edge the wrong way — the grid is the ASSET, the shell is the disposable
+// frame, and the embed bundle must never grow a reason to pull the frame in.
+// A leaf both import is the only arrangement with no cycle and no drift.
+//
+// It imports nothing, by construction.
+// ---------------------------------------------------------------------------
+
+/** X2: every route lives under this prefix. `/api/health` is the one exception
+ *  and is not ours — it is the unauthenticated liveness probe. */
+export const API_V1 = "/api/v1";
+
+/**
+ * ⚠ EXPLICIT, not defaulted. Same-origin is already the browser default, but
+ * this is the one word that decides whether the X3 session cookie rides the
+ * request at all — and the cookie is HttpOnly, so getting it wrong produces no
+ * client-side symptom, just a 401 from a server that never saw a session. An
+ * implicit default is not something a reader (or a gate) can check.
+ */
+export const CREDENTIALS: RequestCredentials = "same-origin";
+
+/**
+ * THE SESSION DIED UNDER US. Raised by any authenticated call that comes back
+ * 401, and handled by the shell (sign out, show the door).
+ *
+ * A DOM CustomEvent rather than an import, deliberately: `customer-grid/**` is
+ * host-neutral and must not know a shell exists — it is the same tree the
+ * Streamlit embed ships. The window is the one channel both sides already
+ * share (`hostBridge` uses it for the host-render signal for the same reason).
+ */
+export const UNAUTHORIZED_EVENT = "aios:unauthorized";
+
+/**
+ * ⭐ THE TENANT THIS RESPONSE WAS SERVED FOR — the header that closes a
+ * cross-tenant SIGHTING the 401 path structurally cannot catch.
+ *
+ * ⛔ THE BUG, owner-reported 2026-08-09: *"I am able to see the automation of
+ * tenant Nurilab, when logged into Royal Import's."* MEASURED: it is not a
+ * server leak. Automations live in per-tenant dataset REPOS, `/automations`
+ * reads `session.runtime` = `get_runtime(claims["t"])` off the SIGNED cookie,
+ * and `_user_for` refuses when the cookie's tenant is not the account's. Every
+ * link holds. What does NOT hold is the browser:
+ *
+ *   `aios_session` is ONE cookie, `path="/"`, per ORIGIN. So one browser can
+ *   hold exactly one tenant session at a time. Sign into tenant B in a second
+ *   tab and the FIRST tab is silently repointed — it keeps painting tenant A's
+ *   chrome (nav, page, the automations it already fetched) while every new
+ *   request it makes is answered for tenant B. Two tenants on one screen, and
+ *   the server was right every time.
+ *
+ * ⚠ AND IT IS NOT COSMETIC: a write issued from the stale tab lands in the
+ * OTHER tenant's store, because the cookie decides. That is the same event the
+ * owner reports as "I updated the data and it doesn't register the change" —
+ * it registered, in the wrong tenant.
+ *
+ * `handledUnauthorized` cannot see this: a repointed tab gets 200s, not 401s.
+ * Its own comment already names the neighbouring hazard ("one browser, two
+ * accounts, and a cached book served across the boundary") — this is that rule
+ * one level up, at the TENANT boundary rather than the user one.
+ */
+export const TENANT_HEADER = "X-AIOS-Tenant";
+
+/** The tenant this frame BOOTED for; `null` until the first authenticated
+ *  answer names one. Module-level on purpose — it must outlive every component
+ *  that could be unmounted by the very reset it triggers. */
+let bootTenant: string | null = null;
+
+/** Test seam ONLY — `verify_login.py` drives the comparator without a browser. */
+export function _resetTenantGuard(): void {
+  bootTenant = null;
+}
+
+export function currentTenant(): string | null {
+  return bootTenant;
+}
+
+/**
+ * Compare a response's tenant stamp against the one this frame booted with.
+ * Returns true when it detected a SWAP and handled it.
+ *
+ * ⚠ RELOAD, NEVER A PARTIAL RESET. There is no correct way to re-point a live
+ * frame at another tenant: its nav, its route, its grid caches, its localStorage
+ * bucket and its in-flight requests were all resolved for the old one. A full
+ * reload is the only action that cannot leave two tenants blended, and it lands
+ * the user in the tenant they actually signed into.
+ *
+ * ⚠ An ABSENT header is not a mismatch. Unauthenticated routes and any older
+ * build serve none, and treating absent as "changed" would reload the app in a
+ * loop — the failure mode that would be worse than the bug.
+ */
+export function checkTenant(res: { headers: { get(name: string): string | null } }): boolean {
+  let seen: string | null = null;
+  try {
+    seen = res.headers.get(TENANT_HEADER);
+  } catch {
+    return false;
+  }
+  if (!seen) return false;
+  if (bootTenant === null) {
+    bootTenant = seen;
+    return false;
+  }
+  if (bootTenant === seen) return false;
+  bootTenant = seen;
+  try {
+    if (typeof window !== "undefined" && window.location) window.location.reload();
+  } catch {
+    /* node (the gate) has no window — the comparator is what is under test */
+  }
+  return true;
+}
+
+/** The authenticated read FAILED for a reason that is not authentication. The
+ *  frame says so plainly; it never substitutes sample data (see apiBridge). */
+export const DATA_ERROR_EVENT = "aios:data-error";
+
+/** The server sent a human-readable confirmation with a write (X2's `toast`).
+ *  `detail` is the string. */
+export const TOAST_EVENT = "aios:toast";
+
+/**
+ * owner item 2 (2026-08-03) — the events response carried DERIVED CELLS with it.
+ *
+ * Creating a measure column used to take two sequential round trips before a number appeared:
+ * one to persist the field, one to compute it. The server now computes right after the write
+ * and returns the values on the same response; `detail` is `{[pid: string]: {[key]: value}}`,
+ * exactly the `derived` shape `/workspace` sends.
+ *
+ * ⚠ A SHORTCUT, NEVER A PATH. `WORKSPACE_STALE_EVENT` still fires beside it and the re-read
+ * still delivers the same values — so a browser that misses this, or a server that could not
+ * compute it, behaves exactly as it did before. Nothing may be built on it arriving.
+ */
+export const DERIVED_CELLS_EVENT = "aios:derived-cells";
+
+/** A write CHANGED durable workspace state (a cohort's membership, a list add, a
+ *  folder move) and the client's copy is now stale.
+ *
+ *  ⛔ WHY THIS EXISTS. `/customers` carries rows; the workspace lives at its own
+ *  URL. So in the embed the Streamlit host reruns and the left panel repaints,
+ *  while standalone had NOTHING — the server's `toast` was the only evidence a
+ *  cohort add had happened, and the panel beside it still showed the old
+ *  membership. A toast is a receipt, not a refresh. */
+export const WORKSPACE_STALE_EVENT = "aios:workspace-stale";
+
+/** Owner item 10 (2026-07-31): the user CLICKED INTO THE WORK SURFACE (a saved view, a grid
+ *  cell) — the frame should fold its navigation rail down to the slim strip so the table gets
+ *  the width. Raised by the grid, handled by the shell; a no-op in the embed (no listener),
+ *  which is exactly the host-neutral contract the other signals follow. */
+export const NAV_MINIMIZE_EVENT = "aios:nav-minimize";
+
+/** Wave 18 (C3-UT): rows changed OUTSIDE the grid's own write path — a shell "Add record",
+ *  an automation run — and the current topic's rows should be refetched. The grid clears its
+ *  rows cache and reloads; senders call `clearCustomersCache()` first so the refetch cannot
+ *  be served from the 5-minute memo. */
+export const ROWS_STALE_EVENT = "aios:rows-stale";
+
+export function signal(name: string, detail?: unknown): void {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent(name, { detail }));
+}
+
+/**
+ * Wave 20 (item 25) — the shell→grid channel for an alert's click-through.
+ *
+ * A notification names `{topic, viewId}`; the SHELL routes to the table and the GRID owns view
+ * selection, so neither has to learn the other's state. An alert for a view the reader can no
+ * longer see must do NOTHING rather than throw — the listener checks its own view list first.
+ */
+export const VIEW_OPEN_EVENT = "aios:view-open";
+
+/** `detail` of {@link VIEW_OPEN_EVENT}. */
+export interface ViewOpenDetail {
+  topic: string;
+  viewId: string;
+}
+
+/**
+ * WAVE 23 (contract C6, wiring W23-W5) — the shell→automation channel for a review
+ * notification's click-through.
+ *
+ * ⛔ THE SAME SHAPE AS `VIEW_OPEN_EVENT` ABOVE, FOR THE SAME REASON, and wave 20 is why both
+ * exist as constants in this leaf rather than as a string typed twice. A card arriving at a
+ * review stage queues an `automation_review` notification naming `{autoId, stageId, count}`;
+ * clicking it has to do TWO things that live on opposite sides of an ownership fence — route to
+ * `#/automation` (the SHELL's hash) and select that automation in the rail (`AutomationSurface`'s
+ * own `activeId`, which the shell cannot see and must not learn). So the frame navigates and
+ * then ASKS, and the surface answers if it can.
+ *
+ * ⚠ THE LISTENER IS THE HALF THAT CAN BE ABSENT. Wave 20 shipped item 25's click-through with
+ * this exact shape and NO listener — the event was dispatched into nothing, every gate green,
+ * the notification landing the reader on the right table and doing nothing else. Declared here
+ * on the wave's first day precisely so the surface can wire the listener while it is being
+ * built rather than at close-out; the wiring row (W23-W5) asserts both ends.
+ *
+ * An automation the reader can no longer open must do NOTHING rather than throw — the listener
+ * checks its own list first, exactly as the grid does for a view it cannot see.
+ */
+export const AUTOMATION_OPEN_EVENT = "aios:automation-open";
+
+/** `detail` of {@link AUTOMATION_OPEN_EVENT}. `stageId` is advisory — a surface that does not
+ *  scroll to a stage simply selects the automation. */
+export interface AutomationOpenDetail {
+  autoId: string;
+  stageId?: string;
+}
+
+/*
+ * ⛔ `AUTOMATION_CREATE_EVENT` STOOD HERE AND IS DELETED WHOLE (wave 25 item 5a, ruling R8).
+ *
+ * It existed for ONE purpose: the "Automated database" doors on Home, in the Database flyout's
+ * create menu and in the New-database dialog routed to `#/automation` and then raised this so the
+ * surface would open its create flow. R8 deletes all three doors — "creating a database is one
+ * act; pointing an automation at it is another" — and `Shell.tsx`'s `openAutomated` was this
+ * event's ONLY signaller.
+ *
+ * ⛔ SO IT HAD TO GO WITH THEM, and the reason is this repo's own scar tissue rather than tidiness.
+ * Left behind, it would be a constant with a listener and no signaller — the exact mirror of the
+ * defect wave 24 found here (declared, signalled, consumed NOWHERE, every gate green, three doors
+ * that navigated and then did nothing). A one-sided event is indistinguishable from a working one
+ * from every direction except a grep, in BOTH directions, so the fix is symmetric: delete the side
+ * that is left, never leave the half that compiles.
+ *
+ * ⚠ `AUTOMATION_OPEN_EVENT` above is UNAFFECTED and still two-sided (the shell signals it from
+ * Home's automation tiles and the alerts click-through; `AutomationSurface` listens at module
+ * scope). `verify_automation_ui.py` now DERIVES that rule instead of naming these two constants:
+ * every `AUTOMATION_*_EVENT` declared in this file must have a signal site AND a listener site.
+ * Creating an automation has one door and it is on the automation surface, which is where W24 put
+ * the front door anyway (`AutomationSurface`'s rail button and its empty state).
+ */

web/src/automation/AutomationFind.tsx

@@ -1,893 +1,893 @@
-// ---------------------------------------------------------------------------
-// automation/AutomationFind.tsx — the discovery filter, as TOGGLES (owner item 6,
-// contract C4).
-//
-// WHAT CHANGED AND WHY. It was a condition BUILDER: an empty row, a field
-// dropdown listing 21 names, "Add a condition". That shape asks the user to
-// remember what is searchable before they can look, and it hid the only fact
-// that decides whether a search returns anything at all — which fields actually
-// carry values. The corpus is 620 million profiles and every run is billed, so
-// "I did not know I could filter on that" and "I filtered on a field that is
-// empty on every row" are both expensive mistakes made in silence.
-//
-// So every searchable field is ON SCREEN, off by default, and turning one on is
-// what creates its condition. The list leads with the fields MEASURED to carry
-// values; the rest are grouped under what is known about them, and neither group
-// is hidden — R3 already decided that "every filter" means the 21 we can stand
-// behind, so all 21 are visible.
-//
-// ⛔ THE VOCABULARY IS THE SERVER'S, ALL OF IT. Field names, operators, which
-// operators take no value, the record ceiling and (once C4 lands it) which
-// fields are populated and which narrow — every one of those rides on
-// `GET /automations`. This file holds no list of its own. The reason is the one
-// `automationApi.ts:11-15` gives for cron presets: the thing that ACCEPTS a
-// filter is Python, and a client copy of what it accepts is a copy that can
-// offer a search the server refuses.
-//
-// ⛔ AND IT DOES NOT RE-IMPLEMENT THE GUARD. `guard` carries the server's
-// numbers, so the rows can say which fields narrow — but the refusal is the
-// server's to make and this surface prints it VERBATIM when it comes back
-// (`DiscoverGuard`'s note). A client that predicts the refusal is a second copy
-// of the rule, free to disagree with the first, and when they disagree the user
-// gets a Save button that is disabled for a reason nobody can see.
-// ---------------------------------------------------------------------------
-import { useEffect, useState } from "react";
-// ⭐ WAVE 27 item 29 — the overlay layer the grid already owns, consumed rather than
-// re-implemented: it is a body portal (so it escapes `.auto-panel`'s 380px), and it brings
-// the dismiss/focus/placement behaviour every other popover on this product already has.
-import { AnchoredOverlay } from "../customer-grid/OverlaySurface";
-import type { AnchorRect } from "../customer-grid/OverlaySurface";
-
-import type {
-  DiscoverEstimate,
-  DiscoverFieldMeta,
-  DiscoverOperator,
-  DiscoverVocab,
-  Predicate,
-} from "./automationApi";
-import { discoverCategories } from "./automationApi";
-
-interface Props {
-  /** The server-declared discovery vocabulary (absent until the list loads). */
-  discover?: DiscoverVocab;
-  recordsLimit: number;
-  onRecordsLimit: (n: number) => void;
-  joinOp: string;
-  onJoinOp: (v: string) => void;
-  preds: Predicate[];
-  onPreds: (next: Predicate[]) => void;
-  estimate: DiscoverEstimate | null;
-  onEstimate: () => void;
-}
-
-/**
- * A FILTER FIELD'S ICON (owner item 5). Drawn, `currentColor`, never an emoji — and in the
- * existing `TriggerMark`/`ActionMark` language rather than a new one: same 16 viewBox, same 15px
- * box, same 1.4 stroke, so a row here and a card in the builder read as one product.
- *
- * ⚠ SHARED SHAPES WHERE THE FIELDS SHARE A MEANING, distinct everywhere else. `TriggerMark`'s
- * note settled the principle — a column of identical glyphs is decoration, the eye learns nothing
- * — but its converse matters just as much here: `bio_hashtags` and `post_hashtags` ARE both
- * hashtags, and drawing two different marks for them would invent a distinction the vendor does
- * not make. Twenty-one contrived glyphs would be twenty-one things to misread.
- *
- * ⛔ THE FALLBACK IS NOT A MEMBER OF THE SET, which is the `ActionMark` scar exactly: its default
- * used to BE the pencil, a real member, so every unmatched kind silently borrowed "edit" and a
- * fallback could not be told from a match. The vocabulary is the SERVER's — it can grow a field
- * tomorrow — so an unmatched name draws a neutral mark that is deliberately meaningless.
- */
-function FilterMark({ name }: { name: string }) {
-  const common = {
-    width: 15, height: 15, viewBox: "0 0 16 16", fill: "none", stroke: "currentColor",
-    strokeWidth: 1.4, strokeLinecap: "round" as const, strokeLinejoin: "round" as const,
-    "aria-hidden": true,
-  };
-  // Audience size — two figures, one behind the other.
-  if (name === "followers")
-    return (
-      <svg {...common}>
-        <circle cx="6.2" cy="5.6" r="2.4" />
-        <path d="M2.2 13c.5-2 2.1-3.2 4-3.2s3.5 1.2 4 3.2" />
-        <path d="M10.6 3.6a2.4 2.4 0 0 1 0 4M11.4 9.9c1.4.4 2.4 1.5 2.8 3.1" />
-      </svg>
-    );
-  // Who this account follows — a figure with an outbound arrow.
-  if (name === "following")
-    return (
-      <svg {...common}>
-        <circle cx="6" cy="5.6" r="2.4" />
-        <path d="M1.8 13c.5-2 2.1-3.2 4.2-3.2 .6 0 1.2.1 1.7.3" />
-        <path d="M9.8 10.6h4.2M12.2 8.8l1.8 1.8-1.8 1.8" />
-      </svg>
-    );
-  if (name === "posts_count")
-    return (
-      <svg {...common}>
-        <rect x="2.6" y="2.6" width="4.6" height="4.6" rx="1" />
-        <rect x="8.8" y="2.6" width="4.6" height="4.6" rx="1" />
-        <rect x="2.6" y="8.8" width="4.6" height="4.6" rx="1" />
-        <rect x="8.8" y="8.8" width="4.6" height="4.6" rx="1" />
-      </svg>
-    );
-  // A story highlight — the ring Instagram draws around one.
-  if (name === "highlights_count")
-    return (
-      <svg {...common}>
-        <circle cx="8" cy="8" r="5.6" strokeDasharray="2.6 1.8" />
-        <circle cx="8" cy="8" r="2.2" />
-      </svg>
-    );
-  if (name === "avg_engagement")
-    return (
-      <svg {...common}>
-        <path d="M8 13.2 3.4 8.8a2.9 2.9 0 0 1 4.6-3.4 2.9 2.9 0 0 1 4.6 3.4z" />
-      </svg>
-    );
-  if (name === "biography")
-    return (
-      <svg {...common}>
-        <rect x="2.4" y="2.8" width="11.2" height="10.4" rx="1.6" />
-        <path d="M4.8 6h6.4M4.8 8.4h6.4M4.8 10.8h3.6" />
-      </svg>
-    );
-  if (name === "category_name" || name === "business_category_name")
-    return (
-      <svg {...common}>
-        <path d="M8.4 2.6H13v4.6l-6.2 6.2-4.6-4.6z" />
-        <circle cx="10.8" cy="5.2" r="0.9" />
-      </svg>
-    );
-  if (name === "is_business_account" || name === "is_professional_account")
-    return (
-      <svg {...common}>
-        <rect x="2.2" y="5" width="11.6" height="8.2" rx="1.6" />
-        <path d="M6 5V3.6a1 1 0 0 1 1-1h2a1 1 0 0 1 1 1V5" />
-      </svg>
-    );
-  if (name === "is_verified")
-    return (
-      <svg {...common}>
-        <path d="M8 2.2l1.7 1.2 2-.2.6 2 1.7 1.1-.9 1.9.9 1.9-1.7 1.1-.6 2-2-.2L8 14.2l-1.7-1.2-2 .2-.6-2L2 10.1l.9-1.9L2 6.3l1.7-1.1.6-2 2 .2z" />
-        <path d="m5.8 8.1 1.5 1.5 3-3.1" />
-      </svg>
-    );
-  // The handle, and the display name it is written under.
-  if (name === "account" || name === "profile_name")
-    return (
-      <svg {...common}>
-        <circle cx="8" cy="8" r="2.4" />
-        <path d="M10.4 5.6v3.2a1.9 1.9 0 0 0 3.2 1.3A5.8 5.8 0 1 0 11 13.1" />
-      </svg>
-    );
-  if (name === "full_name")
-    return (
-      <svg {...common}>
-        <circle cx="8" cy="5.6" r="2.6" />
-        <path d="M3 13.4c.7-2.3 2.6-3.6 5-3.6s4.3 1.3 5 3.6" />
-      </svg>
-    );
-  if (name === "external_url" || name === "profile_url")
-    return (
-      <svg {...common}>
-        <path d="M6.6 9.4 4.9 11a2.6 2.6 0 1 1-1.5-4.4" />
-        <path d="M9.4 6.6 11.1 5a2.6 2.6 0 1 1 1.5 4.4" />
-        <path d="M6.2 8h3.6" />
-      </svg>
-    );
-  if (name === "bio_hashtags" || name === "post_hashtags")
-    return (
-      <svg {...common}>
-        <path d="M6.2 2.8 4.8 13.2M11.2 2.8 9.8 13.2M2.8 6h10.4M2.2 10h10.4" />
-      </svg>
-    );
-  if (name === "related_accounts")
-    return (
-      <svg {...common}>
-        <circle cx="8" cy="3.6" r="1.8" />
-        <circle cx="3.6" cy="12" r="1.8" />
-        <circle cx="12.4" cy="12" r="1.8" />
-        <path d="M6.8 5.2 4.6 10.4M9.2 5.2l2.2 5.2M5.4 12h5.2" />
-      </svg>
-    );
-  // The vendor's own record keys — the thing you hold to open exactly one row.
-  if (name === "id" || name === "fbid")
-    return (
-      <svg {...common}>
-        <circle cx="5.4" cy="10.6" r="2.6" />
-        <path d="M7.2 8.8 13 3M10.6 5.4l1.6 1.6M9.2 6.8l1.6 1.6" />
-      </svg>
-    );
-  return (
-    <svg {...common}>
-      <rect x="3.2" y="3.2" width="9.6" height="9.6" rx="2.2" />
-      <circle cx="8" cy="8" r="1.4" />
-    </svg>
-  );
-}
-
-/** One field's line in the list, with everything known about it. */
-interface FieldRow {
-  name: string;
-  /** What the row is CALLED. Falls back to the raw name only if the server sent none. */
-  label: string;
-  hint: string;
-  kind: string;
-  operators: DiscoverOperator[];
-  options: { value: string; label: string }[];
-  /** Every stored condition naming this field, with its index in the saved array. */
-  at: number[];
-  /** MEASURED to carry values. `null` = the server has not said (C4 not shipped yet). */
-  populated: boolean | null;
-  /** A condition here cuts the corpus down. `null` = not said. */
-  narrowing: boolean | null;
-}
-
-/** A stored value → what the text box shows. A list is the "any of" shape. */
-function valueText(v: Predicate["value"]): string {
-  if (Array.isArray(v)) return v.join(", ");
-  return v === undefined || v === null ? "" : String(v);
-}
-
-/**
- * What the user typed → what is stored. Comma-separated becomes a LIST for the operators that
- * accept one, and stays a plain string for the ones that do not.
- *
- * ⚠ A single value stays a SCALAR rather than a one-element list — the server sends scalars
- * flat and lists as a nested OR group, and a one-element group is a shape nothing has been
- * billed against.
- */
-function parseValue(text: string, multi: boolean): Predicate["value"] {
-  if (!multi) return text;
-  const parts = text.split(",").map((s) => s.trim()).filter(Boolean);
-  if (parts.length > 1) return parts;
-  // Keep the RAW text while it is still being typed — trimming here would fight the cursor on
-  // every keystroke, and the server trims anyway.
-  return text;
-}
-
-/**
- * ⭐ WAVE 26 · DEBT D-69 — A THIRD VALUE COULD NOT BE TYPED, and the cause was one round trip
- * through this pair of functions.
- *
- * `parseValue` returns an ARRAY at 2+ values; `valueText` then renders that array as
- * `join(", ")` — which has NO TRAILING COMMA. So on a controlled input the separator was
- * normalised away between keystrokes: typing `,` onto `skincare, beauty` re-rendered as
- * `skincare, beauty`, and the next character landed as `skincare, beautym`. Two keywords
- * silently became one that matches nothing. ⚠ It hit the FIRST surface a new user meets (wave 24
- * made this panel the only door) and it hit precisely the 3+ keyword list the feature was built
- * for — the owner's *"if i want to include many keywords like floral, flower, beauty"*.
- *
- * ⛔ THE FIX IS THE ONE `parseValue`'s OWN COMMENT ALREADY DESCRIBES FOR THE 1-VALUE CASE:
- * keep the raw text while it is being typed. That comment was right and its scope was too narrow
- * — it protected the cursor at one value and handed the 2+ case to `join`. So the raw text is
- * held for whichever input is FOCUSED, and the stored value is still parsed on every keystroke
- * (so nothing depends on blur to save) and re-parsed on blur (so the display settles).
- *
- * ⚠ KEYED BY THE ROW'S REACT KEY, not by index alone: two conditions on the same field are
- * ordinary here ("Another condition on Bio"), and an index-only key would leak one row's draft
- * into its sibling on a removal.
- */
-interface Draft {
-  key: string;
-  text: string;
-}
-
-/**
- * The comparison a freshly toggled field starts with — ASKED FOR, never chosen here.
- *
- * ⛔ THE THIRD COSTUME OF ONE SCAR, and the reason this function no longer has an opinion.
- * Wave 21 made a new condition NULLARY (`is_not_null`) so it would be saveable without a
- * value, and called that "narrowing-in-the-right-direction". Wave 22 then wrote the narrowing
- * law server-side and `is_not_null` is not in it. From that moment, toggling ANY field on and
- * pressing Save returned "add at least one CONTENT condition…" — the error told the user to do
- * the exact thing they had just done. Wave 24 deleted the wizard and made this panel the only
- * door, so it stopped being a corner case and became the first thing a new user hits.
- *
- * The fix is not a better guess. It is that the module owning the guard also names the default
- * (`automation_engine.default_operator`, asserted against `predicate_narrows` in
- * `verify_automation.py`), and this file looks it up per FIELD. An absent one falls back to the
- * server's first operator — never to a nullary, which is the thing that could not narrow.
- */
-function firstOperator(v: DiscoverVocab | undefined, name: string): string {
-  const meta = (v?.filterMeta || []).find((m) => m.name === name);
-  return meta?.defaultOperator || (v?.operators || [])[0] || "";
-}
-
-/**
- * The rows, ordered: measured-populated first, then the rest.
- *
- * TWO SOURCES, AND THE FALLBACK IS NARROWER THAN THE REAL THING. With C4's
- * `filterMeta` the answer is per field and complete. Without it, `lead` names
- * the three fields seen carrying values and says NOTHING about the other
- * eighteen — so those come back `null`, not `false`, and the UI prints no claim
- * about them rather than an invented one.
- */
-function buildRows(preds: Predicate[], v?: DiscoverVocab): FieldRow[] {
-  const meta = new Map<string, DiscoverFieldMeta>(
-    (v?.filterMeta || []).map((m) => [m.name, m])
-  );
-  const lead = new Set(v?.lead || []);
-  const byName = new Map<string, number[]>();
-  preds.forEach((p, i) => {
-    const list = byName.get(p.name);
-    if (list) list.push(i);
-    else byName.set(p.name, [i]);
-  });
-
-  const rows = (v?.fields || []).map((name) => {
-    const m = meta.get(name);
-    return {
-      name,
-      label: m?.label || name,
-      hint: m?.hint || "",
-      kind: m?.kind || "text",
-      // ⛔ NO FALLBACK TO THE GLOBAL OPERATOR LIST. An older server that sends no per-field list
-      // gets a row with no comparisons rather than all fourteen on every field — visibly
-      // unfinished beats quietly offering `at least` on a yes/no column.
-      operators: m?.operators || [],
-      options: m?.options || [],
-      at: byName.get(name) || [],
-      populated: m ? !!m.populated : lead.has(name) ? true : null,
-      narrowing: m ? !!m.narrowing : null,
-    };
-  });
-  // Stable partition, never a sort: the server's order inside each half is the
-  // order the engine lists them in, and re-alphabetising it would be this file
-  // having an opinion about a server list.
-  return [...rows.filter((r) => r.populated === true), ...rows.filter((r) => r.populated !== true)];
-}
-
-export default function AutomationFind({
-  discover,
-  recordsLimit,
-  onRecordsLimit,
-  joinOp,
-  onJoinOp,
-  preds,
-  onPreds,
-  estimate,
-  onEstimate,
-}: Props) {
-  const rows = buildRows(preds, discover);
-  const known = new Set(discover?.fields || []);
-  // The GLOBAL operator list is gone from this component: comparisons are per field now
-  // (`row.operators`). `nullary` survives for STRAYS only — a stored condition on a field the
-  // vendor dropped has no per-field row to read from, and it still has to render to be removable.
-  const nullary = new Set(discover?.nullaryOperators || []);
-  const withValues = rows.filter((r) => r.populated === true);
-  const rest = rows.filter((r) => r.populated !== true);
-  const knownMeta = !!(discover?.filterMeta || []).length;
-  // ⚠ THE STORED FILTER CAN NAME A FIELD THE LIST NO LONGER HAS — a vocabulary
-  // that moved, an automation copied from elsewhere. It must stay VISIBLE and
-  // REMOVABLE: a condition the user cannot see is one they cannot delete, and
-  // every Save keeps sending it. Same defect as a `<select>` whose value matches
-  // no option, one level up.
-  const strays = preds
-    .map((p, i) => ({ p, i }))
-    .filter(({ p }) => !known.has(p.name));
-
-  const maxRecords = discover?.guard?.maxRecords || discover?.maxRecords || 500;
-
-  /** D-69 — the raw text of the input a person is typing in right now (see `Draft`). */
-  const [draft, setDraft] = useState<Draft | null>(null);
-
-  /**
-   * ⭐ WAVE 27 · OWNER ITEM 29 — which condition's value is open in the BIG editor, if any.
-   *
-   * ⛔ THE TEXT IS HELD HERE, NOT WRITTEN THROUGH ON EVERY KEYSTROKE, and that is the one place
-   * this differs from the rail input beside it. The rail input writes per keystroke on purpose
-   * (a Save pressed straight from the field must not store the previous value — D-69's note).
-   * A modal has its own Save, so per-keystroke writes would buy nothing and would make Cancel
-   * a lie: the value would already be in the config by the time it was pressed.
-   * ⚠ The ANCHOR is captured at click time and stored, because the button it came from is
-   * inside a panel that scrolls — re-reading it later would place the overlay against a rect
-   * that has moved.
-   */
-  const [big, setBig] = useState<{
-    key: string;
-    index: number;
-    label: string;
-    multi: boolean;
-    text: string;
-    anchor: AnchorRect;
-  } | null>(null);
-
-  /**
-   * ⭐ ITEM 16 / D-71 — THE OBSERVED CATEGORY VALUES, fetched WHEN THIS PANEL OPENS.
-   *
-   * ⛔ ON MOUNT, ONCE, AND NEVER ON THE POLLED PAYLOAD. This component is rendered only while the
-   * Find panel is open, so mounting IS the panel opening — and the server moved these off
-   * `GET /automations` after measuring that deriving them reads two user tables plus the platform
-   * master, i.e. a network round-trip per open tab every 2.5 s. Putting the request here is the
-   * client half of that same decision, not an optimisation.
-   *
-   * ⚠ AN EMPTY LIST IS AN ANSWER AND IS RENDERED AS ONE. It means this deployment has not seen a
-   * category value yet — which is TRUE for a fresh tenant — and the field keeps its free-text
-   * input either way. It must never read as "loading forever", and it must never be filled in
-   * with a guess: D-59 is explicit that an invented taxonomy is worse than no dropdown.
-   */
-  const [cats, setCats] = useState<{ value: string; count: number }[]>([]);
-  useEffect(() => {
-    const ac = new AbortController();
-    discoverCategories(ac.signal)
-      .then((r) => setCats(Array.isArray(r?.options) ? r.options : []))
-      // Fail-quiet, on purpose: the picker is an ASSIST over a control that works without it.
-      // An error banner here would report a broken panel when the only thing missing is a
-      // convenience — and the free-text input beside it is unaffected.
-      .catch(() => setCats([]));
-    return () => ac.abort();
-  }, []);
-
-  const setAt = (i: number, patch: Partial<Predicate>) =>
-    onPreds(preds.map((p, j) => (j === i ? { ...p, ...patch } : p)));
-
-  const removeAt = (i: number) => onPreds(preds.filter((_p, j) => j !== i));
-
-  const toggleField = (row: FieldRow) => {
-    if (row.at.length) {
-      onPreds(preds.filter((p) => p.name !== row.name));
-      return;
-    }
-    onPreds([...preds, { name: row.name, operator: firstOperator(discover, row.name) }]);
-  };
-
-  /** One condition line — the comparison, its value, and a way out. */
-  const condition = (i: number, label: string, row?: FieldRow) => {
-    const p = preds[i];
-    if (!p) return null;
-    // The field's OWN comparisons. `row` is absent only for a stray (a stored condition on a
-    // field the vendor no longer offers), which keeps the raw token so it stays removable.
-    const ops = row?.operators || [];
-    const cur = ops.find((o) => o.value === p.operator);
-    const isNullary = cur ? cur.nullary : nullary.has(p.operator);
-    const isMulti = !!cur?.multi;
-    const options = row?.options || [];
-    const rowKey = `${p.name}-${i}`;
-    // D-69: the focused input shows what was TYPED; every other one shows the stored value.
-    const shown = draft && draft.key === rowKey ? draft.text : valueText(p.value);
-    /*
-     * ⭐ ITEM 16 / D-71 — WHICH FIELDS GET THE OBSERVED-VALUES PICKER, DERIVED OFF THE WIRE.
-     *
-     * ⛔ NOT A CLIENT-SIDE LIST OF FIELD NAMES. Naming the vendor's two category columns here
-     * would be the D-55 class verbatim — the wave-9 silent-drop shape, a client copy of a server
-     * vocabulary that is free to drift the day the engine adds a third one. (Their literal keys
-     * are deliberately not written anywhere in this file: the gate asserts the tokens are ABSENT,
-     * and an absence check cannot tell a hard-coded list from the comment forbidding one.)
-     * The server already publishes the answer twice over: `kind: "choice"` is its own declaration
-     * (`BD_FIELD_KINDS`), and `filter_meta` deliberately ships `options: []` for those fields
-     * because their vocabulary is OBSERVED rather than declared and arrives on its own route.
-     * So the rule is exactly that: a choice-kind field with no declared options is one whose
-     * values we can only have learned by seeing them. A new choice field inherits this for free.
-     */
-    const wantsObserved = row?.kind === "choice" && !options.length;
-    /** D-71 — APPEND, never replace: the picker has to compose with the comma list. */
-    const appendValue = (v: string) => {
-      const has = shown
-        .split(",")
-        .map((s) => s.trim().toLowerCase())
-        .filter(Boolean);
-      // Picking the same value twice is a no-op rather than a duplicate: the server expands a
-      // multi-value condition into an OR, and `beauty OR beauty` costs a slot to say nothing.
-      if (has.includes(v.trim().toLowerCase())) return;
-      const next = shown.trim() ? `${shown.replace(/[\s,]+$/, "")}, ${v}` : v;
-      setDraft(null);
-      setAt(i, { value: parseValue(next, isMulti) });
-    };
-    return (
-      <div className="autob-cond" key={rowKey}>
-        <select
-          className="auto-input is-small"
-          aria-label={`Comparison for ${label}`}
-          value={p.operator}
-          onChange={(e) => setAt(i, { operator: e.target.value })}
-        >
-          {/* The stored value is ALWAYS an option. A select whose value matches no
-              option renders the FIRST one, and the next Save writes a comparison
-              nobody chose — this codebase has paid for that twice. */}
-          {p.operator && !ops.some((o) => o.value === p.operator) ? (
-            <option value={p.operator}>{p.operator}</option>
-          ) : null}
-          {ops.map((o) => (
-            <option key={o.value} value={o.value}>
-              {o.label}
-            </option>
-          ))}
-        </select>
-        {isNullary ? null : options.length ? (
-          // A fixed vocabulary gets a dropdown. Owner item 2: a yes/no column was a box you
-          // typed `true` into, beside a comparison list that offered "at least".
-          <select
-            className="auto-input is-small"
-            aria-label={`Value for ${label}`}
-            value={valueText(p.value)}
-            onChange={(e) => setAt(i, { value: e.target.value })}
-          >
-            <option value="">Choose…</option>
-            {options.map((o) => (
-              <option key={o.value} value={o.value}>
-                {o.label}
-              </option>
-            ))}
-          </select>
-        ) : (
-          <input
-            className="auto-input is-small"
-            type={row?.kind === "number" ? "number" : "text"}
-            aria-label={`Value for ${label}`}
-            // ⭐ OWNER ITEM 3. Several comma-separated values become an "any of" condition, which
-            // the server sends as its own OR group — so it does NOT drag Followers into a union
-            // the way the Match dropdown would.
-            placeholder={isMulti ? "floral, flower, beauty" : ""}
-            // D-69: `shown` is the RAW text while this input has focus, so a trailing comma
-            // survives long enough to type the next value after it.
-            value={shown}
-            onFocus={() => setDraft({ key: rowKey, text: valueText(p.value) })}
-            onChange={(e) => {
-              setDraft({ key: rowKey, text: e.target.value });
-              // The STORE still updates on every keystroke. Parsing only on blur would mean a
-              // Save pressed straight from the field wrote the previous value — trading a typing
-              // bug for a data-loss one.
-              setAt(i, { value: parseValue(e.target.value, isMulti) });
-            }}
-            onBlur={(e) => {
-              setDraft(null);
-              setAt(i, { value: parseValue(e.target.value, isMulti) });
-            }}
-          />
-        )}
-        {/* ⭐ WAVE 27 · OWNER ITEM 29 — A WIDE EDITOR FOR THE VALUES THAT DO NOT FIT.
-            ⛔ THE COMPLAINT IS GEOMETRY, and the geometry is a CHAIN nothing here can widen:
-            `.auto-panel` is 380px, `.autob-cond .auto-input` divides what is left across three
-            controls, and `.is-small` trims it again — so a bio phrase list ("floral, flower,
-            wedding florist, event styling") is typed six characters at a time through a box
-            that scrolls sideways. The panel cannot grow; the EDITOR can leave it, and an
-            overlay is drawn in a body portal, so it is not bound by that chain at all.
-            ⚠ ALWAYS OFFERED, never "appears once the text is long": a control that materialises
-            at some threshold is one people do not know exists at the moment they need it.
-            ⚠ NOT on a `<select>` value (a fixed vocabulary has nothing to expand) and not on a
-            nullary comparison (which has no value at all). */}
-        {!isNullary && !options.length ? (
-          <button
-            type="button"
-            className="auto-input is-small autoc-expand"
-            aria-label={`Open a bigger editor for ${label}`}
-            title="Edit in a bigger box"
-            onClick={(e) => {
-              // ⚠ READ SYNCHRONOUSLY from the event. `currentTarget` is null by the time React
-              // re-invokes a state updater, and a null rect here paints the overlay at 0,0 —
-              // measured, in this repo, on a different control ([[react-event-currenttarget-updater]]).
-              const r = e.currentTarget.getBoundingClientRect();
-              setBig({
-                key: rowKey,
-                index: i,
-                label,
-                multi: isMulti,
-                text: valueText(p.value),
-                anchor: { left: r.left, top: r.top, right: r.right, bottom: r.bottom,
-                          width: r.width, height: r.height },
-              });
-            }}
-          >
-            {/* Drawn, never a glyph: the design constitution's "no emojis in the UI" covers
-                the arrow characters too, and every other mark in this product is a path in the
-                same 16x16 stroke vocabulary. Two corners pulling apart = "make this bigger". */}
-            <svg viewBox="0 0 16 16" aria-hidden className="autoc-expand-icon">
-              <path d="M9.5 2.5h4v4M13.5 2.5 9.6 6.4" />
-              <path d="M6.5 13.5h-4v-4M2.5 13.5l3.9-3.9" />
-            </svg>
-          </button>
-        ) : null}
-        {/* ⭐ ITEM 16 / D-71 — THE APPEND-PICKER, BESIDE the input and never instead of it.
-            Free text stays the primary control: these are the values this deployment has SEEN,
-            not the values that exist, so the picker is a shortcut over a superset it cannot
-            enumerate. Appending in code also sidesteps D-69 entirely — a picked value never has
-            to survive a round trip through the text box. */}
-        {wantsObserved && !isNullary ? (
-          <select
-            className="auto-input is-small autoc-catpick"
-            aria-label={`Add a value seen before, to ${label}`}
-            title={
-              cats.length
-                ? "Values this workspace has actually seen, most-seen first. Adds to the list."
-                : "No category values have been seen in your data yet — type one."
-            }
-            value=""
-            disabled={!cats.length}
-            onChange={(e) => {
-              if (e.target.value) appendValue(e.target.value);
-            }}
-          >
-            <option value="">{cats.length ? "Seen before…" : "None seen yet"}</option>
-            {cats.map((c) => (
-              // The COUNT is the honest half (D-59): a value seen once and one seen forty times
-              // are different bets, and an alphabetical list of bare strings hides that.
-              <option key={c.value} value={c.value}>
-                {c.value} ({c.count.toLocaleString()})
-              </option>
-            ))}
-          </select>
-        ) : null}
-        {isMulti && Array.isArray(p.value) && p.value.length > 1 ? (
-          /*
-           * ⭐ ITEM 16 / D-71 — HOW MANY VALUES THIS CONDITION CARRIES, and against what ceiling.
-           *
-           * The COUNT is ours and is always shown. The CEILING is the server's and is shown only
-           * when the server sends one (`guard.maxValues` — an open `ASK ->A:`; `guard` ships
-           * `{minNarrowing, maxRecords}` today).
-           * ⛔ NO CLIENT-SIDE `4`. D-71's exit says "how many of D-68's 4 value slots" — but A
-           * shipped `depth_refusal()`, which computes the depth of the shape actually emitted
-           * rather than budgeting fixed slots, so the number 4 describes a model that no longer
-           * exists. Printing it would be a client copy of a server rule that has already changed
-           * once, which is the specific failure this file's header refuses to commit
-           * ([[measure-the-real-call]]: a correct-looking answer about the wrong subject).
-           */
-          <span className="autob-cond-any" title="Any one of these is a match">
-            any of {p.value.length}
-            {discover?.guard?.maxValues ? ` of ${discover.guard.maxValues}` : ""}
-          </span>
-        ) : null}
-        <button
-          type="button"
-          className="autob-cond-x"
-          aria-label={`Remove this condition on ${label}`}
-          title="Remove this condition"
-          onClick={() => removeAt(i)}
-        >
-          <svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden="true">
-            <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
-          </svg>
-        </button>
-      </div>
-    );
-  };
-
-  const fieldRow = (row: FieldRow) => {
-    const on = row.at.length > 0;
-    return (
-      <div className={"autob-tgl" + (on ? " is-on" : "")} key={row.name}>
-        <div className="autob-tgl-head">
-          <button
-            type="button"
-            className={"auto-step-switch autob-tgl-switch" + (on ? " is-on" : "")}
-            aria-pressed={on}
-            aria-label={`${on ? "Stop searching" : "Search"} on ${row.label}`}
-            title={`${on ? "Stop searching" : "Search"} on ${row.label}`}
-            onClick={() => toggleField(row)}
-          >
-            <span className="auto-step-switch-knob" />
-          </button>
-          <span className="autob-tgl-mark">
-            <FilterMark name={row.name} />
-          </span>
-          {/* ⭐ THE HUMAN LABEL (owner item 1: "wtf is id/fbid").
-              This used to render the vendor's own column name verbatim, and the comment
-              defending it was RIGHT about the reason — a refusal names the field, and a label
-              that reads differently makes the error unmatchable. So the label did not move
-              alone: `field_label()` is what the SERVER's refusals use too, which is the only
-              version of this change that does not trade one confusion for another. */}
-          <span className="autob-tgl-name" title={row.hint || undefined}>
-            {row.label}
-          </span>
-          {/*
-            ⚠ ONE CHIP, AND IT MARKS THE MINORITY. The first version chipped every
-            non-narrowing field "broad" AND every unpopulated one "no values seen" —
-            which put two chips on 18 of the 21 rows, and one of them repeated the group
-            heading the row was already sitting under. A mark that is on almost every row
-            stops being a mark. Read off the screenshot; no assertion could have said it.
-
-            So: the group label carries POPULATED (it is what the groups ARE), and the
-            chip carries NARROWING, inverted to mark the five that DO narrow. That is the
-            actionable half — the server refuses a filter with no narrowing condition, so
-            "these are the ones that satisfy it" is the sentence a user needs, and
-            "this one does not" is not.
-          */}
-          {row.narrowing === true ? (
-            <span
-              className="autob-tgl-flag is-narrow"
-              title="A search needs at least one condition like this."
-            >
-              narrows
-            </span>
-          ) : null}
-        </div>
-        {on ? (
-          <div className="autob-tgl-body">
-            {row.at.map((i) => condition(i, row.label, row))}
-            {row.hint ? <p className="autob-tgl-hint">{row.hint}</p> : null}
-            <button
-              type="button"
-              className="autob-cond-add"
-              onClick={() =>
-                onPreds([...preds, { name: row.name, operator: firstOperator(discover, row.name) }])
-              }
-            >
-              Another condition on {row.label}
-            </button>
-          </div>
-        ) : null}
-      </div>
-    );
-  };
-
-  return (
-    <>
-      <div className="auto-field">
-        <label htmlFor="auto-records">How many profiles to fetch</label>
-        <input
-          id="auto-records"
-          className="auto-input"
-          type="number"
-          min={1}
-          max={maxRecords}
-          value={recordsLimit}
-          onChange={(e) => onRecordsLimit(Number(e.target.value) || 1)}
-        />
-      </div>
-      {/* Owner item 5: "Stop at the 'A search must be at most 500 profiles a run'". The two
-          sentences that followed explained the vendor's billing model to somebody who wants a
-          list of florists. */}
-      <p className="auto-hint">At most {maxRecords.toLocaleString()} profiles a run.</p>
-
-      <h3>Conditions</h3>
-      <div className="auto-field autob-match">
-        <label htmlFor="auto-joinop">Match</label>
-        <select
-          id="auto-joinop"
-          className="auto-input"
-          value={joinOp}
-          onChange={(e) => onJoinOp(e.target.value)}
-        >
-          <option value="and">All of them</option>
-          <option value="or">Any of them</option>
-        </select>
-      </div>
-
-      {!rows.length ? (
-        <p className="auto-note">
-          The searchable fields have not loaded yet.
-        </p>
-      ) : null}
-
-      {withValues.length ? (
-        <div className="autob-tglgroup">
-          <p
-            className="autob-tglgroup-label"
-            title="Most accounts have this filled in."
-          >
-            Usually filled in
-          </p>
-          {withValues.map(fieldRow)}
-        </div>
-      ) : null}
-
-      {rest.length ? (
-        <div className="autob-tglgroup">
-          <p
-            className="autob-tglgroup-label"
-            title={
-              knownMeta
-                ? "Most accounts leave these blank, so a condition here can return nothing."
-                : "We have not measured how often these are filled in."
-            }
-          >
-            {knownMeta ? "Often blank" : "Not measured"}
-          </p>
-          {rest.map(fieldRow)}
-        </div>
-      ) : null}
-
-      {strays.length ? (
-        <div className="autob-tglgroup">
-          <p className="autob-tglgroup-label">Not in the searchable list</p>
-          {strays.map(({ p, i }) => (
-            <div className="autob-tgl is-on is-stray" key={`stray-${i}`}>
-              <div className="autob-tgl-head">
-                {/* A stray gets a mark too — "every filter row" includes the ones the vendor no
-                    longer offers, and a row missing the icon its neighbours have would read as a
-                    different KIND of thing rather than as a field that fell out of the list. It
-                    draws the neutral fallback by construction: a stray is, by definition, not in
-                    the vocabulary this component has arms for. */}
-                <span className="autob-tgl-mark">
-                  <FilterMark name={p.name} />
-                </span>
-                <span className="autob-tgl-name">{p.name}</span>
-                <span className="autob-tgl-flag is-stray" title="The server will refuse this condition by name.">
-                  not searchable
-                </span>
-              </div>
-              <div className="autob-tgl-body">{condition(i, p.name)}</div>
-            </div>
-          ))}
-        </div>
-      ) : null}
-
-      {/* The consequence kept, the mechanism dropped: a condition on an often-blank field
-          returning nothing is a thing that will happen to somebody and confuse them. Why the
-          search is slow when broad is our problem, not theirs. */}
-      <p className="auto-hint">
-        Conditions on often-blank fields can come back with nothing.
-      </p>
-
-      <h3>What it costs</h3>
-      <div className="auto-head-actions">
-        <button type="button" className="auto-btn" onClick={onEstimate}>
-          Estimate this search
-        </button>
-      </div>
-      {estimate ? (
-        <p className="auto-hint">
-          About <strong>${estimate.usd}</strong> for {estimate.records} profiles, at $
-          {estimate.unitUsd} each.{" "}
-          {/*
-            THE CAVEAT IS NOT OPTIONAL. The vendor never quotes a price before a run and this
-            deployment cannot read its own balance, so presenting this as a billed figure
-            would be inventing a measurement.
-          */}
-          <strong>This is an estimate</strong> — {estimate.note}.
-        </p>
-      ) : null}
-
-      {/* ⭐ WAVE 27 · OWNER ITEM 29 — THE BIG EDITOR, rendered ONCE for the whole panel.
-          ⛔ Not one overlay per condition row: `AnchoredOverlay` mounts a body portal and
-          installs document-level dismiss/focus handlers, so N of them would be N listener
-          stacks fighting over one Escape key. One overlay, told which row it is editing.
-          ⚠ `role="dialog"`, not "menu": it holds a text field, and the menu layer's arrow-key
-          handling would take the cursor keys away from the text being typed. */}
-      {big ? (
-        <AnchoredOverlay
-          anchor={big.anchor}
-          className="autoc-bigedit"
-          placement="right-start"
-          role="dialog"
-          ariaLabel={`Value for ${big.label}`}
-          onDismiss={() => setBig(null)}
-          dataKind="find-value-editor"
-        >
-          <label htmlFor="autoc-bigedit-text">{big.label}</label>
-          <textarea
-            id="autoc-bigedit-text"
-            className="autoc-bigedit-text"
-            data-overlay-autofocus
-            autoFocus
-            rows={7}
-            spellCheck={false}
-            value={big.text}
-            placeholder={big.multi ? "floral, flower, wedding florist, event styling" : ""}
-            onChange={(e) => setBig((cur) => (cur ? { ...cur, text: e.target.value } : cur))}
-            onKeyDown={(e) => {
-              // Escape abandons; Ctrl/Cmd+Enter commits. A bare Enter types a NEWLINE, because
-              // this is a textarea and the whole reason it exists is that the value is long.
-              if (e.key === "Escape") setBig(null);
-              if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
-                setAt(big.index, { value: parseValue(big.text, big.multi) });
-                setBig(null);
-              }
-            }}
-          />
-          {/* The same sentence the rail input's placeholder makes, said where there is room
-              for it: a comma list is several values, and the server turns them into an OR. */}
-          {big.multi ? (
-            <p className="auto-hint">
-              Separate values with commas — the search matches any of them.
-            </p>
-          ) : null}
-          <div className="auto-head-actions">
-            <button
-              type="button"
-              className="auto-btn auto-btn--primary"
-              onClick={() => {
-                setAt(big.index, { value: parseValue(big.text, big.multi) });
-                setBig(null);
-              }}
-            >
-              Done
-            </button>
-            <button type="button" className="auto-btn" onClick={() => setBig(null)}>
-              Cancel
-            </button>
-          </div>
-        </AnchoredOverlay>
-      ) : null}
-    </>
-  );
-}
+// ---------------------------------------------------------------------------
+// automation/AutomationFind.tsx — the discovery filter, as TOGGLES (owner item 6,
+// contract C4).
+//
+// WHAT CHANGED AND WHY. It was a condition BUILDER: an empty row, a field
+// dropdown listing 21 names, "Add a condition". That shape asks the user to
+// remember what is searchable before they can look, and it hid the only fact
+// that decides whether a search returns anything at all — which fields actually
+// carry values. The corpus is 620 million profiles and every run is billed, so
+// "I did not know I could filter on that" and "I filtered on a field that is
+// empty on every row" are both expensive mistakes made in silence.
+//
+// So every searchable field is ON SCREEN, off by default, and turning one on is
+// what creates its condition. The list leads with the fields MEASURED to carry
+// values; the rest are grouped under what is known about them, and neither group
+// is hidden — R3 already decided that "every filter" means the 21 we can stand
+// behind, so all 21 are visible.
+//
+// ⛔ THE VOCABULARY IS THE SERVER'S, ALL OF IT. Field names, operators, which
+// operators take no value, the record ceiling and (once C4 lands it) which
+// fields are populated and which narrow — every one of those rides on
+// `GET /automations`. This file holds no list of its own. The reason is the one
+// `automationApi.ts:11-15` gives for cron presets: the thing that ACCEPTS a
+// filter is Python, and a client copy of what it accepts is a copy that can
+// offer a search the server refuses.
+//
+// ⛔ AND IT DOES NOT RE-IMPLEMENT THE GUARD. `guard` carries the server's
+// numbers, so the rows can say which fields narrow — but the refusal is the
+// server's to make and this surface prints it VERBATIM when it comes back
+// (`DiscoverGuard`'s note). A client that predicts the refusal is a second copy
+// of the rule, free to disagree with the first, and when they disagree the user
+// gets a Save button that is disabled for a reason nobody can see.
+// ---------------------------------------------------------------------------
+import { useEffect, useState } from "react";
+// ⭐ WAVE 27 item 29 — the overlay layer the grid already owns, consumed rather than
+// re-implemented: it is a body portal (so it escapes `.auto-panel`'s 380px), and it brings
+// the dismiss/focus/placement behaviour every other popover on this product already has.
+import { AnchoredOverlay } from "../customer-grid/OverlaySurface";
+import type { AnchorRect } from "../customer-grid/OverlaySurface";
+
+import type {
+  DiscoverEstimate,
+  DiscoverFieldMeta,
+  DiscoverOperator,
+  DiscoverVocab,
+  Predicate,
+} from "./automationApi";
+import { discoverCategories } from "./automationApi";
+
+interface Props {
+  /** The server-declared discovery vocabulary (absent until the list loads). */
+  discover?: DiscoverVocab;
+  recordsLimit: number;
+  onRecordsLimit: (n: number) => void;
+  joinOp: string;
+  onJoinOp: (v: string) => void;
+  preds: Predicate[];
+  onPreds: (next: Predicate[]) => void;
+  estimate: DiscoverEstimate | null;
+  onEstimate: () => void;
+}
+
+/**
+ * A FILTER FIELD'S ICON (owner item 5). Drawn, `currentColor`, never an emoji — and in the
+ * existing `TriggerMark`/`ActionMark` language rather than a new one: same 16 viewBox, same 15px
+ * box, same 1.4 stroke, so a row here and a card in the builder read as one product.
+ *
+ * ⚠ SHARED SHAPES WHERE THE FIELDS SHARE A MEANING, distinct everywhere else. `TriggerMark`'s
+ * note settled the principle — a column of identical glyphs is decoration, the eye learns nothing
+ * — but its converse matters just as much here: `bio_hashtags` and `post_hashtags` ARE both
+ * hashtags, and drawing two different marks for them would invent a distinction the vendor does
+ * not make. Twenty-one contrived glyphs would be twenty-one things to misread.
+ *
+ * ⛔ THE FALLBACK IS NOT A MEMBER OF THE SET, which is the `ActionMark` scar exactly: its default
+ * used to BE the pencil, a real member, so every unmatched kind silently borrowed "edit" and a
+ * fallback could not be told from a match. The vocabulary is the SERVER's — it can grow a field
+ * tomorrow — so an unmatched name draws a neutral mark that is deliberately meaningless.
+ */
+function FilterMark({ name }: { name: string }) {
+  const common = {
+    width: 15, height: 15, viewBox: "0 0 16 16", fill: "none", stroke: "currentColor",
+    strokeWidth: 1.4, strokeLinecap: "round" as const, strokeLinejoin: "round" as const,
+    "aria-hidden": true,
+  };
+  // Audience size — two figures, one behind the other.
+  if (name === "followers")
+    return (
+      <svg {...common}>
+        <circle cx="6.2" cy="5.6" r="2.4" />
+        <path d="M2.2 13c.5-2 2.1-3.2 4-3.2s3.5 1.2 4 3.2" />
+        <path d="M10.6 3.6a2.4 2.4 0 0 1 0 4M11.4 9.9c1.4.4 2.4 1.5 2.8 3.1" />
+      </svg>
+    );
+  // Who this account follows — a figure with an outbound arrow.
+  if (name === "following")
+    return (
+      <svg {...common}>
+        <circle cx="6" cy="5.6" r="2.4" />
+        <path d="M1.8 13c.5-2 2.1-3.2 4.2-3.2 .6 0 1.2.1 1.7.3" />
+        <path d="M9.8 10.6h4.2M12.2 8.8l1.8 1.8-1.8 1.8" />
+      </svg>
+    );
+  if (name === "posts_count")
+    return (
+      <svg {...common}>
+        <rect x="2.6" y="2.6" width="4.6" height="4.6" rx="1" />
+        <rect x="8.8" y="2.6" width="4.6" height="4.6" rx="1" />
+        <rect x="2.6" y="8.8" width="4.6" height="4.6" rx="1" />
+        <rect x="8.8" y="8.8" width="4.6" height="4.6" rx="1" />
+      </svg>
+    );
+  // A story highlight — the ring Instagram draws around one.
+  if (name === "highlights_count")
+    return (
+      <svg {...common}>
+        <circle cx="8" cy="8" r="5.6" strokeDasharray="2.6 1.8" />
+        <circle cx="8" cy="8" r="2.2" />
+      </svg>
+    );
+  if (name === "avg_engagement")
+    return (
+      <svg {...common}>
+        <path d="M8 13.2 3.4 8.8a2.9 2.9 0 0 1 4.6-3.4 2.9 2.9 0 0 1 4.6 3.4z" />
+      </svg>
+    );
+  if (name === "biography")
+    return (
+      <svg {...common}>
+        <rect x="2.4" y="2.8" width="11.2" height="10.4" rx="1.6" />
+        <path d="M4.8 6h6.4M4.8 8.4h6.4M4.8 10.8h3.6" />
+      </svg>
+    );
+  if (name === "category_name" || name === "business_category_name")
+    return (
+      <svg {...common}>
+        <path d="M8.4 2.6H13v4.6l-6.2 6.2-4.6-4.6z" />
+        <circle cx="10.8" cy="5.2" r="0.9" />
+      </svg>
+    );
+  if (name === "is_business_account" || name === "is_professional_account")
+    return (
+      <svg {...common}>
+        <rect x="2.2" y="5" width="11.6" height="8.2" rx="1.6" />
+        <path d="M6 5V3.6a1 1 0 0 1 1-1h2a1 1 0 0 1 1 1V5" />
+      </svg>
+    );
+  if (name === "is_verified")
+    return (
+      <svg {...common}>
+        <path d="M8 2.2l1.7 1.2 2-.2.6 2 1.7 1.1-.9 1.9.9 1.9-1.7 1.1-.6 2-2-.2L8 14.2l-1.7-1.2-2 .2-.6-2L2 10.1l.9-1.9L2 6.3l1.7-1.1.6-2 2 .2z" />
+        <path d="m5.8 8.1 1.5 1.5 3-3.1" />
+      </svg>
+    );
+  // The handle, and the display name it is written under.
+  if (name === "account" || name === "profile_name")
+    return (
+      <svg {...common}>
+        <circle cx="8" cy="8" r="2.4" />
+        <path d="M10.4 5.6v3.2a1.9 1.9 0 0 0 3.2 1.3A5.8 5.8 0 1 0 11 13.1" />
+      </svg>
+    );
+  if (name === "full_name")
+    return (
+      <svg {...common}>
+        <circle cx="8" cy="5.6" r="2.6" />
+        <path d="M3 13.4c.7-2.3 2.6-3.6 5-3.6s4.3 1.3 5 3.6" />
+      </svg>
+    );
+  if (name === "external_url" || name === "profile_url")
+    return (
+      <svg {...common}>
+        <path d="M6.6 9.4 4.9 11a2.6 2.6 0 1 1-1.5-4.4" />
+        <path d="M9.4 6.6 11.1 5a2.6 2.6 0 1 1 1.5 4.4" />
+        <path d="M6.2 8h3.6" />
+      </svg>
+    );
+  if (name === "bio_hashtags" || name === "post_hashtags")
+    return (
+      <svg {...common}>
+        <path d="M6.2 2.8 4.8 13.2M11.2 2.8 9.8 13.2M2.8 6h10.4M2.2 10h10.4" />
+      </svg>
+    );
+  if (name === "related_accounts")
+    return (
+      <svg {...common}>
+        <circle cx="8" cy="3.6" r="1.8" />
+        <circle cx="3.6" cy="12" r="1.8" />
+        <circle cx="12.4" cy="12" r="1.8" />
+        <path d="M6.8 5.2 4.6 10.4M9.2 5.2l2.2 5.2M5.4 12h5.2" />
+      </svg>
+    );
+  // The vendor's own record keys — the thing you hold to open exactly one row.
+  if (name === "id" || name === "fbid")
+    return (
+      <svg {...common}>
+        <circle cx="5.4" cy="10.6" r="2.6" />
+        <path d="M7.2 8.8 13 3M10.6 5.4l1.6 1.6M9.2 6.8l1.6 1.6" />
+      </svg>
+    );
+  return (
+    <svg {...common}>
+      <rect x="3.2" y="3.2" width="9.6" height="9.6" rx="2.2" />
+      <circle cx="8" cy="8" r="1.4" />
+    </svg>
+  );
+}
+
+/** One field's line in the list, with everything known about it. */
+interface FieldRow {
+  name: string;
+  /** What the row is CALLED. Falls back to the raw name only if the server sent none. */
+  label: string;
+  hint: string;
+  kind: string;
+  operators: DiscoverOperator[];
+  options: { value: string; label: string }[];
+  /** Every stored condition naming this field, with its index in the saved array. */
+  at: number[];
+  /** MEASURED to carry values. `null` = the server has not said (C4 not shipped yet). */
+  populated: boolean | null;
+  /** A condition here cuts the corpus down. `null` = not said. */
+  narrowing: boolean | null;
+}
+
+/** A stored value → what the text box shows. A list is the "any of" shape. */
+function valueText(v: Predicate["value"]): string {
+  if (Array.isArray(v)) return v.join(", ");
+  return v === undefined || v === null ? "" : String(v);
+}
+
+/**
+ * What the user typed → what is stored. Comma-separated becomes a LIST for the operators that
+ * accept one, and stays a plain string for the ones that do not.
+ *
+ * ⚠ A single value stays a SCALAR rather than a one-element list — the server sends scalars
+ * flat and lists as a nested OR group, and a one-element group is a shape nothing has been
+ * billed against.
+ */
+function parseValue(text: string, multi: boolean): Predicate["value"] {
+  if (!multi) return text;
+  const parts = text.split(",").map((s) => s.trim()).filter(Boolean);
+  if (parts.length > 1) return parts;
+  // Keep the RAW text while it is still being typed — trimming here would fight the cursor on
+  // every keystroke, and the server trims anyway.
+  return text;
+}
+
+/**
+ * ⭐ WAVE 26 · DEBT D-69 — A THIRD VALUE COULD NOT BE TYPED, and the cause was one round trip
+ * through this pair of functions.
+ *
+ * `parseValue` returns an ARRAY at 2+ values; `valueText` then renders that array as
+ * `join(", ")` — which has NO TRAILING COMMA. So on a controlled input the separator was
+ * normalised away between keystrokes: typing `,` onto `skincare, beauty` re-rendered as
+ * `skincare, beauty`, and the next character landed as `skincare, beautym`. Two keywords
+ * silently became one that matches nothing. ⚠ It hit the FIRST surface a new user meets (wave 24
+ * made this panel the only door) and it hit precisely the 3+ keyword list the feature was built
+ * for — the owner's *"if i want to include many keywords like floral, flower, beauty"*.
+ *
+ * ⛔ THE FIX IS THE ONE `parseValue`'s OWN COMMENT ALREADY DESCRIBES FOR THE 1-VALUE CASE:
+ * keep the raw text while it is being typed. That comment was right and its scope was too narrow
+ * — it protected the cursor at one value and handed the 2+ case to `join`. So the raw text is
+ * held for whichever input is FOCUSED, and the stored value is still parsed on every keystroke
+ * (so nothing depends on blur to save) and re-parsed on blur (so the display settles).
+ *
+ * ⚠ KEYED BY THE ROW'S REACT KEY, not by index alone: two conditions on the same field are
+ * ordinary here ("Another condition on Bio"), and an index-only key would leak one row's draft
+ * into its sibling on a removal.
+ */
+interface Draft {
+  key: string;
+  text: string;
+}
+
+/**
+ * The comparison a freshly toggled field starts with — ASKED FOR, never chosen here.
+ *
+ * ⛔ THE THIRD COSTUME OF ONE SCAR, and the reason this function no longer has an opinion.
+ * Wave 21 made a new condition NULLARY (`is_not_null`) so it would be saveable without a
+ * value, and called that "narrowing-in-the-right-direction". Wave 22 then wrote the narrowing
+ * law server-side and `is_not_null` is not in it. From that moment, toggling ANY field on and
+ * pressing Save returned "add at least one CONTENT condition…" — the error told the user to do
+ * the exact thing they had just done. Wave 24 deleted the wizard and made this panel the only
+ * door, so it stopped being a corner case and became the first thing a new user hits.
+ *
+ * The fix is not a better guess. It is that the module owning the guard also names the default
+ * (`automation_engine.default_operator`, asserted against `predicate_narrows` in
+ * `verify_automation.py`), and this file looks it up per FIELD. An absent one falls back to the
+ * server's first operator — never to a nullary, which is the thing that could not narrow.
+ */
+function firstOperator(v: DiscoverVocab | undefined, name: string): string {
+  const meta = (v?.filterMeta || []).find((m) => m.name === name);
+  return meta?.defaultOperator || (v?.operators || [])[0] || "";
+}
+
+/**
+ * The rows, ordered: measured-populated first, then the rest.
+ *
+ * TWO SOURCES, AND THE FALLBACK IS NARROWER THAN THE REAL THING. With C4's
+ * `filterMeta` the answer is per field and complete. Without it, `lead` names
+ * the three fields seen carrying values and says NOTHING about the other
+ * eighteen — so those come back `null`, not `false`, and the UI prints no claim
+ * about them rather than an invented one.
+ */
+function buildRows(preds: Predicate[], v?: DiscoverVocab): FieldRow[] {
+  const meta = new Map<string, DiscoverFieldMeta>(
+    (v?.filterMeta || []).map((m) => [m.name, m])
+  );
+  const lead = new Set(v?.lead || []);
+  const byName = new Map<string, number[]>();
+  preds.forEach((p, i) => {
+    const list = byName.get(p.name);
+    if (list) list.push(i);
+    else byName.set(p.name, [i]);
+  });
+
+  const rows = (v?.fields || []).map((name) => {
+    const m = meta.get(name);
+    return {
+      name,
+      label: m?.label || name,
+      hint: m?.hint || "",
+      kind: m?.kind || "text",
+      // ⛔ NO FALLBACK TO THE GLOBAL OPERATOR LIST. An older server that sends no per-field list
+      // gets a row with no comparisons rather than all fourteen on every field — visibly
+      // unfinished beats quietly offering `at least` on a yes/no column.
+      operators: m?.operators || [],
+      options: m?.options || [],
+      at: byName.get(name) || [],
+      populated: m ? !!m.populated : lead.has(name) ? true : null,
+      narrowing: m ? !!m.narrowing : null,
+    };
+  });
+  // Stable partition, never a sort: the server's order inside each half is the
+  // order the engine lists them in, and re-alphabetising it would be this file
+  // having an opinion about a server list.
+  return [...rows.filter((r) => r.populated === true), ...rows.filter((r) => r.populated !== true)];
+}
+
+export default function AutomationFind({
+  discover,
+  recordsLimit,
+  onRecordsLimit,
+  joinOp,
+  onJoinOp,
+  preds,
+  onPreds,
+  estimate,
+  onEstimate,
+}: Props) {
+  const rows = buildRows(preds, discover);
+  const known = new Set(discover?.fields || []);
+  // The GLOBAL operator list is gone from this component: comparisons are per field now
+  // (`row.operators`). `nullary` survives for STRAYS only — a stored condition on a field the
+  // vendor dropped has no per-field row to read from, and it still has to render to be removable.
+  const nullary = new Set(discover?.nullaryOperators || []);
+  const withValues = rows.filter((r) => r.populated === true);
+  const rest = rows.filter((r) => r.populated !== true);
+  const knownMeta = !!(discover?.filterMeta || []).length;
+  // ⚠ THE STORED FILTER CAN NAME A FIELD THE LIST NO LONGER HAS — a vocabulary
+  // that moved, an automation copied from elsewhere. It must stay VISIBLE and
+  // REMOVABLE: a condition the user cannot see is one they cannot delete, and
+  // every Save keeps sending it. Same defect as a `<select>` whose value matches
+  // no option, one level up.
+  const strays = preds
+    .map((p, i) => ({ p, i }))
+    .filter(({ p }) => !known.has(p.name));
+
+  const maxRecords = discover?.guard?.maxRecords || discover?.maxRecords || 500;
+
+  /** D-69 — the raw text of the input a person is typing in right now (see `Draft`). */
+  const [draft, setDraft] = useState<Draft | null>(null);
+
+  /**
+   * ⭐ WAVE 27 · OWNER ITEM 29 — which condition's value is open in the BIG editor, if any.
+   *
+   * ⛔ THE TEXT IS HELD HERE, NOT WRITTEN THROUGH ON EVERY KEYSTROKE, and that is the one place
+   * this differs from the rail input beside it. The rail input writes per keystroke on purpose
+   * (a Save pressed straight from the field must not store the previous value — D-69's note).
+   * A modal has its own Save, so per-keystroke writes would buy nothing and would make Cancel
+   * a lie: the value would already be in the config by the time it was pressed.
+   * ⚠ The ANCHOR is captured at click time and stored, because the button it came from is
+   * inside a panel that scrolls — re-reading it later would place the overlay against a rect
+   * that has moved.
+   */
+  const [big, setBig] = useState<{
+    key: string;
+    index: number;
+    label: string;
+    multi: boolean;
+    text: string;
+    anchor: AnchorRect;
+  } | null>(null);
+
+  /**
+   * ⭐ ITEM 16 / D-71 — THE OBSERVED CATEGORY VALUES, fetched WHEN THIS PANEL OPENS.
+   *
+   * ⛔ ON MOUNT, ONCE, AND NEVER ON THE POLLED PAYLOAD. This component is rendered only while the
+   * Find panel is open, so mounting IS the panel opening — and the server moved these off
+   * `GET /automations` after measuring that deriving them reads two user tables plus the platform
+   * master, i.e. a network round-trip per open tab every 2.5 s. Putting the request here is the
+   * client half of that same decision, not an optimisation.
+   *
+   * ⚠ AN EMPTY LIST IS AN ANSWER AND IS RENDERED AS ONE. It means this deployment has not seen a
+   * category value yet — which is TRUE for a fresh tenant — and the field keeps its free-text
+   * input either way. It must never read as "loading forever", and it must never be filled in
+   * with a guess: D-59 is explicit that an invented taxonomy is worse than no dropdown.
+   */
+  const [cats, setCats] = useState<{ value: string; count: number }[]>([]);
+  useEffect(() => {
+    const ac = new AbortController();
+    discoverCategories(ac.signal)
+      .then((r) => setCats(Array.isArray(r?.options) ? r.options : []))
+      // Fail-quiet, on purpose: the picker is an ASSIST over a control that works without it.
+      // An error banner here would report a broken panel when the only thing missing is a
+      // convenience — and the free-text input beside it is unaffected.
+      .catch(() => setCats([]));
+    return () => ac.abort();
+  }, []);
+
+  const setAt = (i: number, patch: Partial<Predicate>) =>
+    onPreds(preds.map((p, j) => (j === i ? { ...p, ...patch } : p)));
+
+  const removeAt = (i: number) => onPreds(preds.filter((_p, j) => j !== i));
+
+  const toggleField = (row: FieldRow) => {
+    if (row.at.length) {
+      onPreds(preds.filter((p) => p.name !== row.name));
+      return;
+    }
+    onPreds([...preds, { name: row.name, operator: firstOperator(discover, row.name) }]);
+  };
+
+  /** One condition line — the comparison, its value, and a way out. */
+  const condition = (i: number, label: string, row?: FieldRow) => {
+    const p = preds[i];
+    if (!p) return null;
+    // The field's OWN comparisons. `row` is absent only for a stray (a stored condition on a
+    // field the vendor no longer offers), which keeps the raw token so it stays removable.
+    const ops = row?.operators || [];
+    const cur = ops.find((o) => o.value === p.operator);
+    const isNullary = cur ? cur.nullary : nullary.has(p.operator);
+    const isMulti = !!cur?.multi;
+    const options = row?.options || [];
+    const rowKey = `${p.name}-${i}`;
+    // D-69: the focused input shows what was TYPED; every other one shows the stored value.
+    const shown = draft && draft.key === rowKey ? draft.text : valueText(p.value);
+    /*
+     * ⭐ ITEM 16 / D-71 — WHICH FIELDS GET THE OBSERVED-VALUES PICKER, DERIVED OFF THE WIRE.
+     *
+     * ⛔ NOT A CLIENT-SIDE LIST OF FIELD NAMES. Naming the vendor's two category columns here
+     * would be the D-55 class verbatim — the wave-9 silent-drop shape, a client copy of a server
+     * vocabulary that is free to drift the day the engine adds a third one. (Their literal keys
+     * are deliberately not written anywhere in this file: the gate asserts the tokens are ABSENT,
+     * and an absence check cannot tell a hard-coded list from the comment forbidding one.)
+     * The server already publishes the answer twice over: `kind: "choice"` is its own declaration
+     * (`BD_FIELD_KINDS`), and `filter_meta` deliberately ships `options: []` for those fields
+     * because their vocabulary is OBSERVED rather than declared and arrives on its own route.
+     * So the rule is exactly that: a choice-kind field with no declared options is one whose
+     * values we can only have learned by seeing them. A new choice field inherits this for free.
+     */
+    const wantsObserved = row?.kind === "choice" && !options.length;
+    /** D-71 — APPEND, never replace: the picker has to compose with the comma list. */
+    const appendValue = (v: string) => {
+      const has = shown
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+      // Picking the same value twice is a no-op rather than a duplicate: the server expands a
+      // multi-value condition into an OR, and `beauty OR beauty` costs a slot to say nothing.
+      if (has.includes(v.trim().toLowerCase())) return;
+      const next = shown.trim() ? `${shown.replace(/[\s,]+$/, "")}, ${v}` : v;
+      setDraft(null);
+      setAt(i, { value: parseValue(next, isMulti) });
+    };
+    return (
+      <div className="autob-cond" key={rowKey}>
+        <select
+          className="auto-input is-small"
+          aria-label={`Comparison for ${label}`}
+          value={p.operator}
+          onChange={(e) => setAt(i, { operator: e.target.value })}
+        >
+          {/* The stored value is ALWAYS an option. A select whose value matches no
+              option renders the FIRST one, and the next Save writes a comparison
+              nobody chose — this codebase has paid for that twice. */}
+          {p.operator && !ops.some((o) => o.value === p.operator) ? (
+            <option value={p.operator}>{p.operator}</option>
+          ) : null}
+          {ops.map((o) => (
+            <option key={o.value} value={o.value}>
+              {o.label}
+            </option>
+          ))}
+        </select>
+        {isNullary ? null : options.length ? (
+          // A fixed vocabulary gets a dropdown. Owner item 2: a yes/no column was a box you
+          // typed `true` into, beside a comparison list that offered "at least".
+          <select
+            className="auto-input is-small"
+            aria-label={`Value for ${label}`}
+            value={valueText(p.value)}
+            onChange={(e) => setAt(i, { value: e.target.value })}
+          >
+            <option value="">Choose…</option>
+            {options.map((o) => (
+              <option key={o.value} value={o.value}>
+                {o.label}
+              </option>
+            ))}
+          </select>
+        ) : (
+          <input
+            className="auto-input is-small"
+            type={row?.kind === "number" ? "number" : "text"}
+            aria-label={`Value for ${label}`}
+            // ⭐ OWNER ITEM 3. Several comma-separated values become an "any of" condition, which
+            // the server sends as its own OR group — so it does NOT drag Followers into a union
+            // the way the Match dropdown would.
+            placeholder={isMulti ? "floral, flower, beauty" : ""}
+            // D-69: `shown` is the RAW text while this input has focus, so a trailing comma
+            // survives long enough to type the next value after it.
+            value={shown}
+            onFocus={() => setDraft({ key: rowKey, text: valueText(p.value) })}
+            onChange={(e) => {
+              setDraft({ key: rowKey, text: e.target.value });
+              // The STORE still updates on every keystroke. Parsing only on blur would mean a
+              // Save pressed straight from the field wrote the previous value — trading a typing
+              // bug for a data-loss one.
+              setAt(i, { value: parseValue(e.target.value, isMulti) });
+            }}
+            onBlur={(e) => {
+              setDraft(null);
+              setAt(i, { value: parseValue(e.target.value, isMulti) });
+            }}
+          />
+        )}
+        {/* ⭐ WAVE 27 · OWNER ITEM 29 — A WIDE EDITOR FOR THE VALUES THAT DO NOT FIT.
+            ⛔ THE COMPLAINT IS GEOMETRY, and the geometry is a CHAIN nothing here can widen:
+            `.auto-panel` is 380px, `.autob-cond .auto-input` divides what is left across three
+            controls, and `.is-small` trims it again — so a bio phrase list ("floral, flower,
+            wedding florist, event styling") is typed six characters at a time through a box
+            that scrolls sideways. The panel cannot grow; the EDITOR can leave it, and an
+            overlay is drawn in a body portal, so it is not bound by that chain at all.
+            ⚠ ALWAYS OFFERED, never "appears once the text is long": a control that materialises
+            at some threshold is one people do not know exists at the moment they need it.
+            ⚠ NOT on a `<select>` value (a fixed vocabulary has nothing to expand) and not on a
+            nullary comparison (which has no value at all). */}
+        {!isNullary && !options.length ? (
+          <button
+            type="button"
+            className="auto-input is-small autoc-expand"
+            aria-label={`Open a bigger editor for ${label}`}
+            title="Edit in a bigger box"
+            onClick={(e) => {
+              // ⚠ READ SYNCHRONOUSLY from the event. `currentTarget` is null by the time React
+              // re-invokes a state updater, and a null rect here paints the overlay at 0,0 —
+              // measured, in this repo, on a different control ([[react-event-currenttarget-updater]]).
+              const r = e.currentTarget.getBoundingClientRect();
+              setBig({
+                key: rowKey,
+                index: i,
+                label,
+                multi: isMulti,
+                text: valueText(p.value),
+                anchor: { left: r.left, top: r.top, right: r.right, bottom: r.bottom,
+                          width: r.width, height: r.height },
+              });
+            }}
+          >
+            {/* Drawn, never a glyph: the design constitution's "no emojis in the UI" covers
+                the arrow characters too, and every other mark in this product is a path in the
+                same 16x16 stroke vocabulary. Two corners pulling apart = "make this bigger". */}
+            <svg viewBox="0 0 16 16" aria-hidden className="autoc-expand-icon">
+              <path d="M9.5 2.5h4v4M13.5 2.5 9.6 6.4" />
+              <path d="M6.5 13.5h-4v-4M2.5 13.5l3.9-3.9" />
+            </svg>
+          </button>
+        ) : null}
+        {/* ⭐ ITEM 16 / D-71 — THE APPEND-PICKER, BESIDE the input and never instead of it.
+            Free text stays the primary control: these are the values this deployment has SEEN,
+            not the values that exist, so the picker is a shortcut over a superset it cannot
+            enumerate. Appending in code also sidesteps D-69 entirely — a picked value never has
+            to survive a round trip through the text box. */}
+        {wantsObserved && !isNullary ? (
+          <select
+            className="auto-input is-small autoc-catpick"
+            aria-label={`Add a value seen before, to ${label}`}
+            title={
+              cats.length
+                ? "Values this workspace has actually seen, most-seen first. Adds to the list."
+                : "No category values have been seen in your data yet — type one."
+            }
+            value=""
+            disabled={!cats.length}
+            onChange={(e) => {
+              if (e.target.value) appendValue(e.target.value);
+            }}
+          >
+            <option value="">{cats.length ? "Seen before…" : "None seen yet"}</option>
+            {cats.map((c) => (
+              // The COUNT is the honest half (D-59): a value seen once and one seen forty times
+              // are different bets, and an alphabetical list of bare strings hides that.
+              <option key={c.value} value={c.value}>
+                {c.value} ({c.count.toLocaleString()})
+              </option>
+            ))}
+          </select>
+        ) : null}
+        {isMulti && Array.isArray(p.value) && p.value.length > 1 ? (
+          /*
+           * ⭐ ITEM 16 / D-71 — HOW MANY VALUES THIS CONDITION CARRIES, and against what ceiling.
+           *
+           * The COUNT is ours and is always shown. The CEILING is the server's and is shown only
+           * when the server sends one (`guard.maxValues` — an open `ASK ->A:`; `guard` ships
+           * `{minNarrowing, maxRecords}` today).
+           * ⛔ NO CLIENT-SIDE `4`. D-71's exit says "how many of D-68's 4 value slots" — but A
+           * shipped `depth_refusal()`, which computes the depth of the shape actually emitted
+           * rather than budgeting fixed slots, so the number 4 describes a model that no longer
+           * exists. Printing it would be a client copy of a server rule that has already changed
+           * once, which is the specific failure this file's header refuses to commit
+           * ([[measure-the-real-call]]: a correct-looking answer about the wrong subject).
+           */
+          <span className="autob-cond-any" title="Any one of these is a match">
+            any of {p.value.length}
+            {discover?.guard?.maxValues ? ` of ${discover.guard.maxValues}` : ""}
+          </span>
+        ) : null}
+        <button
+          type="button"
+          className="autob-cond-x"
+          aria-label={`Remove this condition on ${label}`}
+          title="Remove this condition"
+          onClick={() => removeAt(i)}
+        >
+          <svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+            <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+          </svg>
+        </button>
+      </div>
+    );
+  };
+
+  const fieldRow = (row: FieldRow) => {
+    const on = row.at.length > 0;
+    return (
+      <div className={"autob-tgl" + (on ? " is-on" : "")} key={row.name}>
+        <div className="autob-tgl-head">
+          <button
+            type="button"
+            className={"auto-step-switch autob-tgl-switch" + (on ? " is-on" : "")}
+            aria-pressed={on}
+            aria-label={`${on ? "Stop searching" : "Search"} on ${row.label}`}
+            title={`${on ? "Stop searching" : "Search"} on ${row.label}`}
+            onClick={() => toggleField(row)}
+          >
+            <span className="auto-step-switch-knob" />
+          </button>
+          <span className="autob-tgl-mark">
+            <FilterMark name={row.name} />
+          </span>
+          {/* ⭐ THE HUMAN LABEL (owner item 1: "wtf is id/fbid").
+              This used to render the vendor's own column name verbatim, and the comment
+              defending it was RIGHT about the reason — a refusal names the field, and a label
+              that reads differently makes the error unmatchable. So the label did not move
+              alone: `field_label()` is what the SERVER's refusals use too, which is the only
+              version of this change that does not trade one confusion for another. */}
+          <span className="autob-tgl-name" title={row.hint || undefined}>
+            {row.label}
+          </span>
+          {/*
+            ⚠ ONE CHIP, AND IT MARKS THE MINORITY. The first version chipped every
+            non-narrowing field "broad" AND every unpopulated one "no values seen" —
+            which put two chips on 18 of the 21 rows, and one of them repeated the group
+            heading the row was already sitting under. A mark that is on almost every row
+            stops being a mark. Read off the screenshot; no assertion could have said it.
+
+            So: the group label carries POPULATED (it is what the groups ARE), and the
+            chip carries NARROWING, inverted to mark the five that DO narrow. That is the
+            actionable half — the server refuses a filter with no narrowing condition, so
+            "these are the ones that satisfy it" is the sentence a user needs, and
+            "this one does not" is not.
+          */}
+          {row.narrowing === true ? (
+            <span
+              className="autob-tgl-flag is-narrow"
+              title="A search needs at least one condition like this."
+            >
+              narrows
+            </span>
+          ) : null}
+        </div>
+        {on ? (
+          <div className="autob-tgl-body">
+            {row.at.map((i) => condition(i, row.label, row))}
+            {row.hint ? <p className="autob-tgl-hint">{row.hint}</p> : null}
+            <button
+              type="button"
+              className="autob-cond-add"
+              onClick={() =>
+                onPreds([...preds, { name: row.name, operator: firstOperator(discover, row.name) }])
+              }
+            >
+              Another condition on {row.label}
+            </button>
+          </div>
+        ) : null}
+      </div>
+    );
+  };
+
+  return (
+    <>
+      <div className="auto-field">
+        <label htmlFor="auto-records">How many profiles to fetch</label>
+        <input
+          id="auto-records"
+          className="auto-input"
+          type="number"
+          min={1}
+          max={maxRecords}
+          value={recordsLimit}
+          onChange={(e) => onRecordsLimit(Number(e.target.value) || 1)}
+        />
+      </div>
+      {/* Owner item 5: "Stop at the 'A search must be at most 500 profiles a run'". The two
+          sentences that followed explained the vendor's billing model to somebody who wants a
+          list of florists. */}
+      <p className="auto-hint">At most {maxRecords.toLocaleString()} profiles a run.</p>
+
+      <h3>Conditions</h3>
+      <div className="auto-field autob-match">
+        <label htmlFor="auto-joinop">Match</label>
+        <select
+          id="auto-joinop"
+          className="auto-input"
+          value={joinOp}
+          onChange={(e) => onJoinOp(e.target.value)}
+        >
+          <option value="and">All of them</option>
+          <option value="or">Any of them</option>
+        </select>
+      </div>
+
+      {!rows.length ? (
+        <p className="auto-note">
+          The searchable fields have not loaded yet.
+        </p>
+      ) : null}
+
+      {withValues.length ? (
+        <div className="autob-tglgroup">
+          <p
+            className="autob-tglgroup-label"
+            title="Most accounts have this filled in."
+          >
+            Usually filled in
+          </p>
+          {withValues.map(fieldRow)}
+        </div>
+      ) : null}
+
+      {rest.length ? (
+        <div className="autob-tglgroup">
+          <p
+            className="autob-tglgroup-label"
+            title={
+              knownMeta
+                ? "Most accounts leave these blank, so a condition here can return nothing."
+                : "We have not measured how often these are filled in."
+            }
+          >
+            {knownMeta ? "Often blank" : "Not measured"}
+          </p>
+          {rest.map(fieldRow)}
+        </div>
+      ) : null}
+
+      {strays.length ? (
+        <div className="autob-tglgroup">
+          <p className="autob-tglgroup-label">Not in the searchable list</p>
+          {strays.map(({ p, i }) => (
+            <div className="autob-tgl is-on is-stray" key={`stray-${i}`}>
+              <div className="autob-tgl-head">
+                {/* A stray gets a mark too — "every filter row" includes the ones the vendor no
+                    longer offers, and a row missing the icon its neighbours have would read as a
+                    different KIND of thing rather than as a field that fell out of the list. It
+                    draws the neutral fallback by construction: a stray is, by definition, not in
+                    the vocabulary this component has arms for. */}
+                <span className="autob-tgl-mark">
+                  <FilterMark name={p.name} />
+                </span>
+                <span className="autob-tgl-name">{p.name}</span>
+                <span className="autob-tgl-flag is-stray" title="The server will refuse this condition by name.">
+                  not searchable
+                </span>
+              </div>
+              <div className="autob-tgl-body">{condition(i, p.name)}</div>
+            </div>
+          ))}
+        </div>
+      ) : null}
+
+      {/* The consequence kept, the mechanism dropped: a condition on an often-blank field
+          returning nothing is a thing that will happen to somebody and confuse them. Why the
+          search is slow when broad is our problem, not theirs. */}
+      <p className="auto-hint">
+        Conditions on often-blank fields can come back with nothing.
+      </p>
+
+      <h3>What it costs</h3>
+      <div className="auto-head-actions">
+        <button type="button" className="auto-btn" onClick={onEstimate}>
+          Estimate this search
+        </button>
+      </div>
+      {estimate ? (
+        <p className="auto-hint">
+          About <strong>${estimate.usd}</strong> for {estimate.records} profiles, at $
+          {estimate.unitUsd} each.{" "}
+          {/*
+            THE CAVEAT IS NOT OPTIONAL. The vendor never quotes a price before a run and this
+            deployment cannot read its own balance, so presenting this as a billed figure
+            would be inventing a measurement.
+          */}
+          <strong>This is an estimate</strong> — {estimate.note}.
+        </p>
+      ) : null}
+
+      {/* ⭐ WAVE 27 · OWNER ITEM 29 — THE BIG EDITOR, rendered ONCE for the whole panel.
+          ⛔ Not one overlay per condition row: `AnchoredOverlay` mounts a body portal and
+          installs document-level dismiss/focus handlers, so N of them would be N listener
+          stacks fighting over one Escape key. One overlay, told which row it is editing.
+          ⚠ `role="dialog"`, not "menu": it holds a text field, and the menu layer's arrow-key
+          handling would take the cursor keys away from the text being typed. */}
+      {big ? (
+        <AnchoredOverlay
+          anchor={big.anchor}
+          className="autoc-bigedit"
+          placement="right-start"
+          role="dialog"
+          ariaLabel={`Value for ${big.label}`}
+          onDismiss={() => setBig(null)}
+          dataKind="find-value-editor"
+        >
+          <label htmlFor="autoc-bigedit-text">{big.label}</label>
+          <textarea
+            id="autoc-bigedit-text"
+            className="autoc-bigedit-text"
+            data-overlay-autofocus
+            autoFocus
+            rows={7}
+            spellCheck={false}
+            value={big.text}
+            placeholder={big.multi ? "floral, flower, wedding florist, event styling" : ""}
+            onChange={(e) => setBig((cur) => (cur ? { ...cur, text: e.target.value } : cur))}
+            onKeyDown={(e) => {
+              // Escape abandons; Ctrl/Cmd+Enter commits. A bare Enter types a NEWLINE, because
+              // this is a textarea and the whole reason it exists is that the value is long.
+              if (e.key === "Escape") setBig(null);
+              if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
+                setAt(big.index, { value: parseValue(big.text, big.multi) });
+                setBig(null);
+              }
+            }}
+          />
+          {/* The same sentence the rail input's placeholder makes, said where there is room
+              for it: a comma list is several values, and the server turns them into an OR. */}
+          {big.multi ? (
+            <p className="auto-hint">
+              Separate values with commas — the search matches any of them.
+            </p>
+          ) : null}
+          <div className="auto-head-actions">
+            <button
+              type="button"
+              className="auto-btn auto-btn--primary"
+              onClick={() => {
+                setAt(big.index, { value: parseValue(big.text, big.multi) });
+                setBig(null);
+              }}
+            >
+              Done
+            </button>
+            <button type="button" className="auto-btn" onClick={() => setBig(null)}>
+              Cancel
+            </button>
+          </div>
+        </AnchoredOverlay>
+      ) : null}
+    </>
+  );
+}

web/src/automation/AutomationSurface.tsx

@@ -1,664 +1,664 @@
-// ---------------------------------------------------------------------------
-// automation/AutomationSurface.tsx — the Automation surface (contract C-AUTONAV).
-//
-// ⛔ THE CONTRACT THIS FILE GUARANTEES, verbatim: this module path, a DEFAULT
-// export, and NO PROPS. The shell mounts `<AutomationSurface />` and hands it
-// nothing; it fetches its own data from `/api/v1/automations`. That is the whole
-// interface, and it is stated here because the mount line lives in a file this
-// session does not own — a named export would cost a cross-session round trip.
-//
-// "Automation replaces the Views rail" (owner) is implemented the way the wave
-// scout established: the secondary rail is NOT a shell concept — each surface
-// owns its own. So this renders a sibling of `.cg-views` built from the same
-// `--lp-rail-w` tokens and the same fold behaviour, and the Views rail is
-// untouched.
-// ---------------------------------------------------------------------------
-import type { KeyboardEvent as ReactKeyboardEvent } from "react";
-import { useCallback, useEffect, useRef, useState } from "react";
-
-import type { AutomationOpenDetail } from "../apiContract";
-import { AUTOMATION_OPEN_EVENT } from "../apiContract";
-// ⭐ WAVE 26 · ITEM 18 / R14 + C7 — THE LOOPABLE LOOP MARK, CONSUMED, NEVER REDRAWN.
-// The owner's reason is the mark's own geometry: *"these automations are basically loops."*
-// C7 says consume the existing icon component and do not inline a new SVG path, and
-// `shell/Brand.tsx`'s header says why in more detail than a rule could: the mark's one source of
-// truth is generated, it has already been hand-redrawn once, and the copy silently painted LAST
-// WAVE'S BRAND while a comment asserted parity. So this imports the component that POINTS at the
-// generated artifact. [[loopable-nav-logo-toggle]] — one element paints the mark.
-import { Mark } from "../shell/Brand";
-import AutomationDetail from "./AutomationDetail";
-import type { Automation, AutomationList } from "./automationApi";
-import {
-  AutomationError,
-  createAutomation,
-  listAutomations,
-  liveStepOf,
-  patchAutomation,
-} from "./automationApi";
-
-/**
- * The run poll's cadence (item 6). Named constants because they are a MEASURED trade-off, not a
- * taste: `POLL_MAX_MS` is the longest a finished run can still look live, and it is the only
- * cost the backoff has.
- */
-const POLL_MIN_MS = 2500;
-const POLL_MAX_MS = 8000;
-
-/*
- * ⭐ WAVE 26 · ITEM 18 / R14 — `stateTitle` STOOD HERE AND IS DELETED WITH THE DOT IT DESCRIBED.
- *
- * It composed the dot's tooltip ("Running now — <step>", "Last run failed — <summary>"), so it had
- * exactly one reader and no reason to outlive it. Deleting the render and keeping the composer is
- * how a file accumulates functions that look live and are not — and `noUnusedLocals` would have
- * caught this one, which is not a reason to lean on it: the NEXT such function might still have a
- * second caller and compile fine.
- *
- * ⛔ WHY THE TOOLTIP WAS NOT MOVED ONTO THE MARK INSTEAD. R14 is "same mark on every automation;
- * no status colour". Hanging "Last run failed" off a mark that is deliberately status-free just
- * moves the status channel into `title`/`aria-label`, where it is worse: invisible to the eye,
- * announced to a screen reader, and contradicting the visual. The run state has a home one click
- * away — the Builder's own "Last run succeeded / failed" lines, which R13 explicitly keeps.
- *
- * ⚠ `stateOf` ITSELF IS UNTOUCHED in `automationApi.ts`. `Shell.tsx:64/1095` imports it and
- * `liveStepOf` calls it — deleting the export to tidy up this file would break a fence I do not own.
- */
-
-/**
- * The rail's second line — ONE fact, not two.
- *
- * ⚠ It carried "Next 2026-08-04 06:00 · last 2026-08-04 00:20", and the rail is `--lp-rail-w`
- * wide, so it rendered as "Next 2026-08-04 06:00 · l…" — a second line whose only complete word
- * was "Next". Two facts that both truncate are worth less than one that fits. The forward-looking
- * one wins when a schedule exists (it is the question the rail answers: does this run itself?),
- * the last run otherwise. The full picture is one click away in the editor's run history, and the
- * row's `title` already says both.
- *
- * Caught by READING the screenshot: the DOM was correct and the CSS ellipsis was doing exactly
- * its job. [[ui-invisible-to-assertions]] — judge the pixels even when everything is green.
- */
-function railSubtitle(a: Automation): string {
-  /*
-   * ⭐ WAVE 24 (owner item 6, "Run once now is laggy / looks stuck") — WHILE IT IS RUNNING,
-   * THE ONE FACT WORTH THE LINE IS WHAT IT IS DOING.
-   *
-   * MEASURED, not guessed (`scratchpad/perf_automations.py`, mailbox D-5): the engine has been
-   * publishing a live step the whole time (`status.step`, `routes_automation.py:50-51`) and NO
-   * SURFACE HAS EVER RENDERED IT. So a `discover_instagram` run parked in its legitimate
-   * `BD_FILTER_WAIT = 120 s` vendor wait and a genuinely hung thread were pixel-identical: a
-   * pulsing blue dot and a subtitle still reciting the schedule. "Looks stuck" was not a
-   * performance problem — the poll costs 23 ms — it was the product declining to say.
-   *
-   * It takes the line rather than joining it, for the reason this function's note already
-   * gives: the rail is `--lp-rail-w` wide and two facts that both truncate are worth less than
-   * one that fits. The schedule is still one click away and the dot's `title` carries both.
-   */
-  const step = liveStepOf(a);
-  if (step) return step;
-  if (a.schedule?.enabled) return a.nextRunAt ? `Next ${a.nextRunAt}` : "Scheduled";
-  /*
-   * ⭐ WAVE 26 · ITEM 19 / R13 — `Last run 2026-08-06 13:58` IS DELETED FROM THIS LINE.
-   *
-   * ⛔ SCOPE, because R13 draws a line that is easy to over-read: the ruling names THIS secondary
-   * line under the automation's name. The Builder's "Last run succeeded / failed" RESULT lines
-   * (`AutomationBuilder.tsx:1676`, `:1679`) are a different surface and are explicitly NOT in
-   * scope — they are the answer to "Run once now", so deleting them would leave a button with no
-   * outcome.
-   *
-   * "Manual only" STAYS, and the distinction is the ruling's own: a dated run record is a
-   * changing FACT ABOUT THE PAST, while "this one has no schedule" is a stable property of the
-   * automation — the same question `Next …`/`Scheduled` answers for its siblings. Dropping it too
-   * would leave a manual automation with a blank second line and nothing saying why.
-   */
-  return "Manual only";
-}
-
-/*
- * ⛔ W23-W5's LISTENER IS AT MODULE SCOPE, AND THAT IS THE POINT — not a stylistic choice.
- *
- * The frame's click-through sets `window.location.hash = "#/automation"` and signals on the
- * VERY NEXT LINE (Shell.tsx:1647-1650, and its comment is right that the order matters). But a
- * hash write does not mount anything synchronously: `hashchange` is delivered as a task, the
- * router state then updates, React renders, and only THEN does a component effect subscribe.
- * A listener registered in `useEffect` therefore misses every click that arrives from another
- * page — which is every click, since a reader looking at Alerts is by definition not already
- * on this surface. The event would dispatch into nothing and every gate would stay green:
- * exactly the wave-20 item-25 failure the contract's own note describes, reproduced one layer
- * down.
- *
- * This module is imported statically by the shell, so this listener exists from app start. It
- * LATCHES the request; the component consumes the latch when it mounts and hears live events
- * while it is mounted. A request nobody claims is dropped on the next one — the latch is a
- * one-slot mailbox, never a queue.
- */
-let pendingOpen: AutomationOpenDetail | null = null;
-const openSubscribers = new Set<(detail: AutomationOpenDetail) => void>();
-
-if (typeof window !== "undefined") {
-  window.addEventListener(AUTOMATION_OPEN_EVENT, (event) => {
-    const detail = (event as CustomEvent<AutomationOpenDetail>).detail;
-    if (!detail?.autoId) return;
-    if (openSubscribers.size) {
-      for (const notify of openSubscribers) notify(detail);
-      return;
-    }
-    pendingOpen = detail;
-  });
-}
-
-/*
- * ⛔ THE `AUTOMATION_CREATE_EVENT` LISTENER STOOD HERE AND IS DELETED WITH ITS SIGNALLER
- * (wave 25 item 5a, ruling R8) — latch, subscriber set and all.
- *
- * Wave 24 built it to close the opposite defect: the event was declared, signalled from
- * `Shell.tsx`, and consumed NOWHERE, so all three "Automated database" doors navigated to
- * `#/automation` and then did nothing, in production, with every gate green. R8 now deletes those
- * three doors — creating a database and pointing an automation at it are two acts — and they were
- * the event's only signaller.
- *
- * ⛔ SO THIS SIDE GOES TOO, IN THE SAME CHANGE. A listener with no signaller is the same defect
- * read from the other end: it compiles, it costs nothing at runtime, and it reads to the next
- * person as a live channel. The rule that catches both is now DERIVED rather than remembered —
- * `verify_automation_ui.py` enumerates every `AUTOMATION_*_EVENT` in `apiContract.ts` and demands
- * a signal site AND a listener site for each.
- *
- * ⚠ NOTHING ABOUT CREATING AN AUTOMATION IS LOST. `createAndOpen` is untouched and still has two
- * doors, both on this surface: the rail's button and the empty state's. What is gone is the claim
- * that a database can be created BY asking for an automation.
- */
-
-/**
- * A default name for a brand-new automation, and it has to be one the server ACCEPTS.
- *
- * MEASURED against the live route rather than assumed (`scratchpad/probe_names.py`): a create
- * with no name is a 400 (`name the automation`), and duplicate names are ALLOWED. So the name
- * cannot be omitted, and a fixed literal would stack "New automation" three deep in a rail that
- * sorts by name with nothing to tell the rows apart. Numbering from the existing list is a
- * client-side convenience over a server that does not care: if two tabs race, the loser gets a
- * duplicate name, which is legal, visible and renameable — never an error the user has to read.
- */
-function nextAutomationName(existing: Automation[]): string {
-  const taken = new Set(existing.map((a) => (a.name || "").trim().toLowerCase()));
-  for (let n = existing.length + 1; ; n += 1) {
-    const candidate = `Automation ${n}`;
-    if (!taken.has(candidate.toLowerCase())) return candidate;
-  }
-}
-
-export default function AutomationSurface() {
-  const [data, setData] = useState<AutomationList | null>(null);
-  const [error, setError] = useState("");
-  const [activeId, setActiveId] = useState<string>("");
-  const [railShut, setRailShut] = useState(false);
-  const [busy, setBusy] = useState("");
-  /**
-   * ⭐ WAVE 24 / C-CREATE — a create is now a ROUND TRIP, not a local wizard, so the door has to
-   * say it is busy. Without this a second click while the POST is in flight makes a second
-   * automation, and the server allows duplicate names, so the user gets two rows that look
-   * identical and no error to explain either of them.
-   */
-  const [creatingNow, setCreatingNow] = useState(false);
-  /** An open request waiting for the list to arrive (see the resolver below). */
-  const [openRequest, setOpenRequest] = useState<AutomationOpenDetail | null>(null);
-  /* ⛔ `createRequest` LEFT WITH THE EVENT THAT SET IT (wave 25, R8) — see the tombstone above. */
-  const listRef = useRef<HTMLDivElement | null>(null);
-
-  /**
-   * ⛔ C14 LEG 2 — THE ID THE USER LAST ASKED FOR, and it is a ref because it has to be
-   * written SYNCHRONOUSLY, inside the click, before any promise that was already in flight
-   * can resolve. State would not do: a resolution racing React's commit would read the
-   * previous value, which is the exact window this guard exists to close.
-   */
-  const wantedId = useRef("");
-
-  /**
-   * ⭐ THE ONLY PLACE THE RAIL'S SELECTION MOVES ON PURPOSE. Every deliberate change of
-   * automation — a rail click, a create, a delete — goes through here, so "what the user
-   * asked for" and "what is on screen" are written in one statement and cannot drift apart.
-   * A resolution that wants to steer the rail compares itself against `wantedId` instead.
-   */
+// ---------------------------------------------------------------------------
+// automation/AutomationSurface.tsx — the Automation surface (contract C-AUTONAV).
+//
+// ⛔ THE CONTRACT THIS FILE GUARANTEES, verbatim: this module path, a DEFAULT
+// export, and NO PROPS. The shell mounts `<AutomationSurface />` and hands it
+// nothing; it fetches its own data from `/api/v1/automations`. That is the whole
+// interface, and it is stated here because the mount line lives in a file this
+// session does not own — a named export would cost a cross-session round trip.
+//
+// "Automation replaces the Views rail" (owner) is implemented the way the wave
+// scout established: the secondary rail is NOT a shell concept — each surface
+// owns its own. So this renders a sibling of `.cg-views` built from the same
+// `--lp-rail-w` tokens and the same fold behaviour, and the Views rail is
+// untouched.
+// ---------------------------------------------------------------------------
+import type { KeyboardEvent as ReactKeyboardEvent } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import type { AutomationOpenDetail } from "../apiContract";
+import { AUTOMATION_OPEN_EVENT } from "../apiContract";
+// ⭐ WAVE 26 · ITEM 18 / R14 + C7 — THE LOOPABLE LOOP MARK, CONSUMED, NEVER REDRAWN.
+// The owner's reason is the mark's own geometry: *"these automations are basically loops."*
+// C7 says consume the existing icon component and do not inline a new SVG path, and
+// `shell/Brand.tsx`'s header says why in more detail than a rule could: the mark's one source of
+// truth is generated, it has already been hand-redrawn once, and the copy silently painted LAST
+// WAVE'S BRAND while a comment asserted parity. So this imports the component that POINTS at the
+// generated artifact. [[loopable-nav-logo-toggle]] — one element paints the mark.
+import { Mark } from "../shell/Brand";
+import AutomationDetail from "./AutomationDetail";
+import type { Automation, AutomationList } from "./automationApi";
+import {
+  AutomationError,
+  createAutomation,
+  listAutomations,
+  liveStepOf,
+  patchAutomation,
+} from "./automationApi";
+
+/**
+ * The run poll's cadence (item 6). Named constants because they are a MEASURED trade-off, not a
+ * taste: `POLL_MAX_MS` is the longest a finished run can still look live, and it is the only
+ * cost the backoff has.
+ */
+const POLL_MIN_MS = 2500;
+const POLL_MAX_MS = 8000;
+
+/*
+ * ⭐ WAVE 26 · ITEM 18 / R14 — `stateTitle` STOOD HERE AND IS DELETED WITH THE DOT IT DESCRIBED.
+ *
+ * It composed the dot's tooltip ("Running now — <step>", "Last run failed — <summary>"), so it had
+ * exactly one reader and no reason to outlive it. Deleting the render and keeping the composer is
+ * how a file accumulates functions that look live and are not — and `noUnusedLocals` would have
+ * caught this one, which is not a reason to lean on it: the NEXT such function might still have a
+ * second caller and compile fine.
+ *
+ * ⛔ WHY THE TOOLTIP WAS NOT MOVED ONTO THE MARK INSTEAD. R14 is "same mark on every automation;
+ * no status colour". Hanging "Last run failed" off a mark that is deliberately status-free just
+ * moves the status channel into `title`/`aria-label`, where it is worse: invisible to the eye,
+ * announced to a screen reader, and contradicting the visual. The run state has a home one click
+ * away — the Builder's own "Last run succeeded / failed" lines, which R13 explicitly keeps.
+ *
+ * ⚠ `stateOf` ITSELF IS UNTOUCHED in `automationApi.ts`. `Shell.tsx:64/1095` imports it and
+ * `liveStepOf` calls it — deleting the export to tidy up this file would break a fence I do not own.
+ */
+
+/**
+ * The rail's second line — ONE fact, not two.
+ *
+ * ⚠ It carried "Next 2026-08-04 06:00 · last 2026-08-04 00:20", and the rail is `--lp-rail-w`
+ * wide, so it rendered as "Next 2026-08-04 06:00 · l…" — a second line whose only complete word
+ * was "Next". Two facts that both truncate are worth less than one that fits. The forward-looking
+ * one wins when a schedule exists (it is the question the rail answers: does this run itself?),
+ * the last run otherwise. The full picture is one click away in the editor's run history, and the
+ * row's `title` already says both.
+ *
+ * Caught by READING the screenshot: the DOM was correct and the CSS ellipsis was doing exactly
+ * its job. [[ui-invisible-to-assertions]] — judge the pixels even when everything is green.
+ */
+function railSubtitle(a: Automation): string {
+  /*
+   * ⭐ WAVE 24 (owner item 6, "Run once now is laggy / looks stuck") — WHILE IT IS RUNNING,
+   * THE ONE FACT WORTH THE LINE IS WHAT IT IS DOING.
+   *
+   * MEASURED, not guessed (`scratchpad/perf_automations.py`, mailbox D-5): the engine has been
+   * publishing a live step the whole time (`status.step`, `routes_automation.py:50-51`) and NO
+   * SURFACE HAS EVER RENDERED IT. So a `discover_instagram` run parked in its legitimate
+   * `BD_FILTER_WAIT = 120 s` vendor wait and a genuinely hung thread were pixel-identical: a
+   * pulsing blue dot and a subtitle still reciting the schedule. "Looks stuck" was not a
+   * performance problem — the poll costs 23 ms — it was the product declining to say.
+   *
+   * It takes the line rather than joining it, for the reason this function's note already
+   * gives: the rail is `--lp-rail-w` wide and two facts that both truncate are worth less than
+   * one that fits. The schedule is still one click away and the dot's `title` carries both.
+   */
+  const step = liveStepOf(a);
+  if (step) return step;
+  if (a.schedule?.enabled) return a.nextRunAt ? `Next ${a.nextRunAt}` : "Scheduled";
+  /*
+   * ⭐ WAVE 26 · ITEM 19 / R13 — `Last run 2026-08-06 13:58` IS DELETED FROM THIS LINE.
+   *
+   * ⛔ SCOPE, because R13 draws a line that is easy to over-read: the ruling names THIS secondary
+   * line under the automation's name. The Builder's "Last run succeeded / failed" RESULT lines
+   * (`AutomationBuilder.tsx:1676`, `:1679`) are a different surface and are explicitly NOT in
+   * scope — they are the answer to "Run once now", so deleting them would leave a button with no
+   * outcome.
+   *
+   * "Manual only" STAYS, and the distinction is the ruling's own: a dated run record is a
+   * changing FACT ABOUT THE PAST, while "this one has no schedule" is a stable property of the
+   * automation — the same question `Next …`/`Scheduled` answers for its siblings. Dropping it too
+   * would leave a manual automation with a blank second line and nothing saying why.
+   */
+  return "Manual only";
+}
+
+/*
+ * ⛔ W23-W5's LISTENER IS AT MODULE SCOPE, AND THAT IS THE POINT — not a stylistic choice.
+ *
+ * The frame's click-through sets `window.location.hash = "#/automation"` and signals on the
+ * VERY NEXT LINE (Shell.tsx:1647-1650, and its comment is right that the order matters). But a
+ * hash write does not mount anything synchronously: `hashchange` is delivered as a task, the
+ * router state then updates, React renders, and only THEN does a component effect subscribe.
+ * A listener registered in `useEffect` therefore misses every click that arrives from another
+ * page — which is every click, since a reader looking at Alerts is by definition not already
+ * on this surface. The event would dispatch into nothing and every gate would stay green:
+ * exactly the wave-20 item-25 failure the contract's own note describes, reproduced one layer
+ * down.
+ *
+ * This module is imported statically by the shell, so this listener exists from app start. It
+ * LATCHES the request; the component consumes the latch when it mounts and hears live events
+ * while it is mounted. A request nobody claims is dropped on the next one — the latch is a
+ * one-slot mailbox, never a queue.
+ */
+let pendingOpen: AutomationOpenDetail | null = null;
+const openSubscribers = new Set<(detail: AutomationOpenDetail) => void>();
+
+if (typeof window !== "undefined") {
+  window.addEventListener(AUTOMATION_OPEN_EVENT, (event) => {
+    const detail = (event as CustomEvent<AutomationOpenDetail>).detail;
+    if (!detail?.autoId) return;
+    if (openSubscribers.size) {
+      for (const notify of openSubscribers) notify(detail);
+      return;
+    }
+    pendingOpen = detail;
+  });
+}
+
+/*
+ * ⛔ THE `AUTOMATION_CREATE_EVENT` LISTENER STOOD HERE AND IS DELETED WITH ITS SIGNALLER
+ * (wave 25 item 5a, ruling R8) — latch, subscriber set and all.
+ *
+ * Wave 24 built it to close the opposite defect: the event was declared, signalled from
+ * `Shell.tsx`, and consumed NOWHERE, so all three "Automated database" doors navigated to
+ * `#/automation` and then did nothing, in production, with every gate green. R8 now deletes those
+ * three doors — creating a database and pointing an automation at it are two acts — and they were
+ * the event's only signaller.
+ *
+ * ⛔ SO THIS SIDE GOES TOO, IN THE SAME CHANGE. A listener with no signaller is the same defect
+ * read from the other end: it compiles, it costs nothing at runtime, and it reads to the next
+ * person as a live channel. The rule that catches both is now DERIVED rather than remembered —
+ * `verify_automation_ui.py` enumerates every `AUTOMATION_*_EVENT` in `apiContract.ts` and demands
+ * a signal site AND a listener site for each.
+ *
+ * ⚠ NOTHING ABOUT CREATING AN AUTOMATION IS LOST. `createAndOpen` is untouched and still has two
+ * doors, both on this surface: the rail's button and the empty state's. What is gone is the claim
+ * that a database can be created BY asking for an automation.
+ */
+
+/**
+ * A default name for a brand-new automation, and it has to be one the server ACCEPTS.
+ *
+ * MEASURED against the live route rather than assumed (`scratchpad/probe_names.py`): a create
+ * with no name is a 400 (`name the automation`), and duplicate names are ALLOWED. So the name
+ * cannot be omitted, and a fixed literal would stack "New automation" three deep in a rail that
+ * sorts by name with nothing to tell the rows apart. Numbering from the existing list is a
+ * client-side convenience over a server that does not care: if two tabs race, the loser gets a
+ * duplicate name, which is legal, visible and renameable — never an error the user has to read.
+ */
+function nextAutomationName(existing: Automation[]): string {
+  const taken = new Set(existing.map((a) => (a.name || "").trim().toLowerCase()));
+  for (let n = existing.length + 1; ; n += 1) {
+    const candidate = `Automation ${n}`;
+    if (!taken.has(candidate.toLowerCase())) return candidate;
+  }
+}
+
+export default function AutomationSurface() {
+  const [data, setData] = useState<AutomationList | null>(null);
+  const [error, setError] = useState("");
+  const [activeId, setActiveId] = useState<string>("");
+  const [railShut, setRailShut] = useState(false);
+  const [busy, setBusy] = useState("");
+  /**
+   * ⭐ WAVE 24 / C-CREATE — a create is now a ROUND TRIP, not a local wizard, so the door has to
+   * say it is busy. Without this a second click while the POST is in flight makes a second
+   * automation, and the server allows duplicate names, so the user gets two rows that look
+   * identical and no error to explain either of them.
+   */
+  const [creatingNow, setCreatingNow] = useState(false);
+  /** An open request waiting for the list to arrive (see the resolver below). */
+  const [openRequest, setOpenRequest] = useState<AutomationOpenDetail | null>(null);
+  /* ⛔ `createRequest` LEFT WITH THE EVENT THAT SET IT (wave 25, R8) — see the tombstone above. */
+  const listRef = useRef<HTMLDivElement | null>(null);
+
+  /**
+   * ⛔ C14 LEG 2 — THE ID THE USER LAST ASKED FOR, and it is a ref because it has to be
+   * written SYNCHRONOUSLY, inside the click, before any promise that was already in flight
+   * can resolve. State would not do: a resolution racing React's commit would read the
+   * previous value, which is the exact window this guard exists to close.
+   */
+  const wantedId = useRef("");
+
+  /**
+   * ⭐ THE ONLY PLACE THE RAIL'S SELECTION MOVES ON PURPOSE. Every deliberate change of
+   * automation — a rail click, a create, a delete — goes through here, so "what the user
+   * asked for" and "what is on screen" are written in one statement and cannot drift apart.
+   * A resolution that wants to steer the rail compares itself against `wantedId` instead.
+   */
   const select = useCallback((id: string, _stage = "") => {
-    wantedId.current = id;
-    setActiveId(id);
-  }, []);
-
-  /**
-   * ⛔ C14 LEG 3 (the paint half) — A STALE READ MAY NOT REPAINT.
-   *
-   * Every call takes the next generation; only the newest one is allowed to `setData`. The
-   * defect this closes is not cosmetic: a poll issued BEFORE a delete resolves AFTER it, and
-   * a list that still contains the deleted automation puts a row back in the rail that the
-   * user has just watched disappear. Same for a toggle, and same for a create.
-   *
-   * ⚠ THE RETURN VALUE IS NOT GUARDED, deliberately. The caller asked a question and gets
-   * its own answer — coupling the two would mean a create whose `load()` was overtaken by a
-   * poll silently failed to select the automation it had just made.
-   */
-  const gen = useRef(0);
-
-  const load = useCallback(async (abort?: AbortSignal) => {
-    const mine = ++gen.current;
-    try {
-      const next = await listAutomations(abort);
-      if (mine === gen.current) {
-        setData(next);
-        setError("");
-      }
-      return next;
-    } catch (e) {
-      if ((e as Error)?.name === "AbortError") return null;
-      if (mine === gen.current)
-        setError(
-          e instanceof AutomationError
-            ? e.message
-            : "The automation service did not answer."
-        );
-      return null;
-    }
-  }, []);
-
-  useEffect(() => {
-    const ac = new AbortController();
-    void load(ac.signal);
-    return () => ac.abort();
-  }, [load]);
-
-  /**
-   * ⭐⭐ WAVE 24 / C-CREATE (a) — CREATE AND OPEN. This REPLACED the three-step wizard.
-   *
-   * R6 is what makes it possible: `plain` is a real kind with no machine graph nodes, and it is
-   * what `POST /automations` stores when the body names none. So "new automation" stopped being
-   * a question ("which of three kinds?" — two of which can no longer be created at all) and
-   * became what it says: a new automation, open, on its trigger picker. Choosing a SOURCE is now
-   * picking the `ig_profile_match` trigger, which is where that choice belongs.
-   *
-   * ⛔ THE GUARD IS A REF, not the `creatingNow` state, and this file already carries the scar
-   * that explains why (C14 leg 2): a state read inside a click closure is the value from the
-   * last render, so two fast clicks both see `false` and both POST. Duplicate names are legal
-   * server-side, so the user would get two identical rows and no error. The ref is written
-   * synchronously, inside the click, before anything can await.
-   */
-  const creatingRef = useRef(false);
-  const createAndOpen = useCallback(async () => {
-    if (creatingRef.current) return;
-    creatingRef.current = true;
-    setCreatingNow(true);
-    try {
-      const res = await createAutomation({
-        name: nextAutomationName(data?.automations || []),
-      });
-      const id = res?.automation?.id || "";
-      // The create flow is the one caller allowed to name a different id (C14 leg 2) — the
-      // automation did not exist when the click happened, so there is nothing to race with.
-      const next = await load();
-      if (id && next) select(id);
-    } catch (e) {
-      setError(
-        e instanceof AutomationError ? e.message : "The automation was not created."
-      );
-    } finally {
-      creatingRef.current = false;
-      setCreatingNow(false);
-    }
-  }, [data, load, select]);
-
-  // A run is a background thread on the server, so the surface has to ASK whether it
-  // finished. Polling only while something is actually running keeps an idle surface
-  // silent — a fixed interval would be a request every few seconds forever, for a page
-  // whose contents change a handful of times a day.
-  //
-  // ⛔ C14 LEG 3 (the abort half). It used to call `load()` bare — no signal, nothing to
-  // cancel — so a request the interval had already issued kept going after the effect that
-  // owned it was gone. One controller per effect run, aborted with the interval, means a poll
-  // cannot outlive the condition that justified it. The generation guard inside `load` covers
-  // the rest: a response that survives the abort still cannot repaint over a newer one.
-  //
-  // ⭐ WAVE 24 (item 6, C-PERF) — THE INTERVAL BECAME A BACKOFF, and the measurement is why it is
-  // a SMALL change rather than the big one the contract's hypothesis 2 asked for.
-  //
-  // MEASURED (`scratchpad/perf_automations.py`, mailbox D-5): this poll costs ~23 ms and 24 KB
-  // for a ten-automation tenant, and the engine work the hypothesis blamed — a `graph()` rebuild
-  // per automation — is **41 µs each**, i.e. under 4% of the request. The payload was never the
-  // problem, so nothing here gets a cheaper endpoint.
-  //
-  // What the numbers DO indict is the aggregate: a discovery run legitimately blocks up to
-  // `BD_FILTER_WAIT` = 120 s, and two independent 2.5 s polls across this file and the detail
-  // spend ~96 requests and ~2.3 MB over that window — in the same single process the run itself
-  // is a thread in. So the delay grows 2.5 → 5 → 8 s and stops there.
-  //
-  // ⚠ NOT "to learn nothing", and the distinction is the whole justification. That WAS true when
-  // this file rendered no live step: the poll's only observable effect was a dot that had already
-  // been pulsing for two minutes. It stopped being true in this same change — `liveStepOf` now
-  // paints `status.step`, so a poll carries the one fact worth having. The backoff is therefore
-  // NOT "stop asking a pointless question"; it is FEWER ROUND TRIPS FOR THE SAME INFORMATION, on
-  // a step text that changes every few seconds at most, not every 2.5.
-  // The cap is deliberately low: it bounds how long a FINISHED run can still look live, which is
-  // the only thing a backoff can make worse, and 8 s of that is worth ~⅔ fewer requests.
-  //
-  // ⛔ THE KEY IS THE RUNNING SET, NOT A BOOLEAN, and that is what makes the reset correct: the
-  // effect re-runs — and the delay drops back to 2.5 s — the moment a run starts or finishes, so
-  // a user who clicks Run now gets the fast cadence again instead of inheriting the tail of the
-  // previous run's backoff. A bare `anyRunning` boolean cannot see the second run start.
-  // A step text changing does NOT re-key it, so the interval never thrashes.
-  //
-  // C14 LEG 3 (the abort half) is unchanged and still load-bearing: one controller per effect
-  // run, aborted with the timer, so a poll cannot outlive the condition that justified it. The
-  // generation guard inside `load` covers the rest.
-  const runningKey = (data?.automations || [])
-    .filter((a) => a.running)
-    .map((a) => a.id)
-    .sort()
-    .join(",");
-  useEffect(() => {
-    if (!runningKey) return undefined;
-    const ac = new AbortController();
-    let delay = POLL_MIN_MS;
-    let timer = 0;
-    const tick = () => {
-      void load(ac.signal);
-      delay = Math.min(delay * 2, POLL_MAX_MS);
-      timer = window.setTimeout(tick, delay);
-    };
-    timer = window.setTimeout(tick, delay);
-    return () => {
-      window.clearTimeout(timer);
-      ac.abort();
-    };
-  }, [runningKey, load]);
-
-  // ── W23-W5, the surface's half: hear the request, then answer it when we CAN ──────────
-  useEffect(() => {
-    const notify = (detail: AutomationOpenDetail) => setOpenRequest(detail);
-    openSubscribers.add(notify);
-    if (pendingOpen) {
-      const latched = pendingOpen;
-      pendingOpen = null;
-      setOpenRequest(latched);
-    }
-    return () => {
-      openSubscribers.delete(notify);
-    };
-  }, []);
-
-  /* ⛔ THE C-CREATE(b) SUBSCRIBE EFFECT AND ITS RESOLVER STOOD HERE (wave 25, R8). They heard the
-     create event and, once the list had arrived, called `createAndOpen` — the "wait for the list
-     or every automation is named Automation 1" note lives on in `nextAutomationName`, which is
-     still numbered off `existing`. With no signaller there is nothing to hear. */
-
-  /**
-   * ⚠ THE REQUEST OUTLIVES THE FETCH, and it has to. The reader clicks a notification from
-   * another page, so this surface is mounting WITH AN EMPTY LIST — "select it if it is in the
-   * list" would drop every real click and keep only the one case where the reader was already
-   * here. So the request is held until `data` exists, and only then answered.
-   *
-   * An automation the reader can no longer open does NOTHING (the contract's own words): the
-   * request is cleared either way, so a stale id cannot sit here re-firing against every
-   * subsequent list.
-   */
-  useEffect(() => {
-    if (!openRequest || !data) return;
-    const found = (data.automations || []).some((a) => a.id === openRequest.autoId);
-    if (found) {
-      select(openRequest.autoId, openRequest.stageId || "");
-    }
-    setOpenRequest(null);
-  }, [openRequest, data, select]);
-
-  const items = data?.automations || [];
-  const active = items.find((a) => a.id === activeId) || null;
-
-  const toggleEnabled = async (a: Automation) => {
-    setBusy(a.id);
-    try {
-      await patchAutomation(a.id, {
-        schedule: { cron: a.schedule.cron, enabled: !a.schedule.enabled },
-      });
-      await load();
-    } catch (e) {
-      setError(e instanceof AutomationError ? e.message : "That change was not saved.");
-    } finally {
-      setBusy("");
-    }
-  };
-
-  const onRailKey = (event: ReactKeyboardEvent<HTMLDivElement>) => {
-    if (event.key !== "ArrowDown" && event.key !== "ArrowUp") return;
-    const rows = Array.from(
-      listRef.current?.querySelectorAll<HTMLButtonElement>(".auto-row-main") || []
-    );
-    if (!rows.length) return;
-    event.preventDefault();
-    const at = rows.indexOf(document.activeElement as HTMLButtonElement);
-    const next = event.key === "ArrowDown" ? (at + 1) % rows.length
-      : (at - 1 + rows.length) % rows.length;
-    rows[next < 0 ? 0 : next]?.focus();
-  };
-
-  return (
-    <div className="auto-surface">
-      <aside
-        className={"auto-rail" + (railShut ? " is-collapsed" : "")}
-        aria-label="Automations"
-      >
-        {/* The same three-bars fold control the Views rail carries — the two rails are
-            one idea, so they must not fold with two different affordances. */}
-        <div className="auto-rail-top">
-          <button
-            type="button"
-            className="cg-rail-toggle"
-            aria-label={railShut ? "Expand automations" : "Minimize automations"}
-            aria-expanded={!railShut}
-            title={railShut ? "Expand automations" : "Minimize automations"}
-            onClick={() => setRailShut((v) => !v)}
-          >
-            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
-              <path
-                d="M2.5 4.4h11M2.5 8h11M2.5 11.6h11"
-                stroke="currentColor"
-                strokeWidth="1.35"
-                strokeLinecap="round"
-              />
-            </svg>
-          </button>
-        </div>
-
-        <div className="auto-create">
-          <button
-            type="button"
-            className="auto-create-btn"
-            disabled={creatingNow}
-            onClick={() => void createAndOpen()}
-          >
-            <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
-              <path
-                d="M8 3.4v9.2M3.4 8h9.2"
-                stroke="currentColor"
-                strokeWidth="1.5"
-                strokeLinecap="round"
-              />
-            </svg>
-            New automation
-          </button>
-        </div>
-
-        <div className="auto-list" ref={listRef} onKeyDown={onRailKey}>
-          {items.map((a) => {
-            return (
-              <div
-                key={a.id}
-                className={"auto-row" + (a.id === activeId ? " is-active" : "")}
-              >
-                <button
-                  type="button"
-                  className="auto-row-main"
-                  onClick={() => select(a.id)}
-                >
-                  {/* ⭐ ITEM 18 / R14 — THE LOOP MARK, WHERE THE STATUS DOT WAS. Same mark on
-                      every row, no status colour: the owner's point is that an automation IS a
-                      loop, not that this one is green. The `.auto-loopmark` wrapper is what sizes
-                      it — `.lp-mark` is shell-owned CSS and outside this session's region, so the
-                      box is mine and the mark is theirs. */}
-                  <span className="auto-loopmark">
-                    <Mark size={15} />
-                  </span>
-                  <span className="auto-row-text">
-                    <span className="auto-row-name">{a.name}</span>
-                    <span className="auto-row-desc">{railSubtitle(a)}</span>
-                  </span>
-                </button>
-                <button
-                  type="button"
-                  className={"auto-row-switch" + (a.schedule?.enabled ? " is-on" : "")}
-                  disabled={busy === a.id}
-                  aria-pressed={!!a.schedule?.enabled}
-                  title={
-                    a.schedule?.enabled
-                      ? `Scheduled: ${a.schedule.cron}. Click to pause.`
-                      : "Not scheduled. Click to enable."
-                  }
-                  onClick={() => void toggleEnabled(a)}
-                >
-                  <span className="auto-row-switch-knob" />
-                </button>
-              </div>
-            );
-          })}
-          {/* ONE LINE (R13). It used to describe the kinds — "one reads a public web page…
-              the other fills an automation column…" — which was two sentences, wrong by the
-              time a third kind shipped, and printed inside a `--lp-rail-w` column. What the
-              kinds are belongs to the create form, which is one click away and lists all of
-              them from the server. */}
-          {!items.length && !error ? (
-            <p className="auto-rail-empty">No automations yet.</p>
-          ) : null}
-        </div>
-      </aside>
-
-      <section className="auto-main">
-        {error ? (
-          <div className="auto-banner is-error" role="alert">
-            {error}
-          </div>
-        ) : null}
-        {data && !data.storeAvailable ? (
-          <div className="auto-banner is-warn" role="status">
-            The tenant store is unavailable, so nothing can be saved right now.
-          </div>
-        ) : null}
-
-        {/*
-          ⛔ THE `creating` BRANCH IS GONE (wave 24, C-CREATE a / owner items 3 + 4).
-          `AutomationCreate` used to render here — a three-step wizard whose first step asked
-          which DATABASE to write into (an existing one, a new one, or one the automation itself
-          would create) and whose second asked which of three KINDS.
-          R6 retires that question at the root: two of the three kinds can no longer be created
-          at all, and the third is now reached by picking a trigger. A new automation is created
-          the moment it is asked for (`createAndOpen`) and opens on its own Builder, so there is
-          no intermediate face left to render and no `creating` state to hold.
-          ⭐ WAVE 25 (R8) retires the LAST of that vocabulary: the third answer was the
-          "automated database", and it is gone from every door in the product. This button is now
-          one of exactly two ways to make an automation, and both are on this surface.
-          The import went with it — it is what would break `npx tsc -b` for the WHOLE client the
-          moment session B deletes the file, which is why this deletion is sequenced first.
-        */}
-        {active ? (
-          <AutomationDetail
-            key={active.id}
-            automation={active}
-            /* ⛔ `kinds={data?.kinds || []}` LEFT HERE WITH THE PROP IT FED (wave 25, D-57) —
-               both halves in one change, because either alone is a `tsc` error. */
-            cronPresets={data?.cronPresets || []}
-            paidReady={!!data?.paidReady}
-            discover={data?.discover}
-            // The trigger vocabulary (C3). Forwarded as-is — absent stays absent, so the
-            // trigger face can tell "the server offered nothing" from "the server offered
-            // an empty list" rather than collapsing both into a picker with no options.
-            triggers={data?.triggers}
-            // C4's action menu + the builder's ceilings. Forwarded as-is for the same reason
-            // `triggers` is: absent must stay absent, so the builder can tell "the server
-            // offered nothing" from "the server offered an empty list".
-            catalog={data?.actionsCatalog}
-            vocab={data?.flow}
-            // `?? null` and never `|| {enabled:false}`: an absent tick bit is "the server did
-            // not say", which Step 1 prints as its own sentence. Defaulting it here would
-            // turn a missing field into a claim about production (C6 amendment #1).
-            tick={data?.tick ?? null}
-            /*
-             * ⭐ W24-W1 (item 6) — WHAT THIS RUN IS DOING, on the one surface that survives in
-             * BOTH views. REQUIRED on the far side deliberately: an optional prop that nobody
-             * passes degrades to "the feature does not exist", which is indistinguishable from
-             * "it was never built" — and this whole item exists because a live step text rode
-             * the wire for three waves with nothing rendering it.
-             * `liveStepOf` returns the step ONLY while the automation is running; a stale step
-             * from a finished run is a worse answer than none.
-             */
-            liveStep={liveStepOf(active)}
-            /*
-             * ⛔ C14 LEG 2 — THE STALE-ID WRITE-BACK, and this is the ghost's second cause.
-             *
-             * The detail calls `onSaved(automation.id)` from six places (save, the trigger
-             * picker, a schedule change, a node switch, a card move, a run). Each closure
-             * captures the automation it was mounted for, so a save that resolves AFTER the
-             * user has clicked a different row used to call `setActiveId(the OLD id)` — the
-             * rail jumped back, the detail remounted, and what the user saw was the previous
-             * automation reappearing over the one they had just opened. It looked like a
-             * rendering bug; it was a resolution steering the selection.
-             *
-             * A resolution may no longer steer anything. It reloads the list — that part was
-             * always right — and it re-asserts the selection ONLY when its id is still the one
-             * the user asked for, which makes the write a no-op in the good case and nothing
-             * at all in the bad one.
-             */
-            onSaved={async (id) => {
-              const next = await load();
-              if (id && next && id === wantedId.current) select(id);
-            }}
-            onDeleted={async () => {
-              select("");
-              await load();
-            }}
-          />
-        ) : (
-          /*
-           * THE EMPTY STATE IS ONE LINE AND A BUTTON (owner ruling R13 — "never
-           * over-explain", now a DESIGN.md law).
-           *
-           * It was a heading, a three-sentence paragraph and a 130-word bulleted list
-           * describing all three kinds. Every word of it was true and none of it was READ:
-           * an empty state is passed through, not studied, and the person looking at it has
-           * already decided to make an automation. The kinds are described where the choice
-           * is actually made — the create form lists them FROM THE SERVER, so that copy also
-           * cannot go stale the way this list had (it described two kinds after a third
-           * shipped).
-           *
-           * The button is here rather than only in the rail because this pane is where the
-           * eye is; a create affordance the user has to go find is the same defect as the
-           * paragraph, spent differently.
-           */
-          <div className="autob-empty">
-            {/*
-              ⛔ NO TITLE HERE ANY MORE (C13, owner item 2). This pane carried an `h1`
-              reading "Automations" at 20px/600 — a THIRD title treatment on a page that
-              also had the header's editable 16px/700 input, against every database page's
-              single 16px/650 `shell-db-name`. The shell now wraps this branch in the same
-              `shell-db-frame` + `DbHead` a database gets (wiring W23-W1), so the page's name
-              is drawn once, by the one component that draws every other page's name. A
-              stand-in restyled to match would have been a second copy of the same fact,
-              free to drift the day the header moves.
-            */}
-            <p className="autob-empty-line">
-              A job this workspace runs for you, on demand or on a schedule.
-            </p>
-            <button
-              type="button"
-              className="auto-btn is-primary"
-              disabled={creatingNow}
-              onClick={() => void createAndOpen()}
-            >
-              New automation
-            </button>
-          </div>
-        )}
-      </section>
-    </div>
-  );
-}
+    wantedId.current = id;
+    setActiveId(id);
+  }, []);
+
+  /**
+   * ⛔ C14 LEG 3 (the paint half) — A STALE READ MAY NOT REPAINT.
+   *
+   * Every call takes the next generation; only the newest one is allowed to `setData`. The
+   * defect this closes is not cosmetic: a poll issued BEFORE a delete resolves AFTER it, and
+   * a list that still contains the deleted automation puts a row back in the rail that the
+   * user has just watched disappear. Same for a toggle, and same for a create.
+   *
+   * ⚠ THE RETURN VALUE IS NOT GUARDED, deliberately. The caller asked a question and gets
+   * its own answer — coupling the two would mean a create whose `load()` was overtaken by a
+   * poll silently failed to select the automation it had just made.
+   */
+  const gen = useRef(0);
+
+  const load = useCallback(async (abort?: AbortSignal) => {
+    const mine = ++gen.current;
+    try {
+      const next = await listAutomations(abort);
+      if (mine === gen.current) {
+        setData(next);
+        setError("");
+      }
+      return next;
+    } catch (e) {
+      if ((e as Error)?.name === "AbortError") return null;
+      if (mine === gen.current)
+        setError(
+          e instanceof AutomationError
+            ? e.message
+            : "The automation service did not answer."
+        );
+      return null;
+    }
+  }, []);
+
+  useEffect(() => {
+    const ac = new AbortController();
+    void load(ac.signal);
+    return () => ac.abort();
+  }, [load]);
+
+  /**
+   * ⭐⭐ WAVE 24 / C-CREATE (a) — CREATE AND OPEN. This REPLACED the three-step wizard.
+   *
+   * R6 is what makes it possible: `plain` is a real kind with no machine graph nodes, and it is
+   * what `POST /automations` stores when the body names none. So "new automation" stopped being
+   * a question ("which of three kinds?" — two of which can no longer be created at all) and
+   * became what it says: a new automation, open, on its trigger picker. Choosing a SOURCE is now
+   * picking the `ig_profile_match` trigger, which is where that choice belongs.
+   *
+   * ⛔ THE GUARD IS A REF, not the `creatingNow` state, and this file already carries the scar
+   * that explains why (C14 leg 2): a state read inside a click closure is the value from the
+   * last render, so two fast clicks both see `false` and both POST. Duplicate names are legal
+   * server-side, so the user would get two identical rows and no error. The ref is written
+   * synchronously, inside the click, before anything can await.
+   */
+  const creatingRef = useRef(false);
+  const createAndOpen = useCallback(async () => {
+    if (creatingRef.current) return;
+    creatingRef.current = true;
+    setCreatingNow(true);
+    try {
+      const res = await createAutomation({
+        name: nextAutomationName(data?.automations || []),
+      });
+      const id = res?.automation?.id || "";
+      // The create flow is the one caller allowed to name a different id (C14 leg 2) — the
+      // automation did not exist when the click happened, so there is nothing to race with.
+      const next = await load();
+      if (id && next) select(id);
+    } catch (e) {
+      setError(
+        e instanceof AutomationError ? e.message : "The automation was not created."
+      );
+    } finally {
+      creatingRef.current = false;
+      setCreatingNow(false);
+    }
+  }, [data, load, select]);
+
+  // A run is a background thread on the server, so the surface has to ASK whether it
+  // finished. Polling only while something is actually running keeps an idle surface
+  // silent — a fixed interval would be a request every few seconds forever, for a page
+  // whose contents change a handful of times a day.
+  //
+  // ⛔ C14 LEG 3 (the abort half). It used to call `load()` bare — no signal, nothing to
+  // cancel — so a request the interval had already issued kept going after the effect that
+  // owned it was gone. One controller per effect run, aborted with the interval, means a poll
+  // cannot outlive the condition that justified it. The generation guard inside `load` covers
+  // the rest: a response that survives the abort still cannot repaint over a newer one.
+  //
+  // ⭐ WAVE 24 (item 6, C-PERF) — THE INTERVAL BECAME A BACKOFF, and the measurement is why it is
+  // a SMALL change rather than the big one the contract's hypothesis 2 asked for.
+  //
+  // MEASURED (`scratchpad/perf_automations.py`, mailbox D-5): this poll costs ~23 ms and 24 KB
+  // for a ten-automation tenant, and the engine work the hypothesis blamed — a `graph()` rebuild
+  // per automation — is **41 µs each**, i.e. under 4% of the request. The payload was never the
+  // problem, so nothing here gets a cheaper endpoint.
+  //
+  // What the numbers DO indict is the aggregate: a discovery run legitimately blocks up to
+  // `BD_FILTER_WAIT` = 120 s, and two independent 2.5 s polls across this file and the detail
+  // spend ~96 requests and ~2.3 MB over that window — in the same single process the run itself
+  // is a thread in. So the delay grows 2.5 → 5 → 8 s and stops there.
+  //
+  // ⚠ NOT "to learn nothing", and the distinction is the whole justification. That WAS true when
+  // this file rendered no live step: the poll's only observable effect was a dot that had already
+  // been pulsing for two minutes. It stopped being true in this same change — `liveStepOf` now
+  // paints `status.step`, so a poll carries the one fact worth having. The backoff is therefore
+  // NOT "stop asking a pointless question"; it is FEWER ROUND TRIPS FOR THE SAME INFORMATION, on
+  // a step text that changes every few seconds at most, not every 2.5.
+  // The cap is deliberately low: it bounds how long a FINISHED run can still look live, which is
+  // the only thing a backoff can make worse, and 8 s of that is worth ~⅔ fewer requests.
+  //
+  // ⛔ THE KEY IS THE RUNNING SET, NOT A BOOLEAN, and that is what makes the reset correct: the
+  // effect re-runs — and the delay drops back to 2.5 s — the moment a run starts or finishes, so
+  // a user who clicks Run now gets the fast cadence again instead of inheriting the tail of the
+  // previous run's backoff. A bare `anyRunning` boolean cannot see the second run start.
+  // A step text changing does NOT re-key it, so the interval never thrashes.
+  //
+  // C14 LEG 3 (the abort half) is unchanged and still load-bearing: one controller per effect
+  // run, aborted with the timer, so a poll cannot outlive the condition that justified it. The
+  // generation guard inside `load` covers the rest.
+  const runningKey = (data?.automations || [])
+    .filter((a) => a.running)
+    .map((a) => a.id)
+    .sort()
+    .join(",");
+  useEffect(() => {
+    if (!runningKey) return undefined;
+    const ac = new AbortController();
+    let delay = POLL_MIN_MS;
+    let timer = 0;
+    const tick = () => {
+      void load(ac.signal);
+      delay = Math.min(delay * 2, POLL_MAX_MS);
+      timer = window.setTimeout(tick, delay);
+    };
+    timer = window.setTimeout(tick, delay);
+    return () => {
+      window.clearTimeout(timer);
+      ac.abort();
+    };
+  }, [runningKey, load]);
+
+  // ── W23-W5, the surface's half: hear the request, then answer it when we CAN ──────────
+  useEffect(() => {
+    const notify = (detail: AutomationOpenDetail) => setOpenRequest(detail);
+    openSubscribers.add(notify);
+    if (pendingOpen) {
+      const latched = pendingOpen;
+      pendingOpen = null;
+      setOpenRequest(latched);
+    }
+    return () => {
+      openSubscribers.delete(notify);
+    };
+  }, []);
+
+  /* ⛔ THE C-CREATE(b) SUBSCRIBE EFFECT AND ITS RESOLVER STOOD HERE (wave 25, R8). They heard the
+     create event and, once the list had arrived, called `createAndOpen` — the "wait for the list
+     or every automation is named Automation 1" note lives on in `nextAutomationName`, which is
+     still numbered off `existing`. With no signaller there is nothing to hear. */
+
+  /**
+   * ⚠ THE REQUEST OUTLIVES THE FETCH, and it has to. The reader clicks a notification from
+   * another page, so this surface is mounting WITH AN EMPTY LIST — "select it if it is in the
+   * list" would drop every real click and keep only the one case where the reader was already
+   * here. So the request is held until `data` exists, and only then answered.
+   *
+   * An automation the reader can no longer open does NOTHING (the contract's own words): the
+   * request is cleared either way, so a stale id cannot sit here re-firing against every
+   * subsequent list.
+   */
+  useEffect(() => {
+    if (!openRequest || !data) return;
+    const found = (data.automations || []).some((a) => a.id === openRequest.autoId);
+    if (found) {
+      select(openRequest.autoId, openRequest.stageId || "");
+    }
+    setOpenRequest(null);
+  }, [openRequest, data, select]);
+
+  const items = data?.automations || [];
+  const active = items.find((a) => a.id === activeId) || null;
+
+  const toggleEnabled = async (a: Automation) => {
+    setBusy(a.id);
+    try {
+      await patchAutomation(a.id, {
+        schedule: { cron: a.schedule.cron, enabled: !a.schedule.enabled },
+      });
+      await load();
+    } catch (e) {
+      setError(e instanceof AutomationError ? e.message : "That change was not saved.");
+    } finally {
+      setBusy("");
+    }
+  };
+
+  const onRailKey = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+    if (event.key !== "ArrowDown" && event.key !== "ArrowUp") return;
+    const rows = Array.from(
+      listRef.current?.querySelectorAll<HTMLButtonElement>(".auto-row-main") || []
+    );
+    if (!rows.length) return;
+    event.preventDefault();
+    const at = rows.indexOf(document.activeElement as HTMLButtonElement);
+    const next = event.key === "ArrowDown" ? (at + 1) % rows.length
+      : (at - 1 + rows.length) % rows.length;
+    rows[next < 0 ? 0 : next]?.focus();
+  };
+
+  return (
+    <div className="auto-surface">
+      <aside
+        className={"auto-rail" + (railShut ? " is-collapsed" : "")}
+        aria-label="Automations"
+      >
+        {/* The same three-bars fold control the Views rail carries — the two rails are
+            one idea, so they must not fold with two different affordances. */}
+        <div className="auto-rail-top">
+          <button
+            type="button"
+            className="cg-rail-toggle"
+            aria-label={railShut ? "Expand automations" : "Minimize automations"}
+            aria-expanded={!railShut}
+            title={railShut ? "Expand automations" : "Minimize automations"}
+            onClick={() => setRailShut((v) => !v)}
+          >
+            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+              <path
+                d="M2.5 4.4h11M2.5 8h11M2.5 11.6h11"
+                stroke="currentColor"
+                strokeWidth="1.35"
+                strokeLinecap="round"
+              />
+            </svg>
+          </button>
+        </div>
+
+        <div className="auto-create">
+          <button
+            type="button"
+            className="auto-create-btn"
+            disabled={creatingNow}
+            onClick={() => void createAndOpen()}
+          >
+            <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+              <path
+                d="M8 3.4v9.2M3.4 8h9.2"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                strokeLinecap="round"
+              />
+            </svg>
+            New automation
+          </button>
+        </div>
+
+        <div className="auto-list" ref={listRef} onKeyDown={onRailKey}>
+          {items.map((a) => {
+            return (
+              <div
+                key={a.id}
+                className={"auto-row" + (a.id === activeId ? " is-active" : "")}
+              >
+                <button
+                  type="button"
+                  className="auto-row-main"
+                  onClick={() => select(a.id)}
+                >
+                  {/* ⭐ ITEM 18 / R14 — THE LOOP MARK, WHERE THE STATUS DOT WAS. Same mark on
+                      every row, no status colour: the owner's point is that an automation IS a
+                      loop, not that this one is green. The `.auto-loopmark` wrapper is what sizes
+                      it — `.lp-mark` is shell-owned CSS and outside this session's region, so the
+                      box is mine and the mark is theirs. */}
+                  <span className="auto-loopmark">
+                    <Mark size={15} />
+                  </span>
+                  <span className="auto-row-text">
+                    <span className="auto-row-name">{a.name}</span>
+                    <span className="auto-row-desc">{railSubtitle(a)}</span>
+                  </span>
+                </button>
+                <button
+                  type="button"
+                  className={"auto-row-switch" + (a.schedule?.enabled ? " is-on" : "")}
+                  disabled={busy === a.id}
+                  aria-pressed={!!a.schedule?.enabled}
+                  title={
+                    a.schedule?.enabled
+                      ? `Scheduled: ${a.schedule.cron}. Click to pause.`
+                      : "Not scheduled. Click to enable."
+                  }
+                  onClick={() => void toggleEnabled(a)}
+                >
+                  <span className="auto-row-switch-knob" />
+                </button>
+              </div>
+            );
+          })}
+          {/* ONE LINE (R13). It used to describe the kinds — "one reads a public web page…
+              the other fills an automation column…" — which was two sentences, wrong by the
+              time a third kind shipped, and printed inside a `--lp-rail-w` column. What the
+              kinds are belongs to the create form, which is one click away and lists all of
+              them from the server. */}
+          {!items.length && !error ? (
+            <p className="auto-rail-empty">No automations yet.</p>
+          ) : null}
+        </div>
+      </aside>
+
+      <section className="auto-main">
+        {error ? (
+          <div className="auto-banner is-error" role="alert">
+            {error}
+          </div>
+        ) : null}
+        {data && !data.storeAvailable ? (
+          <div className="auto-banner is-warn" role="status">
+            The tenant store is unavailable, so nothing can be saved right now.
+          </div>
+        ) : null}
+
+        {/*
+          ⛔ THE `creating` BRANCH IS GONE (wave 24, C-CREATE a / owner items 3 + 4).
+          `AutomationCreate` used to render here — a three-step wizard whose first step asked
+          which DATABASE to write into (an existing one, a new one, or one the automation itself
+          would create) and whose second asked which of three KINDS.
+          R6 retires that question at the root: two of the three kinds can no longer be created
+          at all, and the third is now reached by picking a trigger. A new automation is created
+          the moment it is asked for (`createAndOpen`) and opens on its own Builder, so there is
+          no intermediate face left to render and no `creating` state to hold.
+          ⭐ WAVE 25 (R8) retires the LAST of that vocabulary: the third answer was the
+          "automated database", and it is gone from every door in the product. This button is now
+          one of exactly two ways to make an automation, and both are on this surface.
+          The import went with it — it is what would break `npx tsc -b` for the WHOLE client the
+          moment session B deletes the file, which is why this deletion is sequenced first.
+        */}
+        {active ? (
+          <AutomationDetail
+            key={active.id}
+            automation={active}
+            /* ⛔ `kinds={data?.kinds || []}` LEFT HERE WITH THE PROP IT FED (wave 25, D-57) —
+               both halves in one change, because either alone is a `tsc` error. */
+            cronPresets={data?.cronPresets || []}
+            paidReady={!!data?.paidReady}
+            discover={data?.discover}
+            // The trigger vocabulary (C3). Forwarded as-is — absent stays absent, so the
+            // trigger face can tell "the server offered nothing" from "the server offered
+            // an empty list" rather than collapsing both into a picker with no options.
+            triggers={data?.triggers}
+            // C4's action menu + the builder's ceilings. Forwarded as-is for the same reason
+            // `triggers` is: absent must stay absent, so the builder can tell "the server
+            // offered nothing" from "the server offered an empty list".
+            catalog={data?.actionsCatalog}
+            vocab={data?.flow}
+            // `?? null` and never `|| {enabled:false}`: an absent tick bit is "the server did
+            // not say", which Step 1 prints as its own sentence. Defaulting it here would
+            // turn a missing field into a claim about production (C6 amendment #1).
+            tick={data?.tick ?? null}
+            /*
+             * ⭐ W24-W1 (item 6) — WHAT THIS RUN IS DOING, on the one surface that survives in
+             * BOTH views. REQUIRED on the far side deliberately: an optional prop that nobody
+             * passes degrades to "the feature does not exist", which is indistinguishable from
+             * "it was never built" — and this whole item exists because a live step text rode
+             * the wire for three waves with nothing rendering it.
+             * `liveStepOf` returns the step ONLY while the automation is running; a stale step
+             * from a finished run is a worse answer than none.
+             */
+            liveStep={liveStepOf(active)}
+            /*
+             * ⛔ C14 LEG 2 — THE STALE-ID WRITE-BACK, and this is the ghost's second cause.
+             *
+             * The detail calls `onSaved(automation.id)` from six places (save, the trigger
+             * picker, a schedule change, a node switch, a card move, a run). Each closure
+             * captures the automation it was mounted for, so a save that resolves AFTER the
+             * user has clicked a different row used to call `setActiveId(the OLD id)` — the
+             * rail jumped back, the detail remounted, and what the user saw was the previous
+             * automation reappearing over the one they had just opened. It looked like a
+             * rendering bug; it was a resolution steering the selection.
+             *
+             * A resolution may no longer steer anything. It reloads the list — that part was
+             * always right — and it re-asserts the selection ONLY when its id is still the one
+             * the user asked for, which makes the write a no-op in the good case and nothing
+             * at all in the bad one.
+             */
+            onSaved={async (id) => {
+              const next = await load();
+              if (id && next && id === wantedId.current) select(id);
+            }}
+            onDeleted={async () => {
+              select("");
+              await load();
+            }}
+          />
+        ) : (
+          /*
+           * THE EMPTY STATE IS ONE LINE AND A BUTTON (owner ruling R13 — "never
+           * over-explain", now a DESIGN.md law).
+           *
+           * It was a heading, a three-sentence paragraph and a 130-word bulleted list
+           * describing all three kinds. Every word of it was true and none of it was READ:
+           * an empty state is passed through, not studied, and the person looking at it has
+           * already decided to make an automation. The kinds are described where the choice
+           * is actually made — the create form lists them FROM THE SERVER, so that copy also
+           * cannot go stale the way this list had (it described two kinds after a third
+           * shipped).
+           *
+           * The button is here rather than only in the rail because this pane is where the
+           * eye is; a create affordance the user has to go find is the same defect as the
+           * paragraph, spent differently.
+           */
+          <div className="autob-empty">
+            {/*
+              ⛔ NO TITLE HERE ANY MORE (C13, owner item 2). This pane carried an `h1`
+              reading "Automations" at 20px/600 — a THIRD title treatment on a page that
+              also had the header's editable 16px/700 input, against every database page's
+              single 16px/650 `shell-db-name`. The shell now wraps this branch in the same
+              `shell-db-frame` + `DbHead` a database gets (wiring W23-W1), so the page's name
+              is drawn once, by the one component that draws every other page's name. A
+              stand-in restyled to match would have been a second copy of the same fact,
+              free to drift the day the header moves.
+            */}
+            <p className="autob-empty-line">
+              A job this workspace runs for you, on demand or on a schedule.
+            </p>
+            <button
+              type="button"
+              className="auto-btn is-primary"
+              disabled={creatingNow}
+              onClick={() => void createAndOpen()}
+            >
+              New automation
+            </button>
+          </div>
+        )}
+      </section>
+    </div>
+  );
+}

web/src/automation/steps.ts

@@ -1,422 +1,422 @@
-// ---------------------------------------------------------------------------
-// automation/steps.ts — the arithmetic behind the numbered Steps (owner ruling R9).
-//
-// Pure functions, deliberately separate from the component: both of the things in
-// here are the kind that go subtly wrong (a step number, a cron round-trip) and
-// stay wrong invisibly, so they are written where they can be read on their own.
-//
-// ⚠ NOTHING HERE INVENTS A STEP. The node list, its order and its `col` all come
-// from the server's `engine.graph()` — the same module that RUNS the steps — and
-// this file only counts them (contract C6). A client-side second idea of what the
-// steps are is the exact drift the split was built to prevent; the rationale is
-// written at AutomationCreate.tsx:1-13.
-// ---------------------------------------------------------------------------
-import type { Action, ActionCatalogRow, Branch, Cond, GraphNode, TriggerOption }
-  from "./automationApi";
-
-/**
- * The branches of an If / then, TOLERATING the pre-wave-24 `{cond, actions}` shape on READ.
- *
- * ⚠ THIS MIRRORS `automation_engine.group_branches` AND THE DUPLICATION IS DELIBERATE, which is
- * worth defending because this file's own header forbids a second idea of the server's data. It
- * is a READ-SIDE TOLERANCE, not a second validator: it never decides what is legal, and every
- * write still goes to `clean_actions`, which returns the one canonical shape. The alternative is
- * strictly worse — a group stored in the old shape would render with no branches and no children,
- * so a live automation's actions would simply VANISH from the screen while running perfectly.
- * A migration the server performs on write and the client tolerates on read is the pair that has
- * no window; trusting `branches` alone has one, for exactly as long as a definition sits unsaved.
- */
-export function groupBranches(a: Action): Branch[] {
-  const cfg = (a?.config || {}) as {
-    branches?: Branch[];
-    cond?: Cond | null;
-    actions?: Action[];
-  };
-  if (Array.isArray(cfg.branches)) return cfg.branches;
-  // The pre-wave-24 shape, read as the one branch the engine migrates it to.
-  if (Array.isArray(cfg.actions))
-    return [{ id: "b1", label: "A", cond: cfg.cond ?? null, actions: cfg.actions }];
-  return [];
-}
-
-/**
- * R8's STEP NUMBERS for a whole flow, keyed by action id.
- *
- * THE RULING, and each clause is a line here:
- *   · the TRIGGER is unnumbered — it is not in this map at all, and the card carries the word
- *     "Trigger" instead. (This REVERSES wave 21's R9, "Step 1 is always the Trigger".)
- *   · the first action is 1, the second 2, …
- *   · an If / then occupies ONE number. Its branches are alternatives, not later steps, so they
- *     consume no numbers of their own.
- *   · a branch's children are numbered RELATIVE TO THEIR BRANCH — the fork at step 2 gives every
- *     one of its branches a `2.1`, a `2.2`, and so on. Two branches therefore both contain a
- *     `2.1`, which is correct rather than colliding: they are alternatives in lettered lanes and
- *     only one of them ever runs (the engine takes the first matching branch and breaks).
- *
- * ⛔ IT DOES NOT LETTER THE BRANCHES, and that is a change from the contract text. `clean_actions`
- * assigns the letter server-side (`_branch_letter`, and "Otherwise" for the null-cond last leg),
- * preserving any label the client sends — so the letter rides on `Branch.label` and a second
- * lettering here would be exactly the client-copy-of-a-server-vocabulary this wave keeps deleting.
- * The client sends an EMPTY label and renders what comes back, which also means letters re-flow
- * correctly when a branch is deleted instead of going stale.
- */
-export function numberActions(actions: Action[]): Map<string, string> {
-  const out = new Map<string, string>();
-  const walk = (list: Action[], prefix: string) => {
-    (list || []).forEach((a, i) => {
-      const n = prefix ? `${prefix}.${i + 1}` : String(i + 1);
-      out.set(a.id, n);
-      if (a.kind === "group")
-        for (const br of groupBranches(a)) walk(br.actions || [], n);
-    });
-  };
-  walk(actions || [], "");
-  return out;
-}
-
-export interface Step {
-  node: GraphNode;
-  /** The number the card carries. */
-  n: number;
-  /** True when this node shares its position with the one before it — an ALTERNATIVE, not a next. */
-  alt: boolean;
-}
-
-/**
- * Number the server's nodes for display.
- *
- * ⭐ THE NUMBER IS `col + 1`, NOT the array index, and that is the honest one. The
- * `field_instagram` graph forks: `capture_paid` and `capture_anon` both sit at
- * `col: 3` because they are the SAME position in the flow reached two ways (the
- * paid rung answers, or the anonymous ladder does). Numbering them 4 and 5 would
- * state a sequence that never happens. They share a number and the second is
- * marked `alt`, so the list says "either of these" rather than "then".
- *
- * "Step 1 is always the Trigger" (R9) therefore falls out of the payload — the
- * trigger is the node at `col: 0` — instead of being asserted by this client. If
- * the engine ever emits something else first, the UI shows what the engine does.
- */
-export function numberSteps(nodes: GraphNode[]): Step[] {
-  return (nodes || []).map((node, i) => {
-    const col = typeof node.col === "number" ? node.col : i;
-    const before = i > 0 ? nodes[i - 1] : null;
-    const beforeCol = before && typeof before.col === "number" ? before.col : -1;
-    return { node, n: col + 1, alt: i > 0 && beforeCol === col };
-  });
-}
-
-/**
- * Move `dragId` into `dropId`'s position within one list (owner item 11).
- *
- * ⛔ IT RETURNS `null` RATHER THAN THE LIST UNCHANGED, and the distinction is what keeps a
- * pointless PATCH off the wire: "these two are the same card", "one of them is not in this list"
- * and "here is your new order" are three different answers, and collapsing the first two into
- * "the order you already had" would have the caller write the flow back to the server on every
- * aborted drag. The caller writes only when this says something happened.
- *
- * THE CARD LANDS EXACTLY WHERE THE TARGET WAS, in both directions — splice out, then splice in at
- * the target's ORIGINAL index. Dragging down, the target shifts up; dragging up, it shifts down.
- * (The tempting version — insert at the target's index *after* the removal — is off by one when
- * dragging downwards and drops the card one slot short of where the pointer is, which reads as
- * the drag not having worked.)
- */
-export function reorderList<T extends { id: string }>(
-  list: T[],
-  dragId: string,
-  dropId: string
-): T[] | null {
-  if (!dragId || !dropId || dragId === dropId) return null;
-  const src = list || [];
-  const from = src.findIndex((x) => x.id === dragId);
-  const to = src.findIndex((x) => x.id === dropId);
-  if (from < 0 || to < 0) return null;
-  const next = [...src];
-  const [moved] = next.splice(from, 1);
-  if (!moved) return null;
-  next.splice(to, 0, moved);
-  return next;
-}
-
-/** One Properties section under "How this fetches": a panel, and every node that opens it. */
-export interface PanelGroup {
-  /** The panel key — what the caller passes to `renderNodeBody`. */
-  panel: string;
-  /** Every machine node whose `panel` is this one, in the server's own order. */
-  nodes: GraphNode[];
-}
-
-/**
- * The machine steps, GROUPED BY PANEL (item 5, contract C-CFG).
- *
- * ⛔ GROUPED, NEVER MAPPED ONE-TO-ONE, and the difference is a defect rather than a nicety.
- * `panel` is MANY-TO-ONE over nodes, which is easy to miss because the old surface hid it: you
- * clicked ONE card and got ONE panel. `field_instagram` gives `capture`, `capture_paid`,
- * `capture_anon` AND `capture_metrics` all `panel: "capture"` (`automation_engine.py:3334-3352`),
- * and `discover_instagram` gives both of its nodes `panel: "find"` (`:3381`/`:3387`). So a body
- * rendered per NODE would print the capture prose four times over, and — the one that actually
- * loses work — mount the 21-toggle discovery filter TWICE against a single `preds` array, two
- * editors writing one piece of state where whichever blurred last silently wins.
- *
- * The detail panel has always joined on `panel` and never on node id (`AutomationDetail`'s own
- * note says so); this keeps that law now that the panels are no longer reached by clicking a card.
- *
- * ORDER IS THE SERVER'S — first appearance wins, so the sections read in flow order rather than
- * in whatever order a Map or a sort would produce.
- */
-export function groupByPanel(nodes: GraphNode[]): PanelGroup[] {
-  const order: string[] = [];
-  const byPanel = new Map<string, GraphNode[]>();
-  for (const n of nodes || []) {
-    // `panel` falls back to the id exactly as `graph()`'s own `node()` does (`panel or nid`),
-    // so a node the engine ships without one still gets its own section instead of joining
-    // every other panel-less node under the empty string.
-    const key = n.panel || n.id;
-    const seen = byPanel.get(key);
-    if (seen) seen.push(n);
-    else {
-      byPanel.set(key, [n]);
-      order.push(key);
-    }
-  }
-  return order.map((panel) => ({ panel, nodes: byPanel.get(panel) || [] }));
-}
-
-/** How the Step-1 card is currently set: what it repeats on, and at what time. */
-export interface TriggerShape {
-  /** `day` = every day · `0`..`6` = that weekday (cron numbering, 0 = Sunday) · `custom` = a cron only. */
-  every: string;
-  /** `HH:MM`, empty when the cron does not express a single fire time. */
-  time: string;
-}
-
-const DAILY = /^(\d{1,2}) (\d{1,2}) \* \* \*$/;
-const WEEKLY = /^(\d{1,2}) (\d{1,2}) \* \* ([0-7])$/;
-
-function two(n: number): string {
-  return String(n).padStart(2, "0");
-}
-
-/**
- * A stored cron → the controls that can express it.
- *
- * ⛔ ANYTHING THIS CANNOT EXPRESS COMES BACK AS `custom`, NEVER AS THE FIRST OPTION.
- * A `<select>` whose value matches no `<option>` renders the first one, and the next
- * Save then writes a schedule nobody chose — the defect this codebase has already
- * paid for twice ([[cg-condition-builder-items]]; the two `(not in this database)`
- * options in AutomationDetail exist for the same reason). A quarter-hourly weekday
- * cron is a legal schedule the engine runs happily; the editor's job is to leave it
- * alone, not to quietly turn it into "every day at 08:00".
- *
- * (Written without the literal cron string on purpose — a step-slash inside a block
- * comment ENDS the comment, and the compiler's 20 cascading errors say nothing about
- * the cron.)
- */
-export function readCron(cron: string): TriggerShape {
-  const raw = String(cron || "").trim();
-  const daily = DAILY.exec(raw);
-  if (daily) {
-    const [, m, h] = daily;
-    if (Number(h) <= 23 && Number(m) <= 59) return { every: "day", time: `${two(Number(h))}:${two(Number(m))}` };
-  }
-  const weekly = WEEKLY.exec(raw);
-  if (weekly) {
-    const [, m, h, d] = weekly;
-    if (Number(h) <= 23 && Number(m) <= 59) {
-      return { every: String(Number(d) % 7), time: `${two(Number(h))}:${two(Number(m))}` };
-    }
-  }
-  return { every: "custom", time: "" };
-}
-
-/** The controls → a cron string. `custom` keeps whatever the user typed, untouched. */
-export function writeCron(every: string, time: string, custom: string): string {
-  if (every === "custom") return String(custom || "").trim();
-  const [h, m] = String(time || "06:00").split(":");
-  const hh = Math.min(23, Math.max(0, Number(h) || 0));
-  const mm = Math.min(59, Math.max(0, Number(m) || 0));
-  return every === "day" ? `${mm} ${hh} * * *` : `${mm} ${hh} * * ${Number(every) || 0}`;
-}
-
-/** The weekday options, in the order a week is read rather than in cron's 0-first order. */
-export const WEEKDAYS: { value: string; label: string }[] = [
-  { value: "1", label: "Every Monday" },
-  { value: "2", label: "Every Tuesday" },
-  { value: "3", label: "Every Wednesday" },
-  { value: "4", label: "Every Thursday" },
-  { value: "5", label: "Every Friday" },
-  { value: "6", label: "Every Saturday" },
-  { value: "0", label: "Every Sunday" },
-];
-
-// ── WAVE 25 · C2: THE GROUPED TRIGGER PICKER'S ARITHMETIC ───────────────────────────────────
-//
-// ⛔ WHY THIS IS HERE AND NOT IN THE COMPONENT. Both functions below are the kind that go subtly
-// wrong and stay wrong INVISIBLY — a group silently sorted first, a stored trigger silently
-// rendering as nothing — and this file exists precisely so that class can be executed under node
-// by `verify_steps.py` instead of eyeballed in a screenshot. It is also D-58's minimum: the
-// builder's largest surface has had no gate but `tsc` and eyes, and the picker's grouped and
-// SELECTED states are the two things a screenshot is worst at proving (the selected row looks
-// identical to an unselected one at a glance, which is the whole scar).
-//
-// ⚠ NOTHING HERE INVENTS A GROUP, A CAPTION OR AN ORDER — the file header's law, applied. Every
-// one of the three rides `TriggerOption` from `routes_automation._triggers_vocab`.
-
-/** One connector's rows inside the Connector group (Gmail / Webhooks / Scraper / TikTok). */
-export interface TriggerSubGroup {
-  key: string;
-  label: string;
-  rows: TriggerOption[];
-}
-
-/** One rendered section of the picker: a caption, the rows under it, and any connector nests. */
-export interface TriggerGroup {
-  /** The server's group id. `""` when the server sent none — one unlabelled section. */
-  key: string;
-  /** The server's caption, PRINTED verbatim. `""` renders no heading, never an invented one. */
-  label: string;
-  order: number;
-  /** Rows that hang directly off the group head. */
-  rows: TriggerOption[];
-  /** Connector nests, in first-appearance order. Empty for Time and Database. */
-  sub: TriggerSubGroup[];
-}
-
-/**
- * The picker's sections: CATEGORY first (Time / Database / Connector), then the trigger, with
- * connector rows nested under their own product name.
- *
- * ⛔ ORDER COMES FROM `groupOrder`, AND AN ABSENT ONE SORTS **LAST**. This is the
- * `ACTION_GROUP_ORDER` rule and it is the safe direction: an unordered group is one this client
- * has no server opinion about, and putting it at the TOP of the menu would present the
- * unclassified thing as the primary answer. Ties keep FIRST-APPEARANCE order, which is what the
- * old `<select>` used as its only ordering and is still the honest fallback for a server that
- * sends no `groupOrder` at all.
- *
- * ⛔ AND NOTHING IS DROPPED. Every option in, every option out — `planned` and `ready:false` rows
- * included, because a picker that hides them answers "can it run when an email arrives?" with
- * silence, and the question then gets asked again (R9's precedent). Faded is a wall the server
- * enforces at `clean_trigger`; a shorter list is a lie.
- */
-export function groupTriggers(options: TriggerOption[]): TriggerGroup[] {
-  const out: TriggerGroup[] = [];
-  const byKey = new Map<string, TriggerGroup>();
-  for (const t of options) {
-    const key = t.group || "";
-    let g = byKey.get(key);
-    if (!g) {
-      g = {
-        key,
-        // ⚠ `groupLabel` OR NOTHING. Falling back to `t.group` would print the id ("connector")
-        // as a heading — a client inventing the server's wording, one `||` at a time.
-        label: t.groupLabel || "",
-        order: typeof t.groupOrder === "number" ? t.groupOrder : Number.MAX_SAFE_INTEGER,
-        rows: [],
-        sub: [],
-      };
-      byKey.set(key, g);
-      out.push(g);
-    }
-    const c = t.connector;
-    if (c && c.key) {
-      let s = g.sub.find((x) => x.key === c.key);
-      if (!s) {
-        s = { key: c.key, label: c.label || c.key, rows: [] };
-        g.sub.push(s);
-      }
-      s.rows.push(t);
-    } else {
-      g.rows.push(t);
-    }
-  }
-  // A STABLE sort by order alone: `Array.prototype.sort` is stable in every runtime this ships to
-  // (ES2019 mandates it), so equal orders keep the first-appearance sequence above.
-  return out.sort((a, b) => a.order - b.order);
-}
-
-/** One rendered section of the ACTION menu: the same shape `TriggerGroup` has, over the
- *  catalog's rows. */
-export interface ActionGroup {
-  key: string;
-  order: number;
-  rows: ActionCatalogRow[];
-  sub: { key: string; label: string; rows: ActionCatalogRow[] }[];
-}
-
-/**
- * ⭐ WAVE 27 · OWNER ITEM 33 / CONTRACT C4 — the action menu, with connector rows NESTED.
- *
- * ⛔ THE SAME ARITHMETIC AS `groupTriggers`, AND THAT IS THE POINT. The trigger picker has
- * nested connectors since wave 24; the action menu is the identical question about a different
- * catalog, and C4 asks for the nest to be "driven by server data, name-for-name". So this reads
- * `row.connector` exactly as `groupTriggers` reads `t.connector`, sorts by `groupOrder` with an
- * absent one LAST, and holds no list of connector names of its own.
- *
- * ⚠ INERT UNTIL THE SERVER STAMPS THE ROWS, by construction rather than by a flag: with no
- * `connector` on any row, every row lands in `rows` and `sub` is empty — which renders the flat
- * menu that ships today. That is what lets this half land before B's, instead of two sessions
- * having to meet in the middle.
- *
- * ⛔ THE GROUP KEY IS ALSO ITS LABEL here, unlike triggers. The action catalog's `group` IS the
- * printed caption ("Web action", "Database", "Connected", "Advanced logic") — the server sends
- * no separate `groupLabel` for actions — so this returns `key` and the caller prints it. Adding
- * a `label` member that merely copied `key` would invent a second name for one string.
- */
-export function groupActions(rows: ActionCatalogRow[]): ActionGroup[] {
-  const out: ActionGroup[] = [];
-  const byKey = new Map<string, ActionGroup>();
-  for (const c of rows) {
-    const key = c.group || "";
-    let g = byKey.get(key);
-    if (!g) {
-      g = {
-        key,
-        order: typeof c.groupOrder === "number" ? c.groupOrder : Number.MAX_SAFE_INTEGER,
-        rows: [],
-        sub: [],
-      };
-      byKey.set(key, g);
-      out.push(g);
-    }
-    const con = c.connector;
-    if (con && con.key) {
-      let s = g.sub.find((x) => x.key === con.key);
-      if (!s) {
-        // The server's LABEL, or its key when it sent none — never a prettified guess.
-        s = { key: con.key, label: con.label || con.key, rows: [] };
-        g.sub.push(s);
-      }
-      s.rows.push(c);
-    } else {
-      g.rows.push(c);
-    }
-  }
-  // Stable by order alone (ES2019 mandates a stable sort), so equal orders keep first
-  // appearance — the same rule `groupTriggers` states one function up.
-  return out.sort((a, b) => a.order - b.order);
-}
-
-/**
- * The option the picker must render as SELECTED — and this function is the scar, in one place.
- *
- * ⛔ A `<select>` WHOSE `value` MATCHES NO `<option>` RENDERS THE FIRST ONE. A custom listbox
- * fails DIFFERENTLY and worse: it renders nothing selected, looks unconfigured, and the next
- * patch writes the blank over a real stored key. This repo has paid for the first form twice
- * (`enters_view`'s view id, and the condition builder's operator) and the control it replaces
- * carried an explicit guard for it.
- *
- * So: a stored key the server did not offer comes back as a SYNTHETIC row saying so, never as
- * `null`. `null` means one thing only — nothing is picked yet — which is also what R14 gates the
- * Configuration section on, so conflating the two would hide a configured automation's settings.
- */
-export function selectedTrigger(
-  options: TriggerOption[],
-  key: string
-): TriggerOption | null {
-  if (!key) return null;
-  const hit = options.find((t) => t.key === key);
-  if (hit) return hit;
-  // ⚠ `ready: false` and NO `detail`: this row is not something the reader can act on, and
-  // inventing a description for a trigger this deployment does not offer would be the client
-  // speaking for a server that said nothing.
-  return { key, label: `${key} (not offered here)`, ready: false };
-}
+// ---------------------------------------------------------------------------
+// automation/steps.ts — the arithmetic behind the numbered Steps (owner ruling R9).
+//
+// Pure functions, deliberately separate from the component: both of the things in
+// here are the kind that go subtly wrong (a step number, a cron round-trip) and
+// stay wrong invisibly, so they are written where they can be read on their own.
+//
+// ⚠ NOTHING HERE INVENTS A STEP. The node list, its order and its `col` all come
+// from the server's `engine.graph()` — the same module that RUNS the steps — and
+// this file only counts them (contract C6). A client-side second idea of what the
+// steps are is the exact drift the split was built to prevent; the rationale is
+// written at AutomationCreate.tsx:1-13.
+// ---------------------------------------------------------------------------
+import type { Action, ActionCatalogRow, Branch, Cond, GraphNode, TriggerOption }
+  from "./automationApi";
+
+/**
+ * The branches of an If / then, TOLERATING the pre-wave-24 `{cond, actions}` shape on READ.
+ *
+ * ⚠ THIS MIRRORS `automation_engine.group_branches` AND THE DUPLICATION IS DELIBERATE, which is
+ * worth defending because this file's own header forbids a second idea of the server's data. It
+ * is a READ-SIDE TOLERANCE, not a second validator: it never decides what is legal, and every
+ * write still goes to `clean_actions`, which returns the one canonical shape. The alternative is
+ * strictly worse — a group stored in the old shape would render with no branches and no children,
+ * so a live automation's actions would simply VANISH from the screen while running perfectly.
+ * A migration the server performs on write and the client tolerates on read is the pair that has
+ * no window; trusting `branches` alone has one, for exactly as long as a definition sits unsaved.
+ */
+export function groupBranches(a: Action): Branch[] {
+  const cfg = (a?.config || {}) as {
+    branches?: Branch[];
+    cond?: Cond | null;
+    actions?: Action[];
+  };
+  if (Array.isArray(cfg.branches)) return cfg.branches;
+  // The pre-wave-24 shape, read as the one branch the engine migrates it to.
+  if (Array.isArray(cfg.actions))
+    return [{ id: "b1", label: "A", cond: cfg.cond ?? null, actions: cfg.actions }];
+  return [];
+}
+
+/**
+ * R8's STEP NUMBERS for a whole flow, keyed by action id.
+ *
+ * THE RULING, and each clause is a line here:
+ *   · the TRIGGER is unnumbered — it is not in this map at all, and the card carries the word
+ *     "Trigger" instead. (This REVERSES wave 21's R9, "Step 1 is always the Trigger".)
+ *   · the first action is 1, the second 2, …
+ *   · an If / then occupies ONE number. Its branches are alternatives, not later steps, so they
+ *     consume no numbers of their own.
+ *   · a branch's children are numbered RELATIVE TO THEIR BRANCH — the fork at step 2 gives every
+ *     one of its branches a `2.1`, a `2.2`, and so on. Two branches therefore both contain a
+ *     `2.1`, which is correct rather than colliding: they are alternatives in lettered lanes and
+ *     only one of them ever runs (the engine takes the first matching branch and breaks).
+ *
+ * ⛔ IT DOES NOT LETTER THE BRANCHES, and that is a change from the contract text. `clean_actions`
+ * assigns the letter server-side (`_branch_letter`, and "Otherwise" for the null-cond last leg),
+ * preserving any label the client sends — so the letter rides on `Branch.label` and a second
+ * lettering here would be exactly the client-copy-of-a-server-vocabulary this wave keeps deleting.
+ * The client sends an EMPTY label and renders what comes back, which also means letters re-flow
+ * correctly when a branch is deleted instead of going stale.
+ */
+export function numberActions(actions: Action[]): Map<string, string> {
+  const out = new Map<string, string>();
+  const walk = (list: Action[], prefix: string) => {
+    (list || []).forEach((a, i) => {
+      const n = prefix ? `${prefix}.${i + 1}` : String(i + 1);
+      out.set(a.id, n);
+      if (a.kind === "group")
+        for (const br of groupBranches(a)) walk(br.actions || [], n);
+    });
+  };
+  walk(actions || [], "");
+  return out;
+}
+
+export interface Step {
+  node: GraphNode;
+  /** The number the card carries. */
+  n: number;
+  /** True when this node shares its position with the one before it — an ALTERNATIVE, not a next. */
+  alt: boolean;
+}
+
+/**
+ * Number the server's nodes for display.
+ *
+ * ⭐ THE NUMBER IS `col + 1`, NOT the array index, and that is the honest one. The
+ * `field_instagram` graph forks: `capture_paid` and `capture_anon` both sit at
+ * `col: 3` because they are the SAME position in the flow reached two ways (the
+ * paid rung answers, or the anonymous ladder does). Numbering them 4 and 5 would
+ * state a sequence that never happens. They share a number and the second is
+ * marked `alt`, so the list says "either of these" rather than "then".
+ *
+ * "Step 1 is always the Trigger" (R9) therefore falls out of the payload — the
+ * trigger is the node at `col: 0` — instead of being asserted by this client. If
+ * the engine ever emits something else first, the UI shows what the engine does.
+ */
+export function numberSteps(nodes: GraphNode[]): Step[] {
+  return (nodes || []).map((node, i) => {
+    const col = typeof node.col === "number" ? node.col : i;
+    const before = i > 0 ? nodes[i - 1] : null;
+    const beforeCol = before && typeof before.col === "number" ? before.col : -1;
+    return { node, n: col + 1, alt: i > 0 && beforeCol === col };
+  });
+}
+
+/**
+ * Move `dragId` into `dropId`'s position within one list (owner item 11).
+ *
+ * ⛔ IT RETURNS `null` RATHER THAN THE LIST UNCHANGED, and the distinction is what keeps a
+ * pointless PATCH off the wire: "these two are the same card", "one of them is not in this list"
+ * and "here is your new order" are three different answers, and collapsing the first two into
+ * "the order you already had" would have the caller write the flow back to the server on every
+ * aborted drag. The caller writes only when this says something happened.
+ *
+ * THE CARD LANDS EXACTLY WHERE THE TARGET WAS, in both directions — splice out, then splice in at
+ * the target's ORIGINAL index. Dragging down, the target shifts up; dragging up, it shifts down.
+ * (The tempting version — insert at the target's index *after* the removal — is off by one when
+ * dragging downwards and drops the card one slot short of where the pointer is, which reads as
+ * the drag not having worked.)
+ */
+export function reorderList<T extends { id: string }>(
+  list: T[],
+  dragId: string,
+  dropId: string
+): T[] | null {
+  if (!dragId || !dropId || dragId === dropId) return null;
+  const src = list || [];
+  const from = src.findIndex((x) => x.id === dragId);
+  const to = src.findIndex((x) => x.id === dropId);
+  if (from < 0 || to < 0) return null;
+  const next = [...src];
+  const [moved] = next.splice(from, 1);
+  if (!moved) return null;
+  next.splice(to, 0, moved);
+  return next;
+}
+
+/** One Properties section under "How this fetches": a panel, and every node that opens it. */
+export interface PanelGroup {
+  /** The panel key — what the caller passes to `renderNodeBody`. */
+  panel: string;
+  /** Every machine node whose `panel` is this one, in the server's own order. */
+  nodes: GraphNode[];
+}
+
+/**
+ * The machine steps, GROUPED BY PANEL (item 5, contract C-CFG).
+ *
+ * ⛔ GROUPED, NEVER MAPPED ONE-TO-ONE, and the difference is a defect rather than a nicety.
+ * `panel` is MANY-TO-ONE over nodes, which is easy to miss because the old surface hid it: you
+ * clicked ONE card and got ONE panel. `field_instagram` gives `capture`, `capture_paid`,
+ * `capture_anon` AND `capture_metrics` all `panel: "capture"` (`automation_engine.py:3334-3352`),
+ * and `discover_instagram` gives both of its nodes `panel: "find"` (`:3381`/`:3387`). So a body
+ * rendered per NODE would print the capture prose four times over, and — the one that actually
+ * loses work — mount the 21-toggle discovery filter TWICE against a single `preds` array, two
+ * editors writing one piece of state where whichever blurred last silently wins.
+ *
+ * The detail panel has always joined on `panel` and never on node id (`AutomationDetail`'s own
+ * note says so); this keeps that law now that the panels are no longer reached by clicking a card.
+ *
+ * ORDER IS THE SERVER'S — first appearance wins, so the sections read in flow order rather than
+ * in whatever order a Map or a sort would produce.
+ */
+export function groupByPanel(nodes: GraphNode[]): PanelGroup[] {
+  const order: string[] = [];
+  const byPanel = new Map<string, GraphNode[]>();
+  for (const n of nodes || []) {
+    // `panel` falls back to the id exactly as `graph()`'s own `node()` does (`panel or nid`),
+    // so a node the engine ships without one still gets its own section instead of joining
+    // every other panel-less node under the empty string.
+    const key = n.panel || n.id;
+    const seen = byPanel.get(key);
+    if (seen) seen.push(n);
+    else {
+      byPanel.set(key, [n]);
+      order.push(key);
+    }
+  }
+  return order.map((panel) => ({ panel, nodes: byPanel.get(panel) || [] }));
+}
+
+/** How the Step-1 card is currently set: what it repeats on, and at what time. */
+export interface TriggerShape {
+  /** `day` = every day · `0`..`6` = that weekday (cron numbering, 0 = Sunday) · `custom` = a cron only. */
+  every: string;
+  /** `HH:MM`, empty when the cron does not express a single fire time. */
+  time: string;
+}
+
+const DAILY = /^(\d{1,2}) (\d{1,2}) \* \* \*$/;
+const WEEKLY = /^(\d{1,2}) (\d{1,2}) \* \* ([0-7])$/;
+
+function two(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+/**
+ * A stored cron → the controls that can express it.
+ *
+ * ⛔ ANYTHING THIS CANNOT EXPRESS COMES BACK AS `custom`, NEVER AS THE FIRST OPTION.
+ * A `<select>` whose value matches no `<option>` renders the first one, and the next
+ * Save then writes a schedule nobody chose — the defect this codebase has already
+ * paid for twice ([[cg-condition-builder-items]]; the two `(not in this database)`
+ * options in AutomationDetail exist for the same reason). A quarter-hourly weekday
+ * cron is a legal schedule the engine runs happily; the editor's job is to leave it
+ * alone, not to quietly turn it into "every day at 08:00".
+ *
+ * (Written without the literal cron string on purpose — a step-slash inside a block
+ * comment ENDS the comment, and the compiler's 20 cascading errors say nothing about
+ * the cron.)
+ */
+export function readCron(cron: string): TriggerShape {
+  const raw = String(cron || "").trim();
+  const daily = DAILY.exec(raw);
+  if (daily) {
+    const [, m, h] = daily;
+    if (Number(h) <= 23 && Number(m) <= 59) return { every: "day", time: `${two(Number(h))}:${two(Number(m))}` };
+  }
+  const weekly = WEEKLY.exec(raw);
+  if (weekly) {
+    const [, m, h, d] = weekly;
+    if (Number(h) <= 23 && Number(m) <= 59) {
+      return { every: String(Number(d) % 7), time: `${two(Number(h))}:${two(Number(m))}` };
+    }
+  }
+  return { every: "custom", time: "" };
+}
+
+/** The controls → a cron string. `custom` keeps whatever the user typed, untouched. */
+export function writeCron(every: string, time: string, custom: string): string {
+  if (every === "custom") return String(custom || "").trim();
+  const [h, m] = String(time || "06:00").split(":");
+  const hh = Math.min(23, Math.max(0, Number(h) || 0));
+  const mm = Math.min(59, Math.max(0, Number(m) || 0));
+  return every === "day" ? `${mm} ${hh} * * *` : `${mm} ${hh} * * ${Number(every) || 0}`;
+}
+
+/** The weekday options, in the order a week is read rather than in cron's 0-first order. */
+export const WEEKDAYS: { value: string; label: string }[] = [
+  { value: "1", label: "Every Monday" },
+  { value: "2", label: "Every Tuesday" },
+  { value: "3", label: "Every Wednesday" },
+  { value: "4", label: "Every Thursday" },
+  { value: "5", label: "Every Friday" },
+  { value: "6", label: "Every Saturday" },
+  { value: "0", label: "Every Sunday" },
+];
+
+// ── WAVE 25 · C2: THE GROUPED TRIGGER PICKER'S ARITHMETIC ───────────────────────────────────
+//
+// ⛔ WHY THIS IS HERE AND NOT IN THE COMPONENT. Both functions below are the kind that go subtly
+// wrong and stay wrong INVISIBLY — a group silently sorted first, a stored trigger silently
+// rendering as nothing — and this file exists precisely so that class can be executed under node
+// by `verify_steps.py` instead of eyeballed in a screenshot. It is also D-58's minimum: the
+// builder's largest surface has had no gate but `tsc` and eyes, and the picker's grouped and
+// SELECTED states are the two things a screenshot is worst at proving (the selected row looks
+// identical to an unselected one at a glance, which is the whole scar).
+//
+// ⚠ NOTHING HERE INVENTS A GROUP, A CAPTION OR AN ORDER — the file header's law, applied. Every
+// one of the three rides `TriggerOption` from `routes_automation._triggers_vocab`.
+
+/** One connector's rows inside the Connector group (Gmail / Webhooks / Scraper / TikTok). */
+export interface TriggerSubGroup {
+  key: string;
+  label: string;
+  rows: TriggerOption[];
+}
+
+/** One rendered section of the picker: a caption, the rows under it, and any connector nests. */
+export interface TriggerGroup {
+  /** The server's group id. `""` when the server sent none — one unlabelled section. */
+  key: string;
+  /** The server's caption, PRINTED verbatim. `""` renders no heading, never an invented one. */
+  label: string;
+  order: number;
+  /** Rows that hang directly off the group head. */
+  rows: TriggerOption[];
+  /** Connector nests, in first-appearance order. Empty for Time and Database. */
+  sub: TriggerSubGroup[];
+}
+
+/**
+ * The picker's sections: CATEGORY first (Time / Database / Connector), then the trigger, with
+ * connector rows nested under their own product name.
+ *
+ * ⛔ ORDER COMES FROM `groupOrder`, AND AN ABSENT ONE SORTS **LAST**. This is the
+ * `ACTION_GROUP_ORDER` rule and it is the safe direction: an unordered group is one this client
+ * has no server opinion about, and putting it at the TOP of the menu would present the
+ * unclassified thing as the primary answer. Ties keep FIRST-APPEARANCE order, which is what the
+ * old `<select>` used as its only ordering and is still the honest fallback for a server that
+ * sends no `groupOrder` at all.
+ *
+ * ⛔ AND NOTHING IS DROPPED. Every option in, every option out — `planned` and `ready:false` rows
+ * included, because a picker that hides them answers "can it run when an email arrives?" with
+ * silence, and the question then gets asked again (R9's precedent). Faded is a wall the server
+ * enforces at `clean_trigger`; a shorter list is a lie.
+ */
+export function groupTriggers(options: TriggerOption[]): TriggerGroup[] {
+  const out: TriggerGroup[] = [];
+  const byKey = new Map<string, TriggerGroup>();
+  for (const t of options) {
+    const key = t.group || "";
+    let g = byKey.get(key);
+    if (!g) {
+      g = {
+        key,
+        // ⚠ `groupLabel` OR NOTHING. Falling back to `t.group` would print the id ("connector")
+        // as a heading — a client inventing the server's wording, one `||` at a time.
+        label: t.groupLabel || "",
+        order: typeof t.groupOrder === "number" ? t.groupOrder : Number.MAX_SAFE_INTEGER,
+        rows: [],
+        sub: [],
+      };
+      byKey.set(key, g);
+      out.push(g);
+    }
+    const c = t.connector;
+    if (c && c.key) {
+      let s = g.sub.find((x) => x.key === c.key);
+      if (!s) {
+        s = { key: c.key, label: c.label || c.key, rows: [] };
+        g.sub.push(s);
+      }
+      s.rows.push(t);
+    } else {
+      g.rows.push(t);
+    }
+  }
+  // A STABLE sort by order alone: `Array.prototype.sort` is stable in every runtime this ships to
+  // (ES2019 mandates it), so equal orders keep the first-appearance sequence above.
+  return out.sort((a, b) => a.order - b.order);
+}
+
+/** One rendered section of the ACTION menu: the same shape `TriggerGroup` has, over the
+ *  catalog's rows. */
+export interface ActionGroup {
+  key: string;
+  order: number;
+  rows: ActionCatalogRow[];
+  sub: { key: string; label: string; rows: ActionCatalogRow[] }[];
+}
+
+/**
+ * ⭐ WAVE 27 · OWNER ITEM 33 / CONTRACT C4 — the action menu, with connector rows NESTED.
+ *
+ * ⛔ THE SAME ARITHMETIC AS `groupTriggers`, AND THAT IS THE POINT. The trigger picker has
+ * nested connectors since wave 24; the action menu is the identical question about a different
+ * catalog, and C4 asks for the nest to be "driven by server data, name-for-name". So this reads
+ * `row.connector` exactly as `groupTriggers` reads `t.connector`, sorts by `groupOrder` with an
+ * absent one LAST, and holds no list of connector names of its own.
+ *
+ * ⚠ INERT UNTIL THE SERVER STAMPS THE ROWS, by construction rather than by a flag: with no
+ * `connector` on any row, every row lands in `rows` and `sub` is empty — which renders the flat
+ * menu that ships today. That is what lets this half land before B's, instead of two sessions
+ * having to meet in the middle.
+ *
+ * ⛔ THE GROUP KEY IS ALSO ITS LABEL here, unlike triggers. The action catalog's `group` IS the
+ * printed caption ("Web action", "Database", "Connected", "Advanced logic") — the server sends
+ * no separate `groupLabel` for actions — so this returns `key` and the caller prints it. Adding
+ * a `label` member that merely copied `key` would invent a second name for one string.
+ */
+export function groupActions(rows: ActionCatalogRow[]): ActionGroup[] {
+  const out: ActionGroup[] = [];
+  const byKey = new Map<string, ActionGroup>();
+  for (const c of rows) {
+    const key = c.group || "";
+    let g = byKey.get(key);
+    if (!g) {
+      g = {
+        key,
+        order: typeof c.groupOrder === "number" ? c.groupOrder : Number.MAX_SAFE_INTEGER,
+        rows: [],
+        sub: [],
+      };
+      byKey.set(key, g);
+      out.push(g);
+    }
+    const con = c.connector;
+    if (con && con.key) {
+      let s = g.sub.find((x) => x.key === con.key);
+      if (!s) {
+        // The server's LABEL, or its key when it sent none — never a prettified guess.
+        s = { key: con.key, label: con.label || con.key, rows: [] };
+        g.sub.push(s);
+      }
+      s.rows.push(c);
+    } else {
+      g.rows.push(c);
+    }
+  }
+  // Stable by order alone (ES2019 mandates a stable sort), so equal orders keep first
+  // appearance — the same rule `groupTriggers` states one function up.
+  return out.sort((a, b) => a.order - b.order);
+}
+
+/**
+ * The option the picker must render as SELECTED — and this function is the scar, in one place.
+ *
+ * ⛔ A `<select>` WHOSE `value` MATCHES NO `<option>` RENDERS THE FIRST ONE. A custom listbox
+ * fails DIFFERENTLY and worse: it renders nothing selected, looks unconfigured, and the next
+ * patch writes the blank over a real stored key. This repo has paid for the first form twice
+ * (`enters_view`'s view id, and the condition builder's operator) and the control it replaces
+ * carried an explicit guard for it.
+ *
+ * So: a stored key the server did not offer comes back as a SYNTHETIC row saying so, never as
+ * `null`. `null` means one thing only — nothing is picked yet — which is also what R14 gates the
+ * Configuration section on, so conflating the two would hide a configured automation's settings.
+ */
+export function selectedTrigger(
+  options: TriggerOption[],
+  key: string
+): TriggerOption | null {
+  if (!key) return null;
+  const hit = options.find((t) => t.key === key);
+  if (hit) return hit;
+  // ⚠ `ready: false` and NO `detail`: this row is not something the reader can act on, and
+  // inventing a description for a trigger this deployment does not offer would be the client
+  // speaking for a server that said nothing.
+  return { key, label: `${key} (not offered here)`, ready: false };
+}

web/src/customer-grid/MapView.tsx

@@ -1,946 +1,946 @@
-// ---------------------------------------------------------------------------
-// customer-grid / MapView.tsx
-// "Map" is a VIEW beside Grid/List/Calendar/Kanban, not a module: it projects
-// the SAME pipeline output the grid paints, so the toolbar count, filters and
-// sorts mean exactly what they mean on the grid; only the projection changes.
-//
-// Wave 8 grows it up (I2/I3/I5/I6, contracts C2/C3/C7):
-//   I2  wheel/pinch zoom, drag to pan, and a box-select that feeds the grid's
-//       OWN selection — so the existing "N selected · Add to cohort" bar serves
-//       the map with no second cohort picker to keep in sync.
-//   I3  colour pins by any single-select field (`display.colorField`) + legend.
-//   I5  size pins by any numeric/measure field (`display.sizeField`) + legend.
-//   I6  a less templatic picture: water wash, land fill, thin C1 strokes,
-//       graticule, hover halos.
-//
-// C7 CALL — NO map library. C7 allows maplibre-gl "with a self-hosted
-// vector/raster-free style (NO external tile fetches ... if real tiles need a
-// network fetch, that is a blocker: fall back)". A basemap IS a network fetch,
-// and self-hosting tiles means shipping them inside a single-file embed. A
-// tileless maplibre would render exactly the geometry below for +230 KB gz on a
-// 251 KB budget. Declined on the contract's own terms; see the mailbox.
-//
-// Honesty rules (rule 8b), carried and extended:
-//   - rows WITHOUT coordinates are never silently hidden — a chip says
-//     "N matching records have no location";
-//   - a pin per row at its geocoded position, no clustering and no jitter (two
-//     customers at one address overlap rather than being drawn where they are
-//     not);
-//   - the colour legend STATES it when a field has more choices than the
-//     palette has entries, rather than recycling a colour onto a second meaning;
-//   - a row with no value under the size field gets the smallest dot and the
-//     legend says so — it is never dropped from the map.
-// ---------------------------------------------------------------------------
-
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import type { KeyboardEvent as ReactKeyboardEvent, PointerEvent as ReactPointerEvent } from "react";
-import type { Field, Row } from "./types";
-import { formatDisplay } from "./cells";
-import { LAND_PATH, LAKE_PATHS } from "./mapGeometry";
-import {
-  BASEMAP_DETAIL_K,
-  bubbleRadius,
-  cardBox,
-  dashPattern,
-  fitView,
-  fromScreen,
-  googleDirectionsUrl,
-  googleMapsUrl,
-  googleRouteUrl,
-  googleZoomForK,
-  graticuleOpacity,
-  hairline,
-  haversineKm,
-  isPlottable,
-  normRect,
-  planRoute,
-  project,
-  toScreen,
-  unproject,
-  WORLD,
-  zoomAt,
-  zoomLimits,
-} from "./mapProjection";
-import type { GeoStop, Pt, View } from "./mapProjection";
-
-const VIEW_W = 1000;
-const VIEW_H = 620;
-const R_MIN = 3.2;
-const R_MAX = 15;
-const R_PLAIN = 4.5;
-const R_NULL = 2.6;
-
-/**
- * The pin palette: C1's cycle (blue -> green -> yellow -> red) then its
- * 20%-darkened variants, exactly as the contract specifies for series colour.
- * `fill` is the pastel; `line` is a darker companion, because a C1 pastel
- * measures 1.4-1.9:1 on white and a fill alone would be a smudge (the same
- * measurement that drove the I7c amendment).
- */
-const SERIES: { fill: string; line: string }[] = [
-  { fill: "#9DBFF2", line: "#5F7FB0" },
-  { fill: "#A5D8B4", line: "#5E9C74" },
-  { fill: "#F5D989", line: "#B39A46" },
-  { fill: "#F0A8A0", line: "#B76D65" },
-  { fill: "#7E99C2", line: "#4A6790" },
-  { fill: "#84AD91", line: "#4C7A5C" },
-  { fill: "#C4AE6E", line: "#8C7838" },
-  { fill: "#C0867F", line: "#8A5049" },
-];
-/** Anything past the palette, plus the blank bucket. Neutral ON PURPOSE: a
- *  ninth colour that repeats the first would make two meanings look identical. */
-const OVERFLOW = { fill: "#D7DBE3", line: "#8A909C" };
-const DEFAULT_PIN = { fill: "#9DBFF2", line: "#4F6079" };
-
-interface MapPoint {
-  pid: number;
-  title: string;
-  p: Pt;
-  /** The ORIGINAL coordinate, kept beside the projected one so the Google
-   *  hand-off links to the exact geocode we plotted rather than to a round-trip
-   *  through the projection. */
-  lat: number;
-  lon: number;
-  colorKey: string | null;
-  size: number | null;
-  /** The RAW cell values behind the two encodings. The hover card formats these
-   *  with `formatDisplay`, the grid's own formatter — `colorKey` is trimmed for
-   *  bucketing and `size` is coerced for the bubble scale, so neither is what a
-   *  human should be shown. */
-  colorVal: Row[keyof Row];
-  sizeVal: Row[keyof Row];
-}
-
-function coord(v: Row[keyof Row]): number | null {
-  if (v == null || v === "") return null;
-  const n = typeof v === "number" ? v : Number(v);
-  return Number.isFinite(n) ? n : null;
-}
-
-function numOrNull(v: Row[keyof Row]): number | null {
-  if (v == null || v === "") return null;
-  const n = typeof v === "number" ? v : Number(v);
-  return Number.isFinite(n) ? n : null;
-}
-
-export function MapView({
-  rows,
-  field,
-  colorField,
-  sizeField,
-  selectedPids,
-  onSelectPids,
-  onOpen,
-}: {
-  /** DISTINCT data rows from the full pipeline, overlay edits layered — the
-   *  calendar/kanban contract, verbatim. */
-  rows: Row[];
-  /** The locked identity column — pin tooltips and aria labels. */
-  field: Field;
-  /** I3 — the view's `display.colorField`, already resolved to a real field. */
-  colorField?: Field;
-  /** I5 — the view's `display.sizeField`, already resolved to a real field. */
-  sizeField?: Field;
-  /** The grid's selection, shared: pins render selected, and the existing
-   *  selection bar is what offers "Add to cohort" (C3). */
-  selectedPids: ReadonlySet<number>;
-  onSelectPids: (pids: number[], mode: "replace" | "add") => void;
-  onOpen: (pid: number) => void;
-}) {
-  const [hoverPid, setHoverPid] = useState<number | null>(null);
-  // I18-R — the route planner. Off until asked for: a route drawn over a
-  // selection nobody asked to route is just clutter.
-  const [routeOn, setRouteOn] = useState(false);
-  const [roundTrip, setRoundTrip] = useState(false);
-  const [routeStartPid, setRouteStartPid] = useState<number | null>(null);
-  const [view, setView] = useState<View | null>(null);
-  const [drag, setDrag] = useState<{ x0: number; y0: number; x1: number; y1: number } | null>(null);
-  /**
-   * ⚠ The svg element lives in STATE, not in a ref, and that is load-bearing.
-   *
-   * `view` starts null, so the FIRST render returns the empty state and there is
-   * no <svg> in the tree at all. A `useRef` would still be null when the wheel
-   * effect below first ran, and by the time the svg actually mounted the
-   * effect's deps (`localPoint`, `kMin`, `kMax`) were all unchanged — so React
-   * would never re-run it and the wheel listener would never be attached. Wheel
-   * zoom would be silently dead on the ordinary path.
-   *
-   * Holding the element in state makes attachment a consequence of MOUNTING
-   * rather than of a dependency happening to change, so the hazard cannot come
-   * back. No unit test can see this: the gate is pure TS under node, and a
-   * screenshot of a static page has no React in it.
-   */
-  const [svgEl, setSvgEl] = useState<SVGSVGElement | null>(null);
-  const panRef = useRef<{ x: number; y: number; tx: number; ty: number } | null>(null);
-  /** A finished drag must not also read as a click on the pin underneath — the
-   *  kanban card's lesson (viewModes.tsx), same fix. */
-  const movedRef = useRef(false);
-  /** Once the user has zoomed or panned, a data change must NOT yank the view
-   *  back. Before that, refitting on new data is the helpful behaviour. */
-  const touchedRef = useRef(false);
-
-  const points = useMemo(() => {
-    const out: MapPoint[] = [];
-    for (const r of rows) {
-      const lat = coord(r.lat);
-      const lon = coord(r.lon);
-      if (lat == null || lon == null) continue;
-      if (Math.abs(lat) > 90 || Math.abs(lon) > 180) continue;
-      out.push({
-        pid: r.pid,
-        title: String(r[field.key] ?? ""),
-        p: project(lon, lat),
-        lat,
-        lon,
-        colorKey: colorField ? String(r[colorField.key] ?? "").trim() : null,
-        size: sizeField ? numOrNull(r[sizeField.key]) : null,
-        colorVal: colorField ? r[colorField.key] : null,
-        sizeVal: sizeField ? r[sizeField.key] : null,
-      });
-    }
-    return out;
-  }, [rows, field.key, colorField, sizeField]);
-  const noCoords = rows.length - points.length;
-
-  // The fit is the INITIAL view, not the projection (see mapProjection.ts).
-  const fit = useMemo(
-    () => fitView(points.map((p) => p.p), VIEW_W, VIEW_H),
-    [points]
-  );
-  useEffect(() => {
-    if (!fit) return;
-    if (!touchedRef.current || view == null) setView(fit);
-    // `view` is deliberately absent from the deps: this effect exists to seed
-    // and re-fit, and re-running it on every pan would fight the user for the
-    // camera.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [fit]);
-
-  const { kMin, kMax } = useMemo(
-    () => (fit ? zoomLimits(fit.k, VIEW_H, BASEMAP_DETAIL_K) : { kMin: 1, kMax: 1 }),
-    [fit]
-  );
-
-  /** Colour buckets, in first-seen order so the legend is stable. */
-  const colorBuckets = useMemo(() => {
-    if (!colorField) return null;
-    const order: string[] = [];
-    const counts = new Map<string, number>();
-    for (const p of points) {
-      const k = p.colorKey ?? "";
-      if (!counts.has(k)) {
-        counts.set(k, 0);
-        order.push(k);
-      }
-      counts.set(k, (counts.get(k) ?? 0) + 1);
-    }
-    const named = order.filter((k) => k !== "");
-    const swatch = new Map<string, { fill: string; line: string }>();
-    named.forEach((k, i) => swatch.set(k, i < SERIES.length ? SERIES[i] : OVERFLOW));
-    return {
-      order,
-      counts,
-      swatch,
-      overflow: Math.max(0, named.length - SERIES.length),
-    };
-  }, [colorField, points]);
-
-  /** The size field's observed range across MAPPED points (not the whole table:
-   *  the legend must describe the picture actually on screen). */
-  const sizeRange = useMemo(() => {
-    if (!sizeField) return null;
-    let min = Infinity;
-    let max = -Infinity;
-    let missing = 0;
-    for (const p of points) {
-      if (p.size == null) {
-        missing += 1;
-        continue;
-      }
-      min = Math.min(min, p.size);
-      max = Math.max(max, p.size);
-    }
-    if (!Number.isFinite(min)) return { min: 0, max: 0, missing, none: true };
-    return { min, max, missing, none: false };
-  }, [sizeField, points]);
-
-  /** A coarse pointer means a phone or tablet, where Google's free URL takes 3
-   *  waypoints rather than 9. A media query, not user-agent sniffing. */
-  const coarsePointer = useMemo(
-    () =>
-      typeof window !== "undefined" &&
-      typeof window.matchMedia === "function" &&
-      window.matchMedia("(pointer: coarse)").matches,
-    []
-  );
-
-  /** Selected pins that can actually be routed, in a STABLE order (by pid) —
-   *  a Set's iteration order must not be what decides a route. */
-  const routable = useMemo(
-    () =>
-      selectedPids.size < 2
-        ? []
-        : points
-            .filter((p) => selectedPids.has(p.pid) && isPlottable(p.lat, p.lon))
-            .sort((a, b) => a.pid - b.pid),
-    [points, selectedPids]
-  );
-  /** Selected records with no usable coordinate. Counted and shown, never
-   *  folded silently into the stop total ([[no-unverifiable-aggregates]]). */
-  const unroutable = selectedPids.size - routable.length;
-
-  const plan = useMemo(() => {
-    if (!routeOn || routable.length < 2) return null;
-    const stops: GeoStop[] = routable.map((p) => ({ lat: p.lat, lon: p.lon }));
-    // Default origin: the WESTERNMOST stop. Deterministic, stable while the user
-    // pans, and sayable out loud — unlike "whatever ended up at index 0". The
-    // picker below overrides it.
-    let start = 0;
-    for (let i = 1; i < routable.length; i++)
-      if (routable[i].lon < routable[start].lon) start = i;
-    if (routeStartPid != null) {
-      const i = routable.findIndex((p) => p.pid === routeStartPid);
-      if (i >= 0) start = i;
-    }
-    const { order, km } = planRoute(stops, haversineKm, { start, roundTrip });
-    return {
-      ordered: order.map((i) => routable[i]),
-      km,
-      link: googleRouteUrl(order.map((i) => stops[i]), { roundTrip, coarsePointer }),
-    };
-  }, [routeOn, routable, roundTrip, routeStartPid, coarsePointer]);
-
-  const paint = useCallback(
-    (p: MapPoint) => {
-      if (!colorBuckets) return DEFAULT_PIN;
-      const k = p.colorKey ?? "";
-      if (k === "") return OVERFLOW;
-      return colorBuckets.swatch.get(k) ?? OVERFLOW;
-    },
-    [colorBuckets]
-  );
-
-  const radius = useCallback(
-    (p: MapPoint) => {
-      if (!sizeField || !sizeRange || sizeRange.none) return R_PLAIN;
-      return bubbleRadius(p.size, sizeRange.min, sizeRange.max, R_MIN, R_MAX, R_NULL);
-    },
-    [sizeField, sizeRange]
-  );
-
-  /** Client coords -> the SVG's own user-space coords (the viewBox scales). */
-  const localPoint = useCallback(
-    (clientX: number, clientY: number): Pt => {
-      if (!svgEl) return { x: 0, y: 0 };
-      const r = svgEl.getBoundingClientRect();
-      return {
-        x: ((clientX - r.left) / r.width) * VIEW_W,
-        y: ((clientY - r.top) / r.height) * VIEW_H,
-      };
-    },
-    [svgEl]
-  );
-
-  /**
-   * ⚠ Wheel zoom MUST be a native, non-passive listener. React registers
-   * `wheel` PASSIVELY at the root, so `e.preventDefault()` inside an `onWheel`
-   * prop is a silent no-op: the page scrolls out from under the map while you
-   * zoom, which reads as "the zoom is broken". Nothing in a screenshot shows
-   * this, and no assertion on the rendered DOM can see it either.
-   *
-   * The zoom maths itself is `zoomAt` — the function the gate already proves
-   * holds the point under the cursor still. Wave 8 re-derived that formula
-   * inline here, so the tested copy and the shipped copy were two copies.
-   */
-  useEffect(() => {
-    if (!svgEl) return;
-    const onWheelNative = (e: WheelEvent) => {
-      e.preventDefault();
-      const { x, y } = localPoint(e.clientX, e.clientY);
-      touchedRef.current = true;
-      setView((v) => (v ? zoomAt(v, Math.exp(-e.deltaY * 0.0016), x, y, kMin, kMax) : v));
-    };
-    svgEl.addEventListener("wheel", onWheelNative, { passive: false });
-    return () => svgEl.removeEventListener("wheel", onWheelNative);
-  }, [svgEl, localPoint, kMin, kMax]);
-
-  /** Zoom about the viewport centre — the button and keyboard gesture, where
-   *  there is no cursor to hold still. */
-  const zoomBy = useCallback(
-    (factor: number) => {
-      touchedRef.current = true;
-      setView((v) => (v ? zoomAt(v, factor, VIEW_W / 2, VIEW_H / 2, kMin, kMax) : v));
-    },
-    [kMin, kMax]
-  );
-
-  const doFit = useCallback(() => {
-    touchedRef.current = false;
-    setView(fit);
-  }, [fit]);
-
-  const panBy = useCallback((dx: number, dy: number) => {
-    touchedRef.current = true;
-    setView((v) => (v ? { ...v, tx: v.tx + dx, ty: v.ty + dy } : v));
-  }, []);
-
-  /** The camera had NO keyboard path at all before wave 9 — scroll wheel only,
-   *  which is unusable without a mouse and unreachable for anyone driving the
-   *  page from the keyboard. */
-  const onFrameKeyDown = useCallback(
-    (e: ReactKeyboardEvent<HTMLDivElement>) => {
-      const step = e.shiftKey ? 160 : 60;
-      switch (e.key) {
-        case "ArrowLeft": panBy(step, 0); break;
-        case "ArrowRight": panBy(-step, 0); break;
-        case "ArrowUp": panBy(0, step); break;
-        case "ArrowDown": panBy(0, -step); break;
-        case "+": case "=": zoomBy(1.6); break;
-        case "-": case "_": zoomBy(1 / 1.6); break;
-        case "0": doFit(); break;
-        // Esc abandons a marquee mid-drag. It falls THROUGH when there is no
-        // drag, so it keeps closing whatever the host has open.
-        case "Escape": if (!drag) return; setDrag(null); break;
-        default: return;
-      }
-      e.preventDefault();
-    },
-    [panBy, zoomBy, doFit, drag]
-  );
-
-  const onPointerDown = useCallback(
-    (e: ReactPointerEvent<SVGSVGElement>) => {
-      if (e.button !== 0 || !view) return;
-      const { x, y } = localPoint(e.clientX, e.clientY);
-      movedRef.current = false;
-      e.currentTarget.setPointerCapture(e.pointerId);
-      // Shift (or Ctrl/Cmd) turns the drag into a SELECTION rectangle; a plain
-      // drag pans. Both gestures are on the same button because a map that
-      // needs a mode toggle to select is a map people never select on.
-      if (e.shiftKey || e.ctrlKey || e.metaKey) setDrag({ x0: x, y0: y, x1: x, y1: y });
-      else panRef.current = { x, y, tx: view.tx, ty: view.ty };
-    },
-    [view, localPoint]
-  );
-
-  const onPointerMove = useCallback(
-    (e: ReactPointerEvent<SVGSVGElement>) => {
-      const { x, y } = localPoint(e.clientX, e.clientY);
-      if (drag) {
-        movedRef.current = true;
-        setDrag((d) => (d ? { ...d, x1: x, y1: y } : d));
-        return;
-      }
-      const pan = panRef.current;
-      if (!pan) return;
-      if (Math.abs(x - pan.x) + Math.abs(y - pan.y) > 2) movedRef.current = true;
-      touchedRef.current = true;
-      setView((v) => (v ? { ...v, tx: pan.tx + (x - pan.x), ty: pan.ty + (y - pan.y) } : v));
-    },
-    [drag, localPoint]
-  );
-
-  const onPointerUp = useCallback(
-    (e: ReactPointerEvent<SVGSVGElement>) => {
-      if (drag && view) {
-        const r = normRect(drag.x0, drag.y0, drag.x1, drag.y1);
-        // A rectangle smaller than a few px is a mis-click, not a selection —
-        // clearing the user's set on a stray shift-click would be its own bug.
-        if (r.x1 - r.x0 > 3 && r.y1 - r.y0 > 3) {
-          const hits: number[] = [];
-          for (const p of points) {
-            const s = toScreen(p.p, view);
-            if (s.x >= r.x0 && s.x <= r.x1 && s.y >= r.y0 && s.y <= r.y1) hits.push(p.pid);
-          }
-          onSelectPids(hits, e.altKey ? "add" : "replace");
-        }
-        setDrag(null);
-      }
-      panRef.current = null;
-      if (e.currentTarget.hasPointerCapture(e.pointerId))
-        e.currentTarget.releasePointerCapture(e.pointerId);
-    },
-    [drag, view, points, onSelectPids]
-  );
-
-  if (!view || !fit) {
-    return (
-      <div className="cg-mode-empty">
-        No records with a location to map yet.
-        {noCoords > 0 &&
-          ` ${noCoords.toLocaleString()} matching record${noCoords === 1 ? "" : "s"} have no location.`}
-      </div>
-    );
-  }
-
-  const hovered = hoverPid != null ? points.find((p) => p.pid === hoverPid) : undefined;
-  const rect = drag ? normRect(drag.x0, drag.y0, drag.x1, drag.y1) : null;
-  const tf = `translate(${view.tx.toFixed(2)} ${view.ty.toFixed(2)}) scale(${view.k.toFixed(6)})`;
-  // Strokes live in the transformed group, so they are pre-divided by the zoom.
-  // ⚠ This is the map's ONE stroke mechanism — see the note over `hairline` in
-  // mapProjection.ts. No `.cg-map*` rule may add `vector-effect:
-  // non-scaling-stroke` on top; that double-cancel is the wave-9 blur bug and
-  // `scalingConflicts()` gates the stylesheet against it.
-  const hair = (w: number) => hairline(w, view.k);
-  const gratOpacity = graticuleOpacity(view.k);
-  // I18 — the Google hand-off. Our vendored basemap is honest to roughly metro
-  // scale; below that the answer is a LINK, not 270 KB gz of tile renderer plus
-  // a hosted planet file. Nothing is fetched and no coordinate leaves the page
-  // unless the user deliberately clicks.
-  const centre = unproject(fromScreen({ x: VIEW_W / 2, y: VIEW_H / 2 }, view));
-  const areaUrl = googleMapsUrl(centre.lat, centre.lon, googleZoomForK(view.k));
-  // A single selected pin gets its own exact hand-off. Selection is persistent,
-  // unlike hover — and the hover card must stay pointer-events:none, so a link
-  // could never live in it without becoming a click trap.
-  const solo = selectedPids.size === 1 ? points.find((p) => selectedPids.has(p.pid)) : undefined;
-  const sizeLegend = sizeRange && !sizeRange.none && sizeRange.max > sizeRange.min
-    ? [sizeRange.min, (sizeRange.min + sizeRange.max) / 2, sizeRange.max]
-    : null;
-
-  return (
-    <div className="cg-mapview">
-      <div className="cg-map-bar">
-        {/* The count is "N of M", never a bare N: a pin can only be drawn for a
-            row the host geocoded, and a lone "1,402" silently redefines the
-            toolbar's 1,550 ([[no-unverifiable-aggregates]]). */}
-        <span className="cg-cal-note cg-map-count">
-          <strong>{points.length.toLocaleString()}</strong> of{" "}
-          {rows.length.toLocaleString()} mapped · pinned at each customer's address
-        </span>
-        {noCoords > 0 && (
-          <span
-            className="cg-cal-nodate"
-            title={`${noCoords.toLocaleString()} matching record${noCoords === 1 ? "" : "s"} have no geocoded location and are not on the map. They remain in the Grid and List views.`}
-          >
-            {noCoords.toLocaleString()} matching record{noCoords === 1 ? " has" : "s have"} no location
-          </span>
-        )}
-        {/* One selected pin -> the exact geocode, handed off to Google. By
-            lat/lon and never by name: a name search can resolve somewhere else,
-            and then this link and our pin disagree about where a customer is.
-            rel="noopener noreferrer" strips the Referer, so Google never learns
-            which tenant or deployment the click came from. */}
-        {solo && (
-          <span className="cg-map-go">
-            <a
-              href={googleMapsUrl(solo.lat, solo.lon)}
-              target="_blank"
-              rel="noopener noreferrer"
-              title={`Open ${solo.title} in Google Maps at ${solo.lat.toFixed(5)}, ${solo.lon.toFixed(5)} (new tab)`}
-            >
-              {solo.title || "Selected pin"} in Google Maps
-            </a>
-            <a
-              href={googleDirectionsUrl(solo.lat, solo.lon)}
-              target="_blank"
-              rel="noopener noreferrer"
-              title={`Directions to ${solo.title} (new tab)`}
-            >
-              Directions
-            </a>
-          </span>
-        )}
-        {/* I18-R — the route planner. Appears only with a multi-pin selection, so
-            it is mutually exclusive with the single-pin links above and the bar
-            never carries both. */}
-        {selectedPids.size >= 2 && (
-          <span className="cg-map-route">
-            {!routeOn ? (
-              <button
-                type="button"
-                className="cg-map-route-go"
-                onClick={() => setRouteOn(true)}
-                disabled={routable.length < 2}
-                title={
-                  routable.length < 2
-                    ? "At least two selected records need a location to plan a route"
-                    : "Order these stops into a route"
-                }
-              >
-                Plan route ({routable.length.toLocaleString()} stops)
-              </button>
-            ) : (
-              plan && (
-                <>
-                  <span className="cg-map-route-sum">
-                    <strong>{plan.ordered.length.toLocaleString()}</strong> stops ·{" "}
-                    {Math.round(plan.km).toLocaleString()} km
-                    {/* ⚠ Never call this a driving distance, and never derive a
-                        time from it: it is the sum of straight lines. Saying so
-                        is the difference between a useful estimate and a lie. */}
-                    <span className="cg-map-route-note"> straight-line, not driving distance</span>
-                  </span>
-                  <label className="cg-map-route-opt">
-                    Start
-                    {/* ⚠ `value` is always set — a <select> without one renders its
-                        FIRST option regardless of state. It mirrors the ACTUAL
-                        origin, so the westernmost default shows itself too. */}
-                    <select
-                      className="cg-map-route-start"
-                      value={String(plan.ordered[0].pid)}
-                      onChange={(e) => setRouteStartPid(Number(e.target.value))}
-                    >
-                      {routable.map((p) => (
-                        <option key={p.pid} value={p.pid}>
-                          {p.title || `#${p.pid}`}
-                        </option>
-                      ))}
-                    </select>
-                  </label>
-                  <label className="cg-map-route-opt">
-                    <input
-                      type="checkbox"
-                      checked={roundTrip}
-                      onChange={(e) => setRoundTrip(e.target.checked)}
-                    />
-                    Return to start
-                  </label>
-                  {plan.link && (
-                    <a
-                      href={plan.link.url}
-                      target="_blank"
-                      rel="noopener noreferrer"
-                      title="Open this route in Google Maps for driving directions (new tab)"
-                    >
-                      Open route in Google Maps
-                      {/* The free URL takes 9 waypoints on desktop and 3 on a
-                          phone. When the route is longer, SAY which part rides. */}
-                      {plan.link.used < plan.ordered.length &&
-                        ` (first ${plan.link.used} of ${plan.ordered.length})`}
-                    </a>
-                  )}
-                  <button
-                    type="button"
-                    className="cg-map-route-go"
-                    onClick={() => {
-                      setRouteOn(false);
-                      setRouteStartPid(null);
-                    }}
-                  >
-                    Clear
-                  </button>
-                </>
-              )
-            )}
-            {unroutable > 0 && (
-              <span className="cg-cal-nodate">
-                {unroutable.toLocaleString()} selected record{unroutable === 1 ? " has" : "s have"} no
-                location and cannot be routed
-              </span>
-            )}
-          </span>
-        )}
-        <span className="cg-map-hint">
-          Scroll to zoom · drag to pan · shift-drag to select
-        </span>
-      </div>
-      <div
-        className="cg-map-frame"
-        tabIndex={0}
-        role="group"
-        aria-label="Map canvas. Arrow keys pan, plus and minus zoom, zero fits to data."
-        onKeyDown={onFrameKeyDown}
-      >
-        <svg
-          ref={setSvgEl}
-          viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
-          preserveAspectRatio="xMidYMid meet"
-          className={"cg-map-svg" + (drag ? " is-selecting" : "")}
-          role="img"
-          aria-label={`Map of ${points.length.toLocaleString()} customers`}
-          onPointerDown={onPointerDown}
-          onPointerMove={onPointerMove}
-          onPointerUp={onPointerUp}
-          onPointerCancel={onPointerUp}
-        >
-          <rect className="cg-map-water" x={0} y={0} width={VIEW_W} height={VIEW_H} />
-          <g transform={tf}>
-            {/* Graticule every 10 degrees. It earns its place zoomed OUT, where
-                it is the only thing giving scale; once the real state borders
-                arrive it would be a second line system fighting the first, so it
-                fades away before they take over. Skipped entirely at zero
-                opacity — ~36 invisible lines are still 36 nodes to lay out. */}
-            {gratOpacity > 0.01 && (
-              <g className="cg-map-grat" strokeWidth={hair(0.6)} opacity={gratOpacity}>
-              {Array.from({ length: 17 }, (_, i) => {
-                const y = project(0, -80 + i * 10).y;
-                return <line key={`p${i}`} x1={0} y1={y} x2={WORLD} y2={y} />;
-              })}
-              {Array.from({ length: 19 }, (_, i) => {
-                const x = project(-180 + i * 20, 0).x;
-                return <line key={`m${i}`} x1={x} y1={0} x2={x} y2={WORLD} />;
-              })}
-              </g>
-            )}
-            {/* One path, every US state ring. Filled AND stroked, so interior
-                state borders come free from the same geometry — no second pass
-                and no chance of the borders disagreeing with the coastline.
-                0.9 rather than wave 8's 1.1: that weight was tuned for a single
-                lone coastline, and it reads heavy once ~169 rings share it. */}
-            <path className="cg-map-land" d={LAND_PATH} strokeWidth={hair(0.9)} />
-            {LAKE_PATHS.map((d, i) => (
-              <path key={i} className="cg-map-lake" d={d} strokeWidth={hair(0.8)} />
-            ))}
-            {/* The planned path, UNDER the pins so it never hides a stop. Inside
-                the zoomed group, so it pans and scales with the geography; the
-                stroke is pre-divided by k like every other line here. */}
-            {plan && plan.ordered.length > 1 && (
-              <polyline
-                className="cg-map-route-line"
-                strokeWidth={hair(1.8)}
-                // ⚠ The dash MUST be pre-divided by the zoom too — a CSS
-                // dasharray is in user units and would scale with the group,
-                // turning the route into a few disconnected strokes.
-                strokeDasharray={dashPattern(5, 4, view.k)}
-                points={
-                  plan.ordered.map((p) => `${p.p.x},${p.p.y}`).join(" ") +
-                  (roundTrip ? ` ${plan.ordered[0].p.x},${plan.ordered[0].p.y}` : "")
-                }
-              />
-            )}
-            {points.map((p) => {
-              const c = paint(p);
-              const on = selectedPids.has(p.pid);
-              const r = radius(p) / view.k;
-              return (
-                <circle
-                  key={p.pid}
-                  className={
-                    "cg-map-pin" +
-                    (hoverPid === p.pid ? " is-hover" : "") +
-                    (on ? " is-selected" : "")
-                  }
-                  cx={p.p.x}
-                  cy={p.p.y}
-                  r={hoverPid === p.pid ? r * 1.28 : r}
-                  fill={c.fill}
-                  stroke={on ? "#202433" : c.line}
-                  strokeWidth={hair(on ? 2 : 1)}
-                  role="button"
-                  tabIndex={0}
-                  aria-label={`Open ${p.title}`}
-                  onMouseEnter={() => setHoverPid(p.pid)}
-                  onMouseLeave={() => setHoverPid((h) => (h === p.pid ? null : h))}
-                  onFocus={() => setHoverPid(p.pid)}
-                  onBlur={() => setHoverPid((h) => (h === p.pid ? null : h))}
-                  onClick={() => {
-                    if (movedRef.current) return; // a finished pan/box is not a click
-                    onOpen(p.pid);
-                  }}
-                  onKeyDown={(e) => {
-                    if (e.key !== "Enter" && e.key !== " ") return;
-                    e.preventDefault();
-                    onOpen(p.pid);
-                  }}
-                >
-                  <title>{p.title}</title>
-                </circle>
-              );
-            })}
-          </g>
-          {/* I18 — the hover card. Wave 8 painted the title alone; a map whose
-              pins carry a colour and a size encoding should say what they ARE.
-              ⚠ Every value goes through `formatDisplay`, the SAME formatter the
-              grid cells use, so a currency, a percentage or a date can never
-              read one way on the map and another way in the table.
-              Drawn in SVG screen space rather than as an HTML overlay: the
-              viewBox letterboxes under preserveAspectRatio, so an HTML card
-              would need the rendered scale re-derived, and this needs no
-              conversion at all. pointer-events stay off — a card that can
-              swallow the next click is a scar this codebase already carries. */}
-          {/* Stop numbers, in SCREEN space so they stay legible at every zoom.
-              pointer-events off: a badge sitting over a pin must not steal the
-              click that opens the record — re-rooting the route is the "Start"
-              picker's job, where it is visible and reversible. */}
-          {plan &&
-            plan.ordered.map((p, i) => {
-              const s = toScreen(p.p, view);
-              return (
-                <g
-                  className="cg-map-stopno"
-                  key={p.pid}
-                  transform={`translate(${s.x.toFixed(2)} ${(s.y - 13).toFixed(2)})`}
-                >
-                  <circle r={7.5} />
-                  <text textAnchor="middle" dy="3.4">{i + 1}</text>
-                </g>
-              );
-            })}
-          {hovered && (() => {
-            const s = toScreen(hovered.p, view);
-            const lines: string[] = [];
-            if (colorField)
-              lines.push(`${colorField.label}: ${formatDisplay(colorField, hovered.colorVal) || "—"}`);
-            if (sizeField)
-              lines.push(`${sizeField.label}: ${formatDisplay(sizeField, hovered.sizeVal) || "—"}`);
-            const title = hovered.title || "(untitled)";
-            // Inter's average advance at 11.5px. An estimate, deliberately
-            // generous: too wide is a slightly roomy card, too narrow is text
-            // spilling past its own background.
-            const w = Math.max(title.length, ...lines.map((l) => l.length)) * 6.2 + 20;
-            const h = 21 + lines.length * 14;
-            const b = cardBox(s.x, s.y, w, h, VIEW_W, VIEW_H);
-            return (
-              <g className="cg-map-card" aria-hidden="true">
-                <rect x={b.x} y={b.y} width={w} height={h} rx={5} />
-                <text className="cg-map-card-t" x={b.x + 10} y={b.y + 15}>{title}</text>
-                {lines.map((l, i) => (
-                  <text className="cg-map-card-l" key={i} x={b.x + 10} y={b.y + 15 + 14 * (i + 1)}>
-                    {l}
-                  </text>
-                ))}
-              </g>
-            );
-          })()}
-          {rect && (
-            <rect
-              className="cg-map-marquee"
-              x={rect.x0}
-              y={rect.y0}
-              width={rect.x1 - rect.x0}
-              height={rect.y1 - rect.y0}
-            />
-          )}
-        </svg>
-
-        {/* --- I18 — the camera controls. Zoom in / zoom out / fit to data, the
-            affordance every map has, replacing wave 8's link-button-in-a-text-bar.
-            OUTSIDE the <svg> deliberately: a mousedown on a button inside it would
-            begin a pan. Icons are SVG strokes — no emoji, no glyph font. The zoom
-            buttons DISABLE at the limits, which is also how the honesty cap on
-            zoom-in makes itself visible instead of just feeling stuck. --- */}
-        <div className="cg-map-ctl" role="group" aria-label="Map camera">
-          <button
-            type="button"
-            className="cg-map-ctl-b"
-            // A greyed button with no reason reads as broken, not as honest —
-            // and filtering to a single metro can push the FITTED zoom past the
-            // cap, so this can be disabled the instant the view opens. Say why,
-            // and point at the thing that does go further.
-            title={
-              view.k >= kMax * (1 - 1e-9)
-                ? "Zoom in — at the limit. The basemap's detail ends here; use Open in Google Maps for street level."
-                : "Zoom in (+)"
-            }
-            aria-label="Zoom in"
-            disabled={view.k >= kMax * (1 - 1e-9)}
-            onClick={() => zoomBy(1.6)}
-          >
-            <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M8 3.6v8.8M3.6 8h8.8" /></svg>
-          </button>
-          <button
-            type="button"
-            className="cg-map-ctl-b"
-            title="Zoom out (−)"
-            aria-label="Zoom out"
-            disabled={view.k <= kMin * (1 + 1e-9)}
-            onClick={() => zoomBy(1 / 1.6)}
-          >
-            <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M3.6 8h8.8" /></svg>
-          </button>
-          <button
-            type="button"
-            className="cg-map-ctl-b"
-            title="Fit to data (0)"
-            aria-label="Fit to data"
-            onClick={doFit}
-          >
-            <svg viewBox="0 0 16 16" aria-hidden="true">
-              <path d="M2.6 5.8V2.6h3.2M10.2 2.6h3.2v3.2M13.4 10.2v3.2h-3.2M5.8 13.4H2.6v-3.2" />
-              <path d="M6.6 8h2.8M8 6.6v2.8" />
-            </svg>
-          </button>
-          {/* The street-level hand-off, aimed at whatever is on screen right
-              now. This is what makes the zoom cap honest rather than merely
-              restrictive: the map stops where its geometry stops, and points at
-              something that does not. */}
-          <a
-            className="cg-map-ctl-b"
-            href={areaUrl}
-            target="_blank"
-            rel="noopener noreferrer"
-            title="Open this area in Google Maps (new tab)"
-            aria-label="Open this area in Google Maps"
-          >
-            <svg viewBox="0 0 16 16" aria-hidden="true">
-              <path d="M7 3.8H4.3a.9.9 0 0 0-.9.9v6.9a.9.9 0 0 0 .9.9h6.9a.9.9 0 0 0 .9-.9V9.2" />
-              <path d="M8.6 3.4h4v4M12.6 3.4 7.4 8.6" />
-            </svg>
-          </a>
-        </div>
-
-        {/* --- legends (I3/I5). Floated over the map, never in the flow. --- */}
-        {(colorBuckets || sizeLegend) && (
-          <div className="cg-map-legends">
-            {colorField && colorBuckets && (
-              <div className="cg-map-legend">
-                <div className="cg-map-legend-t">{colorField.label}</div>
-                {colorBuckets.order.slice(0, SERIES.length + 1).map((k) => {
-                  const c = k === "" ? OVERFLOW : colorBuckets.swatch.get(k) ?? OVERFLOW;
-                  return (
-                    <div key={k || "(blank)"} className="cg-map-legend-row">
-                      <span
-                        className="cg-map-swatch"
-                        style={{ background: c.fill, borderColor: c.line }}
-                      />
-                      <span className="cg-map-legend-k">{k === "" ? "(blank)" : k}</span>
-                      <span className="cg-map-legend-n">
-                        {(colorBuckets.counts.get(k) ?? 0).toLocaleString()}
-                      </span>
-                    </div>
-                  );
-                })}
-                {colorBuckets.overflow > 0 && (
-                  <div className="cg-map-legend-note">
-                    {colorBuckets.overflow.toLocaleString()} further value
-                    {colorBuckets.overflow === 1 ? " is" : "s are"} drawn grey — the palette
-                    holds {SERIES.length} colours and reusing one would make two values look
-                    like the same value.
-                  </div>
-                )}
-              </div>
-            )}
-            {sizeField && sizeRange && (
-              <div className="cg-map-legend">
-                <div className="cg-map-legend-t">{sizeField.label}</div>
-                {sizeLegend ? (
-                  <div className="cg-map-sizerow">
-                    {sizeLegend.map((v, i) => {
-                      const r = bubbleRadius(v, sizeRange.min, sizeRange.max, R_MIN, R_MAX, R_NULL);
-                      return (
-                        <span key={i} className="cg-map-sizeitem">
-                          <svg width={R_MAX * 2 + 2} height={R_MAX * 2 + 2} aria-hidden>
-                            <circle
-                              cx={R_MAX + 1}
-                              cy={R_MAX + 1}
-                              r={r}
-                              fill={DEFAULT_PIN.fill}
-                              stroke={DEFAULT_PIN.line}
-                            />
-                          </svg>
-                          <span className="cg-map-legend-k">{formatDisplay(sizeField, v)}</span>
-                        </span>
-                      );
-                    })}
-                  </div>
-                ) : (
-                  <div className="cg-map-legend-note">
-                    Every mapped record has the same {sizeField.label.toLowerCase()}, so the
-                    bubbles cannot differ in size.
-                  </div>
-                )}
-                {sizeRange.missing > 0 && (
-                  <div className="cg-map-legend-note">
-                    {sizeRange.missing.toLocaleString()} mapped record
-                    {sizeRange.missing === 1 ? " has" : "s have"} no value — drawn at the
-                    smallest dot, never removed from the map.
-                  </div>
-                )}
-              </div>
-            )}
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}
+// ---------------------------------------------------------------------------
+// customer-grid / MapView.tsx
+// "Map" is a VIEW beside Grid/List/Calendar/Kanban, not a module: it projects
+// the SAME pipeline output the grid paints, so the toolbar count, filters and
+// sorts mean exactly what they mean on the grid; only the projection changes.
+//
+// Wave 8 grows it up (I2/I3/I5/I6, contracts C2/C3/C7):
+//   I2  wheel/pinch zoom, drag to pan, and a box-select that feeds the grid's
+//       OWN selection — so the existing "N selected · Add to cohort" bar serves
+//       the map with no second cohort picker to keep in sync.
+//   I3  colour pins by any single-select field (`display.colorField`) + legend.
+//   I5  size pins by any numeric/measure field (`display.sizeField`) + legend.
+//   I6  a less templatic picture: water wash, land fill, thin C1 strokes,
+//       graticule, hover halos.
+//
+// C7 CALL — NO map library. C7 allows maplibre-gl "with a self-hosted
+// vector/raster-free style (NO external tile fetches ... if real tiles need a
+// network fetch, that is a blocker: fall back)". A basemap IS a network fetch,
+// and self-hosting tiles means shipping them inside a single-file embed. A
+// tileless maplibre would render exactly the geometry below for +230 KB gz on a
+// 251 KB budget. Declined on the contract's own terms; see the mailbox.
+//
+// Honesty rules (rule 8b), carried and extended:
+//   - rows WITHOUT coordinates are never silently hidden — a chip says
+//     "N matching records have no location";
+//   - a pin per row at its geocoded position, no clustering and no jitter (two
+//     customers at one address overlap rather than being drawn where they are
+//     not);
+//   - the colour legend STATES it when a field has more choices than the
+//     palette has entries, rather than recycling a colour onto a second meaning;
+//   - a row with no value under the size field gets the smallest dot and the
+//     legend says so — it is never dropped from the map.
+// ---------------------------------------------------------------------------
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { KeyboardEvent as ReactKeyboardEvent, PointerEvent as ReactPointerEvent } from "react";
+import type { Field, Row } from "./types";
+import { formatDisplay } from "./cells";
+import { LAND_PATH, LAKE_PATHS } from "./mapGeometry";
+import {
+  BASEMAP_DETAIL_K,
+  bubbleRadius,
+  cardBox,
+  dashPattern,
+  fitView,
+  fromScreen,
+  googleDirectionsUrl,
+  googleMapsUrl,
+  googleRouteUrl,
+  googleZoomForK,
+  graticuleOpacity,
+  hairline,
+  haversineKm,
+  isPlottable,
+  normRect,
+  planRoute,
+  project,
+  toScreen,
+  unproject,
+  WORLD,
+  zoomAt,
+  zoomLimits,
+} from "./mapProjection";
+import type { GeoStop, Pt, View } from "./mapProjection";
+
+const VIEW_W = 1000;
+const VIEW_H = 620;
+const R_MIN = 3.2;
+const R_MAX = 15;
+const R_PLAIN = 4.5;
+const R_NULL = 2.6;
+
+/**
+ * The pin palette: C1's cycle (blue -> green -> yellow -> red) then its
+ * 20%-darkened variants, exactly as the contract specifies for series colour.
+ * `fill` is the pastel; `line` is a darker companion, because a C1 pastel
+ * measures 1.4-1.9:1 on white and a fill alone would be a smudge (the same
+ * measurement that drove the I7c amendment).
+ */
+const SERIES: { fill: string; line: string }[] = [
+  { fill: "#9DBFF2", line: "#5F7FB0" },
+  { fill: "#A5D8B4", line: "#5E9C74" },
+  { fill: "#F5D989", line: "#B39A46" },
+  { fill: "#F0A8A0", line: "#B76D65" },
+  { fill: "#7E99C2", line: "#4A6790" },
+  { fill: "#84AD91", line: "#4C7A5C" },
+  { fill: "#C4AE6E", line: "#8C7838" },
+  { fill: "#C0867F", line: "#8A5049" },
+];
+/** Anything past the palette, plus the blank bucket. Neutral ON PURPOSE: a
+ *  ninth colour that repeats the first would make two meanings look identical. */
+const OVERFLOW = { fill: "#D7DBE3", line: "#8A909C" };
+const DEFAULT_PIN = { fill: "#9DBFF2", line: "#4F6079" };
+
+interface MapPoint {
+  pid: number;
+  title: string;
+  p: Pt;
+  /** The ORIGINAL coordinate, kept beside the projected one so the Google
+   *  hand-off links to the exact geocode we plotted rather than to a round-trip
+   *  through the projection. */
+  lat: number;
+  lon: number;
+  colorKey: string | null;
+  size: number | null;
+  /** The RAW cell values behind the two encodings. The hover card formats these
+   *  with `formatDisplay`, the grid's own formatter — `colorKey` is trimmed for
+   *  bucketing and `size` is coerced for the bubble scale, so neither is what a
+   *  human should be shown. */
+  colorVal: Row[keyof Row];
+  sizeVal: Row[keyof Row];
+}
+
+function coord(v: Row[keyof Row]): number | null {
+  if (v == null || v === "") return null;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+function numOrNull(v: Row[keyof Row]): number | null {
+  if (v == null || v === "") return null;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+export function MapView({
+  rows,
+  field,
+  colorField,
+  sizeField,
+  selectedPids,
+  onSelectPids,
+  onOpen,
+}: {
+  /** DISTINCT data rows from the full pipeline, overlay edits layered — the
+   *  calendar/kanban contract, verbatim. */
+  rows: Row[];
+  /** The locked identity column — pin tooltips and aria labels. */
+  field: Field;
+  /** I3 — the view's `display.colorField`, already resolved to a real field. */
+  colorField?: Field;
+  /** I5 — the view's `display.sizeField`, already resolved to a real field. */
+  sizeField?: Field;
+  /** The grid's selection, shared: pins render selected, and the existing
+   *  selection bar is what offers "Add to cohort" (C3). */
+  selectedPids: ReadonlySet<number>;
+  onSelectPids: (pids: number[], mode: "replace" | "add") => void;
+  onOpen: (pid: number) => void;
+}) {
+  const [hoverPid, setHoverPid] = useState<number | null>(null);
+  // I18-R — the route planner. Off until asked for: a route drawn over a
+  // selection nobody asked to route is just clutter.
+  const [routeOn, setRouteOn] = useState(false);
+  const [roundTrip, setRoundTrip] = useState(false);
+  const [routeStartPid, setRouteStartPid] = useState<number | null>(null);
+  const [view, setView] = useState<View | null>(null);
+  const [drag, setDrag] = useState<{ x0: number; y0: number; x1: number; y1: number } | null>(null);
+  /**
+   * ⚠ The svg element lives in STATE, not in a ref, and that is load-bearing.
+   *
+   * `view` starts null, so the FIRST render returns the empty state and there is
+   * no <svg> in the tree at all. A `useRef` would still be null when the wheel
+   * effect below first ran, and by the time the svg actually mounted the
+   * effect's deps (`localPoint`, `kMin`, `kMax`) were all unchanged — so React
+   * would never re-run it and the wheel listener would never be attached. Wheel
+   * zoom would be silently dead on the ordinary path.
+   *
+   * Holding the element in state makes attachment a consequence of MOUNTING
+   * rather than of a dependency happening to change, so the hazard cannot come
+   * back. No unit test can see this: the gate is pure TS under node, and a
+   * screenshot of a static page has no React in it.
+   */
+  const [svgEl, setSvgEl] = useState<SVGSVGElement | null>(null);
+  const panRef = useRef<{ x: number; y: number; tx: number; ty: number } | null>(null);
+  /** A finished drag must not also read as a click on the pin underneath — the
+   *  kanban card's lesson (viewModes.tsx), same fix. */
+  const movedRef = useRef(false);
+  /** Once the user has zoomed or panned, a data change must NOT yank the view
+   *  back. Before that, refitting on new data is the helpful behaviour. */
+  const touchedRef = useRef(false);
+
+  const points = useMemo(() => {
+    const out: MapPoint[] = [];
+    for (const r of rows) {
+      const lat = coord(r.lat);
+      const lon = coord(r.lon);
+      if (lat == null || lon == null) continue;
+      if (Math.abs(lat) > 90 || Math.abs(lon) > 180) continue;
+      out.push({
+        pid: r.pid,
+        title: String(r[field.key] ?? ""),
+        p: project(lon, lat),
+        lat,
+        lon,
+        colorKey: colorField ? String(r[colorField.key] ?? "").trim() : null,
+        size: sizeField ? numOrNull(r[sizeField.key]) : null,
+        colorVal: colorField ? r[colorField.key] : null,
+        sizeVal: sizeField ? r[sizeField.key] : null,
+      });
+    }
+    return out;
+  }, [rows, field.key, colorField, sizeField]);
+  const noCoords = rows.length - points.length;
+
+  // The fit is the INITIAL view, not the projection (see mapProjection.ts).
+  const fit = useMemo(
+    () => fitView(points.map((p) => p.p), VIEW_W, VIEW_H),
+    [points]
+  );
+  useEffect(() => {
+    if (!fit) return;
+    if (!touchedRef.current || view == null) setView(fit);
+    // `view` is deliberately absent from the deps: this effect exists to seed
+    // and re-fit, and re-running it on every pan would fight the user for the
+    // camera.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fit]);
+
+  const { kMin, kMax } = useMemo(
+    () => (fit ? zoomLimits(fit.k, VIEW_H, BASEMAP_DETAIL_K) : { kMin: 1, kMax: 1 }),
+    [fit]
+  );
+
+  /** Colour buckets, in first-seen order so the legend is stable. */
+  const colorBuckets = useMemo(() => {
+    if (!colorField) return null;
+    const order: string[] = [];
+    const counts = new Map<string, number>();
+    for (const p of points) {
+      const k = p.colorKey ?? "";
+      if (!counts.has(k)) {
+        counts.set(k, 0);
+        order.push(k);
+      }
+      counts.set(k, (counts.get(k) ?? 0) + 1);
+    }
+    const named = order.filter((k) => k !== "");
+    const swatch = new Map<string, { fill: string; line: string }>();
+    named.forEach((k, i) => swatch.set(k, i < SERIES.length ? SERIES[i] : OVERFLOW));
+    return {
+      order,
+      counts,
+      swatch,
+      overflow: Math.max(0, named.length - SERIES.length),
+    };
+  }, [colorField, points]);
+
+  /** The size field's observed range across MAPPED points (not the whole table:
+   *  the legend must describe the picture actually on screen). */
+  const sizeRange = useMemo(() => {
+    if (!sizeField) return null;
+    let min = Infinity;
+    let max = -Infinity;
+    let missing = 0;
+    for (const p of points) {
+      if (p.size == null) {
+        missing += 1;
+        continue;
+      }
+      min = Math.min(min, p.size);
+      max = Math.max(max, p.size);
+    }
+    if (!Number.isFinite(min)) return { min: 0, max: 0, missing, none: true };
+    return { min, max, missing, none: false };
+  }, [sizeField, points]);
+
+  /** A coarse pointer means a phone or tablet, where Google's free URL takes 3
+   *  waypoints rather than 9. A media query, not user-agent sniffing. */
+  const coarsePointer = useMemo(
+    () =>
+      typeof window !== "undefined" &&
+      typeof window.matchMedia === "function" &&
+      window.matchMedia("(pointer: coarse)").matches,
+    []
+  );
+
+  /** Selected pins that can actually be routed, in a STABLE order (by pid) —
+   *  a Set's iteration order must not be what decides a route. */
+  const routable = useMemo(
+    () =>
+      selectedPids.size < 2
+        ? []
+        : points
+            .filter((p) => selectedPids.has(p.pid) && isPlottable(p.lat, p.lon))
+            .sort((a, b) => a.pid - b.pid),
+    [points, selectedPids]
+  );
+  /** Selected records with no usable coordinate. Counted and shown, never
+   *  folded silently into the stop total ([[no-unverifiable-aggregates]]). */
+  const unroutable = selectedPids.size - routable.length;
+
+  const plan = useMemo(() => {
+    if (!routeOn || routable.length < 2) return null;
+    const stops: GeoStop[] = routable.map((p) => ({ lat: p.lat, lon: p.lon }));
+    // Default origin: the WESTERNMOST stop. Deterministic, stable while the user
+    // pans, and sayable out loud — unlike "whatever ended up at index 0". The
+    // picker below overrides it.
+    let start = 0;
+    for (let i = 1; i < routable.length; i++)
+      if (routable[i].lon < routable[start].lon) start = i;
+    if (routeStartPid != null) {
+      const i = routable.findIndex((p) => p.pid === routeStartPid);
+      if (i >= 0) start = i;
+    }
+    const { order, km } = planRoute(stops, haversineKm, { start, roundTrip });
+    return {
+      ordered: order.map((i) => routable[i]),
+      km,
+      link: googleRouteUrl(order.map((i) => stops[i]), { roundTrip, coarsePointer }),
+    };
+  }, [routeOn, routable, roundTrip, routeStartPid, coarsePointer]);
+
+  const paint = useCallback(
+    (p: MapPoint) => {
+      if (!colorBuckets) return DEFAULT_PIN;
+      const k = p.colorKey ?? "";
+      if (k === "") return OVERFLOW;
+      return colorBuckets.swatch.get(k) ?? OVERFLOW;
+    },
+    [colorBuckets]
+  );
+
+  const radius = useCallback(
+    (p: MapPoint) => {
+      if (!sizeField || !sizeRange || sizeRange.none) return R_PLAIN;
+      return bubbleRadius(p.size, sizeRange.min, sizeRange.max, R_MIN, R_MAX, R_NULL);
+    },
+    [sizeField, sizeRange]
+  );
+
+  /** Client coords -> the SVG's own user-space coords (the viewBox scales). */
+  const localPoint = useCallback(
+    (clientX: number, clientY: number): Pt => {
+      if (!svgEl) return { x: 0, y: 0 };
+      const r = svgEl.getBoundingClientRect();
+      return {
+        x: ((clientX - r.left) / r.width) * VIEW_W,
+        y: ((clientY - r.top) / r.height) * VIEW_H,
+      };
+    },
+    [svgEl]
+  );
+
+  /**
+   * ⚠ Wheel zoom MUST be a native, non-passive listener. React registers
+   * `wheel` PASSIVELY at the root, so `e.preventDefault()` inside an `onWheel`
+   * prop is a silent no-op: the page scrolls out from under the map while you
+   * zoom, which reads as "the zoom is broken". Nothing in a screenshot shows
+   * this, and no assertion on the rendered DOM can see it either.
+   *
+   * The zoom maths itself is `zoomAt` — the function the gate already proves
+   * holds the point under the cursor still. Wave 8 re-derived that formula
+   * inline here, so the tested copy and the shipped copy were two copies.
+   */
+  useEffect(() => {
+    if (!svgEl) return;
+    const onWheelNative = (e: WheelEvent) => {
+      e.preventDefault();
+      const { x, y } = localPoint(e.clientX, e.clientY);
+      touchedRef.current = true;
+      setView((v) => (v ? zoomAt(v, Math.exp(-e.deltaY * 0.0016), x, y, kMin, kMax) : v));
+    };
+    svgEl.addEventListener("wheel", onWheelNative, { passive: false });
+    return () => svgEl.removeEventListener("wheel", onWheelNative);
+  }, [svgEl, localPoint, kMin, kMax]);
+
+  /** Zoom about the viewport centre — the button and keyboard gesture, where
+   *  there is no cursor to hold still. */
+  const zoomBy = useCallback(
+    (factor: number) => {
+      touchedRef.current = true;
+      setView((v) => (v ? zoomAt(v, factor, VIEW_W / 2, VIEW_H / 2, kMin, kMax) : v));
+    },
+    [kMin, kMax]
+  );
+
+  const doFit = useCallback(() => {
+    touchedRef.current = false;
+    setView(fit);
+  }, [fit]);
+
+  const panBy = useCallback((dx: number, dy: number) => {
+    touchedRef.current = true;
+    setView((v) => (v ? { ...v, tx: v.tx + dx, ty: v.ty + dy } : v));
+  }, []);
+
+  /** The camera had NO keyboard path at all before wave 9 — scroll wheel only,
+   *  which is unusable without a mouse and unreachable for anyone driving the
+   *  page from the keyboard. */
+  const onFrameKeyDown = useCallback(
+    (e: ReactKeyboardEvent<HTMLDivElement>) => {
+      const step = e.shiftKey ? 160 : 60;
+      switch (e.key) {
+        case "ArrowLeft": panBy(step, 0); break;
+        case "ArrowRight": panBy(-step, 0); break;
+        case "ArrowUp": panBy(0, step); break;
+        case "ArrowDown": panBy(0, -step); break;
+        case "+": case "=": zoomBy(1.6); break;
+        case "-": case "_": zoomBy(1 / 1.6); break;
+        case "0": doFit(); break;
+        // Esc abandons a marquee mid-drag. It falls THROUGH when there is no
+        // drag, so it keeps closing whatever the host has open.
+        case "Escape": if (!drag) return; setDrag(null); break;
+        default: return;
+      }
+      e.preventDefault();
+    },
+    [panBy, zoomBy, doFit, drag]
+  );
+
+  const onPointerDown = useCallback(
+    (e: ReactPointerEvent<SVGSVGElement>) => {
+      if (e.button !== 0 || !view) return;
+      const { x, y } = localPoint(e.clientX, e.clientY);
+      movedRef.current = false;
+      e.currentTarget.setPointerCapture(e.pointerId);
+      // Shift (or Ctrl/Cmd) turns the drag into a SELECTION rectangle; a plain
+      // drag pans. Both gestures are on the same button because a map that
+      // needs a mode toggle to select is a map people never select on.
+      if (e.shiftKey || e.ctrlKey || e.metaKey) setDrag({ x0: x, y0: y, x1: x, y1: y });
+      else panRef.current = { x, y, tx: view.tx, ty: view.ty };
+    },
+    [view, localPoint]
+  );
+
+  const onPointerMove = useCallback(
+    (e: ReactPointerEvent<SVGSVGElement>) => {
+      const { x, y } = localPoint(e.clientX, e.clientY);
+      if (drag) {
+        movedRef.current = true;
+        setDrag((d) => (d ? { ...d, x1: x, y1: y } : d));
+        return;
+      }
+      const pan = panRef.current;
+      if (!pan) return;
+      if (Math.abs(x - pan.x) + Math.abs(y - pan.y) > 2) movedRef.current = true;
+      touchedRef.current = true;
+      setView((v) => (v ? { ...v, tx: pan.tx + (x - pan.x), ty: pan.ty + (y - pan.y) } : v));
+    },
+    [drag, localPoint]
+  );
+
+  const onPointerUp = useCallback(
+    (e: ReactPointerEvent<SVGSVGElement>) => {
+      if (drag && view) {
+        const r = normRect(drag.x0, drag.y0, drag.x1, drag.y1);
+        // A rectangle smaller than a few px is a mis-click, not a selection —
+        // clearing the user's set on a stray shift-click would be its own bug.
+        if (r.x1 - r.x0 > 3 && r.y1 - r.y0 > 3) {
+          const hits: number[] = [];
+          for (const p of points) {
+            const s = toScreen(p.p, view);
+            if (s.x >= r.x0 && s.x <= r.x1 && s.y >= r.y0 && s.y <= r.y1) hits.push(p.pid);
+          }
+          onSelectPids(hits, e.altKey ? "add" : "replace");
+        }
+        setDrag(null);
+      }
+      panRef.current = null;
+      if (e.currentTarget.hasPointerCapture(e.pointerId))
+        e.currentTarget.releasePointerCapture(e.pointerId);
+    },
+    [drag, view, points, onSelectPids]
+  );
+
+  if (!view || !fit) {
+    return (
+      <div className="cg-mode-empty">
+        No records with a location to map yet.
+        {noCoords > 0 &&
+          ` ${noCoords.toLocaleString()} matching record${noCoords === 1 ? "" : "s"} have no location.`}
+      </div>
+    );
+  }
+
+  const hovered = hoverPid != null ? points.find((p) => p.pid === hoverPid) : undefined;
+  const rect = drag ? normRect(drag.x0, drag.y0, drag.x1, drag.y1) : null;
+  const tf = `translate(${view.tx.toFixed(2)} ${view.ty.toFixed(2)}) scale(${view.k.toFixed(6)})`;
+  // Strokes live in the transformed group, so they are pre-divided by the zoom.
+  // ⚠ This is the map's ONE stroke mechanism — see the note over `hairline` in
+  // mapProjection.ts. No `.cg-map*` rule may add `vector-effect:
+  // non-scaling-stroke` on top; that double-cancel is the wave-9 blur bug and
+  // `scalingConflicts()` gates the stylesheet against it.
+  const hair = (w: number) => hairline(w, view.k);
+  const gratOpacity = graticuleOpacity(view.k);
+  // I18 — the Google hand-off. Our vendored basemap is honest to roughly metro
+  // scale; below that the answer is a LINK, not 270 KB gz of tile renderer plus
+  // a hosted planet file. Nothing is fetched and no coordinate leaves the page
+  // unless the user deliberately clicks.
+  const centre = unproject(fromScreen({ x: VIEW_W / 2, y: VIEW_H / 2 }, view));
+  const areaUrl = googleMapsUrl(centre.lat, centre.lon, googleZoomForK(view.k));
+  // A single selected pin gets its own exact hand-off. Selection is persistent,
+  // unlike hover — and the hover card must stay pointer-events:none, so a link
+  // could never live in it without becoming a click trap.
+  const solo = selectedPids.size === 1 ? points.find((p) => selectedPids.has(p.pid)) : undefined;
+  const sizeLegend = sizeRange && !sizeRange.none && sizeRange.max > sizeRange.min
+    ? [sizeRange.min, (sizeRange.min + sizeRange.max) / 2, sizeRange.max]
+    : null;
+
+  return (
+    <div className="cg-mapview">
+      <div className="cg-map-bar">
+        {/* The count is "N of M", never a bare N: a pin can only be drawn for a
+            row the host geocoded, and a lone "1,402" silently redefines the
+            toolbar's 1,550 ([[no-unverifiable-aggregates]]). */}
+        <span className="cg-cal-note cg-map-count">
+          <strong>{points.length.toLocaleString()}</strong> of{" "}
+          {rows.length.toLocaleString()} mapped · pinned at each customer's address
+        </span>
+        {noCoords > 0 && (
+          <span
+            className="cg-cal-nodate"
+            title={`${noCoords.toLocaleString()} matching record${noCoords === 1 ? "" : "s"} have no geocoded location and are not on the map. They remain in the Grid and List views.`}
+          >
+            {noCoords.toLocaleString()} matching record{noCoords === 1 ? " has" : "s have"} no location
+          </span>
+        )}
+        {/* One selected pin -> the exact geocode, handed off to Google. By
+            lat/lon and never by name: a name search can resolve somewhere else,
+            and then this link and our pin disagree about where a customer is.
+            rel="noopener noreferrer" strips the Referer, so Google never learns
+            which tenant or deployment the click came from. */}
+        {solo && (
+          <span className="cg-map-go">
+            <a
+              href={googleMapsUrl(solo.lat, solo.lon)}
+              target="_blank"
+              rel="noopener noreferrer"
+              title={`Open ${solo.title} in Google Maps at ${solo.lat.toFixed(5)}, ${solo.lon.toFixed(5)} (new tab)`}
+            >
+              {solo.title || "Selected pin"} in Google Maps
+            </a>
+            <a
+              href={googleDirectionsUrl(solo.lat, solo.lon)}
+              target="_blank"
+              rel="noopener noreferrer"
+              title={`Directions to ${solo.title} (new tab)`}
+            >
+              Directions
+            </a>
+          </span>
+        )}
+        {/* I18-R — the route planner. Appears only with a multi-pin selection, so
+            it is mutually exclusive with the single-pin links above and the bar
+            never carries both. */}
+        {selectedPids.size >= 2 && (
+          <span className="cg-map-route">
+            {!routeOn ? (
+              <button
+                type="button"
+                className="cg-map-route-go"
+                onClick={() => setRouteOn(true)}
+                disabled={routable.length < 2}
+                title={
+                  routable.length < 2
+                    ? "At least two selected records need a location to plan a route"
+                    : "Order these stops into a route"
+                }
+              >
+                Plan route ({routable.length.toLocaleString()} stops)
+              </button>
+            ) : (
+              plan && (
+                <>
+                  <span className="cg-map-route-sum">
+                    <strong>{plan.ordered.length.toLocaleString()}</strong> stops ·{" "}
+                    {Math.round(plan.km).toLocaleString()} km
+                    {/* ⚠ Never call this a driving distance, and never derive a
+                        time from it: it is the sum of straight lines. Saying so
+                        is the difference between a useful estimate and a lie. */}
+                    <span className="cg-map-route-note"> straight-line, not driving distance</span>
+                  </span>
+                  <label className="cg-map-route-opt">
+                    Start
+                    {/* ⚠ `value` is always set — a <select> without one renders its
+                        FIRST option regardless of state. It mirrors the ACTUAL
+                        origin, so the westernmost default shows itself too. */}
+                    <select
+                      className="cg-map-route-start"
+                      value={String(plan.ordered[0].pid)}
+                      onChange={(e) => setRouteStartPid(Number(e.target.value))}
+                    >
+                      {routable.map((p) => (
+                        <option key={p.pid} value={p.pid}>
+                          {p.title || `#${p.pid}`}
+                        </option>
+                      ))}
+                    </select>
+                  </label>
+                  <label className="cg-map-route-opt">
+                    <input
+                      type="checkbox"
+                      checked={roundTrip}
+                      onChange={(e) => setRoundTrip(e.target.checked)}
+                    />
+                    Return to start
+                  </label>
+                  {plan.link && (
+                    <a
+                      href={plan.link.url}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      title="Open this route in Google Maps for driving directions (new tab)"
+                    >
+                      Open route in Google Maps
+                      {/* The free URL takes 9 waypoints on desktop and 3 on a
+                          phone. When the route is longer, SAY which part rides. */}
+                      {plan.link.used < plan.ordered.length &&
+                        ` (first ${plan.link.used} of ${plan.ordered.length})`}
+                    </a>
+                  )}
+                  <button
+                    type="button"
+                    className="cg-map-route-go"
+                    onClick={() => {
+                      setRouteOn(false);
+                      setRouteStartPid(null);
+                    }}
+                  >
+                    Clear
+                  </button>
+                </>
+              )
+            )}
+            {unroutable > 0 && (
+              <span className="cg-cal-nodate">
+                {unroutable.toLocaleString()} selected record{unroutable === 1 ? " has" : "s have"} no
+                location and cannot be routed
+              </span>
+            )}
+          </span>
+        )}
+        <span className="cg-map-hint">
+          Scroll to zoom · drag to pan · shift-drag to select
+        </span>
+      </div>
+      <div
+        className="cg-map-frame"
+        tabIndex={0}
+        role="group"
+        aria-label="Map canvas. Arrow keys pan, plus and minus zoom, zero fits to data."
+        onKeyDown={onFrameKeyDown}
+      >
+        <svg
+          ref={setSvgEl}
+          viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
+          preserveAspectRatio="xMidYMid meet"
+          className={"cg-map-svg" + (drag ? " is-selecting" : "")}
+          role="img"
+          aria-label={`Map of ${points.length.toLocaleString()} customers`}
+          onPointerDown={onPointerDown}
+          onPointerMove={onPointerMove}
+          onPointerUp={onPointerUp}
+          onPointerCancel={onPointerUp}
+        >
+          <rect className="cg-map-water" x={0} y={0} width={VIEW_W} height={VIEW_H} />
+          <g transform={tf}>
+            {/* Graticule every 10 degrees. It earns its place zoomed OUT, where
+                it is the only thing giving scale; once the real state borders
+                arrive it would be a second line system fighting the first, so it
+                fades away before they take over. Skipped entirely at zero
+                opacity — ~36 invisible lines are still 36 nodes to lay out. */}
+            {gratOpacity > 0.01 && (
+              <g className="cg-map-grat" strokeWidth={hair(0.6)} opacity={gratOpacity}>
+              {Array.from({ length: 17 }, (_, i) => {
+                const y = project(0, -80 + i * 10).y;
+                return <line key={`p${i}`} x1={0} y1={y} x2={WORLD} y2={y} />;
+              })}
+              {Array.from({ length: 19 }, (_, i) => {
+                const x = project(-180 + i * 20, 0).x;
+                return <line key={`m${i}`} x1={x} y1={0} x2={x} y2={WORLD} />;
+              })}
+              </g>
+            )}
+            {/* One path, every US state ring. Filled AND stroked, so interior
+                state borders come free from the same geometry — no second pass
+                and no chance of the borders disagreeing with the coastline.
+                0.9 rather than wave 8's 1.1: that weight was tuned for a single
+                lone coastline, and it reads heavy once ~169 rings share it. */}
+            <path className="cg-map-land" d={LAND_PATH} strokeWidth={hair(0.9)} />
+            {LAKE_PATHS.map((d, i) => (
+              <path key={i} className="cg-map-lake" d={d} strokeWidth={hair(0.8)} />
+            ))}
+            {/* The planned path, UNDER the pins so it never hides a stop. Inside
+                the zoomed group, so it pans and scales with the geography; the
+                stroke is pre-divided by k like every other line here. */}
+            {plan && plan.ordered.length > 1 && (
+              <polyline
+                className="cg-map-route-line"
+                strokeWidth={hair(1.8)}
+                // ⚠ The dash MUST be pre-divided by the zoom too — a CSS
+                // dasharray is in user units and would scale with the group,
+                // turning the route into a few disconnected strokes.
+                strokeDasharray={dashPattern(5, 4, view.k)}
+                points={
+                  plan.ordered.map((p) => `${p.p.x},${p.p.y}`).join(" ") +
+                  (roundTrip ? ` ${plan.ordered[0].p.x},${plan.ordered[0].p.y}` : "")
+                }
+              />
+            )}
+            {points.map((p) => {
+              const c = paint(p);
+              const on = selectedPids.has(p.pid);
+              const r = radius(p) / view.k;
+              return (
+                <circle
+                  key={p.pid}
+                  className={
+                    "cg-map-pin" +
+                    (hoverPid === p.pid ? " is-hover" : "") +
+                    (on ? " is-selected" : "")
+                  }
+                  cx={p.p.x}
+                  cy={p.p.y}
+                  r={hoverPid === p.pid ? r * 1.28 : r}
+                  fill={c.fill}
+                  stroke={on ? "#202433" : c.line}
+                  strokeWidth={hair(on ? 2 : 1)}
+                  role="button"
+                  tabIndex={0}
+                  aria-label={`Open ${p.title}`}
+                  onMouseEnter={() => setHoverPid(p.pid)}
+                  onMouseLeave={() => setHoverPid((h) => (h === p.pid ? null : h))}
+                  onFocus={() => setHoverPid(p.pid)}
+                  onBlur={() => setHoverPid((h) => (h === p.pid ? null : h))}
+                  onClick={() => {
+                    if (movedRef.current) return; // a finished pan/box is not a click
+                    onOpen(p.pid);
+                  }}
+                  onKeyDown={(e) => {
+                    if (e.key !== "Enter" && e.key !== " ") return;
+                    e.preventDefault();
+                    onOpen(p.pid);
+                  }}
+                >
+                  <title>{p.title}</title>
+                </circle>
+              );
+            })}
+          </g>
+          {/* I18 — the hover card. Wave 8 painted the title alone; a map whose
+              pins carry a colour and a size encoding should say what they ARE.
+              ⚠ Every value goes through `formatDisplay`, the SAME formatter the
+              grid cells use, so a currency, a percentage or a date can never
+              read one way on the map and another way in the table.
+              Drawn in SVG screen space rather than as an HTML overlay: the
+              viewBox letterboxes under preserveAspectRatio, so an HTML card
+              would need the rendered scale re-derived, and this needs no
+              conversion at all. pointer-events stay off — a card that can
+              swallow the next click is a scar this codebase already carries. */}
+          {/* Stop numbers, in SCREEN space so they stay legible at every zoom.
+              pointer-events off: a badge sitting over a pin must not steal the
+              click that opens the record — re-rooting the route is the "Start"
+              picker's job, where it is visible and reversible. */}
+          {plan &&
+            plan.ordered.map((p, i) => {
+              const s = toScreen(p.p, view);
+              return (
+                <g
+                  className="cg-map-stopno"
+                  key={p.pid}
+                  transform={`translate(${s.x.toFixed(2)} ${(s.y - 13).toFixed(2)})`}
+                >
+                  <circle r={7.5} />
+                  <text textAnchor="middle" dy="3.4">{i + 1}</text>
+                </g>
+              );
+            })}
+          {hovered && (() => {
+            const s = toScreen(hovered.p, view);
+            const lines: string[] = [];
+            if (colorField)
+              lines.push(`${colorField.label}: ${formatDisplay(colorField, hovered.colorVal) || "—"}`);
+            if (sizeField)
+              lines.push(`${sizeField.label}: ${formatDisplay(sizeField, hovered.sizeVal) || "—"}`);
+            const title = hovered.title || "(untitled)";
+            // Inter's average advance at 11.5px. An estimate, deliberately
+            // generous: too wide is a slightly roomy card, too narrow is text
+            // spilling past its own background.
+            const w = Math.max(title.length, ...lines.map((l) => l.length)) * 6.2 + 20;
+            const h = 21 + lines.length * 14;
+            const b = cardBox(s.x, s.y, w, h, VIEW_W, VIEW_H);
+            return (
+              <g className="cg-map-card" aria-hidden="true">
+                <rect x={b.x} y={b.y} width={w} height={h} rx={5} />
+                <text className="cg-map-card-t" x={b.x + 10} y={b.y + 15}>{title}</text>
+                {lines.map((l, i) => (
+                  <text className="cg-map-card-l" key={i} x={b.x + 10} y={b.y + 15 + 14 * (i + 1)}>
+                    {l}
+                  </text>
+                ))}
+              </g>
+            );
+          })()}
+          {rect && (
+            <rect
+              className="cg-map-marquee"
+              x={rect.x0}
+              y={rect.y0}
+              width={rect.x1 - rect.x0}
+              height={rect.y1 - rect.y0}
+            />
+          )}
+        </svg>
+
+        {/* --- I18 — the camera controls. Zoom in / zoom out / fit to data, the
+            affordance every map has, replacing wave 8's link-button-in-a-text-bar.
+            OUTSIDE the <svg> deliberately: a mousedown on a button inside it would
+            begin a pan. Icons are SVG strokes — no emoji, no glyph font. The zoom
+            buttons DISABLE at the limits, which is also how the honesty cap on
+            zoom-in makes itself visible instead of just feeling stuck. --- */}
+        <div className="cg-map-ctl" role="group" aria-label="Map camera">
+          <button
+            type="button"
+            className="cg-map-ctl-b"
+            // A greyed button with no reason reads as broken, not as honest —
+            // and filtering to a single metro can push the FITTED zoom past the
+            // cap, so this can be disabled the instant the view opens. Say why,
+            // and point at the thing that does go further.
+            title={
+              view.k >= kMax * (1 - 1e-9)
+                ? "Zoom in — at the limit. The basemap's detail ends here; use Open in Google Maps for street level."
+                : "Zoom in (+)"
+            }
+            aria-label="Zoom in"
+            disabled={view.k >= kMax * (1 - 1e-9)}
+            onClick={() => zoomBy(1.6)}
+          >
+            <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M8 3.6v8.8M3.6 8h8.8" /></svg>
+          </button>
+          <button
+            type="button"
+            className="cg-map-ctl-b"
+            title="Zoom out (−)"
+            aria-label="Zoom out"
+            disabled={view.k <= kMin * (1 + 1e-9)}
+            onClick={() => zoomBy(1 / 1.6)}
+          >
+            <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M3.6 8h8.8" /></svg>
+          </button>
+          <button
+            type="button"
+            className="cg-map-ctl-b"
+            title="Fit to data (0)"
+            aria-label="Fit to data"
+            onClick={doFit}
+          >
+            <svg viewBox="0 0 16 16" aria-hidden="true">
+              <path d="M2.6 5.8V2.6h3.2M10.2 2.6h3.2v3.2M13.4 10.2v3.2h-3.2M5.8 13.4H2.6v-3.2" />
+              <path d="M6.6 8h2.8M8 6.6v2.8" />
+            </svg>
+          </button>
+          {/* The street-level hand-off, aimed at whatever is on screen right
+              now. This is what makes the zoom cap honest rather than merely
+              restrictive: the map stops where its geometry stops, and points at
+              something that does not. */}
+          <a
+            className="cg-map-ctl-b"
+            href={areaUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+            title="Open this area in Google Maps (new tab)"
+            aria-label="Open this area in Google Maps"
+          >
+            <svg viewBox="0 0 16 16" aria-hidden="true">
+              <path d="M7 3.8H4.3a.9.9 0 0 0-.9.9v6.9a.9.9 0 0 0 .9.9h6.9a.9.9 0 0 0 .9-.9V9.2" />
+              <path d="M8.6 3.4h4v4M12.6 3.4 7.4 8.6" />
+            </svg>
+          </a>
+        </div>
+
+        {/* --- legends (I3/I5). Floated over the map, never in the flow. --- */}
+        {(colorBuckets || sizeLegend) && (
+          <div className="cg-map-legends">
+            {colorField && colorBuckets && (
+              <div className="cg-map-legend">
+                <div className="cg-map-legend-t">{colorField.label}</div>
+                {colorBuckets.order.slice(0, SERIES.length + 1).map((k) => {
+                  const c = k === "" ? OVERFLOW : colorBuckets.swatch.get(k) ?? OVERFLOW;
+                  return (
+                    <div key={k || "(blank)"} className="cg-map-legend-row">
+                      <span
+                        className="cg-map-swatch"
+                        style={{ background: c.fill, borderColor: c.line }}
+                      />
+                      <span className="cg-map-legend-k">{k === "" ? "(blank)" : k}</span>
+                      <span className="cg-map-legend-n">
+                        {(colorBuckets.counts.get(k) ?? 0).toLocaleString()}
+                      </span>
+                    </div>
+                  );
+                })}
+                {colorBuckets.overflow > 0 && (
+                  <div className="cg-map-legend-note">
+                    {colorBuckets.overflow.toLocaleString()} further value
+                    {colorBuckets.overflow === 1 ? " is" : "s are"} drawn grey — the palette
+                    holds {SERIES.length} colours and reusing one would make two values look
+                    like the same value.
+                  </div>
+                )}
+              </div>
+            )}
+            {sizeField && sizeRange && (
+              <div className="cg-map-legend">
+                <div className="cg-map-legend-t">{sizeField.label}</div>
+                {sizeLegend ? (
+                  <div className="cg-map-sizerow">
+                    {sizeLegend.map((v, i) => {
+                      const r = bubbleRadius(v, sizeRange.min, sizeRange.max, R_MIN, R_MAX, R_NULL);
+                      return (
+                        <span key={i} className="cg-map-sizeitem">
+                          <svg width={R_MAX * 2 + 2} height={R_MAX * 2 + 2} aria-hidden>
+                            <circle
+                              cx={R_MAX + 1}
+                              cy={R_MAX + 1}
+                              r={r}
+                              fill={DEFAULT_PIN.fill}
+                              stroke={DEFAULT_PIN.line}
+                            />
+                          </svg>
+                          <span className="cg-map-legend-k">{formatDisplay(sizeField, v)}</span>
+                        </span>
+                      );
+                    })}
+                  </div>
+                ) : (
+                  <div className="cg-map-legend-note">
+                    Every mapped record has the same {sizeField.label.toLowerCase()}, so the
+                    bubbles cannot differ in size.
+                  </div>
+                )}
+                {sizeRange.missing > 0 && (
+                  <div className="cg-map-legend-note">
+                    {sizeRange.missing.toLocaleString()} mapped record
+                    {sizeRange.missing === 1 ? " has" : "s have"} no value — drawn at the
+                    smallest dot, never removed from the map.
+                  </div>
+                )}
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

web/src/customer-grid/OverlaySurface.tsx

@@ -1,355 +1,355 @@
-import {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useId,
-  useLayoutEffect,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
-import type {
-  AriaRole,
-  CSSProperties,
-  KeyboardEvent as ReactKeyboardEvent,
-  ReactNode,
-  RefObject,
-} from "react";
-import { createPortal } from "react-dom";
-import { computeOverlayPosition } from "./overlayPlacement";
-import type { Placement as OverlayPlacement } from "./overlayPlacement";
-
-export interface AnchorRect {
-  left: number;
-  top: number;
-  right: number;
-  bottom: number;
-  width: number;
-  height: number;
-}
-
-type Anchor = HTMLElement | AnchorRect;
-/**
- * Wave-9 I14 adds `right-start`: the panel sits BESIDE the anchor (top edges aligned), not
- * under it — the owner's "flyout to the RIGHT". It is a real placement rather than a margin
- * hack because the views rail is a 188px column at the left edge of an iframe, and a panel
- * absolutely-positioned inside `.cg-views` would be clipped by the rail it escapes; every
- * other overlay here is already body-level and fixed for the same reason.
- *
- * The placement ARITHMETIC moved to overlayPlacement.ts with that change, so the collision
- * maths is gated rather than eyeballed (verify_overlay.py).
- */
-type Placement = OverlayPlacement;
-
-interface OverlayStack {
-  register: (id: string) => () => void;
-  isTop: (id: string) => boolean;
-}
-
-const OverlayStackContext = createContext<OverlayStack | null>(null);
-
-const FOCUSABLE = [
-  "[data-overlay-autofocus]",
-  "button:not([disabled])",
-  "input:not([disabled])",
-  "select:not([disabled])",
-  "textarea:not([disabled])",
-  "[href]",
-  '[tabindex]:not([tabindex="-1"])',
-].join(",");
-
-export function OverlayProvider({ children }: { children: ReactNode }) {
-  const stack = useRef<string[]>([]);
-  const api = useMemo<OverlayStack>(
-    () => ({
-      register: (id) => {
-        stack.current = [...stack.current.filter((item) => item !== id), id];
-        return () => {
-          stack.current = stack.current.filter((item) => item !== id);
-        };
-      },
-      isTop: (id) => stack.current.at(-1) === id,
-    }),
-    []
-  );
-  return (
-    <OverlayStackContext.Provider value={api}>
-      {children}
-    </OverlayStackContext.Provider>
-  );
-}
-
-/**
- * ⚠ NULL IS A REACHABLE VALUE HERE, and it must not be fatal.
- *
- * Half the call sites pass `someRef.current`, which is legitimately null on the render
- * before the ref attaches, and `Anchor` does not include null — so every one of them was
- * one ordering accident away from `"getBoundingClientRect" in null`, a TypeError thrown
- * during RENDER, which unmounts the whole tree. That is not a hypothetical: it is what
- * `_qa_live_rail.py` reproduced on the shipped build when the saved-view menu's anchor
- * came back null (2026-08-04).
- *
- * A missing anchor is a positioning problem, not a reason to lose the application. The
- * panel degrades to a zero-rect at the viewport origin — visible, dismissible, obviously
- * wrong — while the root causes stay fixable at their own call sites.
- */
-const NO_RECT: AnchorRect = { left: 0, top: 0, right: 0, bottom: 0, width: 0, height: 0 };
-
-function anchorRect(anchor: Anchor | null | undefined): AnchorRect {
-  if (!anchor) return NO_RECT;
-  if ("getBoundingClientRect" in anchor) {
-    const rect = anchor.getBoundingClientRect();
-    return {
-      left: rect.left,
-      top: rect.top,
-      right: rect.right,
-      bottom: rect.bottom,
-      width: rect.width,
-      height: rect.height,
-    };
-  }
-  return anchor;
-}
-
-function samePosition(a: CSSProperties, b: CSSProperties): boolean {
-  return (
-    a.left === b.left &&
-    a.top === b.top &&
-    a.maxWidth === b.maxWidth &&
-    a.maxHeight === b.maxHeight &&
-    a.visibility === b.visibility
-  );
-}
-
-interface OverlayLayerOptions {
-  panelRef: RefObject<HTMLElement | null>;
-  onDismiss: () => void;
-  dismissOnOutside?: boolean;
-  initialFocus?: "first" | "none" | string;
-  restoreFocus?: boolean;
-  trapFocus?: boolean;
-  outsideElements?: Array<HTMLElement | null>;
-}
-
-/** Shared dismissal/focus contract for anchored menus and fixed drawers. */
-// oxlint-disable-next-line react/only-export-components -- shares the private overlay stack context.
-export function useOverlayLayer({
-  panelRef,
-  onDismiss,
-  dismissOnOutside = true,
-  initialFocus = "first",
-  restoreFocus = true,
-  trapFocus = false,
-  outsideElements = [],
-}: OverlayLayerOptions): void {
-  const id = useId();
-  const stack = useContext(OverlayStackContext);
-  const dismissRef = useRef(onDismiss);
-  const outsideRef = useRef(outsideElements);
-  dismissRef.current = onDismiss;
-  outsideRef.current = outsideElements;
-
-  useEffect(() => stack?.register(id), [id, stack]);
-
-  useEffect(() => {
-    const onPointerDown = (event: PointerEvent) => {
-      if (!dismissOnOutside || (stack && !stack.isTop(id))) return;
-      const target = event.target as Node | null;
-      if (!target || panelRef.current?.contains(target)) return;
-      if (outsideRef.current.some((element) => element?.contains(target))) return;
-      if (
-        document.activeElement instanceof HTMLElement &&
-        panelRef.current?.contains(document.activeElement)
-      )
-        document.activeElement.blur();
-      dismissRef.current();
-    };
-    const onKeyDown = (event: KeyboardEvent) => {
-      if (stack && !stack.isTop(id)) return;
-      if (event.key === "Escape") {
-        event.preventDefault();
-        event.stopPropagation();
-        if (
-          document.activeElement instanceof HTMLElement &&
-          panelRef.current?.contains(document.activeElement)
-        )
-          document.activeElement.blur();
-        dismissRef.current();
-        return;
-      }
-      if (event.key !== "Tab" || !trapFocus) return;
-      const focusable = Array.from(
-        panelRef.current?.querySelectorAll<HTMLElement>(FOCUSABLE) ?? []
-      ).filter((element) => element.getClientRects().length > 0);
-      if (!focusable.length) {
-        event.preventDefault();
-        panelRef.current?.focus();
-        return;
-      }
-      const first = focusable[0];
-      const last = focusable.at(-1)!;
-      const active = document.activeElement;
-      if (event.shiftKey && (active === first || !panelRef.current?.contains(active))) {
-        event.preventDefault();
-        last.focus();
-      } else if (!event.shiftKey && active === last) {
-        event.preventDefault();
-        first.focus();
-      }
-    };
-    document.addEventListener("pointerdown", onPointerDown, true);
-    document.addEventListener("keydown", onKeyDown, true);
-    return () => {
-      document.removeEventListener("pointerdown", onPointerDown, true);
-      document.removeEventListener("keydown", onKeyDown, true);
-    };
-  }, [dismissOnOutside, id, panelRef, stack, trapFocus]);
-
-  useLayoutEffect(() => {
-    const previous =
-      document.activeElement instanceof HTMLElement ? document.activeElement : null;
-    const frame = window.requestAnimationFrame(() => {
-      if (initialFocus === "none") return;
-      const selector = initialFocus === "first" ? FOCUSABLE : initialFocus;
-      const target = panelRef.current?.querySelector<HTMLElement>(selector);
-      target?.focus({ preventScroll: true });
-    });
-    return () => {
-      window.cancelAnimationFrame(frame);
-      if (restoreFocus && previous?.isConnected) previous.focus({ preventScroll: true });
-    };
-  }, [initialFocus, panelRef, restoreFocus]);
-}
-
-export function BodyPortal({ children }: { children: ReactNode }) {
-  return createPortal(children, document.body);
-}
-
-interface AnchoredOverlayProps {
-  /** ⚠ Nullable BY DECLARATION as of 2026-08-04. Several call sites pass `ref.current`,
-   *  which is null before the ref attaches, and the old non-null type made that a
-   *  render-time TypeError instead of a type error. See `anchorRect`. */
-  anchor: Anchor | null | undefined;
-  className: string;
-  children: ReactNode;
-  onDismiss: () => void;
-  placement?: Placement;
-  role?: AriaRole;
-  ariaLabel?: string;
-  id?: string;
-  initialFocus?: "first" | "none" | string;
-  restoreFocus?: boolean;
-  dismissOnOutside?: boolean;
-  onKeyDown?: (event: ReactKeyboardEvent<HTMLElement>) => void;
-  dataKind?: string;
-}
-
-/** Body-level fixed overlay with iframe-viewport collision handling. */
-export function AnchoredOverlay({
-  anchor,
-  className,
-  children,
-  onDismiss,
-  placement = "bottom-start",
-  role,
-  ariaLabel,
-  id,
-  initialFocus = "first",
-  restoreFocus = true,
-  dismissOnOutside = true,
-  onKeyDown,
-  dataKind,
-}: AnchoredOverlayProps) {
-  const panelRef = useRef<HTMLDivElement>(null);
-  const [style, setStyle] = useState<CSSProperties>({
-    position: "fixed",
-    left: 0,
-    top: 0,
-    visibility: "hidden",
-  });
-  const anchorElement = anchor && "getBoundingClientRect" in anchor ? anchor : null;
-
-  useOverlayLayer({
-    panelRef,
-    onDismiss,
-    dismissOnOutside,
-    initialFocus,
-    restoreFocus,
-    outsideElements: [anchorElement],
-  });
-
-  const updatePosition = useCallback(() => {
-    const panel = panelRef.current;
-    if (!panel) return;
-    const target = anchorRect(anchor);
-    const viewport = window.visualViewport;
-    const viewportLeft = viewport?.offsetLeft ?? 0;
-    const viewportTop = viewport?.offsetTop ?? 0;
-    const viewportWidth = viewport?.width ?? window.innerWidth;
-    const viewportHeight = viewport?.height ?? window.innerHeight;
-    const measured = panel.getBoundingClientRect();
-    // The arithmetic lives in overlayPlacement.ts so a gate can run it under node. This
-    // reads the DOM, decides nothing.
-    const placed = computeOverlayPosition({
-      placement,
-      target,
-      panel: {
-        width: Math.max(measured.width, panel.scrollWidth),
-        height: Math.max(measured.height, panel.scrollHeight),
-      },
-      viewport: {
-        left: viewportLeft,
-        top: viewportTop,
-        width: viewportWidth,
-        height: viewportHeight,
-      },
-    });
-    const next: CSSProperties = {
-      position: "fixed",
-      left: placed.left,
-      top: placed.top,
-      maxWidth: placed.maxWidth,
-      maxHeight: placed.maxHeight,
-      visibility: "visible",
-    };
-    setStyle((current) => (samePosition(current, next) ? current : next));
-  }, [anchor, placement]);
-
-  useLayoutEffect(() => {
-    updatePosition();
-    const frame = window.requestAnimationFrame(updatePosition);
-    const observer = new ResizeObserver(updatePosition);
-    if (panelRef.current) observer.observe(panelRef.current);
-    if (anchorElement) observer.observe(anchorElement);
-    window.addEventListener("resize", updatePosition);
-    window.addEventListener("scroll", updatePosition, true);
-    window.visualViewport?.addEventListener("resize", updatePosition);
-    window.visualViewport?.addEventListener("scroll", updatePosition);
-    return () => {
-      window.cancelAnimationFrame(frame);
-      observer.disconnect();
-      window.removeEventListener("resize", updatePosition);
-      window.removeEventListener("scroll", updatePosition, true);
-      window.visualViewport?.removeEventListener("resize", updatePosition);
-      window.visualViewport?.removeEventListener("scroll", updatePosition);
-    };
-  }, [anchorElement, updatePosition]);
-
-  return (
-    <BodyPortal>
-      <div
-        ref={panelRef}
-        id={id}
-        className={className}
-        style={style}
-        role={role}
-        aria-label={ariaLabel}
-        data-overlay-kind={dataKind}
-        onKeyDown={onKeyDown}
-      >
-        {children}
-      </div>
-    </BodyPortal>
-  );
-}
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import type {
+  AriaRole,
+  CSSProperties,
+  KeyboardEvent as ReactKeyboardEvent,
+  ReactNode,
+  RefObject,
+} from "react";
+import { createPortal } from "react-dom";
+import { computeOverlayPosition } from "./overlayPlacement";
+import type { Placement as OverlayPlacement } from "./overlayPlacement";
+
+export interface AnchorRect {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+  width: number;
+  height: number;
+}
+
+type Anchor = HTMLElement | AnchorRect;
+/**
+ * Wave-9 I14 adds `right-start`: the panel sits BESIDE the anchor (top edges aligned), not
+ * under it — the owner's "flyout to the RIGHT". It is a real placement rather than a margin
+ * hack because the views rail is a 188px column at the left edge of an iframe, and a panel
+ * absolutely-positioned inside `.cg-views` would be clipped by the rail it escapes; every
+ * other overlay here is already body-level and fixed for the same reason.
+ *
+ * The placement ARITHMETIC moved to overlayPlacement.ts with that change, so the collision
+ * maths is gated rather than eyeballed (verify_overlay.py).
+ */
+type Placement = OverlayPlacement;
+
+interface OverlayStack {
+  register: (id: string) => () => void;
+  isTop: (id: string) => boolean;
+}
+
+const OverlayStackContext = createContext<OverlayStack | null>(null);
+
+const FOCUSABLE = [
+  "[data-overlay-autofocus]",
+  "button:not([disabled])",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  "[href]",
+  '[tabindex]:not([tabindex="-1"])',
+].join(",");
+
+export function OverlayProvider({ children }: { children: ReactNode }) {
+  const stack = useRef<string[]>([]);
+  const api = useMemo<OverlayStack>(
+    () => ({
+      register: (id) => {
+        stack.current = [...stack.current.filter((item) => item !== id), id];
+        return () => {
+          stack.current = stack.current.filter((item) => item !== id);
+        };
+      },
+      isTop: (id) => stack.current.at(-1) === id,
+    }),
+    []
+  );
+  return (
+    <OverlayStackContext.Provider value={api}>
+      {children}
+    </OverlayStackContext.Provider>
+  );
+}
+
+/**
+ * ⚠ NULL IS A REACHABLE VALUE HERE, and it must not be fatal.
+ *
+ * Half the call sites pass `someRef.current`, which is legitimately null on the render
+ * before the ref attaches, and `Anchor` does not include null — so every one of them was
+ * one ordering accident away from `"getBoundingClientRect" in null`, a TypeError thrown
+ * during RENDER, which unmounts the whole tree. That is not a hypothetical: it is what
+ * `_qa_live_rail.py` reproduced on the shipped build when the saved-view menu's anchor
+ * came back null (2026-08-04).
+ *
+ * A missing anchor is a positioning problem, not a reason to lose the application. The
+ * panel degrades to a zero-rect at the viewport origin — visible, dismissible, obviously
+ * wrong — while the root causes stay fixable at their own call sites.
+ */
+const NO_RECT: AnchorRect = { left: 0, top: 0, right: 0, bottom: 0, width: 0, height: 0 };
+
+function anchorRect(anchor: Anchor | null | undefined): AnchorRect {
+  if (!anchor) return NO_RECT;
+  if ("getBoundingClientRect" in anchor) {
+    const rect = anchor.getBoundingClientRect();
+    return {
+      left: rect.left,
+      top: rect.top,
+      right: rect.right,
+      bottom: rect.bottom,
+      width: rect.width,
+      height: rect.height,
+    };
+  }
+  return anchor;
+}
+
+function samePosition(a: CSSProperties, b: CSSProperties): boolean {
+  return (
+    a.left === b.left &&
+    a.top === b.top &&
+    a.maxWidth === b.maxWidth &&
+    a.maxHeight === b.maxHeight &&
+    a.visibility === b.visibility
+  );
+}
+
+interface OverlayLayerOptions {
+  panelRef: RefObject<HTMLElement | null>;
+  onDismiss: () => void;
+  dismissOnOutside?: boolean;
+  initialFocus?: "first" | "none" | string;
+  restoreFocus?: boolean;
+  trapFocus?: boolean;
+  outsideElements?: Array<HTMLElement | null>;
+}
+
+/** Shared dismissal/focus contract for anchored menus and fixed drawers. */
+// oxlint-disable-next-line react/only-export-components -- shares the private overlay stack context.
+export function useOverlayLayer({
+  panelRef,
+  onDismiss,
+  dismissOnOutside = true,
+  initialFocus = "first",
+  restoreFocus = true,
+  trapFocus = false,
+  outsideElements = [],
+}: OverlayLayerOptions): void {
+  const id = useId();
+  const stack = useContext(OverlayStackContext);
+  const dismissRef = useRef(onDismiss);
+  const outsideRef = useRef(outsideElements);
+  dismissRef.current = onDismiss;
+  outsideRef.current = outsideElements;
+
+  useEffect(() => stack?.register(id), [id, stack]);
+
+  useEffect(() => {
+    const onPointerDown = (event: PointerEvent) => {
+      if (!dismissOnOutside || (stack && !stack.isTop(id))) return;
+      const target = event.target as Node | null;
+      if (!target || panelRef.current?.contains(target)) return;
+      if (outsideRef.current.some((element) => element?.contains(target))) return;
+      if (
+        document.activeElement instanceof HTMLElement &&
+        panelRef.current?.contains(document.activeElement)
+      )
+        document.activeElement.blur();
+      dismissRef.current();
+    };
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (stack && !stack.isTop(id)) return;
+      if (event.key === "Escape") {
+        event.preventDefault();
+        event.stopPropagation();
+        if (
+          document.activeElement instanceof HTMLElement &&
+          panelRef.current?.contains(document.activeElement)
+        )
+          document.activeElement.blur();
+        dismissRef.current();
+        return;
+      }
+      if (event.key !== "Tab" || !trapFocus) return;
+      const focusable = Array.from(
+        panelRef.current?.querySelectorAll<HTMLElement>(FOCUSABLE) ?? []
+      ).filter((element) => element.getClientRects().length > 0);
+      if (!focusable.length) {
+        event.preventDefault();
+        panelRef.current?.focus();
+        return;
+      }
+      const first = focusable[0];
+      const last = focusable.at(-1)!;
+      const active = document.activeElement;
+      if (event.shiftKey && (active === first || !panelRef.current?.contains(active))) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && active === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener("pointerdown", onPointerDown, true);
+    document.addEventListener("keydown", onKeyDown, true);
+    return () => {
+      document.removeEventListener("pointerdown", onPointerDown, true);
+      document.removeEventListener("keydown", onKeyDown, true);
+    };
+  }, [dismissOnOutside, id, panelRef, stack, trapFocus]);
+
+  useLayoutEffect(() => {
+    const previous =
+      document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    const frame = window.requestAnimationFrame(() => {
+      if (initialFocus === "none") return;
+      const selector = initialFocus === "first" ? FOCUSABLE : initialFocus;
+      const target = panelRef.current?.querySelector<HTMLElement>(selector);
+      target?.focus({ preventScroll: true });
+    });
+    return () => {
+      window.cancelAnimationFrame(frame);
+      if (restoreFocus && previous?.isConnected) previous.focus({ preventScroll: true });
+    };
+  }, [initialFocus, panelRef, restoreFocus]);
+}
+
+export function BodyPortal({ children }: { children: ReactNode }) {
+  return createPortal(children, document.body);
+}
+
+interface AnchoredOverlayProps {
+  /** ⚠ Nullable BY DECLARATION as of 2026-08-04. Several call sites pass `ref.current`,
+   *  which is null before the ref attaches, and the old non-null type made that a
+   *  render-time TypeError instead of a type error. See `anchorRect`. */
+  anchor: Anchor | null | undefined;
+  className: string;
+  children: ReactNode;
+  onDismiss: () => void;
+  placement?: Placement;
+  role?: AriaRole;
+  ariaLabel?: string;
+  id?: string;
+  initialFocus?: "first" | "none" | string;
+  restoreFocus?: boolean;
+  dismissOnOutside?: boolean;
+  onKeyDown?: (event: ReactKeyboardEvent<HTMLElement>) => void;
+  dataKind?: string;
+}
+
+/** Body-level fixed overlay with iframe-viewport collision handling. */
+export function AnchoredOverlay({
+  anchor,
+  className,
+  children,
+  onDismiss,
+  placement = "bottom-start",
+  role,
+  ariaLabel,
+  id,
+  initialFocus = "first",
+  restoreFocus = true,
+  dismissOnOutside = true,
+  onKeyDown,
+  dataKind,
+}: AnchoredOverlayProps) {
+  const panelRef = useRef<HTMLDivElement>(null);
+  const [style, setStyle] = useState<CSSProperties>({
+    position: "fixed",
+    left: 0,
+    top: 0,
+    visibility: "hidden",
+  });
+  const anchorElement = anchor && "getBoundingClientRect" in anchor ? anchor : null;
+
+  useOverlayLayer({
+    panelRef,
+    onDismiss,
+    dismissOnOutside,
+    initialFocus,
+    restoreFocus,
+    outsideElements: [anchorElement],
+  });
+
+  const updatePosition = useCallback(() => {
+    const panel = panelRef.current;
+    if (!panel) return;
+    const target = anchorRect(anchor);
+    const viewport = window.visualViewport;
+    const viewportLeft = viewport?.offsetLeft ?? 0;
+    const viewportTop = viewport?.offsetTop ?? 0;
+    const viewportWidth = viewport?.width ?? window.innerWidth;
+    const viewportHeight = viewport?.height ?? window.innerHeight;
+    const measured = panel.getBoundingClientRect();
+    // The arithmetic lives in overlayPlacement.ts so a gate can run it under node. This
+    // reads the DOM, decides nothing.
+    const placed = computeOverlayPosition({
+      placement,
+      target,
+      panel: {
+        width: Math.max(measured.width, panel.scrollWidth),
+        height: Math.max(measured.height, panel.scrollHeight),
+      },
+      viewport: {
+        left: viewportLeft,
+        top: viewportTop,
+        width: viewportWidth,
+        height: viewportHeight,
+      },
+    });
+    const next: CSSProperties = {
+      position: "fixed",
+      left: placed.left,
+      top: placed.top,
+      maxWidth: placed.maxWidth,
+      maxHeight: placed.maxHeight,
+      visibility: "visible",
+    };
+    setStyle((current) => (samePosition(current, next) ? current : next));
+  }, [anchor, placement]);
+
+  useLayoutEffect(() => {
+    updatePosition();
+    const frame = window.requestAnimationFrame(updatePosition);
+    const observer = new ResizeObserver(updatePosition);
+    if (panelRef.current) observer.observe(panelRef.current);
+    if (anchorElement) observer.observe(anchorElement);
+    window.addEventListener("resize", updatePosition);
+    window.addEventListener("scroll", updatePosition, true);
+    window.visualViewport?.addEventListener("resize", updatePosition);
+    window.visualViewport?.addEventListener("scroll", updatePosition);
+    return () => {
+      window.cancelAnimationFrame(frame);
+      observer.disconnect();
+      window.removeEventListener("resize", updatePosition);
+      window.removeEventListener("scroll", updatePosition, true);
+      window.visualViewport?.removeEventListener("resize", updatePosition);
+      window.visualViewport?.removeEventListener("scroll", updatePosition);
+    };
+  }, [anchorElement, updatePosition]);
+
+  return (
+    <BodyPortal>
+      <div
+        ref={panelRef}
+        id={id}
+        className={className}
+        style={style}
+        role={role}
+        aria-label={ariaLabel}
+        data-overlay-kind={dataKind}
+        onKeyDown={onKeyDown}
+      >
+        {children}
+      </div>
+    </BodyPortal>
+  );
+}