Deploy AIOS web (React glide grid + FastAPI slice)

RELEASES.json

@@ -1,5 +1,5 @@
 {
- "current": "e8f1e2f",
+ "current": "4258a93",
  "releases": [
   {
    "version": "v24",

VERSION

@@ -1 +1 @@
-e8f1e2f
+4258a93

api/connectors_bd.py

@@ -0,0 +1,745 @@
+"""connectors_bd.py -- THE BRIGHT DATA TRANSPORT. One vendor's wire, and nothing else.
+
+⭐⭐ WAVE 30 · T09 (DEBT D-128). Every function below was CORRECT CODE UNDER A WRONG NAME: it lived
+in `connectors_ig.py` and took the dataset id as a PARAMETER, which is the definition of not being
+Instagram's. `connectors_tt.py` therefore had to import thirteen names from the Instagram connector
+to reach a wire neither platform owns -- and the module header there said so in as many words
+(*"THE TRANSPORT IS BORROWED FROM `connectors_ig`, ON PURPOSE ... the name is wrong and the code is
+right"*). This file is that sentence resolved.
+
+⛔⛔ **THIS MODULE IS THE ONE PLACE A SOCKET IS OPENED TO BRIGHT DATA, AND THAT IS A TESTABILITY
+PROPERTY BEFORE IT IS AN ARCHITECTURAL ONE.** `bd_call` is the single door: `bd_scrape`,
+`bd_snapshot_progress` and the three corpus functions all reach the network THROUGH it, resolving it
+from THIS module's globals. So one monkeypatch on `connectors_bd.bd_call` seals every paid path in
+the product, for both platforms, whatever the caller. Before the split there was no such point --
+`connectors_ig.bd_call` sealed Instagram's rungs and TikTok's, but only because TikTok's connector
+had borrowed Instagram's function object, which is a coincidence of an import rather than a
+guarantee. [[seal-the-transport-not-the-rung]] is the standing rule; this module is where it becomes
+structural. ⚠ `verify_automation.py:_seal_bd` patches here AND sweeps `sys.modules` for any other
+binding of the same name, because a re-export elsewhere is a second door that reads exactly as green.
+
+⛔ **WHAT IS DELIBERATELY *NOT* HERE: ANY PLATFORM'S VOCABULARY.** No `BD_DS_*` dataset id (those are
+per-platform and stay with their connector), no field map, no profile/post/comment mapper. The test
+for whether something belongs here is not the `bd_` prefix -- it is whether the function could serve
+a THIRD platform tomorrow without an edit. ⚠ One Instagram assumption was found INSIDE the moved code
+and is now a parameter rather than a literal: `bd_filter_start`'s engine-added exclusion rule named
+the column `account`, which B-20 MEASURED as `account_id` in Bright Data's TikTok Profiles dataset.
+It rides on every discovery run, is invisible to the condition builder, and would have reached the
+vendor on the first TikTok search that had anything to exclude. See `handle_field`.
+
+⚠ **THE ROW PRIMITIVES IN SECTION 3 ARE HERE FOR A REASON AND IT IS NOT TIDINESS.** They are the
+readers every Bright Data mapper needs (a vendor row is JSON with two or three names for one fact),
+both connectors used them, and leaving them in `connectors_ig.py` would have kept the import line
+this ticket exists to delete. They know nothing about Instagram. ⚠ `_ig_int` KEEPS ITS NAME on
+purpose: it is referenced by name in the engine and in exact-match gate fixtures, and a rename buys
+nothing but a diff.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+
+import requests
+
+
+# =============================================================================================
+# 1. THE WIRE -- auth, one HTTP door, the scraper endpoints
+# =============================================================================================
+BD_BASE_DEFAULT = "https://api.brightdata.com"
+
+
+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;
+#: it is a ceiling against a hung socket, not a latency budget.
+BD_TIMEOUT = 300.0
+
+
+#: The READ ceiling for one vendor answer, in KB. `fetch` truncates SILENTLY at this size, so it
+#: is load-bearing arithmetic rather than a round number: MEASURED `file_size` was 175,617 bytes
+#: for 5 corpus rows ⇒ **~35 KB per profile row**, and `BD_MAX_RECORDS` is set from it with
+#: headroom (500 × 35 KB ≈ 17 MB against 32 MB). A truncated body is REPORTED as truncated in
+#: `bd_call` — never allowed to surface as "that is not JSON".
+BD_MAX_KB = 32768
+
+
+#: How long a run waits on a scrape batch the vendor DEFERRED (see `_bd_deferral`). Much shorter
+#: than the corpus filter's budget because a scrape snapshot is minutes, not tens of minutes —
+#: and unlike the corpus path there is no handoff to a later run, so this is the whole wait.
+BD_SCRAPE_WAIT = float(os.environ.get("AIOS_BD_SCRAPE_WAIT") or 180)
+
+
+BD_SCRAPE_POLL = float(os.environ.get("AIOS_BD_SCRAPE_POLL") or 10)
+
+
+# A Profile response is the enrichment's identity half, so it retains the normal bounded
+# synchronous wait. Post/Reel engagement can create several snapshots per profile; action
+# runners hand those off immediately and the scheduler collects the already-paid work later.
+BD_METRIC_SCRAPE_WAIT = float(os.environ.get("AIOS_BD_METRIC_SCRAPE_WAIT") or 0)
+
+
+#: ⚠ SPEC, NOT MEASURED — off the pricing page, never returned by the API (the funds gate fires
+#: BEFORE a price is quoted, and `price: 0` means "not priced", not "free"). Every surface that
+#: shows a number derived from this MUST say it is an estimate. `/customer/balance` answers 403
+#: for our token, so there is no way to check a balance or a spend from here either.
+BD_RECORD_PRICE_SPEC = 0.0025
+
+
+def bd_key():
+    """The key, or ''. Read fresh every call — see the module note above on why."""
+    return (os.environ.get("AIOS_BRIGHTDATA_KEY") or "").strip()
+
+
+def bd_base():
+    return (os.environ.get("AIOS_BRIGHTDATA_BASE") or BD_BASE_DEFAULT).strip().rstrip("/")
+
+
+def bd_ready():
+    """Is the paid rung configured at all? The UI reads this to say so honestly."""
+    return bool(bd_key())
+
+
+def _bd_why(raw, key=""):
+    """The vendor's OWN words for a refusal, as `" — …"`, or `""` when it gave none.
+
+    ⛔ THIS WAS THROWN AWAY, AND THE COST WAS MEASURED RATHER THAN IMAGINED. nurilab's live
+    discovery automation failed four runs across two days with `the profile source answered 400`
+    while the body it discarded said, in full:
+
+        {"validation_errors":["Filter logical groups can have a maximum of 4 rules."]}
+
+    — the exact instruction needed to fix it, in our hands, deleted one line before the customer.
+    A bare status code sends somebody to read a vendor's schema for a fault we were already
+    holding the answer to; it is the same defect as a green dot over nothing, pointed the other
+    way. Every non-2xx says WHY now, and the named cases above (402/401/403/429) keep their own
+    plainer sentences because those are ours to explain, not the vendor's.
+    """
+    from automation_engine import _s                             # lazy — see the module header
+    try:
+        text = bytes(raw or b"").decode("utf-8", "replace").strip()[:600]
+    except Exception:                                             # noqa: BLE001
+        return ""
+    if not text:
+        return ""
+    why = ""
+    try:
+        d = json.loads(text)
+    except Exception:                                             # noqa: BLE001
+        d = None
+    if isinstance(d, dict):
+        errs = d.get("validation_errors") or d.get("errors")
+        if isinstance(errs, list) and errs:
+            why = "; ".join(str(e) for e in errs)
+        else:
+            why = str(d.get("error") or d.get("message") or d.get("detail") or "")
+    why = why or text
+    # ⚠ A BODY WE DID NOT WRITE GETS THE SAME TREATMENT AS AN EXCEPTION'S str(). `bd_call` already
+    # refuses to put the latter on the wire in case it carries the key; promising that a vendor
+    # never echoes an Authorization header back is not a guarantee this module can make.
+    if key and key in why:
+        why = why.replace(key, "***")
+    return f" — {_s(why, 300)}"
+
+
+def bd_call(path, params=None, body=None):
+    """One authenticated vendor call. GET when `body` is None, POST otherwise.
+
+    Returns `(payload, note)`; a non-empty `note` means it did NOT answer, and the note is safe to
+    show a user and safe to write to a log.
+
+    Never raises. Every refusal shape — no key, a guarded base, a 402, a 429, a transport error,
+    unparseable JSON — comes back as a note so the caller can record the attempt and drop to the
+    next rung.
+    """
+    from automation_engine import Refused, fetch, fetch_json     # lazy — see the module header
+    key = bd_key()
+    if not key:
+        # ⛔ THE FAIL-CLOSED PATH (C4). Named precisely, because "blocked" with no reason sends
+        # somebody to read Instagram's status page instead of setting an env var.
+        return None, "AIOS_BRIGHTDATA_KEY is not configured — the paid rung is closed"
+    qs = "&".join(f"{k}={requests.utils.quote(str(v))}"
+                  for k, v in (params or {}).items() if v not in (None, ""))
+    url = f"{bd_base()}{path}" + (f"?{qs}" if qs else "")
+    hdrs = {"Authorization": f"Bearer {key}", "Accept": "application/json"}
+    try:
+        if body is None:
+            status, _final, raw = fetch(url, timeout=BD_TIMEOUT, max_kb=BD_MAX_KB, headers=hdrs)
+        else:
+            status, raw = fetch_json(url, body, timeout=BD_TIMEOUT, max_kb=BD_MAX_KB,
+                                     headers=hdrs)
+    except Refused as e:
+        # The BASE was refused by the SSRF rail — a configuration fault, not a vendor outage.
+        return None, f"the profile source's address was refused by the URL rail: {e}"
+    except Exception as e:                                        # noqa: BLE001
+        # ⚠ `type(e).__name__` only. A requests exception's str() can carry the full URL, and the
+        # Authorization header is one refactor away from being a query param; this line must not
+        # be what leaks it.
+        return None, f"the profile source did not answer ({type(e).__name__})"
+    if status == 402:
+        return None, "the profile search is out of credit"
+    if status in (401, 403):
+        return None, f"the profile source refused our key ({status})"
+    if status == 429:
+        # ⚠ MEASURED during the discovery probe: `too_many_parallel_jobs`. The filter API has a
+        # concurrency cap and the probe's most important test died on it — hence every caller
+        # below is SERIAL by construction.
+        return None, "the profile source is busy with another search; they run one at a time"
+    if not (200 <= status < 300):
+        return None, f"the profile source answered {status}{_bd_why(raw, key)}"
+    # ⛔ A BODY THAT REACHED THE READ CEILING IS A TRUNCATION, AND IT MUST SAY SO. `fetch` reads
+    # at most `max_kb` and returns what it got — silently. A truncated JSON document then fails
+    # `json.loads`, falls through to the NDJSON branch, and comes back as "answered with
+    # something that is not JSON": a sentence that sends somebody to read the vendor's schema
+    # looking for a fault that is OUR byte ceiling — after a result set that has already been
+    # paid for. Naming it here is the same no-silent-caps rule the row and table ceilings follow.
+    if len(raw) >= BD_MAX_KB * 1024:
+        return None, (f"the profile source's answer exceeded this client's {BD_MAX_KB // 1024} MB read "
+                      f"ceiling and was TRUNCATED — ask for fewer records; nothing was parsed "
+                      f"from a partial document")
+    text = raw.decode("utf-8", "replace").strip()
+    if not text:
+        return None, f"the profile source answered {status} with an empty body"
+    try:
+        return json.loads(text), ""
+    except Exception:                                             # noqa: BLE001
+        pass
+    # NDJSON is the other shape this API uses for row sets. Tried SECOND, so a genuine JSON error
+    # is not silently reinterpreted as a one-line NDJSON document.
+    rows = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rows.append(json.loads(line))
+        except Exception:                                         # noqa: BLE001
+            return None, "the profile source answered with something we could not read"
+    return (rows, "") if rows else (None, "the profile source answered with something we could not read")
+
+
+def _bd_rows(payload):
+    """A vendor answer → the list of row dicts inside it, whatever envelope it arrived in.
+
+    MEASURED shapes: a bare list (`/v3/scrape`), NDJSON (already listified by `bd_call`), and
+    `{"data": [...]}` / `{"results": [...]}` on the snapshot reads. An unreadable envelope yields
+    NOTHING rather than a guess.
+    """
+    if isinstance(payload, list):
+        return [x for x in payload if isinstance(x, dict)]
+    if isinstance(payload, dict):
+        for k in ("data", "results", "records", "items"):
+            v = payload.get(k)
+            if isinstance(v, list):
+                return [x for x in v if isinstance(x, dict)]
+        return [payload] if payload else []
+    return []
+
+
+def _bd_deferral(payload):
+    """The snapshot id when the 'sync' endpoint DEFERRED, else ''.
+
+    ⛔ MEASURED 2026-08-05, AND IT IS THE TRAP OF THIS WHOLE RUNG. `/v3/scrape` is documented and
+    named as the synchronous call, and for a small batch it is — two profile URLs came back
+    inline. Give it more work and it answers **200** with no rows and a note instead:
+
+        {"snapshot_id": "sd_…", "message": "Your request is still in progress and cannot be
+         retrieved in this call. Use the provided Snapshot ID to track progress…"}
+
+    Read naively that is a 200 with a body, so a parser looking for "did it error?" sails past
+    it, `_bd_rows` wraps the envelope as ONE unusable row, and the caller reports that the vendor
+    returned nothing — **while a snapshot we have already been billed for sits on the account,
+    finishing, and is never collected.** That is the D-26 failure shape (paid work abandoned)
+    arriving through the success path.
+    ⚠ It is a TIME threshold, not a row count: 2 URLs answered inline, 6 and 10 deferred.
+    """
+    if isinstance(payload, dict) and payload.get("snapshot_id") and not payload.get("account"):
+        return str(payload["snapshot_id"])
+    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.
+
+    Sends the SYNC call and, when the vendor defers it (see `_bd_deferral`), **collects the
+    snapshot it handed back** rather than discarding it. One call carries many URLs, which is
+    what keeps the per-profile pacing floor from turning a 20-profile run into an hour.
+    """
+    requested_urls = [str(u) for u in (urls or []) if u]
+    payload, note = bd_call(BD_PATH_SCRAPE, {"dataset_id": dataset_id},
+                            body=[{"url": u} for u in requested_urls])
+    if note:
+        return [], note
+    sid = _bd_deferral(payload)
+    if not sid:
+        return _bd_rows(payload), ""
+
+    # --- THE DEFERRED PATH. Poll the scraper namespace (`sd_…` at `/datasets/v3/…` — crossing it
+    # with the corpus namespace is a flat 404 about a snapshot that is alive).
+    budget = BD_SCRAPE_WAIT if wait is None else float(wait)
+    waited = 0.0
+    while True:
+        # ⭐ 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)
+        waited += BD_SCRAPE_POLL
+    # ⛔ NAME THE SNAPSHOT. It has been paid for and it is still finishing; a note that said only
+    # "no rows" would throw away both the data and the way to get it.
+    if isinstance(deferred, list):
+        deferred.append({"snapshotId": sid, "datasetId": str(dataset_id),
+                         "urls": requested_urls})
+    return [], (f"the profile source deferred this batch to {sid} and it was not ready within "
+                f"{int(budget)}s — the records are collected, not lost; ask for a smaller batch "
+                f"or collect {sid} from the control panel")
+
+
+# =============================================================================================
+# 2. THE CORPUS FILTER -- `POST /datasets/filter`, a DIFFERENT namespace from the scraper
+# =============================================================================================
+# ⚠ Snapshots minted here are `snap_…` and are read at `/datasets/snapshot/…`; the scraper's are
+# `sd_…` at `/datasets/v3/snapshot/…`, and the two 404 each other. Both halves live in this module
+# so that pairing is visible in one place instead of being rediscovered per platform.
+#: ⛔ THE VENDOR'S HARD CAP ON ONE LOGICAL GROUP — MEASURED 2026-08-06 against the live filter API
+#: with nurilab's own seven-condition search, which had failed every run for two days:
+#:
+#:     400 {"validation_errors":["Filter logical groups can have a maximum of 4 rules."]}
+#:
+#: ⚠ EVERY ONE OF THOSE SEVEN CONDITIONS IS ACCEPTED ALONE (all seven probed individually, all
+#: 200). The refusal is about the SHAPE of the group and nothing else — so no field, operator or
+#: value in the builder is at fault, and no amount of editing the conditions would have found it.
+#: What it means without `bd_group` below: the FIFTH condition anybody adds turns a working
+#: discovery automation into one that fails forever, and the surface blames the search.
+BD_GROUP_MAX = 4
+
+
+def bd_group(nodes, operator):
+    """`nodes` → an equivalent list in which NO logical group exceeds `BD_GROUP_MAX` rules.
+
+    ⭐ SAFE BECAUSE AND AND OR ARE ASSOCIATIVE. Folding a run of same-operator rules into a nested
+    group of the SAME operator cannot change what the filter matches — `a∧b∧c∧d∧e` and
+    `(a∧b∧c∧d)∧e` are one predicate written two ways. That is why this is a re-SHAPING of the
+    owner's search rather than a reinterpretation of it, and why it needs no ruling: a condition
+    list means the same thing before and after. Nesting itself is already proven on this API
+    (`expand_predicates`' or-groups, `snap_msh14ix81n8hlpo3nr`).
+
+    ⛔ A ONE-RULE CHUNK IS NEVER WRAPPED. `expand_predicates` already carries that law for the
+    one-value case — a one-element group is a shape nothing has ever been billed against — and a
+    balanced split reaches it whenever a level divides with a remainder of one.
+    """
+    nodes = list(nodes or [])
+    if len(nodes) <= BD_GROUP_MAX:
+        return nodes
+    # ⚠ BALANCED, NOT "take three and nest the rest". The tail-recursive shape costs one level of
+    # DEPTH per extra rule (13 conditions ⇒ 5 deep) against a vendor whose nesting limit we have
+    # not measured and would discover the same way we discovered this one: in production, on
+    # somebody's automation. Chunking makes the depth log₄(n) — 16 conditions fit in two levels.
+    out = []
+    for i in range(0, len(nodes), BD_GROUP_MAX):
+        chunk = nodes[i:i + BD_GROUP_MAX]
+        out.append(chunk[0] if len(chunk) == 1 else {"operator": operator, "filters": chunk})
+    return bd_group(out, operator)
+
+
+#: ⛔ DEBT D-68 — THE VENDOR'S NESTING CEILING, MEASURED IN PRODUCTION 2026-08-06:
+#:     400 — "filter" failed custom validation because logical operators cannot be more than
+#:           3 levels deep
+#: ⭐ AND IT IS NOT AN INDEPENDENT BUDGET FROM `BD_GROUP_MAX`. A >4-rule group is fixed by
+#: NESTING, so the 4-rule cap is what MANUFACTURES depth: five top-level conditions carrying
+#: multi-value lists goes `AND`(split) → `OR`(values) → `OR`(split) and is refused. The real
+#: envelope is about 4 top-level conditions x <=4 values each, which is why
+#: `MAX_PREDICATE_VALUES = 12` was never reachable at a realistic condition count.
+BD_MAX_DEPTH = 3
+
+
+def filter_depth(node):
+    """How many logical levels a vendor `filters` structure nests to. A bare rule is depth 1."""
+    if isinstance(node, list):
+        return max((filter_depth(n) for n in node), default=0)
+    if isinstance(node, dict) and isinstance(node.get("filters"), list):
+        return 1 + filter_depth(node["filters"])
+    return 1
+
+
+def depth_refusal(predicates, operator="and"):
+    """⭐ D-68 — refuse a search whose SHAPE the vendor will reject, before it is sent.
+
+    Returns a sentence or `""`.
+
+    ⛔ WHY THIS CANNOT BE A RULE-COUNT CHECK. The failure is in the emitted STRUCTURE, not in the
+    conditions: the same five conditions pass or fail depending on how many VALUES each carries,
+    because every multi-value list becomes its own OR level and every group over `BD_GROUP_MAX`
+    adds a split level. So the only honest test is to BUILD the shape and measure it — which is
+    cheap, because we build it anyway.
+    ⚠ Free to get wrong at the vendor and expensive to diagnose there: a rejected filter is never
+    billed, but the 400 says nothing about which condition to drop, so a person edits keywords for
+    an afternoon while the shape stays identical. That is what this sentence exists to prevent.
+    """
+    try:
+        depth = filter_depth(bd_group(expand_predicates(predicates), operator or "and"))
+    except Exception:                                                 # noqa: BLE001
+        return ""                                # never block a save on this check's own bug
+    if depth <= BD_MAX_DEPTH:
+        return ""
+    multi = [p for p in (predicates or [])
+             if isinstance((p or {}).get("value"), (list, tuple)) and len(p["value"]) > 1]
+    hint = (f"drop one of the {len(multi)} multi-value conditions, or shorten its list"
+            if multi else "drop one condition")
+    return (f"this search nests {depth} levels deep and the provider allows "
+            f"{BD_MAX_DEPTH} — {hint}. Every extra condition beyond {BD_GROUP_MAX}, and every "
+            f"list of values, adds a level")
+
+
+def expand_predicates(predicates):
+    """Stored predicates → the vendor's `filters` list, expanding a value LIST into a nested OR.
+
+    ⭐ MEASURED 2026-08-06: the filter API ACCEPTS a nested `{operator, filters:[…]}` inside
+    `filters` (`snap_msh14ix81n8hlpo3nr`), which is what makes "Bio contains any of floral,
+    flower, beauty" expressible WITHOUT setting the whole search to "match any". The alternative
+    — the global Match dropdown — would drag every other condition into the same union, so
+    "…and at least 10,000 followers" would silently become "…or at least 10,000 followers".
+
+    ⛔ A ONE-VALUE CONDITION IS STILL SENT FLAT. Wrapping it in a one-element group would be a
+    shape nothing has ever been billed against, adopted for tidiness, on the path that spends
+    money. Only the several-values case takes the new shape.
+    """
+    out = []
+    for p in predicates or []:
+        v = (p or {}).get("value")
+        if isinstance(v, list) and len(v) > 1:
+            # ⚠ THE OR-GROUP IS SUBJECT TO THE SAME 4-RULE CAP as the outer one, and this is the
+            # leg that hits it first in practice: "Bio contains any of floral, flower, beauty,
+            # bouquet, wedding" is five keywords in ONE condition — a single row in the builder,
+            # and a group the vendor refuses. `bd_group` is applied to the union too.
+            out.append({"operator": "or",
+                        "filters": bd_group(
+                            [{"name": p["name"], "operator": p["operator"], "value": one}
+                             for one in v], "or")})
+        elif isinstance(v, list):
+            out.append({**p, "value": v[0]} if v else
+                       {k: val for k, val in p.items() if k != "value"})
+        else:
+            out.append(dict(p))
+    return out
+
+
+#: ⛔ HOW MANY HANDLES ONE `not_in` MAY CARRY. W25/R1b MEASURED that the vendor accepts a flat
+#: `account not_in [...]` list to this size — *"the 12-value ceiling was OURS, not theirs"*. It is
+#: also why the rule below is built BY HAND instead of going through `expand_predicates`: that
+#: function turns any multi-value predicate into a nested OR of one-value rules, which for 5,000
+#: handles would be a 5,000-rule tree the vendor refuses on both its caps at once.
+BD_EXCLUDE_MAX = 5000
+
+
+def bd_filter_start(predicates, operator="and", records_limit=5, dataset_id="",
+                    exclude_handles=(), applied=None, handle_field="account"):
+    """Start ONE corpus query. Returns `(snapshot_id, note)`.
+
+    ⛔⛔ WAVE 30 · T09 — TWO INSTAGRAM ASSUMPTIONS CAME OUT OF THIS FUNCTION WHEN IT MOVED, AND THE
+    SECOND ONE WAS SPENDING MONEY.
+      1. `dataset_id` defaulted to `BD_DS_PROFILES`. In a module that serves both platforms a
+         default corpus is a wrong answer waiting for a caller who forgot; it now REFUSES with a
+         sentence rather than searching Instagram on TikTok's behalf.
+      2. ⭐ `handle_field`. The engine-added `not_in` exclusion below named the column **`account`**
+         — and B-20 MEASURED that Bright Data's TikTok Profiles dataset calls it **`account_id`**
+         (5 of our 21 filter names exist there at all; five more are renamed). This rule is
+         invisible to the condition builder by design, so no amount of restricting what a PERSON
+         may type keeps it off the wire: it rides on every discovery run that has anything to
+         exclude — i.e. every run after the first. ⚠ **What Bright Data DOES with an unknown filter
+         field is UNMEASURED** (refuse, or bill for an unfiltered corpus) and cannot be measured for
+         $0, since every `POST /datasets/filter` that answers 200 mints a billable snapshot. Naming
+         the column per platform is the half that can be fixed for nothing, so it is fixed here.
+
+    ⚠ ALWAYS THE COMPOUND `{operator, filters:[…]}` SHAPE, even for a single condition. A bare
+    `{name, operator, value}` is a plausible-looking second shape that has never been sent from
+    here, and a one-element `filters` list is a trivial extension of the three-element body that
+    HAS been measured end-to-end. One shape, and it is the tested one.
+
+    ⭐⭐ WAVE 27 ITEM 7 — `exclude_handles` IS THE ENGINE'S OWN REFINEMENT AND IS NEVER A CONDITION
+    ROW. Until now discovery paid for every re-found profile: a nightly search over the same
+    keywords returns the same accounts, the upsert notices they are `seen_again`, and the vendor
+    has already billed for all of them. This narrows the search at the VENDOR instead of after it.
+    It is invisible to the condition builder deliberately (W25/R1b: `not_in` is an engine-added
+    refinement, and `BD_OPS_BY_KIND` omits it so nobody can type one) — a person did not write it,
+    should not have to maintain it, and would be confused by a condition that changes every night.
+
+    ⛔ AND IT IS DROPPED RATHER THAN RISKED. Two ways a free saving could break a search that
+    works, and both are checked before the body is sent:
+      1. **DEPTH.** The vendor allows 3 logical levels and the 4-rule group cap MANUFACTURES
+         depth, so a search already near the ceiling gains a level from this rule and starts
+         answering 400 forever ([[bright-data-group-cap]]).
+      2. **`or`.** Under a top-level OR, adding an exclusion as another branch would WIDEN the
+         search to "…or any account not in this list" — i.e. the whole corpus. Under OR the
+         existing filter is wrapped in an AND instead, which costs the level checked in (1).
+    A dropped exclusion is not an error: the search runs exactly as it did before and we pay for
+    the duplicates, which is the status quo, not a regression.
+    """
+    if not str(dataset_id or "").strip():
+        # Fail-closed, and it names what is missing. A transport that guesses a corpus is a
+        # transport that bills the wrong one.
+        return "", "the search was not started — no corpus was named for this platform"
+    nodes = bd_group(expand_predicates(predicates), operator)
+    filt = {"operator": operator, "filters": nodes}
+    handles = [str(h).strip().lstrip("@").lower() for h in (exclude_handles or [])]
+    handles = [h for h in dict.fromkeys(handles) if h][:BD_EXCLUDE_MAX]
+    if isinstance(applied, dict):
+        applied["available"] = len(handles)
+        applied["excluded"] = 0
+    if handles:
+        rule = {"name": handle_field, "operator": "not_in", "value": handles}
+        cand = (bd_group([*nodes, rule], "and") if operator == "and"
+                else [filt, rule])
+        if filter_depth(cand) <= BD_MAX_DEPTH:
+            filt = {"operator": "and", "filters": cand}
+            if isinstance(applied, dict):
+                applied["excluded"] = len(handles)
+        elif isinstance(applied, dict):
+            applied["dropped"] = ("the search is already at the provider's nesting ceiling, so "
+                                  "the already-found list was left off rather than risk it")
+    body = {"dataset_id": dataset_id, "records_limit": int(records_limit),
+            # ⭐ `bd_group` — the top-level group obeys the vendor's 4-rule cap (see its note).
+            # Applied HERE rather than inside `expand_predicates` so the expansion stays a pure
+            # stored-shape → wire-shape translation and the rebalance is one readable step on the
+            # one path that actually posts a filter.
+            "filter": filt}
+    payload, note = bd_call(BD_PATH_FILTER, body=body)
+    if note:
+        return "", note
+    sid = str((payload or {}).get("snapshot_id") or "") if isinstance(payload, dict) else ""
+    if not sid:
+        return "", "the search was accepted but came back with nothing to collect it from"
+    return sid, ""
+
+
+def bd_filter_status(snapshot_id):
+    """`(status, size, note)` for a corpus snapshot. `status` ∈ building | ready | failed | ''."""
+    payload, note = bd_call(f"{BD_PATH_FILTER_SNAPSHOT}/{snapshot_id}")
+    if note:
+        return "", 0, note
+    d = payload if isinstance(payload, dict) else {}
+    status = str(d.get("status") or "")
+    err = str(d.get("error") or "")
+    if status == "failed" and "did not match any records" in err.lower():
+        # ⭐ MEASURED 2026-08-06 (`snap_msh14ix81n8hlpo3nr`): a filter that matches NOTHING comes
+        # back `failed` — "Provided filter did not match any records" — not `ready` with zero
+        # rows. Passed through, that reached the customer as "the search failed", which is the
+        # single most likely outcome of typing a keyword that is too specific and the one most
+        # certain to be read as "the product is broken". It is an ANSWER, so it gets its own
+        # status and no error note.
+        return "empty", 0, ""
+    if status == "failed" and err:
+        # NOT_ENOUGH_FUNDS is the one everybody will hit; say what it means, not just its name.
+        extra = (" — the matched set is too large for this account's balance; narrow the "
+                 "conditions or lower the limit" if "FUNDS" in err.upper() else "")
+        return status, 0, f"the search failed: {err}{extra}"
+    return status, int(d.get("dataset_size") or 0), ""
+
+
+def bd_filter_rows(snapshot_id):
+    """The rows of a READY corpus snapshot. `(rows, note)`.
+
+    ⚠ `/download` answered *"Snapshot is building. Try again in a few minutes"* while the status
+    endpoint ALREADY said `ready` — delivery lags readiness by minutes. So a download that does
+    not parse as rows is reported as not-yet-collectable rather than as an error.
+    """
+    payload, note = bd_call(f"{BD_PATH_FILTER_SNAPSHOT}/{snapshot_id}/download",
+                            {"format": "json"})
+    if note:
+        return [], note
+    rows = _bd_rows(payload)
+    if not rows:
+        return [], "the search is ready but its rows are not downloadable yet — the vendor's " \
+                   "delivery lags its own `ready` status by minutes"
+    return rows, ""
+
+
+# =============================================================================================
+# 3. ROW PRIMITIVES -- reading one vendor row, for any platform's mapper
+# =============================================================================================
+#: `bd_call` refuses a partial response at this same transport ceiling. A single source document
+#: therefore fits a JSON cell; Source data is never shortened by `_s`, which would corrupt JSON
+#: and silently lose fields.
+BD_SOURCE_PAYLOAD_MAX = BD_MAX_KB * 1024
+
+
+def _ig_int(v):
+    try:
+        return int(v)
+    except Exception:
+        return None
+
+
+def _first(node, *names, default=None):
+    """The first of `names` present on `node` with a real value.
+
+    ⚠ THE TOLERANCE IS THE POINT, not laziness. The vendor's `components/schemas` was not readable
+    on 2026-08-04 (recorded as RECALLED in the digest), so every media field name below is a
+    hypothesis. Reading through a candidate list means a rename costs one more candidate instead
+    of a rung that returns nothing and cannot say why. **A field that matches nothing returns
+    `default` (None), never 0** — an invented zero is a measurement, and this module's whole
+    honest-status contract exists to stop those.
+    """
+    if not isinstance(node, dict):
+        return default
+    for n in names:
+        v = node.get(n)
+        if v not in (None, ""):
+            return v
+    return default
+
+
+def _bd_first_url(v):
+    """A link-in-bio value → one string.
+
+    ⚠ MEASURED 2026-08-05: `external_url` is an **ARRAY** on the real row
+    (`["http://linktr.ee/utopianevents/"]`), not the string the previous vendor returned. A dict
+    (`external_url_title`) is also in the family. Read through the shape rather than assuming one.
+    """
+    if isinstance(v, list):
+        v = next((x for x in v if x), "")
+    if isinstance(v, dict):
+        v = _first(v, "url", "link", default="")
+    return str(v or "")
+
+
+def _bd_flag(node, *names):
+    """A vendor boolean → `'1'` / `''` / None. **None when the key is ABSENT or null**, which is
+    the distinction that matters: `is_business_account: false` is a measurement and `''` records
+    it; a missing key is not, and must not arrive as "false"."""
+    for n in names:
+        v = node.get(n) if isinstance(node, dict) else None
+        if v is None:
+            continue
+        return "1" if v is True or str(v).strip().lower() in ("true", "1", "yes") else ""
+    return None
+
+
+def _bd_list(node, *names):
+    """An array field → a comma-joined string, or None when it is absent/empty."""
+    for n in names:
+        v = node.get(n) if isinstance(node, dict) else None
+        if isinstance(v, list) and v:
+            return ", ".join(str(x) for x in v if x)[:400]
+    return None
+
+
+def _bd_source_payload(row):
+    """One complete Bright Data response row as valid JSON, without field filtering.
+
+    Source data is the lossless provider record, not a second relationship cache. A Profile's
+    embedded ``posts`` array stays here *and* each parseable post becomes a linked Post record;
+    keeping both preserves data while Links remain the interactive relational view. `bd_call`
+    rejects partial bodies at ``BD_SOURCE_PAYLOAD_MAX``, and the table-layer JSON ceiling matches
+    it, so this function never truncates a paid source response.
+    """
+    if not isinstance(row, dict):
+        return None
+    try:
+        packed = json.dumps({str(k): v for k, v in row.items()}, ensure_ascii=False,
+                            sort_keys=True, separators=(",", ":"))
+    except (TypeError, ValueError):
+        return None
+    # A source row is bounded by the complete raw HTTP response. Leave this defensive assertion
+    # explicit: should the transport ceiling and JSON-cell ceiling ever diverge, fail visibly
+    # rather than shortening a document and pretending every paid field was retained.
+    if len(packed.encode("utf-8")) > BD_SOURCE_PAYLOAD_MAX:
+        raise ValueError("a Bright Data source row exceeded the guarded response ceiling")
+    return packed

api/connectors_ig.py

@@ -35,7 +35,8 @@ probe doing `import connectors_ig` would have got a half-built engine and an Att
 inside a vendor call. **An intermittent-by-import-order failure is the worst shape available**, so
 every reach-back is a `from automation_engine import …` INSIDE the function that needs it, where
 the module is always fully built. There are exactly seven — `_bd_why`, `bd_call`,
-`apify_posts`, `apify_profile`, `_tag_metric_deferrals`, `pull_profile_bd`, `pull_profile` — each
+`apify_posts`, `apify_reels`, `apify_profile`, `_tag_metric_deferrals`, `pull_profile_bd`,
+`pull_profile` — each
 marked `# lazy — see the module header`, and they reach for four kinds of thing:
 
     fetch / fetch_json / Refused   the SSRF-guarded HTTP rail (the scrape runner shares it)
@@ -65,6 +66,43 @@ import requests
 
 import providers
 
+# ⭐⭐ WAVE 30 · T09 (DEBT D-128) — THE VENDOR WIRE LIVES IN `connectors_bd.py` NOW, AND THIS IS AN
+# IMPORT, NOT A RE-EXPORT-FOR-EVERYONE. Only the names THIS file's own code still calls are listed:
+# `verify_automation.section_split` derives the list both ways from the AST, so an import that
+# outlived its last call site and a use with no import are each a red. Everything else that used to
+# live here — `bd_ready`, `bd_key`, the whole corpus filter, `bd_group`, `expand_predicates` — is
+# reached by its callers directly from `connectors_bd`.
+#
+# ⛔ **WHY THE NAMES ARE IMPORTED RATHER THAN CALLED AS `bd.<name>`, deliberately:** the functions
+# below that still call `bd_call` and `bd_scrape` resolve them from THIS module's globals, which is
+# what makes `connectors_ig.bd_call = <stub>` continue to seal them exactly as it did before the
+# split. Changing the call style would have silently retired six working patch sites in the gate.
+# ⚠ **AND THE HALF THAT DOES NOT SURVIVE, because it is the money one:** a function that MOVED
+# (`bd_scrape`, `bd_snapshot_progress`, the corpus trio) now resolves `bd_call` from
+# `connectors_bd`'s globals, so patching it HERE no longer seals it. `verify_automation._seal_bd`
+# patches every module that holds a binding and then sweeps `sys.modules` to prove none was missed.
+from connectors_bd import (                                          # noqa: F401
+    BD_MAX_KB,
+    BD_METRIC_SCRAPE_WAIT,
+    BD_PATH_FILTER,
+    BD_PATH_FILTER_SNAPSHOT,
+    BD_PATH_SNAPSHOT,
+    BD_PATH_TRIGGER,
+    BD_SCRAPE_POLL,
+    BD_SCRAPE_WAIT,
+    _bd_deferral,
+    _bd_first_url,
+    _bd_flag,
+    _bd_list,
+    _bd_rows,
+    _bd_source_payload,
+    _first,
+    _ig_int,
+    bd_call,
+    bd_scrape,
+    bd_snapshot_progress
+)
+
 
 # ---------------------------------------------------------------------------------------------
 # HANDLE + COUNT READERS (no vendor, no key — pure parsing)
@@ -94,11 +132,6 @@ def ig_handle(url):
     return re.sub(r"[^A-Za-z0-9._]", "", first)[:40]
 
 
-def _ig_int(v):
-    try:
-        return int(v)
-    except Exception:
-        return None
 
 
 def _ig_zero_is_blank(v):
@@ -116,200 +149,22 @@ def _ig_zero_is_blank(v):
     return None if n == 0 else n
 
 
-BD_BASE_DEFAULT = "https://api.brightdata.com"
 BD_DS_PROFILES = "gd_l1vikfch901nx3by4"       # Instagram – Profiles. 36 fields, 620M records
 BD_DS_POSTS = "gd_lk5ns7kz21pck8jpis"         # Instagram – Posts. 43 fields
 BD_DS_REELS = "gd_lyclm20il4r5helnj"           # Instagram Reels: views and play counts
 BD_DS_COMMENTS = "gd_ltppn085pokosxh13"        # Instagram Comments: opt-in full comment engagement
-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;
-#: it is a ceiling against a hung socket, not a latency budget.
-BD_TIMEOUT = 300.0
-#: The READ ceiling for one vendor answer, in KB. `fetch` truncates SILENTLY at this size, so it
-#: is load-bearing arithmetic rather than a round number: MEASURED `file_size` was 175,617 bytes
-#: for 5 corpus rows ⇒ **~35 KB per profile row**, and `BD_MAX_RECORDS` is set from it with
-#: headroom (500 × 35 KB ≈ 17 MB against 32 MB). A truncated body is REPORTED as truncated in
-#: `bd_call` — never allowed to surface as "that is not JSON".
-BD_MAX_KB = 32768
-#: How long a run waits on a scrape batch the vendor DEFERRED (see `_bd_deferral`). Much shorter
-#: than the corpus filter's budget because a scrape snapshot is minutes, not tens of minutes —
-#: and unlike the corpus path there is no handoff to a later run, so this is the whole wait.
-BD_SCRAPE_WAIT = float(os.environ.get("AIOS_BD_SCRAPE_WAIT") or 180)
-BD_SCRAPE_POLL = float(os.environ.get("AIOS_BD_SCRAPE_POLL") or 10)
-# A Profile response is the enrichment's identity half, so it retains the normal bounded
-# synchronous wait. Post/Reel engagement can create several snapshots per profile; action
-# runners hand those off immediately and the scheduler collects the already-paid work later.
-BD_METRIC_SCRAPE_WAIT = float(os.environ.get("AIOS_BD_METRIC_SCRAPE_WAIT") or 0)
-#: ⚠ SPEC, NOT MEASURED — off the pricing page, never returned by the API (the funds gate fires
-#: BEFORE a price is quoted, and `price: 0` means "not priced", not "free"). Every surface that
-#: shows a number derived from this MUST say it is an estimate. `/customer/balance` answers 403
-#: for our token, so there is no way to check a balance or a spend from here either.
-BD_RECORD_PRICE_SPEC = 0.0025
-
-
-def bd_key():
-    """The key, or ''. Read fresh every call — see the module note above on why."""
-    return (os.environ.get("AIOS_BRIGHTDATA_KEY") or "").strip()
-
-
-def bd_base():
-    return (os.environ.get("AIOS_BRIGHTDATA_BASE") or BD_BASE_DEFAULT).strip().rstrip("/")
-
-
-def bd_ready():
-    """Is the paid rung configured at all? The UI reads this to say so honestly."""
-    return bool(bd_key())
-
-
-def _bd_why(raw, key=""):
-    """The vendor's OWN words for a refusal, as `" — …"`, or `""` when it gave none.
-
-    ⛔ THIS WAS THROWN AWAY, AND THE COST WAS MEASURED RATHER THAN IMAGINED. nurilab's live
-    discovery automation failed four runs across two days with `the profile source answered 400`
-    while the body it discarded said, in full:
-
-        {"validation_errors":["Filter logical groups can have a maximum of 4 rules."]}
-
-    — the exact instruction needed to fix it, in our hands, deleted one line before the customer.
-    A bare status code sends somebody to read a vendor's schema for a fault we were already
-    holding the answer to; it is the same defect as a green dot over nothing, pointed the other
-    way. Every non-2xx says WHY now, and the named cases above (402/401/403/429) keep their own
-    plainer sentences because those are ours to explain, not the vendor's.
-    """
-    from automation_engine import _s                             # lazy — see the module header
-    try:
-        text = bytes(raw or b"").decode("utf-8", "replace").strip()[:600]
-    except Exception:                                             # noqa: BLE001
-        return ""
-    if not text:
-        return ""
-    why = ""
-    try:
-        d = json.loads(text)
-    except Exception:                                             # noqa: BLE001
-        d = None
-    if isinstance(d, dict):
-        errs = d.get("validation_errors") or d.get("errors")
-        if isinstance(errs, list) and errs:
-            why = "; ".join(str(e) for e in errs)
-        else:
-            why = str(d.get("error") or d.get("message") or d.get("detail") or "")
-    why = why or text
-    # ⚠ A BODY WE DID NOT WRITE GETS THE SAME TREATMENT AS AN EXCEPTION'S str(). `bd_call` already
-    # refuses to put the latter on the wire in case it carries the key; promising that a vendor
-    # never echoes an Authorization header back is not a guarantee this module can make.
-    if key and key in why:
-        why = why.replace(key, "***")
-    return f" — {_s(why, 300)}"
 
 
-def bd_call(path, params=None, body=None):
-    """One authenticated vendor call. GET when `body` is None, POST otherwise.
 
-    Returns `(payload, note)`; a non-empty `note` means it did NOT answer, and the note is safe to
-    show a user and safe to write to a log.
 
-    Never raises. Every refusal shape — no key, a guarded base, a 402, a 429, a transport error,
-    unparseable JSON — comes back as a note so the caller can record the attempt and drop to the
-    next rung.
-    """
-    from automation_engine import Refused, fetch, fetch_json     # lazy — see the module header
-    key = bd_key()
-    if not key:
-        # ⛔ THE FAIL-CLOSED PATH (C4). Named precisely, because "blocked" with no reason sends
-        # somebody to read Instagram's status page instead of setting an env var.
-        return None, "AIOS_BRIGHTDATA_KEY is not configured — the paid rung is closed"
-    qs = "&".join(f"{k}={requests.utils.quote(str(v))}"
-                  for k, v in (params or {}).items() if v not in (None, ""))
-    url = f"{bd_base()}{path}" + (f"?{qs}" if qs else "")
-    hdrs = {"Authorization": f"Bearer {key}", "Accept": "application/json"}
-    try:
-        if body is None:
-            status, _final, raw = fetch(url, timeout=BD_TIMEOUT, max_kb=BD_MAX_KB, headers=hdrs)
-        else:
-            status, raw = fetch_json(url, body, timeout=BD_TIMEOUT, max_kb=BD_MAX_KB,
-                                     headers=hdrs)
-    except Refused as e:
-        # The BASE was refused by the SSRF rail — a configuration fault, not a vendor outage.
-        return None, f"the profile source's address was refused by the URL rail: {e}"
-    except Exception as e:                                        # noqa: BLE001
-        # ⚠ `type(e).__name__` only. A requests exception's str() can carry the full URL, and the
-        # Authorization header is one refactor away from being a query param; this line must not
-        # be what leaks it.
-        return None, f"the profile source did not answer ({type(e).__name__})"
-    if status == 402:
-        return None, "the profile search is out of credit"
-    if status in (401, 403):
-        return None, f"the profile source refused our key ({status})"
-    if status == 429:
-        # ⚠ MEASURED during the discovery probe: `too_many_parallel_jobs`. The filter API has a
-        # concurrency cap and the probe's most important test died on it — hence every caller
-        # below is SERIAL by construction.
-        return None, "the profile source is busy with another search; they run one at a time"
-    if not (200 <= status < 300):
-        return None, f"the profile source answered {status}{_bd_why(raw, key)}"
-    # ⛔ A BODY THAT REACHED THE READ CEILING IS A TRUNCATION, AND IT MUST SAY SO. `fetch` reads
-    # at most `max_kb` and returns what it got — silently. A truncated JSON document then fails
-    # `json.loads`, falls through to the NDJSON branch, and comes back as "answered with
-    # something that is not JSON": a sentence that sends somebody to read the vendor's schema
-    # looking for a fault that is OUR byte ceiling — after a result set that has already been
-    # paid for. Naming it here is the same no-silent-caps rule the row and table ceilings follow.
-    if len(raw) >= BD_MAX_KB * 1024:
-        return None, (f"the profile source's answer exceeded this client's {BD_MAX_KB // 1024} MB read "
-                      f"ceiling and was TRUNCATED — ask for fewer records; nothing was parsed "
-                      f"from a partial document")
-    text = raw.decode("utf-8", "replace").strip()
-    if not text:
-        return None, f"the profile source answered {status} with an empty body"
-    try:
-        return json.loads(text), ""
-    except Exception:                                             # noqa: BLE001
-        pass
-    # NDJSON is the other shape this API uses for row sets. Tried SECOND, so a genuine JSON error
-    # is not silently reinterpreted as a one-line NDJSON document.
-    rows = []
-    for line in text.splitlines():
-        line = line.strip()
-        if not line:
-            continue
-        try:
-            rows.append(json.loads(line))
-        except Exception:                                         # noqa: BLE001
-            return None, "the profile source answered with something we could not read"
-    return (rows, "") if rows else (None, "the profile source answered with something we could not read")
 
 
-def _first(node, *names, default=None):
-    """The first of `names` present on `node` with a real value.
 
-    ⚠ THE TOLERANCE IS THE POINT, not laziness. The vendor's `components/schemas` was not readable
-    on 2026-08-04 (recorded as RECALLED in the digest), so every media field name below is a
-    hypothesis. Reading through a candidate list means a rename costs one more candidate instead
-    of a rung that returns nothing and cannot say why. **A field that matches nothing returns
-    `default` (None), never 0** — an invented zero is a measurement, and this module's whole
-    honest-status contract exists to stop those.
-    """
-    if not isinstance(node, dict):
-        return default
-    for n in names:
-        v = node.get(n)
-        if v not in (None, ""):
-            return v
-    return default
+
+
+
+
+
 
 
 #: Source-data retention is intentionally unfiltered: if Bright Data returned it in an already
@@ -317,10 +172,6 @@ def _first(node, *names, default=None):
 #: The one cost boundary is the *request*: the full Comments dataset is only called when an owner
 #: enables `commentMetrics`.
 
-#: `bd_call` refuses a partial response at this same transport ceiling. A single source document
-#: therefore fits a JSON cell; Source data is never shortened by `_s`, which would corrupt JSON
-#: and silently lose fields.
-BD_SOURCE_PAYLOAD_MAX = BD_MAX_KB * 1024
 
 #: The vendor's content vocabulary → ours. MEASURED values: profiles' `posts[].content_type` is
 #: `Image`/`Reel`/`Carousel`; the Posts dataset adds `product_type` `clips`/`carousel_container`.
@@ -355,18 +206,6 @@ def ig_shortcode(url):
     return ""
 
 
-def _bd_first_url(v):
-    """A link-in-bio value → one string.
-
-    ⚠ MEASURED 2026-08-05: `external_url` is an **ARRAY** on the real row
-    (`["http://linktr.ee/utopianevents/"]`), not the string the previous vendor returned. A dict
-    (`external_url_title`) is also in the family. Read through the shape rather than assuming one.
-    """
-    if isinstance(v, list):
-        v = next((x for x in v if x), "")
-    if isinstance(v, dict):
-        v = _first(v, "url", "link", default="")
-    return str(v or "")
 
 
 def _bd_posts_count(node):
@@ -389,25 +228,8 @@ def _bd_posts_count(node):
     return None if v == 0 else v
 
 
-def _bd_flag(node, *names):
-    """A vendor boolean → `'1'` / `''` / None. **None when the key is ABSENT or null**, which is
-    the distinction that matters: `is_business_account: false` is a measurement and `''` records
-    it; a missing key is not, and must not arrive as "false"."""
-    for n in names:
-        v = node.get(n) if isinstance(node, dict) else None
-        if v is None:
-            continue
-        return "1" if v is True or str(v).strip().lower() in ("true", "1", "yes") else ""
-    return None
 
 
-def _bd_list(node, *names):
-    """An array field → a comma-joined string, or None when it is absent/empty."""
-    for n in names:
-        v = node.get(n) if isinstance(node, dict) else None
-        if isinstance(v, list) and v:
-            return ", ".join(str(x) for x in v if x)[:400]
-    return None
 
 
 def _bd_tagged_location(node):
@@ -432,28 +254,6 @@ def _bd_tagged_location(node):
     return ", ".join(parts)[:400] or None
 
 
-def _bd_source_payload(row):
-    """One complete Bright Data response row as valid JSON, without field filtering.
-
-    Source data is the lossless provider record, not a second relationship cache. A Profile's
-    embedded ``posts`` array stays here *and* each parseable post becomes a linked Post record;
-    keeping both preserves data while Links remain the interactive relational view. `bd_call`
-    rejects partial bodies at ``BD_SOURCE_PAYLOAD_MAX``, and the table-layer JSON ceiling matches
-    it, so this function never truncates a paid source response.
-    """
-    if not isinstance(row, dict):
-        return None
-    try:
-        packed = json.dumps({str(k): v for k, v in row.items()}, ensure_ascii=False,
-                            sort_keys=True, separators=(",", ":"))
-    except (TypeError, ValueError):
-        return None
-    # A source row is bounded by the complete raw HTTP response. Leave this defensive assertion
-    # explicit: should the transport ceiling and JSON-cell ceiling ever diverge, fail visibly
-    # rather than shortening a document and pretending every paid field was retained.
-    if len(packed.encode("utf-8")) > BD_SOURCE_PAYLOAD_MAX:
-        raise ValueError("a Bright Data source row exceeded the guarded response ceiling")
-    return packed
 
 
 def _bd_comment(row, influencer_key="", shortcode="", fallback_key=""):
@@ -717,153 +517,12 @@ def bd_true_posts_count(rows):
     return None
 
 
-def _bd_rows(payload):
-    """A vendor answer → the list of row dicts inside it, whatever envelope it arrived in.
 
-    MEASURED shapes: a bare list (`/v3/scrape`), NDJSON (already listified by `bd_call`), and
-    `{"data": [...]}` / `{"results": [...]}` on the snapshot reads. An unreadable envelope yields
-    NOTHING rather than a guess.
-    """
-    if isinstance(payload, list):
-        return [x for x in payload if isinstance(x, dict)]
-    if isinstance(payload, dict):
-        for k in ("data", "results", "records", "items"):
-            v = payload.get(k)
-            if isinstance(v, list):
-                return [x for x in v if isinstance(x, dict)]
-        return [payload] if payload else []
-    return []
-
-
-def _bd_deferral(payload):
-    """The snapshot id when the 'sync' endpoint DEFERRED, else ''.
-
-    ⛔ MEASURED 2026-08-05, AND IT IS THE TRAP OF THIS WHOLE RUNG. `/v3/scrape` is documented and
-    named as the synchronous call, and for a small batch it is — two profile URLs came back
-    inline. Give it more work and it answers **200** with no rows and a note instead:
-
-        {"snapshot_id": "sd_…", "message": "Your request is still in progress and cannot be
-         retrieved in this call. Use the provided Snapshot ID to track progress…"}
-
-    Read naively that is a 200 with a body, so a parser looking for "did it error?" sails past
-    it, `_bd_rows` wraps the envelope as ONE unusable row, and the caller reports that the vendor
-    returned nothing — **while a snapshot we have already been billed for sits on the account,
-    finishing, and is never collected.** That is the D-26 failure shape (paid work abandoned)
-    arriving through the success path.
-    ⚠ It is a TIME threshold, not a row count: 2 URLs answered inline, 6 and 10 deferred.
-    """
-    if isinstance(payload, dict) and payload.get("snapshot_id") and not payload.get("account"):
-        return str(payload["snapshot_id"])
-    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.
-
-    Sends the SYNC call and, when the vendor defers it (see `_bd_deferral`), **collects the
-    snapshot it handed back** rather than discarding it. One call carries many URLs, which is
-    what keeps the per-profile pacing floor from turning a 20-profile run into an hour.
-    """
-    requested_urls = [str(u) for u in (urls or []) if u]
-    payload, note = bd_call(BD_PATH_SCRAPE, {"dataset_id": dataset_id},
-                            body=[{"url": u} for u in requested_urls])
-    if note:
-        return [], note
-    sid = _bd_deferral(payload)
-    if not sid:
-        return _bd_rows(payload), ""
 
-    # --- THE DEFERRED PATH. Poll the scraper namespace (`sd_…` at `/datasets/v3/…` — crossing it
-    # with the corpus namespace is a flat 404 about a snapshot that is alive).
-    budget = BD_SCRAPE_WAIT if wait is None else float(wait)
-    waited = 0.0
-    while True:
-        # ⭐ 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)
-        waited += BD_SCRAPE_POLL
-    # ⛔ NAME THE SNAPSHOT. It has been paid for and it is still finishing; a note that said only
-    # "no rows" would throw away both the data and the way to get it.
-    if isinstance(deferred, list):
-        deferred.append({"snapshotId": sid, "datasetId": str(dataset_id),
-                         "urls": requested_urls})
-    return [], (f"the profile source deferred this batch to {sid} and it was not ready within "
-                f"{int(budget)}s — the records are collected, not lost; ask for a smaller batch "
-                f"or collect {sid} from the control panel")
+
 
 
 #: How many profile URLs ride in ONE `/datasets/v3/scrape` call.
@@ -890,8 +549,49 @@ PROFILE_BATCH_URLS = max(1, int(os.environ.get("AIOS_BD_PROFILE_BATCH") or 5))
 MAX_POST_WINDOW = int(os.environ.get("AIOS_IG_MAX_POST_WINDOW") or 60)
 
 
-def bd_profile_posts(handle, count, deferred=None, wait=None):
-    """A profile's LAST `count` posts via discover-by-url. `(rows, note)`.
+def _bd_mapped_posts(rows, raw_out=None):
+    """Posts-dataset rows -> our canonical post rows, drops what will not map.
+
+    ⚠ `raw_out` IS NOT A CONVENIENCE. `bd_true_posts_count` reads the vendor's profile-context
+    echo, which lives on the RAW row and is destroyed by mapping — so a caller that only kept the
+    mapped rows would lose the FREE `posts_count` read and fall through to the branch that BUYS a
+    record for it. The sink keeps a window route exactly as cheap as the per-permalink one it
+    replaces. Same shape as `deferred=` and `applied=` elsewhere in this module.
+
+    ⚠ `_bd_post_metrics`, the SAME mapper `pull_profile_bd` feeds its per-permalink reads through.
+    A window route with its own mapper would be a second answer to "which vendor key is `views`",
+    and this repo has already paid for one of those ([[one-question-two-normalizers]]).
+    """
+    out = []
+    for r in (rows or []):
+        if isinstance(raw_out, list) and isinstance(r, dict):
+            raw_out.append(r)
+        got = _bd_post_metrics(r) if isinstance(r, dict) else None
+        if got:
+            out.append(got)
+    return out
+
+
+def bd_profile_posts(handle, count, deferred=None, wait=None, post_type="", raw_out=None):
+    """A profile's LAST `count` posts via discover-by-url. `(rows, note)` — rows already MAPPED.
+
+    ⭐⭐ WAVE 30 · T16 (carried W29-T10) — `post_type` IS THE WHOLE FIX AND IT IS ONE KEY.
+    MEASURED 2026-08-10 on `@theresalearns`, same window, same hour, so no probability argument is
+    needed: this route WITHOUT the key returned **8 Reels + 3 Carousels** for a 12-post ask; WITH
+    `post_type="reel"` it returned **12/12**. Asking for "the last 12 reels" and being handed eight
+    is not a filter that under-delivers, it is a filter applied to the wrong set — the shortfall
+    scales with a creator's carousel share and nothing in the run says so.
+    ⚠ It is HONOURED, not silently ignored (the failure mode that looks like success): the returned
+    rows carry `content_type: "Reel"`. Same dataset, same route, same mapper, same price.
+    ⛔ **AND IT DOES NOT REVIVE VIEWS ON BRIGHT DATA.** This measured `product_type`, never `views`;
+    the Reels dataset stays type-capable and views-INCAPABLE ([[bd-reels-views-account-level]]).
+    Views still come from Apify. Conflating the two questions about one dataset cost a day once.
+
+    ⭐ ROWS ARE MAPPED HERE NOW, and that is the second half of why this had no caller. It returned
+    raw `_bd_rows()` — a vendor-shaped list every caller would have had to normalise itself, which
+    is a second mapper waiting to disagree with `_bd_post_metrics`. It is the boundary's job.
+
+    ⛔ A DIFFERENT ROUTE FROM `pull_profile`, AND THAT IS THE WHOLE POINT.
 
     ⛔ A DIFFERENT ROUTE FROM `pull_profile`, AND THAT IS THE WHOLE POINT. The profile record
     embeds at most 12 posts however many you ask for — measured, not assumed. This is the
@@ -906,16 +606,28 @@ def bd_profile_posts(handle, count, deferred=None, wait=None):
         n = max(1, min(int(count), MAX_POST_WINDOW))
     except (TypeError, ValueError):
         n = 12
+    _row = {"url": f"https://www.instagram.com/{ig_handle(handle) or handle}/",
+            "num_of_posts": n}
+    if str(post_type or "").strip():
+        # ⚠ SENT ONLY WHEN ASKED FOR. An unconditional `post_type: "post"` would change what every
+        # future caller buys, and the vendor's documented values are exactly `post` and `reel`.
+        _row["post_type"] = str(post_type).strip()
     payload, note = bd_call(BD_PATH_TRIGGER,
                             {"dataset_id": BD_DS_POSTS, "type": "discover_new",
                              "discover_by": "url"},
-                            body=[{"url": f"https://www.instagram.com/{ig_handle(handle) or handle}/",
-                                   "num_of_posts": n}])
+                            body=[_row])
     if note:
         return [], note
-    sid = _bd_deferral(payload) or str((payload or {}).get("snapshot_id") or "")
+    # ⛔ `isinstance`, NOT `(payload or {}).get(...)` — WAVE 30 · T16, and this is a crash that
+    # shipped because the function had no caller. The very next line handles the case where the
+    # vendor answered with ROWS INLINE instead of a snapshot id, so a list payload is an EXPECTED
+    # shape here; `.get` on it raises `AttributeError` before that line can run. Whole, correct-
+    # looking, unreachable code is not tested code — the first real caller found this in one run
+    # ([[artifact-with-no-importer]], the failure mode rather than the waste).
+    sid = _bd_deferral(payload) or (str(payload.get("snapshot_id") or "")
+                                    if isinstance(payload, dict) else "")
     if not sid:
-        return _bd_rows(payload), ""
+        return _bd_mapped_posts(_bd_rows(payload), raw_out), ""
     budget = BD_SCRAPE_WAIT if wait is None else float(wait)
     waited = 0.0
     while True:
@@ -929,7 +641,7 @@ def bd_profile_posts(handle, count, deferred=None, wait=None):
                 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, ""
+                    return _bd_mapped_posts(rows, raw_out), ""
         if waited >= budget:
             break
         time.sleep(BD_SCRAPE_POLL)
@@ -941,17 +653,12 @@ def bd_profile_posts(handle, count, deferred=None, wait=None):
                 f"{int(budget)}s — the records are collected, not lost")
 
 
-def select_post_groups(posts, groups):
-    """Keep the newest `limit` posts of each named TYPE. Returns the kept posts, newest first.
-
-    ⭐ 2026-08-09 (owner: *"not just last 12 but by group also"*). `groups` is
-    `[{"type": "video", "limit": 12}, {"type": "image", "limit": 6}]`. A type nobody named is
-    DROPPED, which is the point of a filter — asking for reels and getting carousels back is the
-    behaviour this replaces.
+def group_types(groups):
+    """`{type: limit}` for a stored `postGroups` value, ignoring anything malformed.
 
-    ⚠ NEWEST-FIRST BY `posted_at`, and a post with no date sorts LAST rather than first. A blank
-    date is not "just now"; ranking it as though it were would silently prefer exactly the rows we
-    know least about ([[sentinel-in-a-sort-key]] — partition, never rank a sentinel).
+    ⚠ ONE READER FOR THE STORED SHAPE. `select_post_groups` built this dict inline and the two
+    routing helpers below need the same answer; three copies of "what did the person ask for" is
+    how a filter and the read that feeds it end up disagreeing about the ask.
     """
     wanted = {}
     for g in (groups or []):
@@ -964,6 +671,45 @@ def select_post_groups(posts, groups):
             continue
         if t and lim > 0:
             wanted[t] = max(wanted.get(t, 0), lim)
+    return wanted
+
+
+def reels_only_limit(groups):
+    """The reel limit when the config asks for REELS AND NOTHING ELSE, else 0.
+
+    ⛔ THE TEST IS EXCLUSIVITY, NOT PRESENCE. "12 reels AND 6 images" cannot be served by a
+    single-type route — one request cannot express it — so a `video in wanted` test would send a
+    mixed ask down the reels-only branch and silently drop the images. That is the specialisation
+    trap: the narrow route is right only when the ask is narrow.
+    """
+    wanted = group_types(groups)
+    return wanted.get("video", 0) if set(wanted) == {"video"} else 0
+
+
+def group_window(groups):
+    """How many posts ONE wide read must return for every group to be fillable.
+
+    ⚠ THE SUM, then bounded by `MAX_POST_WINDOW`. A mixed ask is only satisfiable if the window is
+    at least as large as everything asked for, and the vendor's window is what actually limits it —
+    which is why the caller REPORTS a bound it could not meet rather than quietly returning fewer
+    (a short window reads downstream as "this creator posts less", which is a claim about them).
+    """
+    return min(sum(group_types(groups).values()), MAX_POST_WINDOW)
+
+
+def select_post_groups(posts, groups):
+    """Keep the newest `limit` posts of each named TYPE. Returns the kept posts, newest first.
+
+    ⭐ 2026-08-09 (owner: *"not just last 12 but by group also"*). `groups` is
+    `[{"type": "video", "limit": 12}, {"type": "image", "limit": 6}]`. A type nobody named is
+    DROPPED, which is the point of a filter — asking for reels and getting carousels back is the
+    behaviour this replaces.
+
+    ⚠ NEWEST-FIRST BY `posted_at`, and a post with no date sorts LAST rather than first. A blank
+    date is not "just now"; ranking it as though it were would silently prefer exactly the rows we
+    know least about ([[sentinel-in-a-sort-key]] — partition, never rank a sentinel).
+    """
+    wanted = group_types(groups)
     if not wanted:
         return list(posts or [])
     dated, undated = [], []
@@ -1116,6 +862,65 @@ def apify_posts(urls):
     return [r for r in rows if r], ""
 
 
+def apify_reels(handle, limit):
+    """A profile's LAST `limit` REELS, with view counts INLINE. `(rows, note)`.
+
+    ⭐⭐ WAVE 30 · T16 (carried W29-T11) — ONE CALL FOR WHAT CURRENTLY TAKES THREE.
+    MEASURED 2026-08-10 (`@theresalearns`): `resultsType: "reels"` + `resultsLimit: 12` returned
+    **12/12 `productType: clips`, every one carrying a distinct `videoPlayCount`** (2,113 →
+    418,232). The shipped path for the same answer is a Bright Data profile read, a client-side
+    type filter, and a SEPARATE per-permalink Apify `top_up_views` — three steps, two vendors, and
+    one request's worth of data.
+
+    ⛔ A NEW BRANCH, NEVER A RE-POINTING OF THE DEFAULT CHAIN. `ig_post_metrics` does not move and
+    Bright Data stays first for it; this is the specialisation for a single-type ask, and it is
+    reached only when the config's groups name reels and nothing else.
+    ⚠ ITS CALLER MUST NOT THEN RUN `top_up_views`. The views are already here; asking Apify again
+    per permalink would buy the same numbers twice, which is the shape a "top-up" is meant to
+    avoid rather than cause.
+    ⛔ THE ACTOR PAGE CONTRADICTS ITS OWN INPUT SCHEMA — the page says `resultsType` has no
+    `"reels"` value. It does; the response is the evidence ([[measure-the-real-call]]).
+    """
+    from automation_engine import Refused, fetch_json            # lazy — see the module header
+    h = ig_handle(handle) or str(handle or "").strip().lstrip("@")
+    if not h:
+        return [], "no handle to read reels for"
+    key = apify_key()
+    if not key:
+        return [], "AIOS_APIFY_KEY is not configured — the Apify rung is closed"
+    try:
+        n = max(1, min(int(limit), MAX_POST_WINDOW))
+    except (TypeError, ValueError):
+        n = 12
+    url = (f"{APIFY_BASE}/acts/{APIFY_ACTOR_POSTS}/run-sync-get-dataset-items"
+           f"?token={requests.utils.quote(key)}&timeout={int(APIFY_WAIT)}")
+    body = {"directUrls": [f"https://www.instagram.com/{h}/"], "resultsType": "reels",
+            "resultsLimit": n, "addParentData": False}
+    try:
+        status, raw = fetch_json(url, body, timeout=APIFY_WAIT + 60, max_kb=BD_MAX_KB)
+    except Refused as e:
+        return [], f"Apify's address was refused by the URL rail: {e}"
+    except Exception as e:                                          # noqa: BLE001
+        # ⚠ TYPE NAME ONLY — the token is in the query string of `url`.
+        return [], f"Apify did not answer ({type(e).__name__})"
+    if status == 402:
+        return [], "the Apify account is out of credit"
+    if status in (401, 403):
+        return [], f"Apify refused our key ({status})"
+    if status >= 400:
+        return [], f"Apify answered {status}"
+    try:
+        items = json.loads(raw.decode("utf-8", "replace"))
+    except Exception:                                               # noqa: BLE001
+        return [], "Apify's answer was not readable JSON"
+    if not isinstance(items, list):
+        return [], "Apify answered with something other than a list of items"
+    rows = [r for r in (providers.normalize_post_apify(x) for x in items) if r]
+    if not rows:
+        return [], "Apify answered with no reels for this profile"
+    return rows, ""
+
+
 def apify_profile(handle):
     """One handle -> (canonical profile | None, note). A note means it did NOT answer.
 
@@ -1408,7 +1213,7 @@ DEFERRED_MARK = "__aios_deferred_snapshot__"
 
 def pull_profile_bd(url, max_posts=None, post_metrics=False,
                     comment_metrics=False, log=print, pending_metrics=None,
-                    pending_profile=None, prefetch=None):
+                    pending_profile=None, prefetch=None, post_groups=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
@@ -1517,7 +1322,57 @@ def pull_profile_bd(url, max_posts=None, post_metrics=False,
         if got:
             posts.append(got)
 
-    if post_metrics and posts:
+    # ⭐⭐ WAVE 30 · T16 — THE WINDOW COMES BEFORE THE PRICE, WHICH IS WHY THIS SITS HERE AND NOT
+    # IN THE ENGINE. `select_post_groups` filters what we already bought, and what we already
+    # bought is the PROFILE's embed — at most 12 posts, MIXED. So "the last 12 reels" has been
+    # landing eight on a creator who posts carousels, forever, with a green run and a summary that
+    # says twelve. The engine's own comment named this and deferred it: *"widening belongs ahead of
+    # that step, in the paid path, and that is its own change"*. This is that change.
+    #
+    # ⛔ GATED ON `post_metrics`, DELIBERATELY. Both routes below BUY records. `post_metrics` is
+    # the switch that already means "I am paying per post"; widening without it would spend money
+    # on a run whose config says not to. ⚠ And when a group config cannot be honoured for that
+    # reason the run SAYS SO rather than filtering a window it knows is too narrow — a short answer
+    # that reads as a fact about the creator is the failure this note exists to prevent.
+    # ⚠ `rows2` IS INITIALISED HERE, not inside the metric block, and that is a defect this
+    # ticket introduced and caught in one run: the block that defines it is now SKIPPED when a
+    # window was bought, so `bd_true_posts_count(rows2 ...)` below raised `UnboundLocalError` on
+    # the new path. A name defined in a branch, read outside it, is a crash waiting for whoever
+    # adds the next branch.
+    rows2 = []
+    views_inline, window_bought, window_note = False, False, ""
+    if post_groups and not post_metrics:
+        window_note = ("post groups were configured but post data is switched off, so they filtered "
+                       "the profile's own preview (at most 12 mixed posts) rather than a window "
+                       "bought for them")
+    elif post_groups:
+        _reels_n = reels_only_limit(post_groups)
+        if _reels_n and apify_ready():
+            # ⭐ ONE CALL: last N reels WITH `videoPlayCount` inline. `views_inline` is what stops
+            # `top_up_views` buying the same numbers a second time, per permalink.
+            wide, wnote = apify_reels(handle, _reels_n)
+            if wide:
+                posts, views_inline, window_bought = wide, True, True
+            else:
+                window_note = f"the reels route did not answer ({_s(wnote, 90)})"
+        else:
+            # ⚠ THE FALLBACK IS NOT A DEGRADED COPY — for a reels-only ask it sends Bright Data's
+            # own `post_type: "reel"`, MEASURED at 12/12 where the unfiltered route gives 8. For a
+            # MIXED ask no single-type route exists, so it buys the SUM and lets
+            # `select_post_groups` keep N of each — which is the one path that clause still owns.
+            wide, wnote = bd_profile_posts(handle, group_window(post_groups),
+                                           post_type=("reel" if _reels_n else ""),
+                                           deferred=pending_metrics, raw_out=rows2)
+            if wide:
+                posts, window_bought = wide, True
+            else:
+                window_note = f"the post window was not readable ({_s(wnote, 90)})"
+
+    # ⛔ `not window_bought` IS THE DOUBLE-SPEND GUARD, and it is the whole reason the routes
+    # above return MAPPED rows. Both of them buy records that already carry likes, comments,
+    # captions and (on the Apify branch) views; re-reading the same permalinks below would pay
+    # twice for numbers already in hand — the exact thing a "top-up" exists to avoid causing.
+    if post_metrics and posts and not window_bought:
         time.sleep(min(PACE_SECONDS, 1.0))    # the vendor is paid, but it is still someone's API
         # Posts and Reels are different Bright Data endpoints. Sending every permalink to the
         # Posts endpoint was why Inayma's five video rows got likes/comments but no views: the
@@ -1525,7 +1380,7 @@ def pull_profile_bd(url, max_posts=None, post_metrics=False,
         # without duplicating any record, so enabling post metrics still buys one row per post.
         ordinary = [p for p in posts if p.get("type") != "video"]
         videos = [p for p in posts if p.get("type") == "video"]
-        rows2, metric_notes, ordinary_rows = [], [], []
+        metric_notes, ordinary_rows = [], []
         # `None` keeps direct callers backwards-compatible: they wait for their answer.  An
         # automation passes one run-level list, which makes a deferred metric batch durable and
         # lets this profile finish rather than parking the whole enrichment on it.
@@ -1589,7 +1444,18 @@ def pull_profile_bd(url, max_posts=None, post_metrics=False,
             elif metric_notes:
                 note = f"some post metrics were unavailable: {'; '.join(metric_notes)}"
 
+    # ⭐⭐ T16 — THE ONE PATH THAT LEGITIMATELY SKIPS THE VIEWS TOP-UP, and it is skipped because
+    # the numbers are already here rather than because nobody wants them. `apify_reels` returns
+    # `videoPlayCount` INLINE on every row; `top_up_views` would then buy the same figure again,
+    # per permalink, from the same vendor. Every other route still tops up — Bright Data's Reels
+    # dataset is MEASURED views-incapable, so a BD window is exactly as short of views as the
+    # profile embed was. ⚠ Lifted OUT of the per-permalink block on purpose: leaving it there
+    # would have silently dropped the top-up for a Bright Data WINDOW too, which is the quiet
+    # half-fix this comment exists to refuse.
+    if post_metrics and posts and not views_inline:
         note = "; ".join(x for x in (note, top_up_views(posts, log=log)) if x)
+    if window_note:
+        note = "; ".join(x for x in (note, window_note) if x)
 
     # ⭐⭐ DEBT D-82 (owner ruling R12: *"price, then wire the Posts-dataset call so posts_count
     # fills with the true value"*). The Profiles dataset's `posts_count: 0` is discarded as the
@@ -1665,243 +1531,29 @@ def pull_profile_bd(url, max_posts=None, post_metrics=False,
             "via": via,
             "note": note or ("" if posts else "profile read; no posts were returned")}
 
-#: ⛔ THE VENDOR'S HARD CAP ON ONE LOGICAL GROUP — MEASURED 2026-08-06 against the live filter API
-#: with nurilab's own seven-condition search, which had failed every run for two days:
-#:
-#:     400 {"validation_errors":["Filter logical groups can have a maximum of 4 rules."]}
-#:
-#: ⚠ EVERY ONE OF THOSE SEVEN CONDITIONS IS ACCEPTED ALONE (all seven probed individually, all
-#: 200). The refusal is about the SHAPE of the group and nothing else — so no field, operator or
-#: value in the builder is at fault, and no amount of editing the conditions would have found it.
-#: What it means without `bd_group` below: the FIFTH condition anybody adds turns a working
-#: discovery automation into one that fails forever, and the surface blames the search.
-BD_GROUP_MAX = 4
-
-
-def bd_group(nodes, operator):
-    """`nodes` → an equivalent list in which NO logical group exceeds `BD_GROUP_MAX` rules.
-
-    ⭐ SAFE BECAUSE AND AND OR ARE ASSOCIATIVE. Folding a run of same-operator rules into a nested
-    group of the SAME operator cannot change what the filter matches — `a∧b∧c∧d∧e` and
-    `(a∧b∧c∧d)∧e` are one predicate written two ways. That is why this is a re-SHAPING of the
-    owner's search rather than a reinterpretation of it, and why it needs no ruling: a condition
-    list means the same thing before and after. Nesting itself is already proven on this API
-    (`expand_predicates`' or-groups, `snap_msh14ix81n8hlpo3nr`).
-
-    ⛔ A ONE-RULE CHUNK IS NEVER WRAPPED. `expand_predicates` already carries that law for the
-    one-value case — a one-element group is a shape nothing has ever been billed against — and a
-    balanced split reaches it whenever a level divides with a remainder of one.
-    """
-    nodes = list(nodes or [])
-    if len(nodes) <= BD_GROUP_MAX:
-        return nodes
-    # ⚠ BALANCED, NOT "take three and nest the rest". The tail-recursive shape costs one level of
-    # DEPTH per extra rule (13 conditions ⇒ 5 deep) against a vendor whose nesting limit we have
-    # not measured and would discover the same way we discovered this one: in production, on
-    # somebody's automation. Chunking makes the depth log₄(n) — 16 conditions fit in two levels.
-    out = []
-    for i in range(0, len(nodes), BD_GROUP_MAX):
-        chunk = nodes[i:i + BD_GROUP_MAX]
-        out.append(chunk[0] if len(chunk) == 1 else {"operator": operator, "filters": chunk})
-    return bd_group(out, operator)
-
-
-#: ⛔ DEBT D-68 — THE VENDOR'S NESTING CEILING, MEASURED IN PRODUCTION 2026-08-06:
-#:     400 — "filter" failed custom validation because logical operators cannot be more than
-#:           3 levels deep
-#: ⭐ AND IT IS NOT AN INDEPENDENT BUDGET FROM `BD_GROUP_MAX`. A >4-rule group is fixed by
-#: NESTING, so the 4-rule cap is what MANUFACTURES depth: five top-level conditions carrying
-#: multi-value lists goes `AND`(split) → `OR`(values) → `OR`(split) and is refused. The real
-#: envelope is about 4 top-level conditions x <=4 values each, which is why
-#: `MAX_PREDICATE_VALUES = 12` was never reachable at a realistic condition count.
-BD_MAX_DEPTH = 3
-
-
-def filter_depth(node):
-    """How many logical levels a vendor `filters` structure nests to. A bare rule is depth 1."""
-    if isinstance(node, list):
-        return max((filter_depth(n) for n in node), default=0)
-    if isinstance(node, dict) and isinstance(node.get("filters"), list):
-        return 1 + filter_depth(node["filters"])
-    return 1
-
-
-def depth_refusal(predicates, operator="and"):
-    """⭐ D-68 — refuse a search whose SHAPE the vendor will reject, before it is sent.
-
-    Returns a sentence or `""`.
-
-    ⛔ WHY THIS CANNOT BE A RULE-COUNT CHECK. The failure is in the emitted STRUCTURE, not in the
-    conditions: the same five conditions pass or fail depending on how many VALUES each carries,
-    because every multi-value list becomes its own OR level and every group over `BD_GROUP_MAX`
-    adds a split level. So the only honest test is to BUILD the shape and measure it — which is
-    cheap, because we build it anyway.
-    ⚠ Free to get wrong at the vendor and expensive to diagnose there: a rejected filter is never
-    billed, but the 400 says nothing about which condition to drop, so a person edits keywords for
-    an afternoon while the shape stays identical. That is what this sentence exists to prevent.
-    """
-    try:
-        depth = filter_depth(bd_group(expand_predicates(predicates), operator or "and"))
-    except Exception:                                                 # noqa: BLE001
-        return ""                                # never block a save on this check's own bug
-    if depth <= BD_MAX_DEPTH:
-        return ""
-    multi = [p for p in (predicates or [])
-             if isinstance((p or {}).get("value"), (list, tuple)) and len(p["value"]) > 1]
-    hint = (f"drop one of the {len(multi)} multi-value conditions, or shorten its list"
-            if multi else "drop one condition")
-    return (f"this search nests {depth} levels deep and the provider allows "
-            f"{BD_MAX_DEPTH} — {hint}. Every extra condition beyond {BD_GROUP_MAX}, and every "
-            f"list of values, adds a level")
-
-
-def expand_predicates(predicates):
-    """Stored predicates → the vendor's `filters` list, expanding a value LIST into a nested OR.
-
-    ⭐ MEASURED 2026-08-06: the filter API ACCEPTS a nested `{operator, filters:[…]}` inside
-    `filters` (`snap_msh14ix81n8hlpo3nr`), which is what makes "Bio contains any of floral,
-    flower, beauty" expressible WITHOUT setting the whole search to "match any". The alternative
-    — the global Match dropdown — would drag every other condition into the same union, so
-    "…and at least 10,000 followers" would silently become "…or at least 10,000 followers".
-
-    ⛔ A ONE-VALUE CONDITION IS STILL SENT FLAT. Wrapping it in a one-element group would be a
-    shape nothing has ever been billed against, adopted for tidiness, on the path that spends
-    money. Only the several-values case takes the new shape.
-    """
-    out = []
-    for p in predicates or []:
-        v = (p or {}).get("value")
-        if isinstance(v, list) and len(v) > 1:
-            # ⚠ THE OR-GROUP IS SUBJECT TO THE SAME 4-RULE CAP as the outer one, and this is the
-            # leg that hits it first in practice: "Bio contains any of floral, flower, beauty,
-            # bouquet, wedding" is five keywords in ONE condition — a single row in the builder,
-            # and a group the vendor refuses. `bd_group` is applied to the union too.
-            out.append({"operator": "or",
-                        "filters": bd_group(
-                            [{"name": p["name"], "operator": p["operator"], "value": one}
-                             for one in v], "or")})
-        elif isinstance(v, list):
-            out.append({**p, "value": v[0]} if v else
-                       {k: val for k, val in p.items() if k != "value"})
-        else:
-            out.append(dict(p))
-    return out
 
 
-#: ⛔ HOW MANY HANDLES ONE `not_in` MAY CARRY. W25/R1b MEASURED that the vendor accepts a flat
-#: `account not_in [...]` list to this size — *"the 12-value ceiling was OURS, not theirs"*. It is
-#: also why the rule below is built BY HAND instead of going through `expand_predicates`: that
-#: function turns any multi-value predicate into a nested OR of one-value rules, which for 5,000
-#: handles would be a 5,000-rule tree the vendor refuses on both its caps at once.
-BD_EXCLUDE_MAX = 5000
-
-
-def bd_filter_start(predicates, operator="and", records_limit=5, dataset_id=BD_DS_PROFILES,
-                    exclude_handles=(), applied=None):
-    """Start ONE corpus query. Returns `(snapshot_id, note)`.
-
-    ⚠ ALWAYS THE COMPOUND `{operator, filters:[…]}` SHAPE, even for a single condition. A bare
-    `{name, operator, value}` is a plausible-looking second shape that has never been sent from
-    here, and a one-element `filters` list is a trivial extension of the three-element body that
-    HAS been measured end-to-end. One shape, and it is the tested one.
-
-    ⭐⭐ WAVE 27 ITEM 7 — `exclude_handles` IS THE ENGINE'S OWN REFINEMENT AND IS NEVER A CONDITION
-    ROW. Until now discovery paid for every re-found profile: a nightly search over the same
-    keywords returns the same accounts, the upsert notices they are `seen_again`, and the vendor
-    has already billed for all of them. This narrows the search at the VENDOR instead of after it.
-    It is invisible to the condition builder deliberately (W25/R1b: `not_in` is an engine-added
-    refinement, and `BD_OPS_BY_KIND` omits it so nobody can type one) — a person did not write it,
-    should not have to maintain it, and would be confused by a condition that changes every night.
-
-    ⛔ AND IT IS DROPPED RATHER THAN RISKED. Two ways a free saving could break a search that
-    works, and both are checked before the body is sent:
-      1. **DEPTH.** The vendor allows 3 logical levels and the 4-rule group cap MANUFACTURES
-         depth, so a search already near the ceiling gains a level from this rule and starts
-         answering 400 forever ([[bright-data-group-cap]]).
-      2. **`or`.** Under a top-level OR, adding an exclusion as another branch would WIDEN the
-         search to "…or any account not in this list" — i.e. the whole corpus. Under OR the
-         existing filter is wrapped in an AND instead, which costs the level checked in (1).
-    A dropped exclusion is not an error: the search runs exactly as it did before and we pay for
-    the duplicates, which is the status quo, not a regression.
-    """
-    nodes = bd_group(expand_predicates(predicates), operator)
-    filt = {"operator": operator, "filters": nodes}
-    handles = [str(h).strip().lstrip("@").lower() for h in (exclude_handles or [])]
-    handles = [h for h in dict.fromkeys(handles) if h][:BD_EXCLUDE_MAX]
-    if isinstance(applied, dict):
-        applied["available"] = len(handles)
-        applied["excluded"] = 0
-    if handles:
-        rule = {"name": "account", "operator": "not_in", "value": handles}
-        cand = (bd_group([*nodes, rule], "and") if operator == "and"
-                else [filt, rule])
-        if filter_depth(cand) <= BD_MAX_DEPTH:
-            filt = {"operator": "and", "filters": cand}
-            if isinstance(applied, dict):
-                applied["excluded"] = len(handles)
-        elif isinstance(applied, dict):
-            applied["dropped"] = ("the search is already at the provider's nesting ceiling, so "
-                                  "the already-found list was left off rather than risk it")
-    body = {"dataset_id": dataset_id, "records_limit": int(records_limit),
-            # ⭐ `bd_group` — the top-level group obeys the vendor's 4-rule cap (see its note).
-            # Applied HERE rather than inside `expand_predicates` so the expansion stays a pure
-            # stored-shape → wire-shape translation and the rebalance is one readable step on the
-            # one path that actually posts a filter.
-            "filter": filt}
-    payload, note = bd_call(BD_PATH_FILTER, body=body)
-    if note:
-        return "", note
-    sid = str((payload or {}).get("snapshot_id") or "") if isinstance(payload, dict) else ""
-    if not sid:
-        return "", "the search was accepted but came back with nothing to collect it from"
-    return sid, ""
 
 
-def bd_filter_status(snapshot_id):
-    """`(status, size, note)` for a corpus snapshot. `status` ∈ building | ready | failed | ''."""
-    payload, note = bd_call(f"{BD_PATH_FILTER_SNAPSHOT}/{snapshot_id}")
-    if note:
-        return "", 0, note
-    d = payload if isinstance(payload, dict) else {}
-    status = str(d.get("status") or "")
-    err = str(d.get("error") or "")
-    if status == "failed" and "did not match any records" in err.lower():
-        # ⭐ MEASURED 2026-08-06 (`snap_msh14ix81n8hlpo3nr`): a filter that matches NOTHING comes
-        # back `failed` — "Provided filter did not match any records" — not `ready` with zero
-        # rows. Passed through, that reached the customer as "the search failed", which is the
-        # single most likely outcome of typing a keyword that is too specific and the one most
-        # certain to be read as "the product is broken". It is an ANSWER, so it gets its own
-        # status and no error note.
-        return "empty", 0, ""
-    if status == "failed" and err:
-        # NOT_ENOUGH_FUNDS is the one everybody will hit; say what it means, not just its name.
-        extra = (" — the matched set is too large for this account's balance; narrow the "
-                 "conditions or lower the limit" if "FUNDS" in err.upper() else "")
-        return status, 0, f"the search failed: {err}{extra}"
-    return status, int(d.get("dataset_size") or 0), ""
-
-
-def bd_filter_rows(snapshot_id):
-    """The rows of a READY corpus snapshot. `(rows, note)`.
-
-    ⚠ `/download` answered *"Snapshot is building. Try again in a few minutes"* while the status
-    endpoint ALREADY said `ready` — delivery lags readiness by minutes. So a download that does
-    not parse as rows is reported as not-yet-collectable rather than as an error.
-    """
-    payload, note = bd_call(f"{BD_PATH_FILTER_SNAPSHOT}/{snapshot_id}/download",
-                            {"format": "json"})
-    if note:
-        return [], note
-    rows = _bd_rows(payload)
-    if not rows:
-        return [], "the search is ready but its rows are not downloadable yet — the vendor's " \
-                   "delivery lags its own `ready` status by minutes"
-    return rows, ""
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 def pull_profile(url, max_posts=None, log=print,
                  post_metrics=False, comment_metrics=False, pending_metrics=None,
-                 pending_profile=None, prefetch=None):
+                 pending_profile=None, prefetch=None, post_groups=None):
     """Everything readable about one public profile — EXACT NUMBERS OR NOTHING.
 
     Returns `{state, profile, posts, via, note}` with state ∈ ok | partial | blocked | error.
@@ -1943,7 +1595,8 @@ def pull_profile(url, max_posts=None, log=print,
     paid = pull_profile_bd(url, max_posts=max_posts, post_metrics=post_metrics,
                            comment_metrics=comment_metrics, log=log,
                            pending_metrics=pending_metrics,
-                           pending_profile=pending_profile, prefetch=prefetch)
+                           pending_profile=pending_profile, prefetch=prefetch,
+                           post_groups=post_groups)
     if paid["state"] in ("ok", "partial"):
         return paid
     # ⚠ 200, NOT 90. This string is the ONLY account of what the vendor said, and at 90 the

api/connectors_tt.py

@@ -16,13 +16,15 @@ name below reads through a candidate list it is because the vendor has two names
 public data through a supplier, exactly the rail `connectors_ig.py` states for Instagram. The
 vendor key is a key to a SUPPLIER.
 
-⚠ **THE TRANSPORT IS BORROWED FROM `connectors_ig`, ON PURPOSE.** `bd_call`, `bd_scrape` and
+⭐ **THE TRANSPORT IS `connectors_bd.py` — SHARED, VENDOR-NAMED, AND NO LONGER BORROWED FROM THE
+OTHER PLATFORM'S CONNECTOR** (WAVE 30 · T09, DEBT D-128). `bd_call`, `bd_scrape` and
 `bd_filter_start` take the dataset id as a PARAMETER — they are Bright Data's wire, not
-Instagram's — so re-implementing them here would be a second copy of the deferral handling, the
+Instagram's — and re-implementing them here would be a second copy of the deferral handling, the
 truncation guard, the SSRF rail and the snapshot-progress reader, i.e. five places for one bug.
-The name is wrong and the code is right; extracting a `connectors_bd` transport module is booked
-as a PENDING line in B's mailbox rather than done mid-wave, because moving those functions would
-land in the middle of three other tickets' diffs.
+Until wave 30 the code was right and the NAME was wrong: this file imported thirteen symbols from
+`connectors_ig`, which read as a dependency on Instagram and was really a dependency on a supplier.
+⚠ **This file now imports ZERO names from `connectors_ig`, and a gate check asserts that**, because
+the sentence above is the kind that quietly stops being true.
 
 ⚠ **WHAT $0 COULD NOT BUY, so nobody reads this file as more measured than it is:**
   1. the real ROW shape — `/metadata` describes a DATASET, and Instagram's rows carry undeclared
@@ -34,17 +36,18 @@ land in the middle of three other tickets' diffs.
 from __future__ import annotations
 
 import automation_engine as engine
-from connectors_ig import (  # noqa: F401  (bd_call/bd_scrape are re-exported for the runners)
+# ⚠ T09 — FOUR NAMES CAME OFF THIS LIST AND NOTHING BROKE, which is the point of deriving an
+# import block from the AST both ways. `bd_call`, `bd_filter_start`, `bd_key` and `bd_ready` were
+# imported here under a comment claiming they were *"re-exported for the runners"*; no runner ever
+# read them off this module (the engine imports them from the transport itself), so they were four
+# lines of dependency nobody was paying for. `[[artifact-with-no-importer]]` in its smallest form.
+from connectors_bd import (
     _bd_first_url,
     _bd_flag,
     _bd_list,
     _bd_source_payload,
     _first,
     _ig_int,
-    bd_call,
-    bd_filter_start,
-    bd_key,
-    bd_ready,
     bd_scrape,
 )
 
@@ -291,3 +294,227 @@ TT_NORMALIZERS = {
     "tt_post_metrics": normalize_post,
     "tt_comments": normalize_comment,
 }
+
+
+# ---------------------------------------------------------------------------------------------
+# THE FETCH — wave 30 · W30-T08 (carrying wave-29's dropped T05)
+# ---------------------------------------------------------------------------------------------
+
+def tt_handle(url):
+    """A TikTok profile URL **or** a bare handle → the handle. `''` when it is neither.
+
+    Deliberately permissive about the input and strict about the output, because the two callers
+    hand it different things: an automation stores whatever a person typed in the profile column
+    (`@nurilab`, `nurilab`, or the full URL), while the discovery runner already holds a clean
+    `account_id`. One normaliser, so a row found by discovery and a row typed by hand cannot
+    resolve to two different handles.
+    """
+    s = str(url or "").strip()
+    if not s:
+        return ""
+    if "tiktok.com" in s.lower():
+        # Everything after the first `@`, up to the next path segment or query.
+        tail = s.split("@", 1)[1] if "@" in s else ""
+        s = tail.split("/")[0].split("?")[0].split("#")[0]
+    s = s.strip().lstrip("@").strip()
+    # A handle is the vendor's `account_id` shape: alphanumerics, dots and underscores.
+    return s if s and all(c.isalnum() or c in "._" for c in s) else ""
+
+
+def tt_post_urls(node, limit=0):
+    """⭐ WAVE 30 · T10 — the profile row's own post permalinks, newest-first as the vendor sends.
+
+    ⛔ THIS IS WHY TIKTOK POST CAPTURE COSTS NO EXTRA DISCOVERY. The probe measured `top_videos` as
+    *"an array of video permalinks, NO empties"* on the PROFILE row we have already bought — so the
+    posts read is a scrape of URLs we hold, never a search for them. The two TikTok DISCOVERY
+    datasets (posts-by-profile, posts-by-keyword) are **404 for our key**, so a design that reached
+    for either would not merely be dearer, it would not work.
+
+    ⚠ `top_posts_data` is deliberately NOT read: the probe calls it *"a thin dup of `top_videos`"*,
+    and preferring whichever happened to be longer is how one creator's window silently differs
+    from another's.
+    ⚠ `limit <= 0` means "everything the row carried". The CAP IS THE CALLER'S — `config.maxPosts`,
+    validated 1..12 — and it is applied here rather than after the scrape so an unwanted post is
+    never bought. [[a-constant-two-features-share]]: the 12 is the vendor's measured profile window,
+    not a number this function may invent.
+    """
+    raw = (node or {}).get("top_videos")
+    out = []
+    for item in raw if isinstance(raw, list) else []:
+        # The array is documented as permalinks; a vendor that starts sending objects instead must
+        # degrade to "no posts", never to a URL built out of a guess.
+        u = str(item.get("url") or "").strip() if isinstance(item, dict) else str(item or "").strip()
+        if u.lower().startswith("http") and u not in out:
+            out.append(u)
+    return out[:limit] if limit and limit > 0 else out
+
+
+def pull_posts_tt(post_urls, log=print, deferred=None):
+    """The TikTok Posts dataset for a list of permalinks → `(rows, note)`, already normalised.
+
+    ⚠ ONE CALL FOR THE WHOLE WINDOW. `bd_scrape` has always taken a list, and the Instagram side
+    measured what happens when a caller forgets: 25 records, one billed snapshot each, a walk still
+    running at 67 minutes. Nothing here loops per URL.
+    """
+    urls = [str(u) for u in (post_urls or []) if str(u or "").strip()]
+    if not urls:
+        return [], ""
+    rows, note = bd_scrape(TT_DS_POSTS, urls, deferred=deferred)
+    if note:
+        log(f"[aios-tt] posts: {note}")
+        return [], note
+    out = [r for r in (normalize_post(n) for n in rows) if r]
+    return out, ""
+
+
+def pull_comments_tt(post_urls, log=print, deferred=None):
+    """The TikTok Comments dataset for a list of POST permalinks → `(rows, note)`, normalised.
+
+    ⛔ THE MOST EXPENSIVE THING THIS PRODUCT BUYS, and the reason `commentMetrics` defaults OFF on
+    both networks: a comments scrape ingests identifiable third parties who never entered anybody's
+    list (D-24). The mapper already keeps every commenter field in `source_payload` and promotes
+    none of them to a column; this function adds no new exposure, it just has to be asked for.
+    """
+    urls = [str(u) for u in (post_urls or []) if str(u or "").strip()]
+    if not urls:
+        return [], ""
+    rows, note = bd_scrape(TT_DS_COMMENTS, urls, deferred=deferred)
+    if note:
+        log(f"[aios-tt] comments: {note}")
+        return [], note
+    out = [r for r in (normalize_comment(n) for n in rows) if r]
+    return out, ""
+
+
+#: ⭐⭐ WAVE 30 · D-156 — THE MEDIA DATASETS, AS A SET, SO THE HAND-OFF CAN FILTER ON IDENTITY.
+#: `_media_deferrals` uses this to lift ONLY posts/comments snapshots out of the local deferral
+#: list. That is what makes it structurally impossible to file a PROFILE snapshot in the engine's
+#: metric queue — the defect a draft of T10 shipped and A-39 booked as "the wrong fix is worse
+#: than the gap". A membership test cannot be got wrong by a later edit the way `if` order can.
+TT_MEDIA_DATASETS = (TT_DS_POSTS, TT_DS_COMMENTS)
+
+
+def _media_deferrals(deferred):
+    """The POSTS/COMMENTS entries of a `bd_scrape` deferral list — never the profile's.
+
+    ⚠ The engine, not this module, decides what a deferral MEANS: it stamps `kind` and the
+    handle and files it. TikTok needs no `_tag_metric_deferrals` twin because one dataset is one
+    kind here, so the id already carries everything a mapper choice depends on — and importing
+    Instagram's tagger is not available anyway (W30-T09 gates ZERO `from connectors_ig` lines).
+    """
+    out = []
+    for d in deferred or []:
+        if isinstance(d, dict) and str(d.get("datasetId") or "") in TT_MEDIA_DATASETS:
+            out.append(dict(d))
+    return out
+
+
+def pull_profile_tt(url, log=print, pending_profile=None, prefetch=None,
+                    max_posts=0, post_metrics=False, comment_metrics=False):
+    """ONE TikTok profile from the vendor. Same return contract as `pull_profile`.
+
+    `{state, profile, posts, comments, via, note}` with `state ∈ ok | partial | blocked | error`,
+    so the engine's enrich branch treats every network identically and no caller learns a new
+    shape.
+
+    ⭐ WAVE 30 · T10 — POSTS AND COMMENTS ARE REAL NOW, AND BOTH DEFAULT OFF, exactly as Instagram's
+    do. `post_metrics` scrapes the profile row's own `top_videos` permalinks (see `tt_post_urls` —
+    no discovery call, because both TikTok discovery datasets 404 for our key); `comment_metrics`
+    then scrapes the comments of the posts that came back. ⚠ COMMENTS REQUIRE POSTS by construction
+    rather than by a rule: their input IS a post permalink, so asking for comments with post capture
+    off is a request with no subject, and it returns none instead of quietly buying posts nobody
+    asked for.
+
+    ⛔ `partial` IS THE SUCCESS STATE WHENEVER NO MEDIA WAS READ, and that is deliberate rather than
+    pessimistic. The Instagram contract reads `ok` only when identity AND media both landed
+    (`pull_profile_bd`: *"identity without media is still partial ... a run that wrote a follower
+    count and no posts must not paint green over a posts table that did not grow"*). So: posts not
+    ASKED for → `partial`, saying so; posts asked for and landed → `ok`; asked for and none came →
+    `partial` with the vendor's reason. The state answers "did this pull deliver what it went for",
+    never "did the function finish".
+
+    ⚠ **NO FREE RUNG, AND NO FALLBACK CHAIN.** Instagram's `pull_profile` drops to Apify when the
+    paid rung refuses; `providers.DEFAULT_CHAINS["tt_profile"]` is deliberately single-provider,
+    with its own note explaining that a multi-provider chain is a promise something walks it and
+    that nothing walks Instagram's second name today either. So a refusal here is final, and it
+    says so instead of implying a retry somewhere.
+    """
+    handle = tt_handle(url)
+    if not handle:
+        return {"state": "error", "profile": {}, "posts": [], "comments": [], "via": "",
+                "note": f"{url!r} is not a TikTok profile URL or handle"}
+
+    # ⭐ THE BATCH FAST PATH, same shape as the Instagram side: `prefetch` is `{handle: node}` from
+    # one multi-URL scrape covering a whole selection. A hit is a vendor round trip that does not
+    # happen; a miss falls through to the single-URL call below.
+    cached = prefetch.get(handle) if isinstance(prefetch, dict) else None
+    _deferred = []
+    if isinstance(cached, dict) and cached:
+        rows, note = [cached], ""
+    else:
+        rows, note = bd_scrape(TT_DS_PROFILES, [tt_profile_url(handle)], deferred=_deferred)
+
+    node = rows[0] if rows else {}
+    profile = normalize_profile(node, handle) if node else {}
+    # ⛔ THE READABILITY TEST IS `followers`/`following`, NOT "did we get a dict". `normalize_profile`
+    # drops blanks, so an unreadable row still returns `{"platform": …, "handle": …}` — truthy, and
+    # carrying nothing anybody asked for. The Instagram rung tests exactly this pair for exactly
+    # this reason, and answering "0 followers" instead is the failure it exists to prevent.
+    unreadable = profile.get("followers") is None and profile.get("following") is None
+    if note or unreadable:
+        # ⭐ THE DEFERRAL IS HANDED OVER RATHER THAN DISCARDED. A snapshot the vendor is still
+        # building HAS ALREADY BEEN PAID FOR; dropping its id bills again on the next run for the
+        # same record. That was live on the Instagram profile path until 2026-08-09 — measured on
+        # nurilab as two runs, two fresh snapshots, both abandoned — and it is not being
+        # reintroduced here by omission.
+        if isinstance(pending_profile, list):
+            for d in _deferred:
+                pending_profile.append({**d, "kind": "profile", "influencer": handle})
+        why = note or ("the scrape answered, but no follower/following counts were readable in it "
+                       "(the field names may have moved - see tiktok-capture.md)")
+        return {"state": "blocked", "profile": {}, "posts": [], "comments": [], "via": "brightdata",
+                "deferredProfile": [d.get("snapshotId") for d in _deferred],
+                "note": why}
+
+    # --- W30-T10: THE MEDIA, ONLY WHEN IT WAS ASKED FOR. ------------------------------------
+    if not post_metrics:
+        return {"state": "partial", "profile": profile, "posts": [], "comments": [],
+                "via": "brightdata",
+                "note": note or "profile read; post capture is off for this step"}
+    urls = tt_post_urls(node, limit=max_posts)
+    if not urls:
+        # ⚠ NOT AN ERROR AND NOT A RETRY. A creator with no `top_videos` has nothing to buy, and
+        # saying so is what stops the next run paying to be told the same thing.
+        return {"state": "partial", "profile": profile, "posts": [], "comments": [],
+                "via": "brightdata",
+                "note": note or "profile read; this account's row carried no post links"}
+    posts, p_note = pull_posts_tt(urls, log=log, deferred=_deferred)
+    comments, c_note = ([], "")
+    if comment_metrics and posts:
+        # The comments dataset is keyed on a POST permalink, so it reads the posts we just bought —
+        # `url` from the mapper, never the profile's raw array, so a post the posts scrape refused
+        # is not silently asked about again one rung later.
+        comments, c_note = pull_comments_tt([p.get("url") for p in posts if p.get("url")],
+                                            log=log, deferred=_deferred)
+    # ⭐⭐ WAVE 30 · D-156 — THE MEDIA DEFERRALS ARE HANDED BACK, and the shape of the hand-off is
+    # the whole lesson. An earlier draft of T10 appended every `_deferred` entry to
+    # `pending_profile` tagged `kind: "profile"`. By the time control reaches here a PROFILE
+    # deferral is impossible — the profile branch above returns `blocked` on any note — so **every
+    # id fanned out that way was a POSTS or COMMENTS snapshot in the PROFILE queue**, whose
+    # collector writes preset profile cells onto somebody's record from post rows. The engine keeps
+    # the two queues apart deliberately (`_pending_profile_tasks` vs `_pending_metric_tasks`).
+    # ⇒ So this returns them under their OWN key, filtered by dataset identity
+    # (`_media_deferrals`), and the engine files them in the metric queue with the handle it
+    # already holds. Returning rather than appending also keeps the queue's vocabulary out of a
+    # connector: this module knows which CORPUS deferred, never what the engine calls it.
+    # ⚠ `deferredMedia` rides BOTH returns on purpose. The empty-posts case is the one that
+    # matters most — that is exactly the run where the vendor took too long, so a caller reading
+    # the ids only from the success path would lose every batch it actually paid for.
+    deferred_media = _media_deferrals(_deferred)
+    if not posts:
+        return {"state": "partial", "profile": profile, "posts": [], "comments": [],
+                "via": "brightdata", "deferredMedia": deferred_media,
+                "note": p_note or note or "profile read; the post source returned nothing"}
+    return {"state": "ok", "profile": profile, "posts": posts, "comments": comments,
+            "via": "brightdata", "deferredMedia": deferred_media,
+            "note": c_note or note or ""}

api/main.py

@@ -534,6 +534,15 @@ def _prewarm():
         routes_customers.warm_default(rt)
         import pages as _pages
         _pages.warm_default(rt)
+        # ⭐⭐ WAVE 30 · T12, THE COLD PATH (owner items 4/5). Automation was the ONE module absent
+        # from this list, so its memo was always filled by a visitor rather than by boot: call 1 of
+        # `GET /automations` after every deploy downloaded the whole `user_tables` document (35.8 MB
+        # ceiling, under the store lock) onto whoever clicked first. Memoising the WARM path — two
+        # waves of it — could not touch that, because the cold call is the one that fills the memo.
+        # ⚠ It elects a STRING and keeps no document; see `warm_default`'s own note on why caching
+        # the bucket would trade a latency for memory this tier does not have.
+        import routes_automation as _rauto
+        _rauto.warm_default(rt)
         print(f"[aios-api] prewarm done in {_t.time() - t0:.1f}s")
     except Exception as e:                                    # noqa: BLE001 — boot must not die on a warm-up
         print(f"[aios-api] prewarm skipped: {e}")

api/odoo_relational.py

@@ -57,15 +57,33 @@ PRODUCTS_KEY = "ut_odoo_products"
 #: ⭐ WAVE 28 (owner R1): *"ALL of Unique ID in Odoo is a database e.g. Customers/Products/Agents,
 #: etc. Including expenses and GL codes."* Four more DOCUMENT/REGISTRY grains, each measured to
 #: fit far inside `MAX_ROWS` (19 / 192 / 6,538 / 393 against 60,000).
-#: ⛔ THE LINE GRAINS ARE DELIBERATELY NOT HERE and this is R2, not an omission: 256,810 order
-#: lines, 154,917 expense GL lines and 311,140 commission lines cannot live in a `ut_*` document
-#: at any cap (63.9 MB / 2.57 s per copy for the order lines alone). "Expenses" as a BROWSABLE
-#: LEDGER is a read-through mirror grid; "expenses" as a NUMBER is a rollup on the GL account row.
 AGENTS_KEY = "ut_odoo_agents"
 ACCOUNTS_KEY = "ut_odoo_accounts"
 BILLS_KEY = "ut_odoo_bills"
 VENDORS_KEY = "ut_odoo_vendors"
 
+#: ⭐⭐ WAVE 30 / R7 / W30-T35 — THE TWO LINE GRAINS, AND THEY ARRIVE THE ONLY WAY THEY EVER COULD.
+#:
+#: ⚠ THE PARAGRAPH THAT STOOD HERE SAID THESE WERE "DELIBERATELY NOT HERE … at any cap", and it
+#: was RIGHT ABOUT THE CAP AND WRONG ABOUT THE CONCLUSION — which is exactly why it is replaced
+#: rather than left standing beside its own contradiction. The obstacle was never the number of
+#: rows; it was that every row had to be COPIED into the shared `user_tables` document. MEASURED
+#: on this box's mirror 2026-08-12: 254,189 order lines in the confirmed scope (256,810 unscoped)
+#: and 963,783 GL lines — 4.2x and 16x `MAX_ROWS`, 63.9 MB and ~240 MB as JSON. Owner ruling R6
+#: settles what that means: *"there is no cap in how many data from the API source … can be pulled
+#: into the app"*, so the answer is a different residency, never a bigger ceiling.
+#:
+#: ⛔ THESE TWO TABLES STORE NO ROWS HERE AND NEVER WILL. `routes_odoo_tables` binds them to the
+#: DuckDB mirror (`GRID_SOURCES`) and `core.user_tables.row_limit` answers **0** for them — "this
+#: database stores no rows HERE", which is a different statement from `None` ("connected and
+#: uncapped") and from `MAX_ROWS` ("the editable substrate"). `plan()` below reads that evaluator
+#: and builds no python row for either grain: 963,783 dicts in one process is the dangerous work
+#: the answer exists to prevent. What DOES get written is the DEFINITION — a locked database with
+#: fields, a label, grants and a nav entry, and zero rows. A definition with no rows is a working
+#: grid; that is the whole shape of the conversion.
+ORDER_LINES_KEY = "ut_odoo_order_lines"
+GL_LINES_KEY = "ut_odoo_gl_lines"
+
 #: The join column the partner-grain tables carry. Derived links resolve through it (`on`/`from`).
 JOIN_KEY = "partner_id"
 #: The product-grain equivalent.
@@ -352,6 +370,150 @@ def order_fields():
     )]
 
 
+# ═════════════════════════════════════════════════════════════════════════════════════════════
+# THE TWO READ-THROUGH GRAINS (W30-T35). Their rows are SERVED FROM THE MIRROR, never stored.
+# ═════════════════════════════════════════════════════════════════════════════════════════════
+# ⛔⛔ THE KEY SET IS HALF OF A CONTRACT AND `routes_odoo_tables.GRID_SOURCES[…]["cols"]` IS THE
+# OTHER HALF. It binds a key to SQL; the label, type and order are declared HERE, once. The two
+# lists must name the SAME columns, and both failure directions are silent:
+#   * a bound key with no declaration -> a silent NO-CELL (the row projection is strict);
+#   * a declared key with no binding  -> an INACTIVE filter leaf, which WIDENS the result set.
+# `verify_scopes.section_line_grids` compares the two sets, which is why neither side may "just
+# add a column".
+#
+# ⛔ NO LINK COLUMN AND NO `refreshed` STAMP ON EITHER TABLE, and both absences are findings
+# rather than omissions:
+#   * a LINK folds the rows the TARGET table STORES (`compute_relation_cells` reads the raw
+#     document, not the mirror), so a link at a read-through grain resolves against nothing and
+#     renders a permanently blank column — the trap `account_fields` names from the other end.
+#     The join ids ride as ordinary filterable columns instead, so the relationships are all
+#     still reachable by a person and by SQL.
+#   * `refreshed` means "when this row was last reconciled against Odoo", and it is stamped by
+#     `_ensure_table_inplace` onto rows it WRITES. Nothing here is ever written, so the column
+#     would be blank for every row forever. `section_line_grids` tolerates the key; the honest
+#     thing is not to declare it.
+
+
+def order_line_fields():
+    """One row per `sale.order.line` on a CONFIRMED order — the same `state in (sale, done)`
+    scope every wholesale metric in this product uses.
+
+    MEASURED on the mirror 2026-08-12: **254,189 lines in scope** of 256,810 (the 2,621 excluded
+    sit on draft/sent/cancelled orders). Every line in scope is on a `sale` order — zero `done` —
+    but `done` stays in the option list because it is in the SCOPE, and a filter offering only
+    what happens to be stored today goes stale the first time an order is marked done.
+
+    ⛔ THE SCOPE, THE ORDER DATE AND THE ORDER NAME ALL LIVE ACROSS A JOIN. `sale_order_line`
+    carries no `state` at all (12 columns, measured), so the binding is a join to `sale_order` —
+    which is also what makes `order_no` a readable primary cell instead of a line id.
+
+    ⚠ `qty` IS `int`, NOT `currency`, AND THAT IS A MEASUREMENT. 3,888 of 256,810 lines carry a
+    FRACTIONAL quantity (0.2, 0.4, 0.5, 1.66 …) and the minimum is -1.0, so the question "does the
+    type truncate?" had to be answered rather than assumed: it does not. `int` and `currency` both
+    render through the client's `numberText`, which rounds nothing without a `format.decimals`
+    bag — the only difference is the `$` a `currency` column prepends. A quantity is not money, so
+    it takes the type that does not paint one.
+    """
+    return [_preset(f) for f in (
+        {"key": "order_no", "label": "Order", "type": "text", "source": "overlay",
+         "default": True, "pinned": True,
+         "description": "The sale order this line belongs to. Zero orders have a blank name, "
+                        "which is why it is the primary cell rather than the line id."},
+        {"key": "odoo_id", "label": "Odoo ID", "type": "int", "source": "overlay",
+         "default": False, "description": "The `sale.order.line` id. Also this row's id."},
+        {"key": "order_id", "label": "Odoo order id", "type": "int", "source": "overlay",
+         "default": False,
+         "description": "The `sale.order` id — the key `ut_odoo_orders` is keyed on."},
+        {"key": "customer", "label": "Customer", "type": "text", "source": "overlay",
+         "default": True},
+        {"key": JOIN_KEY, "label": "Odoo partner id", "type": "int", "source": "overlay",
+         "default": False},
+        {"key": "product", "label": "Product", "type": "text", "source": "overlay",
+         "default": True,
+         "description": "Blank on the 101 section and note lines, which carry no product."},
+        {"key": PRODUCT_JOIN_KEY, "label": "Odoo product id", "type": "int", "source": "overlay",
+         "default": False},
+        {"key": "qty", "label": "Qty", "type": "int", "source": "overlay", "default": True,
+         "agg": "sum",
+         "description": "Ordered quantity. 3,888 lines carry a fraction and some are negative "
+                        "(returns), so nothing here is rounded."},
+        {"key": "price_subtotal", "label": "Line $", "type": "currency", "source": "overlay",
+         "default": True, "agg": "sum"},
+        {"key": "margin", "label": "Margin $", "type": "currency", "source": "overlay",
+         "default": False, "agg": "sum",
+         "description": "Odoo's own line margin. Populated on every line."},
+        {"key": "purchase_price", "label": "Unit cost", "type": "currency", "source": "overlay",
+         "default": False,
+         "description": "The cost Odoo priced this line's margin against, per unit."},
+        {"key": "order_date", "label": "Order date", "type": "date", "source": "overlay",
+         "default": True},
+        {"key": "state", "label": "State", "type": "select", "source": "overlay",
+         "default": False, "options": ["sale", "done"]},
+        _scope_field(),
+    )]
+
+
+def gl_line_fields():
+    """One row per `account.move.line` — the general ledger, and the owner's "expenses" at the
+    grain a person can actually browse.
+
+    MEASURED 2026-08-12: **963,783 lines**, of which 944,846 posted, 18,885 cancelled and 52
+    draft. ⛔ UNSCOPED ON PURPOSE — a general ledger whose draft and cancelled entries are
+    invisible is a ledger that cannot be reconciled, so `parent_state` rides as a COLUMN and the
+    reader chooses. That is the same decision the binding states from the SQL side.
+
+    ⚠ TWO COLUMNS ARE LEGITIMATELY BLANK ON REAL ROWS, named here so neither reads as a defect:
+    **61,911 lines carry no partner** (journal entries that are not about a customer), and
+    **1,727 carry no account** at all, which is also why `account_code` — the key
+    `ut_odoo_accounts` is keyed on — is blank on exactly those 1,727 and the join that supplies
+    it is a LEFT one.
+
+    ⚠ `move_type` IS `text`, NOT `select`, and it is the `product_fields.category` argument:
+    five values exist today (`out_invoice` 515,634 · `entry` 414,992 · `in_invoice` 18,901 ·
+    `out_refund` 14,061 · `in_refund` 195) and Odoo's enum is longer than what we happen to hold.
+    A select whose options go stale answers a filter with a list that cannot match a stored value
+    (wave-26 item 24). `line_type` and `parent_state` ARE selects because their option lists were
+    measured COMPLETE against the whole table.
+    """
+    return [_preset(f) for f in (
+        {"key": "entry", "label": "Entry", "type": "text", "source": "overlay",
+         "default": True, "pinned": True,
+         "description": "The journal entry this line belongs to. Never blank."},
+        {"key": "odoo_id", "label": "Odoo ID", "type": "int", "source": "overlay",
+         "default": False, "description": "The `account.move.line` id. Also this row's id."},
+        {"key": "move_id", "label": "Odoo entry id", "type": "int", "source": "overlay",
+         "default": False},
+        {"key": "account", "label": "Account", "type": "text", "source": "overlay",
+         "default": True},
+        {"key": ACCOUNT_JOIN_KEY, "label": "Account code", "type": "text", "source": "overlay",
+         "default": True,
+         "description": "The GL code, from the joined chart of accounts — the key "
+                        "`ut_odoo_accounts` is keyed on. Blank on the 1,727 lines with no "
+                        "account."},
+        {"key": "customer", "label": "Partner", "type": "text", "source": "overlay",
+         "default": True,
+         "description": "Blank on the 61,911 lines that are not about a partner."},
+        {"key": JOIN_KEY, "label": "Odoo partner id", "type": "int", "source": "overlay",
+         "default": False},
+        {"key": "date", "label": "Date", "type": "date", "source": "overlay", "default": True},
+        {"key": "debit", "label": "Debit", "type": "currency", "source": "overlay",
+         "default": True, "agg": "sum"},
+        {"key": "credit", "label": "Credit", "type": "currency", "source": "overlay",
+         "default": True, "agg": "sum"},
+        {"key": "balance", "label": "Balance", "type": "currency", "source": "overlay",
+         "default": True, "agg": "sum",
+         "description": "Debit minus credit, as Odoo stores it. Sums to zero over a whole entry."},
+        {"key": "line_type", "label": "Line type", "type": "select", "source": "overlay",
+         "default": False,
+         "options": ["product", "cogs", "payment_term", "line_note", "line_section"]},
+        {"key": "move_type", "label": "Document type", "type": "text", "source": "overlay",
+         "default": False},
+        {"key": "parent_state", "label": "Entry state", "type": "select", "source": "overlay",
+         "default": True, "options": ["draft", "posted", "cancel"]},
+        _scope_field(),
+    )]
+
+
 def product_fields():
     """One row per `product.product`, keyed on its id — EVERY product, archived ones included.
 
@@ -967,8 +1129,69 @@ TABLES = (
     ("accounts", ACCOUNTS_KEY, "Odoo GL accounts", account_fields),
     ("vendors", VENDORS_KEY, "Odoo vendors", vendor_fields),
     ("bills", BILLS_KEY, "Odoo vendor bills", bill_fields),
+    # ⭐⭐ W30-T35 / R7 — the two READ-THROUGH grains. They are spec rows like any other, and that
+    # is the point: `apply_plan` creates their DEFINITION (label, fields, lock, nav entry, grants)
+    # exactly as it does for the eight above, and `plan` hands them ZERO rows. Leaving them out of
+    # this tuple was the alternative and it is the wrong one — the route 404s on a key `TABLES`
+    # does not name, so the grids would be bound to the mirror and unreachable, which is this
+    # wave's own [[reachable-is-not-the-same-as-built]] shape.
+    ("order_lines", ORDER_LINES_KEY, "Odoo order lines", order_line_fields),
+    ("gl_lines", GL_LINES_KEY, "Odoo GL lines", gl_line_fields),
 )
 
+#: The bucket -> reader map. ⛔ ITS ABSENCES ARE LOAD-BEARING: a bucket with no reader has no
+#: python row builder ANYWHERE, which is what makes "never materialised" structural rather than a
+#: policy `plan()` could forget. The two line grains are absent for that reason and no other.
+_READERS = {
+    "customers": lambda cur, excluded: read_customers(cur, excluded=excluded),
+    "products": lambda cur, excluded: read_products(cur),
+    "invoices": lambda cur, excluded: read_invoices(cur, excluded=excluded),
+    "orders": lambda cur, excluded: read_orders(cur, excluded=excluded),
+    "agents": lambda cur, excluded: read_agents(cur),
+    "accounts": lambda cur, excluded: read_accounts(cur),
+    "vendors": lambda cur, excluded: read_vendors(cur),
+    "bills": lambda cur, excluded: read_bills(cur),
+}
+
+#: The table keys this module can never materialise — DERIVED from the absence of a reader, never
+#: typed out, so it cannot drift from the fact it describes.
+#:
+#: ⛔⛔ IT IS STAMPED ONTO THE DEFINITION AT SPAWN, AND THAT IS NOT BELT-AND-BRACES — IT IS THE
+#: ONLY WAY THESE TWO TABLES EVER GET THE DURABLE FLAG. `core.user_tables.materialises` reads a
+#: process-global registry first and falls back to a stored `readThrough` stamp, "which is what a
+#: cold process reads" — but the only writer of that stamp is `strip_materialised`, and it stamps
+#: exclusively tables it found rows on (`if isinstance(t, dict) and t.get('rows')`, after an early
+#: return when nothing is fat). A table that was BORN read-through has no rows to strip, so it is
+#: never stamped, so a process that cannot reach the mirror reads `rows: {}` and calls that the
+#: answer — an EMPTY GRID with nothing going red, which is the exact failure that docstring names.
+#: The conversion writes the stamp; a table that needs no conversion still needs the statement.
+READ_THROUGH_KEYS = frozenset(key for bucket, key, _l, _f in TABLES if bucket not in _READERS)
+
+
+class _LentDoc:
+    """A store handle that serves the ONE `user_tables` document `plan()` has ALREADY read.
+
+    ⛔⛔ THIS IS NOT A MICRO-OPTIMISATION AND IT IS NOT OPTIONAL. `core.user_tables.row_limit`
+    resolves through `materialises` → `get` → `all_tables(st)`, and every one of those is a WHOLE
+    20 MB document read, deep-copied under `Store._lock`. `plan()` asks the evaluator once per
+    table per loop, so passing the live handle would have added ~16 full document copies to a
+    function that already reads it exactly once — and with `st=None` (the gate's fixture posture,
+    and any dry run) those reads resolve to the MODULE-GLOBAL store, i.e. a Hugging Face dataset
+    fetch per table, on a path that has no business touching the network at all.
+    `materialises`' own docstring asks callers to lend the definition they are holding; `row_limit`
+    takes `st` rather than `defn`, so the lending happens one level up, here.
+
+    ⚠ It answers ONLY the user-tables document and `None` for anything else, deliberately: a shim
+    that quietly proxied other keys would be a second store with a partial view, which is worse
+    than one that says what it knows.
+    """
+
+    def __init__(self, doc, key):
+        self._doc, self._key = doc if isinstance(doc, dict) else {}, key
+
+    def get(self, name):
+        return self._doc if name == self._key else None
+
 
 def plan(cur, rt=None):
     """The rows that WOULD be written, plus the refusals that apply — no store WRITE at all.
@@ -976,6 +1199,11 @@ def plan(cur, rt=None):
     Separated from `apply_plan` so a route, a gate and a dry run all measure the same thing, and
     so **every cap is checked before anything is committed**.
 
+    Returns one key per bucket plus two that are not buckets: `problems` (refusals — a non-empty
+    list makes `apply_plan` raise before it writes anything) and, since W30-T35, **`limits`** —
+    `{table_key: limit_report}` for every table this plan did not fully materialise, which is R6's
+    second sentence carried as data rather than left for a reader to infer from an empty list.
+
     ⛔ `rt` IS WHAT MAKES THE TABLE-COUNT CHECK HONEST, and leaving it out was a real half-spawn
     bug. This spawn writes FOUR tables in four updater passes; a tenant near `MAX_TABLES` would
     create some and refuse the rest — leaving a locked invoices database with no rollup host,
@@ -984,25 +1212,78 @@ def plan(cur, rt=None):
     write. `rt` also carries the stored row counts the shrink guard compares against.
     """
     ut = _ut()
+    # ⭐ R6, AND WITHOUT THIS LINE THE RULE IS ONLY ACCIDENTALLY TRUE. `is_connected` answers from
+    # three places in falling authority: the registry, a stored `connected: True`, then the
+    # `ut_odoo_` naming convention — and that last leg needs the table to ALREADY EXIST. So on a
+    # FIRST spawn, in a process that has not yet built `routes_odoo_tables.GRID_SOURCES`, every one
+    # of these tables reads as unconnected and earns `MAX_ROWS`: R6's cap removal would silently
+    # not apply on exactly the run that creates the databases. This module DECLARES these keys, so
+    # it is the honest place to say what they are. Idempotent (a set add), and it fills the
+    # evaluator's input rather than becoming a second evaluator.
+    ut.register_connected(*[key for _b, key, _l, _f in TABLES])
     excluded = excluded_ids(cur)
-    built = {
-        "customers": read_customers(cur, excluded=excluded),
-        "products": read_products(cur),
-        "invoices": read_invoices(cur, excluded=excluded),
-        "orders": read_orders(cur, excluded=excluded),
-        "agents": read_agents(cur),
-        "accounts": read_accounts(cur),
-        "vendors": read_vendors(cur),
-        "bills": read_bills(cur),
-    }
-    problems = []
-
+    # ⭐⭐ W30-T35 / R6 / R7 — WHICH BUCKETS ARE BUILT AT ALL IS NOW ASKED, NOT ASSUMED, and it is
+    # `core.user_tables.row_limit` that answers: 0 = "stores no rows HERE" (read-through), None =
+    # "connected and uncapped", MAX_ROWS = "the editable substrate". Its own docstring names this
+    # function as the caller that reads it, which is the seam working as designed — one evaluator,
+    # so the spawn, the write doors and the wire cannot disagree about whether a table is capped
+    # ([[one-evaluator-per-question]]).
+    #
+    # ⛔ TWO DIFFERENT REASONS NOT TO BUILD, AND THEY ARE KEPT SEPARATE ON PURPOSE:
+    #   * no reader at all — structural, permanent, and the case that must not depend on a store
+    #     read succeeding (a cold process with no mirror still must not try to build 963,783 rows);
+    #   * a reader exists but the table has already been converted to read-through — the
+    #     `ut_odoo_accounts` case. Building 192 rows and letting `strip_materialised` delete them
+    #     again on the next pass "works", and it is exactly the wasted, dangerous work `row_limit`
+    #     was built to prevent. It also stops a refresh from silently RE-MATERIALISING a table
+    #     D-87's conversion had already emptied.
+    #
+    # ⚠ THE DOCUMENT IS READ **ONCE**, HERE, AND LENT TO THE EVALUATOR — see `_LentDoc`. It used
+    # to be read after the build loop; it moved up because `row_limit` needs it and reading it per
+    # table per loop is ~16 more whole-document deep copies (or, with `st=None`, a Hugging Face
+    # fetch per table on a path that must never touch the network).
     existing = {}
     if rt is not None:
         try:
             existing = dict(rt.get(ut.STORE_KEY) or {})
         except Exception:                                             # noqa: BLE001
             existing = {}
+    # ⛔ THE LENT DOCUMENT CARRIES THE `readThrough` STAMP THIS MODULE IS RESPONSIBLE FOR, and
+    # without it R6's report is silently absent on the run that matters most — the FIRST spawn.
+    # MEASURED: with an empty store, `row_limit` finds no registry entry and no stored stamp, so
+    # it answers `None` ("connected and uncapped") for a grain that stores nothing at all, and
+    # `limit_report` answers None with it — so `plan()["limits"]` came back EMPTY and the grids
+    # were skipped with no stated reason. The structural `reader is None` guard still did its job;
+    # what went missing was the half of R6 that has to SAY WHY.
+    #
+    # ⚠ THE OBVIOUS FIX IS THE ONE I DID NOT TAKE: `ut.register_read_through(*READ_THROUGH_KEYS)`
+    # would work in one line, and `core.user_tables` explicitly reserves that registrar —
+    # *"IT IS ALSO THE ONLY PLACE THAT MAY CALL `register_read_through`"* — for
+    # `routes_odoo_tables.sync_read_through`, because ELIGIBILITY needs the mirror and the fold
+    # matrix. That reasoning does not apply to a grain with no reader (there is nothing it could
+    # be eligible FOR), but the law is written without an exception, so this lends the evaluator
+    # the definition instead of taking one. `_ensure_table_inplace` writes exactly this stamp, so
+    # what is lent is the document as it stands the moment this plan applies.
+    lent = _LentDoc({**existing,
+                     **{k: {**(existing.get(k) or {}), "readThrough": True}
+                        for k in READ_THROUGH_KEYS}},
+                    ut.STORE_KEY)
+
+    built, limits = {}, {}
+    caps = {}
+    for bucket, key, _label, _fields in TABLES:
+        reader = _READERS.get(bucket)
+        caps[key] = cap = ut.row_limit(key, st=lent)
+        if reader is None or cap == 0:
+            built[bucket] = []
+            report = ut.limit_report(key, st=lent)
+            if report:
+                limits[key] = report
+            continue
+        built[bucket] = reader(cur, excluded)
+    problems = []
+
+    if rt is not None:
         needed = [k for _b, k, _l, _f in TABLES if k not in existing]
         if needed and len(existing) + len(needed) > ut.MAX_TABLES:
             problems.append(
@@ -1012,11 +1293,32 @@ def plan(cur, rt=None):
 
     for bucket, key, _label, _fields in TABLES:
         rows = built[bucket]
-        # ⛔ REFUSE, NEVER TRUNCATE. A capped table understates every total it feeds while looking
-        # exactly like a complete one — the failure mode this whole module is arranged against.
-        if len(rows) > ut.MAX_ROWS:
-            problems.append(f"{key}: {len(rows)} rows exceeds MAX_ROWS={ut.MAX_ROWS}; refusing "
-                            f"(a truncated table understates every rollup it feeds)")
+        cap = caps[key]          # asked ONCE per table, above — never re-read per loop
+        # ⭐⭐ R6: THE `MAX_ROWS` REFUSAL IS GONE FOR A CONNECTED SOURCE, AND THE SENTENCE IT USED
+        # TO PRINT IS NOW `limit_report`'s STRUCTURED ANSWER. Owner, verbatim: *"there is no cap in
+        # how many data from the API source (as long as its from a connected source like Odoo) that
+        # can be pulled into the app… Now if there is lag or it can't be done, you need to
+        # explicitly tell me why and recommend a fix."* Both halves are here: a connected table
+        # answers `None` and is never refused for its size, and anything that IS still bounded is
+        # reported with its cause and its recommendation instead of a hand-typed line.
+        #
+        # ⛔ THE `cap and` GUARD IS THE WHOLE CHANGE AND ITS TWO FALSY CASES MEAN OPPOSITE THINGS:
+        # `None` = connected, uncapped, build every row Odoo has; `0` = stores no rows here, and
+        # the loop above already handed it an empty list. Neither may reach the refusal. The
+        # editable substrate still gets `MAX_ROWS` and is still REFUSED, never truncated — a capped
+        # table understates every total it feeds while looking exactly like a complete one.
+        if cap and len(rows) > cap:
+            report = ut.limit_report(key, st=lent) or {}
+            limits[key] = report
+            problems.append(
+                f"{key}: {len(rows):,} rows exceeds the {cap:,}-row ceiling; refusing "
+                f"({report.get('cause', 'a truncated table understates every rollup it feeds')}). "
+                f"{report.get('recommendation', '')}".strip())
+        # ⚠ THE SHRINK GUARD SKIPS A READ-THROUGH GRAIN, and without this it would refuse every
+        # spawn after the first conversion: zero rows against a stored population is the INTENDED
+        # end state there, not the partial mirror read this guard exists to catch.
+        if cap == 0:
+            continue
         stored = len(((existing.get(key) or {}).get("rows")) or {})
         if stored and len(rows) < stored * MAX_SHRINK:
             problems.append(
@@ -1024,6 +1326,11 @@ def plan(cur, rt=None):
                 f"more than {int((1 - MAX_SHRINK) * 100)}% is a bad read, not Odoo history "
                 f"shrinking; refusing rather than deleting rows that still exist")
     built["problems"] = problems
+    # R6's second sentence as DATA rather than prose: every table whose rows this plan did not
+    # (or may not) materialise, with the cause and the recommendation `core.user_tables` derives.
+    # ⚠ NOT a bucket — `apply_plan` iterates `TABLES` and asks `if bucket in built`, so a key that
+    # is not a bucket name is inert there, exactly as `problems` has always been.
+    built["limits"] = limits
     return built
 
 
@@ -1107,6 +1414,13 @@ def _ensure_table_inplace(cur, key, label, fields, rows, username, stamp):
             "recordMode": ut.AUTOMATION_RECORD_MODE,
         }
     table.setdefault("recordMode", ut.AUTOMATION_RECORD_MODE)
+    # W30-T35 — the durable "my rows are not in this document" statement, on the tables no
+    # conversion will ever stamp (see `READ_THROUGH_KEYS`). Written on every pass, not
+    # `setdefault`: it is derived from the code's own structure, so the code is what it must agree
+    # with, and a definition that somehow lost the flag should regain it rather than keep serving
+    # an empty grid.
+    if key in READ_THROUGH_KEYS:
+        table["readThrough"] = True
     have = {str(f.get("key")): f for f in (table.get("fields") or [])}
     for field in fields:
         fkey = str(field.get("key"))

api/providers.py

@@ -44,9 +44,14 @@ from typing import Callable
 #: vendor's own dashboard is. Wrong by 2x still ranks correctly; wrong by 100x does not, which is
 #: why they are named and dated rather than guessed silently.
 #: Bright Data Instagram datasets ~ $0.0015/record (2026-08 list). Apify instagram-scraper
-#: ~ $0.0023/result (2026-08 list). Both re-checked when a provider is added.
+#: ~ $0.0027/result (2026-08 list). Both re-checked when a provider is added.
+#: ⚠ WAVE 30 · T16 — APIFY CORRECTED 0.0023 -> 0.0027, and the direction matters: the old number
+#: made the fallback look CHEAPER than it is, and `estimate()` is what a person is shown before
+#: they authorise a run. An under-stated price is the one rounding error a cost guard cannot catch.
+#: ⚠ Both are LIST rates used to rank and to estimate. They are not invoices, and nothing here
+#: reads a live price — a modelled figure that says so is honest; one that pretends is not.
 _COST_BRIGHTDATA = float(os.environ.get("AIOS_COST_BRIGHTDATA") or 0.0015)
-_COST_APIFY = float(os.environ.get("AIOS_COST_APIFY") or 0.0023)
+_COST_APIFY = float(os.environ.get("AIOS_COST_APIFY") or 0.0027)
 
 
 @dataclass(frozen=True)

api/routes_automation.py

@@ -19,6 +19,7 @@ from fastapi import APIRouter, Body, Depends, Header, Request
 import automation_engine as engine
 import oauth_connect
 import routes_oauth
+import scope_cache
 from deps import Session, err, module_gate, require_session
 
 router = APIRouter(prefix="/api/v1")
@@ -225,6 +226,127 @@ def _tick_state():
 #: or delete — a new database cannot contain the legacy stage cells this retires.
 _BOARD_RETIRED = set()
 
+#: ⭐⭐ WAVE 30 · T12 — THE PICKER DEFAULT, MEMOISED. `{tenant: (stamp, table_key)}`, the shape
+#: `scope_cache` stores.
+#:
+#: ⛔ WHY THE DERIVED STRING AND NOT THE DOCUMENT. The obvious cache here is the `user_tables`
+#: bucket itself, and it is the wrong one: that bucket is up to 35.8 MB per tenant and this box is
+#: the HF free tier, so caching it would trade a latency problem for a memory one. What the warm
+#: path actually needs is `discover_default_table`'s ANSWER — one short string.
+#:
+#: ⛔ AND WHY NOT A PLAIN `_BOARD_RETIRED`-STYLE ONCE-PER-PROCESS SET, which would have been less
+#: code: the election reads which profile databases exist and which hold rows, and BOTH change
+#: while the process lives (somebody creates a database, an automation writes the first row). A
+#: once-per-process memo would pin the picker's default to whatever was true at boot and never
+#: correct itself — a default that disagrees with the save door, which is exactly the wave-25 R2
+#: defect the `"table"` line's own comment records. A TTL bounds the staleness instead.
+#:
+#: ⚠ `scope_cache` rather than a hand-rolled dict, because it is the house pattern for precisely
+#: this (`routes_customers`, `routes_products`, `pages` all use it) and it is stale-while-refresh:
+#: once a copy exists NO request blocks on a rebuild. Automation was the one module importing it
+#: nowhere, which the wave-30 scout named as the reason every other surface feels fast.
+_DISCOVER_DEFAULT = {}
+#: 5 minutes — the same order as `apiBridge.ts:CUSTOMERS_FRESH_MS` on the client. Overridable so a
+#: gate can pin it rather than sleep.
+_DISCOVER_DEFAULT_TTL = float(os.environ.get("AIOS_AUTOMATION_DEFAULT_TTL") or 300)
+
+
+#: The one store key `_LentTables` intercepts. DERIVED from the engine's own constant rather than
+#: written out here: `engine.ut_all` reads the bucket through it, so if that key ever moves, the
+#: lend moves with it instead of silently becoming a pass-through that still looks correct.
+_UT_STORE_KEY = engine.UT_STORE_KEY
+
+
+class _LentTables:
+    """⭐⭐ WAVE 30 · T13 — a read-only `st` that serves ONE already-read `user_tables` document
+    and passes every other key straight through to the real runtime.
+
+    ⛔ WHY THIS EXISTS RATHER THAN A SECOND COPY OF THE WALL. `automation_tables` calls
+    `user_tables.may_open(key, …)` per table; `may_open` → `user_tables.get` → `all_tables(st)` →
+    `st.get('user_tables')`, and `core/store.py:Store.get` deep-copies the WHOLE tenant document on
+    every call, hit or miss, under the store lock. So listing N databases cost **1 + N** full
+    deep copies of a document whose documented ceiling is 35.8 MB — and this is the route that runs
+    the instant somebody clicks an automation row, i.e. the *"and in the MODULE itself"* half of the
+    owner's item 4.
+    ⛔ THE OBVIOUS FIX IS THE FORBIDDEN ONE. Inlining the creator-or-admin test here would remove
+    the N reads and re-create the exact defect wave 20 fixed: this route USED to carry its own
+    wider rule (`createdBy in (uname, 'automation', 'scheduler')`), so a non-admin saw a database
+    in the picker and was refused the moment they opened it. This function's own docstring calls
+    that out — *"a duplicate READER is fine; a duplicate WALL is not"*. `may_open` stays THE one
+    resolver, unmodified and still called per table; it is simply no longer charged for a document
+    the caller is already holding.
+    ⚠ AND IT IS A CALLER-SIDE FIX ON PURPOSE: adding a `tables=` parameter to `may_open` would mean
+    editing `platform/core/user_tables.py`, which belongs to another lane this wave.
+
+    ⚠ READ-ONLY LENDING, and it is safe by inspection rather than by hope: `all_tables` does
+    `dict(st.get(STORE_KEY) or {})`, i.e. it shallow-copies the top level before anybody touches
+    it, and `may_open` only ever READS `t.get('createdBy')`. Nothing on this path mutates the
+    lent document. Any other store key — the shares registry `role_for` consults, for instance —
+    is not intercepted and reaches the real runtime unchanged.
+    """
+
+    def __init__(self, runtime, tables):
+        self._runtime, self._tables = runtime, tables
+
+    def get(self, name, fresh=False):
+        if name == _UT_STORE_KEY and not fresh:
+            return self._tables
+        return self._runtime.get(name, fresh)
+
+    def __getattr__(self, name):
+        return getattr(self._runtime, name)
+
+
+def _discover_default(session, tables):
+    """The discovery picker's default table for this tenant — WITHOUT a bucket read on a warm call.
+
+    ⚠ `tables` is the document the caller ALREADY holds on a cold call (the retirement pass reads
+    one). Passing it through means the cold path elects from the copy it has rather than taking a
+    second one, so this is never an extra read — only ever a saved one.
+    """
+    if not session.runtime.available():
+        return ""
+    if tables is not None:
+        # Cold call: the document is in hand. Elect from it and prime the memo in the same pass.
+        value = engine.discover_default_table(session.runtime, tables=tables)
+        _DISCOVER_DEFAULT[session.tenant] = (time.time(), value)
+        return value
+    return scope_cache.get(_DISCOVER_DEFAULT, session.tenant, _DISCOVER_DEFAULT_TTL,
+                           lambda: engine.discover_default_table(session.runtime))
+
+
+def warm_default(rt):
+    """⭐⭐ WAVE 30 · T12, THE COLD HALF. Elect the discovery picker's default at BOOT.
+
+    ⛔ THE HALF THE MEMO CANNOT FIX, and it is why this exists rather than being a nicety. The memo
+    above makes calls 2..N free; **call 1 is still a full `user_tables` download**, and it lands on
+    whoever clicks Automation first after a deploy — the one visitor with no cache anywhere,
+    waiting on a document whose documented ceiling is 35.8 MB / ~1.4 s, taken under the store's
+    single lock. That is the owner's *"only automation has a loading screen"* on a cold Space, and
+    two waves of memoising the warm path could never touch it. Automation was the only module
+    importing `scope_cache` nowhere AND the only one absent from `_prewarm`.
+
+    ⭐ IT ELECTS, IT DOES NOT CACHE THE DOCUMENT — deliberately, and this is the whole design.
+    `discover_default_table` reads the bucket once here, in the prewarm daemon thread where nobody
+    is waiting, and what survives is a DERIVED STRING. Holding the 35.8 MB document resident would
+    trade a latency the tenant notices for memory the HF free tier does not have, which is the
+    argument `_DISCOVER_DEFAULT`'s own note makes against caching it.
+
+    ⚠ SAME TTL AS THE REQUEST PATH, not a permanent set: the election reads which databases exist
+    and which hold rows, and both change while the process lives. Priming by assignment is exactly
+    what the cold request path already does one function up, so there is one way this memo is
+    filled, not two.
+
+    Returns the elected key (`""` when the store is unavailable), so a caller can log it rather
+    than guess whether the warm-up did anything. Called from `main.py:_prewarm` only.
+    """
+    tenant = str(getattr(rt, "key", "") or "")
+    if not tenant or not rt.available():
+        return ""
+    value = engine.discover_default_table(rt)
+    _DISCOVER_DEFAULT[tenant] = (time.time(), value)
+    return value
+
 
 @router.get("/automations")
 def list_automations(session: Session = Depends(_GATE)):
@@ -250,8 +372,17 @@ def list_automations(session: Session = Depends(_GATE)):
     # `_without_retired_board`), so the persist step is hygiene, not correctness. No client can
     # ever be shown state this skip left behind. Nothing writes new `stage_auto_` cells either —
     # wave 26's R6 deleted the board that made them.
-    tables = engine.ut_all(session.runtime) if session.runtime.available() else None
-    if tables is not None and session.tenant not in _BOARD_RETIRED:
+    # ⭐⭐ WAVE 30 · T12 (owner items 4/5, the complaint that has now survived TWO waves).
+    # ⛔ W29-T01 GUARDED THE SCAN AND NOT THE READ, and that is the whole of what was left. The
+    # line below used to be unconditional — every single request deep-copied the tenant's entire
+    # `user_tables` document (documented ceiling 35.8 MB / ~1.4 s, and `core/store.py:Store.get`
+    # re-serializes on EVERY `.get()`, hit or miss, UNDER THE STORE LOCK so the copies also queue
+    # behind each other) — while on calls 2..N the result was DISCARDED: `tables` had exactly two
+    # consumers, the `_BOARD_RETIRED` scan (skipped after call 1) and a picker DEFAULT STRING.
+    # A whole-tenant document, per request, to render a rail showing a name and a toggle.
+    tables = None
+    if session.runtime.available() and session.tenant not in _BOARD_RETIRED:
+        tables = engine.ut_all(session.runtime)
         _BOARD_RETIRED.add(session.tenant)
         # Idempotent Board retirement removes only engine-marked stage fields and legacy Board
         # state. User-created Status/Stage columns remain intact.
@@ -319,7 +450,11 @@ def list_automations(session: Session = Depends(_GATE)):
                          # save would have written somewhere else — a default that disagrees with
                          # itself across two panels, which is the shape wave 25's R2 fixed for
                          # `targetTable` vs the action's `table`.
-                         "table": (engine.discover_default_table(session.runtime, tables=tables)
+                         # ⭐ WAVE 30 · T12 — through the per-tenant memo. The ELECTION rule and
+                         # everything the comment above says about it are unchanged; what changed
+                         # is that a warm request no longer re-reads a 35.8 MB document to
+                         # recompute a string that did not move.
+                         "table": (_discover_default(session, tables)
                                    or engine.DISCOVER_TABLE)},
             "storeAvailable": bool(session.runtime.available()),
             # Wave 22 C3 — the trigger vocabulary, session-scoped because email readiness is a
@@ -449,9 +584,16 @@ def automation_tables(session: Session = Depends(_GATE)):
             pass
 
     out = []
-    for key, t in sorted(engine.ut_all(session.runtime).items(),
+    # ⭐⭐ WAVE 30 · T13 — ONE read of the tenant document, LENT to the wall for every table.
+    # It was `1 + N` full deep copies (this `ut_all`, then `may_open` → `get` → `all_tables` per
+    # table), each of a document with a 35.8 MB / ~370 ms ceiling, all of them queued behind
+    # `Store._lock`. `may_open` is unchanged and still asked about every table — see `_LentTables`
+    # on why re-implementing the wall here is the one fix that is NOT available.
+    _tables_doc = engine.ut_all(session.runtime)
+    _lent = _LentTables(session.runtime, _tables_doc)
+    for key, t in sorted(_tables_doc.items(),
                          key=lambda kv: (kv[1].get("label") or "").lower()):
-        if not user_tables.may_open(key, session.uname, session.admin, st=session.runtime):
+        if not user_tables.may_open(key, session.uname, session.admin, st=_lent):
             continue
         row = {"key": key, "label": t.get("label") or key,
                "source": t.get("source") or "Blank",

api/routes_connectors.py

@@ -60,13 +60,36 @@ PLANNED = [
      "desc": "Attach files from Drive to records."},
     {"key": "google_calendar", "label": "Google Calendar", "kind": "oauth",
      "desc": "Turn dated records into calendar entries."},
-    {"key": "tiktok", "label": "TikTok", "kind": "token",
-     "desc": "The second social source beside Instagram."},
-    # ⚠ The vendor's name came out of this line in wave 25 (C2's sweep). What a customer needs to
-    # know is that Instagram data already arrives another way — not which supplier carries it.
-    {"key": "meta", "label": "WhatsApp and Instagram (Meta)", "kind": "oauth",
-     "desc": "Blocked on Meta business verification; Instagram data arrives through the "
-             "Scraper connector instead."},
+    # ⭐⭐ WAVE 30 · R4 — TWO ROWS WERE DELETED HERE, AND THEY WERE MISINFORMATION, not clutter.
+    #
+    #   {"key": "tiktok",  "label": "TikTok", ...  "The second social source beside Instagram."}
+    #   {"key": "meta",    "label": "WhatsApp and Instagram (Meta)", ... "Blocked on Meta business
+    #                       verification; Instagram data arrives through the Scraper connector"}
+    #
+    # ⛔ THE TIKTOK ROW SAID "not built yet" ABOUT SOMETHING THAT SHIPPED IN WAVE 29 — which is
+    # precisely the rot this module's header warns about: *"a provider gets wired up somewhere and
+    # the directory keeps calling it planned for a wave or two, which is exactly the
+    # misinformation this surface exists to prevent."* TikTok is a PLATFORM of the Scraper
+    # connector now (R3/R4), and it appears in the Scraper card's own drill below.
+    # ⚠ THE META ROW IS A DIFFERENT CASE and is deleted for a different reason: what it described
+    # (Instagram arriving another way) is now visible ON the Scraper card, so keeping it would put
+    # Instagram on this page twice, once as working and once as blocked. The Meta business
+    # verification blocker itself is not lost — it is D-86's subject and lives in
+    # `.claude/wiki/research/ads-connectors-owner-actions.md`, where an owner action belongs.
+]
+
+#: ⭐ WAVE 30 · R4 — THE SCRAPER'S PLATFORMS, and the whole shape of the ruling in one list.
+#: The owner: *"the damn Tiktok and Instagram belongs in the same bucket … Only when I click
+#: 'Scraper' … would I see the option to choose either Instagram OR TikTok."* So the directory
+#: mirrors the automation menus exactly: ONE card for the capability, and the platforms are behind
+#: it rather than beside it.
+#: ⚠ These are not connectors and must never become rows: they have no state, no credential and
+#: no manage door of their own — the Scraper's key is what is configured, and it configures both.
+SCRAPER_PLATFORMS = [
+    {"key": "instagram", "label": "Instagram",
+     "desc": "Profiles, posts and comments, by search or by handle."},
+    {"key": "tiktok", "label": "TikTok",
+     "desc": "The same three, on TikTok's own schema."},
 ]
 
 #: Token connectors an admin can wire up TODAY by pasting a key — no OAuth client, no app review.
@@ -156,10 +179,17 @@ def directory(rt, uname, is_admin=False):
     # `needs` string still names the env var, deliberately: it is read by whoever has to set it.
     rows.append({
         "key": "scraper", "label": "Scraper", "kind": "builtin",
-        "desc": "Instagram profile and post capture for the discovery automations.",
+        # ⭐ WAVE 30 · R4 — the sentence names the CAPABILITY; the platforms are the drill below.
+        # It used to say "Instagram profile and post capture", which stopped being true the day
+        # TikTok discovery shipped and would have to be re-edited for every platform after it.
+        "desc": "Profile, post and comment capture for the discovery automations.",
         "state": "connected" if _eng.bd_ready() else "unconfigured",
         "needs": "" if _eng.bd_ready() else "AIOS_BRIGHTDATA_KEY is not set on this deployment",
         "manage": "",
+        # ⛔ ONE CREDENTIAL, TWO PLATFORMS — which is why this is a field on the row and not two
+        # rows. `bd_ready()` above answers for both; a per-platform state would be a second
+        # answer to a question that has one.
+        "platforms": [dict(p) for p in SCRAPER_PLATFORMS],
     })
     rows.append({
         "key": "webhooks", "label": "Webhooks", "kind": "builtin",

api/routes_customers.py

@@ -221,10 +221,14 @@ def grid_assembly(session: Session, scope: str = "customer", storage_key: str =
 
 
 def _payload(session: Session):
-    """`{fields, rows, today, pulled_at}` — X2's shape, which `verify_fields_contract.py`
+    """`{fields, rows, today, docs, 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.
 
+    ⭐ `docs` joined the shape in wave 30 (W30-T37 / contract C4). Named here rather than left to
+    the reader because a docstring that still lists the OLD shape is a stale comment on correct
+    code — this repo's D-73 — and it is the first thing anyone greps to learn the payload.
+
     ⚠ `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).
     """
@@ -233,11 +237,26 @@ def _payload(session: Session):
     g = grid_assembly(session)
     rows = aios_grid.rows_from_pool(
         g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"])
+    # ⭐ C4 / D-138 (W30-T37) — THE DOCUMENTS PRODUCER FOR THE CUSTOMER SCOPE. The write door
+    # (`doc_add`/`doc_fetch`/`doc_delete`) never stopped working and every client half is
+    # complete; what vanished with `app.py` at EXIT-6 was the only thing that ever set this key.
+    # All six `onDoc*` handlers in `CustomerGrid.tsx` read `payload?.docs ? … : undefined`, so an
+    # ABSENT key — not a broken one — is what has been switching the whole feature off.
+    #
+    # ⛔ IMPORTED, NEVER RE-SERIALISED. `core.grid_events.docs_for` is the ONE serialiser and
+    # `routes_tables` (the `ut_*` scope) calls the SAME function with the same argument order.
+    # A matching pair here is precisely how the wave-29 close-out reintroduced its own defect in
+    # the opposite direction inside a single commit ([[one-question-two-normalizers]]).
+    # ⚠ `g["pids"]` is the row set this session is ALREADY scoped to — `docs_for` has no
+    # "every document in the tenant" mode to reach for, deliberately.
+    from core import grid_events as _ge
     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"],
+            "docs": _ge.docs_for(g["pids"], scope_key="customer", uname=session.uname,
+                                 admin=session.admin, st=session.runtime),
             "pulled_at": time.strftime("%Y-%m-%d %H:%M")}
 
 

api/routes_grid.py

@@ -757,9 +757,17 @@ def grid_events_route(body: dict = Body(default=None),
     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)
+        # ⭐⭐ WAVE 30 / W30-T30 (owner item 2: *"when I click hide fields it crash… no matter the
+        # size"*). This used to be `ut_assembly(...)`, which builds the whole table to validate a
+        # write it then throws away: `scoped_pool` allocates a dict per row and sorts them, so ONE
+        # hide-fields checkbox rebuilt ~33k order rows before the event was even dispatched.
+        # ⛔ NOTHING IS VALIDATED LESS. The comment above still holds — this assembly is the
+        # permission wall and the admission context — and `ut_write_ctx` returns the SAME six keys
+        # this route reads, with a pid set derived from exactly the row ids `scoped_pool` would
+        # have kept. What it does not do is materialise the rows nobody here looks at.
+        from routes_tables import ut_write_ctx
+
+        g = ut_write_ctx(session, scope)
     else:
         g = grid_assembly(session, scope=scope, consume_corrections=False)
     # ⚠ THE MEASURE CONTEXT IS NOT OPTIONAL (2026-07-31). Without `measure_offer`,
@@ -789,7 +797,14 @@ def grid_events_route(body: dict = Body(default=None),
 
     out = {"results": results, "rerender": any(r["rerender"] for r in results)}
     if ctx.out.doc is not None:
-        out["doc"] = ctx.out.doc
+        # ⭐ C4 / W30-T27 — `docPayload` IS THE NAME THE CLIENT ALREADY DECLARES. `types.ts` has
+        # carried `docPayload?: {pid, docId, name, mime, data_b64}` since C5, and `Documents.tsx`
+        # matches it against the fetch it is waiting on — while this route has been answering
+        # `doc`, which `apiBridge.ts` deliberately drops. One object, emitted under the name the
+        # consumer looks for, so F's wiring needs no translation step to get wrong.
+        # ⚠ `doc` stays for one wave: nothing in the client reads it, but a gate might, and
+        # removing a key to save six bytes is not worth a red nobody predicted.
+        out["doc"] = out["docPayload"] = ctx.out.doc
     if ctx.out.toast is not None:
         out["toast"] = ctx.out.toast
 

api/routes_odoo_tables.py

@@ -14,9 +14,14 @@ it can. `verify_api` now does both.
 
 ADMIN-GATED, and not for tidiness: a refresh REWRITES four locked databases for the whole tenant
 and deletes the rows that left the population. That is an operator action.
+⭐ WAVE 30 (R6/R7, contract C2) ADDS A THIRD ENDPOINT AND IT IS A DIFFERENT KIND OF THING: the
+READ-THROUGH WINDOW. The two above operate on the materialised copy; `/{table_key}/rows` does not
+read the copy at all. See the block above `GRID_SOURCES` for why that had to change.
 """
+import json
+
 from fastapi import Depends
-from fastapi import APIRouter
+from fastapi import APIRouter, Query
 
 from deps import Session, err, require_session
 
@@ -63,8 +68,19 @@ def refresh_odoo_tables(session: Session = Depends(require_session)):
         raise err(400, "not_applicable",
                   "These databases are built from the Royal Imports Odoo mirror (R1).")
     try:
-        return {"ok": True, **rel.refresh(session.runtime, session.tenant,
-                                          username=session.user)}
+        out = rel.refresh(session.runtime, session.tenant, username=session.user)
+        # ⭐⭐ W30-T31 — AND THEN THE ROWS THAT SHOULD NOT BE HERE LEAVE AGAIN.
+        #
+        # The spawn writes every bucket's rows straight into the tenant document by mutating it
+        # inside its own updater, so no guard in `core.user_tables` is on that path (measured, not
+        # assumed: `_ensure_table_inplace` never calls a function there). Stripping AFTER the write
+        # is what makes "a read-through grid stores no rows" true rather than intended — and the
+        # refresh is the only moment a stripped table can come back.
+        # ⚠ Reported in the response, because a silent 7 MB moving in or out of a tenant's
+        # document is exactly the kind of thing an operator should be able to see happening.
+        sync_read_through()
+        moved = _ut().strip_materialised(st=session.runtime)
+        return {"ok": True, **out, "unmaterialised": moved}
     except rel.Refused as e:
         # A refusal is the ANSWER, not a crash: the caller must see WHY nothing was written.
         raise err(409, "refused", str(e))
@@ -93,6 +109,16 @@ def odoo_tables_status(session: Session = Depends(require_session)):
     """
     rel, out = _rel(), {}
     import core.user_tables as user_tables
+    # ⭐ W30-T31 — THE ELIGIBILITY PASS RUNS HERE TOO, and the mirror cursor is taken best-effort:
+    # the freshness surface must answer on a box with no mirror (that is what it is FOR), so a
+    # store that is not ready costs the size half of the question, never the whole endpoint.
+    cur = None
+    try:
+        from harness import datastore
+        cur = datastore.ro_con()
+    except Exception:                                                 # noqa: BLE001
+        pass
+    eligible, why_not = sync_read_through(cur)
     # ⚠ ITERATES `rel.TABLES`, NEVER A LITERAL PAIR. It read `(INVOICES_KEY, CUSTOMERS_KEY)`
     # while those were the only two; the 2026-08-09 widening added products and orders, and a
     # hard-coded list here would have reported "everything is fine" over two databases it had
@@ -101,10 +127,782 @@ def odoo_tables_status(session: Session = Depends(require_session)):
         table = user_tables.get(key, st=session.runtime) or {}
         rows = (table.get("rows") or {})
         stamps = [str((r or {}).get("refreshed") or "") for r in rows.values()]
+        # ⛔⛔ A FRESHNESS SURFACE THAT LIES IS WORSE THAN NO FRESHNESS SURFACE, and this endpoint
+        # was one step from becoming one. Both numbers below are derived from `table["rows"]`, so
+        # the moment a grid stops materialising they would read `rows: 0, refreshed: ""` — an
+        # operator would see a database that looks EMPTY and STALE on a route whose own docstring
+        # says a worklist that quietly stopped updating must be legible without a refresh. So a
+        # read-through table is counted from the MIRROR and says where its count came from.
+        materialised = user_tables.materialises(key, st=session.runtime)
+        if not materialised:
+            try:
+                rows = {}
+                stamps = []
+                spec = _source_for(cur, key) if cur is not None else None
+                if spec is not None:
+                    from harness import datastore as _ds
+                    frm = ({"from_sql": spec["from_sql"]} if spec.get("from_sql")
+                           else {"table": spec["table"]})
+                    n = _ds.window(select="1", where=spec.get("where") or "",
+                                   order_by=spec["id"], limit=1, cur=cur, **frm)["total"]
+                else:
+                    n = -1                    # unknown, and never reported as zero
+            except Exception:                                         # noqa: BLE001
+                n = -1
         out[key] = {
             "exists": bool(table),
-            "rows": len(rows),
-            "refreshed": max([s for s in stamps if s], default=""),
+            "rows": (len(rows) if materialised else n),
+            "rowsFrom": ("document" if materialised else "mirror"),
+            "materialised": materialised,
+            # why this grid still keeps its rows in the tenant document, when it does not have to
+            "materialisedBecause": (why_not.get(key, "") if materialised else ""),
+            "refreshed": (max([s for s in stamps if s], default="") if materialised
+                          else "live — read through the mirror"),
             "locked": table.get("recordMode") == user_tables.AUTOMATION_RECORD_MODE,
+            # W30/R7: whether this database is served THROUGH the mirror rather than from the copy
+            # above. Reported per table, because they convert one at a time and an operator
+            # reading `rows: 0` needs to know whether that means "empty" or "not stored here".
+            "readThrough": key in _sources(),
         }
-    return {"ok": True, "applicable": rel.is_royal(session.tenant), "tables": out}
+    # ⭐ W30-T32 / R6's SECOND SENTENCE, APPLIED TO OUR OWN HALF-BUILT STATE. A read-through
+    # binding whose FIELD DECLARATION has not landed yet answers 404 on the rows route, and an
+    # operator would read that as "the grid does not exist" rather than as "half of it shipped".
+    # These are the two line grains: bound here, declared in `odoo_relational` by W30-T35.
+    # ⚠ It reports the KEYS, never a field list — inventing a contract here is exactly the second
+    # source of truth the ticket forbids.
+    pending = {k: {"readThrough": True, "declared": False,
+                   "cause": "this connected grid has a read-through binding but no field "
+                            "declaration in odoo_relational yet, so it cannot be opened",
+                   "recommendation": "declare its fields + a TABLES row (W30-T35); the binding "
+                                     "and the window are already live"}
+               for k in _sources() if k not in out}
+    return {"ok": True, "applicable": rel.is_royal(session.tenant), "tables": out,
+            "bound_not_declared": pending}
+
+
+# ═════════════════════════════════════════════════════════════════════════════════════════════
+# ⭐⭐ THE READ-THROUGH WINDOW — owner ruling R6 ("no cap on connected-source data") via R7.
+# ═════════════════════════════════════════════════════════════════════════════════════════════
+#
+# THE PROBLEM IT REPLACES, in the owner's numbers. `core.user_tables.MAX_ROWS = 60_000` bounds a
+# `ut_*` table because ALL of a tenant's tables live in ONE JSON document that `Store.get`
+# deep-copies per request (D-87: four Odoo databases = 20.7 MB, ~370 ms a copy). Orders at
+# **32,826** is already 55% of that ceiling; order lines (**255,286**) are 4.3× over it and GL
+# lines (**971,034**) 16× over, so those two could never be grids at all — `odoo_relational.plan`
+# refuses them rather than truncating, which is the correct refusal of the wrong architecture.
+#
+# ⭐ "NO CAP" IS NOT A BIGGER NUMBER. Raising `MAX_ROWS` would make every request slower for every
+# tenant, including the ones who never open an Odoo grid. The mirror ALREADY holds all of it
+# uncapped — measured on this box: 963,783 GL lines counted in ~24 ms — so the fix is to stop
+# copying and serve a WINDOW: the requested slice, plus a `SELECT count(*)` that tells the truth
+# about the whole.
+#
+# ⛔⛔ `total` IS NEVER `len(rows)`. It comes from `datastore.window`'s own count statement over
+# the SAME predicate. A window whose count is its own length is a fabricated aggregate wearing an
+# authoritative face ([[no-unverifiable-aggregates]]).
+#
+# ⛔ PREDICATES PUSH DOWN, and this is the half a client cannot be trusted with. A filter chip
+# evaluated over the 200 rows that happen to be in memory would report "40 matches" out of
+# 971,034 — [[one-question-two-normalizers]] at scale. `harness/filter_sql.py` compiles OUR filter
+# vocabulary to SQL and is the same evaluator the TS engine is held in step with, so the fold and
+# the display answer one question.
+#
+# ⭐ THE SPEC BELOW IS A SECOND STATEMENT OF SOMETHING `odoo_relational`'s READER ALREADY SAYS,
+# AND THAT IS THE REAL RISK HERE — not SQL injection. It is gated rather than trusted:
+# `verify_scopes.section_read_through` runs the REAL reader over the REAL mirror as an ORACLE and
+# asserts the windowed path agrees ROW FOR ROW and TOTAL FOR TOTAL. A binding that drifts from its
+# reader goes red; a bucket with no binding is REPORTED, never silently served from the copy as
+# though it were read-through ([[one-evaluator-per-question]], [[gate-answers-the-wrong-question]]).
+#
+# ⚠ ONE BUCKET IS BOUND HERE (orders). The other seven still serve from the materialised copy and
+# say so on the wire (`readThrough: false`), because R6's second sentence — *"if there is lag or
+# it can't be done, you need to explicitly tell me why and recommend a fix"* — makes an unconverted
+# grid something to REPORT, not something to leave looking converted. Adding one is a spec row plus
+# a green oracle check.
+
+#: `ut_*` key -> how to read that grid straight out of the mirror.
+#:
+#: `where`/`select` are SQL WE author (never a request value); every request value is bound through
+#: `params` by `filter_sql`. `cols` maps a FIELD KEY (what `odoo_relational.<x>_fields()` declares,
+#: and what a saved view's filters name) to `(sql expression, coercion)`. The coercion reproduces
+#: the reader's own python cast, by CALLING the reader's helpers where one exists — `_as_date` and
+#: `_in_scope` are imported, not re-implemented.
+#: Keys a reader does not produce (link columns, `refreshed`) are absent here on purpose: they are
+#: filled by the grid at render time exactly as they are on the materialised path.
+GRID_SOURCES = {}
+
+
+def _sources():
+    """Build `GRID_SOURCES` lazily — it names `odoo_relational` constants, and importing that
+    module at file-import time would drag the Odoo layer into every process that mounts a router.
+    """
+    if GRID_SOURCES:
+        return GRID_SOURCES
+    rel = _rel()
+    # ⭐ R6 / W30-T29 — TELL THE STORE LAYER WHICH DATABASES ARE CONNECTED, so `MAX_ROWS` stops
+    # being a fact about them. `core` never imports up, so the declaration goes this way round.
+    # ⚠ ALL EIGHT, not just the read-through-bound one: every row in these tables comes from Odoo,
+    # which is what R6 is about — being served from the stored copy today is our conversion state,
+    # not a property of the data.
+    _ut().register_connected(*[key for _b, key, _l, _f in rel.TABLES])
+    _s, _i, _n = ((lambda v: str(v or "")), (lambda v: int(v or 0)),
+                  (lambda v: float(v or 0.0)))
+    GRID_SOURCES[rel.ORDERS_KEY] = {
+        "table": "sale_order",
+        # ⛔ IMPORTED, NOT RETYPED. `_CONFIRMED` is the fixed wholesale scope; if it ever changes,
+        # this window changes with it and the oracle check proves it did.
+        "where": f"{rel._CONFIRMED} AND partner_id IS NOT NULL",
+        "id": "id",
+        "needs_excluded": True,          # `wholesale_scope` is resolved against the excluded set
+        "cols": {
+            "order_no": ("name", _s),
+            "odoo_id": ("id", _i),
+            "customer": ("partner_name", _s),
+            rel.JOIN_KEY: ("partner_id", _i),
+            "order_date": ("date_order", rel._as_date),
+            "amount_untaxed": ("amount_untaxed", _n),
+            "team": ("team_name", _s),
+            "state": ("state", _s),
+            "invoice_status": ("invoice_status", _s),
+            # ⭐ THE SCOPE COLUMN BECOMES REAL SQL, which is the point. On the materialised path it
+            # is `_in_scope(pid, excluded)` — a python set test, and a filter on it therefore could
+            # not push down. Inlining the ids (ints, from our own query) makes it a column the
+            # mirror can filter and sort on, so the R6 "limit" it would otherwise have earned does
+            # not exist. `{excluded}` is substituted by `_source_for` below.
+            "wholesale_scope": ("CASE WHEN partner_id IN ({excluded}) THEN '' ELSE '1' END", _s),
+        },
+    }
+
+    # ═════════════════════════════════════════════════════════════════════════════════════════
+    # ⭐⭐ W30-T32 — THE TWO LINE GRAINS. These are the grids R6 exists for: they have never had a
+    # `ut_*` table and never can, at any cap. MEASURED on this box's mirror, warm:
+    #   sale_order_line     254,189 in the confirmed scope (256,810 unscoped) — 63.9 MB as JSON
+    #   account_move_line   963,783                                           — ~240 MB as JSON
+    # Against `MAX_ROWS = 60_000` that is 4.2x and 16x, and against the 32 MB per-table document
+    # budget it is 2x and 7.5x. Read THROUGH, both serve a page in 134–166 ms.
+    #
+    # ⛔ THE FIELD KEYS BELOW ARE HALF OF A CONTRACT AND `odoo_relational` OWNS THE OTHER HALF
+    # (W30-T35, session E). `cols` binds a field key to SQL; the field's label, type and order are
+    # DECLARED THERE, once. Until that declaration lands the route answers 404 for these two keys
+    # (`rel.TABLES` has no entry), and `odoo_tables_status` REPORTS them as bound-not-declared
+    # rather than leaving them invisible — R6's second sentence applied to our own conversion.
+    # ⚠ A key here with no declaration there is a silent NO-CELL (`rows_from_pool` projects
+    # strictly); a key there with no binding here is an INACTIVE filter leaf, which WIDENS. The
+    # two lists are checked against each other by `verify_scopes.section_line_grids`.
+    ol_key = getattr(rel, "ORDER_LINES_KEY", "ut_odoo_order_lines")
+    gl_key = getattr(rel, "GL_LINES_KEY", "ut_odoo_gl_lines")
+    _ut().register_connected(ol_key, gl_key)
+    # ⛔ THE SCOPE IS THE ORDER'S, AND THE LINE TABLE CANNOT ANSWER IT ALONE: `sale_order_line`
+    # carries no `state` (12 columns, measured), so the confirmed-order scope — and `order_date`,
+    # and the order NAME a person reads the grid by — only exist across the join. MEASURED, warm,
+    # best of two: the JOIN beats `order_id IN (SELECT id FROM sale_order WHERE …)` at both depths
+    # (166 / 483 ms against 237 / 565 ms at offset 0 / 200,000), so the shape is chosen on a
+    # number rather than on taste.
+    # ⚠ `_CONFIRMED` is IMPORTED and QUALIFIED, never retyped — it opens with the bare column
+    # `state`, which `sale_order_line` does not have, so the prefix is what keeps it unambiguous
+    # if that table ever gains one. `section_line_grids` counts the same population a second way
+    # (a subquery, not a join) and the two must agree, which is what catches a mis-qualification.
+    GRID_SOURCES[ol_key] = {
+        "from_sql": "(sale_order_line sol JOIN sale_order so ON so.id = sol.order_id)",
+        "tables": {"sol": "sale_order_line", "so": "sale_order"},
+        "where": f"so.{rel._CONFIRMED}",
+        "id": "sol.id",
+        "needs_excluded": True,
+        "cols": {
+            "odoo_id": ("sol.id", _i),
+            "order_no": ("so.name", _s),
+            "order_id": ("sol.order_id", _i),
+            "customer": ("sol.order_partner_name", _s),
+            rel.JOIN_KEY: ("sol.order_partner_id", _i),
+            "product": ("sol.product_name", _s),
+            rel.PRODUCT_JOIN_KEY: ("sol.product_id", _i),
+            "qty": ("sol.product_uom_qty", _n),
+            "price_subtotal": ("sol.price_subtotal", _n),
+            "margin": ("sol.margin", _n),
+            "purchase_price": ("sol.purchase_price", _n),
+            "order_date": ("so.date_order", rel._as_date),
+            "state": ("so.state", _s),
+            "wholesale_scope": (
+                "CASE WHEN sol.order_partner_id IN ({excluded}) THEN '' ELSE '1' END", _s),
+        },
+    }
+    # ⚠ UNSCOPED ON PURPOSE, and it is a decision rather than an omission: every other grid here
+    # carries a fixed scope, but a GENERAL LEDGER whose draft and cancelled entries are invisible
+    # is a ledger that cannot be reconciled. `parent_state` rides as a column so a person filters
+    # in SQL over all 963,783 rows instead of us choosing for them. (Posted-only is 944,846.)
+    # The join to `account_account` is what makes `account_code` — the key `ut_odoo_accounts` is
+    # linked on — available at all; the mirror flattens `account_id`/`account_name` onto the line
+    # but not the CODE, and 192 accounts hash-join for free.
+    GRID_SOURCES[gl_key] = {
+        "from_sql": ("(account_move_line aml LEFT JOIN account_account aa "
+                     "ON aa.id = aml.account_id)"),
+        "tables": {"aml": "account_move_line", "aa": "account_account"},
+        "where": "",
+        "id": "aml.id",
+        "needs_excluded": True,
+        "cols": {
+            "odoo_id": ("aml.id", _i),
+            "entry": ("aml.move_name", _s),
+            "move_id": ("aml.move_id", _i),
+            "account": ("aml.account_name", _s),
+            rel.ACCOUNT_JOIN_KEY: ("aa.code", _s),
+            "customer": ("aml.partner_name", _s),
+            rel.JOIN_KEY: ("aml.partner_id", _i),
+            "date": ("aml.date", rel._as_date),
+            "debit": ("aml.debit", _n),
+            "credit": ("aml.credit", _n),
+            "balance": ("aml.balance", _n),
+            "line_type": ("aml.display_type", _s),
+            "move_type": ("aml.move_type", _s),
+            "parent_state": ("aml.parent_state", _s),
+            "wholesale_scope": (
+                "CASE WHEN aml.partner_id IN ({excluded}) THEN '' ELSE '1' END", _s),
+        },
+    }
+    # ⭐ W30-T31 — THE GL ACCOUNT REGISTRY, BOUND BECAUSE IT IS THE ONE GRID THAT CAN ACTUALLY
+    # STOP MATERIALISING TODAY. 192 rows, nothing folds it, nothing links at it, and it fits
+    # inside one window — the three conditions `_unmaterialisable` checks. It is small, and that
+    # is the point: it is the first shipped database whose rows are NOT in the tenant document,
+    # so the stratum is proven on a real table instead of on a mechanism with no subject.
+    # ⚠ `account_fields()` declares six columns and `read_accounts` is one `cur.execute` over
+    # `account_account`; `section_read_through`'s differential oracle holds this binding to it.
+    # ⚠ `is_expense` REPRODUCES `read_accounts`' predicate IN SQL rather than inventing one, and
+    # that predicate is itself a copy of the semantic layer's `gl_lines` scope. Three statements of
+    # one rule is two too many, but the reader's own comment explains why it is copied rather than
+    # imported, and `section_read_through`'s differential oracle is what keeps this one honest.
+    GRID_SOURCES[rel.ACCOUNTS_KEY] = {
+        "table": "account_account",
+        "where": "",
+        "id": "id",
+        "cols": {
+            rel.ACCOUNT_JOIN_KEY: ("code", _s),
+            "account_name": ("name", _s),
+            "odoo_id": ("id", _i),
+            "account_type": ("account_type", _s),
+            "is_expense": ("CASE WHEN account_type IN ('expense','expense_depreciation') "
+                           "THEN '1' ELSE '' END", _s),
+        },
+    }
+    return GRID_SOURCES
+
+
+def sync_read_through(cur=None):
+    """Register every grid that may stop storing rows, and REPORT why the rest may not.
+
+    Returns `({key: eligible}, {key: reason})`. Idempotent, cheap, and safe to call from any door:
+    registration is additive and `strip_materialised` is a no-op once a table is empty.
+
+    ⛔ IT IS ALSO THE ONLY PLACE THAT MAY CALL `register_read_through`, because the eligibility
+    question needs BOTH halves — `odoo_relational`'s field declarations (for the fold matrix) and
+    the mirror (for the size) — and `core` may import neither.
+    """
+    eligible, reasons = _unmaterialisable(cur)
+    keys = [k for k, ok in eligible.items() if ok]
+    if keys:
+        _ut().register_read_through(*keys)
+    return eligible, reasons
+
+
+#: ⚠ A mirror can be `ready()` and still lack a column (`ready()` reads entity PHASES; column
+#: backfills checkpoint separately) — the gap that already cost a live 500. Every projected
+#: expression is checked against the real column list and degraded to a literal, exactly as
+#: `odoo_relational._col` does for the reader, so a fresh Space serves a blank cell rather than a
+#: DuckDB Binder error.
+#:
+#: ⛔ W30-T32 — IT TAKES AN ALIAS MAP NOW, AND WITHOUT THAT THE GUARD WAS ABOUT TO GO BLIND. The
+#: line-grain grids project `sol.price_subtotal` / `aml.parent_state`, and a dotted string is not
+#: `isalnum()`, so the old single-table version returned EVERY qualified expression unchecked —
+#: the same "expression, nothing to check" branch that correctly skips a CASE. Both of those
+#: columns are 2026-07-28 backfills that a mirror can genuinely be missing, so the blind spot
+#: would have surfaced as a bare DuckDB Binder error on a fresh Space, which is precisely the
+#: failure this helper exists to prevent ([[gate-answers-the-wrong-question]]).
+# ═════════════════════════════════════════════════════════════════════════════════════════════
+# ⭐⭐ W30-T31 / D-87 — WHICH CONNECTED GRIDS MAY STOP MATERIALISING, AND WHY MOST MAY NOT YET.
+# ═════════════════════════════════════════════════════════════════════════════════════════════
+#
+# The prize is real: all of a tenant's `ut_*` tables live in ONE document that `Store.get`
+# deep-copies on EVERY call, hit or miss, and the four original Odoo grids are 20.7 MB / ~370 ms
+# of it. Every permission check in the app pays that.
+#
+# ⛔ AND YOU CANNOT SIMPLY DELETE THE ROWS, WHICH IS THE FINDING THIS FUNCTION ENCODES. Measured
+# mechanically across the eight field declarations, not by eye:
+#   * `ut_odoo_invoices` and `ut_odoo_orders` — 16.2 of those 20.7 MB — are folded by SIX link
+#     rollups on `ut_odoo_customers` (`ar_outstanding`, `open_invoices`, `oldest_due`,
+#     `invoiced_all_time`, `order_count`, `last_order`). `automation_engine.compute_relation_cells`
+#     answers those by reading the RAW document, so with the rows gone it writes zeros — silently.
+#   * every table with a `link` pointing AT it (agents, vendors, bills, customers) has its link
+#     CELLS materialised the same way, from the target's stored rows.
+#   * `ut_odoo_customers` and `ut_odoo_products` carry SOURCE rollups, and `rollup_sql.compute`
+#     writes those cells INTO their own stored rows: no rows, no cells.
+#   * and while the grid client still asks for a whole table (F's W30-T42 is what changes this),
+#     a population larger than one window could only be served by TRUNCATING it — which R6
+#     forbids more strongly than it forbids a cap.
+#
+# ⭐ SO THE PREDICATE IS DERIVED FROM THE DECLARATIONS RATHER THAN LISTED. The day a lane converts
+# those six link rollups to SOURCE rollups (`orders_ytd` on that same table is the precedent), or
+# the day the client pages, the affected grids become eligible here with NO code change — and
+# until then each one's reason is reported per table on the status door, which is R6's second
+# sentence applied to our own conversion state.
+def _fold_reasons(rel):
+    """`{table_key: "why its stored rows are still read by something else"}`.
+
+    Read out of the FIELD DECLARATIONS themselves — one pass over `rel.TABLES`. A table absent
+    from this map is folded by nothing.
+    """
+    reasons = {}
+
+    def _add(key, why):
+        reasons.setdefault(str(key), []).append(why)
+
+    for _bucket, key, _label, mk in rel.TABLES:
+        try:
+            fields = mk()
+        except Exception:                                             # noqa: BLE001
+            continue
+        by_key = {f.get("key"): f for f in fields if isinstance(f, dict)}
+        short = str(key).replace("ut_odoo_", "")
+        for f in fields:
+            if not isinstance(f, dict):
+                continue
+            if f.get("type") == "link" and (f.get("link") or {}).get("table"):
+                _add(f["link"]["table"], f"{short}.{f['key']} is a link whose cells are built "
+                                         f"from these rows")
+            if f.get("type") != "rollup":
+                continue
+            bag = f.get("rollup") or {}
+            if isinstance(bag.get("source"), dict):
+                _add(key, f"{short}.{f['key']} is a source rollup and its cells are written "
+                          f"into these rows")
+                continue
+            tgt = ((by_key.get(str(bag.get("link") or "")) or {}).get("link") or {}).get("table")
+            if tgt:
+                _add(tgt, f"{short}.{f['key']} folds these rows")
+    return {k: "; ".join(v) for k, v in reasons.items()}
+
+
+def _unmaterialisable(cur=None):
+    """`({key: eligible}, {key: reason})` — who may stop storing rows, and why the rest may not.
+
+    ⛔ SIZE FORCES READ-THROUGH; IT NEVER BLOCKS IT — and getting that backwards was a real bug in
+    the first cut of this function. A table too big for the tenant document has NO materialised
+    option at all, so making it ineligible would have handed `odoo_relational.plan` a `row_limit`
+    of None and invited it to build 963,783 python dicts. The window ceiling is a different, much
+    softer thing: it only limits what the whole-table CLIENT door can serve today.
+
+        rows > MAX_ROWS            -> read-through REQUIRED (the document cannot hold it)
+        else if something folds it -> stays materialised (a fold over no rows writes ZEROS)
+        else if rows > WINDOW_MAX  -> stays materialised until the client pages (W30-T42)
+        else                       -> eligible
+
+    ⚠ Without a mirror cursor the size questions cannot be asked, so only a grid that was never
+    part of the materialised spawn is eligible — a table is never freed by a question we skipped.
+    """
+    rel = _rel()
+    folds, eligible, reasons = _fold_reasons(rel), {}, {}
+    # ⛔ "WAS THIS PART OF THE MATERIALISED SPAWN?", and being in `TABLES` STOPPED ANSWERING IT.
+    # W30-T35 declared the two line grains, which have no python row builder anywhere — their
+    # absence from `_READERS` IS that statement — so a table the spawn could never materialise
+    # started reading as spawned, and on a mirror-less deployment fell through to "its size could
+    # not be read" and came back INELIGIBLE. That inverts this function's own first law (size
+    # forces read-through; it never blocks it). Ask the question through the reader map, which is
+    # what actually decides whether a row could ever have been built.
+    spawned = {key for _b, key, _l, _f in rel.TABLES if _b in getattr(rel, "_READERS", {})}
+    from harness import datastore
+    ut = _ut()
+    for key, spec in _sources().items():
+        total = None
+        if cur is not None:
+            try:
+                frm = ({"from_sql": spec["from_sql"]} if spec.get("from_sql")
+                       else {"table": spec["table"]})
+                total = datastore.window(select="1", where=spec.get("where") or "",
+                                         order_by=spec["id"], limit=1, cur=cur, **frm)["total"]
+            except Exception:                                         # noqa: BLE001
+                total = None
+        if total is not None and total > ut.MAX_ROWS:
+            eligible[key] = True                  # no other home exists; this is not a choice
+            continue
+        if total is None and key not in spawned:
+            eligible[key] = True                  # never materialised, so the mirror is its home
+            continue
+        why = []
+        if total is None:
+            why.append("its size could not be read from the mirror on this deployment")
+        if key in folds:
+            why.append(folds[key])
+        if total is not None and total > datastore.WINDOW_MAX:
+            why.append(f"its {total:,} rows exceed the {datastore.WINDOW_MAX:,}-row window and "
+                       f"the grid client still asks for whole tables, so un-materialising it "
+                       f"today could only truncate")
+        eligible[key] = not why
+        if why:
+            reasons[key] = "; ".join(why)
+    return eligible, reasons
+
+
+def _degrade(expr, have_by_alias, default_alias=""):
+    bare = expr.strip()
+    alias, _, col = bare.partition(".")
+    if col and alias.replace("_", "").isalnum() and col.replace("_", "").isalnum():
+        have = have_by_alias.get(alias)
+        if have is None:
+            return expr                   # an alias we do not own — leave it to the caller's SQL
+        return expr if col.lower() in have else "NULL"
+    if not bare.replace("_", "").isalnum():
+        return expr                       # an expression, not a bare column — nothing to check
+    # ⚠ A BARE COLUMN IN A JOINED SPEC RESOLVES THE WAY SQL RESOLVES IT — against every table in
+    # the FROM, not against nothing. Checking it against `have_by_alias[""]`, which a joined spec
+    # does not have, would degrade every such column to NULL: a silent blank cell, which is the
+    # failure this helper exists to avoid rather than to cause.
+    have = have_by_alias.get(default_alias)
+    if have is None:
+        have = set().union(*have_by_alias.values()) if have_by_alias else set()
+    return expr if bare.lower() in have else "NULL"
+
+
+def _source_for(cur, table_key):
+    """The resolved spec for one connected grid, or None when this grid is not read-through yet."""
+    spec = _sources().get(str(table_key or ""))
+    if not spec:
+        return None
+    from harness import datastore
+    # ⚠ `tables` maps the SQL alias a projection uses to the mirror table behind it. A single-table
+    # spec declares none and its columns are bare, so it degrades against `table` as before.
+    aliases = dict(spec.get("tables") or {})
+    if spec.get("table"):
+        aliases.setdefault("", spec["table"])
+    have_by_alias = {}
+    for alias, tname in aliases.items():
+        cols = datastore.columns_of(tname, cur=cur)
+        if not cols:
+            return None                   # the mirror has no such table on this deployment
+        have_by_alias[alias] = cols
+    excluded = ""
+    if spec.get("needs_excluded"):
+        ids = sorted(int(p) for p in _rel().excluded_ids(cur))
+        # `-1` keeps the IN-list non-empty and matches no Odoo id, so the SQL shape is constant
+        # whether or not this tenant excludes a channel.
+        excluded = ", ".join(str(i) for i in ids) or "-1"
+    cols = {}
+    for key, (expr, cast) in spec["cols"].items():
+        cols[key] = (_degrade(expr.format(excluded=excluded) if "{excluded}" in expr else expr,
+                              have_by_alias), cast)
+    return {**spec, "cols": cols}
+
+
+#: How deep a page has to be before the walk is worth a sentence. Derived from the measurement in
+#: the route below, not chosen: 100,000 is still 71 ms, 200,000 is 483 ms, and the second half of
+#: the GL table is where it passes a second. Reporting from 100,000 puts the sentence in front of
+#: the person BEFORE the wait rather than after it.
+_DEEP_PAGE = 100_000
+
+
+#: `filter_sql` speaks the CLIENT's type vocabulary (`types.ts isNumericType`), and two of our
+#: field kinds are spelled differently there. Mapped in one place so the pushdown and the grid
+#: cannot disagree about whether a column is text or a number.
+_FILTER_TYPE = {"select": "status", "checkbox": "text"}
+
+
+def _filter_columns(spec, fields):
+    """`{colId: {sql, type, aggregate}}` — what `filter_sql` needs to compile a predicate.
+
+    Only columns with a real mirror expression are offered. An omitted column is UNKNOWN to the
+    compiler, which skips it — and that is the one behaviour that must be REPORTED rather than
+    accepted, because an ignored condition WIDENS (the tri-state engine's inactive-leaf rule).
+    `_unpushable` below turns every such skip into an R6 sentence.
+    """
+    by_key = {f["key"]: f for f in fields}
+    out = {}
+    for key, (expr, _cast) in spec["cols"].items():
+        ftype = str((by_key.get(key) or {}).get("type") or "text")
+        out[key] = {"sql": expr, "type": _FILTER_TYPE.get(ftype, ftype), "aggregate": False}
+    return out
+
+
+def _leaf_cols(nodes):
+    """Every `colId` a filter tree names, at any depth."""
+    seen = set()
+    for n in (nodes or []):
+        if not isinstance(n, dict):
+            continue
+        if n.get("children") is not None:
+            seen |= _leaf_cols(n.get("children"))
+        elif n.get("colId"):
+            seen.add(str(n["colId"]))
+            rhs = n.get("rhs")
+            if isinstance(rhs, dict) and rhs.get("colId"):
+                seen.add(str(rhs["colId"]))
+    return seen
+
+
+def _json_arg(raw, what):
+    """Decode a JSON query argument, or refuse. ⛔ NEVER degrade to "no filter": a filter that
+    silently fails to parse WIDENS the answer, and the caller sees a plausible bigger number."""
+    if raw in (None, ""):
+        return None
+    try:
+        val = json.loads(raw)
+    except Exception:                                                 # noqa: BLE001
+        raise err(400, "bad_argument", f"{what} must be JSON")
+    return val
+
+
+@router.get("/odoo-tables/{table_key}/rows")
+def odoo_table_rows(table_key: str,
+                    offset: int = Query(default=0, ge=0),
+                    limit: int = Query(default=0),
+                    filters: str = Query(default=None),
+                    filterConj: str = Query(default="and"),
+                    sorts: str = Query(default=None),
+                    search: str = Query(default=None),
+                    session: Session = Depends(require_session)):
+    """ONE WINDOW over a connected grid, read straight from the mirror (contract C2).
+
+    `{fields, rows, total, totalUnfiltered, offset, limit, limits, identity, recordsMutable}` —
+    `rows` is the requested slice and `total` is the count of everything the CURRENT PREDICATE
+    matches, from its own `SELECT count(*)`. `rows.length < total` is the normal case.
+
+    ⛔ `total` is never `len(rows)`; `totalUnfiltered` is the population with the predicate
+    dropped, so a client can render "N of M" without inventing either number.
+    ⛔ The filter, the sort and the search all resolve in SQL against the whole table. Anything
+    that CANNOT (a column with no mirror expression, an op the compiler refuses) is reported in
+    `limits` with its cause and a recommendation — R6's second sentence — and never silently
+    dropped, because an ignored condition widens.
+    """
+    import aios_grid
+    from harness import datastore
+    from routes_tables import _defn_or_refuse
+
+    rel = _rel()
+    # THE WALL FIRST, and it is the SAME one the materialised path uses — 404 for a key that does
+    # not exist, 403 for one this session may not open. Reused rather than re-stated: a second
+    # idea of "may this session open this database" is a permission bug waiting to happen.
+    defn = _defn_or_refuse(session, table_key)
+    fields = None
+    for _bucket, key, _label, mk_fields in rel.TABLES:
+        if key == table_key:
+            fields = mk_fields()
+            break
+    if fields is None:
+        raise err(404, "not_connected", "that database is not a connected Odoo grid")
+
+    try:
+        cur = datastore.ro_con()
+    except RuntimeError as e:
+        # The mirror is mid-first-sync. Relaying it beats serving a window over a partial table.
+        raise err(503, "store_not_ready", str(e))
+
+    spec = _source_for(cur, table_key)
+    if spec is None:
+        raise err(409, "not_read_through",
+                  "this connected database is still served from its stored copy; it has no "
+                  "read-through binding on this deployment yet")
+
+    cols = _filter_columns(spec, fields)
+    limits, tree = [], _json_arg(filters, "filters")
+    sort_spec = _json_arg(sorts, "sorts") or []
+
+    # ── the predicate, pushed down ────────────────────────────────────────────────────────────
+    named = _leaf_cols(tree)
+    missing = sorted(named - set(cols))
+    if missing:
+        limits.append({
+            "subject": ", ".join(missing), "effect": "filter_ignored",
+            "cause": "these columns have no expression in the mirror (a link, a rollup, or a "
+                     "column this deployment's mirror has not backfilled), so a condition on "
+                     "them cannot be answered in SQL",
+            "recommendation": "filter on the id column the link is built from, or open the "
+                              "linked database directly"})
+    # ⭐ R6, MEASURED, AND IT IS THE KIND OF LIMIT THE RULING EXISTS FOR — a difference in the
+    # ANSWER, not in the speed.
+    #
+    # `filter_sql._value_sql` compiles every numeric comparison as `round_even(x, 0)`, and says
+    # why: *"reproduces `aios_grid._round` … The grid displays rounded values; filters must agree
+    # with what is on screen."* That is true of `source: "odoo"` columns, which `rows_from_pool`
+    # rounds. It is FALSE here — these columns are `source: "overlay"` (a storage choice, not a
+    # display one) so `rows_from_pool` passes the exact value through, and the TS engine
+    # (`useVisibleRows.toNum`) does not round either. So the pushdown compares at whole units while
+    # the cell beside it carries cents.
+    #
+    # MEASURED on the live orders mirror (32,700 rows, 47.9% with a non-integer amount):
+    #   > 1000     python 4,476  vs SQL 4,473   (-3)
+    #   > 173.6    python 24,711 vs SQL 24,726  (+15)
+    #   > 500.25   python 11,028 vs SQL 11,026  (-2)
+    # Small, and NOT nothing. Rounding the wire to match would have been the other fix and it was
+    # rejected on measurement: it changes 96 of every 200 money cells (173.55 -> 174) to remove a
+    # 0.05% counting difference — a visible product regression traded for an invisible one.
+    # ⛔ SO IT IS REPORTED INSTEAD. Booked for the owner of `harness/filter_sql.py`, which is not
+    # this fence; see mailbox/D.md.
+    numeric = sorted(k for k in (named & set(cols))
+                     if cols[k]["type"] in ("currency", "int", "pct"))
+    if numeric:
+        limits.append({
+            "subject": ", ".join(numeric), "effect": "precision",
+            "cause": "a number condition is evaluated in SQL at whole-unit precision "
+                     "(`filter_sql` rounds to match the grids whose values the server rounds), "
+                     "while these cells carry their exact value — so a row within half a unit of "
+                     "the threshold can fall on the other side of it",
+            "recommendation": "compare against a whole number, or use a range that does not sit "
+                              "on a fractional boundary"})
+
+    where, params = spec["where"], []
+    try:
+        pred = _fs().compile_filter_tree(
+            tree, conj=(filterConj if filterConj in ("and", "or") else "and"), columns=cols,
+            today=_today())
+    except ValueError as e:
+        # ⛔ A REFUSAL IS AN ANSWER, NOT A CRASH — and it must not become "no filter". Ranking ops
+        # ("top 10") have no SQL form in this compiler; saying so beats returning every row.
+        raise err(400, "filter_unsupported", str(e))
+    if pred is not None:
+        if pred.uses_aggregate:
+            raise err(400, "filter_unsupported",
+                      "a condition on an aggregate column belongs in HAVING, and that path is "
+                      "deliberately not built for windowed grids")
+        where = f"({where}) AND {pred.sql}" if where else pred.sql
+        params.extend(pred.params)
+    if str(search or "").strip():
+        got = _fs().compile_search(search.strip(), cols)
+        if got is not None:
+            where = f"({where}) AND {got.sql}" if where else got.sql
+            params.extend(got.params)
+
+    # ── the order, made TOTAL ─────────────────────────────────────────────────────────────────
+    # ⛔ `tiebreak_sql` is not optional here: without a total order, LIMIT/OFFSET may return one
+    # row on two pages and drop another entirely — a duplicate the user sees with no error
+    # anywhere. `compile_order_by`'s own docstring says so.
+    order = _fs().compile_order_by(sort_spec, cols, tiebreak_sql=spec["id"]) or spec["id"]
+
+    select = ", ".join(f'{expr} AS "{key}"' for key, (expr, _c) in spec["cols"].items())
+    # ⚠ EXACTLY ONE of `table`/`from_sql` — `window` raises if both or neither arrive, so the
+    # spec's own shape decides and a malformed spec fails loudly instead of serving a wrong FROM.
+    frm = {"from_sql": spec["from_sql"]} if spec.get("from_sql") else {"table": spec["table"]}
+    win = datastore.window(select=f'{spec["id"]} AS "_pid", {select}',
+                           where=where, params=tuple(params), order_by=order,
+                           offset=offset, limit=(limit or None), cur=cur, **frm)
+    if win["clamped"]:
+        limits.append({
+            "subject": "limit", "effect": "window_clamped",
+            "cause": f"one response carries at most {datastore.WINDOW_MAX} rows so a single "
+                     f"request cannot exhaust memory for every other tenant on the process",
+            "recommendation": "page with `offset`; `total` already reports the whole population, "
+                              "and no row is unreachable"})
+    # ⭐ R6's SECOND SENTENCE, ON THE ONE LIMIT THAT SURVIVES THE CONVERSION. Removing the row cap
+    # does not make every row equally cheap: `LIMIT/OFFSET` WALKS the offset, so the deeper the
+    # page the longer the scan. MEASURED warm on 963,783 GL lines — offset 0: 134 ms · 100,000:
+    # 71 ms · 900,000: **1,450 ms**; sorted by date rather than by id, offset 500,000: 1,645 ms.
+    # It is a real cost, it is nobody's mistake, and the owner asked to be told rather than to
+    # discover it: say so with the fix, which is a CURSOR the client has to send.
+    if offset >= _DEEP_PAGE:
+        limits.append({
+            "subject": "offset", "effect": "slow",
+            "cause": f"a page {offset:,} rows deep is reached by walking every row before it "
+                     f"(SQL OFFSET has no other meaning), which costs about a second past "
+                     f"half a million rows",
+            "recommendation": "jump with a filter or a sort instead of scrolling, or ask for "
+                              "keyset paging (`id > <last row>`), which is O(page) at any depth "
+                              "and needs the client to send the last row it holds"})
+
+    # ── the wire rows, through the SAME serialiser the materialised path uses ──────────────────
+    rows_src = _pool_from_window(spec, win)
+    overlays = {str(r["pid"]): {k: v for k, v in r.items() if k != "pid"} for r in rows_src}
+
+    # ⭐⭐ W30-T28 — THE TENANT-WIDE OVERLAY, ON A READ-THROUGH GRID.
+    #
+    # A user-added column on a connected grid has nowhere per-user to live: there is no `ut_*` row
+    # to hang it on any more, and `table_store`'s per-user strata would make a SHARED view name a
+    # column other accounts do not have — an unknown column is an INACTIVE condition in the
+    # tri-state engine, which WIDENS. `core/shared_overlay.py` was built for exactly this and has
+    # had no product door since it shipped (W29-T62).
+    #
+    # ⛔ `cells(table_key, pids)` TAKES THE PIDS AND THERE IS NO "EVERYTHING" CALL — and here that
+    # is an asset rather than a chore: **the window IS the scoped row set**, already narrowed by
+    # the wall and the predicate, so the argument it demands is the list we just fetched.
+    # ⚠ It is NOT a permission wall (its header says so twice); `_defn_or_refuse` above already
+    # answered "may this session open this surface".
+    shared_defs = _so().fields(table_key, st=session.runtime)
+    if shared_defs:
+        fields = list(fields) + [dict(f, source="overlay") for f in shared_defs.values()]
+        for pid, cells in _so().cells(table_key, [r["pid"] for r in rows_src],
+                                      st=session.runtime).items():
+            overlays.setdefault(pid, {}).update(cells)
+    rows = aios_grid.rows_from_pool(rows_src, fields, overlays)
+
+    unfiltered = win["total"] if where == spec["where"] else datastore.window(
+        select="1", where=spec["where"], order_by=spec["id"], limit=1, cur=cur, **frm)["total"]
+
+    return {"ok": True, "fields": fields, "rows": rows,
+            # ⛔ FROM THE COUNT STATEMENT. Never `len(rows)`.
+            "total": win["total"], "totalUnfiltered": unfiltered,
+            "offset": win["offset"], "limit": win["limit"], "limits": limits,
+            "today": _today(), "identity": {"pid": "pid"},
+            "scope": {"table": table_key, "readThrough": True},
+            "recordsMutable": bool(defn.get("recordMode") != _ut().AUTOMATION_RECORD_MODE)}
+
+
+def _pool_from_window(spec, win):
+    """`[{pid, **cells}]` — THE one place a mirror window becomes product rows.
+
+    ⛔ ONE BUILDER, TWO CALLERS, and that is deliberate rather than tidy: the windowed route and
+    the whole-table read-through below would otherwise each cast the same columns their own way,
+    and a cell that renders differently depending on which door served it is this repo's recorded
+    defect class ([[one-question-two-normalizers]]).
+    """
+    keys = list(spec["cols"])
+    return [{"pid": int(r[0]),
+             **{k: spec["cols"][k][1](v) for k, v in zip(keys, r[1:])}} for r in win["rows"]]
+
+
+class TooBigToMaterialise(Exception):
+    """A read-through table asked for WHOLE exceeds one window — refuse, never truncate."""
+
+
+def whole_pool(table_key, cur=None):
+    """Every row of a read-through grid, in `scoped_pool`'s shape — or a refusal.
+
+    ⚠ THIS EXISTS FOR THE CLIENT WE HAVE, NOT THE ONE WE WANT. The grid still fetches whole
+    tables (`GET /tables/{key}/rows`); paging is F's W30-T42. So a database whose rows have left
+    this tenant's document has to be servable to that client somehow, and the honest answer for a
+    small one is "read all of it from the mirror". `_unmaterialisable` only ever registers a table
+    that fits, so the refusal below is a guard against the population GROWING past the window
+    later — at which point R6 requires a sentence, not a quietly shorter grid.
+    """
+    from harness import datastore
+    cur = cur if cur is not None else datastore.ro_con()
+    spec = _source_for(cur, table_key)
+    if spec is None:
+        raise TooBigToMaterialise(
+            f"{table_key}: this database is served through the mirror but has no read-through "
+            f"binding on this deployment, so its rows cannot be read at all")
+    frm = {"from_sql": spec["from_sql"]} if spec.get("from_sql") else {"table": spec["table"]}
+    select = ", ".join(f'{expr} AS "{key}"' for key, (expr, _c) in spec["cols"].items())
+    win = datastore.window(select=f'{spec["id"]} AS "_pid", {select}', where=spec.get("where"),
+                           order_by=spec["id"], limit=datastore.WINDOW_MAX, cur=cur, **frm)
+    if win["total"] > len(win["rows"]):
+        # ⛔ REFUSE, NEVER TRIM. A short grid that says nothing is exactly the silent truncation
+        # R6's second sentence is about — and the caller turns this into a message with a cause.
+        raise TooBigToMaterialise(
+            f"{table_key}: {win['total']:,} rows is more than one {datastore.WINDOW_MAX:,}-row "
+            f"window, and this database no longer stores rows in the tenant document; it can "
+            f"only be read a page at a time (`/odoo-tables/{table_key}/rows`)")
+    return _pool_from_window(spec, win)
+
+
+def _fs():
+    from harness import filter_sql
+    return filter_sql
+
+
+def _so():
+    import core.shared_overlay as shared_overlay
+    return shared_overlay
+
+
+def _ut():
+    import core.user_tables as user_tables
+    return user_tables
+
+
+def _today():
+    import time
+    return time.strftime("%Y-%m-%d")

api/routes_products.py

@@ -147,6 +147,22 @@ def product_assembly(session: Session, scope: str = "product", storage_key: str
         scope_key="product", table=pd.TABLE_OPS)
     ws = grid_events.table_workspace(ctx, allowed_pids=pids,
                                      consume_corrections=consume_corrections)
+    # ⭐⭐ W30-T36 — THE TENANT-WIDE STRATUM, MERGED OVER THE PER-USER ONE, IN THE ASSEMBLY SO
+    # EVERY CONSUMER SEES ONE TRUTH. `routes_grid`'s /workspace route serves
+    # `workspace["overlays"] = g["ws"].get("overlays")` verbatim, so doing it here means that door
+    # carries shared values with no change in a file this lane does not own.
+    #
+    # ⚠ SAFE TO MUTATE, and that was checked rather than assumed: `table_workspace` reads through
+    # `store.get`, which deep-copies, so `ws` is a detached copy and nothing writes it back. A
+    # shared value can therefore never leak INTO the per-user bucket by way of this merge.
+    # ⚠ SHARED WINS per key — these are contract columns, so the tenant-wide value is the answer
+    # and any per-user leftover under the same key is stale by construction.
+    _shared = pd.shared_cells(pids)
+    if _shared:
+        _ov = dict(ws.get("overlays") or {})
+        for _pid, _cells in _shared.items():
+            _ov[_pid] = {**(_ov.get(_pid) or {}), **_cells}
+        ws["overlays"] = _ov
     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)
@@ -178,9 +194,9 @@ def products(session: Session = Depends(module_gate(MODULE))):
     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"])
+    rows = aios_grid.rows_from_pool(
+        g["rows_src"], g["fields"], g["ws"].get("overlays"), derived=g["derived"])
+    rows = _seed_image(_seed_shared(rows, g["rows_src"], g["fields"]), 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"},
@@ -222,8 +238,14 @@ def patch_product(pid: int, body: dict = Body(default=None),
 
     # 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.
+    # ⚠ W30-T36 — AND FROM THE SHARED BUCKET TOO. The four shared columns are written to
+    # `<TABLE_KEY>__shared` by `_ProductTableStore.patch_overlay`, so a read-back that consulted
+    # only the per-user stratum would find nothing and report every accepted shared write as
+    # `refused` — a correct write reported as a failure, which is the read-path-cannot-witness-
+    # the-write-path shape ([[read-path-cannot-witness-write-path]]).
     stored = (grid_events.table_workspace(ctx, allowed_pids=None)
               .get("overlays") or {}).get(str(pid)) or {}
+    stored = {**stored, **((pd.shared_cells([pid]).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]))
@@ -242,6 +264,47 @@ def patch_product(pid: int, body: dict = Body(default=None),
 PRODUCT_IMAGE_KEY = "image"
 
 
+def _seed_shared(rows, rows_src, fields):
+    """W30-T36 — the supplier master as a per-render DEFAULT for the four SHARED columns.
+
+    Exactly `_seed_image`'s shape and for the same reasons: no migration, and nothing frozen. An
+    untouched grid renders byte-identically to the read-only version it replaces — including
+    `supplier: "(none)"`, which the pool has always stamped — and **empty means "no override"**,
+    so clearing a cell restores the mastersheet value rather than blanking the column.
+
+    ⛔⛔ GATED PER KEY ON THE SERVED FIELD LIST, AND HERE THAT IS A PERMISSION WALL RATHER THAN
+    TIDINESS. `_seed_image`'s docstring predicted this failure in writing — *"An unconditional seed
+    would put the key straight back onto every row AFTER that strip… 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."* **`first_cost` IS that future non-code default**: a money number, and
+    `product_assembly` strips a hidden field from BOTH wires precisely so a restricted reader
+    cannot read it off the row payload. An ungated seed would re-attach it after the strip.
+    (Belt and braces, deliberately: `perm_scope.strip_row` has already removed the key from
+    `rows_src` too, so the pool row cannot supply it either.)
+
+    ⚠ JOINED ON `pid`, never on position: `rows_from_pool` iterates the pool, but nothing in the
+    contract promises the two lists stay index-aligned, and an off-by-one here would put one SKU's
+    supplier on another SKU's row — a wrong answer that looks entirely plausible.
+    """
+    import modules.product_data as pd
+
+    served = {f.get("key") for f in (fields or ())}
+    keys = [k for k in pd.SHARED_KEYS() if k in served]
+    if not keys:
+        return rows
+    by_pid = {r.get("pid"): r for r in (rows_src or ())}
+    for row in rows:
+        src = by_pid.get(row.get("pid")) or {}
+        for key in keys:
+            # A non-empty stored value WINS; only an empty cell is seeded. Blank is therefore
+            # "no override" rather than "blank", which is the documented meaning `_seed_image`
+            # already gives this column family and the only one that keeps the master reachable
+            # after a mistaken edit.
+            if row.get(key) in (None, ""):
+                row[key] = src.get(key)
+    return rows
+
+
 def _seed_image(rows, fields):
     """R7's "auto-seeded from SKU `code`", as a per-render DEFAULT rather than stored data.
 

api/routes_tables.py

@@ -166,6 +166,27 @@ def scoped_pool(session: Session, table_key: str):
     defn = _defn_or_refuse(session, table_key)
     fields_base = [dict(f) for f in (defn.get("fields") or [])]
     field_keys = {f["key"] for f in fields_base}
+    # ⭐⭐ W30-T31 / D-87 — A READ-THROUGH DATABASE HAS NO ROWS HERE, SO THEY COME FROM THE MIRROR.
+    #
+    # This is the one function that turns "what is stored" into "what this session may see", which
+    # is exactly why the read-through arm belongs HERE and nowhere else: the rows route, the events
+    # route, the comments wall and the assembly all reach rows through it, so they all convert
+    # together or not at all. ⛔ Reading `defn["rows"]` for such a table would find `{}` and serve
+    # an EMPTY GRID — correct-looking, wrong, and silent.
+    # ⚠ The wall above has already run. This adds no scope of its own and takes none away.
+    if not _ut().materialises(table_key, st=session.runtime, defn=defn):
+        import routes_odoo_tables
+        try:
+            rows_src = [r for r in routes_odoo_tables.whole_pool(table_key)]
+        except routes_odoo_tables.TooBigToMaterialise as e:
+            # R6's second sentence: a limit that cannot be met is a SENTENCE, never a short grid.
+            raise err(409, "window_required", str(e))
+        except RuntimeError as e:
+            raise err(503, "store_not_ready", str(e))
+        rows_src = [{k: v for k, v in r.items() if k in field_keys or k == "pid"}
+                    for r in rows_src]
+        rows_src.sort(key=lambda r: r["pid"])
+        return frozenset(r["pid"] for r in rows_src), rows_src, fields_base, defn
     rows_src = []
     for rid, row in (defn.get("rows") or {}).items():
         if not str(rid).isdigit():
@@ -180,6 +201,144 @@ def scoped_pool(session: Session, table_key: str):
     return frozenset(r["pid"] for r in rows_src), rows_src, fields_base, defn
 
 
+@router.patch("/tables/{table_key}/shared/{pid}")
+def patch_shared_cell(table_key: str, pid: int, body: dict = Body(default=None),
+                      session: Session = Depends(require_session)):
+    """Write a cell into the TENANT-WIDE overlay — the product door `core/shared_overlay.py` has
+    been waiting for since it shipped (W29-T62, wave 30 T28).
+
+    ⭐ WHY A SEPARATE STRATUM AT ALL, restated because it is the whole feature and it is not
+    "sharing would be nice": a user-created column and its values live PER USER, so a shared view
+    filtering on one names a column other accounts do not have — and an unknown column is an
+    INACTIVE condition in the tri-state engine, which IGNORES it and therefore WIDENS. The buy
+    list would silently show the whole catalogue to everyone but its author. A column whose value
+    is the same for every reader is the precondition for editing it at all.
+
+    ⛔ THE WALL IS `_defn_or_refuse`, AND THE STRATUM IS NOT ONE. `shared_overlay` refuses no
+    reader and no writer by design; "may this session open this surface" is answered HERE, where
+    the session is. Do not push the question down there.
+    ⚠ A tenant-wide write is not a private one: every account that may open this database sees it.
+    That is the point, and it is why this door declares the column too — a value with no
+    definition is a cell nobody can find.
+    """
+    body = body if isinstance(body, dict) else {}
+    key = str(body.get("field") or "").strip()
+    if not key:
+        raise err(400, "bad_request", "a field key is required")
+    _defn_or_refuse(session, table_key)
+    from core import shared_overlay
+    if not shared_overlay.is_shared(table_key, key, st=session.runtime):
+        shared_overlay.put_field(table_key, key, {
+            "key": key, "label": str(body.get("label") or key), "source": "overlay",
+            "type": str(body.get("type") or "text"), "shared": True,
+            "createdBy": session.uname}, st=session.runtime)
+    try:
+        # ⚠ `put_cell`, not `put_cells` — this door writes exactly ONE cell, and the singular is
+        # the API that says so. It delegates to the plural, so both stay reachable through the one
+        # caller; before this, the singular had no caller at all and `verify_reachability` LENS 2
+        # named it (the same lens that found `drop_field` had no door either).
+        stored = {key: shared_overlay.put_cell(table_key, pid, key, body.get("value"),
+                                               st=session.runtime)}
+    except ValueError as e:
+        # A non-scalar RAISES in the stratum rather than being dropped; relay it as the answer.
+        raise err(400, "bad_value", str(e))
+    return {"ok": True, "pid": pid, "cells": stored,
+            "fields": list(shared_overlay.fields(table_key, st=session.runtime))}
+
+
+@router.delete("/tables/{table_key}/shared/fields/{field_key}")
+def delete_shared_field(table_key: str, field_key: str,
+                        session: Session = Depends(require_session)):
+    """Remove a TENANT-WIDE column and every value in it.
+
+    ⛔ WHY THIS EXISTS AT ALL, said plainly: W30-T28 shipped the door that CREATES a shared column
+    and none that removes one, so a column anybody added was permanent for the whole tenant. The
+    reachability gate found it from the other end — `shared_overlay.drop_field` was complete,
+    correct, gated, and callable by nothing but its own gate ([[reachable-is-not-the-same-as-built]]).
+
+    ⛔ AND THIS ONE IS CREATOR-OR-ADMIN, WHICH THE WRITE DOOR IS NOT. Writing a cell changes a
+    value; dropping the column deletes that value for EVERY account at once, so it is the
+    destructive-op wall this repo already uses for a database delete — not `editRole`, which
+    governs renaming and is not a value wall ([[schema-role-is-not-a-value-wall]]).
+    ⚠ `createdBy` is stamped by the write door above; a column stored before that stamp existed
+    is admin-only, which is the safe direction.
+    """
+    _defn_or_refuse(session, table_key)
+    from core import shared_overlay
+    defn = (shared_overlay.fields(table_key, st=session.runtime) or {}).get(str(field_key))
+    if not defn:
+        raise err(404, "unknown_field", "that column is not a shared column on this database")
+    owner = str(defn.get("createdBy") or "")
+    if not session.admin and owner != session.uname:
+        raise err(403, "forbidden",
+                  f"a tenant-wide column can be removed by its creator or an admin — this one "
+                  f"was added by {owner or 'somebody else'}, and dropping it would delete the "
+                  f"value for every account")
+    dropped = shared_overlay.drop_field(table_key, str(field_key), st=session.runtime)
+    return {"ok": True, "dropped": bool(dropped),
+            "fields": list(shared_overlay.fields(table_key, st=session.runtime))}
+
+
+def scoped_pids(session: Session, table_key: str):
+    """`(pids, fields_base, defn)` — the SAME wall and the SAME row set as `scoped_pool`, without
+    building a row.
+
+    ⭐⭐ WAVE 30 / W30-T30 — THIS IS WHY ONE HIDE-FIELDS CHECKBOX WAS EXPENSIVE. A view write
+    (`view_upsert`) reaches `grid_events_route`, which built a FULL assembly purely to validate
+    it: `scoped_pool` allocates a fresh dict per row and then sorts them — ~33k order rows, on
+    every toggle — and the six keys the events route actually reads from that assembly
+    (`fields`, `pids`, `measures`, `measure_sets`, `lists`, `views`) contain no row at all.
+    `rows_src` was computed and discarded.
+
+    ⛔ THE PID SET IS IDENTICAL, NOT MERELY EQUIVALENT, and that is the whole safety argument:
+    `scoped_pool` derives its pids as `frozenset(r["pid"] for r in rows_src)` over exactly the
+    row ids that pass `str(rid).isdigit()`, which is this comprehension with a dict build in the
+    middle. The row WALL is unchanged — a narrower or wider set here would be a permission
+    change, and this is a performance change.
+
+    ⚠ It does NOT make the write cheap on its own: `_defn_or_refuse` still costs two whole-document
+    deep copies (`ut.get` then `may_open`), which is D-87 and W30-T31. This removes the row pass.
+    """
+    defn = _defn_or_refuse(session, table_key)
+    fields_base = [dict(f) for f in (defn.get("fields") or [])]
+    # ⚠ W30-T31: on a read-through database the stored `rows` is `{}` by construction, so the
+    # comprehension below would answer an EMPTY pid set — and the promise this function makes is
+    # that its set is IDENTICAL to `scoped_pool`'s, not merely cheaper. It defers to that function
+    # rather than growing a second idea of the row set; the saving this ticket bought stays on
+    # every materialised table, which is all of the big ones.
+    if not _ut().materialises(table_key, st=session.runtime, defn=defn):
+        pids, _rows, fields_base, defn = scoped_pool(session, table_key)
+        return pids, fields_base, defn
+    pids = frozenset(int(rid) for rid in (defn.get("rows") or {}) if str(rid).isdigit())
+    return pids, fields_base, defn
+
+
+def ut_write_ctx(session: Session, table_key: str):
+    """The g-dict a WRITE needs — same keys as `ut_assembly`, no rows.
+
+    Returns the six keys `routes_grid.grid_events_route` reads, so the events route consumes this
+    or a full assembly interchangeably. `rows_src` is `[]` on purpose rather than absent: a caller
+    that starts needing rows should fail on an empty list it can see, not on a KeyError.
+    """
+    import aios_grid
+    from core import grid_events
+
+    pids, fields_base, defn = scoped_pids(session, table_key)
+    ctx = grid_events.EventCtx(
+        uname=session.uname, allowed_pids=pids, fields=[], hidden_keys=frozenset(),
+        admin=session.admin, fallback_ws=None, seen_ids={}, st=session.runtime,
+        scope_key=table_key, table=_ops(session, table_key))
+    ws = grid_events.table_workspace(ctx, allowed_pids=pids, consume_corrections=False)
+    workspace, fields, views, lists = aios_grid.workspace_wire(
+        ws, session.uname, set(pids), defs={}, scope_key=table_key, storage_key="",
+        fields_base=fields_base)
+    return {"rows_src": [], "pids": pids, "ws": ws, "workspace": workspace,
+            "fields": fields, "views": views, "lists": lists,
+            "derived": aios_grid.cohort_cells(lists),
+            "measures": [], "measure_sets": {}, "today": time.strftime("%Y-%m-%d"),
+            "defn": defn}
+
+
 def ut_assembly(session: Session, table_key: str, storage_key: str = "",
                 consume_corrections: bool = True):
     """The user-table mirror of `grid_assembly` / `product_assembly` — SAME g-dict keys, so
@@ -612,10 +771,26 @@ def table_rows(table_key: str, session: Session = Depends(require_session)):
     # so a tenant using `json` for a short config sees no change at all.
     rows = aios_grid.rows_from_pool(
         g["rows_src"], g["fields"], _thin_json(g["fields"], merged, table_key), derived=g["derived"])
+    # ⭐ R6's SECOND SENTENCE, ON THE WIRE (W30-T29). *"if there is lag or it can't be done, you
+    # need to explicitly tell me why and recommend a fix."* A ceiling that still applies to this
+    # database says so here, with its cause and the recommendation, rather than waiting to be
+    # discovered as a refused paste. `None` for a connected source, and an EMPTY LIST is the
+    # honest answer for a table nothing limits — never an absent key, which a client cannot tell
+    # apart from an older server.
+    _report = _ut().limit_report(table_key, st=session.runtime)
+    # ⭐ C4 / D-138 — THE DOCUMENTS PRODUCER. Absent since EXIT-6 deleted `app.py`, which was the
+    # only thing that ever set this key; the write door never stopped working and every client
+    # half is complete, but all six `onDoc*` handlers read `payload?.docs ? … : undefined`, so a
+    # missing key has been silently switching the feature off. ⛔ ONE shared serialiser with the
+    # customer scope — `grid_events.docs_for` — never a twin here.
+    from core import grid_events as _ge
     return {"fields": g["fields"], "rows": rows, "today": g["today"],
+            "docs": _ge.docs_for(g["pids"], scope_key=table_key, uname=session.uname,
+                                 admin=session.admin, st=session.runtime),
             "pulled_at": time.strftime("%Y-%m-%d %H:%M"),
             "identity": {"pid": "pid"},
             "scope": {"table": table_key, "rowCount": len(rows)},
+            "limits": [_report] if _report else [],
             "recordsMutable": _ut().records_mutable(table_key, st=session.runtime)}
 
 

platform/aios_grid.py

@@ -1769,8 +1769,26 @@ def clean_filter_tree(raw, valid_keys, depth=1, budget=None, cohort_ids=None):
 
 
 def _default_view_config(fields):
-    shown = [field["key"] for field in fields
-             if field.get("default") is not False or field["source"] == "overlay"]
+    # ⭐⭐ W30-T41's SERVER HALF (F's ask F-1, answered by D — this file is D's fence).
+    #
+    # ⛔ THE SECOND ARM USED TO BE `or field["source"] == "overlay"`, AND IT SWALLOWED THE FIRST
+    # ONE FOR EVERY CONNECTED COLUMN. `user_tables._clean_field` stamps `source: "overlay"` on
+    # every `ut_` field, so on an Odoo grid the arm was true for ALL of them and `default: False`
+    # meant nothing: `odoo_id`, `state`, `customer_link` and `partner_id` opened SHOWN however
+    # they were declared. The exception had become the rule ([[fallback-that-became-the-rule]]),
+    # and it is the same predicate `useGridColumns.isDefaultVisible` carried on the client.
+    #
+    # ⚠ AND THE TWO HALVES MUST MOVE TOGETHER, which is why this is not cosmetic. `CustomerGrid`
+    # compares the stored view against its own `defaultViewConfig` by JSON equality; with the
+    # client fixed (T41) and this left alone, the system view would differ from the client's
+    # default on every render — a view that looks permanently dirty and autosaves forever, which
+    # is the failure `verify_filter_engine`'s key-ORDER check exists to prevent, one level down.
+    #
+    # ⚠ A USER-CREATED COLUMN IS UNAFFECTED, and that is why the fix is a DELETION rather than a
+    # carve-out for the four Odoo keys: it carries no `default` key at all, so `is not False`
+    # keeps it visible. On the main Customer grid exactly one field moves — `notes`, which asks
+    # to be hidden in its own declaration and was being shown against it.
+    shown = [field["key"] for field in fields if field.get("default") is not False]
     hidden = [field["key"] for field in fields if field["key"] not in shown]
     return {
         # `filters` is the ROOT of the filter tree: leaf conditions and/or nested

platform/aios_grid_fields.json

@@ -1,423 +1,464 @@
-{
-  "_comment": "CANONICAL field contract for the AIOS Airtable-style grid \u2014 the SINGLE source of truth. Consumed by platform/aios_grid.py (embed/Space host) and aios-web/api/main.py (standalone API), and regenerated into aios-web/web/public/sample_customers.json. Edit HERE only, then run aios-web/verify_fields_contract.py. source=odoo is READ-ONLY; source=overlay is the editable stratum (notes/tags) outside Odoo. type in {text,status,select,currency,int,date,pct} (select = a fixed-choice READ-ONLY brand attribute; dba is the first, wave 2026-08-02). `description` (wave 5) is the CANONICAL per-field description \u2014 every field must carry one, and since wave 7 (owner W8, 2026-07-28) every description is ONE SHORT PLAIN sentence (two only when a fact would otherwise mislead): what the field IS, nothing else \u2014 no filter tips, no '(none)' coaching, no rationale; the user's workspace NOTE overrides it in the (i) hover, never in this file. BUILDER FACT (documented here, deliberately NOT in user-facing text): blank text attributes display as '(none)', so `is '(none)'` \u2014 not `is empty` \u2014 finds the blanks on agent/city/state/country/zip/payment_terms/pricelist/tags. filterable:false = the CONDITION BUILDER does not offer it (still displayed, still sortable); every such field must have a replacement declared in aios-web/verify_fields_contract.py. 2026-07-27 partner attributes: country/zip/payment_terms/pricelist/tags/customer_since all ship default:false. zip is TEXT because a postal code has leading zeros. Odoo's credit_limit (1% populated) and user_id salesperson (2%) are deliberately ABSENT; agent_ids is the salesperson field and AR is where credit exposure comes from. Wave-5 item 8 (2026-07-27): ltm_rev and at_risk are DELETED \u2014 LTM's replacement is a creatable Sales measure column (the demo column IS Sales \u00b7 the last 12 months), at_risk's replacement is a formula field, e.g. MAX(0, {revenue_ly} - {revenue_ytd}). Wave-6 item 8 (2026-07-27, the no-buildable-presets rule): revenue_ytd, revenue_ly, orders_24m, aov and yoy_pct are DELETED \u2014 every one is self-buildable, so a frozen pre-set beside the builder was two ways to ask one question. Replacements (recorded in verify_fields_contract.py): creatable measure columns for Sales / Orders / Avg order $ over any period (harness/measure_filter.py ADMITTED carries revenue, orders and the composite aov), and a formula over two measure columns for YoY, e.g. ({sales_ytd} - {sales_ly}) / {sales_ly}. Stale view colIds naming the five self-heal on the next autosave (the established rule).",
-  "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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 '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 \u2014 same basis as the Collections page."
-    },
-    {
-      "_note": "wave 21 R1 \u2014 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 \u2014 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."
-    }
-  ],
-  "_product_comment": "ADDITIVE, wave 15 C-TOPIC. The PRODUCT table's field contract. Kept as a SEPARATE top-level key rather than restructuring `fields` into {customer_data, product_data}: both existing readers (aios_grid._load_fields, aios-web/api/main.py) index doc['fields'] directly, and reshaping that mid-wave would break the embed for a cosmetic gain. The keyed shape can arrive when both readers move in ONE commit; until then this is the product half and `fields` is the customer half.",
-  "_product_removed_buy_now": "OWNER, 2026-08-03: 'Buy signal' (key buy_now, a select of Buy now / OK) is NO LONGER A PRESET FIELD. It never earned one: it is a formula over two columns that are both still right here, and the platform has a formula field type for exactly that. THE FORMULA, which reproduces the retired column row for row (modules/product_data.validate proves the equivalence, and goes red if it ever stops holding): IF({lead_days} > 0, IF({dos} < {lead_days}, \"Buy now\", \"OK\"), \"\") . Every branch matches the old server rule, including the blanks - the formula engine refuses a comparison against a blank rather than coercing it to 0, so a SKU with no days-of-supply or no lead time comes out empty, which is 'we do not know' and not 'you are fine'. NOTE the column is still COMPUTED in product_data.pool(): it ships nowhere (rows_from_pool projects strictly through this contract, so no Field means no cell on the wire) and exists only as validate()'s oracle. A formula field is PER-USER, so nothing shared may filter on it - the Buy list view filters on dos/lead_days directly (_seed_wave17).",
-  "product_data": {
-    "identity": "pid",
-    "business_key": "code",
-    "fields": [
-      {
-        "key": "code",
-        "label": "SKU",
-        "type": "text",
-        "source": "odoo",
-        "pinned": true,
-        "default": true,
-        "description": "The SKU code \u2014 the product's real business key. `pid` is a stable CRC32 of it because the grid keys on an integer."
-      },
-      {
-        "key": "product",
-        "label": "Product",
-        "type": "text",
-        "source": "odoo",
-        "default": true,
-        "description": "Product name as it appears in Odoo."
-      },
-      {
-        "key": "category",
-        "label": "Category",
-        "type": "select",
-        "source": "odoo",
-        "default": true,
-        "description": "Product category; '(uncategorized)' when Odoo carries none."
-      },
-      {
-        "key": "supplier",
-        "label": "Supplier",
-        "type": "text",
-        "source": "odoo",
-        "default": true,
-        "description": "Who makes it, from the inventory mastersheet. Not an Odoo field."
-      },
-      {
-        "key": "origin_country",
-        "label": "Country",
-        "type": "text",
-        "source": "odoo",
-        "default": false,
-        "description": "Country of origin, from the inventory mastersheet."
-      },
-      {
-        "key": "lead_days",
-        "label": "Lead time (days)",
-        "type": "int",
-        "source": "odoo",
-        "default": true,
-        "description": "Order-to-arrival days for this supplier. Drives the buy signal."
-      },
-      {
-        "key": "first_cost",
-        "label": "First cost",
-        "type": "currency",
-        "source": "odoo",
-        "default": false,
-        "description": "Quoted unit cost at origin, before freight and duty."
-      },
-      {
-        "key": "rev_ytd",
-        "label": "Revenue YTD",
-        "type": "currency",
-        "source": "odoo",
-        "default": true,
-        "description": "Year-to-date revenue for this SKU, BU-scoped when the caller is."
-      },
-      {
-        "key": "rev_ly",
-        "label": "Revenue LY",
-        "type": "currency",
-        "source": "odoo",
-        "description": "Same period last year \u2014 seasonal wholesale compares like for like."
-      },
-      {
-        "key": "yoy_pct",
-        "label": "YoY %",
-        "type": "pct",
-        "source": "odoo",
-        "description": "Year-over-year change; null when last year was zero (a ratio to zero is not a number)."
-      },
-      {
-        "key": "qty_ytd",
-        "label": "Units YTD",
-        "type": "int",
-        "source": "odoo",
-        "description": "Units sold year to date."
-      },
-      {
-        "key": "orders_ytd",
-        "label": "Orders YTD",
-        "type": "int",
-        "source": "odoo",
-        "description": "Distinct orders containing this SKU, year to date."
-      },
-      {
-        "key": "on_hand",
-        "label": "On hand",
-        "type": "int",
-        "source": "odoo",
-        "description": "Units in stock. CONSOLIDATED \u2014 one physical warehouse, not brand-tagged, so this column is ABSENT for a BU-scoped caller rather than silently company-wide."
-      },
-      {
-        "key": "unit_cost",
-        "label": "Unit cost",
-        "type": "currency",
-        "source": "odoo",
-        "description": "Inventory unit cost. Consolidated; absent for a BU-scoped caller."
-      },
-      {
-        "key": "inv_value",
-        "label": "Stock value",
-        "type": "currency",
-        "source": "odoo",
-        "description": "On-hand value at cost. Consolidated; absent for a BU-scoped caller."
-      },
-      {
-        "key": "qty_ltm",
-        "label": "Units LTM",
-        "type": "int",
-        "source": "odoo",
-        "description": "Units sold in the last twelve months. Consolidated; absent for a BU-scoped caller."
-      },
-      {
-        "key": "dos",
-        "label": "Days of supply",
-        "type": "int",
-        "source": "odoo",
-        "description": "Days of supply at the LTM rate; null means it never sells through. Consolidated; absent for a BU-scoped caller."
-      },
-      {
-        "key": "cover_gap_d",
-        "label": "Cover gap (days)",
-        "type": "int",
-        "source": "odoo",
-        "default": false,
-        "description": "Days of supply minus lead time. Negative means it runs out before a reorder lands."
-      },
-      {
-        "key": "stock_bucket",
-        "label": "Stock status",
-        "type": "select",
-        "source": "odoo",
-        "description": "Dead / excess / healthy bucket from the inventory module. Consolidated; absent for a BU-scoped caller."
-      }
-    ]
-  }
-}
+{
+  "_comment": "CANONICAL field contract for the AIOS Airtable-style grid — the SINGLE source of truth. Consumed by platform/aios_grid.py (embed/Space host) and aios-web/api/main.py (standalone API), and regenerated into aios-web/web/public/sample_customers.json. Edit HERE only, then run aios-web/verify_fields_contract.py. source=odoo is READ-ONLY; source=overlay is the editable stratum (notes/tags) outside Odoo. type in {text,status,select,currency,int,date,pct} (select = a fixed-choice READ-ONLY brand attribute; dba is the first, wave 2026-08-02). `description` (wave 5) is the CANONICAL per-field description — every field must carry one, and since wave 7 (owner W8, 2026-07-28) every description is ONE SHORT PLAIN sentence (two only when a fact would otherwise mislead): what the field IS, nothing else — no filter tips, no '(none)' coaching, no rationale; the user's workspace NOTE overrides it in the (i) hover, never in this file. BUILDER FACT (documented here, deliberately NOT in user-facing text): blank text attributes display as '(none)', so `is '(none)'` — not `is empty` — finds the blanks on agent/city/state/country/zip/payment_terms/pricelist/tags. filterable:false = the CONDITION BUILDER does not offer it (still displayed, still sortable); every such field must have a replacement declared in aios-web/verify_fields_contract.py. 2026-07-27 partner attributes: country/zip/payment_terms/pricelist/tags/customer_since all ship default:false. zip is TEXT because a postal code has leading zeros. Odoo's credit_limit (1% populated) and user_id salesperson (2%) are deliberately ABSENT; agent_ids is the salesperson field and AR is where credit exposure comes from. Wave-5 item 8 (2026-07-27): ltm_rev and at_risk are DELETED — LTM's replacement is a creatable Sales measure column (the demo column IS Sales · the last 12 months), at_risk's replacement is a formula field, e.g. MAX(0, {revenue_ly} - {revenue_ytd}). Wave-6 item 8 (2026-07-27, the no-buildable-presets rule): revenue_ytd, revenue_ly, orders_24m, aov and yoy_pct are DELETED — every one is self-buildable, so a frozen pre-set beside the builder was two ways to ask one question. Replacements (recorded in verify_fields_contract.py): creatable measure columns for Sales / Orders / Avg order $ over any period (harness/measure_filter.py ADMITTED carries revenue, orders and the composite aov), and a formula over two measure columns for YoY, e.g. ({sales_ytd} - {sales_ly}) / {sales_ly}. Stale view colIds naming the five self-heal on the next autosave (the established rule).",
+  "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": "street",
+      "label": "Street",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "First address line, from res.partner directly - not the geocoder, so a customer the map cannot place still shows its address."
+    },
+    {
+      "key": "street2",
+      "label": "Street 2",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "Second address line (suite, unit, floor) on the customer's Odoo address."
+    },
+    {
+      "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."
+    }
+  ],
+  "_product_comment": "ADDITIVE, wave 15 C-TOPIC. The PRODUCT table's field contract. Kept as a SEPARATE top-level key rather than restructuring `fields` into {customer_data, product_data}: both existing readers (aios_grid._load_fields, aios-web/api/main.py) index doc['fields'] directly, and reshaping that mid-wave would break the embed for a cosmetic gain. The keyed shape can arrive when both readers move in ONE commit; until then this is the product half and `fields` is the customer half.",
+  "_product_removed_buy_now": "OWNER, 2026-08-03: 'Buy signal' (key buy_now, a select of Buy now / OK) is NO LONGER A PRESET FIELD. It never earned one: it is a formula over two columns that are both still right here, and the platform has a formula field type for exactly that. THE FORMULA, which reproduces the retired column row for row (modules/product_data.validate proves the equivalence, and goes red if it ever stops holding): IF({lead_days} > 0, IF({dos} < {lead_days}, \"Buy now\", \"OK\"), \"\") . Every branch matches the old server rule, including the blanks - the formula engine refuses a comparison against a blank rather than coercing it to 0, so a SKU with no days-of-supply or no lead time comes out empty, which is 'we do not know' and not 'you are fine'. NOTE the column is still COMPUTED in product_data.pool(): it ships nowhere (rows_from_pool projects strictly through this contract, so no Field means no cell on the wire) and exists only as validate()'s oracle. A formula field is PER-USER, so nothing shared may filter on it - the Buy list view filters on dos/lead_days directly (_seed_wave17).",
+  "product_data": {
+    "identity": "pid",
+    "business_key": "code",
+    "fields": [
+      {
+        "key": "code",
+        "label": "SKU",
+        "type": "text",
+        "source": "odoo",
+        "pinned": true,
+        "default": true,
+        "description": "The SKU code — the product's real business key. `pid` is a stable CRC32 of it because the grid keys on an integer."
+      },
+      {
+        "key": "product",
+        "label": "Product",
+        "type": "text",
+        "source": "odoo",
+        "default": true,
+        "description": "Product name as it appears in Odoo."
+      },
+      {
+        "key": "category",
+        "label": "Category",
+        "type": "select",
+        "source": "odoo",
+        "default": true,
+        "description": "Product category; '(uncategorized)' when Odoo carries none."
+      },
+      {
+        "key": "supplier",
+        "label": "Supplier",
+        "type": "text",
+        "source": "overlay",
+        "default": true,
+        "description": "Who makes it. Editable here and shared with everyone in the workspace; seeded from the inventory mastersheet.",
+        "shared": true
+      },
+      {
+        "key": "origin_country",
+        "label": "Country",
+        "type": "text",
+        "source": "overlay",
+        "default": false,
+        "description": "Country of origin. Editable here and shared with everyone; seeded from the inventory mastersheet.",
+        "shared": true
+      },
+      {
+        "key": "lead_days",
+        "label": "Lead time (days)",
+        "type": "int",
+        "source": "overlay",
+        "default": true,
+        "description": "Order-to-arrival days for this supplier. Drives the buy signal. Editable and shared with everyone.",
+        "shared": true
+      },
+      {
+        "key": "first_cost",
+        "label": "First cost",
+        "type": "currency",
+        "source": "overlay",
+        "default": false,
+        "description": "Quoted unit cost at origin, before freight and duty. Editable and shared with everyone.",
+        "shared": true
+      },
+      {
+        "key": "price_fisch",
+        "label": "Fisch price",
+        "type": "currency",
+        "source": "odoo",
+        "description": "Fisch pricelist price for this SKU. Blank when that list prices it nowhere."
+      },
+      {
+        "key": "price_royal_1",
+        "label": "Royal 1 price",
+        "type": "currency",
+        "source": "odoo",
+        "description": "Royal 1 pricelist price for this SKU. Blank when that list prices it nowhere."
+      },
+      {
+        "key": "price_royal_2",
+        "label": "Royal 2 price",
+        "type": "currency",
+        "source": "odoo",
+        "description": "Royal 2 pricelist price for this SKU. Blank when that list prices it nowhere."
+      },
+      {
+        "key": "rev_ytd",
+        "label": "Revenue YTD",
+        "type": "currency",
+        "source": "odoo",
+        "default": true,
+        "description": "Year-to-date revenue for this SKU, BU-scoped when the caller is."
+      },
+      {
+        "key": "rev_ly",
+        "label": "Revenue LY",
+        "type": "currency",
+        "source": "odoo",
+        "description": "Same period last year — seasonal wholesale compares like for like."
+      },
+      {
+        "key": "yoy_pct",
+        "label": "YoY %",
+        "type": "pct",
+        "source": "odoo",
+        "description": "Year-over-year change; null when last year was zero (a ratio to zero is not a number)."
+      },
+      {
+        "key": "qty_ytd",
+        "label": "Units YTD",
+        "type": "int",
+        "source": "odoo",
+        "description": "Units sold year to date."
+      },
+      {
+        "key": "orders_ytd",
+        "label": "Orders YTD",
+        "type": "int",
+        "source": "odoo",
+        "description": "Distinct orders containing this SKU, year to date."
+      },
+      {
+        "key": "on_hand",
+        "label": "On hand",
+        "type": "int",
+        "source": "odoo",
+        "description": "Units in stock. CONSOLIDATED — one physical warehouse, not brand-tagged, so this column is ABSENT for a BU-scoped caller rather than silently company-wide."
+      },
+      {
+        "key": "unit_cost",
+        "label": "Unit cost",
+        "type": "currency",
+        "source": "odoo",
+        "description": "Inventory unit cost. Consolidated; absent for a BU-scoped caller."
+      },
+      {
+        "key": "inv_value",
+        "label": "Stock value",
+        "type": "currency",
+        "source": "odoo",
+        "description": "On-hand value at cost. Consolidated; absent for a BU-scoped caller."
+      },
+      {
+        "key": "qty_ltm",
+        "label": "Units LTM",
+        "type": "int",
+        "source": "odoo",
+        "description": "Units sold in the last twelve months. Consolidated; absent for a BU-scoped caller."
+      },
+      {
+        "key": "dos",
+        "label": "Days of supply",
+        "type": "int",
+        "source": "odoo",
+        "description": "Days of supply at the LTM rate; null means it never sells through. Consolidated; absent for a BU-scoped caller."
+      },
+      {
+        "key": "cover_gap_d",
+        "label": "Cover gap (days)",
+        "type": "int",
+        "source": "odoo",
+        "default": false,
+        "description": "Days of supply minus lead time. Negative means it runs out before a reorder lands."
+      },
+      {
+        "key": "stock_bucket",
+        "label": "Stock status",
+        "type": "select",
+        "source": "odoo",
+        "description": "Dead / excess / healthy bucket from the inventory module. Consolidated; absent for a BU-scoped caller."
+      }
+    ]
+  }
+}

platform/core/grid_events.py

@@ -255,6 +255,64 @@ def _cohorts(ctx):
     return cohort_mod.scoped(ctx.scope_key)
 
 
+#: The keys a stored document entry may put on the wire. ⛔ `path` IS NOT ONE OF THEM — it is the
+#: byte address inside the tenant's repo, of no use to a browser and a needless disclosure of the
+#: store's layout. `canDelete` is not stored either: it is a fact about the READER, computed per
+#: request below, so one person's answer can never be cached into another's.
+_DOC_WIRE_KEYS = ('id', 'name', 'mime', 'size', 'by', 'ts')
+
+
+def docs_for(pids, scope_key='customer', uname='', admin=False, st=None):
+    """`{"<pid>": [CustomerDoc, ...]}` for a SCOPED row set — the producer `payload.docs` lost.
+
+    ⭐⭐ WAVE 30 / CONTRACT C4 (D-138). The write door has been live and UNREACHABLE since EXIT-6:
+    `doc_add`/`doc_fetch`/`doc_delete` all still work, and the comment inside that handler says
+    exactly why nobody noticed — *"the React shell cannot reach it yet (`payload.docs` is set only
+    by app.py)"*. `app.py` was deleted, and the producer went with it. Every client half survived:
+    `RecordDetail`, `SwipeView` and `Documents` are complete, and all six `onDoc*` handlers in
+    `CustomerGrid.tsx` are written as `payload?.docs ? … : undefined`, so an ABSENT `docs` key is
+    what has been switching the whole feature off. An empty dict is truthy and turns it on with an
+    honest empty state.
+    ⛔ THIS IS THE SIXTH INSTANCE OF THE REACHABILITY CLASS and the one `verify_reachability.py`
+    cannot see — a payload key assembled through helpers and dict merges is not a text-matchable
+    literal ([[reachable-is-not-the-same-as-built]], [[artifact-with-no-importer]]).
+
+    ⛔ ONE READER, NOT A MATCHING PAIR. `routes_tables` (ut_*) and `routes_customers` (the customer
+    scope) both call THIS — they do not each serialise. Two surfaces answering one question
+    separately is how the same defect got reintroduced in the opposite direction inside a single
+    commit ([[one-question-two-normalizers]]).
+
+    ⚠ `pids` IS REQUIRED and is the row set the CALLER has already scoped — `shared_overlay.cells`'
+    argument, for the same reason: there is no "every document in the tenant" call to reach for.
+    A record with no documents gets `[]`, never a missing key, so a client can tell "none" from
+    "not served".
+    """
+    wanted = {str(int(p)) for p in (pids or [])}
+    if not wanted:
+        return {}
+    scope = str(scope_key or 'customer').strip().lower()
+    key = _DOCS_KEY if scope in cohort_mod.LEGACY_SCOPES else f'{scope}_docs'
+    try:
+        stored = (st if st is not None else store).get(key) or {}
+    except Exception:                                                 # noqa: BLE001
+        stored = {}                       # a display read degrades; it never breaks the grid
+    out = {}
+    for pid in wanted:
+        row = stored.get(pid)
+        docs = []
+        for d in (row if isinstance(row, list) else []):
+            if not isinstance(d, dict) or not d.get('id'):
+                continue
+            wire = {k: d.get(k) for k in _DOC_WIRE_KEYS}
+            # The delete wall, mirrored onto the wire so the button is absent rather than
+            # offered-and-refused. `doc_delete` enforces the same test server-side; this is the
+            # DISPLAY of that rule, never a substitute for it.
+            wire['canDelete'] = bool(admin or (d.get('by') and d.get('by') == uname))
+            docs.append(wire)
+        out[pid] = docs
+    return out
+
+
 def _docs_key(ctx):
     """The DOCUMENTS bucket this ctx operates on — `_cohorts`'s sibling (wave 19, item 12's
     silent third case).

platform/harness/datastore.py

@@ -19,6 +19,7 @@ Design rules:
 import datetime as dt
 import json
 import os
+import re
 import sys
 import time
 from pathlib import Path
@@ -178,12 +179,23 @@ ENTITIES = {
         # ⛔ It is synced HERE rather than read from live Odoo because `read_customers` also runs
         # at BOOT off a hydrated snapshot, where Odoo may be unreachable — sourcing it live would
         # make the population "whatever source answered this time", changing size with the network.
+        # ⭐ WAVE 30 (session E's ask, W30-T33). `street`/`street2`/`zip` are the POSTAL half of
+        # an address the mirror has never carried: it holds `city`, `state_id` and `country_id`
+        # and stops there, so `odoo_relational.read_customers` — which reads only the mirror —
+        # cannot serve a full address at all, however the column is declared.
+        # ⛔ DECLARING THEM DOES NOT FILL THEM, and the difference is a whole sync: an existing
+        # mirror ALTERs the columns in on the next `sync_all()` and leaves them NULL until the
+        # backfill below has walked every partner (a partner's `write_date` did not move because
+        # WE changed the schema). Every projection degrades a missing/NULL column to blank rather
+        # than raising, so declaring early is safe — it is just not yet true.
         "fields": ["name", "team_id", "city", "state_id", "country_id", "active",
-                   "agent", "salesman_as_agent", "customer_rank", "write_date"],
+                   "agent", "salesman_as_agent", "customer_rank",
+                   "street", "street2", "zip", "write_date"],
         # `backfill_fields` carries it too, so mirrors that already exist pick it up on the next
         # sync_all() instead of needing a reseed.
         "backfill_fields": ["agent", "salesman_as_agent",           # added 2026-07-28
-                            "customer_rank"],                       # added 2026-08-11 (W29-T54)
+                            "customer_rank",                        # added 2026-08-11 (W29-T54)
+                            "street", "street2", "zip"],            # added 2026-08-12 (W30-T33)
         # m2m fields land as <base>_id (the FIRST linked id — the Customers-module convention:
         # a customer's assigned agent is agent_ids[0], ~one per customer, MECE) + <field> as a
         # JSON list of ALL ids. Declared explicitly: a 2-element m2m read would otherwise be
@@ -387,6 +399,127 @@ def ro_con():
     return cur
 
 
+# ─────────────────────────────────────────────────────────────────────────────────────────────
+# ⭐ WAVE 30 / OWNER RULING R6 + R7 — THE WINDOW. Read this before touching `window()`.
+#
+# R6, verbatim: *"there is no cap in how many data from the API source (as long as its from a
+# connected source like Odoo) that can be pulled into the app."* R7 says how: a connected grid
+# reads THROUGH this mirror instead of copying rows into the one `user_tables` document, which
+# `MAX_ROWS = 60_000` bounds. The mirror is already uncapped — 971,034 GL lines live in this file
+# today — so "no cap" is not a bigger number, it is a different mechanism: serve a SLICE and count
+# the whole.
+#
+# ⛔⛔ `total` IS A `SELECT count(*)` OVER THE SAME PREDICATE, NEVER `len(rows)`. A window whose
+# count is its own length is a fabricated aggregate that reads as authoritative — the class this
+# repo has paid for twice ([[no-unverifiable-aggregates]], [[one-question-two-normalizers]]: a
+# display predicate and a fold predicate answering one question differently). The two statements
+# below are built from ONE `where` + ONE `params` tuple for exactly that reason; they cannot drift
+# apart without deleting a line.
+#
+# ⛔ AND THE PREDICATE PUSHES DOWN. `where` is compiled by `harness/filter_sql.py` — the same
+# compiler the client's filter engine is held in step with — so a filter matching rows outside the
+# loaded window still COUNTS them. A caller that filters the returned list instead has silently
+# asked "how many of the 200 rows in memory match" about a 971,034-row table.
+#
+# ⚠ `order_by` IS REQUIRED IN PRACTICE AND DEFAULTED HERE. Two pages of an UNORDERED window are
+# not guaranteed to partition the table: DuckDB may legally return a row on page 1 and again on
+# page 2, and the user sees a duplicate with no error anywhere. The default is the physical
+# rowid-ish `1` only when a caller genuinely has no key; every real caller passes one.
+#
+# ⚠ TRUST BOUNDARY. `table`, `select`, `where` and `order_by` are SQL we author (a spec row, or
+# `filter_sql`'s output over a whitelisted column map). Every VALUE is bound through `params`.
+# `table` is additionally shape-checked below — not because a caller is hostile, but because a
+# typo'd identifier interpolated into two statements is worth one cheap assertion.
+
+#: The most rows ONE request may carry back. Not a cap on the data — every row is reachable by
+#: paging and `total` always tells the truth about how many there are — but a bound on the memory
+#: a single response can cost. R6's second sentence applies: a caller that asks for more is CLAMPED
+#: and the clamp is REPORTED (`routes_odoo_tables` turns it into a `limits` entry), never silent.
+WINDOW_MAX = 5_000
+
+#: What a caller gets when it names no window at all. Matches `semantic.store_rows`' own default so
+#: the two windowed readers in this codebase do not disagree about what "a page" means.
+WINDOW_DEFAULT = 200
+
+_IDENT_OK = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def window(table=None, select=None, where=None, params=(), order_by=None,
+           offset=0, limit=WINDOW_DEFAULT, cur=None, from_sql=None):
+    """One page of a mirror table PLUS the true count of everything the same predicate matches.
+
+    Returns `{"rows": [tuple, ...], "columns": [name, ...], "total": int, "offset": int,
+    "limit": int, "clamped": bool}` — `rows` is the slice, `total` is the population.
+
+    `select` is the projection expression list ("id, name, amount_untaxed"); `where` is a WHERE
+    body with `?` placeholders; `params` binds them, and is used by BOTH statements.
+
+    ⚠ `table` and `from_sql` are the SAME argument wearing two trust levels, and they are separate
+    names on purpose. `table` is an identifier and is SHAPE-CHECKED; `from_sql` is a whole FROM
+    body — a parenthesised subquery with an alias — which cannot be checked at all. Two of the
+    eight connected grids need one (`read_customers` and `read_agents` are single statements whose
+    population is a SQL `UNION`), so the capability has to exist; naming it distinctly means a
+    reviewer can grep for every caller that hands over raw FROM SQL instead of inferring it.
+    """
+    if bool(table) == bool(from_sql):
+        raise ValueError("datastore.window: pass exactly one of `table` or `from_sql`")
+    if from_sql:
+        name = str(from_sql).strip()
+    else:
+        name = str(table or "").strip()
+        if not _IDENT_OK.match(name):
+            raise ValueError(f"datastore.window: {table!r} is not a table identifier")
+    proj = str(select or "").strip()
+    if not proj:
+        raise ValueError("datastore.window: a projection is required — there is no implicit *")
+    try:
+        offset = max(0, int(offset or 0))
+    except (TypeError, ValueError):
+        offset = 0
+    try:
+        limit = int(limit if limit is not None else WINDOW_DEFAULT)
+    except (TypeError, ValueError):
+        limit = WINDOW_DEFAULT
+    clamped = limit > WINDOW_MAX or limit < 1
+    limit = min(max(limit, 1), WINDOW_MAX)
+
+    params = tuple(params or ())
+    pred = str(where or "").strip()
+    tail = f" WHERE {pred}" if pred else ""
+    order = str(order_by or "").strip() or "1"
+    cur = cur if cur is not None else ro_con()
+
+    # ⛔ THE COUNT RUNS FIRST AND OVER THE SAME `tail` + `params`. Ordering it first is deliberate:
+    # if the projection is ever wrong, the caller fails LOUDLY on the rows query rather than
+    # quietly returning a good count beside a broken page.
+    total = int(cur.execute(f"SELECT count(*) FROM {name}{tail}", params).fetchone()[0] or 0)
+    got = cur.execute(
+        f"SELECT {proj} FROM {name}{tail} ORDER BY {order} LIMIT {int(limit)} OFFSET {int(offset)}",
+        params).fetchall()
+    cols = [d[0] for d in (cur.description or [])]
+    return {"rows": [tuple(r) for r in got], "columns": cols,
+            "total": total, "offset": offset, "limit": limit, "clamped": clamped}
+
+
+def columns_of(table, cur=None):
+    """The column names a mirror table actually has, lowercased.
+
+    ⚠ A mirror can be `ready()` and still be MISSING COLUMNS: `ready()` reads entity PHASES, while
+    `_ensure_columns`/`_backfill_columns` checkpoint separately. Asking before projecting is what
+    stops a DuckDB `BinderException: Referenced column … not found` reaching a user as a bare 500
+    (it already cost one live, which is why `odoo_relational.columns` exists on the app side).
+    """
+    name = str(table or "").strip()
+    if not _IDENT_OK.match(name):
+        raise ValueError(f"datastore.columns_of: {table!r} is not a table identifier")
+    cur = cur if cur is not None else ro_con()
+    try:
+        rows = cur.execute(f"PRAGMA table_info('{name}')").fetchall()
+    except Exception:                                                 # noqa: BLE001
+        return set()
+    return {str(r[1]).lower() for r in rows}
+
+
 SEED_DATASET = os.environ.get("STORE_SEED_DATASET", "royal-imports/cfo-os-data")
 
 

platform/modules/customer_data.py

@@ -8,8 +8,11 @@ The page is a customer-list WORKBENCH in two parts:
      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'
+Composes already-validated customers-module functions, so the page's counts derive FROM the
+lists it renders (rule 8b). ⚠ **This header used to end "no separate validate()" and W30-T33
+made that false** — see `validate()` below. The claim held only while every column composed an
+already-reconciled customers-module function; the ADDRESS family does not, so it needed its own
+tie. 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
@@ -247,6 +250,130 @@ def pool_first(agent_name=None, team_id=None, limit=100):
     return _pool_build(agent_name, team_id, limit=limit, fast=True)
 
 
+# ------------------------------------------------------------------ the address reconciliation
+#: {our pool key: the `res.partner` field an Odoo domain filters on}. The two m2o columns are
+#: stored here as RESOLVED NAMES (`O.m2o_name`), so the oracle asks Odoo whether the id is SET
+#: while we count whether the name is non-blank — a set id resolving to an empty name is the one
+#: place those two questions could come apart, and the per-key leg is what would report it.
+ADDRESS_FIELDS = {
+    'street': 'street', 'street2': 'street2', 'city': 'city',
+    'state': 'state_id', 'country': 'country_id', 'zip': 'zip',
+}
+
+#: OUR blank. `_partner_attrs` collapses every partner attribute to '(none)' when blank (MECE, so
+#: a group-by has no null bucket), a pool row for a partner with NO attrs takes the same sentinel
+#: from the row template, and `_reconcile_ledger`'s revived rows are written '(none)' outright.
+_ADDRESS_BLANK = ('(none)', '', None)
+
+
+def address_blank(value):
+    """OUR blank predicate, in ONE place — the fold and the oracle must ask ONE question.
+
+    ⚠ `.strip()` is part of it, and that is the half that diverges from Odoo. A domain
+    `('street', '!=', False)` counts a whitespace-only street as PRESENT while this counts it as
+    blank, so the two normalizers would disagree by exactly the whitespace-only population.
+    MEASURED 2026-08-12 across `street`/`street2`/`city`/`zip` over the whole pool: **0**. The
+    leg that keeps it 0 is asserted in `validate()` rather than assumed
+    ([[one-question-two-normalizers]]).
+    """
+    return value in _ADDRESS_BLANK or (isinstance(value, str) and not value.strip())
+
+
+def validate(team_id=None):
+    """Reconcile the ADDRESS family the Customer grid ships to an independent Odoo aggregate.
+
+    ⛔ THE POINT OF THIS FUNCTION IS THAT THE NUMBER SURVIVES THE SESSION THAT TOOK IT. W30-T33
+    shipped `street`/`street2` after measuring their coverage with a throwaway shell one-liner —
+    a measurement, never a `validate()` — so nothing in the repo re-checked it and the figure
+    died with that session. The house law is *every metric gets a `validate()` reconciling to an
+    INDEPENDENT Odoo aggregate*, and an oracle nobody re-runs rots exactly like a mode nobody
+    runs ([[rules-need-gates]]). `aios-web/api/verify_odoo_relational.py` is what re-runs it.
+
+    ⚠ THE TRAP THAT REDS A CORRECT LEG, and it is why every domain below is scoped to the pool's
+    OWN pid set: **the customer pool is the WHOLE BOOK**, not `customer_rank > 0 AND active`
+    ([[customer-grid-pool-vs-odoo-count]]). The 3,617/3,478 pair quoted in the wave-30 mailbox is
+    the rank>0-active population and is NOT this one; measured here the same day, the pool holds
+    3,629 rows of which 3,487 carry a street. Comparing our count against a differently-scoped
+    Odoo count is a true measurement of the wrong subject [[measure-the-real-call]].
+
+    ⛔ IT BUILDS THE FULL `pool()`, NOT `pool_first`/`fast=True`, AND THE COST IS REAL — **444 s
+    measured 2026-08-12** (the address itself is ~14 s of that; AR, product mix, salesperson,
+    coords and DBA are the rest). Reported rather than optimised away, per R6's second sentence.
+    `fast=True` is not the shipping basis: it skips `_reconcile_ledger`, so the RETAINED customers
+    (I13) never enter and the population is a different one. The recommended fix if this ever has
+    to get cheap is a `families=` argument on `_pool_build` so a reconciliation can ask for the
+    families it reconciles — NOT a second cheaper pool builder, which would be two evaluators for
+    one question [[one-evaluator-per-question]].
+    """
+    rows = pool(team_id=team_id)
+    pids = [int(r['pid']) for r in rows if r.get('pid')]
+    odoo = O.get_odoo()
+    checks = []
+
+    # ── the population, and the three numbers that keep the address legs honest ───────────────
+    # An Odoo `search` excludes archived records by default, so `n_visible` counts the partners
+    # that are BOTH live and ours. Three populations therefore ride the pool and only one of them
+    # can carry an address: rows Odoo can see, rows `_reconcile_ledger` REVIVED (I13 — Odoo
+    # dropped them; every attribute is written '(none)'), and rows that are neither, i.e. archived
+    # in Odoo but never retained. The third is the one that grows silently, so it is REPORTED as
+    # a number rather than absorbed into a tolerance.
+    revived = [r for r in rows if r.get('odoo_status') != 'Active']
+    rpids = [int(r['pid']) for r in revived if r.get('pid')]
+    n_visible = odoo.search_count('res.partner', [('id', 'in', pids)])
+    # ⛔ ASSERTED, NOT ASSUMED. "The retained rows are the ones Odoo lost" is trivially true when
+    # checked against the ledger that did the retaining — that is the self-sealing shape. So it is
+    # asked of ODOO: a retained pid Odoo can still see means `_reconcile_ledger` buried a LIVE
+    # customer's address behind six '(none)' cells.
+    still_live = odoo.search_count('res.partner', [('id', 'in', rpids)]) if rpids else 0
+    checks.append({
+        'check': "every RETAINED customer (I13) is one Odoo genuinely cannot see — asked of "
+                 "Odoo, never of the ledger that did the retaining",
+        'ours': still_live, 'theirs': 0, 'ok': still_live == 0,
+        'detail': {'pool_rows': len(rows), 'odoo_visible': n_visible, 'retained': len(revived),
+                   'archived_not_retained': len(pids) - n_visible - len(revived)},
+    })
+
+    # ── the six address columns, each against a domain Odoo evaluates server-side ─────────────
+    # ⛔ `search_count` WITH A DOMAIN, never a re-read-and-recount: it makes ODOO do the filtering,
+    # so the oracle cannot inherit a bug from `_partner_attrs`, which is the code under test.
+    for key, field in ADDRESS_FIELDS.items():
+        ours = sum(1 for r in rows if not address_blank(r.get(key)))
+        theirs = odoo.search_count('res.partner', [('id', 'in', pids), (field, '!=', False)])
+        checks.append({
+            'check': f"the grid's `{key}` column is non-blank on exactly the pool customers Odoo "
+                     f"says carry `{field}` — an INDEPENDENT search_count over the pool's own "
+                     f"pid set, never a count of the rows we just built",
+            'ours': ours, 'theirs': theirs, 'ok': ours == theirs,
+            # `column` is what the GATE matches on. Substring-matching the prose is how a leg
+            # silently stops being checked when somebody rewords it, and this file's own twin
+            # (`verify_product_pool`) matches on prose precisely because it had no key to use.
+            'detail': {'column': key, 'odoo_field': field, 'blank_here': len(rows) - ours},
+        })
+
+    # ── the two normalizers are ONE question, and this is the leg that keeps them one ─────────
+    # Everything above compares OUR `.strip() or '(none)'` against ODOO'S `!= False`. Those agree
+    # on every value except a whitespace-only one, which Odoo reports present and this module
+    # renders blank. Measured 0 today; if it ever stops being 0 the per-key legs above go red for
+    # a reason that has nothing to do with the address being wrong, so the cause is named HERE.
+    text_keys = [k for k, f in ADDRESS_FIELDS.items() if f == k]
+    ws = {}
+    if pids:
+        # `O.search_read`, the same door `_partner_attrs` reads through — the client's own method
+        # takes `domain=`/`fields=` as keywords and this wrapper is the one with a fixed shape.
+        for got in O.search_read('res.partner', [('id', 'in', pids)], text_keys):
+            for k in text_keys:
+                v = got.get(k)
+                if isinstance(v, str) and v and not v.strip():
+                    ws[k] = ws.get(k, 0) + 1
+    checks.append({
+        'check': "no pool customer carries a WHITESPACE-ONLY address value — the one input on "
+                 "which our blank predicate and Odoo's `!= False` provably disagree",
+        'ours': sum(ws.values()), 'theirs': 0, 'ok': not ws,
+        'detail': {'per_field': ws, 'fields_checked': text_keys},
+    })
+    return checks
+
+
 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).
@@ -433,7 +560,10 @@ def _pool_build(agent_name, team_id, limit, fast=False):
             '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)'),
+            'agent': a.get('agent', '(none)'),
+            # ⭐ W30-T33 (carried W29-T51) — the street lines beside the city they belong to.
+            'street': a.get('street', '(none)'), 'street2': a.get('street2', '(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)'),
@@ -541,7 +671,13 @@ def _reconcile_ledger(rows, total, agent_name, team_id):
                 # 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)',
+                # ⚠ W30-T33: the address keys land HERE TOO, and this is the site a field addition
+                # silently skips. `rows_from_pool` projects with `r.get(k)`, so a revived row
+                # missing a key renders BLANK rather than raising — archived customers would show
+                # an empty address column while live ones showed a full one, and nothing anywhere
+                # would report it. Two row templates, one field contract.
+                'agent': '(none)', 'street': '(none)', 'street2': '(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,

platform/modules/customers.py

@@ -573,8 +573,9 @@ DIMENSIONS = {
 
 
 def _partner_attrs(pids):
-    """{pid: {city, state, country, agent, zip, payment_terms, customer_since, tags, pricelist}}
-    — the customer attributes the sum-level rollups slice by and the Customer table displays.
+    """{pid: {street, street2, city, state, country, agent, zip, payment_terms, customer_since,
+    tags, pricelist}} — the customer attributes the sum-level rollups slice by and the Customer
+    table displays.
 
     Agent is res.partner.agent_ids (the assigned sales agent; ~one per customer), NOT Odoo's
     user_id 'salesperson' — MEASURED 2026-07-27 at 26 of 1,548 (2%), which is why agent_ids has
@@ -589,8 +590,8 @@ def _partner_attrs(pids):
     if not pids:
         return {}
     rows = O.search_read('res.partner', [('id', 'in', pids)],
-                         ['city', 'state_id', 'country_id', 'agent_ids', 'zip',
-                          'property_payment_term_id', 'create_date', 'category_id',
+                         ['street', 'street2', 'city', 'state_id', 'country_id', 'agent_ids',
+                          'zip', 'property_payment_term_id', 'create_date', 'category_id',
                           'property_product_pricelist'])
     aids = {a for r in rows for a in (r.get('agent_ids') or [])}
     anames = ({p['id']: p['name'] for p in O.search_read('res.partner', [('id', 'in', list(aids))], ['name'])}
@@ -610,6 +611,17 @@ def _partner_attrs(pids):
         # compares dates ISO-LEXICALLY, so a trailing time would sort and filter as text noise.
         since = (r.get('create_date') or '')
         out[r['id']] = {
+            # ⭐ W30-T33 (carried W29-T51) — the STREET half of the address. `city`/`state`/`zip`/
+            # `country` were already here; the two street lines were read nowhere on the customer
+            # path, only by `modules/map.py` for geocoding, and a geocoder's input never reached
+            # the grid. ⚠ NOT ROUTED THROUGH `map.py`: these come off `res.partner` directly, so a
+            # customer the geocoder could not place still shows its address.
+            # ⚠ `.strip()` WITHOUT `.title()`, unlike `city`. A street line carries unit numbers,
+            # directionals and abbreviations ("123 NW 4TH ST APT 2B"), and title-casing turns
+            # those into "123 Nw 4Th St Apt 2B" — a mangling `city` does not risk because a city
+            # is one word-set of ordinary nouns.
+            'street': (r.get('street') or '').strip() or '(none)',
+            'street2': (r.get('street2') or '').strip() or '(none)',
             'city': city.title() if city else '(none)',
             'state': O.m2o_name(r.get('state_id')) or '(none)',
             'country': O.m2o_name(r.get('country_id')) or '(none)',

platform/modules/product_data.py

@@ -57,6 +57,7 @@ from pathlib import Path
 
 import core.odoo as O
 import core.periods as P
+import core.shared_overlay as shared_overlay
 import core.table_store as table_store
 import modules.products as products
 
@@ -117,9 +118,16 @@ UNSHIPPED_ROW_KEYS = ("buy_now",)
 #: exist — and an unknown column is an INACTIVE condition in the tri-state engine, which IGNORES
 #: it and therefore WIDENS. The buy list would silently show the whole catalogue to everyone but
 #: its author. Contract columns are identical for every reader, so the view means one thing.
-#: ⭢ The owner asked for these to be EDITABLE ("turn this Excel sheet into a User created Field
-#: that we can edit"). That needs a SHARED field/overlay stratum, which the platform does not
-#: have yet — booked as the named gap in the wave-17 doc rather than faked per-user.
+#:
+#: ⭐⭐ 2026-08-12 (W30-T36) — THE OWNER'S ASK IS NOW DELIVERED, AND THE PARAGRAPH ABOVE IS WHY IT
+#: TOOK THREE WAVES. Owner: *"turn this Excel sheet into a User created Field that we can edit."*
+#: It was parked because a per-user column silently WIDENS a shared view — not because editing was
+#: hard. Wave 29's `core/shared_overlay.py` (whose header quotes this very comment) is the stratum
+#: that removes the objection: **one value per (row, column) for the whole tenant**, so the column
+#: still means ONE thing to every reader and a shared view still filters honestly.
+#: ⇒ The four columns below are now `source: "overlay"` + `shared: true` in the canonical
+#: contract, their values live in `<TABLE_KEY>__shared`, and the master map is what SEEDS an
+#: unedited cell rather than what freezes it. See `SHARED_KEYS` and `_ProductTableStore`.
 _SUPPLIER_MAP_PATH = Path(__file__).resolve().parent.parent / "procurement_suppliers.json"
 _SUPPLIER_CACHE = {}
 
@@ -156,7 +164,70 @@ def supplier_master():
 #: the whole reason the table-page factory exists ("a new table object gets its own
 #: table_store.make('<its>_table_workspace')").
 TABLE_KEY = 'product_table_workspace'
-TABLE_OPS = table_store.make(TABLE_KEY)
+
+_GRID_FIELDS_PATH = Path(__file__).resolve().parent.parent / 'aios_grid_fields.json'
+_SHARED_KEYS = None
+
+
+def SHARED_KEYS():
+    """The product columns whose values are TENANT-WIDE — derived from the canonical contract's
+    own `shared: true`, never typed out a second time.
+
+    ⛔ IT DELIBERATELY DOES NOT SWALLOW A READ FAILURE. Degrading to `()` would send a shared
+    write into the per-user stratum with nothing going wrong anywhere — the widening defect
+    reappearing silently, which is the one outcome this whole mechanism exists to prevent. If the
+    canonical contract is unreadable the product grid cannot render at all (`pd_fields` parses the
+    same file with no guard), so a raise here costs nothing that was still working.
+    """
+    global _SHARED_KEYS
+    if _SHARED_KEYS is None:
+        doc = json.loads(_GRID_FIELDS_PATH.read_text(encoding='utf-8'))
+        _SHARED_KEYS = tuple(f['key'] for f in (doc.get('product_data') or {}).get('fields') or []
+                             if f.get('shared'))
+    return _SHARED_KEYS
+
+
+class _ProductTableStore(table_store.TableStore):
+    """The product workspace, with the SHARED columns routed to the tenant-wide stratum.
+
+    ⭐⭐ THIS SUBCLASS IS THE WHOLE OF W30-T36's WRITE PATH, AND THE REASON IT LIVES HERE RATHER
+    THAN AT A ROUTE IS THAT **THE BROWSER NEVER CALLS `PATCH /products/{pid}`** — measured, zero
+    call sites in `aios-web/web/src`. A cell edit travels `POST /grid/events` → `grid_events.
+    handle_one` → `_tops(ctx).patch_overlay(...)`, and `_tops` returns `ctx.table`, which
+    `routes_grid._ctx` sets to `TABLE_OPS` for the product scope. So this object IS the seam both
+    doors pass through; intercepting at either route would have left the other one writing a
+    per-user value that only its author could see.
+
+    ⚠ `st=self.st`, NEVER the module default. The shared stratum must resolve to the SAME store
+    handle as the per-user one it sits beside — `_tops`' own comment explains that a split, where
+    one side is tenant-scoped and the other is not, is worse than a stated residency error because
+    a user's value would vanish the moment they saved it. Reading `self.st` means both strata move
+    together the day that singleton gains a tenant handle.
+    """
+
+    def patch_overlay(self, username, pid, updates):
+        clean = dict(updates or {})
+        if not clean:
+            return
+        keys = set(SHARED_KEYS())
+        shared = {k: v for k, v in clean.items() if k in keys}
+        personal = {k: v for k, v in clean.items() if k not in keys}
+        if shared:
+            shared_overlay.put_cells(TABLE_KEY, pid, shared, st=self.st)
+        if personal:
+            super().patch_overlay(username, pid, personal)
+
+
+TABLE_OPS = _ProductTableStore(TABLE_KEY)
+
+
+def shared_cells(pids, st=None):
+    """`{"<pid>": {key: value}}` for the SHARED columns of the rows named by `pids`.
+
+    ⚠ `pids` is required and positional all the way down — `shared_overlay.cells` refuses to serve
+    "everything" by design, and the caller here always holds an already-scoped pool.
+    """
+    return shared_overlay.cells(TABLE_KEY, pids, st=st if st is not None else TABLE_OPS.st)
 
 
 def sku_pid(code):
@@ -286,6 +357,20 @@ def _catalogue_by_code():
     return products.catalogue()
 
 
+def _pricelist_by_code():
+    """`({code: {price_*: price}}, report)` from `products.pricelist_by_code`, or `({}, …)`.
+
+    A SEAM for the same two reasons `_inventory_by_code` is one: it degrades rather than raises
+    (these are columns, not the row set), and `verify_perm_scope`'s section H stubs it to build a
+    pool without Odoo. ⛔ Unstubbed there, section H would reach live Odoo through the back door
+    and the whole file would stop being runnable offline.
+    """
+    try:
+        return products.pricelist_by_code()
+    except Exception as e:
+        return {}, {"error": f"{type(e).__name__}: {str(e)[:200]}"}
+
+
 def pool(team_id=None, t=None):
     """One row per ACTIVE product — the PRODUCT analogue of `customer_data.pool`.
 
@@ -305,6 +390,7 @@ def pool(team_id=None, t=None):
     inv = _inventory_by_code(t)
     bu_share = {} if consolidated else _bu_ltm_share(t, team_id)
     sup = supplier_master()
+    prices, _price_report = _pricelist_by_code()
     cat = _catalogue_by_code()
     # The LEFT side of the join, indexed by the same code key. ⛔ A code here that the catalogue
     # does not carry belongs to a product no ACTIVE record claims — archived, and R12 keeps those
@@ -332,6 +418,18 @@ def pool(team_id=None, t=None):
             "qty_ytd": r.get("qty_ytd", 0.0) if r else None,
             "orders_ytd": r.get("orders_ytd", 0) if r else None,
         }
+        # ⭐ WAVE 30 W30-T34 — the PRICELIST stratum, one column per declared list. Catalogue
+        # data like the supplier block, so it rides every pull, scoped or not: a price book is
+        # not a thing a business unit owns a slice of, and a Fisch reader who cannot see the
+        # Fisch price is exactly who this column is for.
+        #
+        # ⛔ `None`, NEVER 0 AND NEVER A FALLBACK, for the 1,883 SKUs no list prices. That is
+        # W29-T52's own negative control: the single `3_global` rule computes over `list_price`,
+        # which is 1.00 on 5,817 of 5,871 products, so the fallback is not a cheaper answer —
+        # it is a wrong one wearing a currency sign.
+        p = prices.get(code) or {}
+        for _col, _name in products.PRICELIST_COLUMNS:
+            row[_col] = p.get(_col)
         # Wave 17 R3 — the supplier master, on every pull (it is catalogue data, not stock).
         s = sup.get(code) or {}
         row.update({
@@ -504,6 +602,124 @@ def validate(team_id=None, t=None):
         "ours": still_active, "theirs": 0, "ok": still_active == 0,
         "detail": {"codes": coded_outside[:10], "n_codes": len(outside)},
     })
+    # ── ⭐⭐ WAVE 30 W30-T34 — THE PRICELIST COLUMNS, AGAINST ORACLES THAT CANNOT SEE OUR JOIN ──
+    #
+    # Three legs, because the column can fail in three different ways and only one of them is a
+    # count. `products.pricelist_by_code` builds a `{code: {col: price}}` map by expanding each
+    # rule over the products it names, IN PYTHON — that expansion is the fragile part, so every
+    # leg below re-asks ODOO instead of re-reading the map.
+    price_report = _pricelist_by_code()[1]
+    _pl_rows = O.search_read('product.pricelist', [], ['id', 'name'])
+    _pl_id = {}
+    for _p in _pl_rows:
+        _pl_id.setdefault(str(_p.get('name') or '').strip(), _p['id'])
+    _today = P.today().isoformat()
+
+    _targets_memo = {}
+
+    def _rule_targets(list_name):
+        """(variant_ids, template_ids) a pricelist prices today — read FRESH from Odoo.
+
+        Memoised for the LIFE OF THIS CALL only: legs 1 and 2 both need all three lists, and
+        without this `validate()` makes six identical round trips instead of three (measured:
+        ~48s of the run). Deliberately NOT an `lru_cache` — an oracle that survives the process
+        is an oracle reading yesterday's Odoo.
+        """
+        if list_name in _targets_memo:
+            return _targets_memo[list_name]
+        var, tmpl = set(), set()
+        plid = _pl_id.get(list_name)
+        if plid is None:
+            return var, tmpl
+        for r in O.search_read(
+                'product.pricelist.item',
+                [('pricelist_id', '=', plid), ('compute_price', '=', 'fixed'),
+                 ('applied_on', 'in', ['0_product_variant', '1_product'])],
+                ['product_id', 'product_tmpl_id', 'applied_on', 'fixed_price',
+                 'date_start', 'date_end']):
+            ds, de = str(r.get('date_start') or '')[:10], str(r.get('date_end') or '')[:10]
+            if (ds and ds > _today) or (de and de < _today):
+                continue
+            fp = r.get('fixed_price')
+            if not isinstance(fp, (int, float)) or fp <= 0:
+                continue
+            if r.get('applied_on') == '0_product_variant' and r.get('product_id'):
+                var.add(O.m2o_id(r['product_id']))
+            elif r.get('product_tmpl_id'):
+                tmpl.add(O.m2o_id(r['product_tmpl_id']))
+        _targets_memo[list_name] = (var, tmpl)
+        return var, tmpl
+
+    # LEG 1 — COVERAGE PER LIST. Ours: cells we filled. Theirs: a bare Odoo `search_count` of
+    # ACTIVE products a fresh read of that list's rules reaches. The rule set is shared (it IS
+    # the data) but the EXPANSION is not, and the expansion is what breaks.
+    for _col, _name in products.PRICELIST_COLUMNS:
+        _var, _tmpl = _rule_targets(_name)
+        _dom = [('active', '=', True), '|', ('id', 'in', sorted(_var)),
+                ('product_tmpl_id', 'in', sorted(_tmpl))]
+        theirs = O.get_odoo().search_count('product.product', _dom) if (_var or _tmpl) else 0
+        ours = sum(1 for r in rows if isinstance(r.get(_col), (int, float)))
+        checks.append({
+            "check": f"{_name} pricelist: SKUs priced in the grid == an INDEPENDENT Odoo count "
+                     f"of ACTIVE products its date-valid fixed rules reach",
+            "ours": ours, "theirs": theirs, "ok": ours == theirs,
+            "detail": {"column": _col, "variant_rules": len(_var), "template_rules": len(_tmpl)},
+        })
+
+    # LEG 2 — ⛔ THE TICKET'S OWN NEGATIVE CONTROL, AS A LEG. A SKU with no specific item must
+    # render BLANK. Asked of ODOO, never of the map that produced the blank — "everything I left
+    # empty was genuinely unpriced" is trivially true when checked against the dict that emptied
+    # it, which is the self-sealing shape the population leg above exists to end.
+    _unpriced = [r for r in rows
+                 if not any(isinstance(r.get(c), (int, float))
+                            for c, _n in products.PRICELIST_COLUMNS)]
+    _codes = {r["code"] for r in _unpriced}
+    _stray = 0
+    if _codes:
+        # Resolve those codes back to Odoo ids and ask whether ANY declared list prices them.
+        _ids, _tmpls = set(), set()
+        for _p in O.search_read('product.product',
+                                [('active', '=', True),
+                                 ('default_code', 'in', sorted(c for c in _codes
+                                                               if not c.startswith("pid:")))],
+                                ['id', 'product_tmpl_id']):
+            _ids.add(_p['id'])
+            _tmpls.add(O.m2o_id(_p.get('product_tmpl_id')))
+        for _col, _name in products.PRICELIST_COLUMNS:
+            _v, _t = _rule_targets(_name)
+            _stray += len((_v & _ids) | ({t for t in _tmpls if t in _t}))
+    checks.append({
+        "check": "every SKU rendering a BLANK price is genuinely unpriced on all three declared "
+                 "lists (W29-T52's NC: no fallback dressed as a price) — asked of Odoo",
+        "ours": _stray, "theirs": 0, "ok": _stray == 0,
+        "detail": {"blank_skus": len(_unpriced), "priced_skus": len(rows) - len(_unpriced)},
+    })
+
+    # LEG 3 — ⭐ R6's SECOND SENTENCE, AS A NUMBER. *"If there is lag or it can't be done, you
+    # need to explicitly tell me why and recommend a fix."* Everything the reader cannot see is
+    # counted here rather than dropped. The ASSERTION is the one thing that must never be true —
+    # a price cell that is present and not a positive number, i.e. a "free" SKU — while the
+    # rest rides `detail` so it is reported without reddening an honest day's data.
+    _bad = [r["code"] for r in rows
+            for c, _n in products.PRICELIST_COLUMNS
+            if r.get(c) is not None and not (isinstance(r.get(c), (int, float)) and r[c] > 0)]
+    # ⛔ MEASURED 2026-08-12 AND NOT FIXABLE FROM THIS FENCE: `aios_grid.rows_from_pool` sends
+    # every non-text field through `_round(v)` = `round(v)` with no ndigits, i.e. to a whole
+    # dollar. 52.1% of fixed prices carry cents and the median relative error is 5.26%, so this
+    # column ties to the cent HERE and ships rounded. Reported, never silently enforced.
+    _cents = sum(1 for r in rows for c, _n in products.PRICELIST_COLUMNS
+                 if isinstance(r.get(c), (int, float)) and abs(r[c] - round(r[c])) > 1e-9)
+    _to_zero = sum(1 for r in rows for c, _n in products.PRICELIST_COLUMNS
+                   if isinstance(r.get(c), (int, float)) and round(r[c]) == 0)
+    checks.append({
+        "check": "no price cell is present-but-not-a-positive-number (a 0 would read as FREE; "
+                 "an unset rule must be blank), and what the reader cannot see is COUNTED",
+        "ours": len(_bad), "theirs": 0, "ok": not _bad,
+        "detail": {"bad_cells": _bad[:10], "reader_report": price_report,
+                   "wire_rounding_loses_cents_on": _cents,
+                   "wire_rounding_to_zero_dollars": _to_zero},
+    })
+
     # WAVE 17 R3 — the BUY SIGNAL must be a total, exact partition of the catalogue, and every
     # member of it must be re-derivable from the two columns beside it. A signal somebody buys
     # stock on cannot be "mostly right": the failure that matters is a row that says OK because

platform/modules/products.py

@@ -212,6 +212,178 @@ def catalogue():
     return out
 
 
+#: ⭐⭐ WAVE 30 / W30-T34 (the carried W29-T52) — THE PRICELIST STRATUM, PER LIST.
+#:
+#: MEASURED LIVE 2026-08-12, and every one of these numbers shaped the design rather than
+#: decorating it:
+#:
+#:   · **Five pricelists, three of them material.** Date-valid fixed rules: Fisch 5,139,
+#:     Royal 1 2,702, Royal 2 2,605, Public Pricelist 17, Giftware Deals 1. At SKU level that
+#:     is Fisch 3,971 · Royal 1 1,920 · Royal 2 1,857 · Public 6 · Giftware 0.
+#:   · **3,988 of 5,871 active products carry a usable fixed rule; 1,883 carry NONE.**
+#:   · **1,853 SKUs are priced on all three lists AND THE LISTS DISAGREE** — median relative
+#:     spread 16%, max 82%. That is why this is three columns rather than one "the price" or a
+#:     low/high pair: neither can tell a Fisch rep what Fisch sells the SKU for, which is the
+#:     only question the column exists to answer.
+#:   · ⛔ **`list_price` is 1.00 on 5,817 of the 5,871** — so the single `3_global` rule
+#:     computed over it is meaningless, exactly as W29-T52 said. **This reader never falls
+#:     through to it**, and that is the ticket's own negative control: a SKU with no specific
+#:     item renders BLANK, never a fallback dressed as a price.
+#:
+#: ⚠ RESOLVED BY NAME, NOT BY ID. A pricelist renamed or deleted in Odoo makes its column go
+#: blank and makes `report["lists_missing"]` name it — a hard-coded id would keep pointing at
+#: whatever inherited it and mislabel every cell silently.
+PRICELIST_COLUMNS = (
+    ("price_fisch", "Fisch"),
+    ("price_royal_1", "Royal 1"),
+    ("price_royal_2", "Royal 2"),
+)
+
+
+def pricelist_by_code():
+    """`({code: {column_key: price}}, report)` — the date-valid FIXED base-tier price for each
+    declared pricelist, keyed EXACTLY as `catalogue()` keys its rows.
+
+    ⛔ THE KEYING IS LOAD-BEARING, not a detail. `catalogue()` keys on `default_code` with a
+    `pid:{id}` fallback for the ~33 active records that carry none. Keying this map any other
+    way would leave those SKUs permanently blank while an oracle counting active products
+    counted them — a red gate on a working build, or worse, a silent hole nobody counts.
+
+    **The base tier, deliberately.** `pricecomp._tier_for` picks the highest `min_quantity` at
+    or below an order's quantity, because it is pricing a LINE that has one. A catalogue column
+    has no quantity in hand, so it takes the LOWEST `min_quantity` — the price at qty 1. Rules
+    above that break are a bulk price, and `report["qty_break_only"]` counts the SKUs whose only
+    rule sits on one (MEASURED: 10 rules of 10,464 carry a break at all).
+
+    **Variant rules beat template rules**, matching `pricecomp._tier_for`: a `0_product_variant`
+    rule is the more specific statement about this exact SKU.
+
+    ⚠ DEGRADES TO `({}, report)` on a read failure, matching `_inventory_by_code` rather than
+    `catalogue()`: these are COLUMNS, and a product grid that will not render because pricing is
+    momentarily unreachable is a worse failure than one with blank price columns. The blanks are
+    not silent — `product_data.validate()`'s coverage leg reconciles each column against a fresh
+    Odoo count and goes red at zero.
+
+    ⭐ **The report exists because R6's second sentence is law** (*"if it can't be done, you need
+    to explicitly tell me why and recommend a fix"*). Everything this reader CANNOT see is
+    counted rather than dropped: rules on pricelists the contract does not declare, non-fixed
+    (`formula`/`percent`) rules, the `3_global` fallback, and prices that only exist above a
+    quantity break.
+    """
+    # ⚠ THE COUNTERS ARE DISJOINT AND ORDER-DEPENDENT, and saying so is the difference between a
+    # report and a misleading one. A rule is classified ONCE, by the first reason it is skipped:
+    # undeclared list → out of date → not fixed → global → zero price. So `rules_not_fixed: 0`
+    # means "no formula rule on a list we declare", NOT "this Odoo has no formula rules"
+    # (MEASURED 2026-08-12: it has exactly one, and it sits on Public Pricelist, which the
+    # contract does not declare — so it lands in `rules_undeclared_list`).
+    report = {"lists_missing": [], "rules_total": 0, "rules_undeclared_list": 0,
+              "rules_not_fixed": 0, "rules_global": 0, "rules_out_of_date": 0,
+              "rules_zero_price": 0, "qty_break_only": 0}
+    try:
+        pl_rows = O.search_read('product.pricelist', [], ['id', 'name'])
+        by_name = {}
+        for p in pl_rows:
+            by_name.setdefault(str(p.get('name') or '').strip(), p['id'])
+        wanted = {}
+        for col, name in PRICELIST_COLUMNS:
+            pid = by_name.get(name)
+            if pid is None:
+                report["lists_missing"].append(name)
+            else:
+                wanted[pid] = col
+
+        # ⭐⭐ FILTERED SERVER-SIDE, AND THE REASON IS A MEASUREMENT, NOT A STYLE PREFERENCE.
+        # Reading all 10,464 rules with 9 fields and sorting them in Python costs **30.1s** on
+        # this connection; the same rules under a server-side domain with 6 fields cost
+        # **13.6s** (measured 2026-08-12, back to back). `pool()` runs this on a scope's
+        # first-ever build, so that 16.5s is 16.5s of somebody's page load.
+        #
+        # ⚠ The domain reproduces the Python predicate EXACTLY, and the null legs are the part
+        # that is easy to get wrong: an absent `date_start` is `False`, not a past date, so
+        # `('date_start','<=',today)` ALONE would drop every open-ended rule — which is almost
+        # all of them.
+        today = P.today().isoformat()
+        _declared = sorted(wanted)
+        _kinds = ['0_product_variant', '1_product']
+        _live = [('pricelist_id', 'in', _declared), ('compute_price', '=', 'fixed'),
+                 ('applied_on', 'in', _kinds),
+                 '|', ('date_start', '=', False), ('date_start', '<=', today),
+                 '|', ('date_end', '=', False), ('date_end', '>=', today),
+                 ('fixed_price', '>', 0)]
+        rules = O.search_read(
+            'product.pricelist.item', _live,
+            ['pricelist_id', 'product_id', 'product_tmpl_id', 'applied_on', 'fixed_price',
+             'min_quantity']) if _declared else []
+
+        # ⭐ R6's SECOND SENTENCE, PAID FOR WITH `search_count` RATHER THAN A WIDER READ. Six
+        # counts cost ~1.2s together; the rules they count would cost 16s to read. What this
+        # reader cannot see is still REPORTED — it is just no longer transferred.
+        def _n(extra):
+            try:
+                return O.get_odoo().search_count('product.pricelist.item', extra)
+            except Exception:
+                return -1                      # -1 reads as "not measured", never as zero
+        _dated = ['|', ('date_start', '=', False), ('date_start', '<=', today),
+                  '|', ('date_end', '=', False), ('date_end', '>=', today)]
+        report["rules_total"] = _n([])
+        report["rules_undeclared_list"] = _n([('pricelist_id', 'not in', _declared)]) \
+            if _declared else report["rules_total"]
+        if _declared:
+            _on = [('pricelist_id', 'in', _declared)]
+            # `percent_price` and formula rules are read NOWHERE in this repo. A rule we cannot
+            # price is one the operator is TOLD about, never one that quietly becomes a blank.
+            report["rules_not_fixed"] = _n(_on + [('compute_price', '!=', 'fixed')])
+            report["rules_global"] = _n(_on + [('compute_price', '=', 'fixed'),
+                                               ('applied_on', 'not in', _kinds)])
+            report["rules_out_of_date"] = (
+                _n(_on + [('compute_price', '=', 'fixed'), ('applied_on', 'in', _kinds)])
+                - _n(_on + [('compute_price', '=', 'fixed'),
+                            ('applied_on', 'in', _kinds)] + _dated))
+            # A zero price is not "free" — it is an unset rule. Blank says so; 0 does not.
+            report["rules_zero_price"] = _n(
+                _on + [('compute_price', '=', 'fixed'), ('applied_on', 'in', _kinds)]
+                + _dated + [('fixed_price', '<=', 0)])
+
+        by_var, by_tmpl = {}, {}
+        for r in rules:
+            col = wanted[O.m2o_id(r.get('pricelist_id'))]
+            if r.get('applied_on') == '0_product_variant' and r.get('product_id'):
+                by_var.setdefault((col, O.m2o_id(r['product_id'])), []).append(r)
+            elif r.get('product_tmpl_id'):
+                by_tmpl.setdefault((col, O.m2o_id(r['product_tmpl_id'])), []).append(r)
+
+        dom = [('active', '=', True)]
+        prods = O.search_read('product.product', dom,
+                              ['id', 'default_code', 'product_tmpl_id'], limit=50000)
+        n = O.get_odoo().search_count('product.product', dom)
+        if len(prods) != n:
+            # Same guard, same reason as `catalogue()`: a short pull renders as a plausible
+            # smaller set of priced SKUs with nothing reporting it.
+            raise ValueError(
+                f"products.pricelist_by_code: the product pull is TRUNCATED — read {len(prods)} "
+                f"rows against a search_count of {n}.")
+    except Exception as e:
+        report["error"] = f"{type(e).__name__}: {str(e)[:200]}"
+        return {}, report
+
+    out = {}
+    for p in prods:
+        code = (str(p['default_code']).strip() if p.get('default_code') else f"pid:{p['id']}")
+        tmpl = O.m2o_id(p.get('product_tmpl_id'))
+        cells = {}
+        for col, _name in PRICELIST_COLUMNS:
+            cands = by_var.get((col, p['id'])) or by_tmpl.get((col, tmpl))
+            if not cands:
+                continue
+            base = min(cands, key=lambda r: r.get('min_quantity') or 0.0)
+            if (base.get('min_quantity') or 0.0) > 1.0:
+                report["qty_break_only"] += 1
+            cells[col] = base.get('fixed_price')
+        if cells:
+            out.setdefault(code, {}).update(cells)
+    return out, report
+
+
 def catalogue_count():
     """The INDEPENDENT population oracle: Odoo's own count of active products.
 

web/public/sample_customers.json

@@ -1,529 +1,545 @@
-{
-  "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": "street",
+      "label": "Street",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "First address line, from res.partner directly - not the geocoder, so a customer the map cannot place still shows its address."
+    },
+    {
+      "key": "street2",
+      "label": "Street 2",
+      "type": "text",
+      "source": "odoo",
+      "default": false,
+      "description": "Second address line (suite, unit, floor) on the customer's Odoo address."
+    },
+    {
+      "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/automation/AutomationDetail.tsx

@@ -171,6 +171,32 @@ export default function AutomationDetail({
   const cfg = (automation.config || {}) as Record<string, string | number | boolean>;
   const kind = automation.kind;
 
+  /**
+   * ⭐⭐ WAVE 30 · W30-T17 — IS THIS A CORPUS SEARCH? ONE PREDICATE, AND THAT IS THE POINT.
+   *
+   * ⛔ THE DEFECT THIS CLOSES, AND WHY IT WAS A 400 RATHER THAN A MISSING FEATURE.
+   * `automation_engine.py:clean_config`'s discovery branch is already SHARED across both kinds
+   * (`if kind in ("discover_instagram","discover_tiktok")`) and it reads `recordsLimit` with NO
+   * fallback to the stored value — so a config that omits the key is read as `limit = 0` and
+   * refused with the owner's exact sentence about an unbounded discovery query. Three arms in
+   * this file tested `kind === "discover_instagram"` as a literal, so a `discover_tiktok`
+   * automation fell through `buildConfig` to `{ targetTable }` and every save after the first
+   * 400'd — on a panel that was showing the person a records limit the whole time.
+   *
+   * ⛔ A SHARED PREDICATE, NOT A SECOND STRING TEST, AND THE REASON IS MEASURED RATHER THAN
+   * STYLISTIC: TikTok's kind shipped in wave 29 and was missed in FOUR places here and THREE in
+   * the engine, because each site was an independent literal and none of them was wrong on its
+   * own. B is making the same change server-side in the same wave for the same reason. The next
+   * platform gets missed once — here — instead of seven times.
+   *
+   * ⚠ NOT the same question as "does this automation have a TikTok trigger". The kind is what
+   * `clean_config` branches on and what `RUNNERS` dispatches on; the trigger is what a person
+   * picked. `clean_definition`'s law 1 derives one from the other, server-side, and this client
+   * reads the RESULT rather than re-deriving it — two derivations of one fact is how the two
+   * halves disagree.
+   */
+  const isDiscovery = kind === "discover_instagram" || kind === "discover_tiktok";
+
   const [name, setName] = useState(automation.name || "");
   const [cron, setCron] = useState(automation.schedule?.cron || "0 6 * * *");
   const [message, setMessage] = useState("");
@@ -227,7 +253,10 @@ export default function AutomationDetail({
     Math.min(Math.max(1, Number(cfg.maxPosts) || 10), 12)
   );
 
-  // --- discover_instagram half (R7)
+  // --- the DISCOVERY half (R7) — `discover_instagram` and, since W30-T17, `discover_tiktok`.
+  //     ⚠ The 25 is not this panel's invention: it mirrors `automation_engine.py`'s own
+  //     `DISCOVER_SEED_RECORDS`, which is what the server writes when a discovery trigger is
+  //     first picked. Two numbers here would be two answers to "how many by default".
   const [recordsLimit, setRecordsLimit] = useState(Number(cfg.recordsLimit || 25));
   const [joinOp, setJoinOp] = useState(String(cfg.operator || "and"));
   /**
@@ -348,10 +377,22 @@ export default function AutomationDetail({
    * ⚠ The trigger's OWN pickers keep using the trigger's own table; these are two different
    * questions and answering both from one variable is what produced the bug.
    */
-  const walkTable =
-    kind === "discover_instagram"
-      ? String(cfg.targetTable || "") || String(discover?.table || "")
-      : String(cfg.targetTable || "") || String(automation.trigger?.table || "");
+  /*
+    ⭐ W30-T17 — BOTH DISCOVERY KINDS TAKE THIS BRANCH NOW, AND THE FALLBACK DELIBERATELY DOES NOT.
+    ⛔ `discover.table` IS THE INSTAGRAM VOCABULARY'S OWN TABLE, not "the discovery table".
+    MEASURED (scout, 2026-08-12): the wire carries exactly ONE `discover` object — built by
+    `routes_automation.py:list_automations` from `automation_engine.py:BD_FILTER_FIELDS` and
+    friends, with no platform argument anywhere on the route — and its `table` is Instagram's.
+    Widening this fallback to every discovery kind would therefore have offered a TikTok
+    automation the columns of an Instagram database: a list that looks authoritative and names
+    the wrong database, which is the exact failure the comment above says is worse than no list.
+    So TikTok gets `cfg.targetTable` (which `clean_config` sets to its own `ut_tt_profile`) or
+    NOTHING, and nothing renders as "this automation has no table for it to read" — true.
+  */
+  const walkTable = isDiscovery
+    ? String(cfg.targetTable || "") ||
+      (kind === "discover_instagram" ? String(discover?.table || "") : "")
+    : String(cfg.targetTable || "") || String(automation.trigger?.table || "");
 
   /**
    * WHAT STARTS THIS ONE, as a key. The server's stored trigger when it ships one;
@@ -474,8 +515,11 @@ export default function AutomationDetail({
    * a second reader of a string that exists to be shown to a person. One arithmetic, two
    * wordings, and neither wording is parsed by anything.
    */
+  /* W30-T17: both discovery kinds hold half-written rows back, because `completePreds` is what
+     `buildConfig` sends for both and a held row that is never announced is the silent-drop class
+     this module refuses everywhere else. A TikTok automation used to report 0 held, always. */
   const heldCount = (): number =>
-    kind === "discover_instagram" ? preds.length - completePreds().length : 0;
+    isDiscovery ? preds.length - completePreds().length : 0;
 
   const heldNote = (): string => {
     const held = heldCount();
@@ -498,7 +542,18 @@ export default function AutomationDetail({
         targetLabel,
       };
     }
-    if (kind === "discover_instagram") {
+    /*
+      ⛔ BOTH DISCOVERY KINDS, ONE SHAPE (W30-T17). This arm was `kind === "discover_instagram"`,
+      so a TikTok discovery automation fell all the way through to `{ targetTable }` and dropped
+      `recordsLimit` on EVERY save. The server's discovery branch reads that key with no
+      prev-fallback, so the drop is not "the old value survives" — it is `limit = 0`, which the
+      save door refuses outright. Instagram never showed it because this arm existed.
+      ⚠ The FIRST save is a different question and it is not fixed here: `pickTrigger` calls this
+      while `kind` is still `plain` (the server flips it after reading the trigger), so the
+      opening PATCH of a brand-new discovery automation carries no limit by construction. That
+      one is the engine's seed to set — W30-T04 — and it is why the two tickets are separate.
+    */
+    if (isDiscovery) {
       return {
         recordsLimit,
         operator: joinOp,

web/src/automation/AutomationSurface.tsx

@@ -14,7 +14,7 @@
 // untouched.
 // ---------------------------------------------------------------------------
 import type { KeyboardEvent as ReactKeyboardEvent } from "react";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { Suspense, lazy, useCallback, useEffect, useRef, useState } from "react";
 
 import type { AutomationOpenDetail } from "../apiContract";
 import { AUTOMATION_OPEN_EVENT } from "../apiContract";
@@ -26,16 +26,39 @@ import { AUTOMATION_OPEN_EVENT } from "../apiContract";
 // 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,
+  cachedAutomations,
   createAutomation,
   listAutomations,
   liveStepOf,
   patchAutomation,
 } from "./automationApi";
 
+/**
+ * ⭐⭐ WAVE 30 · T21 (owner items 4 + 5) — THE EDITOR STOPS SHIPPING INSIDE THE LIST.
+ *
+ * ⛔ THIS `lazy()` IS THE TICKET. `AutomationDetail` was a STATIC import, and it statically pulls
+ * `AutomationBuilder` (which in turn pulls `CondBuilder`, `PresetPlan` and `TriggerPicker`),
+ * `AutomationFind` and `AutomationTrigger` — so the whole editor was linked into the one chunk a
+ * person must download before the RAIL can paint a list of names. MEASURED at 88,771 B, against
+ * `HomePage` at 4,814 and `ConnectorsPage` at 3,551. That is the "Automation takes forever to
+ * load" complaint, and it had survived two waves because nothing asserted a number.
+ *
+ * ⛔ AND IT NEEDS ITS OWN `<Suspense>`, NOT `Shell.tsx`'s. `Lazily` already wraps this whole
+ * surface, but a Suspense boundary catches ANY suspending descendant — so without an inner
+ * boundary, opening an automation would suspend the boundary that owns the RAIL and blank the
+ * list you just clicked in. The inner one keeps the rail painted while the editor streams in.
+ * `fallback={null}` is deliberate and is `Lazily`'s own choice, not a shortcut: the work area is
+ * simply not there for the moment the chunk is in flight, which is what every other route in this
+ * product already does. ⚠ A skeleton here would be a NEW loading screen in the same wave that
+ * exists to remove one (T22).
+ * ⚠ Default export, checked: `Shell.tsx:53` records that `lazy()` over a NAMED export fails at
+ * runtime, on click, and only for that one surface — `AutomationDetail` exports default.
+ */
+const AutomationDetail = lazy(() => import("./AutomationDetail"));
+
 /**
  * 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
@@ -185,7 +208,12 @@ function nextAutomationName(existing: Automation[]): string {
 }
 
 export default function AutomationSurface() {
-  const [data, setData] = useState<AutomationList | null>(null);
+  /* ⭐ T22 — SEEDED FROM THE CLIENT MEMO, so a revisit inside the freshness window never passes
+     through `data === null` and therefore never paints the skeleton. The lazy initialiser runs
+     once, on mount, BEFORE the first paint — `useState(cachedAutomations())` would call it on
+     every render instead, which is the same value at needless cost. A cold start still returns
+     null and still gets the skeleton: it is made rare, not removed (see `automationApi.ts`). */
+  const [data, setData] = useState<AutomationList | null>(() => cachedAutomations());
   const [error, setError] = useState("");
   const [activeId, setActiveId] = useState<string>("");
   const [railShut, setRailShut] = useState(false);
@@ -574,7 +602,10 @@ export default function AutomationSurface() {
           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.
         */}
+        {/* T21: the editor's own Suspense boundary — see the `lazy()` above for why it cannot be
+            `Shell.tsx`'s. `fallback={null}`, matching `Lazily`. */}
         {active ? (
+          <Suspense fallback={null}>
           <AutomationDetail
             key={active.id}
             automation={active}
@@ -631,6 +662,7 @@ export default function AutomationSurface() {
               await load();
             }}
           />
+          </Suspense>
         ) : (
           /*
            * THE EMPTY STATE IS ONE LINE AND A BUTTON (owner ruling R13 — "never

web/src/automation/TriggerPicker.tsx

@@ -27,6 +27,8 @@
 // ---------------------------------------------------------------------------
 import { useEffect, useRef, useState } from "react";
 
+import { brandForConnector, brandForKind, hasBrandKind } from "../connectors/brandMarks";
+
 import type { TriggerOption } from "./automationApi";
 import { groupTriggers, selectedTrigger } from "./steps";
 
@@ -46,6 +48,18 @@ import { groupTriggers, selectedTrigger } from "./steps";
  * icons).
  */
 export function TriggerMark({ kind = "" }: { kind?: string }) {
+  /*
+    ⭐⭐ WAVE 30 · ITEM 7 / R3 + R4 — A BRAND WINS OVER THE HOUSE GLYPH, and it is resolved HERE
+    rather than at the four call sites. `TriggerMark` is drawn in the flyout, in the compact
+    Properties control, and by `AutomationBuilder` on the trigger card; a per-call-site check is
+    three chances to give the same trigger two identities on one screen.
+    ⛔ The geometric glyphs BELOW ARE NOT DELETED. They are the fallback for every unbranded
+    trigger and, for the two branded ones, the record of what this picker drew before the owner
+    asked for logos — a magnifier with a person in it, and the same frame with a note. Deleting
+    them would also delete the only description of why those two shapes differed.
+  */
+  const brand = brandForKind(kind);
+  if (brand) return brand;
   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,
@@ -234,7 +248,7 @@ function TriggerList({
         title={t.detail || ""}
         onClick={() => onPick(t.key)}
       >
-        <span className="autox-card-mark">
+        <span className={"autox-card-mark" + (hasBrandKind(t.key) ? " is-brand" : "")}>
           <TriggerMark kind={t.key} />
         </span>
         <span className="autox-menu-text">
@@ -271,11 +285,42 @@ function TriggerList({
               reading "connector" in lower case. */}
           {g.label ? <p className="autox-menu-head">{g.label}</p> : null}
           {g.rows.map(row)}
+          {/*
+            ⭐⭐ WAVE 30 · ITEM 7 / R3 — THE CONNECTOR NEST IS A COLLAPSED DISCLOSURE NOW.
+            The owner, verbatim and for the third wave: *"Only when I click 'Scraper' under each
+            automation trigger and actions would I see the option to choose either Instagram OR
+            TikTok. That's it."*
+
+            ⛔ WHAT WAS HERE WAS THE COMPLAINT ITSELF, and it was an ASYMMETRY rather than a
+            missing feature: this rendered `<div className="autox-menu-sub">` with a `<p>` heading
+            — always open, merely indented — while `AutomationBuilder`'s action menu four inches
+            away already used exactly the markup below. One menu asked you to click; the other
+            showed you everything. So this is not a new pattern, it is the OTHER menu's pattern,
+            copied verbatim so the two cannot drift apart again.
+
+            ⚠ `<details>` and not a hand-built disclosure: it opens on Enter and Space with no
+            keydown handler, it needs no open/closed state of its own to get wrong, and it is
+            CLOSED by default, which is the whole ruling.
+            ⚠ The summary wears the same 26px `autox-card-mark` the rows beneath it wear (T19's
+            marks). A smaller slot here was the first version and it made the heading look like a
+            different KIND of thing from its own children — which is the asymmetry again, one
+            level down.
+          */}
           {g.sub.map((s) => (
-            <div className="autox-menu-sub" key={s.key}>
-              <p className="autox-menu-subhead">{s.label}</p>
+            <details className="autox-menu-nest" key={s.key}>
+              <summary className="autox-menu-row autox-menu-sum">
+                {brandForConnector(s.key) ? (
+                  <span className="autox-card-mark is-brand">{brandForConnector(s.key)}</span>
+                ) : null}
+                <span className="autox-menu-text">
+                  <span className="autox-menu-label">{s.label}</span>
+                  <span className="autox-menu-detail">
+                    {s.rows.length} trigger{s.rows.length === 1 ? "" : "s"}
+                  </span>
+                </span>
+              </summary>
               {s.rows.map(row)}
-            </div>
+            </details>
           ))}
         </div>
       ))}
@@ -367,7 +412,9 @@ export default function TriggerPicker({
             The `<select>` this replaces carried the same guard, and without it a trigger pointed
             at something withheld from this session would LOOK unconfigured and the next patch
             would write the blank over it. */}
-        <span className="autox-card-mark">
+        <span
+          className={"autox-card-mark" + (hasBrandKind(picked?.key || "") ? " is-brand" : "")}
+        >
           <TriggerMark kind={picked?.key || ""} />
         </span>
         <span className="autox-trigbtn-label">

web/src/automation/automationApi.ts

@@ -24,11 +24,24 @@ import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal } from "..
  * `scrape_db` and `field_instagram` survive on the two automations that already use them and
  * no new one can be created (R6); `discover_instagram` is now reached by PICKING the
  * `ig_profile_match` trigger rather than by a wizard.
+ *
+ * ⭐⭐ WAVE 30 · W30-T17 — `discover_tiktok` JOINS, AND IT WAS MISSING FROM THIS UNION SINCE THE
+ * DAY THE KIND SHIPPED. `automation_engine.py:KINDS` has carried it since wave 29, and
+ * `clean_definition`'s law-1 arm flips a `tiktok_profile_match` trigger to it UNCONDITIONALLY —
+ * so the server has been storing a kind this client's own type system said could not exist.
+ * ⛔ THE COST WAS NOT COSMETIC. A union that cannot express the value makes `kind ===
+ * "discover_tiktok"` a COMPILE ERROR, so every arm that had to learn TikTok
+ * (`buildConfig`, `heldCount`, `walkTable`) could not be written even by someone who noticed —
+ * the type was quietly enforcing the bug. This is the client half of [[wire-takes-a-list-caller-passes-one]]
+ * turned inside out: the wire carried a value the caller could not name.
+ * ⚠ It is a DISCOVERY kind, so the rule to reach for is the shared predicate, never a fourth
+ * string test: `AutomationDetail.tsx:isDiscovery` is the one place that decides.
  */
 export type AutomationKind =
   | "scrape_db"
   | "field_instagram"
   | "discover_instagram"
+  | "discover_tiktok"
   | "plain";
 export type RunState = "idle" | "running" | "ok" | "error" | "partial";
 /*
@@ -809,8 +822,52 @@ function send<T>(path: string, init?: RequestInit): Promise<T> {
   }).then((r) => result<T>(r));
 }
 
+/**
+ * ⭐⭐ WAVE 30 · T22 (owner item 4) — THE CLIENT MEMO THAT MAKES THE LOADING SCREEN RARE.
+ *
+ * ⛔ THE SKELETON IS NOT THE DEFECT AND MUST NOT BE DELETED. `AutomationSurface` renders
+ * `.auto-rail-loading` while `data === null`, and W29-T01 added it for a real reason: before it,
+ * a person who owns several automations was told "No automations yet." on every single visit,
+ * for the whole first round trip. Deleting it restores that false-empty. **The fix is to make
+ * `data === null` UNREACHABLE on a revisit, not to hide what it renders.**
+ *
+ * ⭐ WHY THE MEMO LIVES HERE AND NOT IN THE COMPONENT, which is the whole win: `Shell.tsx:1155`
+ * ALREADY calls `listAutomations()` on Home mount for its automation tiles. Memoising at this
+ * door — the one function both callers share — means Home → Automation is paid for before the
+ * click, with **no edit to `shell/`** (another session's fence). A cache inside the component
+ * could never see Shell's call.
+ *
+ * ⚠ STALE-WHILE-REVALIDATE, STATED: the seed paints last-known rows and the mount effect still
+ * fetches, so a revisit shows real names instantly and corrects itself. Every mutation path in
+ * the surface already calls `load()`, which refreshes this memo, so nothing has to remember to
+ * invalidate it. An error leaves the memo intact ON PURPOSE — last-known rows beside an error
+ * banner beat an empty rail that blames the reader.
+ * ⚠ Module scope, so it dies with the tab. It is a paint accelerator, never storage — nothing
+ * here may outlive a session, because the account decides the tenant [[aios-multi-tenancy]].
+ */
+const AUTOMATIONS_FRESH_MS = 5 * 60 * 1000;
+
+let listMemo: { at: number; data: AutomationList } | null = null;
+
+/** The last list, if it is still fresh — otherwise `null`, which is a COLD start and says so. */
+export function cachedAutomations(): AutomationList | null {
+  if (!listMemo) return null;
+  if (Date.now() - listMemo.at > AUTOMATIONS_FRESH_MS) return null;
+  return listMemo.data;
+}
+
+/** Drop the memo. For a tenant/identity change — a paint accelerator must never cross accounts. */
+export function forgetAutomations(): void {
+  listMemo = null;
+}
+
 export function listAutomations(abort?: AbortSignal): Promise<AutomationList> {
-  return send<AutomationList>("/automations", { signal: abort });
+  return send<AutomationList>("/automations", { signal: abort }).then((data) => {
+    // ⚠ ONLY ON SUCCESS. `send` throws on a non-2xx, so a failed poll cannot overwrite a good
+    // list with nothing — which would turn a transient 500 into the false-empty above.
+    listMemo = { at: Date.now(), data };
+    return data;
+  });
 }
 
 export function listTables(abort?: AbortSignal): Promise<{ tables: UserTable[] }> {

web/src/connectors/ConnectorsPage.tsx

@@ -8,10 +8,19 @@
 // touching the shell's "an undeclared surface is denied" law (nav.ts'
 // `CHROME_ROUTES` note carries the full argument).
 //
-// ⛔ NO THIRD-PARTY LOGOS AND NO EMOJIS (R8 + DESIGN.md §4). A connector's mark is
-// a two-letter tile in the chip family every database already wears, so the
-// directory reads as part of this product rather than as a wall of other
-// companies' branding — and nobody has to ship, license or update an icon set.
+// ⭐⭐ WAVE 30 · R4 SUPERSEDES WAVE-23 R8 FOR CONNECTOR IDENTITY. A connector card
+// wears its company's REAL mark, drawn as inline SVG by `./brandMarks`. The owner
+// asked for this three times; what stood here was the rule that refused it:
+//
+//   "⛔ NO THIRD-PARTY LOGOS AND NO EMOJIS (R8 + DESIGN.md §4). A connector's mark
+//    is a two-letter tile in the chip family every database already wears…"
+//
+// ⚠ THE REST OF THAT RULE IS UNCHANGED and is not weakened by R4: still no emojis
+// anywhere, still nothing shipped, licensed or hotlinked (every mark is a React
+// component in this directory), and `tileText` SURVIVES as the fallback for any
+// connector we have no logo for — a two-letter tile is the honest answer to "we
+// do not have that company's mark", and deleting it would have left every planned
+// row with an empty square.
 //
 // ⚠ NO CLIENT UNION OVER `state` OR `kind`. They are the server's vocabulary and
 // arrive as strings (the wave-9 law): a client `type State = "connected" | …`
@@ -20,6 +29,7 @@
 
 import { useEffect, useState } from "react";
 import { API_V1, CREDENTIALS } from "../apiContract";
+import { brandForConnector } from "./brandMarks";
 
 /** One row of the directory. Everything optional but `key` + `label` is genuinely optional on
  *  the wire — a builtin has no provider, a planned connector has no `connectedAs`. */
@@ -56,6 +66,22 @@ export interface ConnectorRow {
   note?: string;
   /** What the admin will be asked for — shown where the decision is made, not in a tour. */
   hint?: string;
+  /**
+   * ⭐ WAVE 30 · R4 — the PLATFORMS behind one connector, today only the Scraper's.
+   *
+   * ⛔ NOT ROWS OF THEIR OWN, and the ruling is precisely about that: *"Only when I click
+   * 'Scraper' … would I see the option to choose either Instagram OR TikTok."* They carry no
+   * `state`, no credential and no manage door, because one key configures both — a per-platform
+   * state would be a second answer to a question that already has one.
+   */
+  platforms?: ConnectorPlatform[];
+}
+
+/** One platform inside a connector's drill. Name, sentence, and the key its mark is drawn from. */
+export interface ConnectorPlatform {
+  key: string;
+  label: string;
+  desc: string;
 }
 
 type Load =
@@ -65,6 +91,25 @@ type Load =
 
 const str = (v: unknown): string => (typeof v === "string" ? v : "");
 
+/**
+ * The platform list, read the way `parseDirectory` reads a row: a platform with no name is
+ * DROPPED rather than rendered from its key, and a payload with no `platforms` at all yields
+ * `[]` — an older server simply shows a card with no drill, which is the honest degradation.
+ */
+export function parsePlatforms(raw: unknown): ConnectorPlatform[] {
+  if (!Array.isArray(raw)) return [];
+  const out: ConnectorPlatform[] = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object") continue;
+    const p = item as Record<string, unknown>;
+    const key = str(p.key).trim();
+    const label = str(p.label).trim();
+    if (!key || !label) continue;
+    out.push({ key, label, desc: str(p.desc) });
+  }
+  return out;
+}
+
 export function parseDirectory(body: unknown): ConnectorRow[] {
   const raw = (body as { connectors?: unknown } | null)?.connectors;
   if (!Array.isArray(raw)) return [];
@@ -90,13 +135,20 @@ export function parseDirectory(body: unknown): ConnectorRow[] {
       ...(str(c.startUrl) ? { startUrl: str(c.startUrl) } : {}),
       ...(str(c.note) ? { note: str(c.note) } : {}),
       ...(str(c.hint) ? { hint: str(c.hint) } : {}),
+      ...(parsePlatforms(c.platforms).length
+        ? { platforms: parsePlatforms(c.platforms) }
+        : {}),
     });
   }
   return out;
 }
 
-/** The card's mark: two letters from the connector's own name, in the database chip family.
- *  Unicode-aware for the same reason the account monogram is (`Shell.tsx:299`). */
+/** The card's FALLBACK mark: two letters from the connector's own name, in the database chip
+ *  family. Unicode-aware for the same reason the account monogram is (`Shell.tsx:299`).
+ *  ⚠ SINCE WAVE 30 IT IS THE FALLBACK, NOT THE RULE (R4) — a connector we have a logo for wears
+ *  the logo, and everything else still wears these two letters. Deleting this on the way to
+ *  "real logos everywhere" would have emptied every card the mark module has no entry for,
+ *  which is most of the planned list. */
 export function tileText(label: string): string {
   const chars = String(label ?? "").match(/[\p{L}\p{N}]/gu) ?? [];
   return chars.slice(0, 2).join("").toUpperCase();
@@ -205,12 +257,35 @@ export default function ConnectorsPage({
       ) : null}
 
       <div className="conn-grid">
-        {rows.map((row) => {
-          const planned = row.state === "planned";
-          const connected = row.state === "connected";
-          return (
+        {rows.map((row) => (
+          <ConnectorCard key={row.key} row={row} onKeychain={onKeychain} />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * ONE CARD, EXPORTED — which is what lets `_conn_shot.tsx` paint the real thing.
+ *
+ * ⛔ EXTRACTED IN WAVE 30 SO THE DIRECTORY CAN BE LOOKED AT, and that is not a cosmetic reason.
+ * The page fetches on mount, and `renderToStaticMarkup` does not run effects — so a static render
+ * of `ConnectorsPage` shows a spinner and nothing else, forever. The owner's item 7 is a VISUAL
+ * ruling ("their logo to be fucking displayed"), and a ticket whose done-when is visual has to be
+ * provable by a picture of the shipping component rather than by a picture of a copy of it.
+ * ⚠ Behaviour is byte-identical: this is the same JSX, lifted whole out of the map.
+ */
+export function ConnectorCard({
+  row,
+  onKeychain,
+}: {
+  row: ConnectorRow;
+  onKeychain: () => void;
+}) {
+  const planned = row.state === "planned";
+  const connected = row.state === "connected";
+  return (
             <div
-              key={row.key}
               className={"conn-card" + (planned ? " is-planned" : "")}
               // ⛔ `aria-disabled`, NOT `inert`/`pointer-events` alone. A planned card is
               // non-interactive by R8, and a card that merely LOOKS faded while still taking a
@@ -220,9 +295,20 @@ export default function ConnectorsPage({
               {...(planned ? { "aria-disabled": true } : {})}
             >
               <div className="conn-card-head">
-                <span className="shell-db-chip conn-tile" aria-hidden="true">
-                  {tileText(row.label)}
-                </span>
+                {/* ⭐ WAVE 30 · R4 — THE LOGO, OR THE LETTERS. Two mutually exclusive marks, and
+                    they take DIFFERENT chips deliberately: letters ride the base chip because
+                    12px text needs 4.5:1 and only `--lp-primary` clears it, while a logo brings
+                    its own colour and wants neutral ground under it. Writing one span that
+                    switched only its contents would have put a brand mark on a blue chip. */}
+                {brandForConnector(row.key, 22) ? (
+                  <span className="conn-tile is-brand" aria-hidden="true">
+                    {brandForConnector(row.key, 22)}
+                  </span>
+                ) : (
+                  <span className="shell-db-chip conn-tile" aria-hidden="true">
+                    {tileText(row.label)}
+                  </span>
+                )}
                 <span className="conn-card-name">{row.label}</span>
                 <span className={"conn-state" + stateTone(row.state)}>
                   {/* The server's own word, sentence-cased by CSS never by `toUpperCase` — R6
@@ -231,6 +317,33 @@ export default function ConnectorsPage({
                 </span>
               </div>
               <p className="conn-card-desc">{row.desc}</p>
+              {/* ⭐⭐ WAVE 30 · R4 — THE DRILL, AND IT IS COLLAPSED FOR THE SAME REASON THE
+                  TRIGGER MENU'S IS. The owner's words are a sequence, not a layout: *"Only when
+                  I click 'Scraper' … would I see the option to choose either Instagram OR
+                  TikTok."* So the platforms are behind a disclosure, not listed beside the
+                  card's own sentence — and it is a real `<details>`, which opens on Enter and
+                  Space with no keydown handler and carries no open/closed state to get wrong.
+                  ⚠ These rows are INFORMATIONAL. A platform has no credential of its own, so it
+                  offers no Connect button — the card's own action configures both, and a second
+                  door here would be one that has nothing to open. */}
+              {row.platforms && row.platforms.length ? (
+                <details className="conn-plats">
+                  <summary className="conn-plats-sum">
+                    {row.platforms.length} platform{row.platforms.length === 1 ? "" : "s"}
+                  </summary>
+                  {row.platforms.map((p) => (
+                    <div className="conn-plat" key={p.key}>
+                      <span className="conn-plat-mark" aria-hidden="true">
+                        {brandForConnector(p.key, 16)}
+                      </span>
+                      <span className="conn-plat-text">
+                        <span className="conn-plat-name">{p.label}</span>
+                        {p.desc ? <span className="conn-plat-desc">{p.desc}</span> : null}
+                      </span>
+                    </div>
+                  ))}
+                </details>
+              ) : null}
               {connected && row.connectedAs ? (
                 <p className="conn-card-meta">Connected as {row.connectedAs}</p>
               ) : null}
@@ -266,9 +379,5 @@ export default function ConnectorsPage({
                 </a>
               ) : null}
             </div>
-          );
-        })}
-      </div>
-    </div>
   );
 }

web/src/connectors/brandMarks.tsx

@@ -0,0 +1,294 @@
+// ---------------------------------------------------------------------------
+// connectors/brandMarks.tsx — WAVE 30, owner item 7 (rulings R3 + R4):
+// THE ONE PLACE A CONNECTOR'S IDENTITY IS DRAWN.
+//
+// The owner, verbatim and for the third time: *"their Instagram and Tiktok logo
+// to be fucking displayed, same with all logos under the Connectors module."*
+//
+// ⛔ THIS SUPERSEDES A RULE THAT WAS STILL SHIPPING. Wave-23 R8 said connector
+// identity is a two-letter monogram in the chip family, and it was enforced —
+// `verify_home.py:section_connectors` asserted a real mark could not appear.
+// R4 replaces it FOR CONNECTOR IDENTITY ONLY. Everything else the design
+// constitution says is untouched: no emojis anywhere, and no decorative
+// third-party imagery outside this file's purpose, which is telling a person
+// which company a row is about.
+//
+// ⛔ INLINE SVG, NEVER A FILE AND NEVER A REMOTE URL. There is no `assets/` or
+// `icons/` directory in this app and there is not going to be one: every icon
+// in the product is a React component, `index.css` inlines even its font as a
+// `data:` URI, and `customer-grid/types.ts` carries the standing sentence
+// *"Never an external URL: those are neither same-origin nor CSP-safe here."*
+// A remote logo would work today (no CSP header is set) and would be the one
+// thing on the page that can be taken away by somebody else's outage.
+//
+// ⛔ ONE MODULE FOR THREE SURFACES, and that is the whole design. The trigger
+// picker, the action menu and the Connectors directory all answer "which
+// company is this?" — three copies of a logo set is three chances to add a
+// platform in two places and forget the third, which is precisely the defect
+// wave 30 exists to fix on the server side of the same question.
+//
+// ⚠ WHAT THESE ARE, HONESTLY: recognisable SIMPLIFICATIONS drawn from each
+// brand's published silhouette and brand colour, at 16px, not the trademarked
+// artwork. That is the right call at this size — the real Google `G` is a
+// 500-byte path that renders as mush in a 15px box — and it is stated here so
+// nobody "upgrades" them by pasting a vendor's asset file into a repo that has
+// no place to put one.
+//
+// ⚠ THEME. Marks are brand-coloured and must survive BOTH themes, so no mark
+// relies on pure black or pure white for its silhouette: TikTok's note is
+// `currentColor` with its two brand offsets behind it, which is also how the
+// real mark is constructed.
+// ---------------------------------------------------------------------------
+import type { ReactElement } from "react";
+import { useId } from "react";
+
+/**
+ * The canonical brand names this module can draw. Deliberately NOT the same
+ * strings as the connector keys or the trigger kinds: three vocabularies point
+ * AT this one, and folding them together would make a rename in any of the
+ * three a silent loss of an icon.
+ */
+export type BrandName =
+  | "instagram"
+  | "tiktok"
+  | "odoo"
+  | "google"
+  | "gmail"
+  | "stripe"
+  | "shopify"
+  | "webhooks"
+  | "scraper";
+
+/**
+ * Trigger and action KIND -> brand.
+ *
+ * ⛔ KEYED ON THE KIND AND NOT ON THE CONNECTOR, and the reason is R3 itself:
+ * after this wave Instagram and TikTok share `connector.key === "scraper"`, so
+ * the connector can no longer tell them apart. The kind is the only thing that
+ * still distinguishes the two products, which is exactly why the picker's own
+ * `TriggerMark` has always been keyed this way.
+ *
+ * ⚠ An unmapped kind returns null and the caller draws its existing glyph — a
+ * trigger the engine adds tomorrow renders plainly rather than not at all.
+ */
+export const BRAND_OF_KIND: Record<string, BrandName> = {
+  ig_profile_match: "instagram",
+  tiktok_profile_match: "tiktok",
+  enrich_instagram: "instagram",
+  enrich_tiktok: "tiktok",
+  field_instagram: "instagram",
+};
+
+/**
+ * Connector/provider KEY -> brand, for the Connectors directory and for the
+ * collapsed connector nests in both automation menus.
+ *
+ * ⚠ `scraper` and `webhooks` are OURS, not brands — they get house glyphs in
+ * `currentColor` so they sit in the chip family the way they always have. They
+ * are in this map rather than special-cased at the call site so that "what mark
+ * does this row wear" has ONE answer, whoever is asking.
+ */
+export const BRAND_OF_CONNECTOR: Record<string, BrandName> = {
+  odoo: "odoo",
+  google: "google",
+  gmail: "gmail",
+  stripe: "stripe",
+  shopify: "shopify",
+  scraper: "scraper",
+  webhooks: "webhooks",
+  instagram: "instagram",
+  tiktok: "tiktok",
+};
+
+/** The house frame every mark is drawn in. 16×16 user units, sized by the caller. */
+function frame(size: number) {
+  return { width: size, height: size, viewBox: "0 0 16 16", "aria-hidden": true } as const;
+}
+
+/**
+ * ⚠ TIKTOK'S NOTE, DRAWN THREE TIMES. The real mark is one glyph offset in
+ * cyan and magenta behind a solid copy; drawing only the solid copy loses the
+ * brand entirely at this size, and drawing the offsets in black loses it in
+ * dark mode. The solid copy is `currentColor` so it inherits the row.
+ */
+const TT_NOTE =
+  "M9.05 1.9h2.02c.13 1.2.87 2.13 2.03 2.3v2.03c-.78 0-1.53-.2-2.18-.58v3.98"
+  + "a3.62 3.62 0 1 1-3.62-3.62c.16 0 .32.01.48.03v2.06a1.6 1.6 0 1 0 1.27 1.56z";
+
+export function BrandMark({
+  name,
+  size = 15,
+}: {
+  name: BrandName;
+  size?: number;
+}): ReactElement | null {
+  const f = frame(size);
+  // Per-instance, for the reason spelled out at the `<defs>` below. Hooks run for every
+  // name, not only Instagram, because a hook cannot sit behind a conditional return.
+  const gradId = `aios-brand-ig-${useId()}`;
+  if (name === "instagram")
+    return (
+      <svg {...f} fill="none">
+        {/*
+          ⛔⛔ THE GRADIENT ID IS PER-INSTANCE, AND THE FIXED ONE WAS A REAL BUG — FOUND BY A
+          PICTURE, NOT BY A GATE. It shipped for an hour as the constant `aios-brand-ig`, on the
+          reasoning that duplicate ids resolve to the FIRST definition and every definition is
+          byte-identical, so it cannot matter. MEASURED in the connectors shot: the Scraper card
+          holds an Instagram mark inside a COLLAPSED `<details>`, a second card below holds a
+          visible one — and the visible one painted NOTHING. A closed `<details>` is
+          `content-visibility: hidden`, its subtree is not rendered, and a paint server defined
+          inside a skipped subtree does not resolve for a user outside it. "The first definition
+          wins" IS the failure: whichever copy happens to be hidden decides for all of them.
+          ⚠ Nothing about `<details>` is special — `display:none` does the same. Any page holding
+          two of this mark with the first one hidden loses the second.
+          ⚠ `useId` rather than a module counter, so the markup stays DETERMINISTIC for a given
+          tree — the render gates could not assert against a random id — and stable across a
+          server render and its hydration.
+          ⚠ Every check that looks for this mark matches the PREFIX `url(#aios-brand-ig`.
+        */}
+        <defs>
+          {/* ⚠ `userSpaceOnUse` IS LOAD-BEARING AND ITS ABSENCE LOOKED FINE. The default is
+              `objectBoundingBox`, where the coordinates are FRACTIONS of the shape's box — so
+              `1,15 → 15,1` put the whole gradient vector far outside every path and each one
+              painted a single clamped stop. The mark still rendered, still read as Instagram,
+              and was simply flat pink: a defect only a picture catches, which is why one was
+              taken ([[ui-invisible-to-assertions]]). In user space the numbers mean viewBox
+              units, which is what they were written as. */}
+          <linearGradient
+            id={gradId} gradientUnits="userSpaceOnUse"
+            x1="2" y1="14" x2="14" y2="2"
+          >
+            <stop offset="0" stopColor="#FEDA75" />
+            <stop offset="0.32" stopColor="#FA7E1E" />
+            <stop offset="0.62" stopColor="#D62976" />
+            <stop offset="1" stopColor="#962FBF" />
+          </linearGradient>
+        </defs>
+        <rect
+          x="1.7" y="1.7" width="12.6" height="12.6" rx="3.7"
+          stroke={`url(#${gradId})`} strokeWidth="1.5"
+        />
+        <circle cx="8" cy="8" r="3" stroke={`url(#${gradId})`} strokeWidth="1.5" />
+        <circle cx="11.6" cy="4.4" r="0.95" fill={`url(#${gradId})`} />
+      </svg>
+    );
+  if (name === "tiktok")
+    return (
+      <svg {...f}>
+        <path d={TT_NOTE} fill="#25F4EE" transform="translate(-0.9 -0.5)" />
+        <path d={TT_NOTE} fill="#FE2C55" transform="translate(0.9 0.5)" />
+        <path d={TT_NOTE} fill="currentColor" />
+      </svg>
+    );
+  if (name === "odoo")
+    return (
+      <svg {...f}>
+        {/* Odoo's brand purple, and its wordmark's twin `o`s — the part of that
+            wordmark that survives being shrunk to 15px. */}
+        <rect x="1" y="1" width="14" height="14" rx="3.4" fill="#714B67" />
+        <circle cx="5.7" cy="8.2" r="2.1" fill="none" stroke="#FFFFFF" strokeWidth="1.5" />
+        <circle cx="10.4" cy="8.2" r="2.1" fill="none" stroke="#FFFFFF" strokeWidth="1.5" />
+      </svg>
+    );
+  if (name === "google")
+    return (
+      <svg {...f} fill="none" strokeWidth="2.3">
+        {/* The four-arc G. Each arc is one brand colour, and the bar into the
+            centre is what makes it a G rather than a ring. */}
+        <path d="M4.46 4.46A5 5 0 0 1 11.54 4.46" stroke="#EA4335" strokeLinecap="round" />
+        <path d="M4.46 4.46A5 5 0 0 0 4.46 11.54" stroke="#FBBC05" strokeLinecap="round" />
+        <path d="M4.46 11.54A5 5 0 0 0 11.54 11.54" stroke="#34A853" strokeLinecap="round" />
+        <path d="M11.54 11.54A5 5 0 0 0 13 8" stroke="#4285F4" strokeLinecap="round" />
+        <path d="M13 8H8.4" stroke="#4285F4" />
+      </svg>
+    );
+  if (name === "gmail")
+    return (
+      <svg {...f} fill="none" stroke="#EA4335" strokeWidth="1.5" strokeLinejoin="round">
+        <rect x="1.6" y="3.6" width="12.8" height="9" rx="1.6" />
+        <path d="m2 4.4 6 4.6 6-4.6" />
+      </svg>
+    );
+  if (name === "stripe")
+    return (
+      <svg {...f}>
+        <rect x="1" y="1" width="14" height="14" rx="3.4" fill="#635BFF" />
+        <path
+          d="M10.5 5.6a2.3 2.3 0 0 0-3.6 1.2c0 2.1 4.1 1.5 4.1 3.5a2.4 2.4 0 0 1-3.7 1.3"
+          fill="none" stroke="#FFFFFF" strokeWidth="1.5" strokeLinecap="round"
+        />
+      </svg>
+    );
+  if (name === "shopify")
+    return (
+      <svg {...f}>
+        {/* The bag, in Shopify's two greens: the darker one is the handle, which
+            is the part that reads as a bag rather than as a box. */}
+        <path d="M3.5 5.2h9l-.75 8.4a.9.9 0 0 1-.9.8H5.15a.9.9 0 0 1-.9-.8z" fill="#95BF47" />
+        <path
+          d="M6.1 6.4V4.5a1.9 1.9 0 0 1 3.8 0v1.9"
+          fill="none" stroke="#5E8E3E" strokeWidth="1.4" strokeLinecap="round"
+        />
+      </svg>
+    );
+  /*
+    ⚠ THE LAST TWO ARE OURS, NOT BRANDS — `currentColor`, house stroke weight,
+    so they sit in the chip family beside the coloured logos rather than
+    pretending to be a company. Keeping them here is what lets every caller ask
+    one question instead of two.
+  */
+  if (name === "webhooks")
+    return (
+      <svg {...f} fill="none" stroke="currentColor" strokeWidth="1.4"
+        strokeLinecap="round" strokeLinejoin="round">
+        <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 === "scraper")
+    return (
+      <svg {...f} fill="none" stroke="currentColor" strokeWidth="1.4"
+        strokeLinecap="round" strokeLinejoin="round">
+        {/* A magnifier over a grid of rows: it reads a catalogue of profiles and
+            makes records out of what matches — which is what the bucket does,
+            and it is deliberately NOT either platform's mark, because the whole
+            point of R3 is that the bucket is neither one of them. */}
+        <path d="M2.6 3.4h10.8M2.6 6.2h5.2M2.6 9h3.4" />
+        <circle cx="10.4" cy="10.2" r="3" />
+        <path d="m12.6 12.4 1.6 1.6" />
+      </svg>
+    );
+  return null;
+}
+
+/**
+ * Does this kind wear a LOGO rather than a house glyph?
+ *
+ * ⛔ IT EXISTS BECAUSE THE TILE HAS TO CHANGE TOO, and forgetting that would have shipped the
+ * defect quietly: `.autox-card-mark` paints a blue tint and sets `color: var(--lp-blue-deep)`,
+ * so TikTok's note — which is `currentColor` by design, so it survives dark mode — would have
+ * rendered BLUE, and Instagram's gradient would have sat on a coloured chip. The caller adds
+ * `is-brand`, which neutralises both. One predicate, so the mark and its tile cannot disagree
+ * about whether a row is branded.
+ */
+export function hasBrandKind(kind: string): boolean {
+  return Boolean(BRAND_OF_KIND[kind]);
+}
+
+/** The connector-key twin of `hasBrandKind`, for the directory's tiles. */
+export function hasBrandConnector(key: string): boolean {
+  return Boolean(BRAND_OF_CONNECTOR[key]);
+}
+
+/** The mark for a trigger or action KIND, or null when it is not a branded one. */
+export function brandForKind(kind: string, size = 15): ReactElement | null {
+  const name = BRAND_OF_KIND[kind];
+  return name ? <BrandMark name={name} size={size} /> : null;
+}
+
+/** The mark for a connector/provider KEY, or null when we have no logo for it. */
+export function brandForConnector(key: string, size = 15): ReactElement | null {
+  const name = BRAND_OF_CONNECTOR[key];
+  return name ? <BrandMark name={name} size={size} /> : null;
+}

web/src/customer-grid/CustomerGrid.tsx

@@ -25,6 +25,14 @@ import "@glideapps/glide-data-grid/dist/index.css";
 
 import { useCustomerData } from "./useCustomerData";
 import type { SurfaceScope } from "./apiBridge";
+// ⭐ WAVE 30 · W30-T42 (contract C2) — the WINDOWED grid's arithmetic, pure and node-run in
+// `verify_grid_ux.py`, because every one of these decisions is taken inside a callback where
+// only its own source text could otherwise be checked.
+import { WINDOW_ROWS } from "./apiBridge";
+import {
+  EMPTY_WINDOW_PREDICATE, limitSummary, nextWindowOffset, windowedCapabilityNote,
+  windowedFoldNote, windowPredicateKey,
+} from "./counts";
 import { defaultViewConfig, useGridColumns } from "./useGridColumns";
 import { activeMeasureRuleIds, pendingMeasures, runPipeline, sliceForDisplay,
   unresolvedConditions, useVisibleRows } from "./useVisibleRows";
@@ -666,6 +674,7 @@ function CustomerGrid({
     overlayEdits,
     setOverlayEdits,
     patchOverlay,
+    requestWindow,
   } = useCustomerData(scope, {
     bindSurface: !embedded,
     includeWorkspace: !embedded,
@@ -1402,6 +1411,77 @@ function CustomerGrid({
   const displaySpec = cleanDisplay(config.display);
   const displayMode: DisplayMode = serverWindowed ? "grid" : displaySpec?.mode ?? "grid";
 
+  // ═══════════════════════════════════════════════════════════════════════════════════════
+  // ⭐⭐ WAVE 30 · W30-T42 (contract C2) — PAGING A READ-THROUGH GRID.
+  // ═══════════════════════════════════════════════════════════════════════════════════════
+  //
+  // The client engine is already refused in this mode (`useVisibleRows` passes rows straight
+  // through), which is C2's "F may render no client-side predicate over a windowed grid". That
+  // clause on its own would leave a filter chip INERT: the user narrows 32,826 orders, nothing
+  // filters, and the count keeps reading 32,826 — honest about the scope and silent about the
+  // question. So the predicate has to reach the evaluator that CAN answer it, which is SQL.
+  //
+  // ⛔ THE SAVED VIEW'S OWN OBJECTS GO ON THE WIRE, UNTRANSLATED (see `windowRowsPath`).
+  const windowPredicate = useMemo(
+    () => windowPredicateKey(config.filters, config.filterConj, config.sorts, search),
+    [config.filters, config.filterConj, config.sorts, search]
+  );
+  const windowRequest = useCallback(
+    (offset: number) => ({
+      offset,
+      limit: WINDOW_ROWS,
+      filters: config.filters,
+      filterConj: config.filterConj,
+      sorts: config.sorts,
+      search,
+    }),
+    [config.filters, config.filterConj, config.sorts, search]
+  );
+  const sentPredicate = useRef<string | null>(null);
+  useEffect(() => {
+    if (!serverWindowed) {
+      sentPredicate.current = null;
+      return;
+    }
+    if (sentPredicate.current === windowPredicate) return;
+    // ⚠ THE FIRST WINDOW WENT OUT WITH NO QUERY ARGS AT ALL — `config` is this component's own
+    // state, seeded from a workspace call that had not landed when the rows request left. So a
+    // view carrying no filter, no sort and no search has ALREADY been answered, and firing here
+    // would spend a round trip to receive the bytes on screen. Any other predicate is a real
+    // question and goes out. One function owns both the key and the empty case, so "no
+    // predicate" cannot be spelled two ways.
+    if (sentPredicate.current === null && windowPredicate === EMPTY_WINDOW_PREDICATE) {
+      sentPredicate.current = windowPredicate;
+      return;
+    }
+    sentPredicate.current = windowPredicate;
+    requestWindow(windowRequest(0));
+  }, [serverWindowed, windowPredicate, windowRequest, requestWindow]);
+
+  /**
+   * The scroll → next window. glide reports the visible RECTANGLE; `nextWindowOffset` decides.
+   *
+   * ⚠ `counts.shown` IS THE LOADED COUNT, not `rawRows.length`. They are the same number today
+   * and would stop being one the moment anything layers a row in that the server did not send
+   * (`pendingRows` does exactly that on editable tables) — and the offset this produces is a
+   * promise to the server about where our contiguous run ends. It has to come from the merge
+   * that built the run.
+   */
+  const onVisibleRegionChanged = useCallback(
+    (range: Rectangle) => {
+      if (!serverWindowed) return;
+      const offset = nextWindowOffset({
+        lastVisibleRow: range.y + range.height,
+        loaded: payload?.counts?.shown ?? 0,
+        matched: payload?.counts?.matched ?? 0,
+        limit: WINDOW_ROWS,
+      });
+      if (offset !== null) requestWindow(windowRequest(offset));
+    },
+    [serverWindowed, payload?.counts?.shown, payload?.counts?.matched, requestWindow,
+     windowRequest]
+  );
+
   // CG-8 — measure conditions, answered by the host as `{ruleId: pid[]}`. Converted to Sets
   // once here rather than per row: the pipeline runs this over every row of the book.
   //
@@ -1576,7 +1656,20 @@ function CustomerGrid({
   // pidToIndex is rebuilt over the slice because every index consumer (selection, detail
   // navigation, hover) is positional against what is actually on screen.
   const [displayCap, setDisplayCap] = useState(DISPLAY_PAGE);
-  const capped = visibleRows.length > displayCap;
+  /**
+   * ⛔ W30-T42 — NO CLIENT CAP ON A WINDOWED TABLE, AND THE TWO CAPS WOULD HAVE FOUGHT.
+   *
+   * The display cap exists because the whole-book path holds every row and glide should not be
+   * asked to lay out 33,000 of them at once. In `server-windowed` mode the WINDOW is already
+   * that bound — one page of `WINDOW_ROWS` — so a second cap on top would stop the grid 50 rows
+   * in, under a "Showing first 50 of 200" bar, while the toolbar says "showing 200 of 32,826".
+   * Two truncation stories about one table, neither of them wrong, together a lie.
+   *
+   * ⛔ AND IT WOULD HAVE BROKEN THE PAGING OUTRIGHT: the scroll decision reads how far down the
+   * LOADED rows the viewport reaches, and a capped grid can never scroll past the cap, so the
+   * end of the window would be unreachable and the next window never requested.
+   */
+  const capped = !serverWindowed && visibleRows.length > displayCap;
   /**
    * ⭐⭐ WAVE-29 T33 (owner item 17) — THE TOTALS ROW, and the cap fix it forced.
    *
@@ -1598,10 +1691,57 @@ function CustomerGrid({
     ),
     [visibleRows, fields]
   );
+  /**
+   * ⭐⭐ WAVE 30 · W30-T42 (contract C2 / the ticket's own named trap) — THE TOTALS ROW OVER A
+   * WINDOW IS DISCLOSED, NOT DELETED.
+   *
+   * ⛔ THE TRAP. `totalsAggs` folds `visibleRows`, which in `server-windowed` mode is exactly the
+   * rows this browser has loaded. Painted in the table's footer with no denominator, "the sum of
+   * whatever happens to be in memory" wears the sum of 32,826 orders — a fabricated aggregate,
+   * the thing [[no-unverifiable-aggregates]] exists to forbid. Grouping is refused in this mode
+   * for the same reason (a group header over a window subtotals the PAGE while claiming to
+   * describe the group), and that refusal stays: a group is a claim about a SET, and the client
+   * cannot see the set.
+   *
+   * ⛔ BUT ABSENT IS NOT ONE OF THE TWO HONEST STATES. T42's done-when offers exactly two —
+   * "reads from the server" or "says plainly that it covers the loaded window" — and the wire
+   * carries no aggregates (`rows/total/totalUnfiltered/offset/limit/limits`), so the second one
+   * is the one available. The fold is CORRECT for a question nobody asked; naming the question
+   * is what makes it honest, and the loaded rows are on screen and scrollable, so the number
+   * still drills to rows. The disclosure is `windowedFoldNote`, and it is bound to `showTotals`
+   * by ONE memo below rather than by two conditions that could drift apart — a totals row over a
+   * window with its sentence missing is the whole defect back again.
+   */
   const showTotals = useMemo(
     () => !config.groupBy && Object.keys(totalsAggs).length > 0,
     [config.groupBy, totalsAggs]
   );
+  /** The denominator sentence — non-null EXACTLY when a totals row is painted over a window that
+   *  does not hold the whole matched set. Null on a whole-book table (the total is total) and on
+   *  a window that happens to hold everything (`windowedFoldNote` refuses to invent a
+   *  truncation that is not there). */
+  const foldNote = useMemo(
+    () =>
+      serverWindowed && showTotals
+        ? windowedFoldNote(payload?.counts?.shown ?? 0, payload?.counts?.matched ?? 0)
+        : null,
+    [serverWindowed, showTotals, payload?.counts?.shown, payload?.counts?.matched]
+  );
+  /** R6's SECOND SENTENCE, on the client side of the wire: the limits D's route DECLARED on this
+   *  response. Received and painted nothing = the limit is silent again, one layer further out. */
+  const limitNote = useMemo(() => limitSummary(payload?.limits), [payload?.limits]);
+  /**
+   * ⛔ AND THE LIMIT NOBODY DECLARED, WHICH IS THE ONE A PERSON ACTUALLY NOTICES. Nine controls
+   * this component gates on `serverWindowed` vanish the moment a grid becomes a window — export,
+   * cohorts, folders, grouping, the four alternative views, select-from-file, alert badges — all
+   * of which were working on this grid the day before, because the whole table used to be in the
+   * browser. Every refusal is right on its own; a screen where eight buttons quietly disappear
+   * is not. See `windowedCapabilityNote` for the list and why it is not a guess.
+   */
+  const capabilityNote = useMemo(
+    () => (serverWindowed ? windowedCapabilityNote(payload?.counts?.matched ?? 0) : null),
+    [serverWindowed, payload?.counts?.matched]
+  );
   const displayRows = useMemo(() => {
     const shown = capped ? sliceForDisplay(visibleRows, displayCap) : visibleRows;
     // ⚠ APPENDED AFTER THE SLICE, so the cap can never eat the totals row itself — and it is the
@@ -5236,6 +5376,17 @@ function CustomerGrid({
               // pixel of the marker column; it only makes its width a number we own.
               // ═══ end W18-B VOID ═══
               rowMarkerWidth={rowMarkerPx(displayRows.length)}
+              /**
+               * ⭐⭐ W30-T42 (contract C2) — THE SCROLL THAT ASKS FOR THE NEXT WINDOW.
+               *
+               * ⚠ The W18-B VOID note above says there is deliberately no such handler "anywhere
+               * near it", and that stays true of the void, which is arithmetic over the box and
+               * must not become scroll-tracking. This one is a different subject: how far down
+               * the LOADED rows the viewport has reached, which is the only question a windowed
+               * grid can answer paging with. It is a no-op on every whole-book table (the
+               * callback returns on `!serverWindowed` before reading anything).
+               */
+              onVisibleRegionChanged={onVisibleRegionChanged}
               gridSelection={gridSelection}
               onGridSelectionChange={onGridSelectionChange}
               getRowThemeOverride={getRowThemeOverride}
@@ -5769,6 +5920,26 @@ function CustomerGrid({
             count above still states the full matched count; this bar says what is painted.
             Grid + list only: calendar/kanban project the FULL set with their own stated
             bounds (a month, a stack's Show-all). */}
+        {/* ⭐ W30-T42 — the WINDOWED grid's honest footnotes, in the strip that already exists
+            for exactly this job. Reuses `.cg-more` / `.cg-more-note` rather than adding a
+            class: `index.css` is another lane's fence this wave, and this needs no new pixel.
+            `foldNote` is null unless a totals row is folded over a partial window; `limitNote`
+            is null unless the SERVER declared a limit on this response (R6's second sentence —
+            short on screen, the full cause and recommendation one hover away, the same
+            short-form/`title` split `countLabelCompact` uses for the same strip). */}
+        {!capped && (foldNote || limitNote || capabilityNote) && (
+          <div className="cg-more">
+            {foldNote && <span className="cg-more-note">{foldNote}</span>}
+            {limitNote && (
+              <span className="cg-more-note" title={limitNote.full}>{limitNote.short}</span>
+            )}
+            {capabilityNote && (
+              <span className="cg-more-note" title={capabilityNote.full}>
+                {capabilityNote.short}
+              </span>
+            )}
+          </div>
+        )}
         {capped && (displayMode === "grid" || displayMode === "list") && (
           <div className="cg-more">
             <span className="cg-more-note">

web/src/customer-grid/ImportDialog.tsx

@@ -92,11 +92,11 @@ export default function ImportDialog({
         body: form,
       });
       const body = (await res.json().catch(() => null)) as
-        | (Parsed & { detail?: { error?: { message?: string } } })
+        | (Parsed & { error?: { message?: string } })
         | null;
       if (!res.ok || !body) {
         setError(
-          body?.detail?.error?.message ??
+          body?.error?.message ??
             `That file could not be read (the server answered ${res.status}).`
         );
         return;
@@ -145,11 +145,11 @@ export default function ImportDialog({
         }
       );
       const body = (await res.json().catch(() => null)) as
-        | { imported?: number; detail?: { error?: { message?: string } } }
+        | { imported?: number; error?: { message?: string } }
         | null;
       if (!res.ok) {
         // The server's sentence beats anything invented here: it names the column, or the cap.
-        setError(body?.detail?.error?.message ?? `The server answered ${res.status}.`);
+        setError(body?.error?.message ?? `The server answered ${res.status}.`);
         return;
       }
       onImported(body?.imported ?? plan.rows.length);

web/src/customer-grid/counts.ts

@@ -9,7 +9,7 @@
 // asserted by aios-web/verify_filter_engine.py alongside the filter engine.
 // ---------------------------------------------------------------------------
 
-import type { ScopeCounts } from "./types";
+import type { FilterNode, GridLimit, ScopeCounts, SortSpec } from "./types";
 
 /**
  * A whole-book table holds every row, so its own count IS the truth.
@@ -89,3 +89,195 @@ export function countLabelCompact(recordCount: number, scope?: ScopeCounts): str
   }
   return `showing ${n(scope.shown)} of ${n(scope.matched)}`;
 }
+
+// ═══════════════════════════════════════════════════════════════════════════════════════════
+// ⭐⭐ WAVE 30 · W30-T42 (contract C2) — THE THREE DECISIONS A WINDOWED GRID MAKES,
+//     EXTRACTED AS PURE FUNCTIONS SO THEY CAN BE RUN RATHER THAN GREPPED.
+// ═══════════════════════════════════════════════════════════════════════════════════════════
+//
+// Everything below is decided per scroll, per keystroke and per filter chip inside
+// `CustomerGrid`, i.e. at CLICK TIME — the one place this lane has repeatedly found defects a
+// source scan cannot see (W30-T40's fields panel built its body through a render prop; the
+// crash was only reachable by opening the panel). A decision that lives in a callback can only
+// be asserted by its own text; a decision that lives in an exported function can be FED the
+// numbers and checked against its answer. So the callbacks up there hold wiring, and the
+// arithmetic lives here, where `gridUx.test.ts` runs it under node.
+
+/** The page size one window request asks for. See `apiBridge.WINDOW_ROWS` — this module holds
+ *  no network knowledge, so the caller passes it in. */
+export interface WindowScroll {
+  /**
+   * How far down the loaded rows the viewport reaches — the EXCLUSIVE end of glide's visible
+   * rectangle (`range.y + range.height`), i.e. the first row index below the fold. Named for
+   * what the caller passes rather than for a row it points at: it is one PAST the last visible
+   * row, and a doc that called it "the last row" would be off by one in a reader's head.
+   */
+  lastVisibleRow: number;
+  /** how many rows this browser holds right now (`ScopeCounts.shown`) */
+  loaded: number;
+  /** rows matching the predicate across the WHOLE scope (`ScopeCounts.matched`) */
+  matched: number;
+  /** the page size the next request would ask for */
+  limit: number;
+  /** how many rows from the end to start fetching. Default 25. */
+  lead?: number;
+}
+
+const DEFAULT_LEAD = 25;
+
+/**
+ * "Should I fetch another window, and from which offset?" — `null` means no.
+ *
+ * ⛔ THE OFFSET IS THE LOADED COUNT, AND THAT IS THE WHOLE CONTRACT WITH THE SERVER. Windows
+ * are contiguous from 0 under a TOTAL order (`compile_order_by` appends the id as a tiebreak
+ * precisely so `LIMIT/OFFSET` cannot return one row on two pages), so "how many rows do I
+ * hold" and "where does the next page start" are the same number. Deriving it from a page
+ * counter instead would drift the moment one response comes back short.
+ *
+ * ⛔ AND IT REFUSES ON `matched <= loaded`. When the whole match set is already here there is
+ * nothing to page, and asking anyway would spend a request per scroll event forever against a
+ * server that answers with an empty window — a poll wearing an infinite scroll.
+ *
+ * ⚠ `loaded < 1` also refuses: the FIRST window belongs to the load effect, not to a scroll.
+ * A scroll event that fires before any payload has landed must not race it.
+ */
+export function nextWindowOffset(s: WindowScroll): number | null {
+  const { lastVisibleRow, loaded, matched, limit } = s;
+  if (!Number.isFinite(limit) || limit < 1) return null;
+  if (!Number.isFinite(loaded) || loaded < 1) return null;
+  if (!Number.isFinite(matched) || matched <= loaded) return null;
+  const wanted = Number.isFinite(s.lead as number) ? (s.lead as number) : DEFAULT_LEAD;
+  const lead = Math.max(1, Math.min(wanted, limit));
+  if (!Number.isFinite(lastVisibleRow) || lastVisibleRow < loaded - lead) return null;
+  return loaded;
+}
+
+/**
+ * The sentence under a totals row that was folded over a WINDOW — `null` when there is
+ * nothing to disclose.
+ *
+ * ⛔ THE TICKET'S OWN TRAP, AND WHY THIS IS A DISCLOSURE RATHER THAN A DELETION. `totalsAggs`
+ * folds `visibleRows`, which in `server-windowed` mode is exactly the rows this browser has
+ * loaded. The number is therefore CORRECT for a question nobody asked ("the sum of the first
+ * 200 orders") and wrong for the one the position implies ("the sum of 32,826 orders"). This
+ * repo's law is that every number drills to rows ([[no-unverifiable-aggregates]]) — and the
+ * loaded rows ARE rows, on screen, scrollable. So the honest fix is to name the denominator,
+ * not to hide the fold: W30-T42's done-when offers exactly two acceptable states, "reads from
+ * the server" or "says plainly that it covers the loaded window", and absent is neither.
+ *
+ * ⚠ `null` WHEN `loaded >= matched`, and that is not an optimisation. There the loaded rows
+ * ARE every matching row, so the totals row is a true total and a caveat under it would invent
+ * a truncation that is not there — the same mistake `countLabel` avoids one function up.
+ */
+export function windowedFoldNote(loaded: number, matched: number): string | null {
+  if (!Number.isFinite(loaded) || !Number.isFinite(matched)) return null;
+  if (loaded >= matched) return null;
+  const n = (v: number) => Math.max(0, Math.floor(v)).toLocaleString();
+  return `Column totals cover the ${n(loaded)} rows loaded so far, of ${n(matched)} matching.`;
+}
+
+/**
+ * The footer's report of the limits the SERVER declared — `{short, full}` or `null`.
+ *
+ * ⛔ R6's SECOND SENTENCE, ON THE CLIENT SIDE OF THE WIRE, AND IT IS THE HALF THAT GETS
+ * DROPPED. D's route already refuses to truncate silently: it names every limit that binds a
+ * response with its cause and its recommendation. A client that receives that array and paints
+ * nothing has re-created the exact violation the ruling forbids — the limit is now silent
+ * again, one layer further out, with a green gate on both sides of the wire.
+ *
+ * ⚠ SHORT ON SCREEN, FULL IN THE `title`. The causes are whole sentences (they have to be —
+ * "a number condition is evaluated in SQL at whole-unit precision…" is not compressible into a
+ * chip) and the strip they land in is 30px tall. `countLabelCompact` already established this
+ * pattern for the same strip and the same reason: the honest short form on screen, the complete
+ * statement one hover away. Nothing is dropped; the long half moves.
+ */
+export function limitSummary(
+  limits: GridLimit[] | undefined
+): { short: string; full: string } | null {
+  const binding = (limits ?? []).filter(
+    (l) => l && typeof l.subject === "string" && (l.effect ?? "none") !== "none"
+  );
+  if (binding.length === 0) return null;
+  const subjects = binding.map((l) => l.subject).join(", ");
+  const full = binding
+    .map((l) => `${l.subject}: ${l.cause ?? ""}${l.recommendation ? ` — ${l.recommendation}` : ""}`)
+    .join("\n\n");
+  return { short: `Limits apply to ${subjects}`, full };
+}
+
+/**
+ * ⭐⭐ WAVE 30 · W30-T42 / R6's SECOND SENTENCE — WHAT A WINDOWED GRID CANNOT DO, SAID OUT LOUD.
+ *
+ * ⛔ THE THING THIS EXISTS TO PREVENT, AND IT IS A CLIFF NOBODY HAD WRITTEN DOWN. Turning
+ * `counts.windowed` on for the orders grid does not only change how rows arrive — nine controls
+ * `CustomerGrid` already gates on `serverWindowed` DISAPPEAR the same instant, every one of them
+ * with no explanation on screen. They were all working on that grid the day before, because the
+ * whole table was in the browser. Each refusal is individually correct — a cohort built from the
+ * 200 rows that happen to be in memory is a wrong cohort, an export of one page is a wrong
+ * export, a group header over a window subtotals the PAGE while claiming to describe the group —
+ * and a person who just watched eight buttons vanish is owed the reason.
+ *
+ * That is R6's second sentence exactly: *"if there is lag or it can't be done, you need to
+ * explicitly tell me why and recommend a fix."* A limit that cannot be removed must be REPORTED
+ * with its cause and a recommendation, never silently enforced. Silently enforcing this one would
+ * have been the violation, not the limit.
+ *
+ * ⚠ THE LIST IS THE CODE'S, NOT A GUESS: every entry below is a control `CustomerGrid.tsx` turns
+ * off on `serverWindowed`, and `verify_grid_ux.py` counts the gates so an item cannot be added
+ * there without a line here.
+ */
+export const WINDOWED_TOOLS_OFF = [
+  "grouping and its subtotals",
+  "the kanban, calendar, list, map and catalog views",
+  "export",
+  "add to cohort, and remove from cohort",
+  "add to folder",
+  "select from file",
+  "view alert badges",
+];
+
+export function windowedCapabilityNote(matched: number): { short: string; full: string } {
+  const n = Math.max(0, Math.floor(Number.isFinite(matched) ? matched : 0)).toLocaleString();
+  return {
+    short: "Some tools are off on this grid",
+    full:
+      `This database is read one page at a time out of ${n} records, so the tools that need `
+      + `every matching row in the browser are off here: ${WINDOWED_TOOLS_OFF.join(", ")}. `
+      + `Filtering, searching and sorting are NOT affected — they run on the server across all `
+      + `${n}. Restoring the rest needs the server to do those folds: an export, a cohort `
+      + `membership and a group summary computed over the whole match set rather than over the `
+      + `page in memory.`,
+  };
+}
+
+/**
+ * The predicate this browser has asked the SERVER to evaluate, as one comparable string.
+ *
+ * ⛔ WHY A KEY AND NOT A DEEP COMPARE AT THE CALL SITE. In `server-windowed` mode every
+ * predicate change is a REQUEST, so the effect that fires it must be able to say "this is the
+ * same question I already asked" — and `config.filters` is a fresh array on every render of a
+ * component that re-renders on hover. Keyed on the VALUE, the effect fires once per real
+ * change; keyed on identity it would fire per repaint, which is a paid round trip per mouse
+ * move on a 963,783-row grid.
+ *
+ * ⚠ ONE PLACE BUILDS BOTH THE KEY AND THE EMPTINESS TEST (`EMPTY_WINDOW_PREDICATE` below is
+ * this function's own answer for a blank view). Two spellings of "no predicate" is how the
+ * first window gets re-requested on every mount for nothing.
+ */
+export function windowPredicateKey(
+  filters: FilterNode[] | undefined,
+  filterConj: string | undefined,
+  sorts: SortSpec | undefined,
+  search: string | undefined
+): string {
+  return JSON.stringify([
+    filters ?? [],
+    filterConj === "or" ? "or" : "and",
+    sorts ?? [],
+    (search ?? "").trim(),
+  ]);
+}
+
+/** What `windowPredicateKey` answers for a view with no filter, no sort and no search — i.e.
+ *  exactly the question the FIRST window (offset 0, no query args) already answered. */
+export const EMPTY_WINDOW_PREDICATE = windowPredicateKey([], "and", [], "");

web/src/customer-grid/icons.tsx

@@ -27,10 +27,29 @@ import {
   TYPE_SHAPES,
 } from "./iconShapes";
 
-function Shapes({ shapes }: { shapes: IconShape[] }) {
+/**
+ * ⭐ WAVE 30 item 2 (R5) — `shapes` IS OPTIONAL, and the `?? []` is the whole point.
+ *
+ * Every caller reaches this through a TOTAL `Record<K, IconShape[]>`, so TypeScript promises the
+ * lookup always hits. That promise is only as good as the key: `type` arrives over the WIRE, and
+ * a field whose type is not in the union — a kind added server-side, a stored definition from
+ * before a rename — makes `TYPE_SHAPES[type]` `undefined` at runtime with tsc none the wiser.
+ * `undefined.map` is a TypeError, and until this wave a TypeError anywhere unmounted the entire
+ * React tree: a blank white page, which is exactly what a user calls "it crashes".
+ *
+ * ⚠ RANKED SECOND AND SHIPPED ANYWAY (R5). Every field in `odoo_relational.order_fields` carries
+ * a type present in `TYPE_SHAPES`, and the server's `UT_FIELD_TYPES` filters unknown types off
+ * the wire — so this is LATENT, not the proven cause of owner item 2. The reporter was a user and
+ * cannot be re-interviewed, so both candidate causes are fixed rather than one guessed at.
+ *
+ * An absent lookup now paints NO GLYPH, which is the honest degradation: the row still renders,
+ * still carries its label, and the missing mark says "this type has no icon" rather than taking
+ * the product down to say it.
+ */
+function Shapes({ shapes }: { shapes?: IconShape[] }) {
   return (
     <>
-      {shapes.map((s, i) =>
+      {(shapes ?? []).map((s, i) =>
         s.fill ? (
           <path key={i} d={s.d} fill="currentColor" />
         ) : (
@@ -120,7 +139,10 @@ export function ToneModeIcon({
       viewBox="0 0 16 16"
       aria-hidden
     >
-      {MODE_SHAPES[mode].map((s, i) =>
+      {/* R5: `?? []` for the same reason as `Shapes` — `mode` is a STORED display mode off
+          the wire, so a view saved under a kind this build no longer knows makes the lookup
+          undefined and `.map` a TypeError. */}
+      {(MODE_SHAPES[mode] ?? []).map((s, i) =>
         s.fill ? (
           <path key={i} d={s.d} fill={paint.stroke} />
         ) : (
@@ -165,7 +187,8 @@ export function ChartKindIcon({
       viewBox="0 0 16 16"
       aria-hidden
     >
-      {CHART_KIND_SHAPES[kind].map((s, i) => (
+      {/* R5: same guard, same reason — `kind` comes from a saved chart definition. */}
+      {(CHART_KIND_SHAPES[kind] ?? []).map((s, i) => (
         <path
           key={i}
           d={s.d}
@@ -469,7 +492,8 @@ export function FolderMark({
       viewBox="0 0 16 16"
       aria-hidden
     >
-      {FOLDER_SHAPE_PATHS[shape].map((s, i) => (
+      {/* R5: same guard — a folder's shape is stored in nav prefs. */}
+      {(FOLDER_SHAPE_PATHS[shape] ?? []).map((s, i) => (
         <path
           key={i}
           d={s.d}

web/src/customer-grid/types.ts

@@ -1283,6 +1283,29 @@ export function isPresetField(field: Field): boolean {
   return (field.source === "odoo" && !field.custom) || isMachineOwned(field);
 }
 
+/**
+ * ⭐ WAVE 30 item 2 (R5) — THE ONE PLACE A FIELD'S NAME IS RESOLVED, and why it is a function.
+ *
+ * `Field.label` is declared `string` and arrives over the WIRE, where nothing enforces that. The
+ * fields panel did `f.label.toLowerCase()` unguarded, so a single label-less definition made a
+ * TypeError the moment a search query was typed — and before this wave a TypeError anywhere
+ * unmounted the whole React tree, which is the blank page a user calls "it crashes".
+ *
+ * ⚠ IT LIVES HERE, BESIDE THE OTHER FIELD PREDICATES, RATHER THAN INSIDE THE PANEL, for two
+ * reasons that are worth keeping. A panel-local helper is invisible to every other surface that
+ * will make the same read; and a panel-local helper cannot be RUN under this repo's node harness,
+ * so the search path — the one that only fires once somebody types — would have had no test at all.
+ *
+ * ⚠ FALLS BACK TO THE KEY, never to "". A column with no label is still findable and still
+ * nameable by the thing it actually is; an empty string would produce a row a user can see, cannot
+ * search for, and cannot name in a report.
+ */
+export function fieldLabel(field: Field): string {
+  return typeof field.label === "string" && field.label
+    ? field.label
+    : String(field.key ?? "");
+}
+
 /**
  * ⭐ 2026-08-06, owner item 4 — **the cells a person must not type into.**
  *
@@ -3268,6 +3291,25 @@ export interface ScopeCounts {
   windowed: boolean;
 }
 
+/**
+ * ⭐ WAVE 30 (contract C2 / R6's SECOND SENTENCE) — one limit the server could not remove.
+ *
+ * Authored by `routes_odoo_tables.odoo_table_rows`, which refuses to truncate silently: a
+ * predicate it cannot push down, a window it had to clamp, a page deep enough to be slow, each
+ * arrives named, with the cause and the recommendation the owner's ruling demands. The client's
+ * only job is to not swallow it — see `counts.limitSummary`.
+ *
+ * ⚠ `effect: "none"` is a limit that did NOT bind this response; `"truncated"` is never emitted
+ * by design (the route raises instead), and the value exists so that a future change cannot
+ * start trimming without saying so.
+ */
+export interface GridLimit {
+  subject: string;
+  cause: string;
+  recommendation: string;
+  effect?: string;
+}
+
 export interface CustomersPayload {
   fields: Field[];
   rows: Row[];
@@ -3276,6 +3318,8 @@ export interface CustomersPayload {
   workspace?: GridWorkspace;
   /** Present only for server-windowed tables. See ScopeCounts. */
   counts?: ScopeCounts;
+  /** C2 — limits the SERVER declared on this response. Empty/absent = nothing binds. */
+  limits?: GridLimit[];
   /** Assignable people for `user` fields — supplied by the host from the tenant's real user
    *  list, never invented client-side, so an assignee is always someone who can log in. */
   userOptions?: string[];

web/src/customer-grid/useCustomerData.ts

@@ -28,12 +28,18 @@ import { topicForScope } from "./types";
 import type { CustomersPayload, Field, GridWorkspace, Row } from "./types";
 import {
   clearTopicRowsCache,
+  dropTableRowsCache,
+  fetchTableWindow,
   fetchTopicRows,
   fetchWorkspace,
+  mergeWindow,
   patchTopicRow,
+  readThroughTables,
   setSurfaceScope,
   subscribeChanges,
+  WINDOW_ROWS,
 } from "./apiBridge";
+import type { RowWindowRequest } from "./apiBridge";
 import { DERIVED_CELLS_EVENT, ROWS_STALE_EVENT, WORKSPACE_STALE_EVENT } from "../apiContract";
 import { planChangeReaction, rowsRefetchDelay } from "./liveWorkspace";
 import { signal } from "../apiContract";
@@ -165,6 +171,14 @@ export interface CustomerData {
   setOverlayEdits: Dispatch<SetStateAction<OverlayEdits>>;
   /** Optimistic write + PATCH /api/customers/{pid}; rolls back on failure. */
   patchOverlay: (pid: number, updates: Partial<Row>) => void;
+  /**
+   * ⭐ WAVE 30 · W30-T42 (contract C2) — ASK THE SERVER FOR A WINDOW OF A READ-THROUGH GRID.
+   *
+   * `offset: 0` replaces (a new predicate); `offset > 0` appends (a scroll). A no-op on a
+   * whole-book table, so the caller never has to ask which mode it is in twice — `serverWindowed`
+   * already answers that from `payload.counts`, and a second test here could disagree with it.
+   */
+  requestWindow: (req: RowWindowRequest) => void;
 }
 
 interface CustomerDataOptions {
@@ -210,6 +224,26 @@ export function useCustomerData(
   // something OUTSIDE the grid's own write path changed rows (shell Add-record, an automation
   // run). Senders clear the rows cache first, so the refetch cannot be served from the memo.
   const [rowsBump, setRowsBump] = useState(0);
+  /**
+   * ⭐ WAVE 30 · W30-T42 (contract C2) — the three refs a WINDOWED grid needs, and why each one
+   * is a ref rather than state: none of them may re-render the grid on its own.
+   *
+   *  `readThroughRef`   does THIS table read through the mirror? Answered once per open from
+   *                     `odoo-tables/status`, never from a key list here. Reset to false the
+   *                     moment the scope changes, so a switch cannot carry the previous table's
+   *                     answer into the new table's first scroll.
+   *  `windowSeq`        ONE ordering token shared by the load effect and `requestWindow`. Two
+   *                     paths can `setData` for the same surface (a rowsBump re-load while a
+   *                     scroll is in flight); the newest request wins and every older response
+   *                     is dropped rather than merged, because a merge of two orders is rows in
+   *                     the wrong places with nothing erroring.
+   *  `inflightOffset`   glide fires `onVisibleRegionChanged` on EVERY frame of a drag. Without
+   *                     this the same page is requested dozens of times before the first answer
+   *                     lands — a paid round trip per animation frame.
+   */
+  const readThroughRef = useRef(false);
+  const windowSeq = useRef(0);
+  const inflightOffset = useRef<number | null>(null);
   /** Item 3 (3c) — the LAST scope whose first paint has already been attempted. See the
    *  `firstPaint` note in the load effect: this is what keeps a workspace failure loud on
    *  arrival and silent on every refetch afterwards. */
@@ -252,6 +286,12 @@ export function useCustomerData(
       // bump without this is served the copy that predates the change we just detected — a
       // refetch that costs a request, succeeds, and shows the user nothing.
       clearTopicRowsCache(topic.rowsPath);
+      // ⚠ AND THE WINDOWED FAMILY, which `topic.rowsPath` cannot name: a read-through grid is
+      // served from `odoo-tables/<key>/rows?…` under one key per offset × predicate. Without
+      // this the poller notices a change, re-runs the load effect, and the load effect is
+      // served the pre-change window straight out of the memo — a refetch that costs a request,
+      // succeeds, and shows the user nothing (the exact defect the line above exists to fix).
+      dropTableRowsCache(scope);
       lastRowsRead = Date.now();
       setRowsBump((b) => b + 1);
     };
@@ -346,17 +386,48 @@ export function useCustomerData(
     const firstPaint = loudScope.current !== scope;
     loudScope.current = scope;
 
+    readThroughRef.current = false;
+
     async function load() {
+      const seq = ++windowSeq.current;
+      // A workspace that cannot be read at first paint is not "a table with no saved
+      // views" — it is a table whose schema we do not have, and the grid used to fill
+      // that hole from a localStorage bucket shared with every other surface.
+      //
+      // ⚠ STARTED BEFORE THE READ-THROUGH QUESTION IS ASKED, deliberately. The roster below is
+      // memoised per session but its FIRST call is a real round trip, and awaiting it before
+      // this line would serialise the workspace behind it on the first grid a person opens.
+      // Only the ROWS request has to wait, because only it needs the answer.
+      const wsPromise = includeWorkspace
+        ? fetchWorkspace(scope, { announceFailure: firstPaint })
+        : Promise.resolve(null);
+      /**
+       * ⭐⭐ W30-T42 (R7 / contract C2) — WHOLE BOOK, OR ONE WINDOW?
+       *
+       * ⛔ THE SERVER DECIDES, NOT A LIST HERE. `odoo-tables/status` reports `readThrough` per
+       * table because the bindings convert one bucket at a time; a key list in the client goes
+       * stale on the next spec row and fails in the dangerous direction (asking the window
+       * route for a table it cannot serve, which answers 409).
+       *
+       * ⛔ AND IT FAILS SOFT TO TODAY'S BEHAVIOUR. An unreachable roster yields the empty set,
+       * so the table loads whole exactly as it always has. The opposite default — assume
+       * windowed, discover otherwise — would paint an empty grid over a working table.
+       */
+      const tableKey = scope.startsWith("ut_") ? scope : null;
+      const readThrough = tableKey !== null && (await readThroughTables()).has(tableKey);
+      if (cancelled || seq !== windowSeq.current) return;
+      readThroughRef.current = readThrough;
       const [payload, workspace] = await Promise.all([
-        fetchTopicRows(topic),
-        // A workspace that cannot be read at first paint is not "a table with no saved
-        // views" — it is a table whose schema we do not have, and the grid used to fill
-        // that hole from a localStorage bucket shared with every other surface.
-        includeWorkspace
-          ? fetchWorkspace(scope, { announceFailure: firstPaint })
-          : Promise.resolve(null),
+        readThrough && tableKey !== null
+          // The FIRST window carries no predicate: `config` is CustomerGrid's own state, seeded
+          // from the workspace that is still in flight beside this call, so it does not exist
+          // yet. The grid re-asks with the saved view's predicate the moment it does — see
+          // `windowPredicateKey` and the effect that consumes it.
+          ? fetchTableWindow(tableKey, { offset: 0, limit: WINDOW_ROWS })
+          : fetchTopicRows(topic),
+        wsPromise,
       ]);
-      if (cancelled || !payload) return;
+      if (cancelled || seq !== windowSeq.current || !payload) return;
       setData(workspace ? withWorkspace(payload, workspace) : payload);
     }
 
@@ -499,6 +570,35 @@ export function useCustomerData(
     });
   }, [topic, writable]);
 
+  /**
+   * ⭐⭐ WAVE 30 · W30-T42 — THE ONE DOOR THE GRID USES TO PAGE A READ-THROUGH TABLE.
+   *
+   * Two callers, one function: a PREDICATE change (offset 0, replace) and a SCROLL (offset >
+   * 0, append). Keeping them on one door is what makes the two impossible to get out of step —
+   * `mergeWindow` reads the offset and decides, so there is no second place where "does this
+   * response replace or extend what I hold" is answered.
+   *
+   * ⛔ A no-op on a whole-book table, and silently so. `serverWindowed` (from `payload.counts`)
+   * is the client's ONE answer to "is this table windowed"; a second test that could disagree
+   * with it is how the grid ends up requesting pages of a table it already holds entirely.
+   */
+  const requestWindow = useCallback((req: RowWindowRequest) => {
+    if (!readThroughRef.current || STREAMLIT_COMPONENT || EMBEDDED_HTML) return;
+    const offset = Math.max(0, Math.floor(req.offset || 0));
+    // ⛔ ONE REQUEST PER PAGE IN FLIGHT. glide fires its visible-region callback on every frame
+    // of a scroll; without this the same offset is asked for on each one. Offset 0 is exempt on
+    // purpose — that is a PREDICATE change, and the newest predicate must always be able to
+    // overtake an older one rather than be suppressed by it.
+    if (offset > 0 && inflightOffset.current === offset) return;
+    const seq = ++windowSeq.current;
+    if (offset > 0) inflightOffset.current = offset;
+    void fetchTableWindow(scope, { ...req, offset }).then((next) => {
+      if (offset > 0 && inflightOffset.current === offset) inflightOffset.current = null;
+      if (seq !== windowSeq.current || !next) return;
+      setData((prev) => mergeWindow(prev, next, offset));
+    });
+  }, [scope]);
+
   return {
     fields: data?.fields ?? [],
     rawRows: data?.rows ?? [],
@@ -507,5 +607,6 @@ export function useCustomerData(
     overlayEdits,
     setOverlayEdits,
     patchOverlay,
+    requestWindow,
   };
 }

web/src/customer-grid/useGridColumns.ts

@@ -140,8 +140,35 @@ export function columnTones(
   return out;
 }
 
+/**
+ * ⭐ WAVE 30 (owner item 2 scouting) — THE OVERLAY ARM IS GONE, and the arithmetic is the reason.
+ *
+ * This read `field.default !== false || field.source === "overlay"`. The second arm was written
+ * when `overlay` meant "a column a user added here", and those columns have no `default` key at
+ * all — so the arm was a belt-and-braces no-op for them. Then `user_tables._clean_field` started
+ * stamping `source: "overlay"` on EVERY `ut_*` field, and every connected database became a `ut_*`
+ * one: the exception quietly became the rule and swallowed the first arm entirely.
+ *
+ * ⛔ WHAT THAT COST, measured on the live orders grid: `odoo_relational.order_fields` declares
+ * `default: False` on `odoo_id`, `state`, `customer_link` and `partner_id`, and every one of them
+ * opened SHOWN. The grid arrives wide, and "Hide fields" reads inactive because
+ * `shownCount === fields.length` — so the control that says "some columns are hidden" says the
+ * opposite of what its own table declares. A second instance of [[fallback-that-became-the-rule]].
+ *
+ * ⚠ DROPPING THE ARM DOES NOT HIDE USER COLUMNS, and this is the check that matters before
+ * believing the fix. A column somebody created carries no `default` key, `undefined !== false` is
+ * true, and it stays visible. `_clean_field` also keeps `default` ONLY when it is `True`, so a
+ * `ut_*` column can never arrive carrying `default: false` by accident — only a shipped field
+ * CONTRACT (which is written straight into the store, bypassing that validator) can declare it.
+ *
+ * ⚠ THIS PREDICATE HAS A SERVER TWIN and the twin is the one that decides on first open:
+ * `platform/aios_grid.py:_default_view_config` carries the same expression and builds the "All
+ * records" system view the client pins as its landing default. Fixing one side alone changes
+ * nothing a user sees — see `mailbox/F.md` F-1 ([[one-question-two-normalizers]] across two
+ * languages).
+ */
 function isDefaultVisible(field: Field): boolean {
-  return field.default !== false || field.source === "overlay";
+  return field.default !== false;
 }
 
 export function defaultViewConfig(fields: Field[]): ViewConfig {

web/src/filter-kit/FieldsHidePanel.tsx

@@ -15,7 +15,17 @@
 
 import { useState } from "react";
 import type { Field } from "../customer-grid/types";
-import { isPresetField } from "../customer-grid/types";
+// ⭐ WAVE 30 item 2 (R5) — `fieldLabel` is the ONE resolver for a field's NAME, and every read
+// of `f.label` in this file goes through it. `Field.label` is declared `string` and arrives
+// over the WIRE, where nothing enforces that; the search filter below did
+// `f.label.toLowerCase()` unguarded, so one label-less definition threw the moment a query
+// was typed — and before this wave a throw anywhere unmounted the whole React tree.
+// ⚠ ALL SIX SITES, not just the filter. A guard on the filter alone leaves the visible row
+// and its four aria strings reading `undefined` — [[one-question-two-normalizers]] in
+// miniature, where what a user searches and what they read answer the same question
+// differently. It lives in `types.ts` so the node harness can run it: this panel is JSX and
+// its search path only fires once somebody types, which no static render can do.
+import { fieldLabel, isPresetField } from "../customer-grid/types";
 import { FieldTypeIcon } from "../customer-grid/icons";
 import { TYPE_LABELS } from "../customer-grid/iconShapes";
 
@@ -74,7 +84,7 @@ export function FieldsHidePanel({
   const [dragKey, setDragKey] = useState<string | null>(null);
   const [overKey, setOverKey] = useState<string | null>(null);
   const q = query.trim().toLowerCase();
-  const shown = q ? fields.filter((f) => f.label.toLowerCase().includes(q)) : fields;
+  const shown = q ? fields.filter((f) => fieldLabel(f).toLowerCase().includes(q)) : fields;
   /**
    * Item 23 — reorder is OFF while a search is narrowing the list. Dropping "City" above
    * "State" in a list that is hiding the eight fields between them means nothing the user can
@@ -188,10 +198,10 @@ export function FieldsHidePanel({
                 draggable={canReorder && !locked}
                 aria-label={
                   locked
-                    ? `${f.label} is always first`
+                    ? `${fieldLabel(f)} is always first`
                     : canReorder
-                      ? `Reorder ${f.label} — drag, or use the arrow keys`
-                      : `Reorder ${f.label} (clear the search first)`
+                      ? `Reorder ${fieldLabel(f)} — drag, or use the arrow keys`
+                      : `Reorder ${fieldLabel(f)} (clear the search first)`
                 }
                 title={
                   canReorder && !locked
@@ -241,7 +251,7 @@ export function FieldsHidePanel({
                   draws (icons.tsx). Titled, because this list is where the icon
                   vocabulary is learned. */}
               <FieldTypeIcon type={f.type} title={TYPE_LABELS[f.type]} />
-              <span className="cg-check-label">{f.label}</span>
+              <span className="cg-check-label">{fieldLabel(f)}</span>
               {/* ⭐ OWNER ITEM 3 (2026-08-06): *"it doesn't show pre-set when I hide fields just
                   like how Odoo fields are. This is always the standard label."* Right — the chip
                   asked `source === "odoo"`, so a column an AUTOMATION fills (source `overlay`)
@@ -262,7 +272,7 @@ export function FieldsHidePanel({
                   type="button"
                   className={"cg-check-del" + (armed ? " is-armed" : "")}
                   aria-label={
-                    armed ? `Permanently delete ${f.label}?` : `Delete ${f.label}`
+                    armed ? `Permanently delete ${fieldLabel(f)}?` : `Delete ${fieldLabel(f)}`
                   }
                   title={armed ? undefined : "Removes this field and its values on every row."}
                   onClick={(e) => {

web/src/index.css

@@ -8778,6 +8778,39 @@ a.cg-map-ctl-b { text-decoration: none; }
   background: var(--lp-surface-2);
   color: var(--lp-muted);
 }
+/* ⭐⭐ WAVE 30 · ITEM 7 / R4 — THE TILE A REAL LOGO SITS IN.
+   ⛔ IT IS NOT A STYLE PREFERENCE, IT IS A CORRECTNESS FIX. The base tile paints
+   `--lp-blue-tint` and sets `color: var(--lp-blue-deep)`, and both break a brand mark in a
+   different way: Instagram's gradient would sit on a coloured chip that is not its colour, and
+   TikTok's note — drawn in `currentColor` ON PURPOSE, so the mark survives dark mode — would
+   render BLUE. Neutral ground and inherited text put both back where the brand put them.
+   ⚠ SPECIFICITY, STATED: this is (0,2,0), so the two `.autox-card.is-X .autox-card-mark` rules
+   above (0,3,0) still win inside a group or machine card. That is correct today because neither
+   of those card kinds is ever branded — and if one becomes so, this comment is where to look.
+   ⛔⛔ `color: inherit` IS THE RULE, AND IT IS NOT A TIDY-UP — DO NOT REPLACE IT WITH A TOKEN.
+   This shipped as `var(--lp-text)`, a token that is DEFINED NOWHERE (the ink token is `--lp-ink`).
+   It worked by accident and `web_icons` refused it: an unresolvable `var()` is invalid at
+   computed-value time, so `color` — an inherited property — fell back to `unset`, which for an
+   inherited property IS `inherit`. So this line is a byte-identical statement of what the four
+   brand tiles were already doing, and the paragraph above is where the intent was written down.
+   ⛔ Pinning a real ink here (`--lp-ink`) would be the one change that BREAKS them: two of the
+   nine marks are drawn in `currentColor` on purpose so they survive a dark ground, and an ink
+   would nail them to one. And minting a `--lp-text` token would mint a second name for
+   `--lp-ink`, which the 23-token parity leg (`index.css` vs `theme.ts`) would carry forever. */
+.autox-card-mark.is-brand {
+  background: transparent;
+  color: inherit;
+}
+/* The connector heading's own small slot: a nest caption is 4xs text, so it takes a 13px mark
+   rather than the 26px row tile — the tile beside a caption reads as a row that lost its label. */
+.autox-sub-mark {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  vertical-align: -2px;
+  margin-right: 5px;
+  color: inherit; /* see `.autox-card-mark.is-brand` above — inherited on purpose, never a token */
+}
 .autox-card-text { min-width: 0; display: flex; flex-direction: column; gap: 1px; }
 .autox-card-title {
   overflow: hidden;
@@ -11152,6 +11185,64 @@ a.cg-map-ctl-b { text-decoration: none; }
   font-weight: 600;
   letter-spacing: 0.02em;
 }
+/* ⭐⭐ WAVE 30 · R4 — THE LOGO TILE. It carries its own box because it does NOT wear
+   `.shell-db-chip`: that class paints `--lp-primary` and white text, which is exactly right for
+   two LETTERS (12px type needs 4.5:1 and only the base chip clears it) and exactly wrong under a
+   brand mark, which brings its own colour. Same 26px square in the same radius, so the grid does
+   not shift between a card with a logo and a card with letters. */
+.conn-tile.is-brand {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: 0 0 auto;
+  width: 26px;
+  height: 26px;
+  border-radius: var(--lp-r-md);
+  background: transparent;
+  color: inherit; /* see `.autox-card-mark.is-brand` — inherited on purpose, never a token */
+}
+/* The platform drill (R4): collapsed by default, so a card costs one line until somebody asks. */
+.conn-plats { margin: 6px 0 0; }
+.conn-plats-sum {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  cursor: pointer;
+  list-style: none;
+  font-size: var(--lp-fs-3xs);
+  color: var(--lp-muted);
+}
+.conn-plats-sum::-webkit-details-marker { display: none; }
+/* The chevron, drawn the way the automation menu's nest draws it, so the two disclosures in this
+   product are one gesture rather than two that happen to both open. */
+.conn-plats-sum::before {
+  content: "";
+  flex: 0 0 auto;
+  width: 7px;
+  height: 7px;
+  border-right: 1.4px solid var(--lp-muted);
+  border-bottom: 1.4px solid var(--lp-muted);
+  transform: rotate(-45deg);
+  transition: transform 0.12s ease;
+}
+.conn-plats[open] > .conn-plats-sum::before { transform: rotate(45deg); }
+.conn-plat {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  padding: 6px 0 0 14px;
+}
+.conn-plat-mark {
+  flex: 0 0 auto;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin-top: 1px;
+  color: inherit; /* see `.autox-card-mark.is-brand` — inherited on purpose, never a token */
+}
+.conn-plat-text { min-width: 0; display: flex; flex-direction: column; gap: 1px; }
+.conn-plat-name { font-size: var(--lp-fs-3xs); font-weight: 600; color: var(--lp-ink); }
+.conn-plat-desc { font-size: var(--lp-fs-4xs); color: var(--lp-muted); }
 .conn-card-name {
   flex: 1 1 auto;
   min-width: 0;

web/src/shell/ErrorBoundary.tsx

@@ -0,0 +1,136 @@
+// ---------------------------------------------------------------------------
+// shell / ErrorBoundary.tsx — WAVE 30, owner item 2 (ruling R5).
+//
+// ⛔ WHY THIS FILE EXISTS, AND THE MEASUREMENT BEHIND IT. Until today,
+// `ErrorBoundary|componentDidCatch|getDerivedStateFromError` had ZERO hits in the
+// whole of `web/src`. React's contract when a render throws and nothing catches it
+// is to unmount the ENTIRE tree — so one unguarded property access anywhere in the
+// product produced a blank white page. That is exactly what a user calls "it
+// crashes", and it is why owner item 2 arrived as a report with no diagnosis: there
+// was nothing left on screen to diagnose.
+//
+// A boundary is therefore not a workaround for the hide-fields panel. It is the
+// difference between "one surface failed and said so" and "the product vanished".
+//
+// ⚠ WHAT NO GATE IN THIS REPO CAN PROVE, measured 2026-08-12 rather than assumed —
+// written here so nobody reads the gate as stronger than it is:
+//   · there is NO DOM. `jsdom`, `happy-dom`, `linkedom`, `domino` and
+//     `react-test-renderer` are all absent from `web/node_modules` (160 packages),
+//     and there is no vitest. So the React RECONCILER cannot be run under node.
+//   · React 18.3.1's server renderers do NOT invoke error boundaries. Both
+//     `renderToString` and `renderToStaticMarkup` were fed one throwing child under
+//     a boundary declaring `getDerivedStateFromError`; both PROPAGATED the throw and
+//     `componentDidCatch` never fired.
+// ⇒ the fallback is a SEPARATE exported component precisely so it can be rendered
+//   for real, and the class's protocol is driven by hand in `verify_grid_ux.py`
+//   (throw → catch → `getDerivedStateFromError` → `render()`), which is React's own
+//   documented sequence. The reconciler's guarantee is React's, not ours; what IS
+//   ours — that every surface is actually wrapped — is a source scan, and that is
+//   the check with teeth ([[reachable-is-not-the-same-as-built]]: a boundary that
+//   exists and wraps nothing is this repo's sixth whole-correct-unreachable feature).
+// ---------------------------------------------------------------------------
+
+import { Component } from "react";
+import type { ErrorInfo, ReactNode } from "react";
+import "./errorBoundary.css";
+
+export interface FailurePanelProps {
+  /** The surface that failed, named the way the user got to it ("Odoo orders",
+   *  "Automation", "Loopable"). A panel that will not say WHAT broke sends the
+   *  reader back to us with the same sentence item 2 arrived with. */
+  surface: string;
+  /** The thrown message. Shown, not hidden: a user who can paste one line saves a
+   *  scouting session. ⚠ It is the message ONLY — never a stack, and never a value
+   *  from a row, because this panel is on screen wherever the failure happened. */
+  message?: string;
+  onReload: () => void;
+}
+
+/**
+ * The contained failure card.
+ *
+ * It borrows `.shell-placeholder` and `.shell-retry` on purpose — the shell already
+ * has two failure panels (the data-error card and the nav-failed card) and a third
+ * visual language for the same idea would read as a different kind of problem. The
+ * only new paint is the tone strip in `errorBoundary.css`, which is what separates
+ * "this did not load" from "this broke".
+ *
+ * Exported as its own component so it can be rendered for real under node; see the
+ * measurement in this file's header for why the class cannot be.
+ */
+export function FailurePanel({ surface, message, onReload }: FailurePanelProps) {
+  return (
+    <div className="shell-placeholder shell-crash" role="alert">
+      <h1>{surface} could not be shown</h1>
+      <p>
+        Something here failed while drawing. The rest of the app still works — pick
+        another database from the sidebar, or reload to try this one again.
+      </p>
+      {message ? <p className="shell-crash-detail">{message}</p> : null}
+      <button
+        className="login-submit shell-retry"
+        type="button"
+        onClick={onReload}
+      >
+        Reload
+      </button>
+    </div>
+  );
+}
+
+export interface ErrorBoundaryProps {
+  surface: string;
+  children: ReactNode;
+}
+
+export interface ErrorBoundaryState {
+  error: Error | null;
+}
+
+/**
+ * Catch a render throw and paint `FailurePanel` in its place, leaving every sibling
+ * mounted.
+ *
+ * ⚠ A BOUNDARY LATCHES, AND THAT IS THE TRAP TO KNOW ABOUT. Once it holds an error
+ * it renders the panel until it is REMOUNTED — there is no "it will sort itself out
+ * on the next render". So every mount below passes a `key` that changes when the
+ * user moves (the route, the surface), which turns "navigate away and back" into the
+ * recovery path a person will actually try. `Reload` is the second door, and it is
+ * the same control the shell's two existing failure cards offer.
+ */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error: unknown): ErrorBoundaryState {
+    // Anything can be thrown in JavaScript, including a string or `undefined`.
+    // Normalising here means `render` has one shape to reason about and the panel
+    // can never itself throw reading `.message` off a non-Error.
+    return { error: error instanceof Error ? error : new Error(String(error)) };
+  }
+
+  componentDidCatch(error: unknown, info: ErrorInfo): void {
+    // The console is the only sink this client has today. It is enough to turn the
+    // next report from "it crashes" into a stack — which was the whole cost of item
+    // 2 arriving undiagnosed. Forwarding this to the server is booked as pending
+    // work rather than smuggled in here: it needs a route, and it must be proven to
+    // carry no row values before it ships.
+    console.error(`[${this.props.surface}] render failed`, error, info.componentStack);
+  }
+
+  render(): ReactNode {
+    const { error } = this.state;
+    if (error) {
+      return (
+        <FailurePanel
+          surface={this.props.surface}
+          message={error.message}
+          onReload={() => window.location.reload()}
+        />
+      );
+    }
+    return this.props.children;
+  }
+}

web/src/shell/Shell.tsx

@@ -64,6 +64,7 @@ const SettingsModal = lazy(() =>
   import("../settings/SettingsModal").then((m) => ({ default: m.SettingsModal })));
 import type { SettingsSection } from "../settings/SettingsModal";
 import { Brand } from "./Brand";
+import { ErrorBoundary } from "./ErrorBoundary";
 import LoginPage from "./LoginPage";
 import { CONNECTORS_ROUTE, EMPTY_NAV_PREFS, ENVELOPE_KEYS, HOME_ROUTE, MAX_NAV_FOLDERS, appLink, databaseEntries, dbChipClass, defaultRoute, deleteTable, fetchNav, fetchNavPrefs, fetchTableFootprint, foldNav, postOpened, resolveRoute, saveNavMeta, saveNavPrefs, shapeNav, splitChrome } from "./nav";
 import type { NavEntry, NavMetaPatch, NavPage, NavPrefs, Recent } from "./nav";
@@ -95,9 +96,20 @@ const AlertsPane = lazy(() => import("../alerts/AlertsPane"));
  * These chunks are tens of kilobytes off the same origin that just served the shell, so the
  * honest choice between a flash of a spinner and a frame of nothing is nothing — a spinner that
  * appears and vanishes within one frame reads as a glitch, not as progress.
+ *
+ * ⭐ WAVE 30 (R5) — AND AN ERROR BOUNDARY, INSIDE THE HELPER RATHER THAN AT SIX CALL SITES.
+ * Three of these six (`TemplatePicker`, `SettingsModal`, `AlertsPane`) are siblings of `<main>`,
+ * so the content-area boundary below cannot cover them; putting it here covers all six with one
+ * edit. It also catches what `Suspense` alone cannot: a REJECTED chunk fetch. `lazy()` throws its
+ * rejection at render, which before today unmounted the whole product because one deploy-time
+ * cache miss made a modal's JavaScript unreachable.
  */
-function Lazily({ children }: { children: ReactNode }) {
-  return <Suspense fallback={null}>{children}</Suspense>;
+function Lazily({ children, surface }: { children: ReactNode; surface: string }) {
+  return (
+    <ErrorBoundary surface={surface}>
+      <Suspense fallback={null}>{children}</Suspense>
+    </ErrorBoundary>
+  );
 }
 
 import { createAlert, fetchInbox } from "../alerts/alertsApi";
@@ -578,7 +590,26 @@ function AccountMenu({
   );
 }
 
+/**
+ * ⭐ WAVE 30 (R5) — THE OUTERMOST BOUNDARY, and the ONLY one that can cover the three
+ * EARLY RETURNS below (`FormPublic`, the boot card, `LoginPage`) plus this component's own
+ * body: its route resolution, its nav shaping and its derivations all run BEFORE any JSX
+ * exists to wrap. A throw in any of them used to take the document with it, and a person
+ * who cannot get past the login screen has no navigation left to escape with.
+ *
+ * ⚠ Split rather than nested inline for one reason: a boundary cannot catch a throw from
+ * its OWN render. `ErrorBoundary` has to be the parent of the component that fails, so the
+ * frame becomes a child and the default export becomes the wrapper.
+ */
 export default function Shell() {
+  return (
+    <ErrorBoundary surface="Loopable">
+      <ShellFrame />
+    </ErrorBoundary>
+  );
+}
+
+function ShellFrame() {
   const [session, setSession] = useState<Session>({ phase: "checking" });
   const [nav, setNav] = useState<Nav>({ phase: "idle" });
   // Wave 18 (C3-UT): bumped after "+ New database" so the rail refetches and the new ut_ key
@@ -2047,6 +2078,14 @@ export default function Shell() {
       ) : null}
 
       <main className="shell-main">
+        {/* ⭐ WAVE 30 (R5) — THE CONTENT-AREA BOUNDARY, and the reason it is HERE and not around
+            the whole shell: the `<aside>` rail is its SIBLING, so a surface that throws leaves the
+            navigation mounted and the user can walk away from the broken page instead of reloading
+            a blank document. That is the difference the ticket's done-when is naming.
+            ⚠ `key={route}` is load-bearing. A boundary LATCHES — once it holds an error it renders
+            the panel until it is remounted — so without the key, navigating away from a failing
+            database would carry its failure card onto every page afterwards. */}
+        <ErrorBoundary key={route} surface={active?.label ?? "This page"}>
         {/* ⚠ An honest failure, never a fallback to the bundled sample. Behind
             a login, plausible-looking sample revenue is fabricated data on a
             screen the user has every reason to trust. */}
@@ -2096,7 +2135,7 @@ export default function Shell() {
               {...(active.icon ? { icon: active.icon } : {})}
             />
             <div className="shell-auto-host">
-              <Lazily><AutomationSurface /></Lazily>
+              <Lazily surface="Automation"><AutomationSurface /></Lazily>
             </div>
           </div>
         ) : active?.kind === "native" ? (
@@ -2139,7 +2178,7 @@ export default function Shell() {
           // The one action the page cannot perform itself: a `manage: "keychain"` row opens
           // Settings on the Keychains tab, and the Settings MODAL is the frame's. Same division
           // as every other panel here — the page knows what it wants, the frame owns the door.
-          <Lazily><ConnectorsPage onKeychain={() => setSettings("keychains")} /></Lazily>
+          <Lazily surface="Connectors"><ConnectorsPage onKeychain={() => setSettings("keychains")} /></Lazily>
         ) : nav.phase === "ready" ? (
           // ⭐ WAVE 23 item 9 (R7, C10) — HOME, AND IT IS THE FALLBACK RATHER THAN A ROUTE MATCH.
           //
@@ -2159,7 +2198,7 @@ export default function Shell() {
           // hero's create door, and its empty line carries the hero's sentence (HomePage's
           // `home-empty`, which branches on `entries.length === 0` for exactly this reason).
           // Booked as a dated amendment in the wave doc, since it moves an R4 surface.
-          <Lazily>
+          <Lazily surface="Home">
             <HomePage
               // ⭐ `dbEntries`, NOT `entries` — found by LOOKING at it (wave 24 close-out visual
               // pass), which is the only way it could have been found. The Automation SURFACE is a
@@ -2208,6 +2247,7 @@ export default function Shell() {
             <span className="lp-spin lp-spin--lg" role="status" aria-label="Loading" />
           </div>
         )}
+        </ErrorBoundary>
       </main>
 
       {/* The server's own confirmation of a write (X2's `toast`). In standalone
@@ -2306,7 +2346,7 @@ export default function Shell() {
               // WAVE 23 C12 (wiring W23-W6) — the picker. It applies views to an EXISTING
               // database rather than making one, which is what a platform-curated template is:
               // a set of saved views, not a table (R10).
-              <Lazily>
+              <Lazily surface="Templates">
                 <TemplatePicker
                   entries={dbEntries}
                   onToast={setToast}
@@ -2356,7 +2396,7 @@ export default function Shell() {
       ) : null}
 
       {settings ? (
-        <Lazily>
+        <Lazily surface="Settings">
           <SettingsModal
             user={session.user}
             section={settings}
@@ -2375,7 +2415,7 @@ export default function Shell() {
 
       {/* C-ALERT (item 25): the inbox. */}
       {alertsOpen ? (
-        <Lazily>
+        <Lazily surface="Alerts">
           <AlertsPane
             onClose={() => setAlertsOpen(false)}
             onInbox={setInbox}

web/src/shell/errorBoundary.css

@@ -0,0 +1,32 @@
+/* shell/errorBoundary.css — WAVE 30 item 2 (R5): the contained-failure card.
+   New classes only, co-located with the component that imports them, following
+   `shell/navExtras.css`'s precedent — the shell's own rail and placeholder classes
+   stay in index.css untouched (that file is another session's fence this wave).
+
+   ⚠ Font sizes are tokens, never literals: `verify_ui.py`'s R5 sweep reads EVERY
+   stylesheet under `src/`, not just index.css. */
+
+/* The tone strip is the whole point of this rule. `.shell-placeholder` already
+   centres a heading, a sentence and a retry button — that is what the nav-failed
+   and data-error cards look like, and both of those mean "it did not load". This
+   one means "it broke", and a reader who cannot tell those apart reports the wrong
+   thing. The strip takes the `-deep` weight because it reads as a stroke
+   (DESIGN.md: strokes and text take `-deep`, flat surfaces take the pastel base). */
+.shell-crash {
+  border-left: 3px solid var(--lp-red-deep);
+  background: var(--lp-red-tint);
+  border-radius: var(--lp-r-lg);
+  /* Contained, so a long message cannot push the sidebar off-screen — the failure
+     panel must never be the second way this surface breaks the app. */
+  max-width: 640px;
+  margin: 24px;
+}
+
+/* The thrown message, verbatim. Monospace because it is a machine's words, not
+   ours, and a reader pasting it back to us should be able to see where it ends. */
+.shell-crash-detail {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: var(--lp-fs-2xs);
+  color: var(--lp-red-deep);
+  overflow-wrap: anywhere;
+}